ai-cc-router 0.2.3 → 0.2.5

package/README.md

@@ -7,6 +7,21 @@ Distribute Claude Code requests across N subscriptions to multiply your throughp
 [![npm](https://img.shields.io/npm/v/ai-cc-router)](https://www.npmjs.com/package/ai-cc-router)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+### Features
+
+- **Round-robin token rotation** — distribute requests across 2-20 Claude Max accounts automatically
+- **Transparent proxy** — Claude Code works normally; streaming, thinking, tool use, prompt caching all pass through
+- **Automatic token refresh** — OAuth tokens are refreshed before they expire, saved atomically to disk
+- **Rate limit awareness** — detects 429/529 responses and coolsdown accounts; picks the least-loaded one
+- **Client mode** — connect to a remote CC-Router from any machine with one command (`cc-router client connect <url>`)
+- **Claude Desktop support** — route Cowork / Agent-mode traffic through CC-Router via mitmproxy interception (macOS, Windows, Linux)
+- **Guided setup wizard** — interactive `cc-router setup` extracts tokens from Keychain or credentials file, configures everything
+- **Live dashboard** — real-time terminal UI showing account health, request counts, token usage, recent activity
+- **Proxy authentication** — optional Bearer / x-api-key secret for internet-exposed deployments
+- **Auto-update** — patch/minor releases install automatically (opt-out available)
+- **Multiple deployment modes** — foreground, PM2 daemon, system service, Docker Compose (with LiteLLM)
+- **Cross-platform** — macOS, Linux, Windows; Node.js 20+
+
 ---
 
 > **Warning**  
@@ -498,12 +513,47 @@ Press `q` to quit. Run with `--json` for non-interactive output.
 - The file is excluded by `.gitignore`
 - Writes are atomic (write to `.tmp`, then rename) — no corruption on crash
 - Keychain reads use `execFile` with a fixed argument array — no shell injection
-- No telemetry, no external logging
+- Anonymous opt-out telemetry via [Aptabase](https://aptabase.com) (see [Telemetry](#telemetry) below)
 
 See [docs/security.md](docs/security.md) for details.
 
 ---
 
+## Telemetry
+
+CC-Router sends a handful of anonymous lifecycle events to [Aptabase](https://aptabase.com) (privacy-first, open source, EU-hosted). The goal is simple: know how many people use the project, which versions are live, and roughly how many instances are running — so we can prioritize fixes and features.
+
+**What we send** — the entire payload lives in [`src/utils/telemetry.ts`](src/utils/telemetry.ts), audit it yourself:
+
+| Event                | When                                            | Custom props                             |
+| -------------------- | ------------------------------------------------ | ---------------------------------------- |
+| `app_started`        | First proxy start after install                 | `first_run: true`                        |
+| `setup_completed`    | Setup wizard finishes successfully               | `account_count`                          |
+| `proxy_started`      | Each `cc-router start`                           | `account_count`, `mode`                  |
+| `proxy_heartbeat`    | Every 6h while the proxy is running              | `uptime_hours`, `account_count`          |
+| `telemetry_disabled` | When you run `cc-router telemetry off`           | —                                        |
+
+Plus anonymous system props with every event: `appVersion`, `osName` (macOS/Linux/Windows), `osVersion`, `locale`, `engineVersion` (Node), and an anonymous `installId` (random UUID generated on first run, stored in `~/.cc-router/telemetry.json`).
+
+**What we never send**: IPs, OAuth tokens, account names, request content, prompts, responses, URLs, hostnames, usernames, file paths — nothing that could identify you or your usage patterns.
+
+**Disable it** — three ways, any one works:
+
+```bash
+# 1. Persistent opt-out (recommended)
+cc-router telemetry off
+
+# 2. Respect the de-facto standard (honored by many OSS tools)
+export DO_NOT_TRACK=1
+
+# 3. Project-specific override
+export CC_ROUTER_TELEMETRY=0
+```
+
+Check status anytime: `cc-router telemetry status`.
+
+---
+
 ## Disclaimer
 
 > CC-Router uses the OAuth tokens of your own Claude Max subscriptions.

package/dist/cli/cmd-client.js

@@ -204,7 +204,11 @@ export function registerClient(program) {
                 const status = log.statusCode ?? 0;
                 const statusColor = status >= 500 || status === 0 ? chalk.red : status >= 400 ? chalk.yellow : chalk.green;
                 const duration = log.durationMs ? ` ${chalk.gray(log.durationMs + "ms")}` : "";
-                console.log(`    ${chalk.gray(formatTime(log.ts))}  ${log.accountId.padEnd(18)}  ` +
+                const src = log.source === "cli" ? chalk.blue("cli")
+                    : log.source === "desktop" ? chalk.magenta("dsk")
+                        : log.source === "api" ? chalk.gray("api")
+                            : chalk.gray("   ");
+                console.log(`    ${chalk.gray(formatTime(log.ts))}  ${src} ${log.accountId.padEnd(18)}  ` +
                     `${(log.method ?? "?").padEnd(5)} ${(log.path ?? "?").padEnd(22)}  ` +
                     `${statusColor(String(status))}${duration}`);
             }

package/dist/cli/cmd-setup.js

@@ -13,6 +13,8 @@ import { DEFAULT_RATE_LIMITS } from "../proxy/types.js";
 import { existsSync } from "fs";
 import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, getNetworkExtensionStatus, openNetworkExtensionSettings, } from "../interceptor/mitmproxy-manager.js";
 import { printDesktopSupportExplainer, printNetworkExtensionInstructions } from "./cmd-client.js";
+import { loadTelemetryState, writeTelemetryState } from "../config/telemetry.js";
+import { trackEvent } from "../utils/telemetry.js";
 const execFileAsync = promisify(execFile);
 // ─── Public registration ──────────────────────────────────────────────────────
 export function registerSetup(program) {
@@ -212,9 +214,38 @@ async function runSetupWizard({ addMode }) {
     console.log(chalk.bold(`\n${"━".repeat(40)}\n  Saving\n${"━".repeat(40)}\n`));
     saveAccounts(merged);
     console.log(chalk.green(`  ✓ ${merged.length} account(s) saved to ~/.cc-router/accounts.json`));
+    showTelemetryDisclosureIfNeeded();
+    void trackEvent("setup_completed", { account_count: merged.length });
     // ─── Post-setup interactive flow ─────────────────────────────────────────
     await runPostSetupFlow(merged.length);
 }
+// Anonymous telemetry disclosure, shown exactly once after a successful setup.
+// Controlled by telemetry.disclosureShown in ~/.cc-router/telemetry.json.
+function showTelemetryDisclosureIfNeeded() {
+    try {
+        const state = loadTelemetryState();
+        if (state.disclosureShown)
+            return;
+        console.log();
+        console.log(chalk.dim("─".repeat(60)));
+        console.log(chalk.bold("  Anonymous usage analytics"));
+        console.log();
+        console.log("  CC-Router sends anonymous lifecycle events (version, OS,");
+        console.log("  startup, heartbeat) to help us understand usage and prioritize");
+        console.log("  improvements. No IPs, no tokens, no prompts, no request content.");
+        console.log();
+        console.log(`  Disable:    ${chalk.cyan("cc-router telemetry off")}`);
+        console.log(`  Or set:     ${chalk.cyan("DO_NOT_TRACK=1")}   |   ${chalk.cyan("CC_ROUTER_TELEMETRY=0")}`);
+        console.log(`  Source:     ${chalk.dim("src/utils/telemetry.ts")}`);
+        console.log(chalk.dim("─".repeat(60)));
+        console.log();
+        state.disclosureShown = true;
+        writeTelemetryState(state);
+    }
+    catch {
+        // never block setup on telemetry errors
+    }
+}
 // ─── Post-setup interactive flow ─────────────────────────────────────────────
 async function runPostSetupFlow(accountCount) {
     console.log(chalk.bold(`\n${"━".repeat(40)}\n  Configure this machine\n${"━".repeat(40)}\n`));

package/dist/cli/cmd-telemetry.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+import { loadTelemetryState, writeTelemetryState, isTelemetryEnabled } from "../config/telemetry.js";
+import { trackEvent } from "../utils/telemetry.js";
+export function registerTelemetry(program) {
+    program
+        .command("telemetry [action]")
+        .description("Manage anonymous usage analytics: on, off, status (default: status)")
+        .action(async (action) => {
+        const resolved = action ?? "status";
+        if (resolved === "status") {
+            showStatus();
+            return;
+        }
+        if (resolved === "on") {
+            const state = loadTelemetryState();
+            state.enabled = true;
+            writeTelemetryState(state);
+            console.log(chalk.green("Telemetry enabled."));
+            console.log(chalk.dim(`Install ID: ${state.installId}`));
+            return;
+        }
+        if (resolved === "off") {
+            // Send one last event so we know about opt-out rates
+            await trackEvent("telemetry_disabled");
+            const state = loadTelemetryState();
+            state.enabled = false;
+            writeTelemetryState(state);
+            console.log(chalk.yellow("Telemetry disabled. No data will be sent."));
+            console.log(chalk.dim("Re-enable anytime with: cc-router telemetry on"));
+            return;
+        }
+        console.error(chalk.red(`Unknown action "${resolved}". Use: on, off, status`));
+        process.exitCode = 1;
+    });
+}
+function showStatus() {
+    const state = loadTelemetryState();
+    const envDisabled = process.env["DO_NOT_TRACK"] === "1" || process.env["CC_ROUTER_TELEMETRY"] === "0";
+    console.log(chalk.bold("Telemetry"));
+    console.log();
+    if (envDisabled) {
+        console.log(`  Status:     ${chalk.yellow("disabled")} (by environment variable)`);
+    }
+    else if (state.enabled) {
+        console.log(`  Status:     ${chalk.green("enabled")}`);
+    }
+    else {
+        console.log(`  Status:     ${chalk.yellow("disabled")}`);
+    }
+    console.log(`  Active:     ${isTelemetryEnabled() ? chalk.green("yes") : chalk.yellow("no")}`);
+    console.log(`  Install ID: ${chalk.dim(state.installId)}`);
+    console.log(`  Since:      ${chalk.dim(state.firstRunAt)}`);
+    console.log();
+    console.log(chalk.dim("  What we send:  version, OS, locale, lifecycle events (start, heartbeat)"));
+    console.log(chalk.dim("  What we DON'T: IPs, tokens, prompts, request content, account names"));
+    console.log(chalk.dim("  Source code:   src/utils/telemetry.ts"));
+    console.log();
+    console.log(chalk.dim("  Disable:  cc-router telemetry off"));
+    console.log(chalk.dim("  Or set:   DO_NOT_TRACK=1  |  CC_ROUTER_TELEMETRY=0"));
+}

package/dist/cli/index.js

@@ -10,6 +10,7 @@ import { registerConfigure } from "./cmd-configure.js";
 import { registerDocker } from "./cmd-docker.js";
 import { registerUpdate } from "./cmd-update.js";
 import { registerClient } from "./cmd-client.js";
+import { registerTelemetry } from "./cmd-telemetry.js";
 import { getCurrentVersion, checkForUpdate, printUpdateBanner } from "../utils/self-update.js";
 const program = new Command();
 program
@@ -42,6 +43,7 @@ registerConfigure(program);
 registerDocker(program);
 registerUpdate(program);
 registerClient(program);
+registerTelemetry(program);
 // Background update check — fires on every CLI invocation, uses 6h disk cache
 // so it's essentially free after the first check. Notify on process exit.
 if (!process.env["NO_UPDATE_NOTIFIER"] && !process.env["CI"]) {

package/dist/config/paths.js

@@ -12,3 +12,6 @@ export const LITELLM_URL = process.env["LITELLM_URL"];
 // Proxy-level config (password, future settings) — separate from accounts.json
 export const CONFIG_PATH = process.env["CONFIG_PATH"] ??
     path.join(CONFIG_DIR, "config.json");
+// Anonymous telemetry state — install id + opt-in flag
+export const TELEMETRY_PATH = process.env["TELEMETRY_PATH"] ??
+    path.join(CONFIG_DIR, "telemetry.json");

package/dist/config/telemetry.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
+import { randomUUID } from "crypto";
+import { TELEMETRY_PATH } from "./paths.js";
+import { ensureConfigDir } from "./manager.js";
+function defaultState() {
+    return {
+        enabled: true,
+        installId: randomUUID(),
+        firstRunAt: new Date().toISOString(),
+        disclosureShown: false,
+    };
+}
+// Read the telemetry state, creating and persisting a fresh one on first run.
+// Malformed files are treated as missing so a corrupted file can't crash the CLI.
+export function loadTelemetryState() {
+    if (!existsSync(TELEMETRY_PATH)) {
+        const state = defaultState();
+        writeTelemetryState(state);
+        return state;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(TELEMETRY_PATH, "utf-8"));
+        // Fill any missing fields to keep the file forward-compatible
+        const state = {
+            enabled: raw.enabled ?? true,
+            installId: raw.installId ?? randomUUID(),
+            firstRunAt: raw.firstRunAt ?? new Date().toISOString(),
+            disclosureShown: raw.disclosureShown ?? false,
+        };
+        if (!raw.installId || raw.disclosureShown === undefined) {
+            writeTelemetryState(state);
+        }
+        return state;
+    }
+    catch {
+        const state = defaultState();
+        writeTelemetryState(state);
+        return state;
+    }
+}
+// Atomic write: .tmp + rename, same pattern as writeAccountsAtomic
+export function writeTelemetryState(state) {
+    ensureConfigDir();
+    const tmp = TELEMETRY_PATH + ".tmp";
+    writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+    renameSync(tmp, TELEMETRY_PATH);
+}
+// Returns true only if the user has not opted out through any mechanism:
+//   - DO_NOT_TRACK=1     (de-facto standard)
+//   - CC_ROUTER_TELEMETRY=0  (project-specific override)
+//   - `cc-router telemetry off` (persisted enabled: false)
+export function isTelemetryEnabled() {
+    if (process.env["DO_NOT_TRACK"] === "1")
+        return false;
+    if (process.env["CC_ROUTER_TELEMETRY"] === "0")
+        return false;
+    try {
+        return loadTelemetryState().enabled;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/proxy/server.js

@@ -6,6 +6,8 @@ import { TokenPool } from "./token-pool.js";
 import { needsRefresh, refreshAccountToken, saveAccounts, startRefreshLoop } from "./token-refresher.js";
 import { loadAccounts, accountsFileExists, readAccountsFromPath, readConfig } from "../config/manager.js";
 import { checkForUpdate, performUpdate, restartSelf } from "../utils/self-update.js";
+import { trackEvent, startHeartbeat } from "../utils/telemetry.js";
+import { loadTelemetryState } from "../config/telemetry.js";
 import { logRoute, logError, logStartup } from "./logger.js";
 import { stats } from "./stats.js";
 import { PROXY_PORT, LITELLM_URL } from "../config/paths.js";
@@ -317,6 +319,11 @@ export async function startServer(opts = {}) {
         }
         req._ccAccount = account;
         req._startTime = Date.now();
+        const source = req.headers["x-claude-code-session-id"]
+            ? "cli"
+            : req.headers["x-api-key"]
+                ? "desktop"
+                : "api";
         req._pendingLog = {
             ts: Date.now(),
             accountId: account.id,
@@ -324,6 +331,7 @@ export async function startServer(opts = {}) {
             type: "route",
             method: req.method,
             path: req.path,
+            source,
         };
         stats.totalRequests++;
         logRoute(account.id, account.requestCount, Math.round((account.tokens.expiresAt - Date.now()) / 60_000));
@@ -377,5 +385,22 @@ export async function startServer(opts = {}) {
         logStartup(port, host, mode, target, accounts.length);
         if (autoUpdate)
             console.log(chalk.gray("  Auto-update: enabled (patch/minor)"));
+        // Anonymous telemetry — fire-and-forget, never blocks proxy startup
+        try {
+            const telemetryState = loadTelemetryState();
+            // First-run detection: if the install is brand new, emit app_started too
+            const firstRunAge = Date.now() - new Date(telemetryState.firstRunAt).getTime();
+            if (firstRunAge < 5 * 60 * 1000) {
+                void trackEvent("app_started", { first_run: true });
+            }
+            void trackEvent("proxy_started", {
+                account_count: accounts.length,
+                mode,
+            });
+            startHeartbeat(accounts.length);
+        }
+        catch {
+            // never let telemetry break the proxy
+        }
     });
 }

package/dist/ui/Dashboard.js

@@ -146,6 +146,13 @@ function LogRow({ log, selected }) {
                     : "gray";
     const bg = selected ? "white" : undefined;
     const fg = (c) => selected ? "black" : c;
+    const sourceLabel = log.source === "cli" ? "cli"
+        : log.source === "desktop" ? "dsk"
+            : log.source === "api" ? "api"
+                : "   ";
+    const sourceColor = log.source === "cli" ? "blue"
+        : log.source === "desktop" ? "magenta"
+            : "gray";
     // Per-request token stats
     const inputTok = (log.cacheReadTokens ?? 0) + (log.cacheCreationTokens ?? 0) + (log.inputTokens ?? 0);
     const outputTok = log.outputTokens ?? 0;
@@ -154,7 +161,7 @@ function LogRow({ log, selected }) {
         : cacheHitPct >= 70 ? "green"
             : cacheHitPct >= 30 ? "yellow"
                 : "red";
-    return (_jsxs(Box, { children: [_jsxs(Text, { backgroundColor: bg, color: fg(undefined), children: [selected ? "▶" : " ", " ", time, "  "] }), _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [typeIcon, " "] }), _jsx(Text, { backgroundColor: bg, color: fg("cyan"), children: log.accountId.slice(0, 22).padEnd(22) }), log.method && log.path
+    return (_jsxs(Box, { children: [_jsxs(Text, { backgroundColor: bg, color: fg(undefined), children: [selected ? "▶" : " ", " ", time, "  "] }), _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [typeIcon, " "] }), _jsxs(Text, { backgroundColor: bg, color: fg(sourceColor), children: [sourceLabel, " "] }), _jsx(Text, { backgroundColor: bg, color: fg("cyan"), children: log.accountId.slice(0, 22).padEnd(22) }), log.method && log.path
                 ? _jsxs(Text, { backgroundColor: bg, color: fg("white"), children: [" ", log.method, " ", log.path.padEnd(14)] })
                 : _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [" ", log.type.padEnd(9)] }), log.statusCode !== undefined && (_jsxs(Text, { backgroundColor: bg, color: fg(statusColor), children: [" ", log.statusCode] })), log.durationMs !== undefined && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: [" ", log.durationMs, "ms"] })), cacheHitPct !== null && (_jsxs(Text, { backgroundColor: bg, color: fg(cacheColor), children: [" \u2191", cacheHitPct, "%"] })), (inputTok > 0 || outputTok > 0) && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: [" ", fmtTok(inputTok), "\u2191 ", fmtTok(outputTok), "\u2193"] })), log.details && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: ["  ", log.details] }))] }));
 }
