@diogonzafe/tokenwatch 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @diogonzafe/tokenwatch
 
-Transparent TypeScript wrapper that intercepts LLM API calls and tracks cost in real-time by session, user and model — without changing anything in your existing code.
+Transparent TypeScript wrapper that intercepts LLM API calls and tracks cost in real-time by session, user, model and feature — without changing anything in your existing code.
 
 Supports **OpenAI**, **Anthropic**, **Google Gemini** and **DeepSeek**.
 
@@ -34,17 +34,44 @@ import { createTracker } from '@diogonzafe/tokenwatch'
 const tracker = createTracker({
   // All fields are optional
   storage: 'memory',           // 'memory' (default) | 'sqlite' | IStorage instance
-  alertThreshold: 1.00,        // USD — fires webhookUrl when exceeded
+  alertThreshold: 1.00,        // USD — fires webhookUrl when total cost exceeded
   webhookUrl: 'https://...',   // Discord / Slack webhook
   syncPrices: true,            // fetch fresh prices from GitHub (default: true)
+  warnIfStaleAfterHours: 72,   // warn if prices are older than N hours (0 = disable)
   customPrices: {
     'my-model': { input: 0.50, output: 1.50, maxInputTokens: 32000 }  // USD per 1M tokens
-  }
+  },
+  budgets: {
+    perUser:    { threshold: 1.00, webhookUrl: 'https://...' },  // per-user alert
+    perSession: { threshold: 0.10, webhookUrl: 'https://...' },  // per-session alert
+  },
+  suggestions: true,            // log hints for cheaper models in same family (>50% savings)
 })
 ```
 
 ---
 
+## Lazy Initialization
+
+For module-level singletons where the tracker needs to be imported before `createTracker()` can run (e.g. shared modules, Jest test environments):
+
+```ts
+import { createLazyTracker } from '@diogonzafe/tokenwatch'
+
+// Safe to import anywhere — all methods are no-ops until init() is called
+export const tracker = createLazyTracker()
+
+// At app startup (e.g. index.ts / server.ts):
+tracker.init({ storage: 'sqlite', syncPrices: true })
+
+// In tests — never call init(), track() silently no-ops:
+tracker.track({ model: 'gpt-4o', inputTokens: 100, outputTokens: 50 }) // does nothing
+```
+
+`init()` may only be called once — a second call throws. A failed `init()` (e.g. invalid config) leaves the tracker in no-op mode. `LazyTracker` satisfies the `Tracker` interface, so it can be used anywhere a `Tracker` is expected.
+
+---
+
 ## OpenAI
 
 ```ts
@@ -124,7 +151,12 @@ import { wrapGemini } from '@diogonzafe/tokenwatch'
 
 const genAI = wrapGemini(new GoogleGenerativeAI(process.env.GEMINI_API_KEY!), tracker)
 
-const model = genAI.getGenerativeModel({ model: 'gemini-2.5-flash' })
+// __sessionId, __userId, __feature are passed to getGenerativeModel (not per-call)
+const model = genAI.getGenerativeModel({
+  model: 'gemini-2.5-flash',
+  __sessionId: 'session_abc',
+  __feature: 'rag',
+})
 const result = await model.generateContent('Explain quantum computing')
 ```
 
@@ -154,6 +186,111 @@ const res = await deepseek.chat.completions.create({
 
 ---
 
+## Agent Frameworks
+
+Frameworks like **Mastra**, **Vercel AI SDK**, **LlamaIndex**, and **LangChain** use their own internal LLM abstractions — they never expose the raw OpenAI/Anthropic client. `wrapOpenAI` and `wrapAnthropic` do not apply. Use `tracker.track()` manually via each framework's usage callback instead.
+
+> `tracker.track()` always expects `inputTokens` and `outputTokens`. The field names exposed by each framework differ — see the mappings below.
+
+### Mastra
+
+`agent.generate()` and `agent.stream()` expose usage in `onStepFinish`:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { createTracker } from '@diogonzafe/tokenwatch'
+
+const tracker = createTracker({ storage: 'sqlite' })
+
+const agent = new Agent({ model: 'openai/gpt-4o', instructions: '...' })
+
+const result = await agent.generate('Hello', {
+  onStepFinish: ({ usage }) => {
+    tracker.track({
+      model: 'gpt-4o',
+      inputTokens: usage.promptTokens,      // Mastra uses promptTokens
+      outputTokens: usage.completionTokens, // Mastra uses completionTokens
+      sessionId: 'sess-abc',
+    })
+  },
+})
+```
+
+### Vercel AI SDK
+
+`streamText` / `generateText` expose usage in `onFinish`. As of `ai` v5, the fields are `inputTokens` / `outputTokens`:
+
+```ts
+import { createOpenAI } from '@ai-sdk/openai'
+import { streamText } from 'ai'
+import { createTracker } from '@diogonzafe/tokenwatch'
+
+const tracker = createTracker({ storage: 'sqlite' })
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! })
+
+await streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello',
+  onFinish: ({ usage }) => {
+    tracker.track({
+      model: 'gpt-4o',
+      inputTokens: usage.inputTokens ?? 0,
+      outputTokens: usage.outputTokens ?? 0,
+    })
+  },
+})
+```
+
+For multi-step agents, use `totalUsage` instead of `usage` in `onFinish` to get the aggregate across all steps.
+
+### LlamaIndex TypeScript
+
+Use `Settings.callbackManager` to intercept `llm-end` events. The raw OpenAI response is available as `response.raw` with snake_case field names:
+
+```ts
+import { Settings } from 'llamaindex'
+import { createTracker } from '@diogonzafe/tokenwatch'
+
+const tracker = createTracker({ storage: 'sqlite' })
+
+Settings.callbackManager.on('llm-end', (event) => {
+  const raw = event.detail.response.raw as { model?: string; usage?: { prompt_tokens: number; completion_tokens: number } }
+  if (raw?.usage) {
+    tracker.track({
+      model: raw.model ?? 'unknown',
+      inputTokens: raw.usage.prompt_tokens,      // LlamaIndex exposes snake_case
+      outputTokens: raw.usage.completion_tokens,
+    })
+  }
+})
+```
+
+### LangChain.js
+
+Use the built-in `TokenwatchCallbackHandler` from the `/langchain` sub-path:
+
+```ts
+import { ChatOpenAI } from '@langchain/openai'
+import { createTracker } from '@diogonzafe/tokenwatch'
+import { TokenwatchCallbackHandler } from '@diogonzafe/tokenwatch/langchain'
+
+const tracker = createTracker({ storage: 'sqlite' })
+const handler = new TokenwatchCallbackHandler(tracker, {
+  defaultModel: 'gpt-4o',    // fallback when the response doesn't include the model name
+  sessionId: 'sess_abc',     // optional — tag all calls from this handler
+  userId: 'user_123',
+  feature: 'chat',
+})
+
+const llm = new ChatOpenAI({ model: 'gpt-4o', callbacks: [handler] })
+```
+
+The handler extracts `promptTokens` / `completionTokens` from `llmOutput.tokenUsage` (non-streaming) and falls back to `estimatedTokenUsage` for streaming calls. No `@langchain/core` compile-time dependency is required in tokenwatch itself — it is an optional peer dependency.
+
+> **Note:** This requires `@langchain/core >= 0.1.0` to be installed in your project.
+
+---
+
 ## Reports
 
 All report methods are async:
