@diogonzafe/tokenwatch 0.4.0 → 0.6.0

package/dist/exporters.cjs

@@ -0,0 +1,76 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/exporters/index.ts
+var exporters_exports = {};
+__export(exporters_exports, {
+  OTelExporter: () => OTelExporter
+});
+module.exports = __toCommonJS(exporters_exports);
+
+// src/exporters/otel.ts
+var OTelExporter = class {
+  calls;
+  inputTokens;
+  outputTokens;
+  costUsd;
+  constructor(options = {}, _metricsApi) {
+    let metricsApi;
+    if (_metricsApi) {
+      metricsApi = _metricsApi;
+    } else {
+      try {
+        metricsApi = require("@opentelemetry/api").metrics;
+      } catch {
+        throw new Error(
+          "[tokenwatch] OTelExporter requires @opentelemetry/api. Run: npm install @opentelemetry/api"
+        );
+      }
+    }
+    const meter = metricsApi.getMeter(options.meterName ?? "tokenwatch");
+    this.calls = meter.createCounter("tokenwatch.calls", {
+      description: "Number of LLM API calls tracked"
+    });
+    this.inputTokens = meter.createCounter("tokenwatch.input_tokens", {
+      description: "Input tokens consumed (includes cached and cache-creation tokens)"
+    });
+    this.outputTokens = meter.createCounter("tokenwatch.output_tokens", {
+      description: "Output tokens generated"
+    });
+    this.costUsd = meter.createHistogram("tokenwatch.cost_usd", {
+      description: "Cost per LLM API call in USD",
+      unit: "USD"
+    });
+  }
+  export(entry) {
+    const attrs = { model: entry.model };
+    if (entry.sessionId !== void 0) attrs["session.id"] = entry.sessionId;
+    if (entry.userId !== void 0) attrs["user.id"] = entry.userId;
+    if (entry.feature !== void 0) attrs["feature"] = entry.feature;
+    this.calls.add(1, attrs);
+    this.inputTokens.add(entry.inputTokens + (entry.cachedTokens ?? 0) + (entry.cacheCreationTokens ?? 0), attrs);
+    this.outputTokens.add(entry.outputTokens, attrs);
+    this.costUsd.record(entry.costUSD, attrs);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OTelExporter
+});
+//# sourceMappingURL=exporters.cjs.map

