@hanzo/usage 0.1.1 → 0.1.2

package/src/providers/api-token.ts

@@ -0,0 +1,138 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Generic apiToken provider factory — TypeScript port of CodexBarCore's
+// APITokenFetchStrategy. A provider whose usage/credits/balance is exposed
+// behind a single pasteable API key becomes ~30 lines: describe how to build
+// the request from settings, and how to map the JSON body into a snapshot.
+//
+// The factory owns everything mechanical — key resolution (settings.apiKey or
+// env fallback), the HTTP call, status checking, JSON parsing, and stamping
+// providerId/updatedAt — so each provider file only expresses what is unique
+// to it: its endpoint, its auth header, and its response shape.
+
+import type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+  ProviderMetadata,
+  ProviderSettings,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { CreditsSnapshot, UsageSnapshot } from '../types.js'
+import type { HttpRequest } from '../host.js'
+
+/** Everything a provider's `map` yields except the mechanical providerId/updatedAt. */
+export type ApiTokenUsage = Omit<UsageSnapshot, 'providerId' | 'updatedAt'>
+
+export interface ApiTokenResult {
+  usage: ApiTokenUsage
+  credits?: Omit<CreditsSnapshot, 'updatedAt'>
+}
+
+export interface ApiTokenProviderConfig {
+  id: string
+  metadata: ProviderMetadata
+  /** Source label surfaced to the UI (defaults to the display name). */
+  sourceLabel?: string
+  /** Env var names to fall back to when settings.apiKey is absent. */
+  envKeys?: string[]
+  /** Env var names that supply a base URL for self-hosted gateways. */
+  baseUrlEnv?: string[]
+  /** Require a resolvable base URL (self-hosted gateways) to be available. */
+  requireBaseUrl?: boolean
+  /** Build the HTTP request. `settings.apiKey` (and resolved `baseUrl`) are present. */
+  request: (settings: ProviderSettings, ctx: ProviderFetchContext) => HttpRequest
+  /** Map a decoded 200 body into a usage/credits result. */
+  map: (json: unknown, now: Date, settings: ProviderSettings) => ApiTokenResult
+}
+
+/** Resolve a base URL from explicit settings, then from host env fallbacks. */
+export const resolveBaseUrl = (
+  ctx: ProviderFetchContext,
+  envKeys: readonly string[] = [],
+): string | undefined => {
+  const fromSettings = ctx.settings?.baseUrl
+  if (typeof fromSettings === 'string' && fromSettings.length > 0) return fromSettings
+  for (const name of envKeys) {
+    const value = ctx.host.env(name)
+    if (value) return value
+  }
+  return undefined
+}
+
+/** Resolve an API key from explicit settings, then from host env fallbacks. */
+export const resolveApiKey = (
+  ctx: ProviderFetchContext,
+  envKeys: readonly string[] = [],
+): string | undefined => {
+  const fromSettings = ctx.settings?.apiKey
+  if (typeof fromSettings === 'string' && fromSettings.length > 0) return fromSettings
+  for (const name of envKeys) {
+    const value = ctx.host.env(name)
+    if (value) return value
+  }
+  return undefined
+}
+
+export const makeApiTokenStrategy = (config: ApiTokenProviderConfig): ProviderFetchStrategy => {
+  const label = config.sourceLabel ?? config.metadata.displayName
+  return {
+    id: `${config.id}.apiToken`,
+    kind: 'apiToken',
+    async isAvailable(ctx) {
+      if (!resolveApiKey(ctx, config.envKeys)) return false
+      if (config.requireBaseUrl && !resolveBaseUrl(ctx, config.baseUrlEnv)) return false
+      return true
+    },
+    async fetch(ctx): Promise<ProviderFetchResult> {
+      const apiKey = resolveApiKey(ctx, config.envKeys)
+      if (!apiKey) throw new Error(`${config.id}: no API key`)
+      const baseUrl = resolveBaseUrl(ctx, config.baseUrlEnv)
+      if (config.requireBaseUrl && !baseUrl) throw new Error(`${config.id}: no base URL`)
+      const settings: ProviderSettings = { ...ctx.settings, apiKey, ...(baseUrl ? { baseUrl } : {}) }
+      const req = config.request(settings, ctx)
+      const res = await ctx.host.http({ method: 'GET', timeoutMs: 30_000, ...req })
+      if (res.status !== 200) throw new Error(`${config.id} HTTP ${res.status}`)
+      let body: unknown
+      try {
+        body = JSON.parse(res.text)
+      } catch {
+        throw new Error(`${config.id}: invalid JSON body`)
+      }
+      const now = ctx.host.now()
+      const iso = now.toISOString()
+      const { usage, credits } = config.map(body, now, settings)
+      return {
+        usage: { ...usage, providerId: config.id, updatedAt: iso },
+        credits: credits ? { ...credits, updatedAt: iso } : undefined,
+        sourceLabel: label,
+        strategyId: `${config.id}.apiToken`,
+        strategyKind: 'apiToken',
+      }
+    },
+    // API-key providers have exactly one source; nothing to fall back to.
+    shouldFallback() {
+      return false
+    },
+  }
+}
+
+/** Build a single-strategy apiToken ProviderDescriptor. */
+export const makeApiTokenProvider = (config: ApiTokenProviderConfig): ProviderDescriptor => {
+  const strategy = makeApiTokenStrategy(config)
+  return {
+    id: config.id,
+    metadata: config.metadata,
+    strategies: (mode) => forMode([strategy], mode),
+  }
+}
+
+/** Numeric coercion shared by mappers; non-finite/absent → undefined. */
+export const numberOrUndefined = (v: unknown): number | undefined =>
+  typeof v === 'number' && Number.isFinite(v) ? v : undefined
+
+/** Bearer auth header helper. */
+export const bearer = (key: string): Record<string, string> => ({
+  Authorization: `Bearer ${key}`,
+  Accept: 'application/json',
+})

