@emesoft/tokenhub 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,19 @@
 # @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 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).
+
 `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,14 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 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 disconnect          Remove the pool entries from settings.json
   tokenhub --help | --version
 `;
@@ -37,6 +39,21 @@ 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 === "disconnect") {
     try {
       console.log(disconnectSettings(file) ? `Disconnected. Updated ${file}` : `Nothing to remove in ${file}`);

package/lib/usage.d.ts

@@ -0,0 +1,6 @@
+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 formatUsage(report: Record<string, any>, locale?: string, timeZone?: string): string;

package/lib/usage.js

@@ -0,0 +1,76 @@
+const STATUS_PATH = "/member/api/status";
+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;
+}
+
+/**
+ * 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 async function fetchUsage(baseUrl, key, fetchImpl = fetch) {
+  let res;
+  try {
+    res = await fetchImpl(`${baseUrl}${STATUS_PATH}`, {
+      headers: { authorization: `Bearer ${key}` },
+      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.ok) throw new Error(`Pool answered HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * 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.2.0",
   "description": "Pair Claude Code on this machine with a TokenHub pool",
   "type": "module",
   "bin": {