@tokensbill/node 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @tokensbill/node
+
+**One line. Every AI token tracked.** Automatically captures Anthropic / OpenAI / Gemini token usage from your app's outgoing AI calls and streams it to your [TokensBill](https://tokensbill.com) dashboard — so you can see exactly where your AI spend goes.
+
+## Install
+
+```bash
+npm install @tokensbill/node
+```
+
+## Use — one line at startup
+
+```js
+require('@tokensbill/node').init('tl_live_your_project_key');
+```
+
+Put it at the very top of your entry file (e.g. `server.js`), before your app starts. That's it — every AI API call your app makes is now tracked automatically.
+
+Get your project key from **TokensBill → your project → Integration**.
+
+## What it does
+
+- Wraps global `fetch` (Node 18+, used by the Anthropic/OpenAI SDKs).
+- Reads token counts and cost from the AI provider's response **without altering your call**.
+- Sends the numbers to TokensBill in a background batch.
+- **Silent-fail by design** — it never throws into, blocks, or slows your application. If TokensBill is unreachable, your app is completely unaffected.
+
+## Is the key safe to commit?
+
+The tracking key is a **label, not a password**. It cannot access your AI provider account, read your prompts, or spend money — it only lets your app report usage numbers to your dashboard. You can regenerate it any time from the dashboard.
+
+## Options
+
+```js
+require('@tokensbill/node').init('tl_live_...', {
+  environment: 'production',   // tag events (production | staging | development)
+  ingestBaseUrl: 'https://tokensbill.aiappsjunction.com', // override the endpoint
+});
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * TokensBill Node SDK. One line at startup:
+ *   require('@tokensbill/node').init('tl_live_abc123');
+ *
+ * Wraps global fetch (Node 18+, used by the Anthropic/OpenAI SDKs). The real call is never
+ * altered — we clone the response and read usage in the background. Silent-fail throughout:
+ * nothing the SDK does ever throws into, blocks, or slows the host application.
+ */
+
+const AI_HOSTS = ['api.anthropic.com', 'api.openai.com', 'generativelanguage.googleapis.com'];
+
+const state = {
+  initialized: false,
+  trackingId: '',
+  ingestBaseUrl: 'https://tokensbill.aiappsjunction.com',
+  environment: 'production',
+  batchSize: 100,
+  maxQueue: 500,
+  flushIntervalMs: 5000,
+  timeoutMs: 800,
+  captureSourceLocation: true,
+  queue: [],
+  timer: null,
+  originalFetch: null,
+};
+
+function init(trackingId, options = {}) {
+  try {
+    if (state.initialized) return;
+    state.trackingId = trackingId;
+    if (options.ingestBaseUrl) state.ingestBaseUrl = options.ingestBaseUrl;
+    if (options.environment) state.environment = options.environment;
+    if (options.batchSize) state.batchSize = options.batchSize;
+    if (options.maxQueue) state.maxQueue = options.maxQueue;
+    if (options.flushIntervalMs) state.flushIntervalMs = options.flushIntervalMs;
+    if (options.timeoutMs) state.timeoutMs = options.timeoutMs;
+    if (options.captureSourceLocation === false) state.captureSourceLocation = false;
+
+    patchFetch();
+    startFlushLoop();
+    state.initialized = true;
+  } catch {
+    /* silent — never break startup */
+  }
+}
+
+function patchFetch() {
+  if (typeof globalThis.fetch !== 'function') return;
+  const original = globalThis.fetch;
+  state.originalFetch = original;
+
+  globalThis.fetch = async function (input, opts) {
+    const started = Date.now();
+    const response = await original(input, opts); // real call — never wrapped
+    try {
+      handleResponse(urlOf(input), response, Date.now() - started);
+    } catch {
+      /* silent */
+    }
+    return response;
+  };
+}
+
+function urlOf(input) {
+  if (typeof input === 'string') return input;
+  if (input && typeof input === 'object') return input.url || String(input);
+  return String(input);
+}
+
+function hostOf(url) {
+  try { return new URL(url).host; } catch { return ''; }
+}
+
+function isAiHost(host) {
+  return AI_HOSTS.some((h) => host === h);
+}
+
+/** Reads usage from an AI response in the background (clone → never consume the caller's body). */
+function handleResponse(url, response, latencyMs) {
+  const host = hostOf(url);
+  if (!isAiHost(host) || !response) return;
+
+  const ct = (response.headers && response.headers.get && response.headers.get('content-type')) || '';
+  if (ct.includes('text/event-stream')) return; // don't touch streaming bodies
+
+  const clone = typeof response.clone === 'function' ? response.clone() : null;
+  if (!clone) return;
+
+  // Fire-and-forget: reading the clone never blocks or affects the caller.
+  clone.text()
+    .then((body) => ingest(host, url, body, latencyMs))
+    .catch(() => {});
+}
+
+function ingest(host, url, body, latencyMs) {
+  try {
+    const usage = parseUsage(host, body);
+    if (!usage || (usage.inputTokens == null && usage.outputTokens == null)) return;
+
+    const loc = state.captureSourceLocation ? findCaller() : {};
+    enqueue({
+      provider: usage.provider,
+      model: usage.model,
+      source_file: loc.file || null,
+      source_method: loc.method || null,
+      http_endpoint: pathOf(url),
+      input_tokens: usage.inputTokens,
+      output_tokens: usage.outputTokens,
+      total_tokens: (usage.inputTokens || 0) + (usage.outputTokens || 0),
+      latency_ms: latencyMs,
+      finish_reason: usage.finishReason || null,
+      environment: state.environment,
+      timestamp: new Date().toISOString(),
+    });
+  } catch {
+    /* silent */
+  }
+}
+
+function pathOf(url) {
+  try { return new URL(url).pathname; } catch { return null; }
+}
+
+function parseUsage(host, body) {
+  let json;
+  try { json = JSON.parse(body); } catch { return null; }
+
+  if (host.includes('anthropic')) {
+    const u = json.usage || {};
+    return { provider: 'anthropic', model: json.model, inputTokens: num(u.input_tokens), outputTokens: num(u.output_tokens), finishReason: json.stop_reason };
+  }
+  if (host.includes('openai')) {
+    const u = json.usage || {};
+    const finish = json.choices && json.choices[0] && json.choices[0].finish_reason;
+    return { provider: 'openai', model: json.model, inputTokens: num(u.prompt_tokens), outputTokens: num(u.completion_tokens), finishReason: finish };
+  }
+  if (host.includes('googleapis')) {
+    const u = json.usageMetadata || {};
+    const finish = json.candidates && json.candidates[0] && json.candidates[0].finishReason;
+    return { provider: 'google', model: json.modelVersion, inputTokens: num(u.promptTokenCount), outputTokens: num(u.candidatesTokenCount), finishReason: finish };
+  }
+  return null;
+}
+
+function num(v) { return typeof v === 'number' ? v : null; }
+
+function findCaller() {
+  try {
+    const stack = (new Error().stack || '').split('\n').slice(1);
+    for (const line of stack) {
+      if (line.includes('tokenlens-node') || line.includes('node:internal') || line.includes('@tokenlens')) continue;
+      let m = line.match(/at\s+(.+?)\s+\((.*?):(\d+):(\d+)\)/);
+      if (m) return { method: m[1], file: baseName(m[2]) };
+      m = line.match(/at\s+(.*?):(\d+):(\d+)/);
+      if (m) return { method: null, file: baseName(m[1]) };
+    }
+  } catch { /* best effort */ }
+  return {};
+}
+
+function baseName(p) { return p.split(/[\\/]/).pop(); }
+
+function enqueue(payload) {
+  state.queue.push(payload);
+  if (state.queue.length > state.maxQueue) state.queue.shift(); // drop oldest
+}
+
+function startFlushLoop() {
+  state.timer = setInterval(() => { flush().catch(() => {}); }, state.flushIntervalMs);
+  if (state.timer.unref) state.timer.unref(); // don't keep the process alive
+}
+
+async function flush() {
+  if (state.queue.length === 0) return;
+  const batch = state.queue.splice(0, state.batchSize);
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), state.timeoutMs);
+  try {
+    const send = state.originalFetch || globalThis.fetch;
+    await send(state.ingestBaseUrl.replace(/\/$/, '') + '/api/ingest/batch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-TokenLens-Key': state.trackingId },
+      body: JSON.stringify(batch),
+      signal: controller.signal,
+    });
+  } catch {
+    /* timeout/failure → batch dropped, never retried */
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+module.exports = {
+  init,
+  // exposed for tests only
+  _test: {
+    parseUsage,
+    enqueue,
+    flush,
+    handleResponse,
+    queue: () => state.queue,
+    state,
+  },
+};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@tokensbill/node",
+  "version": "0.1.0",
+  "description": "One line. Every AI token tracked. Automatically captures Anthropic/OpenAI/Gemini token usage from outgoing fetch calls and streams it to TokensBill. Silent-fail by design.",
+  "main": "index.js",
+  "type": "commonjs",
+  "engines": { "node": ">=18" },
+  "files": ["index.js", "README.md"],
+  "keywords": ["ai", "tokens", "cost", "openai", "anthropic", "gemini", "observability", "tokensbill"],
+  "homepage": "https://tokensbill.com",
+  "repository": { "type": "git", "url": "https://github.com/oxtrys/tokensbill" },
+  "scripts": {
+    "test": "node test/sdk.test.js"
+  },
+  "license": "MIT"
+}