@byokit/usage 0.1.0 → 0.2.0

package/dist/quota.js

@@ -0,0 +1,87 @@
+// Protocol shapes informed by can1357/oh-my-pi (MIT), pinned at 2b023d1.
+// This module normalizes quota fields only; it does not import upstream runtime code.
+import { record, window, codexWindows } from "./windows.js";
+const obj = (value) => record(value) ? value : {};
+const rows = (value) => Array.isArray(value) ? value : [];
+const number = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+const label = (value) => typeof value === 'string' ? value.replace(/[^\x20-\x7e]/g, ' ').trim().slice(0, 80) || undefined : undefined;
+const time = (value) => typeof value === 'string' ? Date.parse(value) : number(value);
+const ratio = (used, limit, remaining) => {
+    const cap = number(limit);
+    const consumed = number(used);
+    const left = number(remaining);
+    return cap !== undefined && cap > 0 && (consumed !== undefined || left !== undefined) ? 100 * (consumed ?? cap - left) / cap : undefined;
+};
+export function codexTokenWindows(raw) {
+    const source = obj(raw);
+    const plan = obj(source.rate_limit);
+    const group = (value, name) => ({ limitName: name,
+        ...Object.fromEntries(['primary', 'secondary'].map((key) => {
+            const w = obj(value[`${key}_window`]);
+            return [key, { usedPercent: w.used_percent, windowDurationMins: typeof w.limit_window_seconds === 'number' ? w.limit_window_seconds / 60 : undefined, resetsAt: w.reset_at }];
+        })) });
+    return codexWindows({ rateLimitsByLimitId: Object.fromEntries([
+            ['plan', group(plan, 'Codex')], ...rows(source.additional_rate_limits).map((v, i) => { const extra = obj(v); return [String(i), group(obj(extra.rate_limit), label(extra.limit_name))]; }),
+        ]) });
+}
+export function copilotWindows(raw) {
+    const source = obj(raw);
+    return Object.entries(obj(source.quota_snapshots)).flatMap(([key, value]) => {
+        const quota = obj(value);
+        if (quota.unlimited === true)
+            return [];
+        const left = number(quota.percent_remaining);
+        return window('copilot', 'monthly', left === undefined ? ratio(undefined, quota.entitlement, quota.remaining) : 100 - left, undefined, time(source.quota_reset_date), false, label(key));
+    });
+}
+export function grokWindows(raw) {
+    const config = obj(obj(raw).config);
+    const period = obj(config.currentPeriod);
+    const weekly = number(config.creditUsagePercent);
+    if (weekly !== undefined)
+        return window('grok', 'weekly', weekly, 10080, time(period.end));
+    return window('grok', 'monthly', ratio(config.used, config.monthlyLimit), undefined, time(config.periodEnd));
+}
+export function minimaxWindows(raw) {
+    const source = obj(raw);
+    if (obj(source.base_resp).status_code !== 0)
+        return [];
+    return rows(source.model_remains).flatMap((value) => {
+        const bucket = obj(value);
+        if (bucket.current_interval_status === 3 && bucket.current_weekly_status === 3 && bucket.current_interval_total_count === 0 && bucket.current_weekly_total_count === 0)
+            return [];
+        return ['interval', 'weekly'].flatMap((key) => {
+            const left = number(bucket[`current_${key}_remaining_percent`]);
+            const exhausted = bucket[`current_${key}_status`] === 2;
+            const rawReset = bucket[key === 'interval' ? 'end_time' : 'weekly_end_time'];
+            const reset = typeof rawReset === 'number' && rawReset > 0 ? rawReset < 1e12 ? rawReset * 1000 : rawReset : time(rawReset);
+            return window('minimax', key === 'weekly' ? 'weekly' : 'rolling', exhausted ? 100 : left === undefined ? undefined : 100 - left, key === 'weekly' ? 10080 : undefined, reset, exhausted, label(bucket.model_name));
+        });
+    });
+}
+export function geminiWindows(raw) {
+    return rows(obj(raw).buckets).flatMap((value) => {
+        const bucket = obj(value);
+        const left = number(bucket.remainingFraction);
+        return window('gemini', 'custom', left === undefined ? undefined : 100 - left * 100, undefined, time(bucket.resetTime), false, label(bucket.modelId));
+    });
+}
+export function kimiWindows(raw, nowMs) {
+    const source = obj(raw);
+    const read = (value, minutes, reset) => {
+        const detail = obj(value);
+        const units = { SECOND: 1 / 60, MINUTE: 1, HOUR: 60, DAY: 1440, WEEK: 10080 };
+        const w = obj(detail.window);
+        const duration = number(w.duration);
+        const m = minutes ?? (duration === undefined ? undefined : duration * (units[String(w.timeUnit).toUpperCase().replace(/S$/, '')] ?? NaN));
+        const row = record(detail.detail) ? detail.detail : detail;
+        const resetValue = reset ?? w.resetTime ?? row.resetTime ?? row.reset_at ?? row.resetAt;
+        let resetMs = time(resetValue);
+        if (typeof resetValue === 'number')
+            resetMs = resetValue > 1e12 ? resetValue : resetValue * 1000;
+        if (resetValue === undefined && number(row.reset_in) !== undefined)
+            resetMs = nowMs + number(row.reset_in) * 1000;
+        return window('kimi', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', ratio(row.used, row.limit, row.remaining), m, resetMs);
+    };
+    return [...read(source.usage, 10080), ...read(source.totalQuota), ...rows(source.limits).flatMap((row) => read(row))];
+}

package/dist/room.d.ts

@@ -0,0 +1,3 @@
+import type { Reading, Room } from './types.ts';
+/** Tightest known quota, valid for 24 hours. Refused/authless sources report unknown room. */
+export declare function roomOf(reading: Reading, nowMs: number): Room;

package/dist/room.js

@@ -0,0 +1,11 @@
+/** Tightest known quota, valid for 24 hours. Refused/authless sources report unknown room. */
+export function roomOf(reading, nowMs) {
+    if (!Number.isFinite(reading.at) || !Number.isFinite(nowMs) || nowMs < reading.at || nowMs - reading.at > 86_400_000 || ['not-connected', 'expired', 'auth', 'no-plan'].includes(reading.code ?? ''))
+        return { left: 'unknown', at: reading.at };
+    const tight = reading.windows.reduce((worst, window) => Number.isFinite(window.usedPercent) && (!worst || window.usedPercent > worst.usedPercent) ? window : worst, undefined);
+    if (!tight)
+        return { left: 'unknown', at: reading.at };
+    const span = tight.kind === 'weekly' ? 'week' : tight.kind === 'monthly' ? 'month' : tight.kind === 'session' ? 'session' : 'tightest';
+    return { left: Math.max(0, Math.min(100, 100 - tight.usedPercent)), span, at: reading.at,
+        ...(Number.isFinite(tight.resetsAt) ? { resetsAt: tight.resetsAt } : {}) };
+}

package/dist/store.d.ts

@@ -1,12 +1,13 @@
-import type { Provider } from './types.ts';
-export interface Stored {
-    at: number;
-    raw: unknown;
-}
+import type { Provider, StoredReading, UsageStore, Window } from './types.ts';
+export type Stored = StoredReading;
 /** Bounded regular files only; do not follow credential or state symlinks. */
+export declare function readJsonSnapshot(file: string, cap: number): {
+    value: unknown;
+    modified: number;
+} | undefined;
 export declare function readJson(file: string, cap: number): unknown;
 export declare function fingerprint(salt: string): (provider: Provider, value: string) => string;
-export declare function store(stateDir: string): {
-    get: (id: Provider, fp: string) => Stored | undefined;
-    put(id: Provider, fp: string, reading: Stored): void;
-};
+export declare function store(stateDir: string): UsageStore;
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export declare function safeWindows(provider: Provider, raw: unknown): Window[];
+export declare function memoryUsageStore(): UsageStore;

package/dist/store.js

@@ -1,9 +1,10 @@
 import { createHash, randomUUID, scryptSync } from 'node:crypto';
 import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, constants } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
