@hanzo/usage 0.1.0

package/src/hosts/tauri.ts

@@ -0,0 +1,77 @@
+// 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.
+
+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 const createTauriHost = async (deps: {
+  fs: TauriFs
+  fetch: typeof fetch
+  homeDir: () => Promise<string>
+}): Promise<UsageHost> => {
+  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: Record<string, string> = {}
+        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/src/index.ts

@@ -0,0 +1,22 @@
+// 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 type { ProviderDescriptor } from './provider.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: Record<string, ProviderDescriptor> = {
+  hanzo: hanzoProvider,
+  codex: codexProvider,
+  claude: claudeProvider,
+}
+
+export const allProviders: ProviderDescriptor[] = Object.values(providerRegistry)

package/src/provider.ts

@@ -0,0 +1,125 @@
+// 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).
+
+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[]
+}
+
+const matchesMode = (kind: ProviderFetchKind, mode: ProviderSourceMode): boolean => {
+  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: ProviderFetchStrategy[],
+  mode: ProviderSourceMode,
+): ProviderFetchStrategy[] => all.filter((s) => matchesMode(s.kind, mode))
+
+/** Run strategies in priority order with availability checks and fallback. */
+export const runPipeline = async (
+  descriptor: ProviderDescriptor,
+  ctx: ProviderFetchContext,
+): Promise<ProviderFetchOutcome> => {
+  const attempts: ProviderFetchAttempt[] = []
+  let lastError: unknown
+  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/src/providers/claude.ts

@@ -0,0 +1,178 @@
+// 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 type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { NamedRateWindow, RateWindow, UsageSnapshot } from '../types.js'
+import { readJsonFile } from '../host.js'
+
+interface ClaudeCredentialsFile {
+  claudeAiOauth?: {
+    accessToken?: string
+    expiresAt?: number
+    subscriptionType?: string
+  }
+}
+
+interface ClaudeUsageWindow {
+  utilization?: number
+  used_percent?: number
+  resets_at?: string
+}
+
+interface ClaudeUsageResponse {
+  five_hour?: ClaudeUsageWindow | null
+  seven_day?: ClaudeUsageWindow | null
+  seven_day_sonnet?: ClaudeUsageWindow | null
+  seven_day_opus?: ClaudeUsageWindow | null
+  extra_usage?: { used_cents?: number; limit_cents?: number } | null
+  rate_limit_tier?: string
+  subscriptionType?: string
+}
+
+const WINDOW_MINUTES: Record<string, number> = {
+  five_hour: 300,
+  seven_day: 10_080,
+  seven_day_sonnet: 10_080,
+  seven_day_opus: 10_080,
+}
+
+const toWindow = (key: string, w: ClaudeUsageWindow | null | undefined): RateWindow | undefined => {
+  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: ClaudeUsageResponse,
+  now: string,
+  loginMethod: string,
+  plan?: string,
+): UsageSnapshot => {
+  const extras: NamedRateWindow[] = []
+  for (const [key, title] of [
+    ['seven_day_sonnet', 'Sonnet weekly'],
+    ['seven_day_opus', 'Opus weekly'],
+  ] as const) {
+    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: ProviderFetchContext) => {
+  for (const path of credentialPaths) {
+    const file = await readJsonFile<ClaudeCredentialsFile>(ctx.host, path)
+    if (file?.claudeAiOauth?.accessToken) return file.claudeAiOauth
+  }
+  return undefined
+}
+
+const oauthStrategy: ProviderFetchStrategy = {
+  id: 'claude.oauth',
+  kind: 'oauth',
+  async isAvailable(ctx) {
+    return Boolean(await readCredentials(ctx))
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    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) as ClaudeUsageResponse
+    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: ProviderFetchStrategy = {
+  id: 'claude.web',
+  kind: 'web',
+  async isAvailable(ctx) {
+    return typeof ctx.settings?.cookieHeader === 'string'
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    const cookie = String(ctx.settings?.cookieHeader)
+    const get = async (path: string) => {
+      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')) as Array<{ uuid: string }>
+    const orgId = orgs[0]?.uuid
+    if (!orgId) throw new Error('claude: no organization for session')
+    const body = (await get(`/organizations/${orgId}/usage`)) as ClaudeUsageResponse
+    return {
+      usage: mapUsage(body, ctx.host.now().toISOString(), 'web'),
+      sourceLabel: 'claude.ai session',
+      strategyId: this.id,
+      strategyKind: this.kind,
+    }
+  },
+}
+
+export const claudeProvider: ProviderDescriptor = {
+  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/src/providers/codex.ts

@@ -0,0 +1,126 @@
+// 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 type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { CreditsSnapshot, RateWindow, UsageSnapshot } from '../types.js'
+import { expandHome, readJsonFile } from '../host.js'
+
+interface CodexAuthFile {
+  tokens?: {
+    access_token?: string
+    account_id?: string
+  }
+  OPENAI_API_KEY?: string
+}
+
+interface CodexWindow {
+  used_percent?: number
+  reset_at?: number
+  limit_window_seconds?: number
+}
+
+interface CodexUsageResponse {
+  plan_type?: string
+  rate_limit?: {
+    primary_window?: CodexWindow
+    secondary_window?: CodexWindow
+  }
+  credits?: { has_credits?: boolean; unlimited?: boolean; balance?: number }
+  additional_rate_limits?: Array<{
+    limit_name?: string
+    rate_limit?: { primary_window?: CodexWindow }
+  }>
+}
+
+const codexHome = (ctx: ProviderFetchContext): string =>
+  ctx.host.env('CODEX_HOME') ?? expandHome(ctx.host, '~/.codex')
+
+const toWindow = (w: CodexWindow | undefined): RateWindow | undefined => {
+  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: ProviderFetchStrategy = {
+  id: 'codex.oauth',
+  kind: 'oauth',
+  async isAvailable(ctx) {
+    const auth = await readJsonFile<CodexAuthFile>(ctx.host, `${codexHome(ctx)}/auth.json`)
+    return Boolean(auth?.tokens?.access_token)
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    const auth = await readJsonFile<CodexAuthFile>(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: Record<string, string> = {
+      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) as CodexUsageResponse
+    const now = ctx.host.now().toISOString()
+    const usage: UsageSnapshot = {
+      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): w is NonNullable<typeof w> => Boolean(w)),
+      identity: { providerId: 'codex', plan: body.plan_type, loginMethod: 'oauth' },
+      dataConfidence: 'percentOnly',
+      updatedAt: now,
+    }
+    let credits: CreditsSnapshot | undefined
+    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: ProviderDescriptor = {
+  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),
+}