@byokit/usage 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-10-01)
+
+
+
+- FIX: Subscription hard-limit flags now override positive percentage room, including blocks without quota windows; cached reset times never clear them.
+- FIX: Claude subscription normalized and scoped quota rows now take precedence over legacy aggregates; missing usage remains unknown.
+- Expose observation age and poll outcomes separately; retain last-good figures through failed polls without changing account health.
+- Add cancellable host origin pacing and account-scoped retry policies for rate limits, refresh failures and transient outcomes.
+- Document reset-time units when passing normalized subscription readings to account selection.
+
+## 0.2.0 (2026-09-30)
+
+
+
+- Export `fingerprint`, `fileUsageStore`, `memoryBackoffPolicy`, `retryAfterMs` and `backoffDelayMs` for host subscription usage adapters.
+- Add token quota sources for Claude, Codex, Copilot, Grok, MiniMax, Gemini and Kimi, with BYOKit's own user agent and no credential discovery.
+- Add `callLedger`, `normalizeTokens` and `priceCall` for attributed model calls, reported/partial/unknown counts and estimates from app price tables only, on the member ledger store seam.
+- Add a member-scoped token ledger with local-day totals, trailing seven-day caps and an injectable store (in-memory by default).
+- Add `roomOf`; reset timestamps now use epoch milliseconds.
+- Add host Claude reader, last-good store and 429 backoff hooks. Persist only normalized quota fields and fingerprint non-secret identities.
 - Read subscription usage windows per provider and per account, with last-good readings and bounded provider reads.
 
 ## 0.1.0

package/README.md

@@ -1,25 +1,271 @@
 # @byokit/usage
 
-Read subscription usage windows per provider and per account on Node 22.18 or later. Crewhouse can show each member's room, v1 design can meter a payer's plan, and fleet apps can compare account readings. The app chooses an account and supplies labels; this kit makes no choice and estimates no cost.
+Read subscription quota windows per provider and per account on Node 22.18 or later.
+The app owns sign-in, token renewal, account labels and selection. The kit reads room
+left, estimates no cost and never rotates an account.
 
 ```ts
-import { usage } from '@byokit/usage';
+import { usage, roomOf } from '@byokit/usage';
 const reader = usage({ stateDir: '/app/state/usage' });
-const source = { provider: 'codex' as const, bin: '/app/bin/codex', home: '/app/sign-ins/alice' };
+// Pass the token and account id from your app-owned sign-in store.
+declare const token: string;
+declare const account: { id: string };
+const source = { provider: 'codex' as const, access: token, accountId: account.id };
 const reading = await reader.read(source);
-for (const window of reading.windows) console.log(window.kind, 100 - window.usedPercent);
+const room = roomOf(reading, Date.now());
 ```
 
-The Node-only `.` entry exports `usage`, `UsageError`, types, `claudeWindows`, `codexWindows`, `goWindows`, `zaiWindows`, `words`, and `usageWords`. There is no portable entry and no dependency on accounts. `./testing` exports `fakeFetch`, `fakeCodex`, and `usageContract(make, { test? })` (or a test function directly).
+Sources:
 
-Sources are `{ provider: 'codex', bin, home, env? }`, `{ provider: 'opencode', key }`, or `{ provider: 'zai', key }`. Paths must be absolute; removed or empty keys mean disconnected. Claude plan-token adapters stay in the host: the host's own Source reads its payload and calls `claudeWindows(raw)`. This package opens no Claude files, sends no Claude headers, and refreshes no sign-in.
+- `{ provider: 'codex', access, accountId }` reads ChatGPT's `wham/usage`.
+- `{ provider: 'claude', access, accountUuid?, accountId? }` reads Claude plan usage.
+- `{ provider: 'copilot' | 'grok' | 'minimax' | 'kimi', access, accountId? }` reads
+  the corresponding subscription quota. MiniMax's `access` is the plan key.
+- `{ provider: 'gemini', access, project?, accountId? }` reads Code Assist quota.
+  Without a project, the kit discovers it through `loadCodeAssist` first.
+- `{ provider: 'opencode' | 'zai', key, accountId? }` reads plan-key quota.
+- `{ provider: 'codex', bin, home, env? }` retains the explicit local app-server source.
+- `{ provider: 'claude', credentialsFile, configFile?, statuslineFile? }` is a
+  read-only adapter for files the app explicitly supplies. It reads `claudeAiOauth`
+  and optionally `oauthAccount.accountUuid`. A statusline snapshot uses its body `fetched_at` (epoch milliseconds or ISO date),
+  never file mtime. Known snapshots younger than five minutes precede the endpoint;
+  undated/future snapshots remain visible with unknown/future age. An expired token is never sent.
+- `{ provider: 'claude', accountUuid, read, origin?, connected? }` delegates to the app's
+  reader. `read({ nowMs, signal })` returns `{ raw?, code?, retryAfterMs?, at?, limited? }` using
+  the same Claude payload dialect. The host supplies the actual observation `at`;
+  omitted means unknown age, including engine-cached figures. `limited: true` can
+  report an authoritative block without fabricating a window. `origin` is the
+  host reader's optional HTTP origin for pacing. It has a ten-second deadline, with the signal
+  aborted at expiry. The optional synchronous `connected()` hook controls whether
+  last-good readings remain visible; exceptions count as disconnected.
 