@@ -174,7 +181,7 @@ function DetailPanel({ log }) {
             : log.statusCode >= 500 ? "red"
                 : log.statusCode >= 400 ? "yellow"
                     : "green";
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, color: isError ? "red" : "cyan", children: " DETAILS " }), _jsxs(Box, { marginTop: 1, flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Time", value: time }), _jsx(Field, { label: "Account", value: log.accountId })] }), _jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Method", value: log.method ?? "—" }), _jsx(Field, { label: "Path", value: log.path ?? "—" })] }), _jsxs(Box, { gap: 2, children: [_jsx(FieldColored, { label: "Status", value: statusLabel, color: statusColor }), _jsx(Field, { label: "Duration", value: log.durationMs !== undefined ? `${log.durationMs}ms` : "—" }), _jsx(Field, { label: "Type", value: log.type })] }), log.details && (_jsx(Box, { children: _jsx(Field, { label: "Details", value: log.details }) })), log.cacheReadTokens !== undefined && (_jsx(Box, { gap: 2, children: _jsx(CacheBreakdown, { read: log.cacheReadTokens, created: log.cacheCreationTokens ?? 0, input: log.inputTokens ?? 0, output: log.outputTokens ?? 0 }) }))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, color: isError ? "red" : "cyan", children: " DETAILS " }), _jsxs(Box, { marginTop: 1, flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Time", value: time }), _jsx(Field, { label: "Account", value: log.accountId })] }), _jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Method", value: log.method ?? "—" }), _jsx(Field, { label: "Path", value: log.path ?? "—" })] }), _jsxs(Box, { gap: 2, children: [_jsx(FieldColored, { label: "Status", value: statusLabel, color: statusColor }), _jsx(Field, { label: "Duration", value: log.durationMs !== undefined ? `${log.durationMs}ms` : "—" }), _jsx(Field, { label: "Type", value: log.type }), _jsx(Field, { label: "Source", value: sourceFullLabel(log.source) })] }), log.details && (_jsx(Box, { children: _jsx(Field, { label: "Details", value: log.details }) })), log.cacheReadTokens !== undefined && (_jsx(Box, { gap: 2, children: _jsx(CacheBreakdown, { read: log.cacheReadTokens, created: log.cacheCreationTokens ?? 0, input: log.inputTokens ?? 0, output: log.outputTokens ?? 0 }) }))] })] }));
 }
 function Field({ label, value }) {
     return (_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: [label, ": "] }), _jsx(Text, { color: "white", children: value })] }));