@@ -164,24 +301,36 @@ const report = await tracker.getReport()
 //   totalCostUSD: 0.087,
 //   totalTokens: { input: 24000, output: 6000 },
 //   byModel: {
-//     'gpt-4o':          { costUSD: 0.062, calls: 5, tokens: { input: 20000, output: 5000, reasoning: 0 } },
-//     'o3':              { costUSD: 0.041, calls: 1, tokens: { input: 1000,  output: 200,  reasoning: 800 } },
-//     'claude-sonnet-4-6': { costUSD: 0.025, calls: 2, tokens: { input: 4000, output: 1000, reasoning: 0 } }
+//     'gpt-4o': { costUSD: 0.062, calls: 5, tokens: { input: 20000, output: 5000, reasoning: 0, cached: 4000 } },
+//     'o3':     { costUSD: 0.041, calls: 1, tokens: { input: 1000,  output: 200,  reasoning: 800, cached: 0 } },
 //   },
 //   bySession: { 'session_abc': { costUSD: 0.045, calls: 4 } },
 //   byUser:    { 'user_123':    { costUSD: 0.087, calls: 7 } },
 //   byFeature: { 'chat': { costUSD: 0.062, calls: 5 }, 'rag': { costUSD: 0.025, calls: 3 } },
-//   period: { from: '2026-04-16T10:00:00Z', to: '2026-04-16T11:00:00Z' }
+//   period: { from: '2026-04-16T10:00:00Z', to: '2026-04-16T11:00:00Z' },
+//   pricesUpdatedAt: '2026-04-22'   // date of the price data in use
 // }
 
+// Time-filtered reports
+await tracker.getReport({ last: '24h' })          // last 24 hours
+await tracker.getReport({ last: '7d' })           // last 7 days
+await tracker.getReport({ since: '2026-04-01' })  // since a specific date
+await tracker.getReport({ since: '2026-04-01', until: '2026-04-30' })
+
+// Cost forecast — burn rate + projected daily/monthly spend
+const forecast = await tracker.getCostForecast()
+// { burnRatePerHour: 0.043, projectedDailyCostUSD: 1.03, projectedMonthlyCostUSD: 31.20, basedOnHours: 6 }
+
+await tracker.getCostForecast({ windowHours: 1 })  // use last 1h for burn rate calculation
+
 tracker.getModelInfo('gpt-4o')
-// { input: 2.5, output: 10, maxInputTokens: 128000 }
+// { input: 2.5, output: 10, cachedInput: 1.25, maxInputTokens: 128000 }
 // Returns null if the model is unknown (synchronous)
 
 await tracker.reset()                     // clear all data
 await tracker.resetSession('session_abc') // clear one session
 await tracker.exportJSON()                // full report as JSON string
