@inferhub/usage 0.1.0

package/bin/statusline.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const client = await import(pathToFileURL(join(root, "../dist/index.js")).href);
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "{}";
+  }
+}
+
+let session = {};
+try {
+  session = JSON.parse(readStdin() || "{}");
+} catch {
+  session = {};
+}
+
+try {
+  const { usage } = await client.fetchAccountUsageAuto({ window: "day" });
+  const sessionCost =
+    typeof session?.cost?.total_cost_usd === "number"
+      ? session.cost.total_cost_usd
+      : null;
+  const contextPct =
+    typeof session?.context_window?.used_percentage === "number"
+      ? session.context_window.used_percentage
+      : null;
+  const model = session?.model?.display_name || session?.model?.id || null;
+  process.stdout.write(
+    client.formatStatusLine(usage, {
+      sessionCostUsd: sessionCost,
+      contextPct,
+      model,
+    }) + "\n",
+  );
+} catch (e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stdout.write("IH · offline (" + msg.slice(0, 48) + ")\n");
+  process.exitCode = 0;
+}

package/bin/usage.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const client = await import(pathToFileURL(join(root, "../dist/index.js")).href);
+
+const json = process.argv.includes("--json");
+const force = process.argv.includes("--force");
+const windowArg = process.argv.find((a) => a.startsWith("--window="));
+const window = windowArg?.split("=")[1] || "day";
+
+try {
+  const { usage, auth } = await client.fetchAccountUsageAuto({
+    window,
+    force,
+  });
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        { auth: { source: auth.source, baseUrl: auth.baseUrl }, usage },
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    process.stdout.write(client.formatReport(usage) + "\n");
+    process.stdout.write("  (key source: " + auth.source + ")\n");
+  }
+} catch (e) {
+  console.error(e instanceof Error ? e.message : e);
+  process.exitCode = 1;
+}

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
+export declare function normalizeBaseUrl(input?: string | null): string;
+export declare function usageUrl(baseUrl: string, window?: UsageWindowKind, tz?: string): string;
+/** Resolve API key + base URL from env / agent config files. */
+export declare function resolveAuth(overrides?: Partial<ResolvedAuth>): ResolvedAuth | null;
+export declare function fetchAccountUsage(opts: FetchUsageOptions): Promise<AccountUsage>;
+export declare function fetchAccountUsageAuto(opts?: Omit<FetchUsageOptions, "apiKey" | "baseUrl"> & {
+    apiKey?: string;
+    baseUrl?: string;
+}): Promise<{
+    usage: AccountUsage;
+    auth: ResolvedAuth;
+}>;