package/src/providers/byo.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// BYO — bring-your-own OpenAI-compatible endpoint {baseUrl, apiKey}. This is the
+// self-hosted / BYO-GPU tracking lane: point it at any gateway that speaks the
+// OpenAI API (vLLM, LiteLLM, Hanzo Engine, a self-hosted cloud). It first tries a
+// LiteLLM-style /key/info for real spend/budget; failing that it falls back to a
+// /v1/models liveness probe and reports identity + reachability only
+// (dataConfidence 'unknown').
+//
+// NOTE: BYO devices registered into Hanzo Cloud are metered natively by the cloud
+// ledger (run-for-pay) regardless of what this local probe can read — this lane is
+// for endpoints Hanzo does not itself operate.
+
+import type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { UsageSnapshot } from '../types.js'
+import { bearer, resolveApiKey, resolveBaseUrl } from './api-token.js'
+
+const ENV_KEYS = ['BYO_API_KEY']
+const ENV_URL = ['BYO_BASE_URL']
+
+const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+const obj = (v: unknown): Record<string, unknown> =>
+  v && typeof v === 'object' ? (v as Record<string, unknown>) : {}
+const stripV1 = (base: string): string => base.replace(/\/v1\/?$/, '').replace(/\/$/, '')
+
+const keyInfo = async (
+  ctx: ProviderFetchContext,
+  base: string,
+  key: string,
+  now: Date,
+): Promise<UsageSnapshot | undefined> => {
+  const res = await ctx.host.http({
+    url: `${stripV1(base)}/key/info`,
+    headers: bearer(key),
+    timeoutMs: 15_000,
+  })
+  if (res.status !== 200) return undefined
+  let info: Record<string, unknown>
+  try {
+    info = obj(obj(JSON.parse(res.text)).info)
+  } catch {
+    return undefined
+  }
+  if (Object.keys(info).length === 0) return undefined
+  const spend = num(info.spend)
+  return {
+    providerId: 'byo',
+    identity: {
+      providerId: 'byo',
+      loginMethod: 'api',
+      accountEmail: typeof info.user_id === 'string' ? info.user_id : undefined,
+      accountOrganization: typeof info.team_id === 'string' ? info.team_id : undefined,
+      plan: typeof info.key_name === 'string' ? info.key_name : undefined,
+    },
+    providerCost: { used: spend, currencyCode: 'USD', period: 'key', updatedAt: now.toISOString() },
+    subscriptionExpiresAt: typeof info.expires === 'string' ? info.expires : undefined,
+    dataConfidence: 'exact',
+    updatedAt: now.toISOString(),
+  }
+}
+
+const modelsLiveness = async (
+  ctx: ProviderFetchContext,
+  base: string,
+  key: string,
+  now: Date,
+): Promise<UsageSnapshot> => {
+  const root = stripV1(base)
+  const res = await ctx.host.http({
+    url: `${root}/v1/models`,
+    headers: bearer(key),
+    timeoutMs: 15_000,
+  })
+  if (res.status !== 200) throw new Error(`byo: /v1/models HTTP ${res.status}`)
+  let count: number | undefined
+  try {
+    const data = obj(JSON.parse(res.text)).data
+    if (Array.isArray(data)) count = data.length
+  } catch {
+    // liveness only — a 200 is enough even if the body is not the expected shape
+  }
+  return {
+    providerId: 'byo',
+    identity: {
+      providerId: 'byo',
+      loginMethod: 'api',
+      accountOrganization: count !== undefined ? `${count} models` : undefined,
+    },
+    dataConfidence: 'unknown',
+    updatedAt: now.toISOString(),
+  }
+}
+
+const byoStrategy: ProviderFetchStrategy = {
+  id: 'byo.apiToken',
+  kind: 'apiToken',
+  async isAvailable(ctx) {
+    return Boolean(resolveApiKey(ctx, ENV_KEYS) && resolveBaseUrl(ctx, ENV_URL))
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    const key = resolveApiKey(ctx, ENV_KEYS)
+    const base = resolveBaseUrl(ctx, ENV_URL)
+    if (!key || !base) throw new Error('byo: baseUrl and apiKey are required')
+    const now = ctx.host.now()
+    const info = await keyInfo(ctx, base, key, now)
+    if (info) {
+      return { usage: info, sourceLabel: 'BYO /key/info', strategyId: this.id, strategyKind: this.kind }
+    }
+    const usage = await modelsLiveness(ctx, base, key, now)
+    return { usage, sourceLabel: 'BYO liveness', strategyId: this.id, strategyKind: this.kind }
+  },
+  shouldFallback() {
+    return false
+  },
+}
+
+export const byoProvider: ProviderDescriptor = {
+  id: 'byo',
+  metadata: {
+    displayName: 'BYO endpoint',
+    sessionLabel: 'Key spend',
+    weeklyLabel: 'Liveness',
+    dashboardUrl: 'https://docs.hanzo.ai/docs/gateway',
+    color: '#64748b',
+  },
+  strategies: (mode) => forMode([byoStrategy], mode),
+}

