@hanzo/usage 0.1.0

package/dist/providers/hanzo.js

@@ -0,0 +1,168 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Hanzo provider — two lanes:
+//  1. hanzo.cloud  — commerce billing usage (`GET {base}/v1/billing/usage`),
+//     the same source of truth console and chat bill against.
+//  2. hanzo.dev    — local probe of Hanzo Dev CLI rollouts
+//     ($HANZO_HOME|$CODEX_HOME|~/.hanzo|~/.codex sessions/YYYY/MM/DD/*.jsonl):
+//     the last persisted token_count event carries token totals and the
+//     latest rate-limit snapshot, exactly what the dev app-server replays.
+import { forMode } from '../provider.js';
+import { expandHome } from '../host.js';
+// ---- cloud (commerce ledger) ----
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const cloudStrategy = {
+    id: 'hanzo.cloud',
+    kind: 'apiToken',
+    async isAvailable(ctx) {
+        return Boolean(ctx.settings?.getToken || ctx.settings?.apiKey);
+    },
+    async fetch(ctx) {
+        const base = ctx.settings?.baseUrl ?? 'https://api.hanzo.ai';
+        const token = (await ctx.settings?.getToken?.()) ?? ctx.settings?.apiKey;
+        if (!token)
+            throw new Error('hanzo: no token for cloud usage');
+        const res = await ctx.host.http({
+            url: `${base}/v1/billing/usage`,
+            headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+            timeoutMs: 30_000,
+        });
+        if (res.status !== 200)
+            throw new Error(`hanzo billing usage HTTP ${res.status}`);
+        const body = JSON.parse(res.text);
+        // Defensive roll-up: accept either precomputed totals or a ledger of entries.
+        const entries = Array.isArray(body.usage)
+            ? body.usage
+            : Array.isArray(body.data)
+                ? body.data
+                : [];
+        let tokens = num(body.total_tokens ?? body.totalTokens);
+        let spendCents = num(body.spend_cents ?? body.spendCents);
+        let requests = num(body.total_requests ?? body.requests);
+        for (const e of entries) {
+            tokens += num(e.total_tokens ?? e.totalTokens ?? e.tokens);
+            spendCents += num(e.spend_cents ?? e.spendCents ?? e.cost_cents);
+            requests += num(e.requests ?? e.request_count ?? 1) - (e.requests === undefined && e.request_count === undefined ? 1 : 0);
+        }
+        const now = ctx.host.now().toISOString();
+        const usage = {
+            providerId: 'hanzo',
+            identity: { providerId: 'hanzo', loginMethod: 'iam' },
+            providerCost: {
+                used: spendCents / 100,
+                currencyCode: 'USD',
+                period: 'monthly',
+                updatedAt: now,
+            },
+            totals: { tokens, requests },
+            dataConfidence: 'exact',
+            updatedAt: now,
+        };
+        return {
+            usage,
+            sourceLabel: 'Hanzo Cloud',
+            strategyId: this.id,
+            strategyKind: this.kind,
+        };
+    },
+};
+const devHome = async (ctx) => {
+    const candidates = [
+        ctx.host.env('HANZO_HOME'),
+        ctx.host.env('CODEX_HOME'),
+        expandHome(ctx.host, '~/.hanzo'),
+        expandHome(ctx.host, '~/.codex'),
+    ].filter((c) => Boolean(c));
+    for (const dir of candidates) {
+        if ((await ctx.host.listDir(`${dir}/sessions`)).length > 0)
+            return dir;
+    }
+    return undefined;
+};
+/** Newest entry of a directory listing of numeric names (years, months, days). */
+const newest = (names) => names.filter((n) => /^\d+$/.test(n)).sort().at(-1);
+const toRateWindow = (w, now) => {
+    if (!w || typeof w.used_percent !== 'number')
+        return undefined;
+    return {
+        usedPercent: w.used_percent,
+        windowMinutes: w.window_minutes,
+        resetsAt: typeof w.resets_in_seconds === 'number'
+            ? new Date(now.getTime() + w.resets_in_seconds * 1000).toISOString()
+            : undefined,
+    };
+};
+const devStrategy = {
+    id: 'hanzo.dev',
+    kind: 'localProbe',
+    async isAvailable(ctx) {
+        return Boolean(await devHome(ctx));
+    },
+    async fetch(ctx) {
+        const home = await devHome(ctx);
+        if (!home)
+            throw new Error('hanzo: no dev CLI home with sessions');
+        const sessions = `${home}/sessions`;
+        const year = newest(await ctx.host.listDir(sessions));
+        const month = year && newest(await ctx.host.listDir(`${sessions}/${year}`));
+        const day = month && newest(await ctx.host.listDir(`${sessions}/${year}/${month}`));
+        if (!day)
+            throw new Error('hanzo: no dev sessions found');
+        const dayDir = `${sessions}/${year}/${month}/${day}`;
+        const rollouts = (await ctx.host.listDir(dayDir))
+            .filter((f) => f.endsWith('.jsonl'))
+            .sort();
+        const latest = rollouts.at(-1);
+        if (!latest)
+            throw new Error('hanzo: no rollout files today');
+        const text = (await ctx.host.readTextFile(`${dayDir}/${latest}`)) ?? '';
+        let payload;
+        for (const line of text.split('\n')) {
+            if (!line.includes('"token_count"'))
+                continue;
+            try {
+                const item = JSON.parse(line);
+                if (item.payload?.type === 'token_count')
+                    payload = item.payload;
+            }
+            catch {
+                // tolerate partial trailing lines
+            }
+        }
+        const now = ctx.host.now();
+        const totals = payload?.info?.total_token_usage;
+        const usage = {
+            providerId: 'hanzo',
+            primary: toRateWindow(payload?.rate_limits?.primary, now),
+            secondary: toRateWindow(payload?.rate_limits?.secondary, now),
+            identity: { providerId: 'hanzo', loginMethod: 'dev-cli' },
+            totals: totals
+                ? {
+                    tokens: totals.total_tokens ?? 0,
+                    inputTokens: totals.input_tokens ?? 0,
+                    outputTokens: totals.output_tokens ?? 0,
+                    cachedInputTokens: totals.cached_input_tokens ?? 0,
+                }
+                : undefined,
+            dataConfidence: totals ? 'exact' : 'unknown',
+            updatedAt: now.toISOString(),
+        };
+        return {
+            usage,
+            sourceLabel: 'Hanzo Dev CLI',
+            strategyId: this.id,
+            strategyKind: this.kind,
+        };
+    },
+};
+export const hanzoProvider = {
+    id: 'hanzo',
+    metadata: {
+        displayName: 'Hanzo',
+        sessionLabel: '5h limit',
+        weeklyLabel: 'Weekly limit',
+        defaultEnabled: true,
+        dashboardUrl: 'https://console.hanzo.ai/billing/usage',
+        color: '#ff2d55',
+    },
+    strategies: (mode) => forMode([cloudStrategy, devStrategy], mode),
+};

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+import type { UsageStore, UsageStoreState } from './store.js';
+export declare const useUsage: (store: UsageStore) => UsageStoreState;