package/dist/exporters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/exporters/index.ts","../src/exporters/otel.ts"],"sourcesContent":["export { OTelExporter } from './otel.js'\nexport type { OTelExporterOptions } from './otel.js'\n","import type { UsageEntry, IExporter } from '../types/index.js'\n\n// ─── Local type stubs ─────────────────────────────────────────────────────────\n// Mirror the minimal shape of @opentelemetry/api so this file compiles without\n// a hard compile-time dependency on the package.\n\ninterface OTelAttributes {\n  [key: string]: string | number | boolean | undefined\n}\n\ninterface OTelCounter {\n  add(value: number, attributes?: OTelAttributes): void\n}\n\ninterface OTelHistogram {\n  record(value: number, attributes?: OTelAttributes): void\n}\n\ninterface OTelMeter {\n  createCounter(name: string, options?: { description?: string; unit?: string }): OTelCounter\n  createHistogram(name: string, options?: { description?: string; unit?: string }): OTelHistogram\n}\n\ninterface OTelMetricsAPI {\n  getMeter(name: string, version?: string): OTelMeter\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\nexport interface OTelExporterOptions {\n  /**\n   * Name passed to `metrics.getMeter()`.\n   * @default 'tokenwatch'\n   */\n  meterName?: string\n}\n\n/**\n * OpenTelemetry exporter for tokenwatch.\n *\n * Requires `@opentelemetry/api` to be installed in your project and a\n * `MeterProvider` to be registered globally (e.g. via the OTel SDK).\n *\n * Emits four instruments per tracked call:\n * - `tokenwatch.calls`         — Counter\n * - `tokenwatch.input_tokens`  — Counter\n * - `tokenwatch.output_tokens` — Counter\n * - `tokenwatch.cost_usd`      — Histogram\n *\n * Attributes: `model`, `session.id` (optional), `user.id` (optional), `feature` (optional)\n *\n * @example\n * import { OTelExporter } from '@diogonzafe/tokenwatch/exporters'\n *\n * const tracker = createTracker({ exporter: new OTelExporter() })\n */\nexport class OTelExporter implements IExporter {\n  private readonly calls: OTelCounter\n  private readonly inputTokens: OTelCounter\n  private readonly outputTokens: OTelCounter\n  private readonly costUsd: OTelHistogram\n\n  constructor(options: OTelExporterOptions = {}, _metricsApi?: OTelMetricsAPI) {\n    let metricsApi: OTelMetricsAPI\n    if (_metricsApi) {\n      metricsApi = _metricsApi\n    } else {\n      try {\n        // eslint-disable-next-line @typescript-eslint/no-require-imports\n        metricsApi = (require('@opentelemetry/api') as { metrics: OTelMetricsAPI }).metrics\n      } catch {\n        throw new Error(\n          '[tokenwatch] OTelExporter requires @opentelemetry/api. Run: npm install @opentelemetry/api',\n        )\n      }\n    }\n    const meter = metricsApi.getMeter(options.meterName ?? 'tokenwatch')\n    this.calls = meter.createCounter('tokenwatch.calls', {\n      description: 'Number of LLM API calls tracked',\n    })\n    this.inputTokens = meter.createCounter('tokenwatch.input_tokens', {\n      description: 'Input tokens consumed (includes cached and cache-creation tokens)',\n    })\n    this.outputTokens = meter.createCounter('tokenwatch.output_tokens', {\n      description: 'Output tokens generated',\n    })\n    this.costUsd = meter.createHistogram('tokenwatch.cost_usd', {\n      description: 'Cost per LLM API call in USD',\n      unit: 'USD',\n    })\n  }\n\n  export(entry: UsageEntry): void {\n    const attrs: OTelAttributes = { model: entry.model }\n    if (entry.sessionId !== undefined) attrs['session.id'] = entry.sessionId\n    if (entry.userId !== undefined) attrs['user.id'] = entry.userId\n    if (entry.feature !== undefined) attrs['feature'] = entry.feature\n\n    this.calls.add(1, attrs)\n    this.inputTokens.add(entry.inputTokens + (entry.cachedTokens ?? 0) + (entry.cacheCreationTokens ?? 0), attrs)\n    this.outputTokens.add(entry.outputTokens, attrs)\n    this.costUsd.record(entry.costUSD, attrs)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwDO,IAAM,eAAN,MAAwC;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,UAA+B,CAAC,GAAG,aAA8B;AAC3E,QAAI;AACJ,QAAI,aAAa;AACf,mBAAa;AAAA,IACf,OAAO;AACL,UAAI;AAEF,qBAAc,QAAQ,oBAAoB,EAAkC;AAAA,MAC9E,QAAQ;AACN,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,UAAM,QAAQ,WAAW,SAAS,QAAQ,aAAa,YAAY;AACnE,SAAK,QAAQ,MAAM,cAAc,oBAAoB;AAAA,MACnD,aAAa;AAAA,IACf,CAAC;AACD,SAAK,cAAc,MAAM,cAAc,2BAA2B;AAAA,MAChE,aAAa;AAAA,IACf,CAAC;AACD,SAAK,eAAe,MAAM,cAAc,4BAA4B;AAAA,MAClE,aAAa;AAAA,IACf,CAAC;AACD,SAAK,UAAU,MAAM,gBAAgB,uBAAuB;AAAA,MAC1D,aAAa;AAAA,MACb,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,OAAO,OAAyB;AAC9B,UAAM,QAAwB,EAAE,OAAO,MAAM,MAAM;AACnD,QAAI,MAAM,cAAc,OAAW,OAAM,YAAY,IAAI,MAAM;AAC/D,QAAI,MAAM,WAAW,OAAW,OAAM,SAAS,IAAI,MAAM;AACzD,QAAI,MAAM,YAAY,OAAW,OAAM,SAAS,IAAI,MAAM;AAE1D,SAAK,MAAM,IAAI,GAAG,KAAK;AACvB,SAAK,YAAY,IAAI,MAAM,eAAe,MAAM,gBAAgB,MAAM,MAAM,uBAAuB,IAAI,KAAK;AAC5G,SAAK,aAAa,IAAI,MAAM,cAAc,KAAK;AAC/C,SAAK,QAAQ,OAAO,MAAM,SAAS,KAAK;AAAA,EAC1C;AACF;","names":[]}

package/dist/exporters.d.cts

