npm - @curatedmcp/tokenshield-core - Versions diffs - 0.2.1 → 1.0.0 - Mend

@curatedmcp/tokenshield-core 0.2.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -8,6 +8,8 @@ export { StreamUsageAccumulator, usageFromJson } from "./proxy/usage.js";
 export { handleAnthropicRequest, setProcessorEnabled, getProcessorEnabledIds, getResponseCacheStats, } from "./proxy/anthropic-passthrough.js";
 export { providerForPath, anthropic } from "./providers/registry.js";
 export type { Provider, Conversation, ConvMessage, ConvBlock, ProviderId } from "./providers/types.js";
+export { telemetry, Telemetry, isTelemetryEnabled, setTelemetryEnabled, isFirstRun, markFirstRunComplete, firstRunBanner, getAnonId, } from "./telemetry.js";
+export type { TelemetryRecord } from "./telemetry.js";
 export { Pipeline } from "./processors/pipeline.js";
 export { conversationDedup } from "./processors/conversation-dedup.js";
 export { ResponseCache } from "./processors/response-cache.js";

package/dist/index.js CHANGED Viewed

@@ -5,6 +5,7 @@ export { SSEParser } from "./proxy/sse.js";
 export { StreamUsageAccumulator, usageFromJson } from "./proxy/usage.js";
 export { handleAnthropicRequest, setProcessorEnabled, getProcessorEnabledIds, getResponseCacheStats, } from "./proxy/anthropic-passthrough.js";
 export { providerForPath, anthropic } from "./providers/registry.js";
+export { telemetry, Telemetry, isTelemetryEnabled, setTelemetryEnabled, isFirstRun, markFirstRunComplete, firstRunBanner, getAnonId, } from "./telemetry.js";
 export { Pipeline } from "./processors/pipeline.js";
 export { conversationDedup } from "./processors/conversation-dedup.js";
 export { ResponseCache } from "./processors/response-cache.js";

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EACL,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,SAAS,GACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/server.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { createServer } from "node:http";
 import { handleAnthropicRequest } from "./proxy/anthropic-passthrough.js";
 import { Ledger } from "./ledger.js";
