@diogonzafe/tokenwatch 0.4.0 → 0.6.0

package/README.md

@@ -542,18 +542,50 @@ Budget webhook payload:
 { "text": "[tokenwatch] Budget alert: user \"user_123\" reached $1.0031 USD (threshold: $1)" }
 ```
 
+### Cost anomaly detection
+
+Alert when a single call is anomalously expensive compared to the recent average — catches runaway agents, infinite loops, or abusive usage:
+
+```ts
+const tracker = createTracker({
+  anomalyDetection: {
+    multiplierThreshold: 3,                        // alert if call cost > 3× rolling average
+    webhookUrl: 'https://hooks.slack.com/...',
+    windowHours: 24,                               // lookback window (default: 24h)
+    mode: 'once',                                  // 'once' (default) or 'always'
+  },
+})
+```
+
+Checks two axes independently for each tracked call:
+- **Per-model** — compares the call's cost to the average of all prior calls for that model within `windowHours`
+- **Per-user** — same check scoped to a specific user (only fires when `userId` is present)
+
+No alert fires on the first call for a given model or user (no history = no baseline). Alerts are cleared when `reset()` is called.
+
+Anomaly webhook payload example:
+```json
+{ "text": "[tokenwatch] Anomaly: model \"gpt-4o\" call cost $0.5000 is 4.2x above 24h average ($0.0119)" }
+```
+
+`mode: 'always'` fires on every anomalous call instead of latching after the first.
+
 ---
 
 ## CLI
 
 ```bash
-npx tokenwatch sync     # force update cached prices from remote
-npx tokenwatch prices   # list all models and current prices
-npx tokenwatch report   # show usage report from ~/.tokenwatch/usage.db
-npx tokenwatch help     # show help
+npx tokenwatch sync              # force update cached prices from remote
+npx tokenwatch prices            # list all models and current prices
+npx tokenwatch report            # show usage report from ~/.tokenwatch/usage.db
+npx tokenwatch dashboard         # open local web dashboard (default port: 4242)
+npx tokenwatch dashboard --port 8080
+npx tokenwatch help              # show help
 ```
 
-`tokenwatch report` reads the local SQLite database and prints:
+### `tokenwatch report`
+
+Reads the local SQLite database and prints:
 
 ```
 ── tokenwatch report ──────────────────────────────
@@ -574,7 +606,101 @@ npx tokenwatch help     # show help
 ───────────────────────────────────────────────────
 ```
 
-Requires `storage: 'sqlite'` in your app and `better-sqlite3` installed.
+### `tokenwatch dashboard`
+
+Spins up a local web server and opens a dark-themed dashboard with real-time cost data:
+
+- **Overview cards** — total cost, tokens, calls, burn rate per hour
+- **Cost over time** — line chart bucketed by time (5min / 1h / 1day depending on filter)
+- **Model breakdown** — doughnut chart + table with cost share per model
+- **By user / feature** — collapsible tables, hidden when empty
+- **Cost forecast** — projected daily and monthly spend based on recent burn rate
+- **Time filter tabs** — 1h | 24h | 7d | 30d | All; updates chart and tables in real-time via SSE
+
+Data updates automatically every 3 seconds without refreshing the page. Requires `storage: 'sqlite'` in your app and `better-sqlite3` installed. Zero external dependencies — pure Node.js HTTP server with Chart.js loaded from CDN.
+
+---
+
+## Production Usage
+
+### Storage choice
+
+| Setup | Recommended storage |
+|---|---|
+| Single process (monolith, lambda, single pod) | `'sqlite'` — zero config, persists across restarts |
+| Multi-instance (Kubernetes, PaaS with ≥2 pods) | `PostgresStorage` / `MySQLStorage` / `MongoStorage` — shared, unified data |
+| Ephemeral / testing | `'memory'` (default) — resets on restart |
+
+### CI / test environments
+
+Disable network calls and staleness warnings in CI:
+
+```ts
+const tracker = createTracker({
+  syncPrices: false,          // skip remote price fetch — use bundled prices
+  warnIfStaleAfterHours: 0,   // suppress staleness warning
+})
+```
+
+### On-prem / air-gapped deployments
+
+The daily GitHub Actions workflow updates `prices.json` and publishes a new npm package. Teams that cannot reach GitHub at runtime have two options:
+
+1. **Pin and vendor** — copy `prices.json` from the installed package into your repo and commit it. Pass overrides via `customPrices` for any new models.
+2. **Self-host the sync** — fork the `scripts/scrape-prices.mjs` script and run it on your own schedule, pointing to your internal registry.
+
+Either way, set `syncPrices: false` so the library doesn't try to fetch from GitHub at runtime.
+
+### Anomaly detection in production
+
+Enable `anomalyDetection` to catch runaway agents or abuse early:
+
+```ts
+const tracker = createTracker({
+  storage: new PostgresStorage(pool),
+  anomalyDetection: {
+    multiplierThreshold: 3,                       // alert if a call costs 3x above the rolling average
+    webhookUrl: 'https://hooks.slack.com/...',
+    windowHours: 24,                              // baseline window (default: 24h)
+  },
+})
+```
+
+---
+
+## OpenTelemetry Exporter
+
+Push tracked usage as metrics to any OTel-compatible backend (Datadog, Honeycomb, Grafana, New Relic, etc.) without changing your existing instrumentation:
+
+```bash
+npm install @opentelemetry/api
+```
+
+```ts
+import { createTracker } from '@diogonzafe/tokenwatch'
+import { OTelExporter } from '@diogonzafe/tokenwatch/exporters'
+
+const tracker = createTracker({
+  exporter: new OTelExporter(),   // uses the globally-registered MeterProvider
+})
+```
+
+Four metrics are emitted per call, all with `model`, `session.id`, `user.id`, and `feature` attributes (optional fields omitted when absent):
+
+| Metric | Type | Description |
+|---|---|---|
+| `tokenwatch.calls` | Counter | Number of LLM API calls |
+| `tokenwatch.input_tokens` | Counter | Input tokens (includes cached + cache-creation) |
+| `tokenwatch.output_tokens` | Counter | Output tokens |
+| `tokenwatch.cost_usd` | Histogram | Cost per call in USD |
+
+You must configure a `MeterProvider` before creating the exporter (e.g. using the OpenTelemetry SDK). `OTelExporter` has no compile-time dependency on `@opentelemetry/api` — it resolves it at runtime and throws a helpful error if the package is not installed.
+
+Custom meter name:
+
+```ts
+new OTelExporter({ meterName: 'my-service' })
+```
 
 ---
 

package/dist/adapters.d.cts

@@ -1,4 +1,4 @@
-import { I as IStorage, U as UsageEntry } from './index-CJKk1hHw.cjs';
+import { d as IStorage, U as UsageEntry } from './index-D9xq0RNg.cjs';
 
 /**
  * IStorage adapter for PostgreSQL using the `pg` driver.

package/dist/adapters.d.ts

@@ -1,4 +1,4 @@
-import { I as IStorage, U as UsageEntry } from './index-CJKk1hHw.js';
+import { d as IStorage, U as UsageEntry } from './index-D9xq0RNg.js';
 
 /**
  * IStorage adapter for PostgreSQL using the `pg` driver.