tokenwatch-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javoxir Khusanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# TokenWatch
+
+**Know where your LLM money goes.** Zero-config cost & quality monitor for indie AI builders: one-line SDK, local dashboard, per-feature/per-customer attribution, and a budget kill-switch so an agent loop can never surprise you with a 5-figure bill.
+
+- No proxy in your request path — your calls go straight to the provider, telemetry is sent async on the side
+- Single process, SQLite, zero native dependencies — `npx tokenwatch serve` and you're done
+- Flat and simple, built for solo devs and small teams (not another per-seat enterprise platform)
+
+## Quickstart
+
+```bash
+# 1. Start the server + dashboard (http://localhost:4318)
+npx tokenwatch-sdk serve
+
+# 2. Wrap your client (one line)
+```
+
+```ts
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+import { wrapOpenAI, wrapAnthropic, init } from 'tokenwatch';
+
+const openai = wrapOpenAI(new OpenAI(), { feature: 'chat' });
+const anthropic = wrapAnthropic(new Anthropic(), { feature: 'summarize' });
+
+// Optional: block calls when the monthly budget is spent
+init({ enforceBudget: true });
+```
+
+Every call is now tracked: model, tokens, cost (June 2026 pricing table, overridable), latency, errors — attributable by `feature` and `customerId` tags. Streaming calls are tracked too (via `stream.tee()` — your stream is untouched, usage is read from a mirrored branch).
+
+### Python
+
+Zero-dependency Python SDK in [`python/`](python/):
+
+```python
+from tokenwatch import wrap_openai, wrap_anthropic, init
+
+client = wrap_openai(OpenAI(), feature="chat")
+claude = wrap_anthropic(Anthropic(), feature="summarize")
+init(enforce_budget=True)  # optional kill-switch
+```
+
+### Manual tracking
+
+```ts
+import { track } from 'tokenwatch';
+
+track({ model: 'claude-fable-5', inputTokens: 1200, outputTokens: 400, feature: 'batch-job', customerId: 'acme' });
+```
+
+### Budgets & alerts
+
+Set a monthly budget in the dashboard (or `POST /v1/settings`). At 80% and 100% TokenWatch fires your webhook; at 100% `enforceBudget: true` makes wrapped calls throw `BudgetExceededError` instead of burning money.
+
+## Demo
+
+```bash
+npm run dev     # terminal 1: server
+npm run demo    # terminal 2: seed 30 days of synthetic data
+```
+
+## API
+
+| Endpoint | Description |
+|---|---|
+| `POST /v1/events` | Ingest events (bearer auth if `TOKENWATCH_API_KEY` is set) |
+| `GET /v1/stats?days=30` | Aggregates: totals, by model/feature/customer, daily series |
+| `GET /v1/guard` | `{ blocked, spentMonthUsd, budgetUsd }` — kill-switch state |
+| `GET/POST /v1/settings` | Monthly budget, webhook URL |
+
+## Status / roadmap
+
+v0.1 (MVP): TS + Python SDKs (OpenAI + Anthropic wrappers), streaming usage capture (TS), local server + dashboard, budgets, webhook alerts, kill-switch.
+
+Next: Python streaming capture, cost regression alerts (per-feature spike detection), hosted version, quality evals.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { startServer } from './server.js';
+const args = process.argv.slice(2);
+const wantsHelp = args.includes('--help') || args.includes('-h');
+const command = wantsHelp ? 'help' : args[0] && !args[0].startsWith('-') ? args[0] : 'serve';
+function flag(name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+if (command === 'serve') {
+    const port = Number(flag('port') ?? process.env.TOKENWATCH_PORT ?? process.env.PORT ?? 4318);
+    const dbPath = flag('db') ?? process.env.TOKENWATCH_DB ?? join(homedir(), '.tokenwatch', 'tokenwatch.db');
+    mkdirSync(dirname(dbPath), { recursive: true });
+    startServer({ port, dbPath });
+}
+else {
+    console.log(`tokenwatch — LLM cost & quality monitor
+
+Usage:
+  tokenwatch serve [--port 4318] [--db ~/.tokenwatch/tokenwatch.db]
+
+Env:
+  TOKENWATCH_PORT, TOKENWATCH_DB, TOKENWATCH_API_KEY (require bearer auth for ingestion)`);
+}

package/dist/dashboard.d.ts

@@ -0,0 +1 @@
+export declare const dashboardHtml = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>TokenWatch</title>\n<script src=\"https://cdn.jsdelivr.net/npm/chart.js@4\"></script>\n<style>\n  :root {\n    --bg: #0d1117; --card: #161b22; --border: #30363d;\n    --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff;\n    --green: #3fb950; --red: #f85149; --amber: #d29922;\n  }\n  * { box-sizing: border-box; }\n  body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.5 -apple-system, 'Segoe UI', Roboto, sans-serif; }\n  header { display: flex; align-items: center; gap: 16px; padding: 16px 24px; border-bottom: 1px solid var(--border); }\n  header h1 { font-size: 18px; margin: 0; }\n  header h1 span { color: var(--accent); }\n  .spacer { flex: 1; }\n  select, input, button { background: var(--card); color: var(--text); border: 1px solid var(--border); border-radius: 6px; padding: 6px 10px; font: inherit; }\n  button { cursor: pointer; } button:hover { border-color: var(--accent); }\n  main { max-width: 1200px; margin: 0 auto; padding: 24px; }\n  .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }\n  .card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; }\n  .card .label { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .05em; }\n  .card .value { font-size: 26px; font-weight: 600; margin-top: 4px; }\n  .card .sub { color: var(--muted); font-size: 12px; margin-top: 2px; }\n  .budgetbar { height: 8px; background: var(--border); border-radius: 4px; margin-top: 8px; overflow: hidden; }\n  .budgetbar > div { height: 100%; background: var(--green); }\n  .grid2 { display: grid; grid-template-columns: 2fr 1fr; gap: 12px; margin-top: 12px; }\n  .grid3 { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 12px; margin-top: 12px; }\n  h2 { font-size: 13px; color: var(--muted); text-transform: uppercase; letter-spacing: .05em; margin: 0 0 10px; }\n  table { width: 100%; border-collapse: collapse; font-size: 13px; }\n  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); }\n  th { color: var(--muted); font-weight: 500; }\n  td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }\n  .err { color: var(--red); }\n  .ok { color: var(--green); }\n  .chartbox { position: relative; height: 260px; }\n  @media (max-width: 900px) { .grid2 { grid-template-columns: 1fr; } }\n</style>\n</head>\n<body>\n<header>\n  <h1>\u23F1 Token<span>Watch</span></h1>\n  <div class=\"spacer\"></div>\n  <label>Period\n    <select id=\"days\">\n      <option value=\"7\">7 days</option>\n      <option value=\"30\" selected>30 days</option>\n      <option value=\"90\">90 days</option>\n    </select>\n  </label>\n  <label>Budget $<input id=\"budget\" type=\"number\" min=\"0\" step=\"10\" style=\"width:90px\"></label>\n  <button id=\"saveBudget\">Save</button>\n</header>\n<main>\n  <div class=\"cards\">\n    <div class=\"card\"><div class=\"label\">Spend (period)</div><div class=\"value\" id=\"spend\">\u2013</div><div class=\"sub\" id=\"calls\"></div></div>\n    <div class=\"card\"><div class=\"label\">This month</div><div class=\"value\" id=\"month\">\u2013</div><div class=\"sub\" id=\"budgetState\"></div><div class=\"budgetbar\"><div id=\"budgetFill\" style=\"width:0%\"></div></div></div>\n    <div class=\"card\"><div class=\"label\">Tokens</div><div class=\"value\" id=\"tokens\">\u2013</div><div class=\"sub\" id=\"tokensSplit\"></div></div>\n    <div class=\"card\"><div class=\"label\">Avg latency</div><div class=\"value\" id=\"latency\">\u2013</div></div>\n    <div class=\"card\"><div class=\"label\">Error rate</div><div class=\"value\" id=\"errors\">\u2013</div><div class=\"sub\" id=\"errorCount\"></div></div>\n  </div>\n\n  <div class=\"grid2\">\n    <div class=\"card\"><h2>Daily spend</h2><div class=\"chartbox\"><canvas id=\"dailyChart\"></canvas></div></div>\n    <div class=\"card\"><h2>By model</h2><div class=\"chartbox\"><canvas id=\"modelChart\"></canvas></div></div>\n  </div>\n\n  <div class=\"grid3\">\n    <div class=\"card\"><h2>By feature</h2><table id=\"featureTable\"></table></div>\n    <div class=\"card\"><h2>By customer</h2><table id=\"customerTable\"></table></div>\n  </div>\n\n  <div class=\"card\" style=\"margin-top:12px\"><h2>Recent calls</h2><table id=\"recentTable\"></table></div>\n</main>\n<script>\nconst $ = (id) => document.getElementById(id);\nconst usd = (v) => '$' + (v >= 100 ? v.toFixed(0) : v >= 1 ? v.toFixed(2) : v.toFixed(4));\nconst num = (v) => v >= 1e9 ? (v/1e9).toFixed(1)+'B' : v >= 1e6 ? (v/1e6).toFixed(1)+'M' : v >= 1e3 ? (v/1e3).toFixed(1)+'K' : String(v);\nlet dailyChart, modelChart;\n\nfunction fillTable(el, rows, nameHeader) {\n  el.innerHTML = '<tr><th>' + nameHeader + '</th><th class=\"num\">Cost</th><th class=\"num\">Calls</th><th class=\"num\">Tokens</th></tr>' +\n    rows.map(r => '<tr><td>' + r.name + '</td><td class=\"num\">' + usd(r.costUsd || 0) + '</td><td class=\"num\">' + num(r.calls) + '</td><td class=\"num\">' + num(r.tokens || 0) + '</td></tr>').join('');\n}\n\nasync function load() {\n  const days = $('days').value;\n  const s = await (await fetch('/v1/stats?days=' + days)).json();\n  const t = s.totals;\n\n  $('spend').textContent = usd(t.costUsd);\n  $('calls').textContent = num(t.calls) + ' calls';\n  $('tokens').textContent = num(t.inputTokens + t.outputTokens);\n  $('tokensSplit').textContent = num(t.inputTokens) + ' in / ' + num(t.outputTokens) + ' out';\n  $('latency').textContent = t.avgLatencyMs ? Math.round(t.avgLatencyMs) + ' ms' : '\u2013';\n  const errRate = t.calls ? (100 * t.errors / t.calls) : 0;\n  $('errors').textContent = errRate.toFixed(1) + '%';\n  $('errors').className = 'value ' + (errRate > 5 ? 'err' : 'ok');\n  $('errorCount').textContent = num(t.errors) + ' errors';\n\n  $('month').textContent = usd(s.month.spentUsd);\n  if (s.month.budgetUsd) {\n    const pct = Math.min(100, 100 * s.month.spentUsd / s.month.budgetUsd);\n    $('budgetFill').style.width = pct + '%';\n    $('budgetFill').style.background = pct >= 100 ? 'var(--red)' : pct >= 80 ? 'var(--amber)' : 'var(--green)';\n    $('budgetState').textContent = pct.toFixed(0) + '% of ' + usd(s.month.budgetUsd) + (pct >= 100 ? ' \u2014 BLOCKED' : '');\n    if (!$('budget').matches(':focus')) $('budget').value = s.month.budgetUsd;\n  } else {\n    $('budgetState').textContent = 'no budget set';\n    $('budgetFill').style.width = '0%';\n  }\n\n  const labels = s.daily.map(d => d.day.slice(5));\n  dailyChart?.destroy();\n  dailyChart = new Chart($('dailyChart'), {\n    type: 'bar',\n    data: { labels, datasets: [{ data: s.daily.map(d => d.costUsd), backgroundColor: '#58a6ff' }] },\n    options: { plugins: { legend: { display: false } }, maintainAspectRatio: false,\n      scales: { x: { grid: { display: false }, ticks: { color: '#8b949e' } }, y: { grid: { color: '#21262d' }, ticks: { color: '#8b949e', callback: v => '$' + v } } } }\n  });\n\n  modelChart?.destroy();\n  modelChart = new Chart($('modelChart'), {\n    type: 'doughnut',\n    data: { labels: s.byModel.map(m => m.name), datasets: [{ data: s.byModel.map(m => m.costUsd),\n      backgroundColor: ['#58a6ff','#3fb950','#d29922','#f85149','#bc8cff','#39c5cf','#ff7b72','#7ee787'] }] },\n    options: { maintainAspectRatio: false, plugins: { legend: { position: 'bottom', labels: { color: '#8b949e', boxWidth: 12 } } } }\n  });\n\n  fillTable($('featureTable'), s.byFeature, 'Feature');\n  fillTable($('customerTable'), s.byCustomer, 'Customer');\n\n  $('recentTable').innerHTML = '<tr><th>Time</th><th>Model</th><th>Feature</th><th>Customer</th><th class=\"num\">Tokens</th><th class=\"num\">Cost</th><th class=\"num\">ms</th><th>Status</th></tr>' +\n    s.recent.map(r => '<tr><td>' + new Date(r.ts).toLocaleString() + '</td><td>' + r.model + '</td><td>' + (r.feature || '\u2013') + '</td><td>' + (r.customerId || '\u2013') + '</td><td class=\"num\">' + num(r.inputTokens + r.outputTokens) + '</td><td class=\"num\">' + usd(r.costUsd) + '</td><td class=\"num\">' + (r.latencyMs ?? '\u2013') + '</td><td class=\"' + (r.status === 'error' ? 'err' : 'ok') + '\">' + (r.status === 'error' ? (r.errorType || 'error') : 'ok') + '</td></tr>').join('');\n}\n\n$('days').addEventListener('change', load);\n$('saveBudget').addEventListener('click', async () => {\n  await fetch('/v1/settings', { method: 'POST', headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({ monthlyBudgetUsd: Number($('budget').value) || null }) });\n  load();\n});\nload();\nsetInterval(load, 30000);\n</script>\n</body>\n</html>";

package/dist/dashboard.js

@@ -0,0 +1,150 @@
+export const dashboardHtml = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>TokenWatch</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
+<style>
+  :root {
+    --bg: #0d1117; --card: #161b22; --border: #30363d;
+    --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff;
+    --green: #3fb950; --red: #f85149; --amber: #d29922;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.5 -apple-system, 'Segoe UI', Roboto, sans-serif; }
+  header { display: flex; align-items: center; gap: 16px; padding: 16px 24px; border-bottom: 1px solid var(--border); }
+  header h1 { font-size: 18px; margin: 0; }
+  header h1 span { color: var(--accent); }
+  .spacer { flex: 1; }
+  select, input, button { background: var(--card); color: var(--text); border: 1px solid var(--border); border-radius: 6px; padding: 6px 10px; font: inherit; }
+  button { cursor: pointer; } button:hover { border-color: var(--accent); }
+  main { max-width: 1200px; margin: 0 auto; padding: 24px; }
+  .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }
+  .card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; }
+  .card .label { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .05em; }
+  .card .value { font-size: 26px; font-weight: 600; margin-top: 4px; }
+  .card .sub { color: var(--muted); font-size: 12px; margin-top: 2px; }
+  .budgetbar { height: 8px; background: var(--border); border-radius: 4px; margin-top: 8px; overflow: hidden; }
+  .budgetbar > div { height: 100%; background: var(--green); }
+  .grid2 { display: grid; grid-template-columns: 2fr 1fr; gap: 12px; margin-top: 12px; }
+  .grid3 { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 12px; margin-top: 12px; }
+  h2 { font-size: 13px; color: var(--muted); text-transform: uppercase; letter-spacing: .05em; margin: 0 0 10px; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); }
+  th { color: var(--muted); font-weight: 500; }
+  td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+  .err { color: var(--red); }
+  .ok { color: var(--green); }
+  .chartbox { position: relative; height: 260px; }
+  @media (max-width: 900px) { .grid2 { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<header>
+  <h1>⏱ Token<span>Watch</span></h1>
+  <div class="spacer"></div>
+  <label>Period
+    <select id="days">
+      <option value="7">7 days</option>
+      <option value="30" selected>30 days</option>
+      <option value="90">90 days</option>
+    </select>
+  </label>
+  <label>Budget $<input id="budget" type="number" min="0" step="10" style="width:90px"></label>
+  <button id="saveBudget">Save</button>
+</header>
+<main>
+  <div class="cards">
+    <div class="card"><div class="label">Spend (period)</div><div class="value" id="spend">–</div><div class="sub" id="calls"></div></div>
+    <div class="card"><div class="label">This month</div><div class="value" id="month">–</div><div class="sub" id="budgetState"></div><div class="budgetbar"><div id="budgetFill" style="width:0%"></div></div></div>
+    <div class="card"><div class="label">Tokens</div><div class="value" id="tokens">–</div><div class="sub" id="tokensSplit"></div></div>
+    <div class="card"><div class="label">Avg latency</div><div class="value" id="latency">–</div></div>
+    <div class="card"><div class="label">Error rate</div><div class="value" id="errors">–</div><div class="sub" id="errorCount"></div></div>
+  </div>
+
+  <div class="grid2">
+    <div class="card"><h2>Daily spend</h2><div class="chartbox"><canvas id="dailyChart"></canvas></div></div>
+    <div class="card"><h2>By model</h2><div class="chartbox"><canvas id="modelChart"></canvas></div></div>
+  </div>
+
+  <div class="grid3">
+    <div class="card"><h2>By feature</h2><table id="featureTable"></table></div>
+    <div class="card"><h2>By customer</h2><table id="customerTable"></table></div>
+  </div>
+
+  <div class="card" style="margin-top:12px"><h2>Recent calls</h2><table id="recentTable"></table></div>
+</main>
+<script>
+const $ = (id) => document.getElementById(id);
+const usd = (v) => '$' + (v >= 100 ? v.toFixed(0) : v >= 1 ? v.toFixed(2) : v.toFixed(4));
+const num = (v) => v >= 1e9 ? (v/1e9).toFixed(1)+'B' : v >= 1e6 ? (v/1e6).toFixed(1)+'M' : v >= 1e3 ? (v/1e3).toFixed(1)+'K' : String(v);
+let dailyChart, modelChart;
+
+function fillTable(el, rows, nameHeader) {
+  el.innerHTML = '<tr><th>' + nameHeader + '</th><th class="num">Cost</th><th class="num">Calls</th><th class="num">Tokens</th></tr>' +
+    rows.map(r => '<tr><td>' + r.name + '</td><td class="num">' + usd(r.costUsd || 0) + '</td><td class="num">' + num(r.calls) + '</td><td class="num">' + num(r.tokens || 0) + '</td></tr>').join('');
+}
+
+async function load() {
+  const days = $('days').value;
+  const s = await (await fetch('/v1/stats?days=' + days)).json();
+  const t = s.totals;
+
+  $('spend').textContent = usd(t.costUsd);
+  $('calls').textContent = num(t.calls) + ' calls';
+  $('tokens').textContent = num(t.inputTokens + t.outputTokens);
+  $('tokensSplit').textContent = num(t.inputTokens) + ' in / ' + num(t.outputTokens) + ' out';
+  $('latency').textContent = t.avgLatencyMs ? Math.round(t.avgLatencyMs) + ' ms' : '–';
+  const errRate = t.calls ? (100 * t.errors / t.calls) : 0;
+  $('errors').textContent = errRate.toFixed(1) + '%';
+  $('errors').className = 'value ' + (errRate > 5 ? 'err' : 'ok');
+  $('errorCount').textContent = num(t.errors) + ' errors';
+
+  $('month').textContent = usd(s.month.spentUsd);
+  if (s.month.budgetUsd) {
+    const pct = Math.min(100, 100 * s.month.spentUsd / s.month.budgetUsd);
+    $('budgetFill').style.width = pct + '%';
+    $('budgetFill').style.background = pct >= 100 ? 'var(--red)' : pct >= 80 ? 'var(--amber)' : 'var(--green)';
+    $('budgetState').textContent = pct.toFixed(0) + '% of ' + usd(s.month.budgetUsd) + (pct >= 100 ? ' — BLOCKED' : '');
+    if (!$('budget').matches(':focus')) $('budget').value = s.month.budgetUsd;
+  } else {
+    $('budgetState').textContent = 'no budget set';
+    $('budgetFill').style.width = '0%';
+  }
+
+  const labels = s.daily.map(d => d.day.slice(5));
+  dailyChart?.destroy();
+  dailyChart = new Chart($('dailyChart'), {
+    type: 'bar',
+    data: { labels, datasets: [{ data: s.daily.map(d => d.costUsd), backgroundColor: '#58a6ff' }] },
+    options: { plugins: { legend: { display: false } }, maintainAspectRatio: false,
+      scales: { x: { grid: { display: false }, ticks: { color: '#8b949e' } }, y: { grid: { color: '#21262d' }, ticks: { color: '#8b949e', callback: v => '$' + v } } } }
+  });
+
+  modelChart?.destroy();
+  modelChart = new Chart($('modelChart'), {
+    type: 'doughnut',
+    data: { labels: s.byModel.map(m => m.name), datasets: [{ data: s.byModel.map(m => m.costUsd),
+      backgroundColor: ['#58a6ff','#3fb950','#d29922','#f85149','#bc8cff','#39c5cf','#ff7b72','#7ee787'] }] },
+    options: { maintainAspectRatio: false, plugins: { legend: { position: 'bottom', labels: { color: '#8b949e', boxWidth: 12 } } } }
+  });
+
+  fillTable($('featureTable'), s.byFeature, 'Feature');
+  fillTable($('customerTable'), s.byCustomer, 'Customer');
+
+  $('recentTable').innerHTML = '<tr><th>Time</th><th>Model</th><th>Feature</th><th>Customer</th><th class="num">Tokens</th><th class="num">Cost</th><th class="num">ms</th><th>Status</th></tr>' +
+    s.recent.map(r => '<tr><td>' + new Date(r.ts).toLocaleString() + '</td><td>' + r.model + '</td><td>' + (r.feature || '–') + '</td><td>' + (r.customerId || '–') + '</td><td class="num">' + num(r.inputTokens + r.outputTokens) + '</td><td class="num">' + usd(r.costUsd) + '</td><td class="num">' + (r.latencyMs ?? '–') + '</td><td class="' + (r.status === 'error' ? 'err' : 'ok') + '">' + (r.status === 'error' ? (r.errorType || 'error') : 'ok') + '</td></tr>').join('');
+}
+
+$('days').addEventListener('change', load);
+$('saveBudget').addEventListener('click', async () => {
+  await fetch('/v1/settings', { method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ monthlyBudgetUsd: Number($('budget').value) || null }) });
+  load();
+});
+load();
+setInterval(load, 30000);
+</script>
+</body>
+</html>`;

package/dist/pricing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * USD per 1M tokens. Prices as of June 2026 — verify against provider pricing
+ * pages before relying on exact numbers; override via registerPricing().
+ */
+export interface ModelPrice {
+    input: number;
+    output: number;
+}
+/** Add or override pricing for a model (substring match against the model id). */
+export declare function registerPricing(model: string, price: ModelPrice): void;
+export declare function findPrice(model: string): ModelPrice | undefined;
+/** Returns cost in USD, or 0 if the model is unknown (track it anyway). */
+export declare function computeCostUsd(model: string, inputTokens: number, outputTokens: number): number;

package/dist/pricing.js

@@ -0,0 +1,34 @@
+const PRICING = {
+    'claude-fable-5': { input: 10, output: 50 },
+    'claude-opus-4-8': { input: 5, output: 25 },
+    'claude-opus-4-7': { input: 5, output: 25 },
+    'claude-opus-4-6': { input: 5, output: 25 },
+    'claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude-haiku-4-5': { input: 1, output: 5 },
+    'gpt-5.5-pro': { input: 30, output: 180 },
+    'gpt-5.5': { input: 5, output: 30 },
+    'gemini-3.5-flash': { input: 1.5, output: 9 },
+    'gemini-3.1-pro': { input: 2, output: 12 },
+    'grok-4.3': { input: 1.25, output: 2.5 },
+    'deepseek-v4': { input: 0.3, output: 0.87 },
+    'glm-5': { input: 0.6, output: 1.92 },
+    'kimi-k2.6': { input: 0.6, output: 2.5 },
+};
+let keysByLength = Object.keys(PRICING).sort((a, b) => b.length - a.length);
+/** Add or override pricing for a model (substring match against the model id). */
+export function registerPricing(model, price) {
+    PRICING[model.toLowerCase()] = price;
+    keysByLength = Object.keys(PRICING).sort((a, b) => b.length - a.length);
+}
+export function findPrice(model) {
+    const m = model.toLowerCase();
+    const key = keysByLength.find((k) => m.includes(k));
+    return key ? PRICING[key] : undefined;
+}
+/** Returns cost in USD, or 0 if the model is unknown (track it anyway). */
+export function computeCostUsd(model, inputTokens, outputTokens) {
+    const p = findPrice(model);
+    if (!p)
+        return 0;
+    return (inputTokens * p.input + outputTokens * p.output) / 1_000_000;
+}

package/dist/sdk.d.ts

@@ -0,0 +1,43 @@
+import { registerPricing } from './pricing.js';
+export { registerPricing };
+export interface Tags {
+    feature?: string;
+    customerId?: string;
+}
+export interface TrackEvent extends Tags {
+    ts?: number;
+    model: string;
+    provider?: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd?: number;
+    latencyMs?: number;
+    status?: 'ok' | 'error';
+    errorType?: string;
+}
+export interface InitOptions {
+    /** TokenWatch server URL. Default: $TOKENWATCH_URL or http://localhost:4318 */
+    endpoint?: string;
+    /** API key, if the server requires one ($TOKENWATCH_API_KEY). */
+    apiKey?: string;
+    /** Tags applied to every event (overridable per wrapper/track call). */
+    defaults?: Tags;
+    /** When true, wrapped calls throw BudgetExceededError once the monthly budget is spent. */
+    enforceBudget?: boolean;
+}
+export declare class BudgetExceededError extends Error {
+    constructor(spentUsd: number, budgetUsd: number);
+}
+export declare function init(opts: InitOptions): void;
+export declare function track(event: TrackEvent): void;
+export declare function flush(): Promise<void>;
+export interface GuardState {
+    blocked: boolean;
+    spentMonthUsd: number;
+    budgetUsd: number | null;
+}
+export declare function guardBudget(): Promise<GuardState>;
+/** Wrap an `openai` client: chat.completions.create and responses.create are tracked. */
+export declare function wrapOpenAI<T extends object>(client: T, tags?: Tags): T;
+/** Wrap an `@anthropic-ai/sdk` client: messages.create is tracked. */
+export declare function wrapAnthropic<T extends object>(client: T, tags?: Tags): T;

package/dist/sdk.js

@@ -0,0 +1,202 @@
+import { computeCostUsd, registerPricing } from './pricing.js';
+export { registerPricing };
+export class BudgetExceededError extends Error {
+    constructor(spentUsd, budgetUsd) {
+        super(`TokenWatch: monthly budget exceeded ($${spentUsd.toFixed(2)} of $${budgetUsd.toFixed(2)}). Call blocked.`);
+        this.name = 'BudgetExceededError';
+    }
+}
+const config = {
+    endpoint: process.env.TOKENWATCH_URL ?? 'http://localhost:4318',
+    apiKey: process.env.TOKENWATCH_API_KEY,
+    defaults: {},
+    enforceBudget: false,
+};
+export function init(opts) {
+    if (opts.endpoint)
+        config.endpoint = opts.endpoint.replace(/\/$/, '');
+    if (opts.apiKey !== undefined)
+        config.apiKey = opts.apiKey;
+    if (opts.defaults)
+        config.defaults = opts.defaults;
+    if (opts.enforceBudget !== undefined)
+        config.enforceBudget = opts.enforceBudget;
+}
+// --- event queue -----------------------------------------------------------
+let queue = [];
+let timer = null;
+export function track(event) {
+    const ev = {
+        ts: Date.now(),
+        status: 'ok',
+        ...config.defaults,
+        ...event,
+    };
+    ev.costUsd ??= computeCostUsd(ev.model, ev.inputTokens, ev.outputTokens);
+    queue.push(ev);
+    if (queue.length >= 25)
+        void flush();
+    else if (!timer) {
+        timer = setTimeout(() => {
+            timer = null;
+            void flush();
+        }, 2000);
+        timer.unref?.();
+    }
+}
+export async function flush() {
+    if (queue.length === 0)
+        return;
+    const batch = queue;
+    queue = [];
+    try {
+        const headers = { 'content-type': 'application/json' };
+        if (config.apiKey)
+            headers.authorization = `Bearer ${config.apiKey}`;
+        const res = await fetch(`${config.endpoint}/v1/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ events: batch }),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+    }
+    catch (err) {
+        // Re-queue (bounded) so a transient outage doesn't lose data.
+        queue = batch.concat(queue).slice(0, 1000);
+        if (process.env.TOKENWATCH_DEBUG)
+            console.error('[tokenwatch] flush failed:', err);
+    }
+}
+let guardCache = null;
+export async function guardBudget() {
+    const res = await fetch(`${config.endpoint}/v1/guard`);
+    if (!res.ok)
+        throw new Error(`TokenWatch guard check failed: HTTP ${res.status}`);
+    return (await res.json());
+}
+async function checkBudgetCached() {
+    if (guardCache && Date.now() - guardCache.at < 30_000)
+        return guardCache.state;
+    try {
+        const state = await guardBudget();
+        guardCache = { state, at: Date.now() };
+        return state;
+    }
+    catch {
+        return null; // fail open: never break the user's app because the monitor is down
+    }
+}
+function extractUsage(result) {
+    const u = result?.usage ?? {};
+    return {
+        // OpenAI chat completions / Anthropic + OpenAI responses API
+        inputTokens: u.prompt_tokens ?? u.input_tokens ?? 0,
+        outputTokens: u.completion_tokens ?? u.output_tokens ?? 0,
+    };
+}
+/** Pull usage out of stream events across providers (Anthropic message_start/delta, OpenAI chunks/responses). */
+async function consumeStreamUsage(stream, provider, params, tags, t0) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let model = params?.model ?? 'unknown';
+    try {
+        for await (const ev of stream) {
+            const u = ev?.usage ?? ev?.message?.usage ?? ev?.response?.usage;
+            if (u) {
+                // max(): Anthropic message_delta usage is cumulative; OpenAI sends usage once in the final chunk.
+                inputTokens = Math.max(inputTokens, u.input_tokens ?? u.prompt_tokens ?? 0);
+                outputTokens = Math.max(outputTokens, u.output_tokens ?? u.completion_tokens ?? 0);
+            }
+            model = ev?.model ?? ev?.message?.model ?? ev?.response?.model ?? model;
+        }
+        track({ model, provider, inputTokens, outputTokens, latencyMs: Date.now() - t0, ...tags });
+    }
+    catch (err) {
+        track({
+            model, provider, inputTokens, outputTokens,
+            latencyMs: Date.now() - t0,
+            status: 'error',
+            errorType: err?.constructor?.name ?? 'Error',
+            ...tags,
+        });
+    }
+}
+function instrument(fn, self, provider, tags) {
+    return async function tracked(params, ...rest) {
+        if (config.enforceBudget) {
+            const state = await checkBudgetCached();
+            if (state?.blocked)
+                throw new BudgetExceededError(state.spentMonthUsd, state.budgetUsd ?? 0);
+        }
+        // Streaming: tee the stream — hand one branch back untouched, read usage from the other.
+        if (params && typeof params === 'object' && params.stream) {
+            const t0 = Date.now();
+            const stream = await fn.call(self, params, ...rest);
+            if (typeof stream?.tee === 'function') {
+                const [mine, theirs] = stream.tee();
+                void consumeStreamUsage(mine, provider, params, tags, t0);
+                return theirs;
+            }
+            return stream; // unknown stream shape — pass through untracked
+        }
+        const t0 = Date.now();
+        try {
+            const result = await fn.call(self, params, ...rest);
+            const usage = extractUsage(result);
+            track({
+                model: result?.model ?? params?.model ?? 'unknown',
+                provider,
+                ...usage,
+                latencyMs: Date.now() - t0,
+                ...tags,
+            });
+            return result;
+        }
+        catch (err) {
+            track({
+                model: params?.model ?? 'unknown',
+                provider,
+                inputTokens: 0,
+                outputTokens: 0,
+                latencyMs: Date.now() - t0,
+                status: 'error',
+                errorType: err?.constructor?.name ?? 'Error',
+                ...tags,
+            });
+            throw err;
+        }
+    };
+}
+function wrapPaths(obj, paths, provider, tags) {
+    const heads = new Map();
+    for (const [head, ...rest] of paths) {
+        if (!heads.has(head))
+            heads.set(head, []);
+        heads.get(head).push(rest);
+    }
+    return new Proxy(obj, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            const key = String(prop);
+            const rests = heads.get(key);
+            if (rests) {
+                if (rests.some((r) => r.length === 0) && typeof value === 'function') {
+                    return instrument(value, target, provider, tags);
+                }
+                if (value && typeof value === 'object') {
+                    return wrapPaths(value, rests, provider, tags);
+                }
+            }
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+/** Wrap an `openai` client: chat.completions.create and responses.create are tracked. */
+export function wrapOpenAI(client, tags = {}) {
+    return wrapPaths(client, [['chat', 'completions', 'create'], ['responses', 'create']], 'openai', tags);
+}
+/** Wrap an `@anthropic-ai/sdk` client: messages.create is tracked. */
+export function wrapAnthropic(client, tags = {}) {
+    return wrapPaths(client, [['messages', 'create']], 'anthropic', tags);
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { Hono } from 'hono';
+import { DatabaseSync } from 'node:sqlite';
+export declare function createApp(dbPath: string): {
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    db: DatabaseSync;
+};
+export declare function startServer(opts: {
+    port: number;
+    dbPath: string;
+}): import("@hono/node-server").ServerType;

package/dist/server.js

@@ -0,0 +1,172 @@
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { DatabaseSync } from 'node:sqlite';
+import { computeCostUsd } from './pricing.js';
+import { dashboardHtml } from './dashboard.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  provider TEXT,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  latency_ms INTEGER,
+  feature TEXT,
+  customer_id TEXT,
+  status TEXT NOT NULL DEFAULT 'ok',
+  error_type TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
+CREATE TABLE IF NOT EXISTS settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+export function createApp(dbPath) {
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec(SCHEMA);
+    const insertStmt = db.prepare(`INSERT INTO events (ts, model, provider, input_tokens, output_tokens, cost_usd, latency_ms, feature, customer_id, status, error_type)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const getSetting = (key) => {
+        const row = db.prepare('SELECT value FROM settings WHERE key = ?').get(key);
+        return row?.value ?? null;
+    };
+    const setSetting = (key, value) => db.prepare('INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, value);
+    const startOfMonth = () => {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+    };
+    const monthSpend = () => {
+        const row = db.prepare('SELECT COALESCE(SUM(cost_usd), 0) AS total FROM events WHERE ts >= ?').get(startOfMonth());
+        return row.total;
+    };
+    const budgetUsd = () => {
+        const v = getSetting('monthlyBudgetUsd');
+        return v ? Number(v) : null;
+    };
+    function maybeFireBudgetAlerts() {
+        const budget = budgetUsd();
+        const webhook = getSetting('webhookUrl');
+        if (!budget || !webhook)
+            return;
+        const spent = monthSpend();
+        const monthKey = new Date().toISOString().slice(0, 7);
+        for (const threshold of [0.8, 1.0]) {
+            if (spent < budget * threshold)
+                continue;
+            const alertKey = `alerted_${threshold}_${monthKey}`;
+            if (getSetting(alertKey))
+                continue;
+            setSetting(alertKey, String(Date.now()));
+            fetch(webhook, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    source: 'tokenwatch',
+                    alert: threshold >= 1.0 ? 'budget_exceeded' : 'budget_80_percent',
+                    spentUsd: Number(spent.toFixed(4)),
+                    budgetUsd: budget,
+                    month: monthKey,
+                }),
+            }).catch(() => { });
+        }
+    }
+    const app = new Hono();
+    // Optional bearer auth for ingestion when TOKENWATCH_API_KEY is set.
+    app.use('/v1/events', async (c, next) => {
+        const required = process.env.TOKENWATCH_API_KEY;
+        if (required && c.req.header('authorization') !== `Bearer ${required}`) {
+            return c.json({ error: 'unauthorized' }, 401);
+        }
+        await next();
+    });
+    app.post('/v1/events', async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body?.events || !Array.isArray(body.events)) {
+            return c.json({ error: 'expected { events: [...] }' }, 400);
+        }
+        db.exec('BEGIN');
+        try {
+            for (const e of body.events) {
+                if (!e || typeof e.model !== 'string')
+                    continue;
+                const inputTokens = Number(e.inputTokens) || 0;
+                const outputTokens = Number(e.outputTokens) || 0;
+                insertStmt.run(Number(e.ts) || Date.now(), e.model, e.provider ?? null, inputTokens, outputTokens, typeof e.costUsd === 'number' ? e.costUsd : computeCostUsd(e.model, inputTokens, outputTokens), e.latencyMs != null ? Number(e.latencyMs) : null, e.feature ?? null, e.customerId ?? null, e.status === 'error' ? 'error' : 'ok', e.errorType ?? null);
+            }
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            throw err;
+        }
+        maybeFireBudgetAlerts();
+        return c.json({ ok: true, ingested: body.events.length });
+    });
+    app.get('/v1/stats', (c) => {
+        const days = Math.max(1, Math.min(365, Number(c.req.query('days')) || 30));
+        const since = Date.now() - days * 86_400_000;
+        const totals = db
+            .prepare(`SELECT COALESCE(SUM(cost_usd),0) AS costUsd, COUNT(*) AS calls,
+                COALESCE(SUM(input_tokens),0) AS inputTokens, COALESCE(SUM(output_tokens),0) AS outputTokens,
+                AVG(latency_ms) AS avgLatencyMs, COALESCE(SUM(status = 'error'),0) AS errors
+         FROM events WHERE ts >= ?`)
+            .get(since);
+        const groupBy = (col) => db
+            .prepare(`SELECT COALESCE(${col}, '(untagged)') AS name, SUM(cost_usd) AS costUsd, COUNT(*) AS calls,
+                  SUM(input_tokens + output_tokens) AS tokens
+           FROM events WHERE ts >= ? GROUP BY name ORDER BY costUsd DESC LIMIT 25`)
+            .all(since);
+        const daily = db
+            .prepare(`SELECT date(ts / 1000, 'unixepoch') AS day, SUM(cost_usd) AS costUsd, COUNT(*) AS calls
+         FROM events WHERE ts >= ? GROUP BY day ORDER BY day`)
+            .all(since);
+        const recent = db
+            .prepare(`SELECT ts, model, provider, input_tokens AS inputTokens, output_tokens AS outputTokens,
+                cost_usd AS costUsd, latency_ms AS latencyMs, feature, customer_id AS customerId, status, error_type AS errorType
+         FROM events ORDER BY ts DESC LIMIT 50`)
+            .all();
+        return c.json({
+            periodDays: days,
+            totals,
+            byModel: groupBy('model'),
+            byFeature: groupBy('feature'),
+            byCustomer: groupBy('customer_id'),
+            daily,
+            recent,
+            month: { spentUsd: monthSpend(), budgetUsd: budgetUsd() },
+        });
+    });
+    app.get('/v1/guard', (c) => {
+        const budget = budgetUsd();
+        const spent = monthSpend();
+        return c.json({
+            blocked: budget != null && budget > 0 && spent >= budget,
+            spentMonthUsd: spent,
+            budgetUsd: budget,
+        });
+    });
+    app.get('/v1/settings', (c) => c.json({ monthlyBudgetUsd: budgetUsd(), webhookUrl: getSetting('webhookUrl') }));
+    app.post('/v1/settings', async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body)
+            return c.json({ error: 'invalid json' }, 400);
+        if ('monthlyBudgetUsd' in body)
+            setSetting('monthlyBudgetUsd', body.monthlyBudgetUsd ? String(body.monthlyBudgetUsd) : '');
+        if ('webhookUrl' in body)
+            setSetting('webhookUrl', body.webhookUrl ?? '');
+        return c.json({ ok: true });
+    });
+    app.get('/healthz', (c) => c.json({ ok: true }));
+    app.get('/', (c) => c.html(dashboardHtml));
+    return { app, db };
+}
+export function startServer(opts) {
+    const { app } = createApp(opts.dbPath);
+    const server = serve({ fetch: app.fetch, port: opts.port });
+    console.log(`TokenWatch running → http://localhost:${opts.port}  (db: ${opts.dbPath})`);
+    return server;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "tokenwatch-sdk",
+  "version": "0.1.0",
+  "description": "Zero-config LLM cost & quality monitor for indie AI builders. One-line SDK, local dashboard, budget kill-switch.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "llm",
+    "observability",
+    "cost-tracking",
+    "openai",
+    "anthropic",
+    "claude",
+    "monitoring",
+    "helicone-alternative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jkhusanovpn/tokenwatch.git"
+  },
+  "bin": {
+    "tokenwatch": "dist/cli.js"
+  },
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
+  "exports": {
+    ".": "./dist/sdk.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli.ts serve",
+    "build": "tsc -p tsconfig.json",
+    "demo": "tsx scripts/demo.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "hono": "^4.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22.5"
+  }
+}