package/src/providers/deepgram.ts

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Deepgram provider — port of CodexBarCore/Providers/Deepgram. Deepgram exposes a
+// usage-breakdown API (audio hours, tokens, requests), no balance/quota. When no
+// project is configured we enumerate projects and aggregate. Auth is the Deepgram
+// `Token <key>` scheme (NOT Bearer).
+
+import type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { UsageSnapshot } from '../types.js'
+import { resolveApiKey } from './api-token.js'
+
+const ENV_KEYS = ['DEEPGRAM_API_KEY']
+const ENV_URL = 'DEEPGRAM_API_URL'
+const ENV_PROJECT = 'DEEPGRAM_PROJECT_ID'
+const DEFAULT_BASE = 'https://api.deepgram.com/v1'
+
+interface UsageResult {
+  requests?: number
+  total_hours?: number
+  tokens_in?: number
+  tokens_out?: number
+}
+
+const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+
+const deepgramStrategy: ProviderFetchStrategy = {
+  id: 'deepgram.apiToken',
+  kind: 'apiToken',
+  async isAvailable(ctx) {
+    return Boolean(resolveApiKey(ctx, ENV_KEYS))
+  },
+  async fetch(ctx: ProviderFetchContext): Promise<ProviderFetchResult> {
+    const key = resolveApiKey(ctx, ENV_KEYS)
+    if (!key) throw new Error('deepgram: no API key')
+    const base = ctx.settings?.baseUrl ?? ctx.host.env(ENV_URL) ?? DEFAULT_BASE
+    const headers = { Authorization: `Token ${key}`, Accept: 'application/json' }
+    const get = async (path: string): Promise<Record<string, unknown>> => {
+      const res = await ctx.host.http({ url: `${base}${path}`, headers, timeoutMs: 30_000 })
+      if (res.status !== 200) throw new Error(`deepgram ${path} HTTP ${res.status}`)
+      return JSON.parse(res.text) as Record<string, unknown>
+    }
+    const configured =
+      (typeof ctx.settings?.projectId === 'string' ? ctx.settings.projectId : undefined) ??
+      ctx.host.env(ENV_PROJECT)
+    let projectIds: string[]
+    if (configured) {
+      projectIds = [configured]
+    } else {
+      const body = await get('/projects')
+      const projects = Array.isArray(body.projects) ? body.projects : []
+      projectIds = projects
+        .map((p) => (p as { project_id?: string }).project_id)
+        .filter((id): id is string => Boolean(id))
+    }
+    let hours = 0
+    let tokens = 0
+    let requests = 0
+    for (const id of projectIds) {
+      const body = await get(`/projects/${id}/usage/breakdown`)
+      for (const r of (Array.isArray(body.results) ? body.results : []) as UsageResult[]) {
+        hours += num(r.total_hours)
+        tokens += num(r.tokens_in) + num(r.tokens_out)
+        requests += num(r.requests)
+      }
+    }
+    const now = ctx.host.now().toISOString()
+    const usage: UsageSnapshot = {
+      providerId: 'deepgram',
+      identity: {
+        providerId: 'deepgram',
+        loginMethod: 'api',
+        accountOrganization: projectIds.length === 1 ? projectIds[0] : `${projectIds.length} projects`,
+      },
+      totals: { tokens, requests },
+      dataConfidence: tokens > 0 || requests > 0 || hours > 0 ? 'exact' : 'unknown',
+      updatedAt: now,
+    }
+    return { usage, sourceLabel: 'Deepgram usage', strategyId: this.id, strategyKind: this.kind }
+  },
+  shouldFallback() {
+    return false
+  },
+}
+
+export const deepgramProvider: ProviderDescriptor = {
+  id: 'deepgram',
+  metadata: {
+    displayName: 'Deepgram',
+    sessionLabel: 'Usage',
+    weeklyLabel: 'Requests',
+    dashboardUrl: 'https://console.deepgram.com/usage',
+    color: '#13ef93',
+  },
+  strategies: (mode) => forMode([deepgramStrategy], mode),
+}

