Module usage 

OAuth /api/oauth/usage response + internal usage-data types.

Two shapes live here:

• UsageApiResponse mirrors the endpoint’s wire JSON per ADR-0011 §Endpoint contract. Recognized buckets sit in named Option fields; codenamed/unreleased buckets land in unknown_buckets via #[serde(flatten)] so forward-compat is lossless.
• UsageData is the enum segments consume after the fallback cascade lands. Per ADR-0013, the variant IS the provenance tag: Endpoint(EndpointUsage) carries authoritative endpoint data; Jsonl(JsonlUsage) carries raw token counts aggregated from transcripts so segments can render ~5h: 420k instead of synthesizing a percentage against a tier ceiling we don’t know.

The endpoint client converts wire → internal via UsageApiResponse::into_endpoint_usage; the JSONL-mode cascade constructs a JsonlUsage directly from the aggregator output in cascade.rs.

Structs

EndpointUsage

Data from a successful OAuth /api/oauth/usage response (possibly served from cache). unknown_buckets carries codenamed buckets forward so plugins can inspect them; core segments don’t read it.

ExtraUsage

Overage-credit tracking for accounts with extra-usage enabled. is_enabled is the load-bearing flag: when false, every other field is typically null in the live endpoint.

FiveHourWindow

Active-block window surfaced to segments under JSONL fallback.

JsonlUsage

Data derived from the JSONL transcript aggregator. seven_day is always populated (zero-valued on an empty transcript); five_hour is None when the current 5h block has no recent activity, per docs/specs/jsonl-aggregation.md. Fields are pub(crate) so the aggregator+cascade own the construction invariants; segments in this crate read them directly.

SevenDayWindow

Rolling 7-day window under JSONL fallback. No resets_at: this is a rolling window, not a hard-reset bucket, so the rate_limit_7d_reset segment hides entirely under JSONL per docs/specs/rate-limit-segments.md §JSONL-fallback display.

UsageApiResponse

Shape of the OAuth /api/oauth/usage endpoint response. Every recognized bucket is Option because the endpoint omits (or emits null for) buckets that don’t apply to the account’s tier, and unknown_buckets captures codenamed / unreleased buckets Anthropic may add without notice (omelette_*, iguana_*, cowork, etc. observed live 2026-04-18). See docs/research/claude-data-files.md §Raw data for the reference capture.

UsageBucket

Utilization plus reset-time for a single rolling window.

Enums

UsageData

What DataContext::usage surfaces after the cascade in docs/specs/data-fetching.md §OAuth fallback cascade finishes. The variant IS the provenance tag per ADR-0013: segments dispatch on it to pick between percent rendering (endpoint) and raw-token rendering (JSONL). #[non_exhaustive] leaves room for a future third source without a SemVer break.

Constants

KNOWN_BUCKETS

Names of every recognized top-level field on UsageApiResponse. Exported so linesmith doctor can check “did the endpoint return any forward-compat keys?” without duplicating the field list — the [KNOWN_BUCKETS_PARITY] test below pins this against UsageApiResponse so the two can’t drift.

RESEARCH_DOCUMENTED_BUCKETS

Codenamed forward-compat buckets observed in the live endpoint during research captures (see docs/research/claude-data-files.md §Raw data, 2026-04-18 capture). These are unrecognized by UsageApiResponse’s strict struct fields but Anthropic ships them on every response — gating the doctor’s “endpoint.shape_current” WARN on this list keeps the report quiet on healthy accounts while preserving the WARN for new unknown keys (the actual signal a maintainer wants).