@hanzo/usage 0.1.0

package/dist/host.d.ts

@@ -0,0 +1,27 @@
+export interface HttpRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    text: string;
+}
+export interface UsageHost {
+    /** Read a UTF-8 text file; returns undefined when missing/unreadable. */
+    readTextFile(path: string): Promise<string | undefined>;
+    /** List directory entries (names, not paths); [] when missing. */
+    listDir(path: string): Promise<string[]>;
+    /** Write a UTF-8 text file, creating parent directories. */
+    writeTextFile(path: string, contents: string): Promise<void>;
+    http(req: HttpRequest): Promise<HttpResponse>;
+    env(name: string): string | undefined;
+    homeDir(): string;
+    now(): Date;
+}
+/** Expand a leading `~/` against the host home directory. */
+export declare const expandHome: (host: UsageHost, path: string) => string;
+export declare const readJsonFile: <T>(host: UsageHost, path: string) => Promise<T | undefined>;

package/dist/host.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Host abstraction — the port of CodexBar's "Host APIs" concept. Providers never
+// touch the filesystem, network, or environment directly; they go through a
+// UsageHost so the same provider code runs in Node (chat/console/dev), Tauri
+// (desktop/app), and tests.
+/** Expand a leading `~/` against the host home directory. */
+export const expandHome = (host, path) => path.startsWith('~/') ? `${host.homeDir()}/${path.slice(2)}` : path;
+export const readJsonFile = async (host, path) => {
+    const text = await host.readTextFile(expandHome(host, path));
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/hosts/node.d.ts

@@ -0,0 +1,2 @@
+import type { UsageHost } from '../host.js';
+export declare const nodeHost: UsageHost;

package/dist/hosts/node.js

@@ -0,0 +1,50 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Node host — used by chat's Express API, console/app server routes, and CLIs.
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+export const nodeHost = {
+    async readTextFile(path) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async listDir(path) {
+        try {
+            return await readdir(path);
+        }
+        catch {
+            return [];
+        }
+    },
+    async writeTextFile(path, contents) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, contents, 'utf8');
+    },
+    async http(req) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), req.timeoutMs ?? 30_000);
+        try {
+            const res = await fetch(req.url, {
+                method: req.method ?? 'GET',
+                headers: req.headers,
+                body: req.body,
+                signal: controller.signal,
+            });
+            const headers = {};
+            res.headers.forEach((v, k) => {
+                headers[k] = v;
+            });
+            return { status: res.status, headers, text: await res.text() };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    },
+    env: (name) => process.env[name],
+    homeDir: () => homedir(),
+    now: () => new Date(),
+};

package/dist/hosts/tauri.d.ts

@@ -0,0 +1,26 @@
+import type { UsageHost } from '../host.js';
+type TauriFs = {
+    readTextFile(path: string): Promise<string>;
+    readDir(path: string): Promise<Array<{
+        name: string;
+    }>>;
+    writeTextFile(path: string, contents: string): Promise<void>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+};
+/**
+ * Build a UsageHost from Tauri plugin modules. Modules are passed in (not
+ * imported) so this file stays dependency-free for web/Node bundles:
+ *
+ *   import * as fs from '@tauri-apps/plugin-fs'
+ *   import { fetch } from '@tauri-apps/plugin-http'
+ *   import { homeDir } from '@tauri-apps/api/path'
+ *   const host = await createTauriHost({ fs, fetch, homeDir })
+ */
+export declare const createTauriHost: (deps: {
+    fs: TauriFs;
+    fetch: typeof fetch;
+    homeDir: () => Promise<string>;
+}) => Promise<UsageHost>;
+export {};