package/dist/client.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
+const mem = new Map();
+export function normalizeBaseUrl(input) {
+    let u = (input || DEFAULT_BASE_URL).trim().replace(/\/+$/, "");
+    // Accept API root without /v1
+    if (!u.endsWith("/v1")) {
+        u = `${u}/v1`;
+    }
+    return u;
+}
+export function usageUrl(baseUrl, window = "day", tz = "UTC") {
+    const base = normalizeBaseUrl(baseUrl);
+    const q = new URLSearchParams({ window, tz });
+    return `${base}/me/usage?${q.toString()}`;
+}
+/** Resolve API key + base URL from env / agent config files. */
+export function resolveAuth(overrides = {}) {
+    if (overrides.apiKey) {
+        return {
+            apiKey: overrides.apiKey,
+            baseUrl: normalizeBaseUrl(overrides.baseUrl),
+            source: "override",
+        };
+    }
+    const envKey = process.env.INFERHUB_API_KEY ||
+        process.env.ANTHROPIC_AUTH_TOKEN ||
+        process.env.ANTHROPIC_API_KEY ||
+        process.env.OPENAI_API_KEY;
+    const envBase = process.env.INFERHUB_BASE_URL ||
+        process.env.ANTHROPIC_BASE_URL ||
+        process.env.OPENAI_BASE_URL;
+    if (envKey) {
+        return {
+            apiKey: envKey,
+            baseUrl: normalizeBaseUrl(envBase || DEFAULT_BASE_URL),
+            source: "env",
+        };
+    }
+    // OpenCode provider config
+    const oc = tryReadJson(join(homedir(), ".config", "opencode", "opencode.json"));
+    const ocKey = oc?.provider?.inferhub?.options?.apiKey;
+    const ocBase = oc?.provider?.inferhub?.options?.baseURL;
+    if (typeof ocKey === "string" && ocKey) {
+        return {
+            apiKey: ocKey,
+            baseUrl: normalizeBaseUrl(typeof ocBase === "string" ? ocBase : DEFAULT_BASE_URL),
+            source: "opencode.json",
+        };
+    }
+    // Claude settings env
+    const claude = tryReadJson(join(homedir(), ".claude", "settings.json"));
+    const cKey = claude?.env?.ANTHROPIC_AUTH_TOKEN ||
+        claude?.env?.ANTHROPIC_API_KEY ||
+        claude?.env?.INFERHUB_API_KEY;
+    const cBase = claude?.env?.ANTHROPIC_BASE_URL || claude?.env?.INFERHUB_BASE_URL;
+    if (typeof cKey === "string" && cKey) {
+        return {
+            apiKey: cKey,
+            baseUrl: normalizeBaseUrl(typeof cBase === "string" ? cBase : DEFAULT_BASE_URL),
+            source: "claude settings",
+        };
+    }
+    // Codex auth.json
+    const codexAuth = tryReadJson(join(homedir(), ".codex", "auth.json"));
+    const codexKey = codexAuth?.OPENAI_API_KEY;
+    if (typeof codexKey === "string" && codexKey) {
+        return {
+            apiKey: codexKey,
+            baseUrl: normalizeBaseUrl(DEFAULT_BASE_URL),
+            source: "codex auth.json",
+        };
+    }
+    return null;
+}
+function tryReadJson(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function cacheKey(apiKey, window, tz, baseUrl) {
+    const h = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+    return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}`;
+}
+function diskCachePath(key) {
+    const dir = process.env.CLAUDE_PLUGIN_DATA ||
+        process.env.INFERHUB_CACHE_DIR ||
+        join(tmpdir(), "inferhub-usage");
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* ignore */
+    }
+    const safe = createHash("sha256").update(key).digest("hex").slice(0, 24);
+    return join(dir, `usage-${safe}.json`);
+}
+export async function fetchAccountUsage(opts) {
+    const window = opts.window ?? "day";
+    const tz = opts.tz ?? "UTC";
+    const baseUrl = normalizeBaseUrl(opts.baseUrl);
+    const ttlMs = (opts.cacheTtlSeconds ?? 30) * 1000;
+    const key = cacheKey(opts.apiKey, window, tz, baseUrl);
+    const now = Date.now();
+    if (!opts.force) {
+        const hit = mem.get(key);
+        if (hit && hit.expires > now)
+            return hit.value;
+        try {
+            const p = diskCachePath(key);
+            if (existsSync(p)) {
+                const raw = JSON.parse(readFileSync(p, "utf8"));
+                if (raw.expires > now && raw.value?.object === "account.usage") {
+                    mem.set(key, raw);
+                    return raw.value;
+                }
+            }
+        }
+        catch {
+            /* ignore disk cache */
+        }
+    }
+    const url = usageUrl(baseUrl, window, tz);
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("fetch is not available in this runtime");
+    }
+    const res = await fetchImpl(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "x-api-key": opts.apiKey,
+            Accept: "application/json",
+        },
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`InferHub usage HTTP ${res.status}: ${body.slice(0, 300)}`);
+    }
+    const value = (await res.json());
+    if (!value || value.object !== "account.usage") {
+        throw new Error("unexpected usage response shape");
+    }
+    const entry = { expires: now + ttlMs, value };
+    mem.set(key, entry);
+    try {
+        writeFileSync(diskCachePath(key), JSON.stringify(entry));
+    }
+    catch {
+        /* ignore */
+    }
+    return value;
+}
+export async function fetchAccountUsageAuto(opts = {}) {
+    const auth = resolveAuth({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    if (!auth) {
+        throw new Error("No InferHub API key found. Set INFERHUB_API_KEY or configure Claude/Codex/OpenCode via @inferhub/helper.");
+    }
+    const usage = await fetchAccountUsage({
+        ...opts,
+        apiKey: auth.apiKey,
+        baseUrl: auth.baseUrl,
+    });
+    return { usage, auth };
+}

package/dist/format.d.ts

@@ -0,0 +1,12 @@
+import type { AccountUsage } from "./types.js";
+export declare function money(usdc: string | number | null | undefined, digits?: number): string;
+export declare function tokens(n: number | null | undefined): string;
+export declare function shortModel(model: string | null | undefined): string;
+/** Compact one-liner for Claude statusline / Codex Stop summary. */
+export declare function formatStatusLine(usage: AccountUsage, extras?: {
+    sessionCostUsd?: number | null;
+    contextPct?: number | null;
+    model?: string | null;
+}): string;
+/** Multi-line human report for /usage skills. */
+export declare function formatReport(usage: AccountUsage): string;

package/dist/format.js

@@ -0,0 +1,61 @@
+export function money(usdc, digits = 2) {
+    const n = Number(usdc ?? 0);
+    if (!Number.isFinite(n))
+        return "$0.00";
+    if (Math.abs(n) > 0 && Math.abs(n) < 0.01)
+        return `$${n.toFixed(4)}`;
+    return `$${n.toFixed(digits)}`;
+}
+export function tokens(n) {
+    const v = Number(n ?? 0);
+    if (v >= 1_000_000)
+        return `${(v / 1_000_000).toFixed(1)}M`;
+    if (v >= 1_000)
+        return `${(v / 1_000).toFixed(1)}k`;
+    return String(Math.round(v));
+}
+export function shortModel(model) {
+    if (!model)
+        return "—";
+    const parts = model.split("/");
+    return parts[parts.length - 1] || model;
+}
+/** Compact one-liner for Claude statusline / Codex Stop summary. */
+export function formatStatusLine(usage, extras) {
+    const sess = extras?.sessionCostUsd != null && Number.isFinite(extras.sessionCostUsd)
+        ? money(extras.sessionCostUsd)
+        : null;
+    const day = money(usage.window.spend_usdc);
+    const all = money(usage.all_time.spend_usdc);
+    const bal = money(usage.balance.amount_usdc);
+    const top = shortModel(usage.top_model?.model);
+    const model = extras?.model ? shortModel(extras.model) : null;
+    const ctx = extras?.contextPct != null && Number.isFinite(extras.contextPct)
+        ? `${Math.round(extras.contextPct)}%ctx`
+        : null;
+    const parts = ["IH"];
+    if (model)
+        parts.push(model);
+    if (sess)
+        parts.push(`sess ${sess}`);
+    parts.push(`${usage.window.kind} ${day}`);
+    parts.push(`all ${all}`);
+    parts.push(`bal ${bal}`);
+    parts.push(`top ${top}`);
+    if (ctx)
+        parts.push(ctx);
+    return parts.join(" · ");
+}
+/** Multi-line human report for /usage skills. */
+export function formatReport(usage) {
+    const lines = [
+        "InferHub usage",
+        `  Balance:   ${money(usage.balance.amount_usdc)} USDC`,
+        `  ${usage.window.kind} window (${usage.window.tz}): ${money(usage.window.spend_usdc)} · ${usage.window.requests} req · ${tokens(usage.window.total_tokens)} tok`,
+        `  All-time:  ${money(usage.all_time.spend_usdc)} · ${usage.all_time.requests} req · ${tokens(usage.all_time.total_tokens)} tok`,
+        `  Top model: ${usage.top_model?.model ?? "—"} (${money(usage.top_model?.spend_usdc ?? 0)}, ${usage.top_model?.requests ?? 0} req)`,
+    ];
+    if (usage.cache?.cached)
+        lines.push(`  (cached, ttl ${usage.cache.ttl_seconds}s)`);
+    return lines.join("\n");
+}

package/dist/format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/format.test.js

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { formatStatusLine, money, normalizeBaseUrl, usageUrl } from "./index.js";
+test("normalizeBaseUrl adds /v1", () => {
+    assert.equal(normalizeBaseUrl("https://api.inferhub.dev"), "https://api.inferhub.dev/v1");
+    assert.equal(normalizeBaseUrl("https://api.inferhub.dev/v1/"), "https://api.inferhub.dev/v1");
+});
+test("usageUrl", () => {
+    assert.equal(usageUrl("https://api.inferhub.dev", "day", "UTC"), "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC");
+});
+test("formatStatusLine", () => {
+    const usage = {
+        object: "account.usage",
+        currency: "USDC",
+        balance: { amount_usdc: "1.250000", updated_at: null },
+        window: {
+            kind: "day",
+            tz: "UTC",
+            since: "",
+            until: "",
+            requests: 3,
+            prompt_tokens: 100,
+            completion_tokens: 50,
+            total_tokens: 150,
+            spend_usdc: "0.012000",
+        },
+        all_time: {
+            requests: 10,
+            prompt_tokens: 1000,
+            completion_tokens: 500,
+            total_tokens: 1500,
+            spend_usdc: "0.500000",
+        },
+        top_model: {
+            model: "free/grok/grok-4.5",
+            requests: 8,
+            tokens: 1200,
+            spend_usdc: "0.400000",
+        },
+        cache: { cached: false, ttl_seconds: 30 },
+    };
+    const line = formatStatusLine(usage, {
+        sessionCostUsd: 0.03,
+        contextPct: 12,
+        model: "free/grok/grok-4.5",
+    });
+    assert.match(line, /IH/);
+    assert.match(line, /bal \$1\.25/);
+    assert.match(line, /top grok-4\.5/);
+    assert.equal(money("0.001"), "$0.0010");
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind, } from "./types.js";
+export { DEFAULT_BASE_URL, fetchAccountUsage, fetchAccountUsageAuto, normalizeBaseUrl, resolveAuth, usageUrl, } from "./client.js";
+export { formatReport, formatStatusLine, money, shortModel, tokens } from "./format.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DEFAULT_BASE_URL, fetchAccountUsage, fetchAccountUsageAuto, normalizeBaseUrl, resolveAuth, usageUrl, } from "./client.js";
+export { formatReport, formatStatusLine, money, shortModel, tokens } from "./format.js";

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+export type UsageWindowKind = "day" | "24h" | "7d" | "30d";
+export type AccountUsage = {
+    object: "account.usage";
+    currency: string;
+    balance: {
+        amount_usdc: string;
+        updated_at: string | null;
+    };
+    window: {
+        kind: UsageWindowKind | string;
+        tz: string;
+        since: string;
+        until: string;
+        requests: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        spend_usdc: string;
+    };
+    all_time: {
+        requests: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        spend_usdc: string;
+    };
+    top_model: {
+        model: string;
+        requests: number;
+        tokens: number;
+        spend_usdc: string;
+    } | null;
+    cache: {
+        cached: boolean;
+        ttl_seconds: number;
+    };
+};
+export type FetchUsageOptions = {
+    apiKey: string;
+    /** OpenAI-style base ending in /v1, or API root. Default https://api.inferhub.dev/v1 */
+    baseUrl?: string;
+    window?: UsageWindowKind;
+    tz?: string;
+    /** Force network; ignore process cache */
+    force?: boolean;
+    /** Client-side process cache TTL seconds (default 30) */
+    cacheTtlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+};
+export type ResolvedAuth = {
+    apiKey: string;
+    baseUrl: string;
+    source: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@inferhub/usage",
+  "version": "0.1.0",
+  "description": "Shared InferHub account usage client for coding-agent plugins",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/*.test.js 2>nul || node --import tsx --test src/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "bin": {
+    "inferhub-statusline": "bin/statusline.mjs",
+    "inferhub-usage": "bin/usage.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inferhub/plugins.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://inferhub.dev",
+  "keywords": [
+    "inferhub",
+    "usage",
+    "statusline",
+    "billing"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind } from "./types.js";
+
+export const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
+
+const mem = new Map<string, { expires: number; value: AccountUsage }>();
+
+export function normalizeBaseUrl(input?: string | null): string {
+  let u = (input || DEFAULT_BASE_URL).trim().replace(/\/+$/, "");
+  // Accept API root without /v1
+  if (!u.endsWith("/v1")) {
+    u = `${u}/v1`;
+  }
+  return u;
+}
+
+export function usageUrl(baseUrl: string, window: UsageWindowKind = "day", tz = "UTC"): string {
+  const base = normalizeBaseUrl(baseUrl);
+  const q = new URLSearchParams({ window, tz });
+  return `${base}/me/usage?${q.toString()}`;
+}
+
+/** Resolve API key + base URL from env / agent config files. */
+export function resolveAuth(overrides: Partial<ResolvedAuth> = {}): ResolvedAuth | null {
+  if (overrides.apiKey) {
+    return {
+      apiKey: overrides.apiKey,
+      baseUrl: normalizeBaseUrl(overrides.baseUrl),
+      source: "override",
+    };
+  }
+
+  const envKey =
+    process.env.INFERHUB_API_KEY ||
+    process.env.ANTHROPIC_AUTH_TOKEN ||
+    process.env.ANTHROPIC_API_KEY ||
+    process.env.OPENAI_API_KEY;
+  const envBase =
+    process.env.INFERHUB_BASE_URL ||
+    process.env.ANTHROPIC_BASE_URL ||
+    process.env.OPENAI_BASE_URL;
+
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      baseUrl: normalizeBaseUrl(envBase || DEFAULT_BASE_URL),
+      source: "env",
+    };
+  }
+
+  // OpenCode provider config
+  const oc = tryReadJson(join(homedir(), ".config", "opencode", "opencode.json"));
+  const ocKey = oc?.provider?.inferhub?.options?.apiKey;
+  const ocBase = oc?.provider?.inferhub?.options?.baseURL;
+  if (typeof ocKey === "string" && ocKey) {
+    return {
+      apiKey: ocKey,
+      baseUrl: normalizeBaseUrl(typeof ocBase === "string" ? ocBase : DEFAULT_BASE_URL),
+      source: "opencode.json",
+    };
+  }
+
+  // Claude settings env
+  const claude = tryReadJson(join(homedir(), ".claude", "settings.json"));
+  const cKey =
+    claude?.env?.ANTHROPIC_AUTH_TOKEN ||
+    claude?.env?.ANTHROPIC_API_KEY ||
+    claude?.env?.INFERHUB_API_KEY;
+  const cBase = claude?.env?.ANTHROPIC_BASE_URL || claude?.env?.INFERHUB_BASE_URL;
+  if (typeof cKey === "string" && cKey) {
+    return {
+      apiKey: cKey,
+      baseUrl: normalizeBaseUrl(typeof cBase === "string" ? cBase : DEFAULT_BASE_URL),
+      source: "claude settings",
+    };
+  }
+
+  // Codex auth.json
+  const codexAuth = tryReadJson(join(homedir(), ".codex", "auth.json"));
+  const codexKey = codexAuth?.OPENAI_API_KEY;
+  if (typeof codexKey === "string" && codexKey) {
+    return {
+      apiKey: codexKey,
+      baseUrl: normalizeBaseUrl(DEFAULT_BASE_URL),
+      source: "codex auth.json",
+    };
+  }
+
+  return null;
+}
+
+function tryReadJson(path: string): any | null {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function cacheKey(apiKey: string, window: string, tz: string, baseUrl: string): string {
+  const h = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+  return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}`;
+}
+
+function diskCachePath(key: string): string {
+  const dir =
+    process.env.CLAUDE_PLUGIN_DATA ||
+    process.env.INFERHUB_CACHE_DIR ||
+    join(tmpdir(), "inferhub-usage");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    /* ignore */
+  }
+  const safe = createHash("sha256").update(key).digest("hex").slice(0, 24);
+  return join(dir, `usage-${safe}.json`);
+}
+
+export async function fetchAccountUsage(opts: FetchUsageOptions): Promise<AccountUsage> {
+  const window = opts.window ?? "day";
+  const tz = opts.tz ?? "UTC";
+  const baseUrl = normalizeBaseUrl(opts.baseUrl);
+  const ttlMs = (opts.cacheTtlSeconds ?? 30) * 1000;
+  const key = cacheKey(opts.apiKey, window, tz, baseUrl);
+  const now = Date.now();
+
+  if (!opts.force) {
+    const hit = mem.get(key);
+    if (hit && hit.expires > now) return hit.value;
+    try {
+      const p = diskCachePath(key);
+      if (existsSync(p)) {
+        const raw = JSON.parse(readFileSync(p, "utf8")) as {
+          expires: number;
+          value: AccountUsage;
+        };
+        if (raw.expires > now && raw.value?.object === "account.usage") {
+          mem.set(key, raw);
+          return raw.value;
+        }
+      }
+    } catch {
+      /* ignore disk cache */
+    }
+  }
+
+  const url = usageUrl(baseUrl, window, tz);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("fetch is not available in this runtime");
+  }
+
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${opts.apiKey}`,
+      "x-api-key": opts.apiKey,
+      Accept: "application/json",
+    },
+    signal: opts.signal,
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`InferHub usage HTTP ${res.status}: ${body.slice(0, 300)}`);
+  }
+
+  const value = (await res.json()) as AccountUsage;
+  if (!value || value.object !== "account.usage") {
+    throw new Error("unexpected usage response shape");
+  }
+
+  const entry = { expires: now + ttlMs, value };
+  mem.set(key, entry);
+  try {
+    writeFileSync(diskCachePath(key), JSON.stringify(entry));
+  } catch {
+    /* ignore */
+  }
+  return value;
+}
+
+export async function fetchAccountUsageAuto(
+  opts: Omit<FetchUsageOptions, "apiKey" | "baseUrl"> & {
+    apiKey?: string;
+    baseUrl?: string;
+  } = {},
+): Promise<{ usage: AccountUsage; auth: ResolvedAuth }> {
+  const auth = resolveAuth({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+  if (!auth) {
+    throw new Error(
+      "No InferHub API key found. Set INFERHUB_API_KEY or configure Claude/Codex/OpenCode via @inferhub/helper.",
+    );
+  }
+  const usage = await fetchAccountUsage({
+    ...opts,
+    apiKey: auth.apiKey,
+    baseUrl: auth.baseUrl,
+  });
+  return { usage, auth };
+}

package/src/format.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { formatStatusLine, money, normalizeBaseUrl, usageUrl } from "./index.js";
+import type { AccountUsage } from "./types.js";
+
+test("normalizeBaseUrl adds /v1", () => {
+  assert.equal(normalizeBaseUrl("https://api.inferhub.dev"), "https://api.inferhub.dev/v1");
+  assert.equal(normalizeBaseUrl("https://api.inferhub.dev/v1/"), "https://api.inferhub.dev/v1");
+});
+
+test("usageUrl", () => {
+  assert.equal(
+    usageUrl("https://api.inferhub.dev", "day", "UTC"),
+    "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC",
+  );
+});
+
+test("formatStatusLine", () => {
+  const usage: AccountUsage = {
+    object: "account.usage",
+    currency: "USDC",
+    balance: { amount_usdc: "1.250000", updated_at: null },
+    window: {
+      kind: "day",
+      tz: "UTC",
+      since: "",
+      until: "",
+      requests: 3,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      total_tokens: 150,
+      spend_usdc: "0.012000",
+    },
+    all_time: {
+      requests: 10,
+      prompt_tokens: 1000,
+      completion_tokens: 500,
+      total_tokens: 1500,
+      spend_usdc: "0.500000",
+    },
+    top_model: {
+      model: "free/grok/grok-4.5",
+      requests: 8,
+      tokens: 1200,
+      spend_usdc: "0.400000",
+    },
+    cache: { cached: false, ttl_seconds: 30 },
+  };
+  const line = formatStatusLine(usage, {
+    sessionCostUsd: 0.03,
+    contextPct: 12,
+    model: "free/grok/grok-4.5",
+  });
+  assert.match(line, /IH/);
+  assert.match(line, /bal \$1\.25/);
+  assert.match(line, /top grok-4\.5/);
+  assert.equal(money("0.001"), "$0.0010");
+});

package/src/format.ts

@@ -0,0 +1,68 @@
+import type { AccountUsage } from "./types.js";
+
+export function money(usdc: string | number | null | undefined, digits = 2): string {
+  const n = Number(usdc ?? 0);
+  if (!Number.isFinite(n)) return "$0.00";
+  if (Math.abs(n) > 0 && Math.abs(n) < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(digits)}`;
+}
+
+export function tokens(n: number | null | undefined): string {
+  const v = Number(n ?? 0);
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return String(Math.round(v));
+}
+
+export function shortModel(model: string | null | undefined): string {
+  if (!model) return "—";
+  const parts = model.split("/");
+  return parts[parts.length - 1] || model;
+}
+
+/** Compact one-liner for Claude statusline / Codex Stop summary. */
+export function formatStatusLine(
+  usage: AccountUsage,
+  extras?: {
+    sessionCostUsd?: number | null;
+    contextPct?: number | null;
+    model?: string | null;
+  },
+): string {
+  const sess =
+    extras?.sessionCostUsd != null && Number.isFinite(extras.sessionCostUsd)
+      ? money(extras.sessionCostUsd)
+      : null;
+  const day = money(usage.window.spend_usdc);
+  const all = money(usage.all_time.spend_usdc);
+  const bal = money(usage.balance.amount_usdc);
+  const top = shortModel(usage.top_model?.model);
+  const model = extras?.model ? shortModel(extras.model) : null;
+  const ctx =
+    extras?.contextPct != null && Number.isFinite(extras.contextPct)
+      ? `${Math.round(extras.contextPct)}%ctx`
+      : null;
+
+  const parts: string[] = ["IH"];
+  if (model) parts.push(model);
+  if (sess) parts.push(`sess ${sess}`);
+  parts.push(`${usage.window.kind} ${day}`);
+  parts.push(`all ${all}`);
+  parts.push(`bal ${bal}`);
+  parts.push(`top ${top}`);
+  if (ctx) parts.push(ctx);
+  return parts.join(" · ");
+}
+
+/** Multi-line human report for /usage skills. */
+export function formatReport(usage: AccountUsage): string {
+  const lines = [
+    "InferHub usage",
+    `  Balance:   ${money(usage.balance.amount_usdc)} USDC`,
+    `  ${usage.window.kind} window (${usage.window.tz}): ${money(usage.window.spend_usdc)} · ${usage.window.requests} req · ${tokens(usage.window.total_tokens)} tok`,
+    `  All-time:  ${money(usage.all_time.spend_usdc)} · ${usage.all_time.requests} req · ${tokens(usage.all_time.total_tokens)} tok`,
+    `  Top model: ${usage.top_model?.model ?? "—"} (${money(usage.top_model?.spend_usdc ?? 0)}, ${usage.top_model?.requests ?? 0} req)`,
+  ];
+  if (usage.cache?.cached) lines.push(`  (cached, ttl ${usage.cache.ttl_seconds}s)`);
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export type {
+  AccountUsage,
+  FetchUsageOptions,
+  ResolvedAuth,
+  UsageWindowKind,
+} from "./types.js";
+export {
+  DEFAULT_BASE_URL,
+  fetchAccountUsage,
+  fetchAccountUsageAuto,
+  normalizeBaseUrl,
+  resolveAuth,
+  usageUrl,
+} from "./client.js";
+export { formatReport, formatStatusLine, money, shortModel, tokens } from "./format.js";

package/src/types.ts

@@ -0,0 +1,58 @@
+export type UsageWindowKind = "day" | "24h" | "7d" | "30d";
+
+export type AccountUsage = {
+  object: "account.usage";
+  currency: string;
+  balance: {
+    amount_usdc: string;
+    updated_at: string | null;
+  };
+  window: {
+    kind: UsageWindowKind | string;
+    tz: string;
+    since: string;
+    until: string;
+    requests: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    spend_usdc: string;
+  };
+  all_time: {
+    requests: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    spend_usdc: string;
+  };
+  top_model: {
+    model: string;
+    requests: number;
+    tokens: number;
+    spend_usdc: string;
+  } | null;
+  cache: {
+    cached: boolean;
+    ttl_seconds: number;
+  };
+};
+
+export type FetchUsageOptions = {
+  apiKey: string;
+  /** OpenAI-style base ending in /v1, or API root. Default https://api.inferhub.dev/v1 */
+  baseUrl?: string;
+  window?: UsageWindowKind;
+  tz?: string;
+  /** Force network; ignore process cache */
+  force?: boolean;
+  /** Client-side process cache TTL seconds (default 30) */
+  cacheTtlSeconds?: number;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+};
+
+export type ResolvedAuth = {
+  apiKey: string;
+  baseUrl: string;
+  source: string;
+};