@diogonzafe/tokenwatch 0.5.0 → 0.6.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
@@ -593,6 +621,89 @@ Data updates automatically every 3 seconds without refreshing the page. Requires
 
 ---
 
+## 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' })
+```
+
+---
+
 ## Privacy & Security
 
 - Prompt and response **content is never read or stored** — only token counts and model names

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.

package/dist/cli.js

@@ -245,7 +245,7 @@ function maybeSuggestCheaperModel(model, costUSD, inputTokens, outputTokens, lay
 
 // prices.json
 var prices_default = {
-  updated_at: "2026-04-22",
+  updated_at: "2026-04-23",
   source: "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
   models: {
     "gpt-4o": {
@@ -1594,7 +1594,14 @@ var TrackerConfigSchema = z.object({
     perUser: BudgetConfigSchema.optional(),
     perSession: BudgetConfigSchema.optional()
   }).optional(),
-  suggestions: z.boolean().optional().default(false)
+  suggestions: z.boolean().optional().default(false),
+  anomalyDetection: z.object({
+    multiplierThreshold: z.number().positive(),
+    webhookUrl: z.string().url(),
+    windowHours: z.number().positive().optional().default(24),
+    mode: z.enum(["once", "always"]).optional().default("once")
+  }).optional(),
+  exporter: z.custom((v) => v !== null && typeof v === "object" && typeof v.export === "function").optional()
 });
 function createTracker(config = {}) {
   const parsed = TrackerConfigSchema.safeParse(config);
@@ -1611,7 +1618,9 @@ ${issues}`);
     customPrices,
     warnIfStaleAfterHours,
     budgets,
-    suggestions
+    suggestions,
+    anomalyDetection,
+    exporter
   } = parsed.data;
   const storage = typeof storageOption === "object" ? storageOption : createStorage(storageOption);
   let remotePrices;
@@ -1644,6 +1653,7 @@ ${issues}`);
   let alertFired = false;
   const firedUserAlerts = /* @__PURE__ */ new Set();
   const firedSessionAlerts = /* @__PURE__ */ new Set();
+  const firedAnomalyKeys = /* @__PURE__ */ new Set();
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   function resolveModelPrice(model) {
     maybeWarnStaleness();
@@ -1668,7 +1678,12 @@ ${issues}`);
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     storage.record(full);
+    if (exporter) {
+      Promise.resolve(exporter.export(full)).catch(() => {
+      });
+    }
     maybeFireAlerts(full);
+    if (anomalyDetection) maybeDetectAnomaly(full);
     if (suggestions) {
       maybeSuggestCheaperModel(entry.model, costUSD, entry.inputTokens, entry.outputTokens, {
         bundledPrices,
@@ -1838,11 +1853,56 @@ ${issues}`);
       basedOnPeriod: { from: first, to: last }
     };
   }
+  function maybeDetectAnomaly(entry) {
+    if (entry.costUSD <= 0) return;
+    const { multiplierThreshold, webhookUrl: aUrl, windowHours: wh, mode: modeRaw } = anomalyDetection;
+    const wHours = wh ?? 24;
+    const mode = modeRaw ?? "once";
+    const windowStart = Date.now() - wHours * 60 * 60 * 1e3;
+    const entryTs = new Date(entry.timestamp).getTime();
+    function checkEntity(key, label, predicate) {
+      if (mode !== "always" && firedAnomalyKeys.has(key)) return;
+      if (mode !== "always") firedAnomalyKeys.add(key);
+      Promise.resolve(storage.getAll()).then((all) => {
+        const history = all.filter(
+          (e) => predicate(e) && new Date(e.timestamp).getTime() >= windowStart && new Date(e.timestamp).getTime() !== entryTs
+        );
+        if (history.length === 0) {
+          if (mode !== "always") firedAnomalyKeys.delete(key);
+          return;
+        }
+        const avg = history.reduce((s, e) => s + e.costUSD, 0) / history.length;
+        if (avg <= 0 || entry.costUSD <= avg * multiplierThreshold) {
+          if (mode !== "always") firedAnomalyKeys.delete(key);
+          return;
+        }
+        const multiple = (entry.costUSD / avg).toFixed(1);
+        fireWebhook(aUrl, {
+          text: `[tokenwatch] Anomaly: ${label} call cost $${entry.costUSD.toFixed(4)} is ${multiple}x above ${wHours}h average ($${avg.toFixed(4)})`
+        });
+      }).catch(() => {
+        if (mode !== "always") firedAnomalyKeys.delete(key);
+      });
+    }
+    if (entry.userId) {
+      checkEntity(
+        `user:${entry.userId}`,
+        `user "${entry.userId}"`,
+        (e) => e.userId === entry.userId
+      );
+    }
+    checkEntity(
+      `model:${entry.model}`,
+      `model "${entry.model}"`,
+      (e) => e.model === entry.model
+    );
+  }
   async function reset() {
     await Promise.resolve(storage.clearAll());
     alertFired = false;
     firedUserAlerts.clear();
     firedSessionAlerts.clear();
+    firedAnomalyKeys.clear();
   }
   async function resetSession(sessionId) {
     await Promise.resolve(storage.clearSession(sessionId));