+import { UsageError } from "./types.js";
 import { record } from "./windows.js";
 /** Bounded regular files only; do not follow credential or state symlinks. */
-export function readJson(file, cap) {
+export function readJsonSnapshot(file, cap) {
     let fd;
     try {
         fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -18,7 +19,7 @@ export function readJson(file, cap) {
                 break;
             length += count;
         }
-        return length <= cap ? JSON.parse(body.subarray(0, length).toString('utf8')) : undefined;
+        return length <= cap ? { value: JSON.parse(body.subarray(0, length).toString('utf8')), modified: stat.mtimeMs } : undefined;
     }
     catch {
         return undefined;
@@ -28,6 +29,7 @@ export function readJson(file, cap) {
             closeSync(fd);
     }
 }
+export function readJson(file, cap) { return readJsonSnapshot(file, cap)?.value; }
 export function fingerprint(salt) {
     const memo = new Map();
     return (provider, value) => {
@@ -43,20 +45,22 @@ export function fingerprint(salt) {
     };
 }
 export function store(stateDir) {
-    const path = join(stateDir, 'plans-v1.json');
+    if (typeof stateDir !== 'string' || !isAbsolute(stateDir) || /[\0\r\n]/.test(stateDir))
+        throw new UsageError();
+    const path = join(stateDir, 'plans-v2.json');
     function load() {
         const saved = readJson(path, 256 * 1024);
         const plans = {};
         if (!record(saved) || !record(saved.plans))
             return plans;
-        for (const id of ['claude', 'codex', 'opencode', 'zai']) {
+        for (const id of ['claude', 'codex', 'opencode', 'zai', 'copilot', 'grok', 'minimax', 'gemini', 'kimi']) {
             const entries = saved.plans[id];
             if (!record(entries))
                 continue;
             const readings = Object.create(null);
             for (const [fp, r] of Object.entries(entries)) {
                 if (/^[a-f0-9]{64}$/.test(fp) && record(r) && typeof r.at === 'number' && Number.isFinite(r.at))
-                    readings[fp] = { at: r.at, raw: r.raw };
+                    readings[fp] = { at: r.at, windows: safeWindows(id, r.windows) };
             }
             plans[id] = readings;
         }
@@ -65,13 +69,15 @@ export function store(stateDir) {
     return {
         get: (id, fp) => load()[id]?.[fp],
         put(id, fp, reading) {
+            if (!/^[a-f0-9]{64}$/.test(fp) || !Number.isFinite(reading.at))
+                return;
             const temporary = `${path}.${randomUUID()}.tmp`;
             try {
                 const plans = load();
                 const entries = plans[id] ?? {};
                 if (reading.at < (entries[fp]?.at ?? -Infinity))
                     return;
-                entries[fp] = reading;
+                entries[fp] = { at: reading.at, windows: safeWindows(id, reading.windows) };
                 plans[id] = entries;
                 const body = JSON.stringify({ plans });
                 if (Buffer.byteLength(body) > 256 * 1024)
@@ -91,3 +97,21 @@ export function store(stateDir) {
         },
     };
 }
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export function safeWindows(provider, raw) {
+    return (Array.isArray(raw) ? raw : []).slice(0, 64).flatMap((value) => {
+        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent))
+            return [];
+        return [{ provider, kind: value.kind, usedPercent: Math.max(0, Math.min(100, value.usedPercent)),
+                ...(typeof value.minutes === 'number' && Number.isFinite(value.minutes) && value.minutes > 0 ? { minutes: value.minutes } : {}),
+                ...(typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) ? { resetsAt: value.resetsAt } : {}),
+                ...(value.limited === true ? { limited: true } : {}),
+                ...(typeof value.limit === 'string' && value.limit.length <= 80 ? { limit: value.limit } : {}) }];
+    });
+}
+export function memoryUsageStore() {
+    const readings = new Map();
+    return { get: (provider, account) => { const r = readings.get(`${provider}\0${account}`); return r ? { at: r.at, windows: safeWindows(provider, r.windows) } : undefined; },
+        put: (provider, account, reading) => { const key = `${provider}\0${account}`; if (reading.at >= (readings.get(key)?.at ?? -Infinity))
+            readings.set(key, { at: reading.at, windows: safeWindows(provider, reading.windows) }); } };
+}

package/dist/types.d.ts

@@ -1,18 +1,44 @@
-export type Provider = 'claude' | 'codex' | 'opencode' | 'zai';
-/** Claude's credential adapter belongs to the host; only its parser ships here. */
+export type Provider = 'claude' | 'codex' | 'opencode' | 'zai' | 'copilot' | 'grok' | 'minimax' | 'gemini' | 'kimi';
+/** Host-owned identity makes readings survive token renewal. Tokens never become stored identities. */
+type Identity = {
+    accountId?: string;
+};
 export type Source = {
     provider: 'codex';
     bin: string;
     home: string;
     env?: Record<string, string>;
 } | {
-    provider: 'opencode';
-    key: string;
-} | {
-    provider: 'zai';
+    provider: 'codex';
+    access: string;
+    accountId: string;
+} | ({
+    provider: 'claude';
+    access: string;
+    accountUuid?: string;
+} & Identity) | ({
+    provider: 'claude';
+    accountUuid: string;
+    read: ClaudeReader;
+    connected?: () => boolean;
+}) | {
+    provider: 'claude';
+    credentialsFile: string;
+    configFile?: string;
+    statuslineFile?: string;
+} | ({
+    provider: 'opencode' | 'zai';
     key: string;
-};
+} & Identity) | ({
+    provider: 'copilot' | 'grok' | 'minimax' | 'kimi';
+    access: string;
+} & Identity) | ({
+    provider: 'gemini';
+    access: string;
+    project?: string;
+} & Identity);
 export type Kind = 'session' | 'weekly' | 'monthly' | 'rolling' | 'custom';
+/** All reset times are epoch milliseconds in 0.2.0. */
 export type Window = {
     provider: Provider;
     kind: Kind;
@@ -29,11 +55,46 @@ export type Reading = {
     at: number;
     code?: Code;
 };
+export type Room = {
+    left: number;
+    span: 'session' | 'week' | 'month' | 'tightest';
+    resetsAt?: number;
+    at: number;
+} | {
+    left: 'unknown';
+    at?: number;
+};
 export type ReadOptions = {
     nowMs?: number;
 };
+export type SourceAnswer = {
+    raw?: unknown;
+    code?: Code;
+    retryAfterMs?: number;
+};
+/** The app owns credential reads/refresh and sends its own requests through this seam. */
+export type ClaudeReader = (options: {
+    nowMs: number;
+    signal: AbortSignal;
+}) => Promise<SourceAnswer>;
+export type StoredReading = {
+    at: number;
+    windows: Window[];
+};
+export interface UsageStore {
+    get(provider: Provider, account: string): StoredReading | undefined;
+    put(provider: Provider, account: string, reading: StoredReading): void;
+}
+export interface BackoffPolicy {
+    get(provider: Provider, account: string): number | undefined;
+    set(provider: Provider, account: string, untilMs: number): void;
+    /** Retry-After duration to wait; default at least five minutes. */
+    delayMs?(retryAfterMs: number | undefined): number;
+}
 export type UsageOptions = {
-    stateDir: string;
+    stateDir?: string;
+    store?: UsageStore;
+    backoff?: BackoffPolicy;
     salt?: string;
     fetch?: typeof fetch;
     now?: () => number;
@@ -42,6 +103,7 @@ export interface Usage {
     read(source: Source, options?: ReadOptions): Promise<Reading>;
     lastKnown(source: Source, options?: ReadOptions): Reading | undefined;
     connected(source: Source): boolean;
+    /** Stable identity fingerprint, absent for an opaque token without a host-supplied id. */
     account(source: Source): string | undefined;
 }
 export declare class UsageError extends Error {
@@ -49,3 +111,4 @@ export declare class UsageError extends Error {
     name: string;
     constructor();
 }
+export {};

package/dist/windows.d.ts

@@ -1,5 +1,6 @@
-import type { Window } from './types.ts';
+import type { Kind, Provider, Window } from './types.ts';
 export declare const record: (v: unknown) => v is Record<string, unknown>;
+export declare function window(provider: Provider, kind: Kind, used: unknown, minutes?: number, resetsAt?: number, limited?: boolean, limit?: string): Window[];
 /** Accepts both the statusline envelope and the provider's usage payload. */
 export declare function claudeWindows(raw: unknown): Window[];
 /** Accepts the `usage` member; monthly length is deliberately absent. */

package/dist/windows.js

@@ -1,6 +1,6 @@
 export const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const obj = (v) => record(v) ? v : {};
-function window(provider, kind, used, minutes, resetsAt, limited = false, limit) {
+export function window(provider, kind, used, minutes, resetsAt, limited = false, limit) {
     if (typeof used !== 'number' || !Number.isFinite(used))
         return [];
     return [{ provider, kind, usedPercent: Math.max(0, Math.min(100, used)),
@@ -12,7 +12,7 @@ export function claudeWindows(raw) {
     const source = obj(obj(raw).rate_limits ?? raw);
     return ['five_hour', 'seven_day'].flatMap((id) => {
         const w = obj(source[id]);
-        return window('claude', id === 'five_hour' ? 'session' : 'weekly', Number.isFinite(w.utilization) ? w.utilization : w.used_percentage, id === 'five_hour' ? 300 : 10080, typeof w.resets_at === 'number' ? w.resets_at : Date.parse(String(w.resets_at)) / 1000);
+        return window('claude', id === 'five_hour' ? 'session' : 'weekly', Number.isFinite(w.utilization) ? w.utilization : w.used_percentage, id === 'five_hour' ? 300 : 10080, typeof w.resets_at === 'number' ? w.resets_at * 1000 : Date.parse(String(w.resets_at)));
     });
 }
 /** Accepts the `usage` member; monthly length is deliberately absent. */
@@ -21,7 +21,7 @@ export function goWindows(raw) {
         const w = obj(obj(raw)[kind]);
         if (typeof w.percent !== 'number' || w.percent < 0 || !['ok', 'rate-limited'].includes(String(w.status)))
             return [];
-        return window('opencode', kind, w.percent, kind === 'monthly' ? undefined : kind === 'weekly' ? 10080 : 300, Date.parse(String(w.resetsAt)) / 1000, w.status === 'rate-limited');
+        return window('opencode', kind, w.percent, kind === 'monthly' ? undefined : kind === 'weekly' ? 10080 : 300, Date.parse(String(w.resetsAt)), w.status === 'rate-limited');
     });
 }
 /** Accepts the `data.limits` member; unknown bucket sizes are skipped. */
@@ -31,7 +31,7 @@ export function zaiWindows(raw) {
         const key = `${w.unit}:${w.number}`;
         if (key !== '3:5' && key !== '6:1')
             return [];
-        return window('zai', key === '3:5' ? 'session' : 'weekly', w.percentage, key === '3:5' ? 300 : 10080, Number(w.nextResetTime) / 1000);
+        return window('zai', key === '3:5' ? 'session' : 'weekly', w.percentage, key === '3:5' ? 300 : 10080, typeof w.nextResetTime === 'number' ? w.nextResetTime : undefined);
     });
 }
 export function codexWindows(result) {
@@ -45,7 +45,7 @@ export function codexWindows(result) {
         const rows = ['primary', 'secondary'].flatMap((key) => {
             const w = obj(raw[key]);
             const m = typeof w.windowDurationMins === 'number' && w.windowDurationMins > 0 && Number.isFinite(w.windowDurationMins) ? w.windowDurationMins : undefined;
-            return window('codex', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', w.usedPercent, m, typeof w.resetsAt === 'number' ? w.resetsAt : undefined, false, name.toLowerCase() === 'codex' ? undefined : name);
+            return window('codex', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', w.usedPercent, m, typeof w.resetsAt === 'number' ? w.resetsAt * 1000 : undefined, false, name.toLowerCase() === 'codex' ? undefined : name);
         }).sort((a, b) => (a.minutes ?? 0) - (b.minutes ?? 0));
         return rows.length ? [rows] : [];
     });

package/package.json

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