@byokit/usage 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.6.0 (2026-10-01)
+
+- FIX: Claude subscription quota snapshots can now be read through an identity-free ephemeral host callback without credentials or a fabricated account UUID; readings never enter a cache or shared store, and retry state stays local to the source.
+
 ## 0.5.0 (2026-10-01)
 
 - Add a React Native entry for local call/token ledgers and pure quota helpers; subscription and API key (billed per use) attribution is preserved, with estimates only from app prices.

package/README.md

@@ -39,6 +39,26 @@ Sources:
   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
@@ -359,6 +379,11 @@ that the accounts chooser accepts directly. Preserve the original measurement ti
 
 Managed-folder Claude usage uses the shared poll-health and normalized quota pipeline, including scoped hard blocks, unknown usage, last-good observation times, account retry policies and cancellable host origin pacing.
 
+The token and call ledgers accept host-supplied entries/results; they are not
+harness-log or ccusage readers. A bounded incremental log source (including file
+offsets, rotation and bounded work per update) remains outstanding. This snapshot
+source does not implement it or scan real logs.
+
 ## React Native
 
 The `react-native` condition of `@byokit/usage` selects a portable entry. The explicit

package/dist/ephemeral.d.ts

@@ -0,0 +1,3 @@
+import type { EphemeralClaudeSource, Reading, ReadOptions, UsageOptions } from './types.ts';
+/** Only retry/concurrency metadata survives a call; source objects are weakly held. */
+export declare function ephemeralClaude(options: UsageOptions): (source: EphemeralClaudeSource, clock: number, opts?: ReadOptions) => Promise<Reading>;

package/dist/ephemeral.js

@@ -0,0 +1,64 @@
+import { customClaude } from "./providers.js";
+import { safeWindows } from "./safe-windows.js";
+import { claudeWindows } from "./windows.js";
+/** Only retry/concurrency metadata survives a call; source objects are weakly held. */
+export function ephemeralClaude(options) {
+    const states = new WeakMap();
+    return async (source, clock, opts) => {
+        const empty = (poll) => ({ provider: 'claude', windows: [], code: poll.outcome === 'ok' ? 'unavailable' : poll.outcome, poll });
+        let connected = true;
+        try {
+            connected = source.connected?.() ?? true;
+        }
+        catch {
+            connected = false;
+        }
+        if (!connected) {
+            states.delete(source);
+            return empty({ at: clock, outcome: 'not-connected' });
+        }
+        let state = states.get(source);
+        if (!state) {
+            state = { failures: 0 };
+            states.set(source, state);
+        }
+        if (state.pending)
+            return state.pending;
+        if (state.poll?.retryAt !== undefined && clock < state.poll.retryAt)
+            return empty(state.poll);
+        const current = state;
+        const task = (async () => {
+            const answer = await customClaude(source, clock, { signal: opts?.signal });
+            const rows = safeWindows('claude', claudeWindows(answer.raw));
+            const limited = !answer.code && answer.limited === true;
+            const code = answer.code ?? (!rows.length && !limited ? 'incomplete' : undefined);
+            const poll = { at: clock, outcome: code ?? 'ok' };
+            if (code && ['rate-limited', 'refresh-failed', 'unavailable', 'incomplete'].includes(code)) {
+                current.failures = current.poll?.outcome === code ? current.failures + 1 : 1;
+                const retry = typeof answer.retryAfterMs === 'number' && Number.isFinite(answer.retryAfterMs) && answer.retryAfterMs >= 0 ? answer.retryAfterMs : undefined;
+                let delay = code === 'rate-limited' ? 300_000 : Math.min(3_600_000, 60_000 * 2 ** Math.min(current.failures - 1, 6));
+                try {
+                    const selected = options.backoff?.delayMs?.(retry, { outcome: code, failures: current.failures });
+                    if (selected !== undefined && Number.isFinite(selected) && selected >= 0)
+                        delay = selected;
+                }
+                catch { /* internal retry policy stands */ }
+                poll.retryAt = clock + Math.max(60_000, delay, retry ?? 0);
+            }
+            else
+                current.failures = 0;
+            current.poll = poll;
+            if (code)
+                return empty(poll);
+            const at = typeof answer.at === 'number' && Number.isFinite(answer.at) ? answer.at : undefined;
+            return { provider: 'claude', windows: rows, ...(at !== undefined ? { at } : {}), ...(limited ? { limited: true } : {}), poll };
+        })();
+        current.pending = task;
+        try {
+            return await task;
+        }
+        finally {
+            current.pending = undefined;
+        }
+    };
+}

package/dist/index.js