-`read(source, { nowMs? })` resolves `{ provider, windows, at, code? }`. Remaining room is `100 - usedPercent`; reset times are provider epoch seconds, even outside a plausible clock-display range. `lastKnown(source, { nowMs? })` returns the stored reading only within 24 hours while connected. `connected(source)` and `account(source)` are synchronous; the latter is a salted fingerprint for a host's collection memo. Only bad sources reject with `UsageError` (`code: 'bad-source'`). Failures retain a last-good reading and its original timestamp, with a code explaining the failed update. A good read has no code. Reads have a 60-second floor, per-account concurrent deduplication and a 429 backoff of at least five minutes. `UsageOptions.now` supplies the default clock; a per-call clock overrides it. An injected `fetch` wins; otherwise global fetch is resolved on each read.
+`read(source, { nowMs?, signal? })` returns `{ provider, windows, at?, limited?, poll?, code? }`.
+`at` is source observation time; it is absent when unavailable. `poll` contains
+last attempt time, `outcome` (`ok` or a safe failure code) and optional `retryAt`.
+All timestamps are epoch milliseconds. A failed poll keeps the figures and their
+original observation time. Poll 429 (`rate-limited`), host renewal failure
+(`refresh-failed`) and credential refusals are distinct; usage never changes
+account health or renews credentials.
 
-Parsers consume Claude's usage/statusline payload, the Go `usage` member, the Z.ai `data.limits` member, or the Codex app-server result (`CodexRateLimitResult`). They carry provider names, normalized kind, percent used, optional duration, reset time, separate limit name and limited flag. Codex windows preserve critical-limit ordering and the eight-window cap. Raw endpoint dialects stay behind this typed surface.
+Windows include kind, optional reported `usedPercent`, duration, reset, limit,
+`limited` and `scope: { model?, surface? }`. Missing usage is unknown, never zero.
+Claude `limits[]` session/weekly-all rows override corresponding legacy aggregates,
+even if incomplete; dynamic weekly-scoped rows retain model and surface. Legacy
+`five_hour`/`seven_day` are fallback for absent aggregate kinds. These are synthetic
+contract fixtures; fresh live provider payload qualification has not been run.
 
-Isolation: the kit reads only the sign-in folder the app passes and spawns only the Codex binary the app passes by absolute path. It discovers no paths and reads no environment variables. The spawn uses an argv array and an environment built from nothing plus the host's `env` and `CODEX_HOME=home`; pass PATH and HOME explicitly when the binary needs them. Tokens never enter logs, errors or readings. Maps hold fingerprints, never raw secrets. The kit reads only `home/auth.json` for Codex identity and writes only `stateDir/plans-v1.json` (0700 directory, 0600 file, atomic rename, 256 KB cap). `salt` defaults to `byokit/usage/account`; a migrating host may preserve its previous salt and stateDir. Legacy stores from before per-account storage are not supported.
+Parsers are exported: `claudeWindows`, `codexWindows` (app-server),
+`codexTokenWindows(raw, nowMs?)`, `codexHardLimit`, `goWindows`, `zaiWindows`,
+`copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`, `kimiWindows`.
+Codex absolute reset takes precedence; relative seconds require a captured clock.
+Hard flags do not replace the reported percentage or invent an absent window.
+Hosts using exported Codex parsers must carry `codexHardLimit(raw)` into the reading
+as `limited` to represent windowless blocks.
 