@@ -0,0 +1,60 @@
+import { I as IExporter, U as UsageEntry } from './index-D9xq0RNg.cjs';
+
+interface OTelAttributes {
+    [key: string]: string | number | boolean | undefined;
+}
+interface OTelCounter {
+    add(value: number, attributes?: OTelAttributes): void;
+}
+interface OTelHistogram {
+    record(value: number, attributes?: OTelAttributes): void;
+}
+interface OTelMeter {
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OTelCounter;
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OTelHistogram;
+}
+interface OTelMetricsAPI {
+    getMeter(name: string, version?: string): OTelMeter;
+}
+interface OTelExporterOptions {
+    /**
+     * Name passed to `metrics.getMeter()`.
+     * @default 'tokenwatch'
+     */
+    meterName?: string;
+}
+/**
+ * OpenTelemetry exporter for tokenwatch.
+ *
+ * Requires `@opentelemetry/api` to be installed in your project and a
+ * `MeterProvider` to be registered globally (e.g. via the OTel SDK).
+ *
+ * Emits four instruments per tracked call:
+ * - `tokenwatch.calls`         — Counter
+ * - `tokenwatch.input_tokens`  — Counter
+ * - `tokenwatch.output_tokens` — Counter
+ * - `tokenwatch.cost_usd`      — Histogram
+ *
+ * Attributes: `model`, `session.id` (optional), `user.id` (optional), `feature` (optional)
+ *
+ * @example
+ * import { OTelExporter } from '@diogonzafe/tokenwatch/exporters'
+ *
+ * const tracker = createTracker({ exporter: new OTelExporter() })
+ */
+declare class OTelExporter implements IExporter {
+    private readonly calls;
+    private readonly inputTokens;
+    private readonly outputTokens;
+    private readonly costUsd;
+    constructor(options?: OTelExporterOptions, _metricsApi?: OTelMetricsAPI);
+    export(entry: UsageEntry): void;
+}
+
+export { OTelExporter, type OTelExporterOptions };

package/dist/exporters.d.ts

@@ -0,0 +1,60 @@
+import { I as IExporter, U as UsageEntry } from './index-D9xq0RNg.js';
+
+interface OTelAttributes {
+    [key: string]: string | number | boolean | undefined;
+}
+interface OTelCounter {
+    add(value: number, attributes?: OTelAttributes): void;
+}
+interface OTelHistogram {
+    record(value: number, attributes?: OTelAttributes): void;
+}
+interface OTelMeter {
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OTelCounter;
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OTelHistogram;
+}
+interface OTelMetricsAPI {
+    getMeter(name: string, version?: string): OTelMeter;
+}
+interface OTelExporterOptions {
+    /**
+     * Name passed to `metrics.getMeter()`.
+     * @default 'tokenwatch'
+     */
+    meterName?: string;
+}
+/**
+ * OpenTelemetry exporter for tokenwatch.
+ *
+ * Requires `@opentelemetry/api` to be installed in your project and a
+ * `MeterProvider` to be registered globally (e.g. via the OTel SDK).
+ *
+ * Emits four instruments per tracked call:
+ * - `tokenwatch.calls`         — Counter
+ * - `tokenwatch.input_tokens`  — Counter
+ * - `tokenwatch.output_tokens` — Counter
+ * - `tokenwatch.cost_usd`      — Histogram
+ *
+ * Attributes: `model`, `session.id` (optional), `user.id` (optional), `feature` (optional)
+ *
+ * @example
+ * import { OTelExporter } from '@diogonzafe/tokenwatch/exporters'
+ *
+ * const tracker = createTracker({ exporter: new OTelExporter() })
+ */
+declare class OTelExporter implements IExporter {
+    private readonly calls;
+    private readonly inputTokens;
+    private readonly outputTokens;
+    private readonly costUsd;
+    constructor(options?: OTelExporterOptions, _metricsApi?: OTelMetricsAPI);
+    export(entry: UsageEntry): void;
+}
+
+export { OTelExporter, type OTelExporterOptions };

package/dist/exporters.js