package/src/providers/groq.ts

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Groq provider — port of CodexBarCore/Providers/Groq. Groq exposes NO balance or
+// quota; its only usage signal is an enterprise Prometheus metrics API reporting
+// current throughput RATES. We faithfully report those (requests/min, tokens/min)
+// as an honest throughput snapshot — not a cumulative total (Groq gives no total).
+// Four parallel PromQL queries against {base}/metrics/prometheus/api/v1/query.
+
+import type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { UsageSnapshot } from '../types.js'
+import { bearer, resolveApiKey } from './api-token.js'
+
+const ENV_KEYS = ['GROQ_API_KEY']
+const ENV_URL = 'GROQ_API_URL'
+const DEFAULT_BASE = 'https://api.groq.com/v1'
+
+const QUERIES = {
+  requests: 'sum(model_project_id_status_code:requests:rate5m)',
+  tokensIn: 'sum(model_project_id:tokens_in:rate5m)',
+  tokensOut: 'sum(model_project_id:tokens_out:rate5m)',
+} as const
+
+interface PrometheusResponse {
+  status?: string
+  data?: { result?: Array<{ value?: [number, string | number] }> }
+}
+
+/** Sum the scalar value across every returned Prometheus series (per-second rate). */
+const sumRate = (body: PrometheusResponse): number => {
+  if (body.status !== 'success') return 0
+  let total = 0
+  for (const series of body.data?.result ?? []) {
+    const raw = series.value?.[1]
+    const n = typeof raw === 'number' ? raw : Number(raw)
+    if (Number.isFinite(n)) total += n
+  }
+  return total
+}
+
+const groqStrategy: ProviderFetchStrategy = {
+  id: 'groq.apiToken',
+  kind: 'apiToken',
+  async isAvailable(ctx) {
+    return Boolean(resolveApiKey(ctx, ENV_KEYS))
+  },
+  async fetch(ctx: ProviderFetchContext): Promise<ProviderFetchResult> {
+    const key = resolveApiKey(ctx, ENV_KEYS)
+    if (!key) throw new Error('groq: no API key')
+    const base = ctx.settings?.baseUrl ?? ctx.host.env(ENV_URL) ?? DEFAULT_BASE
+    const query = async (promql: string): Promise<PrometheusResponse> => {
+      const res = await ctx.host.http({
+        url: `${base}/metrics/prometheus/api/v1/query?query=${encodeURIComponent(promql)}`,
+        headers: bearer(key),
+        timeoutMs: 30_000,
+      })
+      if (res.status !== 200) throw new Error(`groq metrics HTTP ${res.status}`)
+      return JSON.parse(res.text) as PrometheusResponse
+    }
+    const [requests, tokensIn, tokensOut] = await Promise.all([
+      query(QUERIES.requests),
+      query(QUERIES.tokensIn),
+      query(QUERIES.tokensOut),
+    ])
+    // Per-second rates → per-minute throughput (Groq exposes no cumulative total).
+    const requestsPerMin = Math.round(sumRate(requests) * 60)
+    const tokensPerMin = Math.round((sumRate(tokensIn) + sumRate(tokensOut)) * 60)
+    const now = ctx.host.now().toISOString()
+    const usage: UsageSnapshot = {
+      providerId: 'groq',
+      identity: { providerId: 'groq', loginMethod: 'api' },
+      totals: { tokens: tokensPerMin, requests: requestsPerMin },
+      dataConfidence: 'estimated',
+      updatedAt: now,
+    }
+    return { usage, sourceLabel: 'Groq metrics', strategyId: this.id, strategyKind: this.kind }
+  },
+  shouldFallback() {
+    return false
+  },
+}
+
+export const groqProvider: ProviderDescriptor = {
+  id: 'groq',
+  metadata: {
+    displayName: 'Groq',
+    sessionLabel: 'Throughput (req/min)',
+    weeklyLabel: 'Tokens/min',
+    dashboardUrl: 'https://console.groq.com/metrics',
+    color: '#f55036',
+  },
+  strategies: (mode) => forMode([groqStrategy], mode),
+}