package/dist/react.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// React binding — one hook, no extra state library.
+import { useSyncExternalStore } from 'react';
+export const useUsage = (store) => useSyncExternalStore((onChange) => store.subscribe(onChange), () => store.getState(), () => store.getState());

package/dist/store.d.ts

@@ -0,0 +1,49 @@
+import type { PlanUtilizationSeriesHistory, CreditsSnapshot, UsageSnapshot } from './types.js';
+import type { ProviderDescriptor, ProviderFetchAttempt, ProviderSettings, ProviderSourceMode } from './provider.js';
+import type { UsageHost } from './host.js';
+export interface ProviderState {
+    snapshot?: UsageSnapshot;
+    credits?: CreditsSnapshot;
+    error?: string;
+    sourceLabel?: string;
+    attempts?: ProviderFetchAttempt[];
+    refreshing: boolean;
+}
+export interface UsageStoreState {
+    providers: Record<string, ProviderState>;
+    refreshing: boolean;
+    lastRefreshAt?: string;
+}
+export interface UsageStoreOptions {
+    host: UsageHost;
+    providers: ProviderDescriptor[];
+    sourceMode?: ProviderSourceMode;
+    settings?: Record<string, ProviderSettings>;
+    /** Poll interval in ms; default 5 minutes (CodexBar's default). */
+    intervalMs?: number;
+    /** Directory for history JSON files; omit to keep history in memory only. */
+    historyDir?: string;
+}
+type Listener = () => void;
+export declare class UsageStore {
+    private readonly opts;
+    private state;
+    private listeners;
+    private timer;
+    private history;
+    constructor(opts: UsageStoreOptions);
+    getState(): UsageStoreState;
+    subscribe(listener: Listener): () => void;
+    private emit;
+    private setProvider;
+    refresh(providerId?: string): Promise<void>;
+    private refreshProvider;
+    start(): void;
+    stop(): void;
+    getHistory(providerId: string): PlanUtilizationSeriesHistory[];
+    private captureHistory;
+    private historyPath;
+    private loadHistory;
+    private persistHistory;
+}
+export {};