-The undocumented provider endpoints are fixed to `https://opencode.ai/zen/go/v1/usage` and `https://api.z.ai/api/monitor/usage/quota/limit`, with Bearer keys passed by the host, `accept: application/json`, and redirects rejected. HTTP reads have a 10-second deadline and 64 KB body cap. Codex runs `app-server`, initializes the client and calls `account/rateLimits/read`, with a 20-second deadline, 64 KB stdout cap and SIGTERM followed by SIGKILL after one second. No telemetry or credential write-back.
+`roomOf(reading, nowMs)` returns `left`, observation `at?`, `ageMs?`, `freshness`
+(`fresh`, `stale`, `future`, `unknown`), `poll?`, and the tightest row's `scope?`.
+Numeric results include `span` and optional reset. Authoritative hard blocks give
+zero eligibility room even without a percentage/window, with `limited: true`;
+a predicted reset never clears a block. Otherwise undated/future/older-than-24h
+readings and disconnected/expired/auth/no-plan readings give unknown room.
+Incomplete windows cannot establish positive room; known exhaustion still stands.
+Scope is conservative across all windows until hosts implement model demand for
+every model/surface a run can use, including subagents and fallbacks.
+Temporary poll failures may retain eligible last-good room and its age; a poll
+failure itself never exhausts or moves an account. Auto's shared input contract is
+`fixtures/conformance/usage-typescript.json` and runtime spec section 13.
 