@@ -8,6 +8,7 @@ import { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimax
 import { UsageError } from "./types.js";
 import { codexIdentity } from "./identity.js";
 import { claudeUsage as managedClaudeUsage, claudeCredential, managedClaudeFolder } from "./claude.js";
+import { ephemeralClaude } from "./ephemeral.js";
 export * from "./types.js";
 /** Identity runs only the named binary, never opens a credential file. */
 export async function identity(source) {
@@ -29,6 +30,8 @@ const validText = (v) => typeof v === 'string' && !v.includes('\0') && !/[\r\n]/
 function validate(source, stateDir) {
     if (!record(source) || !providers.includes(source.provider))
         throw new UsageError();
+    if ('ephemeral' in source && (source.ephemeral !== true || source.provider !== 'claude' || typeof source.read !== 'function' || ['accountUuid', 'accountId', 'origin', 'folder', 'credentialsFile', 'access', 'key', 'bin', 'home', 'configFile', 'statuslineFile'].some((field) => field in source)))
+        throw new UsageError();
     if ('folder' in source) {
         if (source.provider !== 'claude' || !validText(source.folder) || !isAbsolute(source.folder) || !stateDir || !managedClaudeFolder(source.folder, stateDir))
             throw new UsageError();
@@ -40,7 +43,7 @@ function validate(source, stateDir) {
             throw new UsageError();
     }
     else if ('read' in source) {
-        if (source.provider !== 'claude' || typeof source.read !== 'function' || !validText(source.accountUuid) || !source.accountUuid || source.connected !== undefined && typeof source.connected !== 'function')
+        if (source.provider !== 'claude' || typeof source.read !== 'function' || !('ephemeral' in source) && (!validText(source.accountUuid) || !source.accountUuid) || source.connected !== undefined && typeof source.connected !== 'function')
             throw new UsageError();
     }
     else if ('bin' in source) {
@@ -98,6 +101,7 @@ export function usage(options) {
     const attempts = new Map();
     const failures = new Map();
     const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
+    const readEphemeral = ephemeralClaude(options);
     function connected(source) {
         validate(source, options.stateDir);
         if ('folder' in source)
@@ -133,7 +137,7 @@ export function usage(options) {
         else if ('credentialsFile' in source)
             id = claudeAuth(source)?.account;
         else if ('read' in source)
-            id = source.accountUuid;
+            id = 'ephemeral' in source ? undefined : source.accountUuid;
         else if ('bin' in source) {
             const raw = readJson(join(source.home, 'auth.json'), 64 * 1024);
             const tokens = record(raw) && record(raw.tokens) ? raw.tokens : undefined;
@@ -165,6 +169,9 @@ export function usage(options) {
         }
     }
     function lastKnown(source, opts) {
+        validate(source, options.stateDir);
+        if ('ephemeral' in source)
+            return undefined;
         if (!connected(source))
             return undefined;
         const id = identity(source);
@@ -187,6 +194,8 @@ export function usage(options) {
     async function read(source, opts) {
         validate(source, options.stateDir);
         const clock = now(opts);
+        if ('ephemeral' in source)
+            return readEphemeral(source, clock, opts);
         const empty = (code) => ({ provider: source.provider, windows: [], code, poll: { at: clock, outcome: code ?? 'unavailable' } });
         if (!connected(source))
             return empty('not-connected');

package/dist/providers.d.ts

@@ -26,7 +26,7 @@ export declare function customClaude(source: Extract<Source, {
     read: unknown;
 }>, nowMs: number, pacing?: {
     hook?: PacingHook;
-    account: string;
+    account?: string;
     signal?: AbortSignal;
 }): Promise<Answer>;
 export declare function codexUsage(source: Extract<Source, {

package/dist/providers.js

@@ -114,7 +114,7 @@ export async function customClaude(source, nowMs, pacing) {
     const timer = setTimeout(abort, 10_000);
     try {
         const operation = async () => {
-            if (source.origin && pacing?.hook)
+            if ('origin' in source && source.origin && pacing?.hook && pacing.account !== undefined)
                 await pacing.hook({ provider: source.provider, account: pacing.account, origin: source.origin, signal: controller.signal });
             if (controller.signal.aborted)
                 return { code: 'unavailable' };

package/dist/types.d.ts

@@ -29,7 +29,7 @@ export type Source = {
     read: ClaudeReader;
     origin?: string;
     connected?: () => boolean;
-}) | {
+}) | EphemeralClaudeSource | {
     provider: 'claude';
     credentialsFile: string;
     configFile?: string;
@@ -106,6 +106,13 @@ export type ClaudeReader = (options: {
     nowMs: number;
     signal: AbortSignal;
 }) => Promise<SourceAnswer>;
+/** Reuse one source object per host-owned snapshot stream; no identity or last-good cache. */
+export type EphemeralClaudeSource = {
+    provider: 'claude';
+    ephemeral: true;
+    read: ClaudeReader;
+    connected?: () => boolean;
+};
 export type StoredReading = {
     at?: number;
     windows: Window[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/usage",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Read subscription usage windows per provider and account.",
   "license": "Apache-2.0",
   "type": "module",