@emesoft/tokenhub 0.5.0 → 0.7.0

package/README.md

@@ -2,16 +2,23 @@
 
 Pair Claude Code on this machine with a [TokenHub](https://tokenhub.aimpact.io.vn) pool. No dependencies, Node 18+.
 
+`connect` pairs with https://tokenhub.aimpact.io.vn by default. For another pool, pass its address: `npx @emesoft/tokenhub connect https://pool.example.com`.
+
 ```
-npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn
-npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn --no-statusline
+npx @emesoft/tokenhub connect
+npx @emesoft/tokenhub connect --no-statusline
 npx @emesoft/tokenhub usage
 npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
-npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn --admin
+npx @emesoft/tokenhub connect --admin
 npx @emesoft/tokenhub disconnect --admin
+npx @emesoft/tokenhub overlay
 ```
 
+To type `tokenhub` without `npx`, install it **globally**: `npm install -g @emesoft/tokenhub`, then `tokenhub connect`. A plain `npm install @emesoft/tokenhub` puts it in the current folder's `node_modules`, which is not on your `PATH` (only `npx` finds it there). With nvm, global packages belong to one Node version: install again after `nvm use`.
+
+`overlay` (Windows) downloads the TokenHub desktop overlay installer from the pool (`/downloads/overlay.exe`) and starts it. The overlay then shows your own usage after `connect`, or the whole pool after `connect --admin`.
+
 `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`). It also adds a `statusLine` that shows today's spend and credit under the Claude Code prompt (pass `--no-statusline` to skip it; a `statusLine` you already had is left alone). 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).
