# @smithers-orchestrator/usage — src

Every module here is public npm surface: the package exports both `.` and
`./*`, so file names are API — do not rename, move, or split them. The
package-level README (`packages/usage/README.md`) tells the product story and
carries the per-provider auth table; this file just maps the modules.

## Module map

- **Dispatchers** — `getAccountUsage.js` routes a provider to its adapter;
  `getUsageForAccounts.js` adds the on-disk cache (soft per-provider TTL plus a
  hard floor) around it for many accounts in parallel.
- **Network adapters** — `claudeOauthUsage.js`, `codexWhamUsage.js`,
  `anthropicHeaderUsage.js`, `openaiHeaderUsage.js`, `googleUsage.js`. Each
  returns a `UsageProbe` and never throws.
- **Pure parsers** — `parseClaudeOauthUsage.js`, `parseCodexUsage.js`,
  `parseAnthropicRateLimitHeaders.js`, `parseOpenAiRateLimitHeaders.js`,
  `parseDurationSeconds.js`.
- **Credential readers** — `readClaudeCredentials.js` (with a macOS Keychain
  fallback), `readCodexCredentials.js` plus `decodeJwtClaims.js`.
- **Presentation** — `formatUsageReports.js`, `formatRelativeReset.js`,
  `humanizeDurationShort.js`.
- **Persistence / data** — `usageCache.js`, `publishedCaps.js`.
- **Type sidecars** — `UsageReport.ts`, `UsageWindow.ts`, `UsageSource.ts`
  (type-only). `index.d.ts` is generated by `tsup --dts-only`; never hand-edit.

Key shape: `UsageProbe` (the adapter half-result) is a JSDoc typedef in
`buildUsageReport.js`; `buildUsageReport` wraps it with account identity and a
timestamp into a full `UsageReport`.

## Gotchas

- Adapters degrade to `source: "none"` with a readable `error` instead of
  throwing, so one bad account never breaks the table.
- The claude-code cache floor is a hard 180s even with `--fresh`: the OAuth
  usage endpoint 429s aggressively below that.
- Tokens read by the credential readers are only ever used to mint an outbound
  `Authorization` header — never logged, never included in reports.