package/dist/hosts/tauri.js

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Tauri host — used by hanzo desktop and the hanzo app launcher. Requires the
+// fs + http plugins with scope covering the provider config paths
+// (~/.codex, ~/.claude, ~/.hanzo) and the provider API domains.
+/**
+ * Build a UsageHost from Tauri plugin modules. Modules are passed in (not
+ * imported) so this file stays dependency-free for web/Node bundles:
+ *
+ *   import * as fs from '@tauri-apps/plugin-fs'
+ *   import { fetch } from '@tauri-apps/plugin-http'
+ *   import { homeDir } from '@tauri-apps/api/path'
+ *   const host = await createTauriHost({ fs, fetch, homeDir })
+ */
+export const createTauriHost = async (deps) => {
+    const home = (await deps.homeDir()).replace(/\/$/, '');
+    return {
+        async readTextFile(path) {
+            try {
+                return await deps.fs.readTextFile(path);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async listDir(path) {
+            try {
+                return (await deps.fs.readDir(path)).map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
+        async writeTextFile(path, contents) {
+            const dir = path.slice(0, path.lastIndexOf('/'));
+            try {
+                await deps.fs.mkdir(dir, { recursive: true });
+            }
+            catch {
+                // exists
+            }
+            await deps.fs.writeTextFile(path, contents);
+        },
+        async http(req) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), req.timeoutMs ?? 30_000);
+            try {
+                const res = await deps.fetch(req.url, {
+                    method: req.method ?? 'GET',
+                    headers: req.headers,
+                    body: req.body,
+                    signal: controller.signal,
+                });
+                const headers = {};
+                res.headers.forEach((v, k) => {
+                    headers[k] = v;
+                });
+                return { status: res.status, headers, text: await res.text() };
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        },
+        env: () => undefined,
+        homeDir: () => home,
+        now: () => new Date(),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './types.js';
+export * from './host.js';
+export * from './provider.js';
+export * from './store.js';
+export { codexProvider } from './providers/codex.js';
+export { claudeProvider } from './providers/claude.js';
+export { hanzoProvider } from './providers/hanzo.js';
+import type { ProviderDescriptor } from './provider.js';
+/** All built-in providers, registry-style like CodexBar's descriptor registry. */
+export declare const providerRegistry: Record<string, ProviderDescriptor>;
+export declare const allProviders: ProviderDescriptor[];

package/dist/index.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+export * from './types.js';
+export * from './host.js';
+export * from './provider.js';
+export * from './store.js';
+export { codexProvider } from './providers/codex.js';
+export { claudeProvider } from './providers/claude.js';
+export { hanzoProvider } from './providers/hanzo.js';
+import { codexProvider } from './providers/codex.js';
+import { claudeProvider } from './providers/claude.js';
+import { hanzoProvider } from './providers/hanzo.js';
+/** All built-in providers, registry-style like CodexBar's descriptor registry. */
+export const providerRegistry = {
+    hanzo: hanzoProvider,
+    codex: codexProvider,
+    claude: claudeProvider,
+};
+export const allProviders = Object.values(providerRegistry);

package/dist/provider.d.ts

@@ -0,0 +1,71 @@
+import type { CreditsSnapshot, UsageSnapshot } from './types.js';
+import type { UsageHost } from './host.js';
+export type ProviderSourceMode = 'auto' | 'web' | 'cli' | 'oauth' | 'api';
+export type ProviderFetchKind = 'cli' | 'web' | 'oauth' | 'apiToken' | 'localProbe';
+export interface ProviderSettings {
+    /** API key / secret for apiToken strategies. */
+    apiKey?: string;
+    /** Base URL override (e.g. self-hosted gateway). */
+    baseUrl?: string;
+    /** Bearer-token resolver for cloud (IAM) strategies. */
+    getToken?: () => Promise<string | undefined>;
+    /** Extra provider-specific settings. */
+    [key: string]: unknown;
+}
+export interface ProviderFetchContext {
+    host: UsageHost;
+    sourceMode: ProviderSourceMode;
+    settings?: ProviderSettings;
+    verbose?: boolean;
+}
+export interface ProviderFetchResult {
+    usage: UsageSnapshot;
+    credits?: CreditsSnapshot;
+    /** Human-readable label of the source that produced the data. */
+    sourceLabel: string;
+    strategyId: string;
+    strategyKind: ProviderFetchKind;
+}
+export interface ProviderFetchStrategy {
+    /** e.g. "codex.oauth", "claude.web" */
+    id: string;
+    kind: ProviderFetchKind;
+    isAvailable(ctx: ProviderFetchContext): Promise<boolean>;
+    fetch(ctx: ProviderFetchContext): Promise<ProviderFetchResult>;
+    /** Whether the pipeline should try the next strategy after this error. */
+    shouldFallback?(error: unknown, ctx: ProviderFetchContext): boolean;
+}
+export interface ProviderFetchAttempt {
+    strategyId: string;
+    ok: boolean;
+    error?: string;
+    skipped?: boolean;
+}
+export interface ProviderFetchOutcome {
+    result?: ProviderFetchResult;
+    error?: unknown;
+    attempts: ProviderFetchAttempt[];
+}
+export interface ProviderMetadata {
+    displayName: string;
+    /** Label for the primary lane, e.g. "5h limit" / "Session". */
+    sessionLabel: string;
+    /** Label for the secondary lane, e.g. "Weekly limit". */
+    weeklyLabel: string;
+    supportsCredits?: boolean;
+    defaultEnabled?: boolean;
+    dashboardUrl?: string;
+    statusPageUrl?: string;
+    /** Brand accent as CSS color. */
+    color?: string;
+}
+export interface ProviderDescriptor {
+    id: string;
+    metadata: ProviderMetadata;
+    /** Strategies in priority order for a given source mode. */
+    strategies(mode: ProviderSourceMode): ProviderFetchStrategy[];
+}
+/** Filter a full priority list down to the requested source mode. */
+export declare const forMode: (all: ProviderFetchStrategy[], mode: ProviderSourceMode) => ProviderFetchStrategy[];
+/** Run strategies in priority order with availability checks and fallback. */
+export declare const runPipeline: (descriptor: ProviderDescriptor, ctx: ProviderFetchContext) => Promise<ProviderFetchOutcome>;

package/dist/provider.js

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Provider abstraction — TypeScript port of CodexBarCore's ProviderDescriptor /
+// ProviderFetchPlan / ProviderFetchPipeline (priority-ordered strategies with
+// availability checks and fallback).
+const matchesMode = (kind, mode) => {
+    if (mode === 'auto')
+        return true;
+    if (mode === 'web')
+        return kind === 'web';
+    if (mode === 'cli')
+        return kind === 'cli' || kind === 'localProbe';
+    if (mode === 'oauth')
+        return kind === 'oauth';
+    return kind === 'apiToken';
+};
+/** Filter a full priority list down to the requested source mode. */
+export const forMode = (all, mode) => all.filter((s) => matchesMode(s.kind, mode));
+/** Run strategies in priority order with availability checks and fallback. */
+export const runPipeline = async (descriptor, ctx) => {
+    const attempts = [];
+    let lastError;
+    for (const strategy of descriptor.strategies(ctx.sourceMode)) {
+        if (!(await strategy.isAvailable(ctx))) {
+            attempts.push({ strategyId: strategy.id, ok: false, skipped: true });
+            continue;
+        }
+        try {
+            const result = await strategy.fetch(ctx);
+            attempts.push({ strategyId: strategy.id, ok: true });
+            return { result, attempts };
+        }
+        catch (error) {
+            attempts.push({
+                strategyId: strategy.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            lastError = error;
+            const fallback = strategy.shouldFallback?.(error, ctx) ?? true;
+            if (!fallback)
+                break;
+        }
+    }
+    return { error: lastError ?? new Error(`${descriptor.id}: no strategy available`), attempts };
+};

package/dist/providers/claude.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderDescriptor } from '../provider.js';
+export declare const claudeProvider: ProviderDescriptor;

package/dist/providers/claude.js

@@ -0,0 +1,138 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Claude (Anthropic) provider — port of CodexBarCore/Providers/Claude.
+// OAuth strategy reads Claude Code credentials (~/.claude/.credentials.json)
+// and calls the Anthropic OAuth usage endpoint; web strategy uses a claude.ai
+// sessionKey cookie supplied via settings.
+import { forMode } from '../provider.js';
+import { readJsonFile } from '../host.js';
+const WINDOW_MINUTES = {
+    five_hour: 300,
+    seven_day: 10_080,
+    seven_day_sonnet: 10_080,
+    seven_day_opus: 10_080,
+};
+const toWindow = (key, w) => {
+    const used = w?.utilization ?? w?.used_percent;
+    if (typeof used !== 'number')
+        return undefined;
+    return { usedPercent: used, windowMinutes: WINDOW_MINUTES[key], resetsAt: w?.resets_at };
+};
+const mapUsage = (body, now, loginMethod, plan) => {
+    const extras = [];
+    for (const [key, title] of [
+        ['seven_day_sonnet', 'Sonnet weekly'],
+        ['seven_day_opus', 'Opus weekly'],
+    ]) {
+        const window = toWindow(key, body[key]);
+        if (window)
+            extras.push({ id: key, title, window, usageKnown: true });
+    }
+    return {
+        providerId: 'claude',
+        primary: toWindow('five_hour', body.five_hour),
+        secondary: toWindow('seven_day', body.seven_day),
+        extraRateWindows: extras.length ? extras : undefined,
+        identity: {
+            providerId: 'claude',
+            plan: plan ?? body.subscriptionType ?? body.rate_limit_tier,
+            loginMethod,
+        },
+        providerCost: body.extra_usage && typeof body.extra_usage.used_cents === 'number'
+            ? {
+                used: body.extra_usage.used_cents / 100,
+                limit: typeof body.extra_usage.limit_cents === 'number'
+                    ? body.extra_usage.limit_cents / 100
+                    : undefined,
+                currencyCode: 'USD',
+                period: 'monthly',
+                updatedAt: now,
+            }
+            : undefined,
+        dataConfidence: 'percentOnly',
+        updatedAt: now,
+    };
+};
+const credentialPaths = ['~/.claude/.credentials.json', '~/.config/claude/.credentials.json'];
+const readCredentials = async (ctx) => {
+    for (const path of credentialPaths) {
+        const file = await readJsonFile(ctx.host, path);
+        if (file?.claudeAiOauth?.accessToken)
+            return file.claudeAiOauth;
+    }
+    return undefined;
+};
+const oauthStrategy = {
+    id: 'claude.oauth',
+    kind: 'oauth',
+    async isAvailable(ctx) {
+        return Boolean(await readCredentials(ctx));
+    },
+    async fetch(ctx) {
+        const creds = await readCredentials(ctx);
+        if (!creds?.accessToken)
+            throw new Error('claude: no OAuth credentials');
+        const res = await ctx.host.http({
+            url: 'https://api.anthropic.com/api/oauth/usage',
+            headers: {
+                Authorization: `Bearer ${creds.accessToken}`,
+                'anthropic-beta': 'oauth-2025-04-20',
+                Accept: 'application/json',
+            },
+            timeoutMs: 30_000,
+        });
+        if (res.status !== 200)
+            throw new Error(`claude usage HTTP ${res.status}`);
+        const body = JSON.parse(res.text);
+        return {
+            usage: mapUsage(body, ctx.host.now().toISOString(), 'oauth', creds.subscriptionType),
+            sourceLabel: 'Claude OAuth',
+            strategyId: this.id,
+            strategyKind: this.kind,
+        };
+    },
+};
+/** Web strategy: settings.cookieHeader must hold `sessionKey=sk-ant-…`. */
+const webStrategy = {
+    id: 'claude.web',
+    kind: 'web',
+    async isAvailable(ctx) {
+        return typeof ctx.settings?.cookieHeader === 'string';
+    },
+    async fetch(ctx) {
+        const cookie = String(ctx.settings?.cookieHeader);
+        const get = async (path) => {
+            const res = await ctx.host.http({
+                url: `https://claude.ai/api${path}`,
+                headers: { Cookie: cookie, Accept: 'application/json' },
+                timeoutMs: 30_000,
+            });
+            if (res.status !== 200)
+                throw new Error(`claude.ai${path} HTTP ${res.status}`);
+            return JSON.parse(res.text);
+        };
+        const orgs = (await get('/organizations'));
+        const orgId = orgs[0]?.uuid;
+        if (!orgId)
+            throw new Error('claude: no organization for session');
+        const body = (await get(`/organizations/${orgId}/usage`));
+        return {
+            usage: mapUsage(body, ctx.host.now().toISOString(), 'web'),
+            sourceLabel: 'claude.ai session',
+            strategyId: this.id,
+            strategyKind: this.kind,
+        };
+    },
+};
+export const claudeProvider = {
+    id: 'claude',
+    metadata: {
+        displayName: 'Claude',
+        sessionLabel: 'Session (5h)',
+        weeklyLabel: 'Weekly limit',
+        defaultEnabled: true,
+        dashboardUrl: 'https://claude.ai/settings/usage',
+        statusPageUrl: 'https://status.anthropic.com',
+        color: '#d97757',
+    },
+    strategies: (mode) => forMode([oauthStrategy, webStrategy], mode),
+};

package/dist/providers/codex.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderDescriptor } from '../provider.js';
+export declare const codexProvider: ProviderDescriptor;

package/dist/providers/codex.js

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Codex (OpenAI) provider — port of CodexBarCore/Providers/Codex (OAuth strategy).
+// Reads CLI credentials from $CODEX_HOME/auth.json (default ~/.codex/auth.json)
+// and calls the ChatGPT backend usage endpoint.
+import { forMode } from '../provider.js';
+import { expandHome, readJsonFile } from '../host.js';
+const codexHome = (ctx) => ctx.host.env('CODEX_HOME') ?? expandHome(ctx.host, '~/.codex');
+const toWindow = (w) => {
+    if (!w || typeof w.used_percent !== 'number')
+        return undefined;
+    return {
+        usedPercent: w.used_percent,
+        windowMinutes: w.limit_window_seconds ? Math.round(w.limit_window_seconds / 60) : undefined,
+        resetsAt: w.reset_at ? new Date(w.reset_at * 1000).toISOString() : undefined,
+    };
+};
+const oauthStrategy = {
+    id: 'codex.oauth',
+    kind: 'oauth',
+    async isAvailable(ctx) {
+        const auth = await readJsonFile(ctx.host, `${codexHome(ctx)}/auth.json`);
+        return Boolean(auth?.tokens?.access_token);
+    },
+    async fetch(ctx) {
+        const auth = await readJsonFile(ctx.host, `${codexHome(ctx)}/auth.json`);
+        const token = auth?.tokens?.access_token;
+        if (!token)
+            throw new Error('codex: no access token in auth.json');
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+            'User-Agent': 'HanzoUsage',
+        };
+        if (auth?.tokens?.account_id)
+            headers['ChatGPT-Account-Id'] = auth.tokens.account_id;
+        const res = await ctx.host.http({
+            url: 'https://chatgpt.com/backend-api/wham/usage',
+            headers,
+            timeoutMs: 30_000,
+        });
+        if (res.status !== 200)
+            throw new Error(`codex usage HTTP ${res.status}`);
+        const body = JSON.parse(res.text);
+        const now = ctx.host.now().toISOString();
+        const usage = {
+            providerId: 'codex',
+            primary: toWindow(body.rate_limit?.primary_window),
+            secondary: toWindow(body.rate_limit?.secondary_window),
+            extraRateWindows: (body.additional_rate_limits ?? [])
+                .map((extra) => {
+                const window = toWindow(extra.rate_limit?.primary_window);
+                if (!window || !extra.limit_name)
+                    return undefined;
+                return { id: extra.limit_name, title: extra.limit_name, window, usageKnown: true };
+            })
+                .filter((w) => Boolean(w)),
+            identity: { providerId: 'codex', plan: body.plan_type, loginMethod: 'oauth' },
+            dataConfidence: 'percentOnly',
+            updatedAt: now,
+        };
+        let credits;
+        if (body.credits?.has_credits) {
+            credits = {
+                remaining: body.credits.balance ?? 0,
+                unlimited: body.credits.unlimited,
+                updatedAt: now,
+            };
+        }
+        return {
+            usage,
+            credits,
+            sourceLabel: 'OpenAI OAuth',
+            strategyId: this.id,
+            strategyKind: this.kind,
+        };
+    },
+};
+export const codexProvider = {
+    id: 'codex',
+    metadata: {
+        displayName: 'Codex',
+        sessionLabel: '5h limit',
+        weeklyLabel: 'Weekly limit',
+        supportsCredits: true,
+        defaultEnabled: true,
+        dashboardUrl: 'https://chatgpt.com/codex/settings/usage',
+        statusPageUrl: 'https://status.openai.com',
+        color: '#10a37f',
+    },
+    strategies: (mode) => forMode([oauthStrategy], mode),
+};

package/dist/providers/hanzo.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderDescriptor } from '../provider.js';
+export declare const hanzoProvider: ProviderDescriptor;