@@ -215,6 +222,16 @@ function fmtTok(n) {
         return `${(n / 1_000).toFixed(1)}k`;
     return String(n);
 }
+// ─── Source label ─────────────────────────────────────────────────────────────
+function sourceFullLabel(source) {
+    if (source === "cli")
+        return "Claude Code";
+    if (source === "desktop")
+        return "Claude Desktop";
+    if (source === "api")
+        return "API";
+    return "—";
+}
 // ─── HTTP status text ─────────────────────────────────────────────────────────
 function httpStatusText(code) {
     const map = {

package/dist/utils/telemetry.js

@@ -0,0 +1,86 @@
+import os from "os";
+import { isTelemetryEnabled, loadTelemetryState } from "../config/telemetry.js";
+import { detectPlatform } from "./platform.js";
+import { getCurrentVersion } from "./self-update.js";
+// ─── Aptabase configuration ──────────────────────────────────────────────────
+// Aptabase is a privacy-first, open source analytics service.
+// The full payload we send is documented below — search for "trackEvent" calls
+// in the codebase to audit every event.  Nothing here contains PII.
+const APTABASE_APP_KEY = "A-EU-1060569594";
+const APTABASE_ENDPOINT = "https://eu.aptabase.com/api/v0/event";
+const TIMEOUT_MS = 3_000;
+function getOsName() {
+    switch (detectPlatform()) {
+        case "macos": return "macOS";
+        case "linux": return "Linux";
+        case "windows": return "Windows";
+    }
+}
+function getLocale() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    }
+    catch {
+        return process.env["LANG"]?.split(".")[0] ?? "unknown";
+    }
+}
+function getSystemProps() {
+    return {
+        isDebug: false,
+        locale: getLocale(),
+        osName: getOsName(),
+        osVersion: os.release(),
+        appVersion: getCurrentVersion(),
+        engineName: "node",
+        engineVersion: process.versions.node,
+        sdkVersion: `cc-router@${getCurrentVersion()}`,
+    };
+}
+// Session ID: <installId>-<epoch-hours>.  This groups events that belong to the
+// same "session" (proxy run) without leaking any timing precision finer than 1h.
+function getSessionId(installId) {
+    const epochHours = Math.floor(Date.now() / 3_600_000);
+    return `${installId}-${epochHours}`;
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+// Fire-and-forget: never throws, never blocks the caller.  If telemetry is
+// disabled (env var or opt-out) this is a synchronous no-op.
+export async function trackEvent(eventName, props) {
+    try {
+        if (!isTelemetryEnabled())
+            return;
+        const state = loadTelemetryState();
+        const body = {
+            timestamp: new Date().toISOString(),
+            sessionId: getSessionId(state.installId),
+            eventName,
+            systemProps: getSystemProps(),
+            props: props ?? {},
+        };
+        await fetch(APTABASE_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "App-Key": APTABASE_APP_KEY,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Silently swallow — telemetry must never disrupt the proxy
+    }
+}
+// Start a heartbeat that fires every 6 hours while the proxy is running.
+// Uses .unref() so the timer does not prevent Node from exiting.
+export function startHeartbeat(accountCount) {
+    const startTime = Date.now();
+    const timer = setInterval(() => {
+        const uptimeHours = Math.floor((Date.now() - startTime) / 3_600_000);
+        trackEvent("proxy_heartbeat", {
+            uptime_hours: uptimeHours,
+            account_count: accountCount,
+        });
+    }, 6 * 60 * 60 * 1000);
+    timer.unref();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cc-router",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Round-robin proxy for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {