@emesoft/tokenhub 0.2.0 → 0.3.1

package/README.md

@@ -5,6 +5,7 @@ Pair Claude Code on this machine with a [TokenHub](https://tokenhub.aimpact.io.v
 ```
 npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn
 npx @emesoft/tokenhub usage
+npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
 ```
 
@@ -12,6 +13,10 @@ npx @emesoft/tokenhub disconnect
 
 `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`.

package/bin/tokenhub.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
 import { runConnect } from "../lib/pair.js";
 import { disconnectSettings, readSettings, settingsPath } from "../lib/settings.js";
 import { fetchUsage, formatUsage, resolveCredentials } from "../lib/usage.js";
@@ -9,6 +10,8 @@ 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
 `;
@@ -54,6 +57,20 @@ async function main(argv) {
       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,457 @@
+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}.`;
+}
+
+const MAX_MODEL_WIDTH = 24;
+const MIN_MODEL_WIDTH = 5;
+
+/**
+ * Format a request cost at the precision the pool logs it, so small amounts are never rounded away.
+ * @param {number} amount USD.
+ * @returns {string} For example `$0.0435`.
+ */
+function exactMoney(amount) {
+  return `$${(Number(amount) || 0).toFixed(4)}`;
+}
+
+/**
+ * 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";
+}
+
+/**
+ * Choose the table columns: sized to the content, then thinned to fit the terminal.
+ * Drops In/Out first, then Latency, then shrinks the model column.
+ * @param {number} columns Terminal width.
+ * @param {Record<string, any>[]} recent Requests to show (the model column fits the longest name, capped).
+ * @returns {{ id: string, title: string, width: number, right: boolean }[]} Visible columns in order.
+ */
+function tableColumns(columns, recent) {
+  const model = Math.min(MAX_MODEL_WIDTH, Math.max(MIN_MODEL_WIDTH, ...recent.map((request) => String(request.model ?? "-").length)));
+  let cols = [
+    { id: "time", title: "Time", width: 8, right: false },
+    { id: "model", title: "Model", width: model, right: false },
+    { id: "status", title: "Status", width: 6, right: false },
+    { id: "latency", title: "Latency", width: 7, right: true },
+    { id: "in", title: "In", width: 6, right: true },
+    { id: "out", title: "Out", width: 6, right: true },
+    { id: "cost", title: "Cost", width: 9, right: true },
+  ];
+  for (const drop of [["in", "out"], ["latency"]]) {
+    if (tableWidth(cols) <= columns - 1) break;
+    cols = cols.filter((col) => !drop.includes(col.id));
+  }
+  const excess = tableWidth(cols) - (columns - 1);
+  if (excess > 0) {
+    const modelCol = cols.find((col) => col.id === "model");
+    modelCol.width = Math.max(MIN_MODEL_WIDTH, modelCol.width - excess);
+  }
+  return cols;
+}
+
+/**
+ * Total width of a bordered table.
+ * @param {{ width: number }[]} cols Columns.
+ * @returns {number} Characters per line, borders and padding included.
+ */
+function tableWidth(cols) {
+  return cols.reduce((sum, col) => sum + col.width + 3, 1);
+}
+
+/**
+ * Draw a horizontal table border.
+ * @param {{ width: number }[]} cols Columns.
+ * @param {[string, string, string]} corners Left, junction and right characters.
+ * @param {boolean} color Whether to emit colour.
+ * @returns {string} One grey line.
+ */
+function border(cols, [left, mid, right], color) {
+  return paint(color, "grey", `${left}${cols.map((col) => "─".repeat(col.width + 2)).join(mid)}${right}`);
+}
+
+/**
+ * Draw one table line from already padded cells.
+ * @param {string[]} cells Cell text, each exactly its column width (colour codes allowed).
+ * @param {boolean} color Whether to emit colour.
+ * @returns {string} One line with grey vertical borders.
+ */
+function tableLine(cells, color) {
+  const bar = paint(color, "grey", "│");
+  return `${bar}${cells.map((cell) => ` ${cell} `).join(bar)}${bar}`;
+}
+
+/**
+ * Pad text to a column width on its alignment side.
+ * @param {string} text Plain text, already no longer than the column.
+ * @param {{ width: number, right: boolean }} col Column.
+ * @returns {string} Text of exactly `col.width` characters.
+ */
+function fit(text, col) {
+  return col.right ? text.padStart(col.width) : text.padEnd(col.width);
+}
+
+/**
+ * Render one request as table cells.
+ * @param {Record<string, any>} request Entry from `/member/api/recent`.
+ * @param {{ id: string, width: number, right: boolean }[]} cols Visible columns.
+ * @param {boolean} color Whether to emit colour.
+ * @param {string | undefined} timeZone IANA zone.
+ * @returns {string[]} One padded cell per column.
+ */
+function requestCells(request, cols, color, timeZone) {
+  const text = {
+    time: clock(request.started_at, timeZone),
+    model: String(request.model ?? "-"),
+    status: String(request.status),
+    latency: latency(request.latency_ms),
+    in: tokens(request.input_tokens),
+    out: tokens(request.output_tokens),
+    cost: exactMoney(request.usd),
+  };
+  return cols.map((col) => {
+    const cell = fit(truncate(text[col.id], col.width), col);
+    return col.id === "status" ? paint(color, statusTone(request.status), cell) : cell;
+  });
+}
+
+/**
+ * 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 - 1` wide (the last column is left free: some terminals clip it), 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 cols = tableColumns(columns, recent);
+  const width = tableWidth(cols);
+  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, width - 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");
+  lines.push(border(cols, ["┌", "┬", "┐"], color));
+  lines.push(tableLine(cols.map((col) => paint(color, "bold", fit(col.title, col))), color));
+  lines.push(border(cols, ["├", "┼", "┤"], color));
+  const room = Math.max(0, rows - lines.length - 2);
+  if (recent.length === 0) {
+    if (room > 0) lines.push(tableLine([paint(color, "grey", "No requests yet.".padEnd(width - 4))], color));
+  } else {
+    for (const request of recent.slice(0, room)) lines.push(tableLine(requestCells(request, cols, color, timeZone), color));
+  }
+  lines.push(border(cols, ["└", "┴", "┘"], color));
+  while (fill && lines.length < rows - 1) lines.push("");
+  lines.push(footer);
+  return lines.slice(-Math.max(rows, 1)).map((line) => clip(line, Math.max(columns - 1, 1))).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

@@ -3,4 +3,5 @@ export function resolveCredentials(
   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

@@ -1,4 +1,8 @@
+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;
 
 /**
@@ -15,29 +19,60 @@ export function resolveCredentials(settings, env = process.env) {
 }
 
 /**
- * Fetch the member's status from the pool.
+ * 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 (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.
+ * @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.
  */
-export async function fetchUsage(baseUrl, key, fetchImpl = fetch) {
+async function getJson(baseUrl, path, key, fetchImpl) {
   let res;
   try {
-    res = await fetchImpl(`${baseUrl}${STATUS_PATH}`, {
-      headers: { authorization: `Bearer ${key}` },
+    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) throw new Error(`Too many requests. Retry in ${res.headers.get("retry-after") ?? "a few"}s.`);
+  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`.

package/package.json

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