@byokit/usage 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Read subscription usage windows per provider and per account, with last-good readings and bounded provider reads.
+
+## 0.1.0
+
+- Read subscription usage windows per provider and per account, with last-good readings and bounded provider reads.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,25 @@
+# @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.
+
+```ts
+import { usage } 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' };
+const reading = await reader.read(source);
+for (const window of reading.windows) console.log(window.kind, 100 - window.usedPercent);
+```
+
+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 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.
+
+`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.
+
+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.
+
+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.
+
+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.
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type Usage, type UsageOptions } from './types.ts';
+export * from './types.ts';
+export { claudeWindows, codexWindows, goWindows, zaiWindows, type CodexRateLimitResult } from './windows.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;

package/dist/index.js

@@ -0,0 +1,119 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { codexUsage, providerGet } from "./providers.js";
+import { fingerprint, readJson, store } from "./store.js";
+import { codexWindows, goWindows, record, zaiWindows } from "./windows.js";
+import { UsageError } from "./types.js";
+export * from "./types.js";
+export { claudeWindows, codexWindows, goWindows, zaiWindows } from "./windows.js";
+export { WORDS, words, usageWords } from "./words.js";
+const validText = (v) => typeof v === 'string' && !v.includes('\0');
+function validate(source) {
+    if (!record(source))
+        throw new UsageError();
+    if (source.provider === 'codex') {
+        if (!validText(source.bin) || !isAbsolute(source.bin) || !validText(source.home) || !isAbsolute(source.home))
+            throw new UsageError();
+        if (source.env !== undefined && (!record(source.env) || Object.entries(source.env).some(([k, v]) => !k || k.includes('=') || !validText(k) || !validText(v))))
+            throw new UsageError();
+    }
+    else if (!['opencode', 'zai'].includes(source.provider) || !validText(source.key) || source.key.length > 16384)
+        throw new UsageError();
+}
+/** One reader owns per-account backoff and concurrent-read deduplication. */
+export function usage(options) {
+    if (!validText(options.stateDir) || !isAbsolute(options.stateDir))
+        throw new UsageError();
+    const disk = store(options.stateDir);
+    const fp = fingerprint(options.salt ?? 'byokit/usage/account');
+    const backoff = new Map();
+    const inFlight = new Map();
+    const attempts = new Map();
+    const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
+    function connected(source) {
+        validate(source);
+        if (source.provider !== 'codex')
+            return source.key.trim() !== '';
+        try {
+            accessSync(source.bin, constants.X_OK);
+            return statSync(source.bin).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    function account(source) {
+        validate(source);
+        if (source.provider !== 'codex')
+            return source.key.trim() ? fp(source.provider, source.key) : undefined;
+        const raw = readJson(join(source.home, 'auth.json'), 64 * 1024);
+        const tokens = record(raw) && record(raw.tokens) ? raw.tokens : undefined;
+        const value = typeof tokens?.account_id === 'string' ? tokens.account_id : `codex-home\0${source.home}`;
+        return value !== '' && value.length <= 16384 ? fp('codex', value) : undefined;
+    }
+    const windows = (source, raw) => source.provider === 'codex' ? codexWindows(raw) : source.provider === 'opencode' ? goWindows(raw) : zaiWindows(raw);
+    function lastKnown(source, opts) {
+        if (!connected(source))
+            return undefined;
+        const key = account(source);
+        if (!key)
+            return undefined;
+        const stored = disk.get(source.provider, key);
+        const clock = now(opts);
+        if (!stored || clock < stored.at || clock - stored.at > 86_400_000)
+            return undefined;
+        const rows = windows(source, stored.raw);
+        return rows.length ? { provider: source.provider, windows: rows, at: stored.at } : undefined;
+    }
+    async function read(source, opts) {
+        validate(source);
+        const clock = now(opts);
+        const empty = (code) => ({ provider: source.provider, windows: [], at: clock, code });
+        if (!connected(source))
+            return empty('not-connected');
+        const key = account(source);
+        if (!key)
+            return empty('not-connected');
+        const identity = `${source.provider}\0${key}`;
+        const previous = lastKnown(source, { nowMs: clock });
+        if (previous && clock - previous.at < 60_000)
+            return previous;
+        if ((backoff.get(identity) ?? 0) > clock)
+            return previous ? { ...previous, code: 'rate-limited' } : empty('rate-limited');
+        const pending = inFlight.get(identity);
+        if (pending)
+            return pending;
+        const attempt = attempts.get(identity);
+        if (attempt && clock >= attempt.at && clock - attempt.at < 60_000)
+            return previous ? { ...previous, code: attempt.answer.code } : empty(attempt.answer.code ?? 'unavailable');
+        const task = (async () => {
+            let answer;
+            try {
+                answer = source.provider === 'codex' ? await codexUsage(source) : await providerGet(source, options.fetch ?? globalThis.fetch, clock);
+            }
+            catch {
+                answer = { code: 'unavailable' };
+            }
+            if (answer.until !== undefined)
+                backoff.set(identity, answer.until);
+            const rows = windows(source, answer.raw);
+            if (!answer.code && !rows.length)
+                answer = { code: 'incomplete' };
+            // Do not keep a source key or a raw payload in a retry map.
+            attempts.set(identity, { at: clock, answer: { code: answer.code } });
+            if (rows.length && !answer.code) {
+                disk.put(source.provider, key, { at: clock, raw: answer.raw });
+                return { provider: source.provider, windows: rows, at: clock };
+            }
+            return previous ? { ...previous, code: answer.code } : empty(answer.code ?? 'unavailable');
+        })();
+        inFlight.set(identity, task);
+        try {
+            return await task;
+        }
+        finally {
+            inFlight.delete(identity);
+        }
+    }
+    return { read, lastKnown, connected, account };
+}

package/dist/providers.d.ts

@@ -0,0 +1,12 @@
+import type { Code, Source } from './types.ts';
+export interface Answer {
+    raw?: unknown;
+    code?: Code;
+    until?: number;
+}
+export declare function providerGet(source: Extract<Source, {
+    key: string;
+}>, fetcher: typeof fetch, nowMs: number): Promise<Answer>;
+export declare function codexUsage(source: Extract<Source, {
+    provider: 'codex';
+}>): Promise<Answer>;

package/dist/providers.js

@@ -0,0 +1,109 @@
+import { spawn } from 'node:child_process';
+import { record } from "./windows.js";
+export async function providerGet(source, fetcher, nowMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    try {
+        const url = source.provider === 'opencode' ? 'https://opencode.ai/zen/go/v1/usage' : 'https://api.z.ai/api/monitor/usage/quota/limit';
+        const response = await fetcher(url, { headers: { accept: 'application/json', authorization: `Bearer ${source.key}` }, redirect: 'error', signal: controller.signal });
+        if (response.status === 429) {
+            const retry = response.headers.get('retry-after');
+            const seconds = Number(retry);
+            const delay = retry !== null && Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retry ?? '') - nowMs;
+            controller.abort();
+            return { code: 'rate-limited', until: nowMs + Math.max(300_000, Number.isFinite(delay) ? delay : 0) };
+        }
+        if (response.status !== 200) {
+            controller.abort();
+            return { code: response.status === 401 ? 'auth' : response.status === 403 ? 'no-plan' : 'unavailable' };
+        }
+        if (!response.body)
+            return { code: 'incomplete' };
+        const chunks = [];
+        let size = 0;
+        const reader = response.body.getReader();
+        for (;;) {
+            const { value: chunk, done } = await reader.read();
+            if (done)
+                break;
+            size += chunk.byteLength;
+            if (size > 64 * 1024) {
+                controller.abort();
+                return { code: 'incomplete' };
+            }
+            chunks.push(chunk);
+        }
+        let raw;
+        try {
+            raw = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            return { code: 'incomplete' };
+        }
+        if (!record(raw))
+            return { code: 'incomplete' };
+        if (source.provider === 'zai' && raw.success === false)
+            return { code: 'no-plan' };
+        return { raw: source.provider === 'opencode' ? raw.usage : record(raw.data) ? raw.data.limits : undefined };
+    }
+    catch {
+        return { code: 'unavailable' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function codexUsage(source) {
+    return new Promise((resolve) => {
+        const child = spawn(source.bin, ['app-server'], { env: { ...source.env, CODEX_HOME: source.home }, stdio: ['pipe', 'pipe', 'ignore'] });
+        let buffer = '';
+        let bytes = 0;
+        let settled = false;
+        let escalation;
+        const finish = (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill('SIGTERM');
+                escalation = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL'); }, 1000);
+            }
+            resolve(answer);
+        };
+        const timer = setTimeout(() => finish({ code: 'unavailable' }), 20_000);
+        child.once('error', () => finish({ code: 'unavailable' }));
+        child.once('close', () => { clearTimeout(escalation); finish({ code: 'unavailable' }); });
+        child.stdin.on('error', () => finish({ code: 'unavailable' }));
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            if (settled)
+                return;
+            bytes += Buffer.byteLength(chunk);
+            buffer += chunk;
+            if (bytes > 64 * 1024) {
+                finish({ code: 'incomplete' });
+                return;
+            }
+            for (;;) {
+                const newline = buffer.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                try {
+                    const message = JSON.parse(line);
+                    if (!record(message))
+                        continue;
+                    if (message.id === 1)
+                        child.stdin.write(`${JSON.stringify({ id: 2, method: 'account/rateLimits/read', params: {} })}\n`);
+                    if (message.id === 2)
+                        finish(record(message.result) ? { raw: message.result } : { code: 'incomplete' });
+                }
+                catch { /* Non-JSON output is bounded and ignored. */ }
+            }
+        });
+        child.stdin.write(`${JSON.stringify({ id: 1, method: 'initialize', params: { clientInfo: { name: 'byokit', version: '1' } } })}\n`);
+    });
+}

package/dist/store.d.ts

@@ -0,0 +1,12 @@
+import type { Provider } from './types.ts';
+export interface Stored {
+    at: number;
+    raw: unknown;
+}
+/** Bounded regular files only; do not follow credential or state symlinks. */
+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;
+};

package/dist/store.js

@@ -0,0 +1,93 @@
+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 { record } from "./windows.js";
+/** Bounded regular files only; do not follow credential or state symlinks. */
+export function readJson(file, cap) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > cap)
+            return undefined;
+        const body = Buffer.alloc(cap + 1);
+        let length = 0;
+        while (length <= cap) {
+            const count = readSync(fd, body, length, cap + 1 - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        return length <= cap ? JSON.parse(body.subarray(0, length).toString('utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+export function fingerprint(salt) {
+    const memo = new Map();
+    return (provider, value) => {
+        const key = createHash('sha256').update(`${provider}\0${value}`).digest('hex');
+        let fp = memo.get(key);
+        if (!fp) {
+            fp = scryptSync(value, `${salt}/${provider}`, 32, { N: 16384, r: 8, p: 1 }).toString('hex');
+            if (memo.size >= 32)
+                memo.clear();
+            memo.set(key, fp);
+        }
+        return fp;
+    };
+}
+export function store(stateDir) {
+    const path = join(stateDir, 'plans-v1.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']) {
+            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 };
+            }
+            plans[id] = readings;
+        }
+        return plans;
+    }
+    return {
+        get: (id, fp) => load()[id]?.[fp],
+        put(id, fp, reading) {
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                const plans = load();
+                const entries = plans[id] ?? {};
+                if (reading.at < (entries[fp]?.at ?? -Infinity))
+                    return;
+                entries[fp] = reading;
+                plans[id] = entries;
+                const body = JSON.stringify({ plans });
+                if (Buffer.byteLength(body) > 256 * 1024)
+                    return;
+                mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+                chmodSync(stateDir, 0o700);
+                writeFileSync(temporary, body, { mode: 0o600, flag: 'wx' });
+                renameSync(temporary, path);
+            }
+            catch { /* Persistence failure never exposes provider data as an error. */ }
+            finally {
+                try {
+                    unlinkSync(temporary);
+                }
+                catch { /* already renamed or never created */ }
+            }
+        },
+    };
+}

package/dist/testing/contract.d.ts

@@ -0,0 +1,20 @@
+import type { Reading, Source, Usage } from '../types.ts';
+export type UsageContractTestFn = (name: string, fn: (t: {
+    skip(message?: string): void;
+}) => void | Promise<void>) => unknown;
+export interface UsageContractBench {
+    usage: Usage;
+    source: Source;
+    expected: Reading['windows'];
+    nowMs: number;
+    restart(): Usage;
+    fake?: {
+        fail(): void;
+        disconnect(): void;
+        calls(): number;
+    };
+    cleanup?(): void | Promise<void>;
+}
+export declare function usageContract(make: () => UsageContractBench | Promise<UsageContractBench>, options?: {
+    test?: UsageContractTestFn;
+} | UsageContractTestFn): void;

package/dist/testing/contract.js

@@ -0,0 +1,47 @@
+import { test as nodeTest } from 'node:test';
+import assert from 'node:assert/strict';
+export function usageContract(make, options = {}) {
+    const test = typeof options === 'function' ? options : options.test ?? nodeTest;
+    test('usage contract: concurrent reads, freshness floor and restart keep one account reading', async () => {
+        const b = await make();
+        try {
+            const [a, duplicate] = await Promise.all([b.usage.read(b.source, { nowMs: b.nowMs }), b.usage.read(b.source, { nowMs: b.nowMs })]);
+            assert.deepEqual(a.windows, b.expected);
+            assert.deepEqual(a, duplicate);
+            assert.equal(a.code, undefined);
+            const count = b.fake?.calls();
+            assert.deepEqual(await b.usage.read(b.source, { nowMs: b.nowMs + 59_999 }), a);
+            if (count !== undefined) {
+                assert.equal(count, 1);
+                assert.equal(b.fake.calls(), count);
+            }
+            assert.deepEqual(b.restart().lastKnown(b.source, { nowMs: b.nowMs + 60_000 }), a);
+            assert.equal(b.restart().lastKnown(b.source, { nowMs: b.nowMs + 86_400_001 }), undefined);
+        }
+        finally {
+            await b.cleanup?.();
+        }
+    });
+    test('usage contract: failed reads stand on the last good reading only while connected', async (t) => {
+        const b = await make();
+        try {
+            if (!b.fake) {
+                t.skip('Requires scripted failure and disconnect.');
+                return;
+            }
+            const a = await b.usage.read(b.source, { nowMs: b.nowMs });
+            b.fake.fail();
+            const failed = await b.usage.read(b.source, { nowMs: b.nowMs + 60_000 });
+            assert.deepEqual(failed.windows, a.windows);
+            assert.equal(failed.at, a.at);
+            assert.ok(failed.code);
+            b.fake.disconnect();
+            assert.equal(b.usage.connected(b.source), false);
+            assert.equal(b.usage.lastKnown(b.source, { nowMs: b.nowMs + 61_000 }), undefined);
+            assert.equal((await b.usage.read(b.source, { nowMs: b.nowMs + 61_000 })).code, 'not-connected');
+        }
+        finally {
+            await b.cleanup?.();
+        }
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,37 @@
+export { usageContract, type UsageContractBench, type UsageContractTestFn } from './contract.ts';
+export interface FakeAnswer {
+    status?: number;
+    body?: unknown;
+    retryAfter?: string;
+    text?: string;
+}
+/** Deterministic HTTP responses, never an endpoint. Calls preserve the exact request. */
+export declare function fakeFetch(initial?: FakeAnswer[]): {
+    fetch: typeof globalThis.fetch;
+    calls: {
+        url: string;
+        init?: RequestInit;
+    }[];
+    push: (...answers: FakeAnswer[]) => void;
+};
+export interface FakeCodexScript {
+    raw?: unknown;
+    corrupt?: boolean;
+    flood?: boolean;
+    hang?: boolean;
+    ignoreTerm?: boolean;
+}
+export interface FakeCodex {
+    bin: string;
+    script(value: FakeCodexScript): void;
+    invocations(): {
+        argv: string[];
+        env: Record<string, string>;
+        requests: unknown[];
+    }[];
+}
+/** Writes a fake app-server only under the caller's scratch directory. */
+export declare function fakeCodex(options: {
+    dir: string;
+    raw?: unknown;
+}): FakeCodex;

package/dist/testing/index.js

@@ -0,0 +1,48 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export { usageContract } from "./contract.js";
+/** Deterministic HTTP responses, never an endpoint. Calls preserve the exact request. */
+export function fakeFetch(initial = []) {
+    const queue = [...initial];
+    const calls = [];
+    const fetch = async (url, init) => {
+        calls.push({ url: String(url), init });
+        const answer = queue.shift() ?? { status: 503 };
+        return new Response(answer.text ?? JSON.stringify(answer.body ?? {}), { status: answer.status ?? 200,
+            headers: answer.retryAfter === undefined ? {} : { 'retry-after': answer.retryAfter } });
+    };
+    return { fetch, calls, push: (...answers) => { queue.push(...answers); } };
+}
+/** Writes a fake app-server only under the caller's scratch directory. */
+export function fakeCodex(options) {
+    mkdirSync(options.dir, { recursive: true });
+    const bin = join(options.dir, 'codex');
+    const script = join(options.dir, 'script.json');
+    const log = join(options.dir, 'calls.jsonl');
+    writeFileSync(script, JSON.stringify({ raw: options.raw }));
+    writeFileSync(log, '');
+    writeFileSync(bin, `#!${process.execPath}
+const fs = require('node:fs');
+const config = JSON.parse(fs.readFileSync(${JSON.stringify(script)}, 'utf8'));
+const call = { argv: process.argv.slice(2), env: process.env, requests: [] };
+if (config.ignoreTerm) process.on('SIGTERM', () => {});
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+  for (;;) {
+    const i = buffer.indexOf('\\n'); if (i < 0) break;
+    const request = JSON.parse(buffer.slice(0, i)); buffer = buffer.slice(i + 1);
+    call.requests.push(request);
+    if (request.id === 1) console.log(JSON.stringify({ id: 1, result: {} }));
+    if (request.id === 2) {
+      fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify(call) + '\\n');
+      if (config.hang) continue;
+      if (config.flood) { console.log('x'.repeat(65537)); continue; }
+      console.log(config.corrupt ? JSON.stringify({ id: 2, result: null }) : JSON.stringify({ id: 2, result: config.raw }));
+    }
+  }
+});
+`, { mode: 0o755 });
+    return { bin, script: (value) => writeFileSync(script, JSON.stringify(value)), invocations: () => readFileSync(log, 'utf8').split('\n').filter(Boolean).map((s) => JSON.parse(s)) };
+}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export type Provider = 'claude' | 'codex' | 'opencode' | 'zai';
+/** Claude's credential adapter belongs to the host; only its parser ships here. */
+export type Source = {
+    provider: 'codex';
+    bin: string;
+    home: string;
+    env?: Record<string, string>;
+} | {
+    provider: 'opencode';
+    key: string;
+} | {
+    provider: 'zai';
+    key: string;
+};
+export type Kind = 'session' | 'weekly' | 'monthly' | 'rolling' | 'custom';
+export type Window = {
+    provider: Provider;
+    kind: Kind;
+    limit?: string;
+    usedPercent: number;
+    minutes?: number;
+    resetsAt?: number;
+    limited?: boolean;
+};
+export type Code = 'not-connected' | 'expired' | 'auth' | 'no-plan' | 'rate-limited' | 'unavailable' | 'incomplete';
+export type Reading = {
+    provider: Provider;
+    windows: Window[];
+    at: number;
+    code?: Code;
+};
+export type ReadOptions = {
+    nowMs?: number;
+};
+export type UsageOptions = {
+    stateDir: string;
+    salt?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+};
+export interface Usage {
+    read(source: Source, options?: ReadOptions): Promise<Reading>;
+    lastKnown(source: Source, options?: ReadOptions): Reading | undefined;
+    connected(source: Source): boolean;
+    account(source: Source): string | undefined;
+}
+export declare class UsageError extends Error {
+    readonly code = "bad-source";
+    name: string;
+    constructor();
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+export class UsageError extends Error {
+    code = 'bad-source';
+    name = 'UsageError';
+    constructor() { super('The app supplied an invalid usage source.'); }
+}

package/dist/windows.d.ts

@@ -0,0 +1,14 @@
+import type { Window } from './types.ts';
+export declare const record: (v: unknown) => v is Record<string, unknown>;
+/** 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. */
+export declare function goWindows(raw: unknown): Window[];
+/** Accepts the `data.limits` member; unknown bucket sizes are skipped. */
+export declare function zaiWindows(raw: unknown): Window[];
+/** Typed pass-through of the app-server rate-limit result. */
+export interface CodexRateLimitResult {
+    rateLimitsByLimitId?: Record<string, unknown>;
+    rateLimits?: unknown;
+}
+export declare function codexWindows(result: CodexRateLimitResult | undefined): Window[];

package/dist/windows.js

@@ -0,0 +1,55 @@
+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) {
+    if (typeof used !== 'number' || !Number.isFinite(used))
+        return [];
+    return [{ provider, kind, usedPercent: Math.max(0, Math.min(100, used)),
+            ...(minutes !== undefined && Number.isFinite(minutes) && minutes > 0 ? { minutes } : {}),
+            ...(Number.isFinite(resetsAt) ? { resetsAt } : {}), ...(limited ? { limited: true } : {}), ...(limit ? { limit } : {}) }];
+}
+/** Accepts both the statusline envelope and the provider's usage payload. */
+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);
+    });
+}
+/** Accepts the `usage` member; monthly length is deliberately absent. */
+export function goWindows(raw) {
+    return ['rolling', 'weekly', 'monthly'].flatMap((kind) => {
+        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');
+    });
+}
+/** Accepts the `data.limits` member; unknown bucket sizes are skipped. */
+export function zaiWindows(raw) {
+    return (Array.isArray(raw) ? raw : []).flatMap((value) => {
+        const w = obj(value);
+        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);
+    });
+}
+export function codexWindows(result) {
+    const limits = Object.values(obj(result?.rateLimitsByLimitId));
+    if (!limits.length && result?.rateLimits !== undefined)
+        limits.push(result.rateLimits);
+    const groups = limits.flatMap((raw) => {
+        if (!record(raw))
+            return [];
+        const name = String(raw.limitName ?? raw.limitId ?? 'Codex').replace(/[^\x20-\x7e]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'Codex';
+        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);
+        }).sort((a, b) => (a.minutes ?? 0) - (b.minutes ?? 0));
+        return rows.length ? [rows] : [];
+    });
+    const chosen = groups.flat().sort((a, b) => b.usedPercent - a.usedPercent).slice(0, 8);
+    return groups.map((rows, ordinal) => ({ rows: rows.filter((w) => chosen.includes(w)), ordinal }))
+        .filter((g) => g.rows.length).sort((a, b) => Math.max(...b.rows.map((w) => w.usedPercent)) - Math.max(...a.rows.map((w) => w.usedPercent)) || a.ordinal - b.ordinal).flatMap((g) => g.rows);
+}

package/dist/words.d.ts

@@ -0,0 +1,8 @@
+import WORDS from './words.json' with { type: 'json' };
+import type { Code } from './types.ts';
+export { WORDS };
+export type WordKey = keyof typeof WORDS;
+export declare const words: (key: WordKey, vars?: Record<string, string>) => string;
+export declare const usageWords: (code: Code, vars: {
+    name: string;
+}) => string;

package/dist/words.js

@@ -0,0 +1,4 @@
+import WORDS from './words.json' with { type: 'json' };
+export { WORDS };
+export const words = (key, vars = {}) => WORDS[key].replace(/\{(\w+)\}/g, (_, k) => vars[k] ?? `{${k}}`);
+export const usageWords = (code, vars) => words(`code.${code}`, vars);

package/dist/words.json

@@ -0,0 +1,9 @@
+{
+    "code.not-connected": "{name} isn't signed in on this computer.",
+    "code.expired": "{name} needs a fresh sign-in in its own app.",
+    "code.auth": "{name} turned this sign-in down. Sign in again in its own app.",
+    "code.no-plan": "This {name} account has no plan with limits.",
+    "code.rate-limited": "{name} asked us to wait. Showing the last reading.",
+    "code.unavailable": "{name} didn't answer. Trying again shortly.",
+    "code.incomplete": "{name} answered in a way we can't read yet."
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@byokit/usage",
+  "version": "0.1.0",
+  "description": "Read subscription usage windows per provider and account.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/usage"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}