MT-22692: API tokens & billing

[Lorenc326]

Motivation

Adds API token management and billing usage to the Go SDK's General surface.

Changes

• APITokens (client.APITokens): List / Get / Create / Reset / Delete; the full token value is returned only by Create and Reset.
• Billing (client.Billing): Usage — current billing-cycle usage across Sandbox, Sending & Marketing.
• httptest tests + extends examples/general + README entries.

Field shapes and paths verified against the OpenAPI spec (account-management). Stacked on the accounts/access/permissions PR, whose AccessLevel* / ResourceType* constants the API-token permissions reuse.

How to test

• go test -race ./...
• go vet ./...
• golangci-lint run ./...

Summary by CodeRabbit

• New Features
  • Added API token management, including listing, retrieving, creating, resetting, and deleting tokens.
  • Added billing usage reporting for plans, billing cycles, and message counts.
  • Added example programs demonstrating API token and billing workflows.
• Documentation
  • Added API token management and billing examples to the supported functionality list.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Mailtrap client support for API token lifecycle operations and billing usage retrieval, including public models, client wiring, tests, runnable examples, and README links.

Changes

Management API services

Layer / File(s)	Summary
API token lifecycle api_tokens.go, api_tokens_test.go	Adds token models and list, get, create, reset, and delete operations with endpoint tests.
Billing usage service billing.go, billing_test.go	Adds billing usage models and a usage endpoint method with nested response assertions.
Client wiring and examples client.go, examples/api-tokens/main.go, examples/billing/main.go, README.md	Exposes both services on Client, adds usage examples, and links them from the README.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately captures the main change: adding API tokens and billing support.
Description check	✅ Passed	The description covers the required core sections with motivation, changes, and testing; the images section is omitted but non-critical.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/billing/main.go`:
- Around line 23-30: Both reporting conditions can panic by dereferencing a nil
Usage field. In the Sending and Testing checks, add usage.Sending.Usage != nil
and usage.Testing.Usage != nil before accessing SentMessagesCount, while
preserving the existing output behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 20ff4f85-a598-4de2-985e-f4ed1dbb2984

📥 Commits

Reviewing files that changed from the base of the PR and between 56491e6 and 60ad753.

📒 Files selected for processing (8)

• README.md
• api_tokens.go
• api_tokens_test.go
• billing.go
• billing_test.go
• client.go
• examples/api-tokens/main.go
• examples/billing/main.go

[coderabbitai]

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Missing nil check on Usage before accessing SentMessagesCount.

BillingProduct.Usage is a pointer (*BillingUsageMetrics) and can be nil if the API omits the usage key for a product. The condition checks usage.Sending != nil && usage.Sending.Usage.SentMessagesCount != nil but skips usage.Sending.Usage != nil — if Usage is nil, the access to SentMessagesCount panics. Same issue on lines 27-29 for Testing.

🛡️ Proposed fix: add intermediate nil checks

-	if usage.Sending != nil && usage.Sending.Usage.SentMessagesCount != nil {
+	if usage.Sending != nil && usage.Sending.Usage != nil && usage.Sending.Usage.SentMessagesCount != nil {
 		sent := usage.Sending.Usage.SentMessagesCount
 		fmt.Printf("email sending: %d/%d messages this cycle\n", sent.Current, sent.Limit)
 	}
-	if usage.Testing != nil && usage.Testing.Usage.SentMessagesCount != nil {
+	if usage.Testing != nil && usage.Testing.Usage != nil && usage.Testing.Usage.SentMessagesCount != nil {
 		sent := usage.Testing.Usage.SentMessagesCount
 		fmt.Printf("sandbox: %d/%d messages this cycle\n", sent.Current, sent.Limit)
 	}

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if usage.Sending != nil && usage.Sending.Usage.SentMessagesCount != nil {
	sent := usage.Sending.Usage.SentMessagesCount
	fmt.Printf("email sending: %d/%d messages this cycle\n", sent.Current, sent.Limit)
	}
	if usage.Testing != nil && usage.Testing.Usage.SentMessagesCount != nil {
	sent := usage.Testing.Usage.SentMessagesCount
	fmt.Printf("sandbox: %d/%d messages this cycle\n", sent.Current, sent.Limit)
	}
	if usage.Sending != nil && usage.Sending.Usage != nil && usage.Sending.Usage.SentMessagesCount != nil {
	sent := usage.Sending.Usage.SentMessagesCount
	fmt.Printf("email sending: %d/%d messages this cycle\n", sent.Current, sent.Limit)
	}
	if usage.Testing != nil && usage.Testing.Usage != nil && usage.Testing.Usage.SentMessagesCount != nil {
	sent := usage.Testing.Usage.SentMessagesCount
	fmt.Printf("sandbox: %d/%d messages this cycle\n", sent.Current, sent.Limit)
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/billing/main.go` around lines 23 - 30, Both reporting conditions can
panic by dereferencing a nil Usage field. In the Sending and Testing checks, add
usage.Sending.Usage != nil and usage.Testing.Usage != nil before accessing
SentMessagesCount, while preserving the existing output behavior.