@@ -0,0 +1,56 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/exporters/otel.ts
+var OTelExporter = class {
+  calls;
+  inputTokens;
+  outputTokens;
+  costUsd;
+  constructor(options = {}, _metricsApi) {
+    let metricsApi;
+    if (_metricsApi) {
+      metricsApi = _metricsApi;
+    } else {
+      try {
+        metricsApi = __require("@opentelemetry/api").metrics;
+      } catch {
+        throw new Error(
+          "[tokenwatch] OTelExporter requires @opentelemetry/api. Run: npm install @opentelemetry/api"
+        );
+      }
+    }
+    const meter = metricsApi.getMeter(options.meterName ?? "tokenwatch");
+    this.calls = meter.createCounter("tokenwatch.calls", {
+      description: "Number of LLM API calls tracked"
+    });
+    this.inputTokens = meter.createCounter("tokenwatch.input_tokens", {
+      description: "Input tokens consumed (includes cached and cache-creation tokens)"
+    });
+    this.outputTokens = meter.createCounter("tokenwatch.output_tokens", {
+      description: "Output tokens generated"
+    });
+    this.costUsd = meter.createHistogram("tokenwatch.cost_usd", {
+      description: "Cost per LLM API call in USD",
+      unit: "USD"
+    });
+  }
+  export(entry) {
+    const attrs = { model: entry.model };
+    if (entry.sessionId !== void 0) attrs["session.id"] = entry.sessionId;
+    if (entry.userId !== void 0) attrs["user.id"] = entry.userId;
+    if (entry.feature !== void 0) attrs["feature"] = entry.feature;
+    this.calls.add(1, attrs);
+    this.inputTokens.add(entry.inputTokens + (entry.cachedTokens ?? 0) + (entry.cacheCreationTokens ?? 0), attrs);
+    this.outputTokens.add(entry.outputTokens, attrs);
+    this.costUsd.record(entry.costUSD, attrs);
+  }
+};
+export {
+  OTelExporter
+};
+//# sourceMappingURL=exporters.js.map

package/dist/exporters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/exporters/otel.ts"],"sourcesContent":["import type { UsageEntry, IExporter } from '../types/index.js'\n\n// ─── Local type stubs ─────────────────────────────────────────────────────────\n// Mirror the minimal shape of @opentelemetry/api so this file compiles without\n// a hard compile-time dependency on the package.\n\ninterface OTelAttributes {\n  [key: string]: string | number | boolean | undefined\n}\n\ninterface OTelCounter {\n  add(value: number, attributes?: OTelAttributes): void\n}\n\ninterface OTelHistogram {\n  record(value: number, attributes?: OTelAttributes): void\n}\n\ninterface OTelMeter {\n  createCounter(name: string, options?: { description?: string; unit?: string }): OTelCounter\n  createHistogram(name: string, options?: { description?: string; unit?: string }): OTelHistogram\n}\n\ninterface OTelMetricsAPI {\n  getMeter(name: string, version?: string): OTelMeter\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\nexport interface OTelExporterOptions {\n  /**\n   * Name passed to `metrics.getMeter()`.\n   * @default 'tokenwatch'\n   */\n  meterName?: string\n}\n\n/**\n * OpenTelemetry exporter for tokenwatch.\n *\n * Requires `@opentelemetry/api` to be installed in your project and a\n * `MeterProvider` to be registered globally (e.g. via the OTel SDK).\n *\n * Emits four instruments per tracked call:\n * - `tokenwatch.calls`         — Counter\n * - `tokenwatch.input_tokens`  — Counter\n * - `tokenwatch.output_tokens` — Counter\n * - `tokenwatch.cost_usd`      — Histogram\n *\n * Attributes: `model`, `session.id` (optional), `user.id` (optional), `feature` (optional)\n *\n * @example\n * import { OTelExporter } from '@diogonzafe/tokenwatch/exporters'\n *\n * const tracker = createTracker({ exporter: new OTelExporter() })\n */\nexport class OTelExporter implements IExporter {\n  private readonly calls: OTelCounter\n  private readonly inputTokens: OTelCounter\n  private readonly outputTokens: OTelCounter\n  private readonly costUsd: OTelHistogram\n\n  constructor(options: OTelExporterOptions = {}, _metricsApi?: OTelMetricsAPI) {\n    let metricsApi: OTelMetricsAPI\n    if (_metricsApi) {\n      metricsApi = _metricsApi\n    } else {\n      try {\n        // eslint-disable-next-line @typescript-eslint/no-require-imports\n        metricsApi = (require('@opentelemetry/api') as { metrics: OTelMetricsAPI }).metrics\n      } catch {\n        throw new Error(\n          '[tokenwatch] OTelExporter requires @opentelemetry/api. Run: npm install @opentelemetry/api',\n        )\n      }\n    }\n    const meter = metricsApi.getMeter(options.meterName ?? 'tokenwatch')\n    this.calls = meter.createCounter('tokenwatch.calls', {\n      description: 'Number of LLM API calls tracked',\n    })\n    this.inputTokens = meter.createCounter('tokenwatch.input_tokens', {\n      description: 'Input tokens consumed (includes cached and cache-creation tokens)',\n    })\n    this.outputTokens = meter.createCounter('tokenwatch.output_tokens', {\n      description: 'Output tokens generated',\n    })\n    this.costUsd = meter.createHistogram('tokenwatch.cost_usd', {\n      description: 'Cost per LLM API call in USD',\n      unit: 'USD',\n    })\n  }\n\n  export(entry: UsageEntry): void {\n    const attrs: OTelAttributes = { model: entry.model }\n    if (entry.sessionId !== undefined) attrs['session.id'] = entry.sessionId\n    if (entry.userId !== undefined) attrs['user.id'] = entry.userId\n    if (entry.feature !== undefined) attrs['feature'] = entry.feature\n\n    this.calls.add(1, attrs)\n    this.inputTokens.add(entry.inputTokens + (entry.cachedTokens ?? 0) + (entry.cacheCreationTokens ?? 0), attrs)\n    this.outputTokens.add(entry.outputTokens, attrs)\n    this.costUsd.record(entry.costUSD, attrs)\n  }\n}\n"],"mappings":";;;;;;;;AAwDO,IAAM,eAAN,MAAwC;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,UAA+B,CAAC,GAAG,aAA8B;AAC3E,QAAI;AACJ,QAAI,aAAa;AACf,mBAAa;AAAA,IACf,OAAO;AACL,UAAI;AAEF,qBAAc,UAAQ,oBAAoB,EAAkC;AAAA,MAC9E,QAAQ;AACN,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,UAAM,QAAQ,WAAW,SAAS,QAAQ,aAAa,YAAY;AACnE,SAAK,QAAQ,MAAM,cAAc,oBAAoB;AAAA,MACnD,aAAa;AAAA,IACf,CAAC;AACD,SAAK,cAAc,MAAM,cAAc,2BAA2B;AAAA,MAChE,aAAa;AAAA,IACf,CAAC;AACD,SAAK,eAAe,MAAM,cAAc,4BAA4B;AAAA,MAClE,aAAa;AAAA,IACf,CAAC;AACD,SAAK,UAAU,MAAM,gBAAgB,uBAAuB;AAAA,MAC1D,aAAa;AAAA,MACb,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,OAAO,OAAyB;AAC9B,UAAM,QAAwB,EAAE,OAAO,MAAM,MAAM;AACnD,QAAI,MAAM,cAAc,OAAW,OAAM,YAAY,IAAI,MAAM;AAC/D,QAAI,MAAM,WAAW,OAAW,OAAM,SAAS,IAAI,MAAM;AACzD,QAAI,MAAM,YAAY,OAAW,OAAM,SAAS,IAAI,MAAM;AAE1D,SAAK,MAAM,IAAI,GAAG,KAAK;AACvB,SAAK,YAAY,IAAI,MAAM,eAAe,MAAM,gBAAgB,MAAM,MAAM,uBAAuB,IAAI,KAAK;AAC5G,SAAK,aAAa,IAAI,MAAM,cAAc,KAAK;AAC/C,SAAK,QAAQ,OAAO,MAAM,SAAS,KAAK;AAAA,EAC1C;AACF;","names":[]}

