@hanzo/usage 0.1.1 → 0.1.2

package/dist/providers/api-token.d.ts

@@ -0,0 +1,36 @@
+import type { ProviderDescriptor, ProviderFetchContext, ProviderFetchStrategy, ProviderMetadata, ProviderSettings } 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 declare const resolveBaseUrl: (ctx: ProviderFetchContext, envKeys?: readonly string[]) => string | undefined;
+/** Resolve an API key from explicit settings, then from host env fallbacks. */
+export declare const resolveApiKey: (ctx: ProviderFetchContext, envKeys?: readonly string[]) => string | undefined;
+export declare const makeApiTokenStrategy: (config: ApiTokenProviderConfig) => ProviderFetchStrategy;
+/** Build a single-strategy apiToken ProviderDescriptor. */
+export declare const makeApiTokenProvider: (config: ApiTokenProviderConfig) => ProviderDescriptor;
+/** Numeric coercion shared by mappers; non-finite/absent → undefined. */
+export declare const numberOrUndefined: (v: unknown) => number | undefined;
+/** Bearer auth header helper. */
+export declare const bearer: (key: string) => Record<string, string>;

package/dist/providers/api-token.js

@@ -0,0 +1,99 @@
+// 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 { forMode } from '../provider.js';
+/** Resolve a base URL from explicit settings, then from host env fallbacks. */
+export const resolveBaseUrl = (ctx, envKeys = []) => {
+    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, envKeys = []) => {
+    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) => {
+    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) {
+            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 = { ...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;
+            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) => {
+    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) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+/** Bearer auth header helper. */
+export const bearer = (key) => ({
+    Authorization: `Bearer ${key}`,
+    Accept: 'application/json',
+});

package/dist/providers/byo.d.ts

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

package/dist/providers/byo.js

@@ -0,0 +1,114 @@
+// 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 { forMode } from '../provider.js';
+import { bearer, resolveApiKey, resolveBaseUrl } from './api-token.js';
+const ENV_KEYS = ['BYO_API_KEY'];
+const ENV_URL = ['BYO_BASE_URL'];
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const obj = (v) => v && typeof v === 'object' ? v : {};
+const stripV1 = (base) => base.replace(/\/v1\/?$/, '').replace(/\/$/, '');
+const keyInfo = async (ctx, base, key, now) => {
+    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;
+    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, base, key, now) => {
+    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;
+    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 = {
+    id: 'byo.apiToken',
+    kind: 'apiToken',
+    async isAvailable(ctx) {
+        return Boolean(resolveApiKey(ctx, ENV_KEYS) && resolveBaseUrl(ctx, ENV_URL));
+    },
+    async fetch(ctx) {
+        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 = {
+    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/dist/providers/deepgram.d.ts

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

package/dist/providers/deepgram.js

@@ -0,0 +1,83 @@
+// 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 { forMode } from '../provider.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';
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const deepgramStrategy = {
+    id: 'deepgram.apiToken',
+    kind: 'apiToken',
+    async isAvailable(ctx) {
+        return Boolean(resolveApiKey(ctx, ENV_KEYS));
+    },
+    async fetch(ctx) {
+        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) => {
+            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);
+        };
+        const configured = (typeof ctx.settings?.projectId === 'string' ? ctx.settings.projectId : undefined) ??
+            ctx.host.env(ENV_PROJECT);
+        let projectIds;
+        if (configured) {
+            projectIds = [configured];
+        }
+        else {
+            const body = await get('/projects');
+            const projects = Array.isArray(body.projects) ? body.projects : [];
+            projectIds = projects
+                .map((p) => p.project_id)
+                .filter((id) => 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 : [])) {
+                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 = {
+            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 = {
+    id: 'deepgram',
+    metadata: {
+        displayName: 'Deepgram',
+        sessionLabel: 'Usage',
+        weeklyLabel: 'Requests',
+        dashboardUrl: 'https://console.deepgram.com/usage',
+        color: '#13ef93',
+    },
+    strategies: (mode) => forMode([deepgramStrategy], mode),
+};

package/dist/providers/groq.d.ts

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

package/dist/providers/groq.js

@@ -0,0 +1,83 @@
+// 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 { forMode } from '../provider.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)',
+};
+/** Sum the scalar value across every returned Prometheus series (per-second rate). */
+const sumRate = (body) => {
+    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 = {
+    id: 'groq.apiToken',
+    kind: 'apiToken',
+    async isAvailable(ctx) {
+        return Boolean(resolveApiKey(ctx, ENV_KEYS));
+    },
+    async fetch(ctx) {
+        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) => {
+            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);
+        };
+        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 = {
+            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 = {
+    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),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/usage",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Track AI provider usage, rate limits, and spend across every Hanzo surface. Headless provider engine + full provider catalog.",
   "license": "MIT",
   "author": "Hanzo AI Inc",

package/src/catalog.ts

@@ -14,6 +14,7 @@ export interface ProviderCatalogEntry {
 
 export const providerCatalog: ProviderCatalogEntry[] = [
   { id: 'hanzo', name: 'Hanzo', color: '#ff2d55' },
+  { id: 'byo', name: 'BYO endpoint', color: '#64748b' },
   { id: 'abacus', name: 'Abacus AI', icon: 'providers/abacus.svg' },
   { id: 'alibaba', name: 'Alibaba', icon: 'providers/alibaba.svg' },
   { id: 'alibabatokenplan', name: 'Alibaba Token Plan' },

package/src/index.ts

@@ -6,18 +6,81 @@ export * from './store.js'
 export { codexProvider } from './providers/codex.js'
 export { claudeProvider } from './providers/claude.js'
 export { hanzoProvider } from './providers/hanzo.js'
+export { groqProvider } from './providers/groq.js'
+export { deepgramProvider } from './providers/deepgram.js'
+export { byoProvider } from './providers/byo.js'
+export * from './providers/api-token.js'
+export {
+  openrouterProvider,
+  deepseekProvider,
+  elevenlabsProvider,
+  poeProvider,
+  veniceProvider,
+  chutesProvider,
+  moonshotProvider,
+  kimiProvider,
+  kimik2Provider,
+  zaiProvider,
+  openaiProvider,
+  litellmProvider,
+  llmproxyProvider,
+  minimaxProvider,
+} from './providers/api-token-providers.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'
+import { groqProvider } from './providers/groq.js'
+import { deepgramProvider } from './providers/deepgram.js'
+import { byoProvider } from './providers/byo.js'
+import {
+  openrouterProvider,
+  deepseekProvider,
+  elevenlabsProvider,
+  poeProvider,
+  veniceProvider,
+  chutesProvider,
+  moonshotProvider,
+  kimiProvider,
+  kimik2Provider,
+  zaiProvider,
+  openaiProvider,
+  litellmProvider,
+  llmproxyProvider,
+  minimaxProvider,
+} from './providers/api-token-providers.js'
 
-/** All built-in providers, registry-style like CodexBar's descriptor registry. */
+/** All built-in providers with a live fetch pipeline, registry-style like
+ *  CodexBar's descriptor registry. Keys are the canonical provider ids. */
 export const providerRegistry: Record<string, ProviderDescriptor> = {
   hanzo: hanzoProvider,
   codex: codexProvider,
   claude: claudeProvider,
+  openai: openaiProvider,
+  openrouter: openrouterProvider,
+  deepseek: deepseekProvider,
+  elevenlabs: elevenlabsProvider,
+  deepgram: deepgramProvider,
+  groq: groqProvider,
+  poe: poeProvider,
+  venice: veniceProvider,
+  chutes: chutesProvider,
+  moonshot: moonshotProvider,
+  kimi: kimiProvider,
+  kimik2: kimik2Provider,
+  zai: zaiProvider,
+  litellm: litellmProvider,
+  llmproxy: llmproxyProvider,
+  minimax: minimaxProvider,
+  byo: byoProvider,
 }
 
 export const allProviders: ProviderDescriptor[] = Object.values(providerRegistry)
+
+/** Provider ids that have a live native pipeline — UIs badge catalog entries
+ *  as "In-app tracked" when their id is in this set (the rest are connect-only
+ *  or tracked only via api.hanzo.ai cloud routing). */
+export const trackedProviderIds: readonly string[] = Object.keys(providerRegistry)
+
 export * from './catalog.js'