@allixsenos/asu 0.3.0

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { UsageCache } from './cache.js';
+import { createLocalContext, homePath } from './local.js';
+import { loadProviders } from './registry.js';
+import { UsageService } from './service.js';
+import { render, tableWraps } from './output.js';
+import { version } from './version.js';
+export const help = `asu — agent subscription usage
+
+Usage: asu [usage] [options]
+
+  --format plain|table|json   Output format (table in a terminal, plain when piped or when the table would wrap)
+  --json                     Shortcut for --format json
+  --plain                    Shortcut for --format plain
+  --table                    Shortcut for --format table
+  --utc                      Print full UTC timestamps instead of times relative to now
+  --provider <id>             Select provider; repeat or use comma-separated IDs
+  --all                      Include providers with no detected install or credentials
+  --fresh                    Fetch again, bypassing the five-minute cache
+  --no-cache                 Do not read or write the persistent cache
+  --cache-dir <path>          Override the private usage cache directory
+  --plugin <path-or-package>  Load a trusted provider plugin; repeatable
+  --help, -h                 Show this help
+  --version, -v              Show version
+
+Providers: claude, codex, copilot, cursor, zai, grok, kimi, minimax
+Credentials are read-only. Sign in and refresh tokens through the provider CLI.
+JSON has schemaVersion: 1. Diagnostics go to stderr; stdout contains only the report.
+Exit codes: 0 at least one available provider; 1 none available; 2 invocation error.
+`;
+export async function run(args = process.argv.slice(2)) {
+    let format = process.stdout.isTTY ? 'table' : 'plain';
+    try {
+        const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+                format: { type: 'string' }, json: { type: 'boolean' }, plain: { type: 'boolean' }, table: { type: 'boolean' }, utc: { type: 'boolean' },
+                provider: { type: 'string', multiple: true }, all: { type: 'boolean' }, fresh: { type: 'boolean' },
+                'no-cache': { type: 'boolean' }, 'cache-dir': { type: 'string' }, plugin: { type: 'string', multiple: true },
+                help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+            } });
+        if (values.help) {
+            process.stdout.write(help);
+            return 0;
+        }
+        if (values.version) {
+            process.stdout.write(`${version}\n`);
+            return 0;
+        }
+        if (positionals.length > 1 || positionals.length === 1 && positionals[0] !== 'usage')
+            throw new Error('Expected asu [usage]. See --help.');
+        const formats = [values.format, values.json ? 'json' : undefined, values.plain ? 'plain' : undefined, values.table ? 'table' : undefined].filter(Boolean);
+        if (formats.length > 1 || formats.some(value => !['plain', 'table', 'json'].includes(value)))
+            throw new Error('Choose one output format: plain, table, or json.');
+        const explicit = formats.length > 0;
+        format = formats[0] ?? format;
+        const providers = await loadProviders(values.plugin);
+        const providerIds = values.provider?.flatMap(value => value.split(',')).map(value => value.trim());
+        if (providerIds?.some(id => !providers.some(provider => provider.id === id)))
+            throw new Error('Unknown provider ID. See --help for built-ins.');
+        const local = createLocalContext();
+        const cacheRoot = homePath(local, local.env.XDG_CACHE_HOME, '.cache');
+        const directory = homePath(local, values['cache-dir'] ?? local.env.ASU_CACHE_DIR, `${cacheRoot}/asu`);
+        const service = new UsageService(providers, { local, cache: new UsageCache(values['no-cache'] ? undefined : directory) });
+        const report = await service.collect({ providerIds, fresh: values.fresh });
+        if (!values.all && !providerIds?.length)
+            report.providers = report.providers.filter(provider => provider.installed || provider.credentialsPresent || provider.reason?.code !== 'missing_credentials');
+        const options = { columns: process.stdout.columns, utc: values.utc };
+        // A table that must wrap in a narrow terminal is harder to read than plain text.
+        if (format === 'table' && !explicit && tableWraps(report, options))
+            format = 'plain';
+        process.stdout.write(render(report, format, options));
+        return report.providers.some(provider => provider.availability === 'available') ? 0 : 1;
+    }
+    catch (error) {
+        // All errors exposed here are ours; do not print plugin/import/runtime exception messages.
+        const messages = ['Expected asu [usage]. See --help.', 'Choose one output format: plain, table, or json.',
+            'Unknown provider ID. See --help for built-ins.', 'Could not load a provider plugin. Check its path, exports, and unique provider ID.'];
+        const message = error instanceof Error && messages.includes(error.message) ? error.message : 'Could not run ASU. Check arguments and plugin configuration; see --help.';
+        process.stderr.write(`asu: ${message}\n`);
+        return 2;
+    }
+}
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+    process.stdout.on('error', (error) => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        process.stderr.write('asu: Could not write output.\n');
+        process.exit(2);
+    });
+    process.exitCode = await run();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+import type { ReasonCode } from './models.js';
+/** Only fixed messages reach output; errors may otherwise contain credentials. */
+export declare class UsageError extends Error {
+    readonly code: ReasonCode;
+    constructor(code: ReasonCode);
+}
+export declare function safeReason(error: unknown): {
+    code: ReasonCode;
+    message: string;
+};