-await tracker.exportCSV()                 // all raw calls as CSV (RFC 4180 — fields with commas/quotes are escaped)
+await tracker.exportCSV()                 // all raw calls as CSV (RFC 4180)
 ```
 
 ---
@@ -206,10 +355,10 @@ Prices are in **USD per 1 million tokens**.
 
 ```json
 {
-  "gpt-4o":            { "input": 2.50,  "output": 10.00, "maxInputTokens": 128000 },
-  "claude-sonnet-4-6": { "input": 3.00,  "output": 15.00, "maxInputTokens": 1000000 },
-  "gemini-2.5-pro":    { "input": 1.25,  "output": 10.00, "maxInputTokens": 1048576 },
-  "deepseek-chat":     { "input": 0.28,  "output": 0.42,  "maxInputTokens": 131072 }
+  "gpt-4o":            { "input": 2.50, "output": 10.00, "cachedInput": 1.25,  "maxInputTokens": 128000 },
+  "claude-sonnet-4-6": { "input": 3.00, "output": 15.00, "cachedInput": 0.30,  "cacheCreationInput": 3.75, "maxInputTokens": 1000000 },
+  "gemini-2.5-pro":    { "input": 1.25, "output": 10.00,                        "maxInputTokens": 1048576 },
+  "deepseek-chat":     { "input": 0.28, "output": 0.42,                         "maxInputTokens": 131072 }
 }
 ```
 
@@ -311,8 +460,45 @@ const tracker = createTracker({ storage: new RedisStorage() })
 
 ---
 
+## Prompt Caching
+
+OpenAI and Anthropic offer discounted pricing for cached prompt tokens. tokenwatch tracks these automatically — no changes needed at the call site.
+
+**OpenAI** — cached reads billed at 50% of input price:
+```ts
+// prompt_tokens_details.cached_tokens is extracted automatically
+const res = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: '...' }],
+})
+// report.byModel['gpt-4o'].tokens.cached shows how many tokens were served from cache
+```
+
+**Anthropic** — cache reads at 10% of input price, cache creation at 125%:
+```ts
+const res = await anthropic.messages.create({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: '...' }],
+  // cache_read_input_tokens and cache_creation_input_tokens extracted from usage automatically
+})
+```
+
+Cached token prices are included in `prices.json` for all models that support caching. You can also override them:
+```ts
+const tracker = createTracker({
+  customPrices: {
+    'my-model': { input: 2.50, output: 10.00, cachedInput: 1.25, cacheCreationInput: 3.13 }
+  }
+})
+```
+
+---
+
 ## Alerts & Webhooks
 
+### Global threshold
+
 ```ts
 const tracker = createTracker({
   alertThreshold: 5.00,                          // USD
@@ -326,6 +512,36 @@ Webhook payload:
 { "text": "[tokenwatch] Alert: total cost reached $5.0012 USD (threshold: $5)" }
 ```
 
+### Per-user and per-session budgets
+
+```ts
+const tracker = createTracker({
+  budgets: {
+    perUser: {
+      threshold: 1.00,
+      webhookUrl: 'https://hooks.slack.com/...',
+      mode: 'once',   // default — fires once per user; use 'always' to fire on every call that exceeds
+    },
+    perSession: {
+      threshold: 0.10,
+      webhookUrl: 'https://hooks.slack.com/...',
+    },
+  },
+})
+
+await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  __userId: 'user_123',       // required for perUser alert to fire
+  __sessionId: 'sess_abc',    // required for perSession alert to fire
+})
+```
+
+Budget webhook payload:
+```json
+{ "text": "[tokenwatch] Budget alert: user \"user_123\" reached $1.0031 USD (threshold: $1)" }
+```
+
 ---
 
 ## CLI
@@ -351,6 +567,10 @@ npx tokenwatch help     # show help
 
   By user:
     user_123                       $0.004231  (11 calls)
+
+  By feature:
+    chat                           $0.002500  (5 calls)
+    rag                            $0.001731  (6 calls)
 ───────────────────────────────────────────────────
 ```
 
@@ -367,11 +587,36 @@ Requires `storage: 'sqlite'` in your app and `better-sqlite3` installed.
 
 ---
 
+## TypeScript
+
+`__sessionId`, `__userId`, and `__feature` are typed via the `TrackingMeta` interface, which is automatically merged into the `create` params type by the wrapper. In most setups they just work with no cast required.
+
+If you hit a type error (e.g. with stricter SDK versions), use `as Record<string, unknown>`:
+
+```ts
+await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [],
+  __sessionId: 'sess-1',
+  __feature: 'chat',
+} as Record<string, unknown>)
+```
+
+`TrackingMeta` is exported if you need to annotate your own helper types:
+
+```ts
+import type { TrackingMeta } from '@diogonzafe/tokenwatch'
+
+type MyParams = { model: string; messages: Message[] } & TrackingMeta
+```
+
+---
+
 ## Behaviour Guarantees
 
 - `__sessionId`, `__userId`, and `__feature` are **stripped before** the request reaches the API
 - The response object returned is **identical** to the original SDK response
-- `track()` is **synchronous and non-blocking** — zero latency added to API calls
+- `track()` is **synchronous and non-blocking** — negligible sub-millisecond overhead; no proxy server or network hop
 - If the API call **fails**, no cost is recorded and the original error is re-thrown unchanged
 - Streaming is fully supported — usage is accumulated from the final stream event
 - Database writes from `record()` are **fire-and-forget** — a storage failure never interrupts your API call

package/dist/adapters.cjs

@@ -32,33 +32,52 @@ var PostgresStorage = class {
     this.client = client;
   }
   client;