@@ -22,8 +29,8 @@ Requests to the pool carry your key and one extra header, `x-tokenhub-cli: <vers
 
 `disconnect` removes only those two entries and the TokenHub `statusLine`.
 
-`connect --admin` is for pool admins. It pairs this machine as an *admin device* for the TokenHub desktop overlay: you confirm the code on the pool's **admin** console (so only the signed-in admin can approve it), and the CLI saves a read-only device token to `~/.tokenhub/admin.json` (or `$TOKENHUB_CONFIG_DIR/admin.json`). It never touches Claude Code's settings. The token can read account names and quota levels, nothing else. Revoke a device on the admin Devices page (`/admin/pair`); `disconnect --admin` just forgets the token locally.
+`connect --admin` is for pool admins. It pairs this machine as an *admin device* for the TokenHub desktop overlay: you confirm the code on the pool's **admin** console (so only the signed-in admin can approve it), and the CLI saves a device token to `~/.tokenhub/admin.json` (or `$TOKENHUB_CONFIG_DIR/admin.json`). It never touches Claude Code's settings. The token can read account names and quota levels and switch accounts on or off (the overlay's switch), nothing else: no emails, tokens, members or settings. Revoke a device on the admin Devices page (`/admin/pair`); `disconnect --admin` just forgets the token locally.
 
 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.
+Sign in, manage your keys and top up at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn).

package/bin/tokenhub.js

@@ -2,19 +2,22 @@
 import { readFileSync } from "node:fs";
 import { adminConfigPath, removeAdminConfig } from "../lib/admin.js";
 import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
-import { runConnect } from "../lib/pair.js";
+import { runOverlayInstall } from "../lib/overlay.js";
+import { DEFAULT_POOL_URL, runConnect } from "../lib/pair.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> [--no-statusline]
+  tokenhub connect [poolUrl] [--no-statusline]
                                Pair this machine and write ~/.claude/settings.json, including the status line
-                               (today's spend under the prompt) unless --no-statusline
-  tokenhub connect <poolUrl> --admin
+                               (today's spend under the prompt) unless --no-statusline.
+                               poolUrl defaults to ${DEFAULT_POOL_URL}
+  tokenhub connect [poolUrl] --admin
                                Pair this machine as an admin device (for the desktop overlay's pool view): the admin
                                confirms in the console, the token is saved to ~/.tokenhub/admin.json
+  tokenhub overlay [poolUrl]   Download and install the TokenHub desktop overlay (Windows)
   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)
@@ -43,10 +46,6 @@ async function main(argv) {
   }
   const file = settingsPath();
   if (command === "connect") {
-    if (!arg) {
-      console.error(`Missing pool URL.\n\n${HELP}`);
-      return 1;
-    }
     const controller = new AbortController();
     process.once("SIGINT", () => controller.abort());
     return runConnect({
@@ -58,11 +57,14 @@ async function main(argv) {
       adminFile: adminConfigPath(),
     });
   }
+  if (command === "overlay") {
+    return runOverlayInstall(arg ? { poolUrl: arg } : {});
+  }
   if (command === "usage") {
     try {
       const credentials = resolveCredentials(readSettings(file).settings);
       if (!credentials) {
-        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        console.error("Not connected. Run `tokenhub connect` first.");
         return 1;
       }
       const report = await fetchUsage(credentials.baseUrl, credentials.key);
@@ -78,7 +80,7 @@ async function main(argv) {
       const options = parseDashboardArgs(argv.slice(1));
       const credentials = resolveCredentials(readSettings(file).settings);
       if (!credentials) {
-        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        console.error("Not connected. Run `tokenhub connect` first.");
         return 1;
       }
       return await runDashboard(credentials, options);

package/lib/overlay.d.ts

@@ -0,0 +1,9 @@
+export const OVERLAY_PATH: string;
+export function runOverlayInstall(options?: {
+  poolUrl?: string;
+  log?: (line: string) => void;
+  platform?: string;
+  run?: (file: string) => void;
+  dir?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<number>;

package/lib/overlay.js

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalizeUrl } from "./settings.js";
+import { DEFAULT_POOL_URL } from "./pair.js";
+
+/** Path of the overlay installer on the pool. */
+export const OVERLAY_PATH = "/downloads/overlay.exe";
+
+/**
+ * Start the installer and let it run on its own (it shows its own window; this process does not wait for it).
+ * @param {string} file Installer path.
+ * @returns {void}
+ */
+function launch(file) {
+  const child = spawn(file, [], { detached: true, stdio: "ignore", windowsHide: false });
+  child.on("error", () => {});
+  child.unref();
+}
+
+/**
+ * Download the TokenHub desktop overlay's Windows installer from the pool and start it.
+ * @param {object} options
+ * @param {string} [options.poolUrl] Pool address (default `DEFAULT_POOL_URL`).
+ * @param {(line: string) => void} [options.log] Output sink.
+ * @param {string} [options.platform] Node platform name; the overlay is Windows only.
+ * @param {(file: string) => void} [options.run] Starts the downloaded installer (tests replace it).
+ * @param {string} [options.dir] Folder to save the installer in (default a new temp folder).
+ * @param {typeof fetch} [options.fetchImpl] `fetch` override for tests.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runOverlayInstall({
+  poolUrl = DEFAULT_POOL_URL,
+  log = console.log,
+  platform = process.platform,
+  run = launch,
+  dir,
+  fetchImpl = fetch,
+} = {}) {
+  if (platform !== "win32") {
+    log("The TokenHub overlay is a Windows app; there is no build for this system yet.");
+    return 1;
+  }
+  let url;
+  try {
+    url = `${normalizeUrl(poolUrl)}${OVERLAY_PATH}`;
+  } catch (error) {
+    log(`Error: ${error.message}`);
+    return 1;
+  }
+  log(`Downloading the overlay from ${url} ...`);
+  let res;
+  try {
+    res = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
+  } catch (error) {
+    log(`Error: could not reach the pool (${error.message}).`);
+    return 1;
+  }
+  if (res.status === 404) {
+    log("This pool has not published the overlay installer yet. Ask your admin.");
+    return 1;
+  }
+  if (!res.ok) {
+    log(`Error: the pool answered HTTP ${res.status}.`);
+    return 1;
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const expected = Number(res.headers.get("content-length"));
+  // A Windows executable starts with "MZ"; anything else (an HTML error page, a cut-off download) is not run.
+  if ((expected > 0 && bytes.length !== expected) || bytes.length < 2 || bytes[0] !== 0x4d || bytes[1] !== 0x5a) {
+    log("Error: the download is incomplete or not an installer. Try again.");
+    return 1;
+  }
+  const file = join(dir ?? mkdtempSync(join(tmpdir(), "tokenhub-overlay-")), "TokenHub-Overlay-setup.exe");
+  writeFileSync(file, bytes);
+  log(`Downloaded ${(bytes.length / 1024 / 1024).toFixed(1)} MB. Starting the installer...`);
+  run(file);
+  log("Follow the installer. The overlay picks up `tokenhub connect` (your usage) or `tokenhub connect --admin` (the pool).");
+  return 0;
+}

package/lib/pair.d.ts

@@ -1,6 +1,8 @@
+export const DEFAULT_POOL_URL: string;
 export function openBrowser(url: string, platform?: string): void;
 export function runConnect(options: {
-  poolUrl: string;
+  /** Pool address; defaults to `DEFAULT_POOL_URL`. */
+  poolUrl?: string;
   settingsFile: string;
   log?: (line: string) => void;
   open?: (url: string) => void;

package/lib/pair.js

@@ -5,6 +5,9 @@ import { connectSettings, normalizeUrl, overridingEnvVars, readSettings } from "
 
 const MAX_WAIT_MS = 15 * 60 * 1000;
 
+/** The pool `connect` pairs with when no address is given. */
+export const DEFAULT_POOL_URL = "https://tokenhub.aimpact.io.vn";
+
 /**
  * Open a URL in the default browser; failures are ignored (the URL is printed anyway).
  * @param {string} url Address to open.
@@ -62,7 +65,7 @@ async function postJson(url, body, signal) {
 /**
  * Run the pairing flow and write the issued key into settings.json.
  * @param {object} options
- * @param {string} options.poolUrl Pool address as typed by the user.
+ * @param {string} [options.poolUrl] Pool address as typed by the user (default `DEFAULT_POOL_URL`).
  * @param {string} options.settingsFile Path of settings.json to update.
  * @param {(line: string) => void} [options.log] Output sink.
  * @param {(url: string) => void} [options.open] Browser opener.
@@ -76,7 +79,7 @@ async function postJson(url, body, signal) {
  * @returns {Promise<number>} Process exit code.
  */
 export async function runConnect({
-  poolUrl,
+  poolUrl = DEFAULT_POOL_URL,
   settingsFile,
   log = console.log,
   open = openBrowser,

package/package.json

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