package/dist/errors.js

@@ -0,0 +1,24 @@
+const messages = {
+    missing_credentials: 'No supported local credentials found. Sign in using the provider CLI.',
+    invalid_credentials: 'Local credentials are malformed or expired. Sign in using the provider CLI.',
+    credential_read_error: 'Could not read the local credential store. Check its permissions and format.',
+    unauthorized: 'The provider rejected these credentials. Sign in using the provider CLI.',
+    timeout: 'The provider did not respond before the deadline.',
+    rate_limited: 'The provider is rate limiting usage requests. Try again after the cache expires.',
+    http_error: 'The provider usage endpoint returned an HTTP error.',
+    invalid_response: 'The provider returned an unrecognized or malformed usage response.',
+    provider_error: 'The provider could not report usage.',
+};
+/** Only fixed messages reach output; errors may otherwise contain credentials. */
+export class UsageError extends Error {
+    code;
+    constructor(code) {
+        super(messages[code]);
+        this.code = code;
+    }
+}
+export function safeReason(error) {
+    const code = error instanceof UsageError && Object.hasOwn(messages, error.code) ? error.code : 'provider_error';
+    return { code, message: messages[code] };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAA+B;IAC3C,mBAAmB,EAAE,uEAAuE;IAC5F,mBAAmB,EAAE,6EAA6E;IAClG,qBAAqB,EAAE,8EAA8E;IACrG,YAAY,EAAE,0EAA0E;IACxF,OAAO,EAAE,mDAAmD;IAC5D,YAAY,EAAE,kFAAkF;IAChG,UAAU,EAAE,qDAAqD;IACjE,gBAAgB,EAAE,oEAAoE;IACtF,cAAc,EAAE,sCAAsC;CACvD,CAAC;AAEF,kFAAkF;AAClF,MAAM,OAAO,UAAW,SAAQ,KAAK;IACd;IAArB,YAAqB,IAAgB;QAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAA1C,SAAI,GAAJ,IAAI,CAAY;IAA2B,CAAC;CAClE;AACD,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,IAAI,GAAG,KAAK,YAAY,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAChH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { Provider, ProviderContext, Credentials } from './providers/base.js';
+export type { UsageData, ProviderUsage, UsageReport, UsageWindow, Balance } from './models.js';
+export type { LocalContext } from './local.js';
+export type { RequestJson, JsonRequest } from './transport.js';
+export { usageDataSchema, providerUsageSchema, reportSchema, emptyUsage } from './models.js';
+export { UsageError } from './errors.js';
+export { UsageService } from './service.js';
+export { UsageCache } from './cache.js';
+export { createLocalContext } from './local.js';
+export { createTransport } from './transport.js';
+export { builtInProviders, loadProviders } from './registry.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { usageDataSchema, providerUsageSchema, reportSchema, emptyUsage } from './models.js';
+export { UsageError } from './errors.js';
+export { UsageService } from './service.js';
+export { UsageCache } from './cache.js';
+export { createLocalContext } from './local.js';
+export { createTransport } from './transport.js';
+export { builtInProviders, loadProviders } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/local.d.ts

@@ -0,0 +1,14 @@
+export interface LocalContext {
+    home: string;
+    env: Readonly<Record<string, string | undefined>>;
+    platform: NodeJS.Platform;
+    readText(path: string): Promise<string | null>;
+    readJson(path: string): Promise<unknown | null>;
+    keychain(service: string, validate?: (value: string) => boolean): Promise<string | null>;
+    sqliteToken(path: string, key: string): Promise<string | null>;
+}
+export declare function readText(path: string): Promise<string | null>;
+export declare function readKeychainEntry(service: string, account: string | undefined, run: (args: string[]) => Promise<string>, validate?: (_value: string) => boolean): Promise<string | null>;
+export declare function createLocalContext(overrides?: Partial<LocalContext>): LocalContext;
+export declare function homePath(context: LocalContext, setting: string | undefined, fallback: string): string;
+export declare function detectCommands(context: LocalContext, names: string[], appPaths?: string[]): Promise<boolean>;

package/dist/local.js

@@ -0,0 +1,121 @@
+import { access, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { homedir, userInfo } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { UsageError } from './errors.js';
+const exec = promisify(execFile);
+export async function readText(path) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 1_048_576)
+            throw new UsageError('credential_read_error');
+        const buffer = Buffer.alloc(1_048_577);
+        let size = 0;
+        while (size < buffer.length) {
+            const { bytesRead } = await file.read(buffer, size, buffer.length - size, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+        }
+        if (size > 1_048_576)
+            throw new UsageError('credential_read_error');
+        return buffer.subarray(0, size).toString('utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new UsageError('credential_read_error');
+    }
+    finally {
+        await file?.close();
+    }
+}
+export async function readKeychainEntry(service, account, run, validate = (_value) => true) {
+    for (const args of [...(account ? [['-a', account]] : []), []]) {
+        try {
+            const raw = (await run(['find-generic-password', '-s', service, ...args, '-w'])).trim();
+            if (raw && validate(raw))
+                return raw;
+        }
+        catch { /* Try the legacy service-only lookup after an unavailable or invalid entry. */ }
+    }
+    return null;
+}
+async function keychain(service, validate) {
+    if (process.platform !== 'darwin')
+        return null;
+    let account;
+    try {
+        account = userInfo().username;
+    }
+    catch { /* Try legacy lookup below. */ }
+    return readKeychainEntry(service, account, async (args) => {
+        const { stdout } = await exec('/usr/bin/security', args, { timeout: 2_000, maxBuffer: 1_048_576 });
+        return stdout;
+    }, validate);
+}
+async function sqliteToken(path, key) {
+    try {
+        await access(path);
+    }
+    catch {
+        return null;
+    }
+    // A subprocess contains node:sqlite's experimental warning on Node 22 and bounds a busy database.
+    // No token is passed in argv, and child output is never logged.
+    const script = `const {DatabaseSync}=require('node:sqlite');
+    const db=new DatabaseSync(process.argv[1],{readOnly:true});
+    try { const r=db.prepare('SELECT value FROM ItemTable WHERE key = ?').get(process.argv[2]);
+      if(typeof r?.value==='string') process.stdout.write(r.value); } finally {db.close();}`;
+    try {
+        const { stdout } = await exec(process.execPath, ['--no-warnings', '-e', script, path, key], { timeout: 2_000, maxBuffer: 65_536 });
+        return stdout.trim() || null;
+    }
+    catch {
+        throw new UsageError('credential_read_error');
+    }
+}
+export function createLocalContext(overrides = {}) {
+    const local = { home: homedir(), env: process.env, platform: process.platform,
+        readText, keychain, sqliteToken, ...overrides };
+    return { ...local, readJson: overrides.readJson ?? (async (path) => {
+            const text = await local.readText(path);
+            if (text === null)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new UsageError('invalid_credentials');
+            }
+        }) };
+}
+export function homePath(context, setting, fallback) {
+    const path = setting || join(context.home, fallback);
+    return path.startsWith('~/') ? join(context.home, path.slice(2)) : resolve(path);
+}
+export async function detectCommands(context, names, appPaths = []) {
+    const suffixes = context.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+    const paths = (context.env.PATH ?? '').split(delimiter).filter(Boolean)
+        .flatMap(dir => names.flatMap(name => suffixes.map(suffix => join(dir, name + suffix))));
+    for (const path of paths) {
+        try {
+            await access(path, context.platform === 'win32' ? constants.F_OK : constants.X_OK);
+            return true;
+        }
+        catch { /* next */ }
+    }
+    for (const path of appPaths) {
+        try {
+            await access(path);
+            return true;
+        }
+        catch { /* next */ }
+    }
+    return false;
+}
+//# sourceMappingURL=local.js.map