-  /** Creates the `tokenwatch_usage` table if it does not already exist. */
+  /** Creates the `tokenwatch_usage` table if it does not already exist.
+   *  Also adds new columns for databases created before v0.2.0 / v0.3.0. */
   async migrate() {
     await this.client.query(`
       CREATE TABLE IF NOT EXISTS tokenwatch_usage (
-        id            BIGSERIAL PRIMARY KEY,
-        model         TEXT      NOT NULL,
-        input_tokens  INTEGER   NOT NULL,
-        output_tokens INTEGER   NOT NULL,
-        cost_usd      NUMERIC   NOT NULL,
-        session_id    TEXT,
-        user_id       TEXT,
-        timestamp     TIMESTAMPTZ NOT NULL
+        id                    BIGSERIAL PRIMARY KEY,
+        model                 TEXT        NOT NULL,
+        input_tokens          INTEGER     NOT NULL,
+        output_tokens         INTEGER     NOT NULL,
+        reasoning_tokens      INTEGER     NOT NULL DEFAULT 0,
+        cached_tokens         INTEGER     NOT NULL DEFAULT 0,
+        cache_creation_tokens INTEGER     NOT NULL DEFAULT 0,
+        cost_usd              NUMERIC     NOT NULL,
+        session_id            TEXT,
+        user_id               TEXT,
+        feature               TEXT,
+        timestamp             TIMESTAMPTZ NOT NULL
       )
     `);
+    for (const col of [
+      "ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS reasoning_tokens INTEGER NOT NULL DEFAULT 0",
+      "ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS feature TEXT",
+      "ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS cached_tokens INTEGER NOT NULL DEFAULT 0",
+      "ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS cache_creation_tokens INTEGER NOT NULL DEFAULT 0"
+    ]) {
+      await this.client.query(col).catch(() => {
+      });
+    }
   }
   record(entry) {
     this.client.query(
       `INSERT INTO tokenwatch_usage
-         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)
-         VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+         (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,
+          cost_usd, session_id, user_id, feature, timestamp)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
       [
         entry.model,
         entry.inputTokens,
         entry.outputTokens,
+        entry.reasoningTokens ?? 0,
+        entry.cachedTokens ?? 0,
+        entry.cacheCreationTokens ?? 0,
         entry.costUSD,
         entry.sessionId ?? null,
         entry.userId ?? null,
+        entry.feature ?? null,
         entry.timestamp
       ]
     ).catch((err) => {
@@ -82,13 +101,20 @@ var PostgresStorage = class {
   }
 };
 function rowToEntry(r) {
+  const reasoningTokens = r["reasoning_tokens"] ?? 0;
+  const cachedTokens = r["cached_tokens"] ?? 0;
+  const cacheCreationTokens = r["cache_creation_tokens"] ?? 0;
   return {
     model: r["model"],
     inputTokens: r["input_tokens"],
     outputTokens: r["output_tokens"],
+    ...reasoningTokens > 0 && { reasoningTokens },
+    ...cachedTokens > 0 && { cachedTokens },
+    ...cacheCreationTokens > 0 && { cacheCreationTokens },
     costUSD: Number(r["cost_usd"]),
     ...r["session_id"] != null && { sessionId: r["session_id"] },
     ...r["user_id"] != null && { userId: r["user_id"] },
+    ...r["feature"] != null && { feature: r["feature"] },
     timestamp: r["timestamp"] instanceof Date ? r["timestamp"].toISOString() : r["timestamp"]
   };
 }
@@ -99,33 +125,51 @@ var MySQLStorage = class {
     this.client = client;
   }
   client;
-  /** Creates the `tokenwatch_usage` table if it does not already exist. */
+  /** Creates the `tokenwatch_usage` table if it does not already exist.
+   *  Also adds new columns for databases created before v0.2.0 / v0.3.0. */
   async migrate() {
     await this.client.execute(`
       CREATE TABLE IF NOT EXISTS tokenwatch_usage (
-        id            BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-        model         VARCHAR(255) NOT NULL,
-        input_tokens  INT          NOT NULL,
-        output_tokens INT          NOT NULL,
-        cost_usd      DECIMAL(18,8) NOT NULL,
-        session_id    VARCHAR(255),
-        user_id       VARCHAR(255),
-        timestamp     DATETIME(3)  NOT NULL
+        id                    BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+        model                 VARCHAR(255)  NOT NULL,
+        input_tokens          INT           NOT NULL,
+        output_tokens         INT           NOT NULL,
+        reasoning_tokens      INT           NOT NULL DEFAULT 0,
+        cached_tokens         INT           NOT NULL DEFAULT 0,
+        cache_creation_tokens INT           NOT NULL DEFAULT 0,
+        cost_usd              DECIMAL(18,8) NOT NULL,
+        session_id            VARCHAR(255),
+        user_id               VARCHAR(255),
+        feature               VARCHAR(255),
+        timestamp             DATETIME(3)   NOT NULL
       )
     `);
+    await this.client.execute(`
+      ALTER TABLE tokenwatch_usage
+        ADD COLUMN IF NOT EXISTS reasoning_tokens      INT NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS feature               VARCHAR(255),
+        ADD COLUMN IF NOT EXISTS cached_tokens         INT NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS cache_creation_tokens INT NOT NULL DEFAULT 0
+    `).catch(() => {
+    });
   }
   record(entry) {
     this.client.execute(
       `INSERT INTO tokenwatch_usage
-         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+         (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,
+          cost_usd, session_id, user_id, feature, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         entry.model,
         entry.inputTokens,
         entry.outputTokens,
+        entry.reasoningTokens ?? 0,
+        entry.cachedTokens ?? 0,
+        entry.cacheCreationTokens ?? 0,
         entry.costUSD,
         entry.sessionId ?? null,
         entry.userId ?? null,
+        entry.feature ?? null,
         entry.timestamp
       ]
     ).catch((err) => {
@@ -149,13 +193,20 @@ var MySQLStorage = class {
   }
 };
 function rowToEntry2(r) {
+  const reasoningTokens = r["reasoning_tokens"] ?? 0;
+  const cachedTokens = r["cached_tokens"] ?? 0;
+  const cacheCreationTokens = r["cache_creation_tokens"] ?? 0;
   return {
     model: r["model"],
     inputTokens: r["input_tokens"],
     outputTokens: r["output_tokens"],
+    ...reasoningTokens > 0 && { reasoningTokens },
+    ...cachedTokens > 0 && { cachedTokens },
+    ...cacheCreationTokens > 0 && { cacheCreationTokens },
     costUSD: Number(r["cost_usd"]),
     ...r["session_id"] != null && { sessionId: r["session_id"] },
     ...r["user_id"] != null && { userId: r["user_id"] },
+    ...r["feature"] != null && { feature: r["feature"] },
     timestamp: r["timestamp"] instanceof Date ? r["timestamp"].toISOString() : r["timestamp"]
   };
 }
@@ -179,9 +230,13 @@ var MongoStorage = class {
       model: entry.model,
       inputTokens: entry.inputTokens,
       outputTokens: entry.outputTokens,
+      ...entry.reasoningTokens !== void 0 && { reasoningTokens: entry.reasoningTokens },
+      ...entry.cachedTokens !== void 0 && { cachedTokens: entry.cachedTokens },
+      ...entry.cacheCreationTokens !== void 0 && { cacheCreationTokens: entry.cacheCreationTokens },
       costUSD: entry.costUSD,
       sessionId: entry.sessionId ?? null,
       userId: entry.userId ?? null,
+      ...entry.feature !== void 0 && { feature: entry.feature },
       timestamp: entry.timestamp
     }).catch((err) => {
       console.warn("[tokenwatch] MongoStorage.record failed:", err);
@@ -203,9 +258,13 @@ function docToEntry(doc) {
     model: doc.model,
     inputTokens: doc.inputTokens,
     outputTokens: doc.outputTokens,
+    ...doc.reasoningTokens != null && doc.reasoningTokens > 0 && { reasoningTokens: doc.reasoningTokens },
+    ...doc.cachedTokens != null && doc.cachedTokens > 0 && { cachedTokens: doc.cachedTokens },
+    ...doc.cacheCreationTokens != null && doc.cacheCreationTokens > 0 && { cacheCreationTokens: doc.cacheCreationTokens },
     costUSD: doc.costUSD,
     ...doc.sessionId != null && { sessionId: doc.sessionId },
     ...doc.userId != null && { userId: doc.userId },
+    ...doc.feature != null && { feature: doc.feature },
     timestamp: doc.timestamp
   };
 }

package/dist/adapters.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/index.ts","../src/adapters/postgres.ts","../src/adapters/mysql.ts","../src/adapters/mongodb.ts"],"sourcesContent":["export { PostgresStorage } from './postgres.js'\nexport { MySQLStorage } from './mysql.js'\nexport { MongoStorage } from './mongodb.js'\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for PostgreSQL using the `pg` driver.\n *\n * Install peer dep:  npm install pg\n * Types (optional):  npm install -D @types/pg\n *\n * @example\n * ```ts\n * import { Pool } from 'pg'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { PostgresStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL })\n * const storage = new PostgresStorage(pool)\n * await storage.migrate()          // create table if it doesn't exist\n *\n * const tracker = createTracker({ storage })\n * ```\n */\n\n// Minimal structural types so the adapter compiles without `pg` installed\ninterface QueryClient {\n  query(sql: string, values?: unknown[]): Promise<{ rows: unknown[] }>\n}\n\nexport class PostgresStorage implements IStorage {\n  constructor(private readonly client: QueryClient) {}\n\n  /** Creates the `tokenwatch_usage` table if it does not already exist. */\n  async migrate(): Promise<void> {\n    await this.client.query(`\n      CREATE TABLE IF NOT EXISTS tokenwatch_usage (\n        id            BIGSERIAL PRIMARY KEY,\n        model         TEXT      NOT NULL,\n        input_tokens  INTEGER   NOT NULL,\n        output_tokens INTEGER   NOT NULL,\n        cost_usd      NUMERIC   NOT NULL,\n        session_id    TEXT,\n        user_id       TEXT,\n        timestamp     TIMESTAMPTZ NOT NULL\n      )\n    `)\n  }\n\n  record(entry: UsageEntry): void {\n    this.client\n      .query(\n        `INSERT INTO tokenwatch_usage\n         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)\n         VALUES ($1, $2, $3, $4, $5, $6, $7)`,\n        [\n          entry.model,\n          entry.inputTokens,\n          entry.outputTokens,\n          entry.costUSD,\n          entry.sessionId ?? null,\n          entry.userId ?? null,\n          entry.timestamp,\n        ],\n      )\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] PostgresStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const result = await this.client.query(\n      'SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC',\n    )\n    return (result.rows as Array<Record<string, unknown>>).map(rowToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.client.query('DELETE FROM tokenwatch_usage')\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.client.query(\n      'DELETE FROM tokenwatch_usage WHERE session_id = $1',\n      [sessionId],\n    )\n  }\n}\n\nfunction rowToEntry(r: Record<string, unknown>): UsageEntry {\n  return {\n    model: r['model'] as string,\n    inputTokens: r['input_tokens'] as number,\n    outputTokens: r['output_tokens'] as number,\n    costUSD: Number(r['cost_usd']),\n    ...(r['session_id'] != null && { sessionId: r['session_id'] as string }),\n    ...(r['user_id'] != null && { userId: r['user_id'] as string }),\n    timestamp:\n      r['timestamp'] instanceof Date\n        ? (r['timestamp'] as Date).toISOString()\n        : (r['timestamp'] as string),\n  }\n}\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for MySQL / MariaDB using the `mysql2` driver.\n *\n * Install peer dep:  npm install mysql2\n *\n * @example\n * ```ts\n * import mysql from 'mysql2/promise'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { MySQLStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const pool = mysql.createPool({ uri: process.env.MYSQL_URL })\n * const storage = new MySQLStorage(pool)\n * await storage.migrate()          // create table if it doesn't exist\n *\n * const tracker = createTracker({ storage })\n * ```\n */\n\n// Minimal structural type so the adapter compiles without `mysql2` installed\ninterface QueryClient {\n  execute(sql: string, values?: unknown[]): Promise<[unknown]>\n}\n\nexport class MySQLStorage implements IStorage {\n  constructor(private readonly client: QueryClient) {}\n\n  /** Creates the `tokenwatch_usage` table if it does not already exist. */\n  async migrate(): Promise<void> {\n    await this.client.execute(`\n      CREATE TABLE IF NOT EXISTS tokenwatch_usage (\n        id            BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,\n        model         VARCHAR(255) NOT NULL,\n        input_tokens  INT          NOT NULL,\n        output_tokens INT          NOT NULL,\n        cost_usd      DECIMAL(18,8) NOT NULL,\n        session_id    VARCHAR(255),\n        user_id       VARCHAR(255),\n        timestamp     DATETIME(3)  NOT NULL\n      )\n    `)\n  }\n\n  record(entry: UsageEntry): void {\n    this.client\n      .execute(\n        `INSERT INTO tokenwatch_usage\n         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)\n         VALUES (?, ?, ?, ?, ?, ?, ?)`,\n        [\n          entry.model,\n          entry.inputTokens,\n          entry.outputTokens,\n          entry.costUSD,\n          entry.sessionId ?? null,\n          entry.userId ?? null,\n          entry.timestamp,\n        ],\n      )\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] MySQLStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const [rows] = await this.client.execute(\n      'SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC',\n    )\n    return (rows as Array<Record<string, unknown>>).map(rowToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.client.execute('DELETE FROM tokenwatch_usage')\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.client.execute(\n      'DELETE FROM tokenwatch_usage WHERE session_id = ?',\n      [sessionId],\n    )\n  }\n}\n\nfunction rowToEntry(r: Record<string, unknown>): UsageEntry {\n  return {\n    model: r['model'] as string,\n    inputTokens: r['input_tokens'] as number,\n    outputTokens: r['output_tokens'] as number,\n    costUSD: Number(r['cost_usd']),\n    ...(r['session_id'] != null && { sessionId: r['session_id'] as string }),\n    ...(r['user_id'] != null && { userId: r['user_id'] as string }),\n    timestamp:\n      r['timestamp'] instanceof Date\n        ? (r['timestamp'] as Date).toISOString()\n        : (r['timestamp'] as string),\n  }\n}\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for MongoDB using the official `mongodb` driver.\n *\n * Install peer dep:  npm install mongodb\n *\n * @example\n * ```ts\n * import { MongoClient } from 'mongodb'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { MongoStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const client = new MongoClient(process.env.MONGO_URL!)\n * await client.connect()\n *\n * const storage = new MongoStorage(client.db('myapp'))\n * const tracker = createTracker({ storage })\n * ```\n *\n * Recommended index (run once at startup):\n * ```ts\n * await storage.createIndexes()\n * ```\n */\n\n// Minimal structural types so the adapter compiles without `mongodb` installed\ninterface MongoDocument {\n  _id?: unknown\n  model: string\n  inputTokens: number\n  outputTokens: number\n  costUSD: number\n  sessionId?: string | null\n  userId?: string | null\n  timestamp: string\n}\n\ninterface MongoCursor {\n  sort(sort: Record<string, unknown>): MongoCursor\n  toArray(): Promise<MongoDocument[]>\n}\n\ninterface Collection {\n  insertOne(doc: MongoDocument): Promise<unknown>\n  find(filter: Record<string, unknown>): MongoCursor\n  deleteMany(filter: Record<string, unknown>): Promise<unknown>\n  createIndex(index: Record<string, unknown>): Promise<unknown>\n}\n\ninterface Database {\n  collection(name: string): Collection\n}\n\nconst COLLECTION = 'tokenwatch_usage'\n\nexport class MongoStorage implements IStorage {\n  private readonly col: Collection\n\n  constructor(db: Database) {\n    this.col = db.collection(COLLECTION)\n  }\n\n  /** Creates recommended indexes for query performance. Call once at startup. */\n  async createIndexes(): Promise<void> {\n    await this.col.createIndex({ timestamp: 1 })\n    await this.col.createIndex({ sessionId: 1 })\n    await this.col.createIndex({ userId: 1 })\n    await this.col.createIndex({ model: 1 })\n  }\n\n  record(entry: UsageEntry): void {\n    this.col\n      .insertOne({\n        model: entry.model,\n        inputTokens: entry.inputTokens,\n        outputTokens: entry.outputTokens,\n        costUSD: entry.costUSD,\n        sessionId: entry.sessionId ?? null,\n        userId: entry.userId ?? null,\n        timestamp: entry.timestamp,\n      })\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] MongoStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const docs = await this.col.find({}).sort({ timestamp: 1 }).toArray()\n    return docs.map(docToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.col.deleteMany({})\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.col.deleteMany({ sessionId })\n  }\n}\n\nfunction docToEntry(doc: MongoDocument): UsageEntry {\n  return {\n    model: doc.model,\n    inputTokens: doc.inputTokens,\n    outputTokens: doc.outputTokens,\n    costUSD: doc.costUSD,\n    ...(doc.sessionId != null && { sessionId: doc.sessionId }),\n    ...(doc.userId != null && { userId: doc.userId }),\n    timestamp: doc.timestamp,\n  }\n}\n"],"mappings":"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","names":["rowToEntry"]}
+{"version":3,"sources":["../src/adapters/index.ts","../src/adapters/postgres.ts","../src/adapters/mysql.ts","../src/adapters/mongodb.ts"],"sourcesContent":["export { PostgresStorage } from './postgres.js'\nexport { MySQLStorage } from './mysql.js'\nexport { MongoStorage } from './mongodb.js'\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for PostgreSQL using the `pg` driver.\n *\n * Install peer dep:  npm install pg\n * Types (optional):  npm install -D @types/pg\n *\n * @example\n * ```ts\n * import { Pool } from 'pg'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { PostgresStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL })\n * const storage = new PostgresStorage(pool)\n * await storage.migrate()          // create table if it doesn't exist\n *\n * const tracker = createTracker({ storage })\n * ```\n */\n\n// Minimal structural types so the adapter compiles without `pg` installed\ninterface QueryClient {\n  query(sql: string, values?: unknown[]): Promise<{ rows: unknown[] }>\n}\n\nexport class PostgresStorage implements IStorage {\n  constructor(private readonly client: QueryClient) {}\n\n  /** Creates the `tokenwatch_usage` table if it does not already exist.\n   *  Also adds new columns for databases created before v0.2.0 / v0.3.0. */\n  async migrate(): Promise<void> {\n    await this.client.query(`\n      CREATE TABLE IF NOT EXISTS tokenwatch_usage (\n        id                    BIGSERIAL PRIMARY KEY,\n        model                 TEXT        NOT NULL,\n        input_tokens          INTEGER     NOT NULL,\n        output_tokens         INTEGER     NOT NULL,\n        reasoning_tokens      INTEGER     NOT NULL DEFAULT 0,\n        cached_tokens         INTEGER     NOT NULL DEFAULT 0,\n        cache_creation_tokens INTEGER     NOT NULL DEFAULT 0,\n        cost_usd              NUMERIC     NOT NULL,\n        session_id            TEXT,\n        user_id               TEXT,\n        feature               TEXT,\n        timestamp             TIMESTAMPTZ NOT NULL\n      )\n    `)\n    // Incremental migrations for databases created before v0.2.0 / v0.3.0\n    for (const col of [\n      'ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS reasoning_tokens INTEGER NOT NULL DEFAULT 0',\n      'ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS feature TEXT',\n      'ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS cached_tokens INTEGER NOT NULL DEFAULT 0',\n      'ALTER TABLE tokenwatch_usage ADD COLUMN IF NOT EXISTS cache_creation_tokens INTEGER NOT NULL DEFAULT 0',\n    ]) {\n      await this.client.query(col).catch(() => { /* column already exists */ })\n    }\n  }\n\n  record(entry: UsageEntry): void {\n    this.client\n      .query(\n        `INSERT INTO tokenwatch_usage\n         (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,\n          cost_usd, session_id, user_id, feature, timestamp)\n         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,\n        [\n          entry.model,\n          entry.inputTokens,\n          entry.outputTokens,\n          entry.reasoningTokens ?? 0,\n          entry.cachedTokens ?? 0,\n          entry.cacheCreationTokens ?? 0,\n          entry.costUSD,\n          entry.sessionId ?? null,\n          entry.userId ?? null,\n          entry.feature ?? null,\n          entry.timestamp,\n        ],\n      )\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] PostgresStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const result = await this.client.query(\n      'SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC',\n    )\n    return (result.rows as Array<Record<string, unknown>>).map(rowToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.client.query('DELETE FROM tokenwatch_usage')\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.client.query(\n      'DELETE FROM tokenwatch_usage WHERE session_id = $1',\n      [sessionId],\n    )\n  }\n}\n\nfunction rowToEntry(r: Record<string, unknown>): UsageEntry {\n  const reasoningTokens = (r['reasoning_tokens'] as number | null) ?? 0\n  const cachedTokens = (r['cached_tokens'] as number | null) ?? 0\n  const cacheCreationTokens = (r['cache_creation_tokens'] as number | null) ?? 0\n  return {\n    model: r['model'] as string,\n    inputTokens: r['input_tokens'] as number,\n    outputTokens: r['output_tokens'] as number,\n    ...(reasoningTokens > 0 && { reasoningTokens }),\n    ...(cachedTokens > 0 && { cachedTokens }),\n    ...(cacheCreationTokens > 0 && { cacheCreationTokens }),\n    costUSD: Number(r['cost_usd']),\n    ...(r['session_id'] != null && { sessionId: r['session_id'] as string }),\n    ...(r['user_id'] != null && { userId: r['user_id'] as string }),\n    ...(r['feature'] != null && { feature: r['feature'] as string }),\n    timestamp:\n      r['timestamp'] instanceof Date\n        ? (r['timestamp'] as Date).toISOString()\n        : (r['timestamp'] as string),\n  }\n}\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for MySQL / MariaDB using the `mysql2` driver.\n *\n * Install peer dep:  npm install mysql2\n *\n * @example\n * ```ts\n * import mysql from 'mysql2/promise'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { MySQLStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const pool = mysql.createPool({ uri: process.env.MYSQL_URL })\n * const storage = new MySQLStorage(pool)\n * await storage.migrate()          // create table if it doesn't exist\n *\n * const tracker = createTracker({ storage })\n * ```\n */\n\n// Minimal structural type so the adapter compiles without `mysql2` installed\ninterface QueryClient {\n  execute(sql: string, values?: unknown[]): Promise<[unknown]>\n}\n\nexport class MySQLStorage implements IStorage {\n  constructor(private readonly client: QueryClient) {}\n\n  /** Creates the `tokenwatch_usage` table if it does not already exist.\n   *  Also adds new columns for databases created before v0.2.0 / v0.3.0. */\n  async migrate(): Promise<void> {\n    await this.client.execute(`\n      CREATE TABLE IF NOT EXISTS tokenwatch_usage (\n        id                    BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,\n        model                 VARCHAR(255)  NOT NULL,\n        input_tokens          INT           NOT NULL,\n        output_tokens         INT           NOT NULL,\n        reasoning_tokens      INT           NOT NULL DEFAULT 0,\n        cached_tokens         INT           NOT NULL DEFAULT 0,\n        cache_creation_tokens INT           NOT NULL DEFAULT 0,\n        cost_usd              DECIMAL(18,8) NOT NULL,\n        session_id            VARCHAR(255),\n        user_id               VARCHAR(255),\n        feature               VARCHAR(255),\n        timestamp             DATETIME(3)   NOT NULL\n      )\n    `)\n    // Incremental migrations for databases created before v0.2.0 / v0.3.0\n    await this.client.execute(`\n      ALTER TABLE tokenwatch_usage\n        ADD COLUMN IF NOT EXISTS reasoning_tokens      INT NOT NULL DEFAULT 0,\n        ADD COLUMN IF NOT EXISTS feature               VARCHAR(255),\n        ADD COLUMN IF NOT EXISTS cached_tokens         INT NOT NULL DEFAULT 0,\n        ADD COLUMN IF NOT EXISTS cache_creation_tokens INT NOT NULL DEFAULT 0\n    `).catch(() => { /* MySQL < 8.0 may not support IF NOT EXISTS — ignore if columns already exist */ })\n  }\n\n  record(entry: UsageEntry): void {\n    this.client\n      .execute(\n        `INSERT INTO tokenwatch_usage\n         (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,\n          cost_usd, session_id, user_id, feature, timestamp)\n         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n        [\n          entry.model,\n          entry.inputTokens,\n          entry.outputTokens,\n          entry.reasoningTokens ?? 0,\n          entry.cachedTokens ?? 0,\n          entry.cacheCreationTokens ?? 0,\n          entry.costUSD,\n          entry.sessionId ?? null,\n          entry.userId ?? null,\n          entry.feature ?? null,\n          entry.timestamp,\n        ],\n      )\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] MySQLStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const [rows] = await this.client.execute(\n      'SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC',\n    )\n    return (rows as Array<Record<string, unknown>>).map(rowToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.client.execute('DELETE FROM tokenwatch_usage')\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.client.execute(\n      'DELETE FROM tokenwatch_usage WHERE session_id = ?',\n      [sessionId],\n    )\n  }\n}\n\nfunction rowToEntry(r: Record<string, unknown>): UsageEntry {\n  const reasoningTokens = (r['reasoning_tokens'] as number | null) ?? 0\n  const cachedTokens = (r['cached_tokens'] as number | null) ?? 0\n  const cacheCreationTokens = (r['cache_creation_tokens'] as number | null) ?? 0\n  return {\n    model: r['model'] as string,\n    inputTokens: r['input_tokens'] as number,\n    outputTokens: r['output_tokens'] as number,\n    ...(reasoningTokens > 0 && { reasoningTokens }),\n    ...(cachedTokens > 0 && { cachedTokens }),\n    ...(cacheCreationTokens > 0 && { cacheCreationTokens }),\n    costUSD: Number(r['cost_usd']),\n    ...(r['session_id'] != null && { sessionId: r['session_id'] as string }),\n    ...(r['user_id'] != null && { userId: r['user_id'] as string }),\n    ...(r['feature'] != null && { feature: r['feature'] as string }),\n    timestamp:\n      r['timestamp'] instanceof Date\n        ? (r['timestamp'] as Date).toISOString()\n        : (r['timestamp'] as string),\n  }\n}\n","import type { IStorage, UsageEntry } from '../types/index.js'\n\n/**\n * IStorage adapter for MongoDB using the official `mongodb` driver.\n *\n * Install peer dep:  npm install mongodb\n *\n * @example\n * ```ts\n * import { MongoClient } from 'mongodb'\n * import { createTracker } from '@diogonzafe/tokenwatch'\n * import { MongoStorage } from '@diogonzafe/tokenwatch/adapters'\n *\n * const client = new MongoClient(process.env.MONGO_URL!)\n * await client.connect()\n *\n * const storage = new MongoStorage(client.db('myapp'))\n * const tracker = createTracker({ storage })\n * ```\n *\n * Recommended index (run once at startup):\n * ```ts\n * await storage.createIndexes()\n * ```\n */\n\n// Minimal structural types so the adapter compiles without `mongodb` installed\ninterface MongoDocument {\n  _id?: unknown\n  model: string\n  inputTokens: number\n  outputTokens: number\n  reasoningTokens?: number\n  cachedTokens?: number\n  cacheCreationTokens?: number\n  costUSD: number\n  sessionId?: string | null\n  userId?: string | null\n  feature?: string | null\n  timestamp: string\n}\n\ninterface MongoCursor {\n  sort(sort: Record<string, unknown>): MongoCursor\n  toArray(): Promise<MongoDocument[]>\n}\n\ninterface Collection {\n  insertOne(doc: MongoDocument): Promise<unknown>\n  find(filter: Record<string, unknown>): MongoCursor\n  deleteMany(filter: Record<string, unknown>): Promise<unknown>\n  createIndex(index: Record<string, unknown>): Promise<unknown>\n}\n\ninterface Database {\n  collection(name: string): Collection\n}\n\nconst COLLECTION = 'tokenwatch_usage'\n\nexport class MongoStorage implements IStorage {\n  private readonly col: Collection\n\n  constructor(db: Database) {\n    this.col = db.collection(COLLECTION)\n  }\n\n  /** Creates recommended indexes for query performance. Call once at startup. */\n  async createIndexes(): Promise<void> {\n    await this.col.createIndex({ timestamp: 1 })\n    await this.col.createIndex({ sessionId: 1 })\n    await this.col.createIndex({ userId: 1 })\n    await this.col.createIndex({ model: 1 })\n  }\n\n  record(entry: UsageEntry): void {\n    this.col\n      .insertOne({\n        model: entry.model,\n        inputTokens: entry.inputTokens,\n        outputTokens: entry.outputTokens,\n        ...(entry.reasoningTokens !== undefined && { reasoningTokens: entry.reasoningTokens }),\n        ...(entry.cachedTokens !== undefined && { cachedTokens: entry.cachedTokens }),\n        ...(entry.cacheCreationTokens !== undefined && { cacheCreationTokens: entry.cacheCreationTokens }),\n        costUSD: entry.costUSD,\n        sessionId: entry.sessionId ?? null,\n        userId: entry.userId ?? null,\n        ...(entry.feature !== undefined && { feature: entry.feature }),\n        timestamp: entry.timestamp,\n      })\n      .catch((err: unknown) => {\n        console.warn('[tokenwatch] MongoStorage.record failed:', err)\n      })\n  }\n\n  async getAll(): Promise<UsageEntry[]> {\n    const docs = await this.col.find({}).sort({ timestamp: 1 }).toArray()\n    return docs.map(docToEntry)\n  }\n\n  async clearAll(): Promise<void> {\n    await this.col.deleteMany({})\n  }\n\n  async clearSession(sessionId: string): Promise<void> {\n    await this.col.deleteMany({ sessionId })\n  }\n}\n\nfunction docToEntry(doc: MongoDocument): UsageEntry {\n  return {\n    model: doc.model,\n    inputTokens: doc.inputTokens,\n    outputTokens: doc.outputTokens,\n    ...(doc.reasoningTokens != null && doc.reasoningTokens > 0 && { reasoningTokens: doc.reasoningTokens }),\n    ...(doc.cachedTokens != null && doc.cachedTokens > 0 && { cachedTokens: doc.cachedTokens }),\n    ...(doc.cacheCreationTokens != null && doc.cacheCreationTokens > 0 && { cacheCreationTokens: doc.cacheCreationTokens }),\n    costUSD: doc.costUSD,\n    ...(doc.sessionId != null && { sessionId: doc.sessionId }),\n    ...(doc.userId != null && { userId: doc.userId }),\n    ...(doc.feature != null && { feature: doc.feature }),\n    timestamp: doc.timestamp,\n  }\n}\n"],"mappings":"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","names":["rowToEntry"]}