@byokit/usage weekly downloads statistics

@byokit/usage

Read subscription quota windows per provider and per account on Node 22.18 or later. React Native also supports local call/token accounting and pure quota parsing. The app owns sign-in, token renewal, account labels and selection. The kit reads room left, estimates cost only from app-supplied prices and never rotates an account.

import { usage, roomOf } from '@byokit/usage';
const reader = usage({ stateDir: '/app/state/usage' });
// 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);
const room = roomOf(reading, Date.now());

Sources:

• { 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: 'cursor', folder } reads the dashboard's current-period usage (GetCurrentPeriodUsage on api2.cursor.sh) with the folder's own login from <folder>/cursor/auth.json, parsed to one monthly window.
• { provider: 'pi', folder, piProvider } reads the plan the selected Pi provider id names, from that folder's own login in <folder>/auth.json: openai-codex reads ChatGPT's Codex windows (wham/usage, addressed by the stored ChatGPT account id or the access token's own claim) and kimi-coding reads Kimi's windows (coding/v1/usages). Any other Pi provider id is refused as an invalid source. A missing or refused reading is unknown, never zero. The account cache fingerprint uses the sign-in file's metadata only, never its contents. A re-login or a refresh-only rewrite of <folder>/auth.json changes its metadata and drops the last-good reading.
• { provider: 'claude', credentialsFile, configFile?, statuslineFile? } is a read-only adapter for files the app explicitly supplies. It reads claudeAiOauth and optionally oauthAccount.accountUuid. A path carrying a .claude, .codex or .pi segment, lexically or through a symlink, is refused with UsageError before any file is opened, so the person's own default sign-in is never read. 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.
• { provider: 'claude', ephemeral: true, read, connected? } supports a host-owned opaque snapshot stream without an account UUID, email, folder or token. The same ClaudeReader answer and ten-second cancellable deadline apply. For a statusline body, return { raw: snapshot, at: snapshot.fetched_at } when the host knows that fetched_at is epoch milliseconds; otherwise omit at for unknown age. The kit normalizes rate_limits and quota rows; it never opens a snapshot or credential file, discovers credentials, copies tokens or makes a fallback request. connected() should reflect the host's sign-in status; false or a thrown error returns not-connected. An absent/invalid snapshot returns incomplete, while timeout/cancellation returns unavailable; the host can report other safe codes. account() and lastKnown() always return undefined. Successful readings are never retained, so each subsequent read invokes the callback again. Only retry metadata and concurrent operations are weakly held per source object in this reader: reuse an immutable source for one stream, and replace it when the host changes sign-in or stream. Failures never return earlier quota figures. Rate limits honor Retry-After with a five-minute default; transient failures use exponential backoff from one minute, capped at one hour. backoff.delayMs may customize these delays with a one-minute minimum. Store and backoff get/set hooks and account-based pacing are never called; the host owns any pacing in its callback. No state is shared between source objects or reader instances.

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.…