package/dist/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAUjC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,GAAG,SAAS;YAAE,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,OAAO,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC;YAChF,IAAI,CAAC,SAAS;gBAAE,MAAM;YACtB,IAAI,IAAI,SAAS,CAAC;QACpB,CAAC;QACD,IAAI,IAAI,GAAG,SAAS;YAAE,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAC;QACpE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpE,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAC;IAChD,CAAC;YAAS,CAAC;QAAC,MAAM,IAAI,EAAE,KAAK,EAAE,CAAC;IAAC,CAAC;AACpC,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAe,EAAE,OAA2B,EAClF,GAAwC,EAAE,WAAW,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI;IAC7E,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,uBAAuB,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACxF,IAAI,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,GAAG,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC,CAAC,+EAA+E,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AACD,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,QAAqC;IAC5E,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QAAC,OAAO,GAAG,QAAQ,EAAE,CAAC,QAAQ,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,8BAA8B,CAAC,CAAC;IAC/E,OAAO,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAC,IAAI,EAAC,EAAE;QACtD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;QACnG,OAAO,MAAM,CAAC;IAChB,CAAC,EAAE,QAAQ,CAAC,CAAC;AACf,CAAC;AACD,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,GAAW;IAClD,IAAI,CAAC;QAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IAClD,kGAAkG;IAClG,gEAAgE;IAChE,MAAM,MAAM,GAAG;;;4FAG2E,CAAC;IAC3F,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,EACxF,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAC;IAAC,CAAC;AAC5D,CAAC;AACD,MAAM,UAAU,kBAAkB,CAAC,YAAmC,EAAE;IACtE,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC3E,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,SAAS,EAAE,CAAC;IAClD,OAAO,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAC,IAAI,EAAC,EAAE;YAC/D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,IAAI,CAAC;gBAAC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;YAAC,CAAC;YAC3C,MAAM,CAAC;gBAAC,MAAM,IAAI,UAAU,CAAC,qBAAqB,CAAC,CAAC;YAAC,CAAC;QACxD,CAAC,CAAC,EAAE,CAAC;AACP,CAAC;AACD,MAAM,UAAU,QAAQ,CAAC,OAAqB,EAAE,OAA2B,EAAE,QAAgB;IAC3F,MAAM,IAAI,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACnF,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAqB,EAAE,KAAe,EAAE,WAAqB,EAAE;IAClG,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;SACpE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;IAC/H,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAAC,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;IAAC,CAAC;IAC9F,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+export declare const displayText: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export declare const windowSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    percentUsed: z.ZodNullable<z.ZodNumber>;
+    resetsAt: z.ZodNullable<z.ZodISODateTime>;
+    used: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    unlimited: z.ZodOptional<z.ZodBoolean>;
+    scope: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        surface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const balanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    unit: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    remaining: z.ZodOptional<z.ZodNumber>;
+    used: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    unlimited: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const usageDataSchema: z.ZodObject<{
+    planLabel: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    windows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        percentUsed: z.ZodNullable<z.ZodNumber>;
+        resetsAt: z.ZodNullable<z.ZodISODateTime>;
+        used: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        unit: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            surface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    balances: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        unit: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        remaining: z.ZodOptional<z.ZodNumber>;
+        used: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    details: z.ZodArray<z.ZodObject<{
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        value: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const reasonCodes: readonly ["missing_credentials", "invalid_credentials", "credential_read_error", "unauthorized", "timeout", "rate_limited", "http_error", "invalid_response", "provider_error"];
+export declare const providerUsageSchema: z.ZodObject<{
+    planLabel: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    windows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        percentUsed: z.ZodNullable<z.ZodNumber>;
+        resetsAt: z.ZodNullable<z.ZodISODateTime>;
+        used: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        unit: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            surface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    balances: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        unit: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        remaining: z.ZodOptional<z.ZodNumber>;
+        used: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    details: z.ZodArray<z.ZodObject<{
+        label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        value: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strip>>;
+    providerId: z.ZodString;
+    displayName: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    experimental: z.ZodBoolean;
+    installed: z.ZodNullable<z.ZodBoolean>;
+    credentialsPresent: z.ZodBoolean;
+    authenticated: z.ZodNullable<z.ZodBoolean>;
+    availability: z.ZodEnum<{
+        error: "error";
+        available: "available";
+        unavailable: "unavailable";
+    }>;
+    reason: z.ZodNullable<z.ZodObject<{
+        code: z.ZodEnum<{
+            missing_credentials: "missing_credentials";
+            invalid_credentials: "invalid_credentials";
+            credential_read_error: "credential_read_error";
+            unauthorized: "unauthorized";
+            timeout: "timeout";
+            rate_limited: "rate_limited";
+            http_error: "http_error";
+            invalid_response: "invalid_response";
+            provider_error: "provider_error";
+        }>;
+        message: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strip>>;
+    fetchedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    cached: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const reportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    generatedAt: z.ZodISODateTime;
+    warnings: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    providers: z.ZodArray<z.ZodObject<{
+        planLabel: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        windows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            percentUsed: z.ZodNullable<z.ZodNumber>;
+            resetsAt: z.ZodNullable<z.ZodISODateTime>;
+            used: z.ZodOptional<z.ZodNumber>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            unit: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            unlimited: z.ZodOptional<z.ZodBoolean>;
+            scope: z.ZodOptional<z.ZodObject<{
+                model: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+                surface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        balances: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            unit: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            remaining: z.ZodOptional<z.ZodNumber>;
+            used: z.ZodOptional<z.ZodNumber>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            unlimited: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        details: z.ZodArray<z.ZodObject<{
+            label: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            value: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>>;
+        providerId: z.ZodString;
+        displayName: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        experimental: z.ZodBoolean;
+        installed: z.ZodNullable<z.ZodBoolean>;
+        credentialsPresent: z.ZodBoolean;
+        authenticated: z.ZodNullable<z.ZodBoolean>;
+        availability: z.ZodEnum<{
+            error: "error";
+            available: "available";
+            unavailable: "unavailable";
+        }>;
+        reason: z.ZodNullable<z.ZodObject<{
+            code: z.ZodEnum<{
+                missing_credentials: "missing_credentials";
+                invalid_credentials: "invalid_credentials";
+                credential_read_error: "credential_read_error";
+                unauthorized: "unauthorized";
+                timeout: "timeout";
+                rate_limited: "rate_limited";
+                http_error: "http_error";
+                invalid_response: "invalid_response";
+                provider_error: "provider_error";
+            }>;
+            message: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>>;
+        fetchedAt: z.ZodISODateTime;
+        expiresAt: z.ZodISODateTime;
+        cached: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UsageWindow = z.infer<typeof windowSchema>;
+export type Balance = z.infer<typeof balanceSchema>;
+export type UsageData = z.infer<typeof usageDataSchema>;
+export type ProviderUsage = z.infer<typeof providerUsageSchema>;
+export type UsageReport = z.infer<typeof reportSchema>;
+export type ReasonCode = typeof reasonCodes[number];
+export declare function emptyUsage(): UsageData;

package/dist/models.js

@@ -0,0 +1,57 @@
+import { stripVTControlCharacters } from 'node:util';
+import { z } from 'zod';
+export const displayText = z.string().max(1024).transform(value => stripVTControlCharacters(value).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, ' ').trim());
+const id = z.string().regex(/^[a-z0-9][a-z0-9._:-]{0,127}$/);
+const quantity = z.number().finite().nonnegative();
+const timestamp = z.iso.datetime();
+export const windowSchema = z.object({
+    id,
+    label: displayText,
+    percentUsed: quantity.nullable(),
+    resetsAt: timestamp.nullable(),
+    used: quantity.optional(),
+    limit: quantity.optional(),
+    unit: displayText.optional(),
+    unlimited: z.boolean().optional(),
+    scope: z.object({ model: displayText.optional(), surface: displayText.optional() }).optional(),
+});
+export const balanceSchema = z.object({
+    id,
+    label: displayText,
+    unit: displayText,
+    remaining: z.number().finite().optional(),
+    used: quantity.optional(),
+    limit: quantity.optional(),
+    unlimited: z.boolean().optional(),
+});
+export const usageDataSchema = z.object({
+    planLabel: displayText.nullable(),
+    windows: z.array(windowSchema).max(100),
+    balances: z.array(balanceSchema).max(100),
+    details: z.array(z.object({ label: displayText, value: displayText })).max(100),
+});
+export const reasonCodes = ['missing_credentials', 'invalid_credentials', 'credential_read_error',
+    'unauthorized', 'timeout', 'rate_limited', 'http_error', 'invalid_response', 'provider_error'];
+export const providerUsageSchema = usageDataSchema.extend({
+    providerId: id,
+    displayName: displayText,
+    experimental: z.boolean(),
+    installed: z.boolean().nullable(),
+    credentialsPresent: z.boolean(),
+    authenticated: z.boolean().nullable(),
+    availability: z.enum(['available', 'unavailable', 'error']),
+    reason: z.object({ code: z.enum(reasonCodes), message: displayText }).nullable(),
+    fetchedAt: timestamp,
+    expiresAt: timestamp,
+    cached: z.boolean(),
+});
+export const reportSchema = z.object({
+    schemaVersion: z.literal(1),
+    generatedAt: timestamp,
+    warnings: z.array(displayText),
+    providers: z.array(providerUsageSchema),
+});
+export function emptyUsage() {
+    return { planLabel: null, windows: [], balances: [], details: [] };
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -0,0 +1,13 @@
+import type { UsageReport } from './models.js';
+export type OutputFormat = 'plain' | 'table' | 'json';
+export interface RenderOptions {
+    columns?: number;
+    /** Print full UTC timestamps instead of times relative to now. */
+    utc?: boolean;
+    now?: number;
+}
+export declare function renderPlain(report: UsageReport, options?: RenderOptions): string;
+export declare function renderTable(report: UsageReport, options?: RenderOptions): string;
+/** True when a cell would wrap at this width. The CLI then prefers plain output unless the table was requested. */
+export declare function tableWraps(report: UsageReport, options?: RenderOptions): boolean;
+export declare function render(report: UsageReport, format: OutputFormat, options?: RenderOptions): string;