Module usage 

Read-only, normalized quota/usage snapshots for the four OAuth providers the multi-account broker manages: Claude (Anthropic), ChatGPT/Codex, Kimi Code and Grok (xAI).

Design rules (goal plan G3):

• Read-only. Every adapter is a single pinned GET. Nothing here can redeem a banked reset, purchase credits, or generate inference.
• Caller supplies the resolved token. fetch_usage takes the provider and the already-resolved access token for exactly that (provider, account) so the credential broker invokes it behind its boundary. This module never reads auth.json, never refreshes, never sees a refresh token.
• Pinned destinations. URLs are constants. The only override is a loopback-only test seam (UsageFetchOptions::endpoint_override) that is rejected for any non-loopback host, so a bearer token can never be coaxed toward an attacker-chosen destination.
• No redirects, bounded time and body. UsageClient is built with a redirect::Policy::none(); 3xx is an error. Bodies are streamed into a capped buffer.
• Sanitized errors. UsageError never contains the token, the URL query, or a byte of an upstream body. Parse notes use fixed vocabulary — never raw upstream key names or values.
• Unknown is not capacity. used_percent is a tagged enum (UsedPercent); missing, null, non-numeric and out-of-range values are explicitly Unknown { reason }. Reset timestamps are provider-authoritative (RFC 3339 or unix seconds → epoch ms) or None — never inferred from now + window.
• Dynamic windows. Codex primary_window can be weekly and secondary_window can be null; durations come from limit_window_seconds, never from a hard-coded “primary = 5h”.

Schema provenance (no network was used):

• Codex field set verified against the string table of the locally installed official codex binary (RateLimitWindowSnapshot, RateLimitStatusPayload, RateLimitResetCreditsSummary/Details, /wham/usage, /wham/rate-limit-reset-credits).
• Kimi field set verified against the official kimi CLI bundle (managed-usage.ts: usage, limits[].window/detail, boosterWallet).
• Anthropic matches the previously shipped synaps status reader.
• Grok /v1/billing?format=credits follows the QuotaKit-documented shape (config.creditUsagePercent, onDemandUsed.val / onDemandCap.val, config.currentPeriod.end / config.billingPeriodEnd, billingPeriodMinutes). Unverified against a live account; anything else yields an explicitly unknown window.

Structs

AccountUsageEntry

BankedResetCredit

BankedResets

Codex banked weekly-reset inventory (read-only view).

CreditBalance

Billing/credit balance. This is money-like inventory, not quota.

ModelAvailability

Per-model availability. Sources, in precedence order:

UsageClient

HTTP client with the policy this module requires: no redirects, bounded connect/total timeouts, built-in roots. Construct once and reuse.

UsageErrorSummary

Secret-free error row.

UsageFetchOptions

Options for fetch_usage. Production callers use Default.

UsageReport

synaps status --json / broker listing payload.

UsageSnapshot

Normalized, secret-free usage observation for one (provider, account).

UsageWindow

One quota window as reported by the provider.

Enums

AccountUsageOutcome

One account’s outcome inside a UsageReport: partial failures never discard the accounts that succeeded.

Availability

Three-state model availability derived from model-scoped windows.

ResetKind

What kind of clock a reset_at describes.

UsageError

Usage failures. Display/Serialize never include a token, a URL query, or any upstream body bytes.

UsedPercent

Fraction of a window consumed. Never a bare number: the parser must decide Valid (finite, 0.0..=100.0) or Unknown with a fixed-vocabulary reason.

WindowScope

What a window applies to.

Constants

ANTHROPIC_USAGE_URL

Anthropic OAuth usage summary (same endpoint the broker’s typed op uses).

CODEX_RESET_CREDITS_URL

ChatGPT/Codex banked-reset inventory (GET only — the sibling /consume endpoint redeems a reset and is deliberately NOT reachable from here).

CODEX_USAGE_URL

ChatGPT/Codex rate-limit usage (GET, bearer + chatgpt-account-id).

GROK_BILLING_URL

Grok Build billing (credits view).

KIMI_USAGE_URL

Kimi Code managed usage.

OVERRUN_PERCENT_MAX

Largest reported percentage still read as “window overrun” (exhausted) rather than garbage. Above 10x the value is more likely a unit error (basis points, a raw counter) than a real overrun, so it stays unknown; both fail closed. Shared with quota_policy::WindowLimit::verdict.

SCHEMA_VERSION

Snapshot JSON schema version (bump on incompatible field changes).

USAGE_CONNECT_TIMEOUT

TCP/TLS connect budget.

USAGE_MAX_BODY_BYTES

Hard cap on a buffered usage body. Real payloads are a few KiB.

USAGE_REQUEST_TIMEOUT

Total time budget for one usage request.

Functions

duration_label

18000 → 5h, 604800 → 7d, 90 → 90s.

fetch_usage

Read-only usage fetch for one (provider, account) using the caller’s already-resolved access token. See the module docs for the guarantees.

parse_anthropic_usage

Parse GET /api/oauth/usage. Every object value carrying utilization or resets_at is a window; null windows are skipped with a note.

parse_codex_reset_credits

Parse GET /wham/rate-limit-reset-credits (inventory detail).

parse_codex_usage

Parse GET /wham/usage. expected_account_id is the id derived from the bearer token; a differing response account_id fails closed.

parse_grok_billing

Parse GET /v1/billing?format=credits.

parse_kimi_usage

Parse GET /coding/v1/usages (official CLI parseManagedUsagePayload).

supported_usage_providers

Providers with a usage adapter, in display order.

supports_usage

Whether a usage adapter exists for the provider. Copilot and Gemini expose no quota endpoint we can read, so they are honestly unsupported.