+import { telemetry } from "./telemetry.js";
 export function defaultConfig(overrides = {}) {
     const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? ".";
     return {
@@ -29,6 +30,7 @@ async function closeServer(server) {
 }
 export async function start(opts) {
     const ledger = new Ledger(opts.config.ledgerPath);
+    const isTeamDeployment = opts.config.bind === "0.0.0.0";
     const sink = (r) => {
         try {
             ledger.record(r);
@@ -36,6 +38,30 @@ export async function start(opts) {
         catch {
             // ledger errors must never break the request path
         }
+        try {
+            // Approximate byte counts from token estimates (industry rule-of-thumb)
+            const tokensIn = r.usageRaw.inputTokens + r.usageRaw.cacheReadInputTokens;
+            const tokensOut = r.usageSent.inputTokens + r.usageSent.cacheReadInputTokens;
+            const TOKEN_TO_BYTE = 3.5;
+            const bytesIn = Math.round(tokensIn * TOKEN_TO_BYTE);
+            const bytesOut = Math.round(tokensOut * TOKEN_TO_BYTE);
+            telemetry.record({
+                bytesIn,
+                bytesOut,
+                bytesSaved: Math.max(0, bytesIn - bytesOut),
+                inputTokens: r.usageRaw.inputTokens,
+                outputTokens: r.usageRaw.outputTokens,
+                dollarsEstimate: r.dollarsRaw,
+                dollarsSaved: r.dollarsSaved,
+                provider: "anthropic",
+                model: r.model,
+                client: null,
+                teamDeployment: isTeamDeployment,
+            });
+        }
+        catch {
+            // telemetry must never break the request path
+        }
         opts.onRecord?.(r);
     };
     const proxy = createServer((req, res) => {
@@ -45,6 +71,15 @@ export async function start(opts) {
             res.end(JSON.stringify({ ok: true, version: "0.1.0" }));
             return;
         }
+        // Friendly landing page for humans who hit the proxy port in a browser.
+        // The proxy itself only speaks /v1/messages, /v1/messages/stream, etc.
+        if (req.method === "GET" && (req.url === "/" || req.url === "/index.html")) {
+            res.statusCode = 200;
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            res.setHeader("cache-control", "no-store");
+            res.end(proxyLandingHtml(opts.config));
+            return;
+        }
         handleAnthropicRequest(req, res, opts.config, sink).catch((err) => {
             if (!res.headersSent) {
                 res.statusCode = 500;
@@ -118,6 +153,7 @@ export async function start(opts) {
         ledger,
         close: async () => {
             clearInterval(retentionInterval);
+            telemetry.stop();
             await Promise.all([closeServer(proxy), closeServer(dashboard)]);
             ledger.close();
         },
@@ -127,4 +163,67 @@ function defaultDashboardHtml() {
     return `<!doctype html><meta charset="utf-8"><title>TokenShield</title>
 <body><h1>TokenShield</h1><p>Dashboard renderer not provided.</p></body>`;
 }
+function proxyLandingHtml(config) {
+    const dashUrl = `http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.dashboardPort}`;
+    const exportLine = `export ANTHROPIC_BASE_URL=http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.port}`;
+    return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<title>TokenShield proxy</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  *{box-sizing:border-box}
+  body{font:15px/1.55 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0b0d12;color:#e6e7ea;margin:0;padding:40px 20px;display:flex;justify-content:center}
+  main{max-width:640px;width:100%}
+  .pill{display:inline-flex;align-items:center;gap:6px;background:rgba(34,197,94,.12);color:#4ade80;padding:4px 10px;border-radius:999px;font-size:12px;font-weight:600}
+  .pill::before{content:'';width:6px;height:6px;border-radius:50%;background:#22c55e;animation:pulse 2s ease-in-out infinite}
+  @keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
+  h1{font-size:28px;margin:16px 0 8px;font-weight:700}
+  .subtitle{color:#9ca3af;margin:0 0 28px}
+  .card{background:rgba(255,255,255,.04);border:1px solid rgba(255,255,255,.08);border-radius:12px;padding:20px 22px;margin:14px 0}
+  .card h2{font-size:14px;text-transform:uppercase;letter-spacing:.06em;color:#a5b4fc;margin:0 0 8px}
+  code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:rgba(255,255,255,.07);padding:2px 6px;border-radius:4px;font-size:13px;color:#fbbf24}
+  pre{background:rgba(0,0,0,.4);border:1px solid rgba(255,255,255,.08);border-radius:8px;padding:14px 16px;overflow-x:auto;margin:8px 0 0}
+  pre code{background:none;padding:0;color:#86efac}
+  a{color:#a5b4fc;text-decoration:none;border-bottom:1px solid rgba(165,180,252,.3)}
+  a:hover{border-color:#a5b4fc}
+  .footer{margin-top:32px;font-size:12px;color:#6b7280;text-align:center}
+  .dash-cta{display:inline-block;background:#22c55e;color:#0b0d12;font-weight:600;padding:10px 20px;border-radius:8px;text-decoration:none;border:0;margin-top:6px}
+  .dash-cta:hover{background:#16a34a}
+</style>
+</head><body><main>
+  <span class="pill">TokenShield is running</span>
+  <h1>This is the proxy, not the dashboard.</h1>
+  <p class="subtitle">You hit port ${config.port} — that's where Claude Code (or Cursor, Windsurf, Aider) sends its API requests. The proxy doesn't serve a UI; it forwards traffic to Anthropic.</p>
+  <div class="card">
+    <h2>→ Want the dashboard?</h2>
+    <p style="margin:0 0 12px">Live spend, requests, savings, and recent traffic:</p>
+    <a class="dash-cta" href="${dashUrl}">Open dashboard →</a>
+  </div>
+  <div class="card">
+    <h2>→ Route Claude Code through this proxy</h2>
+    <p style="margin:0 0 4px">In the shell where you run <code>claude</code>:</p>
+    <pre><code>${exportLine}</code></pre>
+    <p style="margin:12px 0 0;font-size:13px;color:#9ca3af">Your <code>ANTHROPIC_API_KEY</code> stays where it is. TokenShield never reads it.</p>
+  </div>
+  <div class="card">
+    <h2>→ Other clients</h2>
+    <p style="margin:0;font-size:13px;color:#9ca3af">
+      <strong style="color:#e6e7ea">Cursor / Windsurf:</strong> Settings → AI → Custom Base URL = <code>http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.port}</code>
+      <br><br>
+      <strong style="color:#e6e7ea">Anthropic SDK:</strong> set <code>baseURL</code> when instantiating the client.
+      <br><br>
+      <strong style="color:#e6e7ea">Auto-configure your shell:</strong> <code>tokenshield integrations enable claude-code</code>
+    </p>
+  </div>
+  <p class="footer">
+    Docs: <a href="https://curatedmcp.com/tokenshield">curatedmcp.com/tokenshield</a> &nbsp;·&nbsp;
+    Source: <a href="https://github.com/oneprofile-dev/tokenshield">github.com/oneprofile-dev/tokenshield</a>
+  </p>
+</main></body></html>`;
+}
 //# sourceMappingURL=server.js.map

package/dist/server.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA2C,MAAM,WAAW,CAAC;AAElF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;~~AAiBrC~~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"}
1	+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+export declare function isTelemetryEnabled(): boolean;
+export declare function setTelemetryEnabled(on: boolean): void;
+export declare function getAnonId(): string;
+export declare function isFirstRun(): boolean;
+export declare function markFirstRunComplete(): void;
+export declare function firstRunBanner(): string;
+export interface TelemetryRecord {
+    bytesIn: number;
+    bytesOut: number;
+    bytesSaved: number;
+    inputTokens: number;
+    outputTokens: number;
+    dollarsEstimate: number;
+    dollarsSaved: number;
+    provider: "anthropic" | "openai" | "gemini" | null;
+    model: string | null;
+    client: string | null;
+    teamDeployment: boolean;
+}
+export declare class Telemetry {
+    private counters;
+    private timer;
+    private flushing;
+    start(): void;
+    stop(): void;
+    record(r: TelemetryRecord): void;
+    flush(): Promise<void>;
+}
+export declare const telemetry: Telemetry;

package/dist/telemetry.js ADDED Viewed

@@ -0,0 +1,218 @@
+import { createHash } from "node:crypto";
+import { hostname, platform, userInfo } from "node:os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const ENDPOINT = process.env["TOKENSHIELD_TELEMETRY_URL"] ?? "https://curatedmcp.com/api/v1/tokenshield/telemetry";
+// Flush every N requests OR every M minutes, whichever first. Keeps the
+// network footprint tiny and ensures dev sessions still report at the end.
+const FLUSH_EVERY_REQUESTS = 50;
+const FLUSH_EVERY_MS = 5 * 60 * 1000;
+function telemetryDir() {
+    const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? ".";
+    return join(home, ".tokenshield");
+}
+function settingsFile() {
+    return join(telemetryDir(), "settings.json");
+}
+function loadSettings() {
+    const file = settingsFile();
+    if (existsSync(file)) {
+        try {
+            const raw = readFileSync(file, "utf8");
+            const parsed = JSON.parse(raw);
+            return {
+                telemetry: parsed.telemetry === "off" ? "off" : "on",
+                anonId: parsed.anonId ?? generateAnonId(),
+                firstRunCompleted: parsed.firstRunCompleted ?? false,
+            };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return {
+        telemetry: "on",
+        anonId: generateAnonId(),
+        firstRunCompleted: false,
+    };
+}
+function saveSettings(s) {
+    const dir = telemetryDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(settingsFile(), JSON.stringify(s, null, 2), "utf8");
+}
+function generateAnonId() {
+    // Deterministic per-machine: sha256 of hostname + username.
+    // Cannot be reversed to a person; cannot be cross-correlated with other
+    // CuratedMCP products without explicit account linking.
+    const seed = `${hostname()}::${userInfo().username}::tokenshield`;
+    return createHash("sha256").update(seed).digest("hex");
+}
+export function isTelemetryEnabled() {
+    // Hard kill switches — these win over settings file
+    if (process.env["TOKENSHIELD_TELEMETRY"] === "0" || process.env["TOKENSHIELD_TELEMETRY"] === "off")
+        return false;
+    if (process.env["DO_NOT_TRACK"] === "1")
+        return false;
+    if (process.env["CI"] === "true")
+        return false;
+    const s = loadSettings();
+    return s.telemetry === "on";
+}
+export function setTelemetryEnabled(on) {
+    const s = loadSettings();
+    s.telemetry = on ? "on" : "off";
+    s.firstRunCompleted = true;
+    saveSettings(s);
+}
+export function getAnonId() {
+    return loadSettings().anonId;
+}
+export function isFirstRun() {
+    return !loadSettings().firstRunCompleted;
+}
+export function markFirstRunComplete() {
+    const s = loadSettings();
+    s.firstRunCompleted = true;
+    saveSettings(s);
+}
+export function firstRunBanner() {
+    return [
+        "",
+        "  ┌──────────────────────────────────────────────────────────────────┐",
+        "  │  TokenShield collects anonymous usage stats by default:          │",
+        "  │    • Aggregate token counts and $ saved                          │",
+        "  │    • CLI version, Node version, OS                               │",
+        "  │    • Provider (anthropic/openai/gemini) + most-used model        │",
+        "  │                                                                  │",
+        "  │  Never sent: prompts, responses, file contents, API keys,        │",
+        "  │  IP address, hostname, username, file paths.                     │",
+        "  │                                                                  │",
+        "  │  Disable any time:   tokenshield telemetry off                   │",
+        "  │  Or via env:         TOKENSHIELD_TELEMETRY=0 (or DO_NOT_TRACK=1) │",
+        "  │  Source:             https://github.com/oneprofile-dev/tokenshield │",
+        "  └──────────────────────────────────────────────────────────────────┘",
+        "",
+    ].join("\n");
+}
+function emptyCounters() {
+    return {
+        requests: 0,
+        bytesIn: 0,
+        bytesOut: 0,
+        bytesSaved: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        dollarsEstimate: 0,
+        dollarsSaved: 0,
+        modelCounts: new Map(),
+        provider: null,
+        client: null,
+        teamDeployment: false,
+    };
+}
+export class Telemetry {
+    counters = emptyCounters();
+    timer = null;
+    flushing = false;
+    start() {
+        if (!isTelemetryEnabled())
+            return;
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_EVERY_MS);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        // Best-effort final flush — fire and forget
+        void this.flush();
+    }
+    record(r) {
+        if (!isTelemetryEnabled())
+            return;
+        const c = this.counters;
+        c.requests += 1;
+        c.bytesIn += r.bytesIn;
+        c.bytesOut += r.bytesOut;
+        c.bytesSaved += r.bytesSaved;
+        c.inputTokens += r.inputTokens;
+        c.outputTokens += r.outputTokens;
+        c.dollarsEstimate += r.dollarsEstimate;
+        c.dollarsSaved += r.dollarsSaved;
+        if (r.provider)
+            c.provider = r.provider;
+        if (r.client)
+            c.client = r.client;
+        if (r.teamDeployment)
+            c.teamDeployment = true;
+        if (r.model)
+            c.modelCounts.set(r.model, (c.modelCounts.get(r.model) ?? 0) + 1);
+        if (c.requests >= FLUSH_EVERY_REQUESTS) {
+            void this.flush();
+        }
+    }
+    async flush() {
+        if (this.flushing)
+            return;
+        if (!isTelemetryEnabled())
+            return;
+        if (this.counters.requests === 0)
+            return;
+        this.flushing = true;
+        const snap = this.counters;
+        this.counters = emptyCounters();
+        let topModel = null;
+        let topModelCount = 0;
+        for (const [model, count] of snap.modelCounts) {
+            if (count > topModelCount) {
+                topModel = model;
+                topModelCount = count;
+            }
+        }
+        const cliVersion = process.env["npm_package_version"] ?? "unknown";
+        const payload = {
+            anonId: getAnonId(),
+            cliVersion,
+            nodeVersion: process.version,
+            platform: platform(),
+            requests: snap.requests,
+            bytesIn: snap.bytesIn,
+            bytesOut: snap.bytesOut,
+            bytesSaved: snap.bytesSaved,
+            inputTokens: snap.inputTokens,
+            outputTokens: snap.outputTokens,
+            dollarsEstimate: Math.round(snap.dollarsEstimate * 1e6) / 1e6,
+            dollarsSaved: Math.round(snap.dollarsSaved * 1e6) / 1e6,
+            provider: snap.provider ?? undefined,
+            topModel: topModel ?? undefined,
+            client: snap.client ?? undefined,
+            teamDeployment: snap.teamDeployment,
+        };
+        try {
+            const controller = new AbortController();
+            const t = setTimeout(() => controller.abort(), 5000);
+            await fetch(ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(t);
+        }
+        catch {
+            // Telemetry must NEVER affect user experience. Drop the batch silently.
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}
+export const telemetry = new Telemetry();
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAW,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,IAAI,qDAAqD,CAAC;AAEnH,wEAAwE;AACxE,2EAA2E;AAC3E,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,SAAS,YAAY;IACnB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,eAAe,CAAC,CAAC;AAC/C,CAAC;AAQD,SAAS,YAAY;IACnB,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAC;YACpD,OAAO;gBACL,SAAS,EAAE,MAAM,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;gBACpD,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,cAAc,EAAE;gBACzC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,KAAK;aACrD,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IACD,OAAO;QACL,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,cAAc,EAAE;QACxB,iBAAiB,EAAE,KAAK;KACzB,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,CAAW;IAC/B,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,aAAa,CAAC,YAAY,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,cAAc;IACrB,4DAA4D;IAC5D,wEAAwE;IACxE,wDAAwD;IACxD,MAAM,IAAI,GAAG,GAAG,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAAC,QAAQ,eAAe,CAAC;IAClE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,oDAAoD;IACpD,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjH,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAE/C,MAAM,CAAC,GAAG,YAAY,EAAE,CAAC;IACzB,OAAO,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,EAAW;IAC7C,MAAM,CAAC,GAAG,YAAY,EAAE,CAAC;IACzB,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IAChC,CAAC,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,YAAY,EAAE,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,CAAC,YAAY,EAAE,CAAC,iBAAiB,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,YAAY,EAAE,CAAC;IACzB,CAAC,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,EAAE;QACF,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAmBD,SAAS,aAAa;IACpB,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,CAAC;QACX,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,eAAe,EAAE,CAAC;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,IAAI,GAAG,EAAE;QACtB,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,cAAc,EAAE,KAAK;KACtB,CAAC;AACJ,CAAC;AAgBD,MAAM,OAAO,SAAS;IACZ,QAAQ,GAAG,aAAa,EAAE,CAAC;IAC3B,KAAK,GAA0B,IAAI,CAAC;IACpC,QAAQ,GAAG,KAAK,CAAC;IAEzB,KAAK;QACH,IAAI,CAAC,kBAAkB,EAAE;YAAE,OAAO;QAClC,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC,EAAE,cAAc,CAAC,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,4CAA4C;QAC5C,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,CAAkB;QACvB,IAAI,CAAC,kBAAkB,EAAE;YAAE,OAAO;QAElC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QACxB,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;QACvB,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC;QACzB,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,CAAC;QAC7B,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,CAAC;QAC/B,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC;QACjC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,eAAe,CAAC;QACvC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC;QACjC,IAAI,CAAC,CAAC,QAAQ;YAAE,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QACxC,IAAI,CAAC,CAAC,MAAM;YAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QAClC,IAAI,CAAC,CAAC,cAAc;YAAE,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC;QAC9C,IAAI,CAAC,CAAC,KAAK;YAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAE/E,IAAI,CAAC,CAAC,QAAQ,IAAI,oBAAoB,EAAE,CAAC;YACvC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,kBAAkB,EAAE;YAAE,OAAO;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,CAAC;YAAE,OAAO;QAEzC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,aAAa,EAAE,CAAC;QAEhC,IAAI,QAAQ,GAAkB,IAAI,CAAC;QACnC,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC9C,IAAI,KAAK,GAAG,aAAa,EAAE,CAAC;gBAC1B,QAAQ,GAAG,KAAK,CAAC;gBACjB,aAAa,GAAG,KAAK,CAAC;YACxB,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,SAAS,CAAC;QAEnE,MAAM,OAAO,GAAG;YACd,MAAM,EAAE,SAAS,EAAE;YACnB,UAAU;YACV,WAAW,EAAE,OAAO,CAAC,OAAO;YAC5B,QAAQ,EAAE,QAAQ,EAAE;YACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,GAAG,CAAC,GAAG,GAAG;YAC7D,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,GAAG;YACvD,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,SAAS;YACpC,QAAQ,EAAE,QAAQ,IAAI,SAAS;YAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS;YAChC,cAAc,EAAE,IAAI,CAAC,cAAc;SACpC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;YACrD,MAAM,KAAK,CAAC,QAAQ,EAAE;gBACpB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,YAAY,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@curatedmcp/tokenshield-core",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "description": "TokenShield proxy engine — Anthropic API-layer middleware with token accounting",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts CHANGED Viewed

@@ -13,6 +13,17 @@ export {
 } from "./proxy/anthropic-passthrough.js";
 export { providerForPath, anthropic } from "./providers/registry.js";
 export type { Provider, Conversation, ConvMessage, ConvBlock, ProviderId } from "./providers/types.js";
+export {
+  telemetry,
+  Telemetry,
+  isTelemetryEnabled,
+  setTelemetryEnabled,
+  isFirstRun,
+  markFirstRunComplete,
+  firstRunBanner,
+  getAnonId,
+} from "./telemetry.js";
+export type { TelemetryRecord } from "./telemetry.js";
 export { Pipeline } from "./processors/pipeline.js";
 export { conversationDedup } from "./processors/conversation-dedup.js";
 export { ResponseCache } from "./processors/response-cache.js";

package/src/server.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import { createServer, IncomingMessage, ServerResponse, Server } from "node:http
 import type { ProxyConfig, RequestRecord } from "./types.js";
 import { handleAnthropicRequest } from "./proxy/anthropic-passthrough.js";
 import { Ledger } from "./ledger.js";
+import { telemetry } from "./telemetry.js";
 export interface ProxyServerHandle {
   proxy: Server;
@@ -50,12 +51,36 @@ async function closeServer(server: Server): Promise<void> {
 export async function start(opts: StartOptions): Promise<ProxyServerHandle> {
   const ledger = new Ledger(opts.config.ledgerPath);
+  const isTeamDeployment = opts.config.bind === "0.0.0.0";
   const sink = (r: RequestRecord): void => {
     try {
       ledger.record(r);
     } catch {
       // ledger errors must never break the request path
     }
+    try {
+      // Approximate byte counts from token estimates (industry rule-of-thumb)
+      const tokensIn = r.usageRaw.inputTokens + r.usageRaw.cacheReadInputTokens;
+      const tokensOut = r.usageSent.inputTokens + r.usageSent.cacheReadInputTokens;
+      const TOKEN_TO_BYTE = 3.5;
+      const bytesIn = Math.round(tokensIn * TOKEN_TO_BYTE);
+      const bytesOut = Math.round(tokensOut * TOKEN_TO_BYTE);
+      telemetry.record({
+        bytesIn,
+        bytesOut,
+        bytesSaved: Math.max(0, bytesIn - bytesOut),
+        inputTokens: r.usageRaw.inputTokens,
+        outputTokens: r.usageRaw.outputTokens,
+        dollarsEstimate: r.dollarsRaw,
+        dollarsSaved: r.dollarsSaved,
+        provider: "anthropic",
+        model: r.model,
+        client: null,
+        teamDeployment: isTeamDeployment,
+      });
+    } catch {
+      // telemetry must never break the request path
+    }
     opts.onRecord?.(r);
   };
@@ -66,6 +91,15 @@ export async function start(opts: StartOptions): Promise<ProxyServerHandle> {
       res.end(JSON.stringify({ ok: true, version: "0.1.0" }));
       return;
     }
+    // Friendly landing page for humans who hit the proxy port in a browser.
+    // The proxy itself only speaks /v1/messages, /v1/messages/stream, etc.
+    if (req.method === "GET" && (req.url === "/" || req.url === "/index.html")) {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/html; charset=utf-8");
+      res.setHeader("cache-control", "no-store");
+      res.end(proxyLandingHtml(opts.config));
+      return;
+    }
     handleAnthropicRequest(req, res, opts.config, sink).catch((err: unknown) => {
       if (!res.headersSent) {
         res.statusCode = 500;
@@ -142,6 +176,7 @@ export async function start(opts: StartOptions): Promise<ProxyServerHandle> {
     ledger,
     close: async () => {
       clearInterval(retentionInterval);
+      telemetry.stop();
       await Promise.all([closeServer(proxy), closeServer(dashboard)]);
       ledger.close();
     },
@@ -152,3 +187,67 @@ function defaultDashboardHtml(): string {
   return `<!doctype html><meta charset="utf-8"><title>TokenShield</title>
 <body><h1>TokenShield</h1><p>Dashboard renderer not provided.</p></body>`;
 }
+function proxyLandingHtml(config: ProxyConfig): string {
+  const dashUrl = `http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.dashboardPort}`;
+  const exportLine = `export ANTHROPIC_BASE_URL=http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.port}`;
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<title>TokenShield proxy</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  *{box-sizing:border-box}
+  body{font:15px/1.55 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0b0d12;color:#e6e7ea;margin:0;padding:40px 20px;display:flex;justify-content:center}
+  main{max-width:640px;width:100%}
+  .pill{display:inline-flex;align-items:center;gap:6px;background:rgba(34,197,94,.12);color:#4ade80;padding:4px 10px;border-radius:999px;font-size:12px;font-weight:600}
+  .pill::before{content:'';width:6px;height:6px;border-radius:50%;background:#22c55e;animation:pulse 2s ease-in-out infinite}
+  @keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
+  h1{font-size:28px;margin:16px 0 8px;font-weight:700}
+  .subtitle{color:#9ca3af;margin:0 0 28px}
+  .card{background:rgba(255,255,255,.04);border:1px solid rgba(255,255,255,.08);border-radius:12px;padding:20px 22px;margin:14px 0}
+  .card h2{font-size:14px;text-transform:uppercase;letter-spacing:.06em;color:#a5b4fc;margin:0 0 8px}
+  code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:rgba(255,255,255,.07);padding:2px 6px;border-radius:4px;font-size:13px;color:#fbbf24}
+  pre{background:rgba(0,0,0,.4);border:1px solid rgba(255,255,255,.08);border-radius:8px;padding:14px 16px;overflow-x:auto;margin:8px 0 0}
+  pre code{background:none;padding:0;color:#86efac}
+  a{color:#a5b4fc;text-decoration:none;border-bottom:1px solid rgba(165,180,252,.3)}
+  a:hover{border-color:#a5b4fc}
+  .footer{margin-top:32px;font-size:12px;color:#6b7280;text-align:center}
+  .dash-cta{display:inline-block;background:#22c55e;color:#0b0d12;font-weight:600;padding:10px 20px;border-radius:8px;text-decoration:none;border:0;margin-top:6px}
+  .dash-cta:hover{background:#16a34a}
+</style>
+</head><body><main>
+  <span class="pill">TokenShield is running</span>
+  <h1>This is the proxy, not the dashboard.</h1>
+  <p class="subtitle">You hit port ${config.port} — that's where Claude Code (or Cursor, Windsurf, Aider) sends its API requests. The proxy doesn't serve a UI; it forwards traffic to Anthropic.</p>
+  <div class="card">
+    <h2>→ Want the dashboard?</h2>
+    <p style="margin:0 0 12px">Live spend, requests, savings, and recent traffic:</p>
+    <a class="dash-cta" href="${dashUrl}">Open dashboard →</a>
+  </div>
+  <div class="card">
+    <h2>→ Route Claude Code through this proxy</h2>
+    <p style="margin:0 0 4px">In the shell where you run <code>claude</code>:</p>
+    <pre><code>${exportLine}</code></pre>
+    <p style="margin:12px 0 0;font-size:13px;color:#9ca3af">Your <code>ANTHROPIC_API_KEY</code> stays where it is. TokenShield never reads it.</p>
+  </div>
+  <div class="card">
+    <h2>→ Other clients</h2>
+    <p style="margin:0;font-size:13px;color:#9ca3af">
+      <strong style="color:#e6e7ea">Cursor / Windsurf:</strong> Settings → AI → Custom Base URL = <code>http://${config.bind === "0.0.0.0" ? "127.0.0.1" : config.bind}:${config.port}</code>
+      <br><br>
+      <strong style="color:#e6e7ea">Anthropic SDK:</strong> set <code>baseURL</code> when instantiating the client.
+      <br><br>
+      <strong style="color:#e6e7ea">Auto-configure your shell:</strong> <code>tokenshield integrations enable claude-code</code>
+    </p>
+  </div>
+  <p class="footer">
+    Docs: <a href="https://curatedmcp.com/tokenshield">curatedmcp.com/tokenshield</a> &nbsp;·&nbsp;
+    Source: <a href="https://github.com/oneprofile-dev/tokenshield">github.com/oneprofile-dev/tokenshield</a>
+  </p>
+</main></body></html>`;
+}

package/src/telemetry.ts ADDED Viewed

@@ -0,0 +1,265 @@
+import { createHash } from "node:crypto";
+import { hostname, platform, userInfo } from "node:os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const ENDPOINT = process.env["TOKENSHIELD_TELEMETRY_URL"] ?? "https://curatedmcp.com/api/v1/tokenshield/telemetry";
+// Flush every N requests OR every M minutes, whichever first. Keeps the
+// network footprint tiny and ensures dev sessions still report at the end.
+const FLUSH_EVERY_REQUESTS = 50;
+const FLUSH_EVERY_MS = 5 * 60 * 1000;
+function telemetryDir(): string {
+  const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? ".";
+  return join(home, ".tokenshield");
+}
+function settingsFile(): string {
+  return join(telemetryDir(), "settings.json");
+}
+interface Settings {
+  telemetry: "on" | "off";
+  anonId: string;
+  firstRunCompleted: boolean;
+}
+function loadSettings(): Settings {
+  const file = settingsFile();
+  if (existsSync(file)) {
+    try {
+      const raw = readFileSync(file, "utf8");
+      const parsed = JSON.parse(raw) as Partial<Settings>;
+      return {
+        telemetry: parsed.telemetry === "off" ? "off" : "on",
+        anonId: parsed.anonId ?? generateAnonId(),
+        firstRunCompleted: parsed.firstRunCompleted ?? false,
+      };
+    } catch {
+      // fall through
+    }
+  }
+  return {
+    telemetry: "on",
+    anonId: generateAnonId(),
+    firstRunCompleted: false,
+  };
+}
+function saveSettings(s: Settings): void {
+  const dir = telemetryDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(settingsFile(), JSON.stringify(s, null, 2), "utf8");
+}
+function generateAnonId(): string {
+  // Deterministic per-machine: sha256 of hostname + username.
+  // Cannot be reversed to a person; cannot be cross-correlated with other
+  // CuratedMCP products without explicit account linking.
+  const seed = `${hostname()}::${userInfo().username}::tokenshield`;
+  return createHash("sha256").update(seed).digest("hex");
+}
+export function isTelemetryEnabled(): boolean {
+  // Hard kill switches — these win over settings file
+  if (process.env["TOKENSHIELD_TELEMETRY"] === "0" || process.env["TOKENSHIELD_TELEMETRY"] === "off") return false;
+  if (process.env["DO_NOT_TRACK"] === "1") return false;
+  if (process.env["CI"] === "true") return false;
+  const s = loadSettings();
+  return s.telemetry === "on";
+}
+export function setTelemetryEnabled(on: boolean): void {
+  const s = loadSettings();
+  s.telemetry = on ? "on" : "off";
+  s.firstRunCompleted = true;
+  saveSettings(s);
+}
+export function getAnonId(): string {
+  return loadSettings().anonId;
+}
+export function isFirstRun(): boolean {
+  return !loadSettings().firstRunCompleted;
+}
+export function markFirstRunComplete(): void {
+  const s = loadSettings();
+  s.firstRunCompleted = true;
+  saveSettings(s);
+}
+export function firstRunBanner(): string {
+  return [
+    "",
+    "  ┌──────────────────────────────────────────────────────────────────┐",
+    "  │  TokenShield collects anonymous usage stats by default:          │",
+    "  │    • Aggregate token counts and $ saved                          │",
+    "  │    • CLI version, Node version, OS                               │",
+    "  │    • Provider (anthropic/openai/gemini) + most-used model        │",
+    "  │                                                                  │",
+    "  │  Never sent: prompts, responses, file contents, API keys,        │",
+    "  │  IP address, hostname, username, file paths.                     │",
+    "  │                                                                  │",
+    "  │  Disable any time:   tokenshield telemetry off                   │",
+    "  │  Or via env:         TOKENSHIELD_TELEMETRY=0 (or DO_NOT_TRACK=1) │",
+    "  │  Source:             https://github.com/oneprofile-dev/tokenshield │",
+    "  └──────────────────────────────────────────────────────────────────┘",
+    "",
+  ].join("\n");
+}
+// ─── Batched counters ────────────────────────────────────────────────────────
+interface Counters {
+  requests: number;
+  bytesIn: number;
+  bytesOut: number;
+  bytesSaved: number;
+  inputTokens: number;
+  outputTokens: number;
+  dollarsEstimate: number;
+  dollarsSaved: number;
+  modelCounts: Map<string, number>;
+  provider: string | null;
+  client: string | null;
+  teamDeployment: boolean;
+}
+function emptyCounters(): Counters {
+  return {
+    requests: 0,
+    bytesIn: 0,
+    bytesOut: 0,
+    bytesSaved: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    dollarsEstimate: 0,
+    dollarsSaved: 0,
+    modelCounts: new Map(),
+    provider: null,
+    client: null,
+    teamDeployment: false,
+  };
+}
+export interface TelemetryRecord {
+  bytesIn: number;
+  bytesOut: number;
+  bytesSaved: number;
+  inputTokens: number;
+  outputTokens: number;
+  dollarsEstimate: number;
+  dollarsSaved: number;
+  provider: "anthropic" | "openai" | "gemini" | null;
+  model: string | null;
+  client: string | null;
+  teamDeployment: boolean;
+}
+export class Telemetry {
+  private counters = emptyCounters();
+  private timer: NodeJS.Timeout | null = null;
+  private flushing = false;
+  start(): void {
+    if (!isTelemetryEnabled()) return;
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, FLUSH_EVERY_MS);
+    this.timer.unref?.();
+  }
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    // Best-effort final flush — fire and forget
+    void this.flush();
+  }
+  record(r: TelemetryRecord): void {
+    if (!isTelemetryEnabled()) return;
+    const c = this.counters;
+    c.requests += 1;
+    c.bytesIn += r.bytesIn;
+    c.bytesOut += r.bytesOut;
+    c.bytesSaved += r.bytesSaved;
+    c.inputTokens += r.inputTokens;
+    c.outputTokens += r.outputTokens;
+    c.dollarsEstimate += r.dollarsEstimate;
+    c.dollarsSaved += r.dollarsSaved;
+    if (r.provider) c.provider = r.provider;
+    if (r.client) c.client = r.client;
+    if (r.teamDeployment) c.teamDeployment = true;
+    if (r.model) c.modelCounts.set(r.model, (c.modelCounts.get(r.model) ?? 0) + 1);
+    if (c.requests >= FLUSH_EVERY_REQUESTS) {
+      void this.flush();
+    }
+  }
+  async flush(): Promise<void> {
+    if (this.flushing) return;
+    if (!isTelemetryEnabled()) return;
+    if (this.counters.requests === 0) return;
+    this.flushing = true;
+    const snap = this.counters;
+    this.counters = emptyCounters();
+    let topModel: string | null = null;
+    let topModelCount = 0;
+    for (const [model, count] of snap.modelCounts) {
+      if (count > topModelCount) {
+        topModel = model;
+        topModelCount = count;
+      }
+    }
+    const cliVersion = process.env["npm_package_version"] ?? "unknown";
+    const payload = {
+      anonId: getAnonId(),
+      cliVersion,
+      nodeVersion: process.version,
+      platform: platform(),
+      requests: snap.requests,
+      bytesIn: snap.bytesIn,
+      bytesOut: snap.bytesOut,
+      bytesSaved: snap.bytesSaved,
+      inputTokens: snap.inputTokens,
+      outputTokens: snap.outputTokens,
+      dollarsEstimate: Math.round(snap.dollarsEstimate * 1e6) / 1e6,
+      dollarsSaved: Math.round(snap.dollarsSaved * 1e6) / 1e6,
+      provider: snap.provider ?? undefined,
+      topModel: topModel ?? undefined,
+      client: snap.client ?? undefined,
+      teamDeployment: snap.teamDeployment,
+    };
+    try {
+      const controller = new AbortController();
+      const t = setTimeout(() => controller.abort(), 5000);
+      await fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+      clearTimeout(t);
+    } catch {
+      // Telemetry must NEVER affect user experience. Drop the batch silently.
+    } finally {
+      this.flushing = false;
+    }
+  }
+}
+export const telemetry = new Telemetry();