package/dist/store.js

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// UsageStore — port of CodexBar's UsageStore + AdaptiveRefreshPolicy: central
+// observable state, concurrent refresh across providers, poll timer, and
+// plan-utilization history capture (schema-compatible with the Swift app).
+import { runPipeline } from './provider.js';
+const HISTORY_MAX_ENTRIES = 2000;
+export class UsageStore {
+    opts;
+    state = { providers: {}, refreshing: false };
+    listeners = new Set();
+    timer;
+    history = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        for (const p of opts.providers) {
+            this.state.providers[p.id] = { refreshing: false };
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(next) {
+        this.state = { ...this.state, ...next };
+        for (const l of this.listeners)
+            l();
+    }
+    setProvider(id, patch) {
+        this.emit({
+            providers: {
+                ...this.state.providers,
+                [id]: { ...this.state.providers[id], refreshing: false, ...patch },
+            },
+        });
+    }
+    async refresh(providerId) {
+        const targets = this.opts.providers.filter((p) => !providerId || p.id === providerId);
+        this.emit({ refreshing: true });
+        await Promise.all(targets.map((p) => this.refreshProvider(p)));
+        this.emit({ refreshing: false, lastRefreshAt: this.opts.host.now().toISOString() });
+    }
+    async refreshProvider(descriptor) {
+        this.setProvider(descriptor.id, { refreshing: true });
+        const ctx = {
+            host: this.opts.host,
+            sourceMode: this.opts.sourceMode ?? 'auto',
+            settings: this.opts.settings?.[descriptor.id],
+        };
+        const outcome = await runPipeline(descriptor, ctx);
+        if (outcome.result) {
+            this.setProvider(descriptor.id, {
+                snapshot: outcome.result.usage,
+                credits: outcome.result.credits,
+                sourceLabel: outcome.result.sourceLabel,
+                attempts: outcome.attempts,
+                error: undefined,
+            });
+            await this.captureHistory(outcome.result.usage);
+        }
+        else {
+            // Keep stale data over flapping — errors annotate, they don't erase.
+            this.setProvider(descriptor.id, {
+                error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+                attempts: outcome.attempts,
+            });
+        }
+    }
+    start() {
+        if (this.timer)
+            return;
+        const interval = this.opts.intervalMs ?? 5 * 60 * 1000;
+        this.timer = setInterval(() => void this.refresh(), interval);
+        void this.refresh();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    // ---- plan-utilization history (sparkline data) ----
+    getHistory(providerId) {
+        return this.history.get(providerId) ?? [];
+    }
+    async captureHistory(snapshot) {
+        const lanes = [
+            {
+                name: 'session',
+                windowMinutes: snapshot.primary?.windowMinutes ?? 300,
+                usedPercent: snapshot.primary?.usedPercent,
+                resetsAt: snapshot.primary?.resetsAt,
+            },
+            {
+                name: 'weekly',
+                windowMinutes: snapshot.secondary?.windowMinutes ?? 10_080,
+                usedPercent: snapshot.secondary?.usedPercent,
+                resetsAt: snapshot.secondary?.resetsAt,
+            },
+        ];
+        let series = this.history.get(snapshot.providerId);
+        if (!series) {
+            series = await this.loadHistory(snapshot.providerId);
+            this.history.set(snapshot.providerId, series);
+        }
+        const capturedAt = snapshot.updatedAt;
+        // Hour-bucketed dedup, as the Swift store does.
+        const bucket = capturedAt.slice(0, 13);
+        for (const lane of lanes) {
+            if (typeof lane.usedPercent !== 'number')
+                continue;
+            let s = series.find((x) => x.name === lane.name);
+            if (!s) {
+                s = { name: lane.name, windowMinutes: lane.windowMinutes, entries: [] };
+                series.push(s);
+            }
+            const last = s.entries.at(-1);
+            if (last && last.capturedAt.slice(0, 13) === bucket) {
+                last.usedPercent = lane.usedPercent;
+                last.resetsAt = lane.resetsAt;
+            }
+            else {
+                s.entries.push({ capturedAt, usedPercent: lane.usedPercent, resetsAt: lane.resetsAt });
+                if (s.entries.length > HISTORY_MAX_ENTRIES)
+                    s.entries.splice(0, s.entries.length - HISTORY_MAX_ENTRIES);
+            }
+        }
+        await this.persistHistory(snapshot.providerId, series);
+    }
+    historyPath(providerId) {
+        return this.opts.historyDir ? `${this.opts.historyDir}/${providerId}.json` : undefined;
+    }
+    async loadHistory(providerId) {
+        const path = this.historyPath(providerId);
+        if (!path)
+            return [];
+        const text = await this.opts.host.readTextFile(path);
+        if (!text)
+            return [];
+        try {
+            const file = JSON.parse(text);
+            return file.version === 1 ? file.unscoped : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async persistHistory(providerId, series) {
+        const path = this.historyPath(providerId);
+        if (!path)
+            return;
+        const file = { version: 1, unscoped: series };
+        await this.opts.host.writeTextFile(path, JSON.stringify(file));
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+/** Universal quota unit — one rate-limit window (session/5h, weekly, …). */
+export interface RateWindow {
+    /** 0–100 percent used. */
+    usedPercent: number;
+    /** Window length in minutes (300 = 5h, 10080 = weekly). */
+    windowMinutes?: number;
+    /** Absolute reset time, ISO 8601. */
+    resetsAt?: string;
+    /** Textual reset description when only scraped text is available. */
+    resetDescription?: string;
+    /** Rolling-recovery providers: percent that regenerates next. */
+    nextRegenPercent?: number;
+    /** True when a lane was fabricated (e.g. provider returned null for it). */
+    isSyntheticPlaceholder?: boolean;
+}
+export declare const remainingPercent: (w: RateWindow) => number;
+export interface NamedRateWindow {
+    id: string;
+    title: string;
+    window: RateWindow;
+    usageKnown: boolean;
+}
+export type UsageDataConfidence = 'exact' | 'estimated' | 'percentOnly' | 'unknown';
+export interface ProviderIdentity {
+    providerId: string;
+    accountEmail?: string;
+    accountOrganization?: string;
+    loginMethod?: string;
+    plan?: string;
+}
+/** Per-provider fetch result — the central value of the system. */
+export interface UsageSnapshot {
+    providerId: string;
+    /** Session / 5h lane. */
+    primary?: RateWindow;
+    /** Weekly lane. */
+    secondary?: RateWindow;
+    tertiary?: RateWindow;
+    /** Model-specific or auxiliary windows. */
+    extraRateWindows?: NamedRateWindow[];
+    identity?: ProviderIdentity;
+    dataConfidence: UsageDataConfidence;
+    subscriptionExpiresAt?: string;
+    subscriptionRenewsAt?: string;
+    providerCost?: ProviderCostSnapshot;
+    /** Absolute token totals when the source reports them (exact confidence). */
+    totals?: UsageTotals;
+    updatedAt: string;
+}
+export interface UsageTotals {
+    tokens: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    requests?: number;
+}
+export interface CreditEvent {
+    id: string;
+    date: string;
+    service: string;
+    creditsUsed: number;
+}
+export interface CreditsSnapshot {
+    remaining: number;
+    unlimited?: boolean;
+    events?: CreditEvent[];
+    updatedAt: string;
+}
+/** Generic spend/budget meter used by API providers. */
+export interface ProviderCostSnapshot {
+    used: number;
+    limit?: number;
+    currencyCode: string;
+    period?: string;
+    resetsAt?: string;
+    updatedAt: string;
+}
+export interface ModelBreakdown {
+    modelName: string;
+    costUSD: number;
+    totalTokens: number;
+    requestCount: number;
+}
+export interface CostUsageDailyEntry {
+    /** "YYYY-MM-DD" */
+    date: string;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    requestCount: number;
+    costUSD: number;
+    modelsUsed: string[];
+    modelBreakdowns?: ModelBreakdown[];
+}
+export interface CostUsageTokenSnapshot {
+    providerId: string;
+    sessionTokens: number;
+    sessionCostUSD: number;
+    sessionRequests: number;
+    last30DaysTokens: number;
+    last30DaysCostUSD: number;
+    last30DaysRequests: number;
+    currencyCode: string;
+    historyDays: number;
+    daily: CostUsageDailyEntry[];
+    updatedAt: string;
+}
+export interface PlanUtilizationEntry {
+    capturedAt: string;
+    usedPercent: number;
+    resetsAt?: string;
+}
+export interface PlanUtilizationSeriesHistory {
+    /** "session" | "weekly" | named lane */
+    name: string;
+    windowMinutes: number;
+    entries: PlanUtilizationEntry[];
+}
+export interface PlanUtilizationHistoryFile {
+    version: 1;
+    preferredAccountKey?: string;
+    unscoped: PlanUtilizationSeriesHistory[];
+    accounts?: Record<string, PlanUtilizationSeriesHistory[]>;
+}
+export type StatusIndicator = 'none' | 'minor' | 'major' | 'critical' | 'unknown';
+export interface ProviderStatus {
+    indicator: StatusIndicator;
+    description?: string;
+    updatedAt: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// TypeScript port of CodexBarCore's data model (UsageFetcher.swift, CreditsModels.swift,
+// CostUsageModels.swift). Wire-compatible JSON where the Swift app persists snapshots.
+export const remainingPercent = (w) => Math.max(0, 100 - w.usedPercent);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@hanzo/usage",
+  "version": "0.1.0",
+  "description": "Track AI provider usage, rate limits, and spend across Hanzo products. Headless core (fork of CodexBar, ported to TypeScript).",
+  "license": "MIT",
+  "author": "Hanzo AI Inc",
+  "homepage": "https://github.com/hanzoai/usage",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanzoai/usage.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./node": {
+      "types": "./dist/hosts/node.d.ts",
+      "default": "./dist/hosts/node.js"
+    },
+    "./tauri": {
+      "types": "./dist/hosts/tauri.d.ts",
+      "default": "./dist/hosts/tauri.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/host.ts

@@ -0,0 +1,49 @@
+// 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.
+
+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 const expandHome = (host: UsageHost, path: string): string =>
+  path.startsWith('~/') ? `${host.homeDir()}/${path.slice(2)}` : path
+
+export const readJsonFile = async <T>(
+  host: UsageHost,
+  path: string,
+): Promise<T | undefined> => {
+  const text = await host.readTextFile(expandHome(host, path))
+  if (text === undefined) return undefined
+  try {
+    return JSON.parse(text) as T
+  } catch {
+    return undefined
+  }
+}

package/src/hosts/node.ts

@@ -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'
+import type { HttpRequest, HttpResponse, UsageHost } from '../host.js'
+
+export const nodeHost: UsageHost = {
+  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: HttpRequest): Promise<HttpResponse> {
+    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: Record<string, string> = {}
+      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(),
+}