package/dist/{index-CJKk1hHw.d.cts → index-D9xq0RNg.d.cts}

@@ -24,6 +24,20 @@ interface BudgetConfig {
     /** 'once' (default) — fire once per entity lifetime; 'always' — fire on every call that exceeds */
     mode?: 'once' | 'always';
 }
+interface AnomalyDetectionConfig {
+    /** Alert when a call's cost exceeds this multiple of the rolling per-entity average (e.g. 3 = 3×) */
+    multiplierThreshold: number;
+    /** Discord / Slack / generic webhook URL */
+    webhookUrl: string;
+    /** Hours of history to use as the baseline window (default: 24) */
+    windowHours?: number;
+    /** 'once' (default) — fire once per entity; 'always' — fire on every anomalous call */
+    mode?: 'once' | 'always';
+}
+interface IExporter {
+    /** Called after every successful track() — fire-and-forget, errors are swallowed */
+    export(entry: UsageEntry): void | Promise<void>;
+}
 interface TrackerConfig {
     /** 'memory' (default), 'sqlite', or a custom IStorage instance (e.g. PostgresStorage, MySQLStorage, MongoStorage) */
     storage?: 'memory' | 'sqlite' | IStorage;
@@ -44,6 +58,10 @@ interface TrackerConfig {
     };
     /** Log a hint after each call suggesting a cheaper model in the same family when savings > 50% */
     suggestions?: boolean;
+    /** Alert via webhook when a call's cost is Nx above the rolling average for that user or model */
+    anomalyDetection?: AnomalyDetectionConfig;
+    /** Custom exporter called after every tracked call (e.g. OTelExporter) */
+    exporter?: IExporter;
 }
 interface UsageEntry {
     model: string;
@@ -160,4 +178,4 @@ interface TrackingMeta {
     __feature?: string;
 }
 
-export type { BudgetConfig as B, CostForecast as C, FeatureStats as F, IStorage as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, ModelStats as d, PricesFile as e, ReportOptions as f, UserStats as g };
+export type { AnomalyDetectionConfig as A, BudgetConfig as B, CostForecast as C, FeatureStats as F, IExporter as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, IStorage as d, ModelStats as e, PricesFile as f, ReportOptions as g, UserStats as h };

package/dist/{index-CJKk1hHw.d.ts → index-D9xq0RNg.d.ts}

@@ -24,6 +24,20 @@ interface BudgetConfig {
     /** 'once' (default) — fire once per entity lifetime; 'always' — fire on every call that exceeds */
     mode?: 'once' | 'always';
 }
+interface AnomalyDetectionConfig {
+    /** Alert when a call's cost exceeds this multiple of the rolling per-entity average (e.g. 3 = 3×) */
+    multiplierThreshold: number;
+    /** Discord / Slack / generic webhook URL */
+    webhookUrl: string;
+    /** Hours of history to use as the baseline window (default: 24) */
+    windowHours?: number;
+    /** 'once' (default) — fire once per entity; 'always' — fire on every anomalous call */
+    mode?: 'once' | 'always';
+}
+interface IExporter {
+    /** Called after every successful track() — fire-and-forget, errors are swallowed */
+    export(entry: UsageEntry): void | Promise<void>;
+}
 interface TrackerConfig {
     /** 'memory' (default), 'sqlite', or a custom IStorage instance (e.g. PostgresStorage, MySQLStorage, MongoStorage) */
     storage?: 'memory' | 'sqlite' | IStorage;
@@ -44,6 +58,10 @@ interface TrackerConfig {
     };
     /** Log a hint after each call suggesting a cheaper model in the same family when savings > 50% */
     suggestions?: boolean;
+    /** Alert via webhook when a call's cost is Nx above the rolling average for that user or model */
+    anomalyDetection?: AnomalyDetectionConfig;
+    /** Custom exporter called after every tracked call (e.g. OTelExporter) */
+    exporter?: IExporter;
 }
 interface UsageEntry {
     model: string;
@@ -160,4 +178,4 @@ interface TrackingMeta {
     __feature?: string;
 }
 
-export type { BudgetConfig as B, CostForecast as C, FeatureStats as F, IStorage as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, ModelStats as d, PricesFile as e, ReportOptions as f, UserStats as g };
+export type { AnomalyDetectionConfig as A, BudgetConfig as B, CostForecast as C, FeatureStats as F, IExporter as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, IStorage as d, ModelStats as e, PricesFile as f, ReportOptions as g, UserStats as h };

package/dist/index.cjs

@@ -269,7 +269,7 @@ async function getRemotePrices() {
 
 // 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": {
@@ -1618,7 +1618,14 @@ var TrackerConfigSchema = import_zod.z.object({
     perUser: BudgetConfigSchema.optional(),
     perSession: BudgetConfigSchema.optional()
   }).optional(),
-  suggestions: import_zod.z.boolean().optional().default(false)
+  suggestions: import_zod.z.boolean().optional().default(false),
+  anomalyDetection: import_zod.z.object({
+    multiplierThreshold: import_zod.z.number().positive(),
+    webhookUrl: import_zod.z.string().url(),
+    windowHours: import_zod.z.number().positive().optional().default(24),
+    mode: import_zod.z.enum(["once", "always"]).optional().default("once")
+  }).optional(),
+  exporter: import_zod.z.custom((v) => v !== null && typeof v === "object" && typeof v.export === "function").optional()
 });
 function createTracker(config = {}) {
   const parsed = TrackerConfigSchema.safeParse(config);
@@ -1635,7 +1642,9 @@ ${issues}`);
     customPrices,
     warnIfStaleAfterHours,
     budgets,
-    suggestions
+    suggestions,
+    anomalyDetection,
+    exporter
   } = parsed.data;
   const storage = typeof storageOption === "object" ? storageOption : createStorage(storageOption);
   let remotePrices;
@@ -1668,6 +1677,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();
@@ -1692,7 +1702,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,
@@ -1862,11 +1877,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));