@emesoft/tokenhub 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,24 @@
 # @emesoft/tokenhub
 
-Pair Claude Code on this machine with a TokenHub pool. No dependencies, Node 18+.
+Pair Claude Code on this machine with a [TokenHub](https://tokenhub.aimpact.io.vn) pool. No dependencies, Node 18+.
 
 ```
-npx @emesoft/tokenhub connect https://pool.example.com
+npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn
+npx @emesoft/tokenhub usage
+npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
 ```
 
 `connect` prints a short code and opens your browser. Confirm the code on the pool's member site and the CLI writes `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` into `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). Other settings are kept, and the previous file is saved as `settings.json.bak`. Each paired machine gets its own key, which you can revoke on the Keys page.
 
+`usage` shows today's and this week's spend against your limits, your credit and the pool's health (`--json` for the raw report). It exits 2 when the pool would currently refuse your requests (out of credit or budget reached).
+
+`dashboard` is a live full-screen view: today's and this week's spend as bars against your limits (green under 70%, orange to 90%, red above), credit, pool health, a banner when you are blocked, and a table of your recent requests, newest first. It refreshes every 3 seconds (`--interval <sec>`, minimum 2). Press `q` or Ctrl+C to quit and `r` to refresh now. On a connection error it keeps the last good screen, shows `reconnecting…` and backs off (honouring `retry-after`). Without a terminal, with `NO_COLOR` set or with `--once`, it prints one plain frame and exits (code 2 when blocked, like `usage`).
+
+Requests to the pool carry your key and one extra header, `x-tokenhub-cli: <version>` (this CLI's version), and nothing else.
+
 `disconnect` removes only those two entries.
 
 If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, it overrides `settings.json`.
+
+Sign in, manage your keys and top up at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn). The setup guide there has this command with your pool address filled in.

package/bin/tokenhub.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
 import { runConnect } from "../lib/pair.js";
-import { disconnectSettings, settingsPath } from "../lib/settings.js";
+import { disconnectSettings, readSettings, settingsPath } from "../lib/settings.js";
+import { fetchUsage, formatUsage, resolveCredentials } from "../lib/usage.js";
 
 const HELP = `tokenhub - pair Claude Code with a TokenHub pool
 
 Usage:
   tokenhub connect <poolUrl>   Pair this machine and write ~/.claude/settings.json
+  tokenhub usage [--json]      Show today's and this week's spend, credit and pool health
+  tokenhub dashboard [--interval <sec>] [--once]
+                               Live full-screen view of spend, pool health and recent requests (q quits)
   tokenhub disconnect          Remove the pool entries from settings.json
   tokenhub --help | --version
 `;
@@ -37,6 +42,35 @@ async function main(argv) {
     process.once("SIGINT", () => controller.abort());
     return runConnect({ poolUrl: arg, settingsFile: file, signal: controller.signal });
   }
+  if (command === "usage") {
+    try {
+      const credentials = resolveCredentials(readSettings(file).settings);
+      if (!credentials) {
+        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        return 1;
+      }
+      const report = await fetchUsage(credentials.baseUrl, credentials.key);
+      console.log(arg === "--json" ? JSON.stringify(report, null, 2) : formatUsage(report));
+      return report.blocked ? 2 : 0;
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      return 1;
+    }
+  }
+  if (command === "dashboard") {
+    try {
+      const options = parseDashboardArgs(argv.slice(1));
+      const credentials = resolveCredentials(readSettings(file).settings);
+      if (!credentials) {
+        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        return 1;
+      }
+      return await runDashboard(credentials, options);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      return 1;
+    }
+  }
   if (command === "disconnect") {
     try {
       console.log(disconnectSettings(file) ? `Disconnected. Updated ${file}` : `Nothing to remove in ${file}`);

package/lib/dashboard.d.ts

@@ -0,0 +1,34 @@
+export interface DashboardState {
+  report: Record<string, any> | null;
+  recent: Record<string, any>[];
+  refreshedAt: number | null;
+  error: string | null;
+  intervalSec: number;
+  poolHost?: string;
+  timeZone?: string;
+}
+export const DEFAULT_INTERVAL_SEC: number;
+export const MIN_INTERVAL_SEC: number;
+export function parseDashboardArgs(args: string[]): { intervalSec: number; once: boolean };
+export function renderFrame(state: DashboardState, view: { columns: number; rows: number; color: boolean; now: number; fill?: boolean }): string;
+export function startPolling(
+  credentials: { baseUrl: string; key: string },
+  options: {
+    intervalMs: number;
+    getLimit: () => number;
+    onState: (state: DashboardState) => void;
+    signal: AbortSignal;
+    fetchImpl?: typeof fetch;
+    timeZone?: string;
+  },
+): { done: Promise<void>; refreshNow: () => void };
+export function runDashboard(
+  credentials: { baseUrl: string; key: string },
+  options: { intervalSec: number; once: boolean },
+  io?: {
+    stdout?: NodeJS.WriteStream;
+    stdin?: NodeJS.ReadStream;
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+  },
+): Promise<number>;

package/lib/dashboard.js

@@ -0,0 +1,379 @@
+import { fetchRecent, fetchUsage } from "./usage.js";
+
+export const DEFAULT_INTERVAL_SEC = 3;
+export const MIN_INTERVAL_SEC = 2;
+const MAX_BACKOFF_MS = 30_000;
+const BAR_WIDTH = 20;
+const ENTER_SCREEN = "\x1b[?1049h\x1b[?25l";
+const LEAVE_SCREEN = "\x1b[?25h\x1b[?1049l";
+const COLORS = { green: "32", clay: "38;5;173", red: "31", grey: "90", bold: "1" };
+const ANSI = /\x1b\[[0-9;]*m/y;
+
+/**
+ * Parse the arguments after `dashboard`.
+ * @param {string[]} args Raw arguments.
+ * @returns {{ intervalSec: number, once: boolean }} Validated options.
+ * @throws {Error} On an unknown flag or an interval that is not a number of at least MIN_INTERVAL_SEC.
+ */
+export function parseDashboardArgs(args) {
+  let intervalSec = DEFAULT_INTERVAL_SEC;
+  let once = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--once") once = true;
+    else if (args[i] === "--interval") {
+      intervalSec = Number(args[++i]);
+      if (!Number.isFinite(intervalSec) || intervalSec < MIN_INTERVAL_SEC) {
+        throw new Error(`--interval must be a number of seconds, ${MIN_INTERVAL_SEC} or more.`);
+      }
+    } else throw new Error(`Unknown option: ${args[i]}`);
+  }
+  return { intervalSec, once };
+}
+
+/**
+ * Wrap text in an SGR colour when colour is on.
+ * @param {boolean} color Whether to emit escape codes.
+ * @param {keyof typeof COLORS} name Colour name.
+ * @param {string} text Text to paint.
+ * @returns {string} The text, painted or untouched.
+ */
+function paint(color, name, text) {
+  return color ? `\x1b[${COLORS[name]}m${text}\x1b[0m` : text;
+}
+
+/**
+ * Shorten text to a width, marking the cut with an ellipsis.
+ * @param {string} text Plain text.
+ * @param {number} width Maximum visible width.
+ * @returns {string} Text of at most `width` characters.
+ */
+function truncate(text, width) {
+  if (text.length <= width) return text;
+  return width <= 1 ? text.slice(0, Math.max(width, 0)) : `${text.slice(0, width - 1)}…`;
+}
+
+/**
+ * Cut a line that may contain SGR codes to a visible width so it never wraps.
+ * @param {string} line Line with optional colour codes.
+ * @param {number} columns Maximum visible width.
+ * @returns {string} The line, closed with a reset when it was cut.
+ */
+function clip(line, columns) {
+  let out = "";
+  let visible = 0;
+  let i = 0;
+  while (i < line.length) {
+    ANSI.lastIndex = i;
+    const code = ANSI.exec(line);
+    if (code) {
+      out += code[0];
+      i += code[0].length;
+    } else if (visible < columns) {
+      out += line[i++];
+      visible++;
+    } else return `${out}\x1b[0m`;
+  }
+  return out;
+}
+
+/**
+ * Format a dollar amount.
+ * @param {number} amount USD.
+ * @returns {string} For example `$1.20`, or `$0.0042` for amounts under a cent.
+ */
+function money(amount) {
+  const n = Number(amount) || 0;
+  return n > 0 && n < 0.01 ? `$${n.toFixed(4)}` : `$${n.toFixed(2)}`;
+}
+
+/**
+ * Format a token count compactly.
+ * @param {number | null | undefined} count Tokens.
+ * @returns {string} For example `842`, `12.3k` or `1.2M`; `-` when unknown.
+ */
+function tokens(count) {
+  if (count === null || count === undefined) return "-";
+  if (count >= 1e6) return `${(count / 1e6).toFixed(1)}M`;
+  if (count >= 1e4) return `${(count / 1e3).toFixed(1)}k`;
+  return String(count);
+}
+
+/**
+ * Format a latency.
+ * @param {number | null | undefined} ms Milliseconds.
+ * @returns {string} For example `340ms` or `2.4s`; `-` when unknown.
+ */
+function latency(ms) {
+  if (ms === null || ms === undefined) return "-";
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+}
+
+/**
+ * Format a time of day as HH:MM:SS.
+ * @param {string | number} when ISO string or epoch milliseconds.
+ * @param {string | undefined} timeZone IANA zone (system default when omitted).
+ * @returns {string} Time of day.
+ */
+function clock(when, timeZone) {
+  return new Date(when).toLocaleTimeString("en-GB", { timeZone, hour12: false });
+}
+
+/**
+ * Draw one spend window as a bar against its limit.
+ * @param {string} label Row label.
+ * @param {{ spent_usd: number, limit_usd: number | null }} window Spend and limit.
+ * @param {number} barWidth Cells in the bar.
+ * @param {boolean} color Whether to emit colour.
+ * @returns {string} One line.
+ */
+function spendLine(label, window, barWidth, color) {
+  const head = label.padEnd(8);
+  if (window.limit_usd === null || window.limit_usd === undefined) {
+    return `${head}${paint(color, "grey", "░".repeat(barWidth))} ${money(window.spent_usd)}  ${paint(color, "grey", "no limit")}`;
+  }
+  const ratio = window.limit_usd > 0 ? window.spent_usd / window.limit_usd : 1;
+  const tone = ratio > 0.9 ? "red" : ratio >= 0.7 ? "clay" : "green";
+  const filled = Math.round(Math.min(ratio, 1) * barWidth);
+  const bar = paint(color, tone, "█".repeat(filled)) + paint(color, "grey", "░".repeat(barWidth - filled));
+  return `${head}${bar} ${money(window.spent_usd)} / ${money(window.limit_usd)}  ${paint(color, tone, `${Math.round(ratio * 100)}%`)}`;
+}
+
+/**
+ * Explain a block in one line for the banner.
+ * @param {Record<string, any>} report Status report with `blocked` set.
+ * @param {string | undefined} timeZone IANA zone for the lift time.
+ * @returns {string} Banner text.
+ */
+function blockedText(report, timeZone) {
+  if (report.blocked_reason === "credit") return "BLOCKED: out of credit. Top up on the member site.";
+  const period = report.blocked_reason === "weekly_budget" ? "weekly" : "daily";
+  const lifts = report.blocked_until ? `, lifts ${new Date(report.blocked_until).toLocaleString("en-GB", { timeZone, dateStyle: "medium", timeStyle: "short" })}` : "";
+  return `BLOCKED: ${period} budget reached${lifts}.`;
+}
+
+/**
+ * Pick the optional table columns that fit the terminal width.
+ * @param {number} columns Terminal width.
+ * @returns {{ latency: boolean, tokens: boolean }} Which optional columns to show.
+ */
+function tableLayout(columns) {
+  return { latency: columns >= 50, tokens: columns >= 70 };
+}
+
+/**
+ * Colour name for an HTTP status.
+ * @param {number} status HTTP status of a logged request.
+ * @returns {keyof typeof COLORS} Green below 400, clay for 4xx, red otherwise.
+ */
+function statusTone(status) {
+  return status < 400 ? "green" : status < 500 ? "clay" : "red";
+}
+
+/**
+ * Render one request as a table row.
+ * @param {Record<string, any>} request Entry from `/member/api/recent`.
+ * @param {{ latency: boolean, tokens: boolean }} layout Visible columns.
+ * @param {number} modelWidth Width reserved for the model name.
+ * @param {boolean} color Whether to emit colour.
+ * @param {string | undefined} timeZone IANA zone.
+ * @returns {string} One line.
+ */
+function requestRow(request, layout, modelWidth, color, timeZone) {
+  const cells = [clock(request.started_at, timeZone), truncate(String(request.model ?? "-"), modelWidth).padEnd(modelWidth)];
+  cells.push(paint(color, statusTone(request.status), String(request.status).padEnd(6)));
+  if (layout.latency) cells.push(latency(request.latency_ms).padStart(7));
+  if (layout.tokens) cells.push(tokens(request.input_tokens).padStart(7), tokens(request.output_tokens).padStart(7));
+  cells.push(money(request.usd).padStart(8));
+  return cells.join(" ");
+}
+
+/**
+ * Render the whole dashboard as text. Pure: no I/O, so it can be tested without a terminal.
+ * @param {{ report: Record<string, any> | null, recent: Record<string, any>[], refreshedAt: number | null, error: string | null, intervalSec: number, poolHost?: string, timeZone?: string }} state Latest poll result.
+ * @param {{ columns: number, rows: number, color: boolean, now: number, fill?: boolean }} view Terminal size, colour switch, current epoch ms and whether to pad to `rows` so the footer sits on the last row (default true).
+ * @returns {string} Lines joined with `\n`, each at most `columns` wide, at most `rows` lines, no trailing newline.
+ */
+export function renderFrame(state, { columns, rows, color, now, fill = true }) {
+  const { report, recent, refreshedAt, error, intervalSec, timeZone } = state;
+  const lines = [];
+  const stale = refreshedAt !== null && now - refreshedAt > intervalSec * 2000 + 1000;
+  const refreshed = refreshedAt === null ? "waiting for first refresh" : `refreshed ${clock(refreshedAt, timeZone)}${stale ? " (stale)" : ""}`;
+  const title = `${report ? report.member : "TokenHub"}${state.poolHost ? ` @ ${state.poolHost}` : ""}`;
+  const right = `${refreshed} · every ${intervalSec}s`;
+  lines.push(`${paint(color, "bold", title)}${" ".repeat(Math.max(2, columns - title.length - right.length))}${paint(color, "grey", right)}`);
+  lines.push("");
+
+  if (report) {
+    const barWidth = Math.max(6, Math.min(BAR_WIDTH, columns - 40));
+    lines.push(spendLine("Today", report.today, barWidth, color), spendLine("Week", report.week, barWidth, color));
+    const poolState = report.pool?.state ?? "unknown";
+    const poolTone = poolState === "ok" ? "green" : poolState === "degraded" ? "clay" : poolState === "down" ? "red" : "grey";
+    lines.push(`${"Credit".padEnd(8)}${money(report.credit_usd)}   Pool ${paint(color, poolTone, poolState)}`);
+    if (report.blocked) lines.push(paint(color, "red", blockedText(report, timeZone)));
+  } else {
+    lines.push(paint(color, "grey", "No data yet."));
+  }
+  lines.push("");
+
+  const footer = error ? paint(color, "red", `reconnecting… ${error}`) : paint(color, "grey", "q quit · r refresh now");
+  const layout = tableLayout(columns);
+  const fixed = 8 + 1 + 6 + 1 + 8 + (layout.latency ? 8 : 0) + (layout.tokens ? 16 : 0) + 1;
+  const modelWidth = Math.max(8, columns - fixed);
+  const header = ["Time".padEnd(8), "Model".padEnd(modelWidth), "Status".padEnd(6)];
+  if (layout.latency) header.push("Latency".padStart(7));
+  if (layout.tokens) header.push("In".padStart(7), "Out".padStart(7));
+  header.push("$".padStart(8));
+  lines.push(paint(color, "grey", header.join(" ")));
+  const room = Math.max(0, rows - lines.length - 1);
+  if (recent.length === 0) {
+    if (room > 0) lines.push(paint(color, "grey", "No requests yet."));
+  } else {
+    for (const request of recent.slice(0, room)) lines.push(requestRow(request, layout, modelWidth, color, timeZone));
+  }
+  while (fill && lines.length < rows - 1) lines.push("");
+  lines.push(footer);
+  return lines.slice(-Math.max(rows, 1)).map((line) => clip(line, columns)).join("\n");
+}
+
+/**
+ * Poll status and recent requests until aborted, keeping the last good data when a poll fails.
+ * Failures back off exponentially; a 429 waits at least its `retry-after`.
+ * @param {{ baseUrl: string, key: string }} credentials Pool and key.
+ * @param {{ intervalMs: number, getLimit: () => number, onState: (state: Record<string, any>) => void, signal: AbortSignal, fetchImpl?: typeof fetch, timeZone?: string }} options Poll settings; `onState` receives a fresh state object after every poll.
+ * @returns {{ done: Promise<void>, refreshNow: () => void }} `done` settles after abort; `refreshNow` cuts the current wait short.
+ */
+export function startPolling(credentials, { intervalMs, getLimit, onState, signal, fetchImpl = fetch, timeZone }) {
+  let state = { report: null, recent: [], refreshedAt: null, error: null, intervalSec: intervalMs / 1000, poolHost: new URL(credentials.baseUrl).host, timeZone };
+  let failures = 0;
+  let wake = () => {};
+
+  const poll = async () => {
+    const [status, recentResult] = await Promise.allSettled([
+      fetchUsage(credentials.baseUrl, credentials.key, fetchImpl),
+      fetchRecent(credentials.baseUrl, credentials.key, getLimit(), fetchImpl),
+    ]);
+    const failed = [status, recentResult].filter((result) => result.status === "rejected");
+    state = {
+      ...state,
+      report: status.status === "fulfilled" ? status.value : state.report,
+      recent: recentResult.status === "fulfilled" ? (recentResult.value.requests ?? []) : state.recent,
+      refreshedAt: status.status === "fulfilled" ? Date.now() : state.refreshedAt,
+      error: failed.length ? failed[0].reason.message : null,
+    };
+    onState(state);
+    if (!failed.length) {
+      failures = 0;
+      return intervalMs;
+    }
+    failures++;
+    const retryAfterMs = Math.max(0, ...failed.map((result) => (result.reason.retryAfter ?? 0) * 1000));
+    return Math.max(retryAfterMs, Math.min(intervalMs * 2 ** failures, MAX_BACKOFF_MS));
+  };
+
+  const wait = (ms) =>
+    new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      wake = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      signal.addEventListener("abort", wake, { once: true });
+    });
+
+  const done = (async () => {
+    while (!signal.aborted) {
+      const delay = await poll();
+      if (!signal.aborted) await wait(delay);
+    }
+  })();
+  return { done, refreshNow: () => wake() };
+}
+
+/**
+ * Run the dashboard: a live full-screen view on a TTY, or one plain frame otherwise.
+ * @param {{ baseUrl: string, key: string }} credentials Pool and key.
+ * @param {{ intervalSec: number, once: boolean }} options Parsed `dashboard` options.
+ * @param {{ stdout?: NodeJS.WriteStream, stdin?: NodeJS.ReadStream, env?: Record<string, string | undefined>, fetchImpl?: typeof fetch }} [io] Streams and environment (injected in tests).
+ * @returns {Promise<number>} Exit code: 0 on quit, 1 on a failed single frame, 2 when a single frame shows a block.
+ */
+export async function runDashboard(credentials, { intervalSec, once }, { stdout = process.stdout, stdin = process.stdin, env = process.env, fetchImpl = fetch } = {}) {
+  const live = !once && stdout.isTTY && stdin.isTTY && !env.NO_COLOR;
+  if (!live) return printOnce(credentials, intervalSec, stdout, fetchImpl);
+
+  const controller = new AbortController();
+  const size = () => ({ columns: stdout.columns || 80, rows: stdout.rows || 24 });
+  let state = null;
+  const draw = () => {
+    if (!state) return;
+    const { columns, rows } = size();
+    const frame = renderFrame(state, { columns, rows, color: true, now: Date.now() });
+    stdout.write(`\x1b[H${frame.split("\n").map((line) => `${line}\x1b[K`).join("\n")}\x1b[J`);
+  };
+  const restore = () => {
+    if (stdin.isRaw) stdin.setRawMode(false);
+    stdout.write(LEAVE_SCREEN);
+  };
+  const fail = (error) => {
+    restore();
+    console.error(`Error: ${error?.message ?? error}`);
+    process.exit(1);
+  };
+
+  stdout.write(ENTER_SCREEN);
+  stdin.setRawMode(true);
+  stdin.resume();
+  process.once("exit", restore);
+  process.once("SIGTERM", () => controller.abort());
+  process.once("SIGINT", () => controller.abort());
+  process.once("uncaughtException", fail);
+  process.once("unhandledRejection", fail);
+  stdout.on("resize", draw);
+
+  const polling = startPolling(credentials, {
+    intervalMs: intervalSec * 1000,
+    getLimit: () => Math.min(Math.max(size().rows, 10), 100),
+    onState: (next) => {
+      state = next;
+      draw();
+    },
+    signal: controller.signal,
+    fetchImpl,
+  });
+  stdin.on("data", (chunk) => {
+    const keys = String(chunk);
+    if (keys === "q" || keys === "Q" || keys === "\x03") controller.abort();
+    else if (keys === "r" || keys === "R") polling.refreshNow();
+  });
+  const redraw = setInterval(draw, 1000);
+
+  await polling.done;
+  clearInterval(redraw);
+  stdout.off("resize", draw);
+  stdin.pause();
+  restore();
+  return 0;
+}
+
+/**
+ * Print a single plain (uncoloured) frame and finish.
+ * @param {{ baseUrl: string, key: string }} credentials Pool and key.
+ * @param {number} intervalSec Interval shown in the header.
+ * @param {NodeJS.WriteStream} stdout Output stream.
+ * @param {typeof fetch} fetchImpl Fetch implementation.
+ * @returns {Promise<number>} 1 on failure, 2 when blocked, else 0.
+ */
+async function printOnce(credentials, intervalSec, stdout, fetchImpl) {
+  const rows = stdout.rows || 30;
+  try {
+    const [report, recent] = await Promise.all([
+      fetchUsage(credentials.baseUrl, credentials.key, fetchImpl),
+      fetchRecent(credentials.baseUrl, credentials.key, Math.min(Math.max(rows, 10), 100), fetchImpl),
+    ]);
+    const state = { report, recent: recent.requests ?? [], refreshedAt: Date.now(), error: null, intervalSec, poolHost: new URL(credentials.baseUrl).host };
+    stdout.write(`${renderFrame(state, { columns: stdout.columns || 80, rows, color: false, now: Date.now(), fill: false })}\n`);
+    return report.blocked ? 2 : 0;
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    return 1;
+  }
+}

package/lib/usage.d.ts

@@ -0,0 +1,7 @@
+export function resolveCredentials(
+  settings: Record<string, any>,
+  env?: Record<string, string | undefined>,
+): { baseUrl: string; key: string } | null;
+export function fetchUsage(baseUrl: string, key: string, fetchImpl?: typeof fetch): Promise<Record<string, any>>;
+export function fetchRecent(baseUrl: string, key: string, limit: number, fetchImpl?: typeof fetch): Promise<Record<string, any>>;
+export function formatUsage(report: Record<string, any>, locale?: string, timeZone?: string): string;

package/lib/usage.js

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+
+const STATUS_PATH = "/member/api/status";
+const RECENT_PATH = "/member/api/recent";
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * Pick the pool URL and key the way Claude Code does: shell variables win over settings.json.
+ * @param {Record<string, any>} settings Parsed settings.json ({} when missing).
+ * @param {Record<string, string | undefined>} [env] Environment to read ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN from.
+ * @returns {{ baseUrl: string, key: string } | null} Credentials, or null when either is missing.
+ */
+export function resolveCredentials(settings, env = process.env) {
+  const fromFile = settings?.env ?? {};
+  const baseUrl = env.ANTHROPIC_BASE_URL || fromFile.ANTHROPIC_BASE_URL;
+  const key = env.ANTHROPIC_AUTH_TOKEN || fromFile.ANTHROPIC_AUTH_TOKEN;
+  return baseUrl && key ? { baseUrl: String(baseUrl).replace(/\/+$/, ""), key: String(key) } : null;
+}
+
+/**
+ * GET a JSON endpoint on the pool with the member's key, mapping failures to readable errors.
+ * @param {string} baseUrl Pool origin.
+ * @param {string} path Absolute path (with query) on the pool.
+ * @param {string} key Gateway key.
+ * @param {typeof fetch} fetchImpl Fetch implementation.
+ * @returns {Promise<Record<string, any>>} The parsed body.
+ * @throws {Error} On network errors, 401, 429 (with `retryAfter` seconds when the pool sent it) and other failures.
+ */
+async function getJson(baseUrl, path, key, fetchImpl) {
+  let res;
+  try {
+    res = await fetchImpl(`${baseUrl}${path}`, {
+      headers: { authorization: `Bearer ${key}`, "x-tokenhub-cli": CLI_VERSION },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new Error(`Could not reach ${baseUrl} (${error.message})`);
+  }
+  if (res.status === 401) throw new Error("The pool rejected this key. It may be revoked; run `tokenhub connect` again.");
+  if (res.status === 429) {
+    const retryAfter = res.headers.get("retry-after");
+    throw Object.assign(new Error(`Too many requests. Retry in ${retryAfter ?? "a few"}s.`), {
+      retryAfter: Number(retryAfter) > 0 ? Number(retryAfter) : undefined,
+    });
+  }
+  if (!res.ok) throw new Error(`Pool answered HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Fetch the member's status from the pool.
+ * @param {string} baseUrl Pool origin.
+ * @param {string} key Gateway key.
+ * @param {typeof fetch} [fetchImpl] Fetch implementation (injected in tests).
+ * @returns {Promise<Record<string, any>>} The `GET /member/api/status` body.
+ * @throws {Error} With a user-readable message on network errors, 401/429 and other failures.
+ */
+export function fetchUsage(baseUrl, key, fetchImpl = fetch) {
+  return getJson(baseUrl, STATUS_PATH, key, fetchImpl);
+}
+
+/**
+ * Fetch the member's most recent requests, newest first.
+ * @param {string} baseUrl Pool origin.
+ * @param {string} key Gateway key.
+ * @param {number} limit How many requests to ask for.
+ * @param {typeof fetch} [fetchImpl] Fetch implementation (injected in tests).
+ * @returns {Promise<Record<string, any>>} The `GET /member/api/recent` body (`{ requests: [...] }`).
+ * @throws {Error} Same mapping as `fetchUsage`.
+ */
+export function fetchRecent(baseUrl, key, limit, fetchImpl = fetch) {
+  return getJson(baseUrl, `${RECENT_PATH}?limit=${encodeURIComponent(limit)}`, key, fetchImpl);
+}
+
+/**
+ * Render a status report as a few readable lines.
+ * @param {Record<string, any>} report Body returned by `fetchUsage`.
+ * @param {string} [locale] Locale for reset times (system default when omitted).
+ * @param {string} [timeZone] IANA zone for reset times (system default when omitted).
+ * @returns {string} Multi-line text without a trailing newline.
+ */
+export function formatUsage(report, locale, timeZone) {
+  const when = (iso) => new Date(iso).toLocaleString(locale, { timeZone, dateStyle: "medium", timeStyle: "short" });
+  const money = (amount) => `$${Number(amount).toFixed(2)}`;
+  const window = (label, w) => {
+    const spend = w.limit_usd === null ? `${money(w.spent_usd)} (no limit)` : `${money(w.spent_usd)} / ${money(w.limit_usd)}`;
+    return `${label.padEnd(8)}${spend.padEnd(26)}resets ${when(w.resets_at)}`;
+  };
+  const lines = [
+    `${report.member} @ TokenHub`,
+    window("Today", report.today),
+    window("Week", report.week),
+    `${"Credit".padEnd(8)}${money(report.credit_usd)}`,
+    `${"Pool".padEnd(8)}${report.pool?.state ?? "unknown"}`,
+  ];
+  if (report.blocked) lines.push(blockedLine(report, when));
+  return lines.join("\n");
+}
+
+/**
+ * Explain why the gateway would refuse this member's requests.
+ * @param {Record<string, any>} report Status report with `blocked` set.
+ * @param {(iso: string) => string} when Formats an ISO time for display.
+ * @returns {string} One line.
+ */
+function blockedLine(report, when) {
+  if (report.blocked_reason === "credit") return "Blocked: out of credit. Top up on the member site.";
+  const period = report.blocked_reason === "weekly_budget" ? "weekly" : "daily";
+  return `Blocked: ${period} budget reached${report.blocked_until ? `, lifts ${when(report.blocked_until)}` : ""}.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emesoft/tokenhub",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Pair Claude Code on this machine with a TokenHub pool",
   "type": "module",
   "bin": {