@emesoft/tokenhub 0.7.1 → 0.8.0

package/README.md

@@ -1,10 +1,16 @@
-# @emesoft/tokenhub
+<p align="center">
+  <img src="https://tokenhub.aimpact.io.vn/readme/banner.jpg" alt="TokenHub" width="520">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@emesoft/tokenhub"><img src="https://img.shields.io/npm/v/@emesoft/tokenhub" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@emesoft/tokenhub?activeTab=code"><img src="https://img.shields.io/npm/l/@emesoft/tokenhub" alt="MIT license"></a>
+  <img src="https://img.shields.io/node/v/@emesoft/tokenhub" alt="Node.js 18+">
+</p>
 
-[![npm](https://img.shields.io/npm/v/@emesoft/tokenhub)](https://www.npmjs.com/package/@emesoft/tokenhub)
-[![license](https://img.shields.io/npm/l/@emesoft/tokenhub)](https://www.npmjs.com/package/@emesoft/tokenhub?activeTab=code)
-![node](https://img.shields.io/node/v/@emesoft/tokenhub)
+# @emesoft/tokenhub
 
-Connect [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to a [TokenHub](https://tokenhub.aimpact.io.vn) pool in one command, and keep an eye on your spend from the terminal.
+Connect [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to your company's [TokenHub](https://tokenhub.aimpact.io.vn) in one command, and keep an eye on your spend from the terminal.
 
 - **One-step setup:** pair in the browser, no keys to copy.
 - **Spend at a glance:** a status line under the Claude Code prompt, plus `usage` and a live `dashboard`.
@@ -14,22 +20,30 @@ Connect [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to a [Toke
 
 ```sh
 npm install -g @emesoft/tokenhub
-tokenhub connect
+tokenhub connect <your tenant name>
 claude
 ```
 
+Your tenant name is the first part of your TokenHub address: for `https://acme.aimpact.io.vn` it is `acme` (`connect` asks if you leave it out; a full URL works too). Ask your admin if you don't know it.
+
 `connect` shows a short code and opens your browser. Sign in to the pool, check the code matches, and confirm. That's it: Claude Code now runs through the pool.
 
+<img src="https://tokenhub.aimpact.io.vn/readme/connect.png" alt="tokenhub connect in a terminal, next to the pool's page confirming the same code" width="100%">
+
+From then on, today's spend and your credit sit under the Claude Code prompt:
+
+<img src="https://tokenhub.aimpact.io.vn/readme/statusline.png" alt="The TokenHub status line under the Claude Code prompt" width="560">
+
 Prefer not to install? Use `npx @emesoft/tokenhub connect` instead.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `tokenhub connect [poolUrl]` | Pair this machine with the pool (default `https://tokenhub.aimpact.io.vn`). |
+| `tokenhub connect [tenant]` | Pair this machine with your tenant (`acme` = `https://acme.aimpact.io.vn`, or a full URL). Asks for it when left out. |
 | `tokenhub usage [--json]` | Today's and this week's spend against your limits, your credit and pool health. |
 | `tokenhub dashboard` | Live full-screen view of spend and your recent requests. |
-| `tokenhub overlay [poolUrl]` | Install the TokenHub desktop overlay (Windows). |
+| `tokenhub overlay <tenant>` | Install the TokenHub desktop overlay (Windows). |
 | `tokenhub disconnect` | Undo `connect`. |
 | `tokenhub --help` / `--version` | Help and version. |
 
@@ -61,10 +75,16 @@ Each machine gets its own key, which you can revoke from the pool's **Keys** pag
 
 `tokenhub dashboard` shows your daily and weekly spend as bars against your limits (green below 70%, orange to 90%, red above), your credit, pool health and your latest requests. Press `r` to refresh now and `q` to quit. If the connection drops, it keeps the last screen and reconnects on its own. With `--once`, `NO_COLOR` or no terminal, it prints a single plain frame.
 
+<img src="https://tokenhub.aimpact.io.vn/readme/dashboard.png" alt="tokenhub dashboard: daily and weekly spend bars, credit, pool health and recent requests" width="100%">
+
 ## Desktop overlay
 
 `tokenhub overlay` downloads the TokenHub overlay installer from the pool and starts it (Windows). The overlay is a small always-on-top widget that shows your own usage after `connect`, or the whole pool after `connect --admin`.
 
+<img src="https://tokenhub.aimpact.io.vn/readme/overlay.jpg" alt="The TokenHub desktop overlay, collapsed and expanded, on a desktop" width="100%">
+
+<sub>Screenshots use sample data.</sub>
+
 ## For admins
 
 `tokenhub connect --admin` pairs this machine as an **admin device** for the desktop overlay's pool view:
@@ -85,12 +105,13 @@ The CLI talks only to the pool you connect to. Requests carry your key and one h
 | --- | --- |
 | `tokenhub: command not found` after `npm install` | Install globally with `-g`. A plain `npm install` puts it in the current folder, which isn't on your `PATH` (only `npx` finds it there). |
 | Command missing after switching Node with nvm | Global packages belong to one Node version. Run `npm install -g @emesoft/tokenhub` again. |
-| `The pool rejected this key` | The key was revoked. Run `tokenhub connect` again. |
+| `The pool rejected this key` | The key was revoked. Run `tokenhub connect <tenant>` again. |
 | Claude Code ignores the pool | A shell variable is overriding `settings.json` (see the note under [What `connect` changes](#what-connect-changes)). |
 
 ## Links
 
-- Pool: sign in, manage keys and top up at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn)
+- Your tenant: sign in, manage keys and top up at `https://<tenant>.aimpact.io.vn`; find yours at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn/enter)
+- Upgrading from 0.7: the default pool is gone; run `tokenhub connect <tenant>` once
 - Changelog: [npm versions](https://www.npmjs.com/package/@emesoft/tokenhub?activeTab=versions)
 
 ## License

package/bin/tokenhub.js

@@ -3,21 +3,22 @@ import { readFileSync } from "node:fs";
 import { adminConfigPath, removeAdminConfig } from "../lib/admin.js";
 import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
 import { runOverlayInstall } from "../lib/overlay.js";
-import { DEFAULT_POOL_URL, runConnect } from "../lib/pair.js";
+import { promptTenant, runConnect, TENANT_DOMAIN } 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
+const HELP = `tokenhub - pair Claude Code with your TokenHub tenant
 
 Usage:
-  tokenhub connect [poolUrl] [--no-statusline]
+  tokenhub connect [tenant] [--no-statusline]
                                Pair this machine and write ~/.claude/settings.json, including the status line
                                (today's spend under the prompt) unless --no-statusline.
-                               poolUrl defaults to ${DEFAULT_POOL_URL}
-  tokenhub connect [poolUrl] --admin
+                               tenant is your tenant name (acme = https://acme.${TENANT_DOMAIN}) or a full URL;
+                               it is asked for when left out
+  tokenhub connect [tenant] --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 overlay <tenant>    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)
@@ -48,8 +49,17 @@ async function main(argv) {
   if (command === "connect") {
     const controller = new AbortController();
     process.once("SIGINT", () => controller.abort());
+    let poolUrl = arg;
+    if (!poolUrl) {
+      try {
+        poolUrl = await promptTenant();
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        return 1;
+      }
+    }
     return runConnect({
-      poolUrl: arg,
+      poolUrl,
       settingsFile: file,
       signal: controller.signal,
       statusLine: !flags.includes("--no-statusline"),
@@ -58,7 +68,7 @@ async function main(argv) {
     });
   }
   if (command === "overlay") {
-    return runOverlayInstall(arg ? { poolUrl: arg } : {});
+    return runOverlayInstall({ poolUrl: arg });
   }
   if (command === "usage") {
     try {

package/lib/overlay.js

@@ -2,8 +2,7 @@ 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";
+import { resolvePoolUrl } from "./pair.js";
 
 /** Path of the overlay installer on the pool. */
 export const OVERLAY_PATH = "/downloads/overlay.exe";
@@ -22,7 +21,7 @@ function launch(file) {
 /**
  * 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 {string} options.poolUrl Tenant slug or pool URL (see `resolvePoolUrl`).
  * @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).
@@ -31,7 +30,7 @@ function launch(file) {
  * @returns {Promise<number>} Process exit code.
  */
 export async function runOverlayInstall({
-  poolUrl = DEFAULT_POOL_URL,
+  poolUrl,
   log = console.log,
   platform = process.platform,
   run = launch,
@@ -44,7 +43,7 @@ export async function runOverlayInstall({
   }
   let url;
   try {
-    url = `${normalizeUrl(poolUrl)}${OVERLAY_PATH}`;
+    url = `${resolvePoolUrl(poolUrl)}${OVERLAY_PATH}`;
   } catch (error) {
     log(`Error: ${error.message}`);
     return 1;

package/lib/pair.d.ts

@@ -1,8 +1,10 @@
-export const DEFAULT_POOL_URL: string;
+export const TENANT_DOMAIN: string;
+export function resolvePoolUrl(input: string | undefined): string;
+export function promptTenant(streams?: { input?: NodeJS.ReadableStream & { isTTY?: boolean }; output?: NodeJS.WritableStream }): Promise<string>;
 export function openBrowser(url: string, platform?: string): void;
 export function runConnect(options: {
-  /** Pool address; defaults to `DEFAULT_POOL_URL`. */
-  poolUrl?: string;
+  /** Tenant slug (`acme`) or pool URL; required. */
+  poolUrl: string | undefined;
   settingsFile: string;
   log?: (line: string) => void;
   open?: (url: string) => void;

package/lib/pair.js

@@ -1,12 +1,46 @@
 import { spawn } from "node:child_process";
 import { hostname } from "node:os";
+import { createInterface } from "node:readline/promises";
 import { writeAdminConfig } from "./admin.js";
 import { connectSettings, normalizeUrl, overridingEnvVars, readSettings } from "./settings.js";
 
 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";
+/** Tenants live at `<slug>.<TENANT_DOMAIN>`; `connect <slug>` targets `https://<slug>.<TENANT_DOMAIN>`. */
+export const TENANT_DOMAIN = "aimpact.io.vn";
+
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$/;
+
+/**
+ * Turn what the user typed into a pool address: a full URL is kept, a tenant slug becomes its subdomain.
+ * @param {string | undefined} input Tenant slug (`acme`) or URL (`https://acme.aimpact.io.vn`).
+ * @returns {string} Pool address without a trailing slash.
+ * @throws {Error} When the input is empty, or neither a URL nor a valid slug.
+ */
+export function resolvePoolUrl(input) {
+  const value = String(input ?? "").trim();
+  if (!value) throw new Error(`Name your tenant, e.g. \`tokenhub connect acme\` for https://acme.${TENANT_DOMAIN}`);
+  if (value.includes("://")) return normalizeUrl(value);
+  const slug = value.toLowerCase();
+  if (!SLUG_PATTERN.test(slug)) throw new Error(`"${value}" is not a tenant name (3-30 lowercase letters, digits and hyphens) or a URL.`);
+  return `https://${slug}.${TENANT_DOMAIN}`;
+}
+
+/**
+ * Ask for the tenant slug on the terminal.
+ * @param {{ input?: NodeJS.ReadableStream & { isTTY?: boolean }, output?: NodeJS.WritableStream }} [streams] Streams to prompt on (tests).
+ * @returns {Promise<string>} What was typed.
+ * @throws {Error} When stdin is not interactive.
+ */
+export async function promptTenant({ input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) throw new Error(`Name your tenant, e.g. \`tokenhub connect acme\` for https://acme.${TENANT_DOMAIN} (no terminal to ask on).`);
+  const rl = createInterface({ input, output });
+  try {
+    return await rl.question(`Tenant name (the part before .${TENANT_DOMAIN}): `);
+  } finally {
+    rl.close();
+  }
+}
 
 /**
  * Open a URL in the default browser; failures are ignored (the URL is printed anyway).
@@ -65,7 +99,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 (default `DEFAULT_POOL_URL`).
+ * @param {string} options.poolUrl Tenant slug or pool URL as typed by the user (see `resolvePoolUrl`).
  * @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.
@@ -79,7 +113,7 @@ async function postJson(url, body, signal) {
  * @returns {Promise<number>} Process exit code.
  */
 export async function runConnect({
-  poolUrl = DEFAULT_POOL_URL,
+  poolUrl,
   settingsFile,
   log = console.log,
   open = openBrowser,
@@ -93,7 +127,7 @@ export async function runConnect({
 }) {
   let pool;
   try {
-    pool = normalizeUrl(poolUrl);
+    pool = resolvePoolUrl(poolUrl);
     if (!admin) readSettings(settingsFile);
   } catch (error) {
     log(`Error: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emesoft/tokenhub",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Connect Claude Code to a TokenHub pool in one command, and track your spend from the terminal",
   "keywords": [
     "claude",