@byokit/usage 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 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,212 @@
 # @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';
+// Supplied by the host's signed-in account.
+declare const token: string;
+declare const account: { id: string };
 const reader = usage({ stateDir: '/app/state/usage' });
-const source = { provider: 'codex' as const, bin: '/app/bin/codex', home: '/app/sign-ins/alice' };
+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 valid statusline snapshot younger
+  than five minutes precedes the endpoint. An expired token is never sent.
+- `{ provider: 'claude', accountUuid, read, connected? }` delegates to the app's
+  reader. `read({ nowMs, signal })` returns `{ raw?, code?, retryAfterMs? }` using
+  the same Claude payload dialect. 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? })` returns `{ provider, windows, at, code? }`; `at` and all
+`resetsAt` fields are **epoch milliseconds** in 0.2.0. This changes 0.1.0's seconds
+reset convention. Windows include kind, used percent, optional duration in minutes,
+reset time, limit label and limited flag. Parsers are exported for host integrations:
+`claudeWindows`, `codexWindows` (app-server), `codexTokenWindows`, `goWindows`,
+`zaiWindows`, `copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`,
+`kimiWindows(raw, nowMs)`.
 
-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.
+`roomOf(reading, nowMs)` returns `{ left, span, resetsAt?, at }` using the tightest
+window. Span maps session/week/month and maps rolling/custom to `tightest`. Missing
+windows, readings older than 24 hours, future readings, or disconnected/expired/auth/
+no-plan readings give `{ left: 'unknown', at }`. A temporary rate limit or failed
+update can still show the last-good room and its original timestamp. Auto selection
+belongs to the accounts kit; usage only reports room.
 
-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.
+`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.
 
-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.
+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 reading for up to 24 hours. Reads have a
+60-second floor and concurrent deduplication per provider/account. The default 429
+backoff honors Retry-After with a five-minute minimum. `UsageOptions.now` supplies
+the default clock; a per-call clock overrides it. An injected `fetch` wins; otherwise
+global fetch is resolved on each read.
 
-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.
+The host may supply public synchronous persistence and backoff hooks:
+
+```ts
+import { usage, type UsageStore, type BackoffPolicy } from '@byokit/usage';
+declare const appStore: UsageStore;
+declare const appBackoff: BackoffPolicy;
+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) { appBackoff.set(provider, fingerprint, untilMs); },
+    delayMs(retryAfterMs) { return Math.max(300_000, retryAfterMs ?? 0); },
+  },
+});
+```
+
+`UsageStore` holds only `{ at, windows }`; only whitelisted normalized fields cross
+this boundary. Exceptions from host hooks do not expose data or fail a provider read.
+Internal 429 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 only `{ at, windows }` with normalized fields.
+`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.
+
+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.2.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.

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 { 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;