-Tests run the contract with recorded, sanitized payloads and fakes only, behind the repository's egress guard. Real endpoints and real sign-in folders are never run by the suite. `usageContract` takes a bench with `usage`, `source`, `expected`, `nowMs`, `restart`, optional `cleanup`, and optional scripted `fake` (`fail`, `disconnect`, `calls`). Scripted-failure cases skip without the fake seam.
+`connected(source)` and `account(source)` are synchronous. `account` returns a salted
+fingerprint of a non-secret host id, credential account UUID, token subject, or explicit
+local folder identity. Token subjects provide cache identity only, never authentication.
+For opaque tokens and plan keys, pass `accountId` to keep quota history across renewal.
+Without it, reads still work in memory, but `account()` is undefined and no public or
+disk store is used. Tokens never become persisted fingerprint inputs.
+
+Good reads have no code. Bad sources throw `UsageError` (`code: 'bad-source'`); other
+failures resolve codes without bodies or secrets. `lastKnown(source, { nowMs? })`
+returns a connected account's last-good figures and most recent poll outcome.
+Ordinary dated readings expire after 24 hours; authoritative blocks stay until a
+new successful read replaces them. Undated figures remain available for display
+with unknown room. Reads have a
+60-second floor and concurrent deduplication per provider/account. Default 429
+backoff honors Retry-After with a five-minute minimum. Unknown/transient and
+refresh failures back off exponentially from one minute to one hour; these are
+kit defaults, not universal provider policy. Failure counters are separate by
+outcome and account, cleared by a successful quota poll. `UsageOptions.now` supplies
+the default clock; a per-call clock overrides it. An injected `fetch` wins; otherwise
+global fetch is resolved on each read.
+
+The host may supply public synchronous persistence and backoff hooks:
+
+```ts
+import { usage, type UsageStore, type BackoffState } from '@byokit/usage';
+// Replace these maps with your app's durable store to retain state across restart.
+const appStore: UsageStore = {
+  get(provider, fingerprint) { return saved.get(`${provider}/${fingerprint}`); },
+  put(provider, fingerprint, reading) { saved.set(`${provider}/${fingerprint}`, reading); },
+};
+const saved = new Map<string, import('@byokit/usage').StoredReading>();
+const appBackoff = new Map<string, BackoffState | number>();
+const reader = usage({
+  store: {
+    get(provider, fingerprint) { return appStore.get(provider, fingerprint); },
+    put(provider, fingerprint, reading) { appStore.put(provider, fingerprint, reading); },
+  },
+  backoff: {
+    get(provider, fingerprint) { return appBackoff.get(`${provider}/${fingerprint}`); },
+    set(provider, fingerprint, untilMs, state) { appBackoff.set(`${provider}/${fingerprint}`, state ?? untilMs); },
+    delayMs(retryAfterMs, { outcome, failures }) { return Math.max(300_000, retryAfterMs ?? 0); },
+  },
+});
+```
+
+`UsageStore` holds `{ at?, windows, limited?, poll? }`; only whitelisted normalized fields cross
+this boundary. Exceptions from host hooks do not expose data or fail a provider read.
+Internal backoff remains effective if a host backoff hook fails. The 60-second
+minimum retry interval applies even if a policy selects a shorter delay. By default,
+`stateDir` selects an atomic disk store (0700 directory, 0600 file, 256 KB cap), or
+without `stateDir` an in-memory store is used. `memoryUsageStore()` is exported.
+`store` overrides `stateDir`. Disk storage uses `plans-v2.json`, deliberately ignoring
+old raw-payload stores so second-based and millisecond-based readings never mix.
+The default salt is `byokit/usage/account`.
+
+To replace a host's Claude quota adapter, pass the exact files the host already
+selected. Reuse the backoff policy across collector instances:
+
+```ts
+import { usage, fileUsageStore, memoryBackoffPolicy, fingerprint } from '@byokit/usage';
+const salt = 'my-app/usage/account';
+const store = fileUsageStore('/app/state/usage');
+const backoff = memoryBackoffPolicy();
+const source = {
+  provider: 'claude' as const,
+  credentialsFile: '/app/sign-ins/claude/.credentials.json',
+  configFile: '/app/sign-ins/claude/.claude.json',
+  statuslineFile: '/app/sign-ins/claude/statusline.json',
+};
+const reader = usage({ store, backoff, salt });
+const reading = await reader.read(source);
+const lastGood = reader.lastKnown(source);
+// For a host-owned non-secret account UUID, this matches reader.account(source).
+declare const accountUuid: string;
+const accountKey = fingerprint(salt)('claude', accountUuid);
+const saved = store.get('claude', accountKey);
+```
+
+The kit replaces the credential/snapshot read, quota request, payload parsing,
+account fingerprint, last-good disk writes and 429 rest tracking. The host selects
+paths and displays the returned windows. A valid recent snapshot precedes the
+request; the request uses the kit's own user agent. No credential refresh occurs.
+Legacy raw stores require host migration into normalized millisecond readings;
+they are never loaded automatically.
+
+`fileUsageStore(absoluteStateDir)` exposes the same bounded atomic disk store as
+`stateDir`; invalid directory paths throw `UsageError`. Its keys must be 64-character
+hex fingerprints, and it persists normalized observations, hard blocks and poll metadata.
+`fingerprint(salt)` returns `(provider, nonSecretIdentity) => string`; use the same
+salt as the reader and never supply a token as the identity.
+`memoryBackoffPolicy()` supplies shared per-provider/account rests, keeps the later
+rest when updated, and writes no files. The host can use `retryAfterMs(header, nowMs)`
+to parse Retry-After seconds or an HTTP date (invalid/absent values give `undefined`,
+past dates clamp to zero), and `backoffDelayMs(retryAfterMs)` to apply the default
+five-minute minimum. These helpers also support an app-owned Claude `read` hook
+without duplicating fingerprint, persistence or retry logic.
+
+`BackoffPolicy.set(provider, fingerprint, untilMs, state?)` receives a normalized
+`state` with `{ untilMs, at, outcome, failures }` on a retryable failure, and zero
+eligibility time without state after success. Persist and return that state from
+`get` to preserve outcome and retry eligibility across restart. Legacy numeric
+`get` values still work; their reason is unavailable when no stored poll supplies it.
+`delayMs(retryAfterMs, { outcome, failures })` chooses host policy; a valid server
+Retry-After is always a lower bound, alongside the existing one-minute floor.
+
+`UsageOptions.pace({ provider, account, origin, signal })` is an optional async host
+hook before each HTTP usage request (including provider discovery/fallback reads).
+The host can share an origin-keyed queue across reader instances. Distinct origins
+are independent; the kit adds no global queue or fixed origin spacing. Account is
+a fingerprint, never a token. Host Claude readers opt in with `source.origin`.
+The hook shares the request deadline and can be cancelled by `ReadOptions.signal`;
+no request is sent when pacing fails or is cancelled. In-flight duplicate callers
+share the first caller's operation/signal. There is no polling timer or inference ping.
+
+Isolation: there is no home/path discovery or environment read. Only absolute files
+and the Codex binary explicitly supplied by the app are opened/run. Credential files
+are bounded regular files, with final symlinks rejected. The spawn uses argv and an
+environment built from the host's explicit `env` plus `CODEX_HOME=home`; pass PATH
+and HOME explicitly when needed. No tokens in logs, errors, readings or public hooks;
+no credential write-back, telemetry, automatic refresh or reset-credit spend.
+
+Built-in requests send `User-Agent: byokit/usage/0.3.0`, never another app's identity.
+A refusal returns a code; with no last-good quota, room is unknown. Fixed endpoints
+are Anthropic `api/oauth/usage`, ChatGPT `backend-api/wham/usage`, GitHub
+`copilot_internal/user`, Grok `v1/billing` (weekly credits then monthly when needed),
+MiniMax `v1/token_plan/remains`, Gemini `v1internal:retrieveUserQuota`, Kimi
+`coding/v1/usages`, OpenCode `zen/go/v1/usage`, and z.ai `monitor/usage/quota/limit`.
+HTTP requests reject redirects, have a ten-second deadline and a 64 KB body cap.
+Claude includes `anthropic-beta: oauth-2025-04-20`; Codex includes the host's
+`ChatGPT-Account-Id`. Codex app-server reads have a twenty-second deadline, a 64 KB
+stdout cap and SIGTERM followed by SIGKILL after one second.
+
+The Node-only main entry also exports `UsageError`, types, `words` and `usageWords`.
+`./testing` exports `fakeFetch`, `fakeCodex` and `usageContract(make, { test? })`.
+Tests use synthetic recorded protocol shapes and fakes behind the repository's
+network guard. They never open real sign-ins or call provider endpoints.
+
+`tokenLedger({ store?, cap? })` records measured token counts for host member ids.
+`record(member, tokens, time)` accepts a nonnegative safe integer and epoch milliseconds;
+`query(member, from, to)` uses `[from, to)` bounds and returns total `tokens`, sorted
+local-calendar `days: [{ date, tokens }]`, and a `week` ending at `to`. The week spans
+seven local calendar days (including DST), independent of `from`, and includes
+`{ from, to, tokens, cap?, remaining? }`. Remaining allowance is clamped to zero.
+`cap` is a seven-day token count or a synchronous member-to-cap function; omitted
+means uncapped. `store` implements `record(member, { tokens, time })` and
+`query(member, from, to)`, with `memoryTokenLedgerStore()` as the default. Reuse a
+store to keep history across reader instances. The host owns durable storage and
+retention; the default ledger never writes files. Invalid inputs and store failures
+throw `TokenLedgerError` with `code: 'invalid' | 'store'`, without exposing member ids
+or store exception text. Entries are counts only, never sign-in tokens.
+
+`callLedger({ store?, prices? })` records runtime model calls through the same
+`TokenLedgerStore` seam. `record(member, { provider, account, model, runId, time,
+billing, usage?, payer?, durationMs?, state?, limits? })` returns and stores one
+`CallRecord`. `billing` is `subscription` or `api`; `payer` defaults to the member.
+`state` is `completed` (default), `cancelled` or `failed`. The host records each
+actual model call, including retries, and supplies the provider's final usage when
+available. No missing counts are inferred from words or decision sub-answers.
+
+`normalizeTokens(provider, usage)` accepts native usage or its response envelope,
+and normalized `{ input?, output?, cachedInput?, cacheWrite?, total? }` counts.
+It returns only safe nonnegative integer counts with
+`provenance: 'reported' | 'partial' | 'unknown'`. Input includes cache reads/writes,
+which are subsets, so total is input plus output once. Claude's distinct cache
+buckets are added to ordinary input ([Claude usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching));
+OpenAI-compatible input already includes cache ([OpenAI caching](https://developers.openai.com/api/docs/guides/prompt-caching)).
+Gemini output includes candidates and thinking tokens ([Gemini UsageMetadata](https://ai.google.dev/api/generate-content#UsageMetadata)).
+Absent, invalid, explicitly estimated or inconsistent counts remain unknown; raw
+response objects, prompts and credential fields are discarded.
+
+Prices are host data keyed by provider then model: `{ billing, currency,
+inputPerMillion, outputPerMillion, cachedInputPerMillion?, cacheWritePerMillion? }`.
+`priceCall(tokens, price, billing)` and the ledger return a cost only when reported
+counts and the matching app price row suffice. No vendor prices are bundled or
+fetched. Costs carry `basis: 'app-prices'`, `estimated: true`, and billing labels
+`Person's own plan` or `Person's API bill`; an estimate is not an invoice or an
+extra charge against a subscription. Missing separate cache rates use the host's
+input rate. If a separate rate requires an unknown cache count, cost is unknown.
+
+`query(member, from, to)` returns time-sorted `calls`, aggregate `tokens`, `costs`
+separated by currency and billing, and `unpricedCalls`. An aggregate field is
+unknown if any call lacks that field. Store implementations must preserve the
+entry's optional `call` metadata to replay calls; the default in-memory store does.
+Sharing the store lets `tokenLedger.query` count these calls automatically. For
+calls with unknown total counts, member/day/week results expose `unknownCalls`,
+`tokens` is the known subtotal, and week `remaining` is omitted. Cap and price
+policy remain the host's. All times, durations and quota reset timestamps are
+milliseconds. There is no transport, credential discovery or automatic rotation.
+
+When passing normalized windows to `@byokit/accounts`' structural helper, use
+`roomOf(reading.windows, reading.at, 'milliseconds')`. Its two-argument form is for
+legacy reset seconds; normalized usage windows in 0.2.0+ already use milliseconds.
+Alternatively, this package's `roomOf(reading, nowMs)` returns a structural `Room`
+that the accounts chooser accepts directly. Preserve the original measurement time.

package/dist/backoff.d.ts

@@ -0,0 +1,7 @@
+import type { BackoffPolicy } from './types.ts';
+/** Parse Retry-After seconds or HTTP-date into a duration in milliseconds. */
+export declare function retryAfterMs(header: string | null | undefined, nowMs: number): number | undefined;
+/** Default quota rest: honor a longer server delay, otherwise wait five minutes. */
+export declare function backoffDelayMs(retryAfter: number | undefined): number;
+/** Share this policy between readers to preserve per-account 429 rests in memory. */
+export declare function memoryBackoffPolicy(): BackoffPolicy;

package/dist/backoff.js

@@ -0,0 +1,26 @@
+/** Parse Retry-After seconds or HTTP-date into a duration in milliseconds. */
+export function retryAfterMs(header, nowMs) {
+    if (!header?.trim())
+        return undefined;
+    const value = header.trim();
+    const delay = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) * 1000 : Date.parse(value) - nowMs;
+    return Number.isFinite(delay) ? Math.max(0, delay) : undefined;
+}
+/** Default quota rest: honor a longer server delay, otherwise wait five minutes. */
+export function backoffDelayMs(retryAfter) {
+    return Math.max(300_000, typeof retryAfter === 'number' && Number.isFinite(retryAfter) ? retryAfter : 0);
+}
+/** Share this policy between readers to preserve per-account 429 rests in memory. */
+export function memoryBackoffPolicy() {
+    const rests = new Map();
+    return {
+        get: (provider, account) => rests.get(`${provider}\0${account}`),
+        set: (provider, account, untilMs) => {
+            if (!Number.isFinite(untilMs))
+                return;
+            const key = `${provider}\0${account}`;
+            rests.set(key, Math.max(rests.get(key) ?? 0, untilMs));
+        },
+        delayMs: backoffDelayMs,
+    };
+}

package/dist/calls.d.ts

@@ -0,0 +1,68 @@
+import { type TokenLedgerStore } from './ledger.ts';
+import type { Window } from './types.ts';
+export interface NormalizedTokens {
+    /** Input includes cache reads and cache writes; cache counts are subsets. */
+    input?: number;
+    output?: number;
+    cachedInput?: number;
+    cacheWrite?: number;
+    total?: number;
+    provenance: 'reported' | 'partial' | 'unknown';
+}
+export interface ModelPrice {
+    billing: 'subscription' | 'api';
+    currency: string;
+    inputPerMillion: number;
+    outputPerMillion: number;
+    cachedInputPerMillion?: number;
+    cacheWritePerMillion?: number;
+}
+export type PriceTable = Readonly<Record<string, Readonly<Record<string, ModelPrice>>>>;
+export interface CallCost {
+    amount: number;
+    currency: string;
+    billing: ModelPrice['billing'];
+    label: "Person's own plan" | "Person's API bill";
+    basis: 'app-prices';
+    estimated: true;
+}
+export interface CallInput {
+    provider: string;
+    account: string;
+    model: string;
+    runId: string;
+    time: number;
+    billing: 'subscription' | 'api';
+    /** Native provider usage/envelope, or normalized input/output/cachedInput/cacheWrite/total counts. */
+    usage?: unknown;
+    payer?: string;
+    durationMs?: number;
+    state?: 'completed' | 'cancelled' | 'failed';
+    limits?: readonly Window[];
+}
+export interface CallRecord extends Omit<CallInput, 'usage' | 'limits'> {
+    tokens: NormalizedTokens;
+    state: 'completed' | 'cancelled' | 'failed';
+    cost?: CallCost;
+    limits?: Window[];
+}
+export interface CallQuery {
+    calls: CallRecord[];
+    tokens: NormalizedTokens;
+    /** Separate subtotals by currency and billing; unpriced calls are counted explicitly. */
+    costs: CallCost[];
+    unpricedCalls: number;
+}
+export interface CallLedger {
+    record(member: string, call: CallInput): CallRecord;
+    query(member: string, from: number, to: number): CallQuery;
+}
+/** Pure normalization of reported counts, never estimates from text or shared decision invocations. */
+export declare function normalizeTokens(provider: string, raw: unknown): NormalizedTokens;
+/** App-supplied price estimates only, including explicit billing attribution. */
+export declare function priceCall(tokens: NormalizedTokens, price: ModelPrice | undefined, billing: ModelPrice['billing']): CallCost | undefined;
+/** Every recorded attempt is a call; the host records retries separately under its run id. */
+export declare function callLedger(options?: {
+    store?: TokenLedgerStore;
+    prices?: PriceTable;
+}): CallLedger;

package/dist/calls.js

@@ -0,0 +1,131 @@
+import { record as isRecord } from "./windows.js";
+import { memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
+import { safeWindows } from "./store.js";
+const object = (value) => isRecord(value) ? value : {};
+const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const text = (value) => typeof value === 'string' && !!value && value.length <= 1024 && !/[\0\r\n]/.test(value);
+const time = (value) => typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(new Date(value).getTime());
+const sum = (...values) => count(values.reduce((a, b) => a + b, 0));
+function normalized(input, output, cachedInput, cacheWrite, total) {
+    if (input !== undefined && ((cachedInput ?? 0) + (cacheWrite ?? 0) > input))
+        return { provenance: 'unknown' };
+    const derived = input !== undefined && output !== undefined ? sum(input, output) : undefined;
+    // Inconsistent reported totals are not a reliable measurement.
+    if (derived !== undefined && total !== undefined && derived !== total)
+        return { provenance: 'unknown' };
+    const measured = derived ?? total;
+    return { ...(input === undefined ? {} : { input }), ...(output === undefined ? {} : { output }),
+        ...(cachedInput === undefined ? {} : { cachedInput }), ...(cacheWrite === undefined ? {} : { cacheWrite }),
+        ...(measured === undefined ? {} : { total: measured }),
+        provenance: input !== undefined && output !== undefined && derived !== undefined ? 'reported' : [input, output, cachedInput, cacheWrite, measured].some((v) => v !== undefined) ? 'partial' : 'unknown' };
+}
+/** Pure normalization of reported counts, never estimates from text or shared decision invocations. */
+export function normalizeTokens(provider, raw) {
+    const envelope = object(raw);
+    const usage = object(envelope.usage ?? envelope.usageMetadata ?? raw);
+    if (usage.provenance === 'unknown' || usage.provenance === 'estimated')
+        return { provenance: 'unknown' };
+    if (['input', 'output', 'total'].some((key) => key in usage))
+        return normalized(count(usage.input), count(usage.output), count(usage.cachedInput), count(usage.cacheWrite), count(usage.total));
+    if (provider === 'claude' || provider === 'anthropic') {
+        if (!['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'].some((key) => count(usage[key]) !== undefined))
+            return { provenance: 'unknown' };
+        const uncached = count(usage.input_tokens);
+        const cached = count(usage.cache_read_input_tokens) ?? (usage.cache_read_input_tokens === undefined ? 0 : undefined);
+        const written = count(usage.cache_creation_input_tokens) ?? (usage.cache_creation_input_tokens === undefined ? 0 : undefined);
+        const input = uncached !== undefined && cached !== undefined && written !== undefined ? sum(uncached, cached, written) : undefined;
+        return normalized(input, count(usage.output_tokens), cached, written);
+    }
+    if (provider === 'gemini' || provider === 'google') {
+        const output = count(usage.candidatesTokenCount);
+        const thoughts = count(usage.thoughtsTokenCount) ?? (usage.thoughtsTokenCount === undefined ? 0 : undefined);
+        const input = count(usage.promptTokenCount);
+        return normalized(input, output !== undefined && thoughts !== undefined ? sum(output, thoughts) : undefined, count(usage.cachedContentTokenCount), undefined, count(usage.totalTokenCount));
+    }
+    const input = count(usage.input_tokens ?? usage.prompt_tokens);
+    const output = count(usage.output_tokens ?? usage.completion_tokens);
+    const details = object(usage.input_tokens_details ?? usage.prompt_tokens_details);
+    return normalized(input, output, count(details.cached_tokens), count(details.cache_write_tokens), count(usage.total_tokens));
+}
+/** App-supplied price estimates only, including explicit billing attribution. */
+export function priceCall(tokens, price, billing) {
+    if (!price || price.billing !== billing || tokens.input === undefined || tokens.output === undefined || tokens.provenance !== 'reported' || !text(price.currency))
+        return undefined;
+    if ([tokens.input, tokens.output, tokens.cachedInput, tokens.cacheWrite, tokens.total].some((value) => value !== undefined && count(value) === undefined) || tokens.total !== undefined && tokens.input + tokens.output !== tokens.total)
+        return undefined;
+    const rates = [price.inputPerMillion, price.outputPerMillion, price.cachedInputPerMillion, price.cacheWritePerMillion];
+    if (rates.some((rate) => rate !== undefined && (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0)))
+        return undefined;
+    if (typeof price.inputPerMillion !== 'number' || typeof price.outputPerMillion !== 'number')
+        return undefined;
+    if (tokens.cachedInput === undefined && price.cachedInputPerMillion !== undefined && price.cachedInputPerMillion !== price.inputPerMillion
+        || tokens.cacheWrite === undefined && price.cacheWritePerMillion !== undefined && price.cacheWritePerMillion !== price.inputPerMillion)
+        return undefined;
+    const cached = tokens.cachedInput ?? 0;
+    const written = tokens.cacheWrite ?? 0;
+    const ordinary = tokens.input - cached - written;
+    if (ordinary < 0)
+        return undefined;
+    const amount = (ordinary * price.inputPerMillion + cached * (price.cachedInputPerMillion ?? price.inputPerMillion)
+        + written * (price.cacheWritePerMillion ?? price.inputPerMillion) + tokens.output * price.outputPerMillion) / 1_000_000;
+    if (!Number.isFinite(amount))
+        return undefined;
+    return { amount, currency: price.currency, billing, label: billing === 'subscription' ? "Person's own plan" : "Person's API bill", basis: 'app-prices', estimated: true };
+}
+function aggregate(calls) {
+    const field = (key) => calls.every((call) => call.tokens[key] !== undefined) ? count(calls.reduce((total, call) => total + call.tokens[key], 0)) : undefined;
+    return normalized(field('input'), field('output'), field('cachedInput'), field('cacheWrite'), field('total'));
+}
+/** Every recorded attempt is a call; the host records retries separately under its run id. */
+export function callLedger(options = {}) {
+    const store = options.store ?? memoryTokenLedgerStore();
+    return {
+        record(member, call) {
+            if (!text(member) || !call || ![call.provider, call.account, call.model, call.runId].every(text) || !time(call.time)
+                || !['subscription', 'api'].includes(call.billing) || call.payer !== undefined && !text(call.payer)
+                || call.durationMs !== undefined && (typeof call.durationMs !== 'number' || !Number.isFinite(call.durationMs) || call.durationMs < 0)
+                || call.state !== undefined && !['completed', 'cancelled', 'failed'].includes(call.state) || call.limits !== undefined && !Array.isArray(call.limits))
+                throw new TokenLedgerError('invalid');
+            const tokens = normalizeTokens(call.provider, call.usage);
+            const cost = priceCall(tokens, options.prices?.[call.provider]?.[call.model], call.billing);
+            const limits = call.limits?.flatMap((window) => safeWindows(window.provider, [window]));
+            const result = { provider: call.provider, account: call.account, model: call.model, runId: call.runId, time: call.time,
+                billing: call.billing, payer: call.payer ?? member, state: call.state ?? 'completed', tokens,
+                ...(call.durationMs === undefined ? {} : { durationMs: call.durationMs }), ...(cost ? { cost } : {}), ...(limits ? { limits } : {}) };
+            try {
+                store.record(member, { time: call.time, tokens: tokens.total ?? 0, call: copyCall(result) });
+            }
+            catch {
+                throw new TokenLedgerError('store');
+            }
+            return result;
+        },
+        query(member, from, to) {
+            if (!text(member) || !time(from) || !time(to) || to < from)
+                throw new TokenLedgerError('invalid');
+            let entries;
+            try {
+                entries = store.query(member, from, to);
+            }
+            catch {
+                throw new TokenLedgerError('store');
+            }
+            if (!Array.isArray(entries))
+                throw new TokenLedgerError('invalid');
+            const calls = entries.filter((entry) => entry.call && entry.time >= from && entry.time < to).map((entry) => copyCall(entry.call)).sort((a, b) => a.time - b.time);
+            const costs = new Map();
+            for (const call of calls) {
+                if (!call.cost)
+                    continue;
+                const key = `${call.cost.currency}\0${call.cost.billing}`;
+                const previous = costs.get(key);
+                costs.set(key, { ...call.cost, amount: (previous?.amount ?? 0) + call.cost.amount });
+            }
+            return { calls, tokens: aggregate(calls), costs: [...costs.values()], unpricedCalls: calls.filter((call) => !call.cost).length };
+        },
+    };
+}
+function copyCall(call) {
+    return { ...call, tokens: { ...call.tokens }, ...(call.cost ? { cost: { ...call.cost } } : {}),
+        ...(call.limits ? { limits: call.limits.map((window) => ({ ...window })) } : {}) };
+}

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 import { type Usage, type UsageOptions } from './types.ts';
 export * from './types.ts';
+export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
+export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError, type TokenLedger, type TokenLedgerStore, type TokenLedgerOptions, type TokenEntry, type TokenQuery } from './ledger.ts';
+export { roomOf } from './room.ts';
+export { fingerprint, store as fileUsageStore, memoryUsageStore } from './store.ts';
+export { retryAfterMs, backoffDelayMs, memoryBackoffPolicy } from './backoff.ts';
 export { claudeWindows, codexWindows, goWindows, zaiWindows, type CodexRateLimitResult } from './windows.ts';
+export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from './quota.ts';
 export { WORDS, words, usageWords, type WordKey } from './words.ts';
 /** One reader owns per-account backoff and concurrent-read deduplication. */
 export declare function usage(options: UsageOptions): Usage;