@diogonzafe/tokenwatch 0.5.0 → 0.7.0

package/README.md

@@ -542,6 +542,34 @@ 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
@@ -549,12 +577,27 @@ Budget webhook payload:
 ```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 report            # show usage report (SQLite default)
+npx tokenwatch report    --db postgres://user:pass@host:5432/db
 npx tokenwatch dashboard         # open local web dashboard (default port: 4242)
 npx tokenwatch dashboard --port 8080
+npx tokenwatch dashboard --db postgres://user:pass@host:5432/db
+npx tokenwatch dashboard --db mysql://user:pass@host:3306/db
+npx tokenwatch dashboard --db mongodb://user:pass@host:27017/db
 npx tokenwatch help              # show help
 ```
 
+Both `report` and `dashboard` accept a `--db <url>` flag to connect directly to any database — no SQLite required. The URL protocol determines the adapter automatically:
+
+| URL prefix | Adapter | Peer dep required |
+|---|---|---|
+| *(none)* | SQLite (`~/.tokenwatch/usage.db`) | `better-sqlite3` |
+| `postgres://` or `postgresql://` | `PostgresStorage` | `pg` |
+| `mysql://` | `MySQLStorage` | `mysql2` |
+| `mongodb://` or `mongodb+srv://` | `MongoStorage` | `mongodb` |
+
+If the required peer dep is not installed, a clear error message with the install command is shown.
+
 ### `tokenwatch report`
 
 Reads the local SQLite database and prints:
@@ -589,7 +632,99 @@ Spins up a local web server and opens a dark-themed dashboard with real-time cos
 - **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.
+Data updates automatically every 3 seconds without refreshing the page. Zero external dependencies — pure Node.js HTTP server with Chart.js loaded from CDN.
+
+Works with **any storage backend** via `--db <url>`:
+
+```bash
+tokenwatch dashboard                                         # SQLite (default)
+tokenwatch dashboard --db postgres://user:pass@host:5432/db  # PostgreSQL
+tokenwatch dashboard --db mysql://user:pass@host:3306/db     # MySQL
+tokenwatch dashboard --db mongodb://user:pass@host:27017/db  # MongoDB
+```
+
+---
+
+## 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.