@diogonzafe/tokenwatch 0.1.7 → 0.1.9

package/README.md

@@ -17,6 +17,11 @@ npm install openai                  # OpenAI / DeepSeek
 npm install @anthropic-ai/sdk       # Anthropic
 npm install @google/generative-ai   # Gemini
 npm install better-sqlite3          # optional — only for storage: 'sqlite'
+
+# Database adapters (optional — only if using @diogonzafe/tokenwatch/adapters)
+npm install pg          # PostgreSQL
+npm install mysql2      # MySQL / MariaDB
+npm install mongodb     # MongoDB
 ```
 
 ---
@@ -28,7 +33,7 @@ import { createTracker } from '@diogonzafe/tokenwatch'
 
 const tracker = createTracker({
   // All fields are optional
-  storage: 'memory',           // 'memory' (default) | 'sqlite'
+  storage: 'memory',           // 'memory' (default) | 'sqlite' | IStorage instance
   alertThreshold: 1.00,        // USD — fires webhookUrl when exceeded
   webhookUrl: 'https://...',   // Discord / Slack webhook
   syncPrices: true,            // fetch fresh prices from GitHub (default: true)
@@ -135,8 +140,10 @@ const res = await deepseek.chat.completions.create({
 
 ## Reports
 
+All report methods are async:
+
 ```ts
-tracker.getReport()
+const report = await tracker.getReport()
 // {
 //   totalCostUSD: 0.087,
 //   totalTokens: { input: 24000, output: 6000 },
@@ -151,12 +158,12 @@ tracker.getReport()
 
 tracker.getModelInfo('gpt-4o')
 // { input: 2.5, output: 10, maxInputTokens: 128000 }
-// Returns null if the model is unknown
+// Returns null if the model is unknown (synchronous)
 
-tracker.reset()                     // clear all data
-tracker.resetSession('session_abc') // clear one session
-tracker.exportJSON()                // full report as JSON string
-tracker.exportCSV()                 // all calls as CSV string
+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 calls as CSV string
 ```
 
 ---
@@ -167,7 +174,7 @@ Prices are resolved in this priority order:
 
 1. **`customPrices`** — your own overrides, highest priority
 2. **Remote `prices.json`** — fetched from GitHub, cached for 24h in `~/.tokenwatch/prices.json`
-3. **Bundled `prices.json`** — always-present fallback, updated weekly via GitHub Action
+3. **Bundled `prices.json`** — always-present fallback, updated daily via GitHub Action
 
 If a model is not found in any layer, cost is recorded as **$0** with a `console.warn`.
 
@@ -188,11 +195,20 @@ Prices are in **USD per 1 million tokens**.
 }
 ```
 
-Prices are updated every Monday via a GitHub Action that pulls from the [LiteLLM community model registry](https://github.com/BerriAI/litellm). New models are auto-discovered — no manual updates needed.
+Prices are updated every day via a GitHub Action that pulls from the [LiteLLM community model registry](https://github.com/BerriAI/litellm). New models are auto-discovered — no manual updates needed.
 
 ---
 
-## SQLite Storage
+## Storage
+
+### In-memory (default)
+
+```ts
+const tracker = createTracker({ storage: 'memory' })
+// Resets on process restart. Good for short-lived processes and testing.
+```
+
+### SQLite
 
 For persistent tracking across restarts:
 
@@ -205,6 +221,76 @@ const tracker = createTracker({ storage: 'sqlite' })
 // Data stored in ~/.tokenwatch/usage.db
 ```
 
+### PostgreSQL
+
+```bash
+npm install pg
+```
+
+```ts
+import { Pool } from 'pg'
+import { createTracker } from '@diogonzafe/tokenwatch'
+import { PostgresStorage } from '@diogonzafe/tokenwatch/adapters'
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+const storage = new PostgresStorage(pool)
+await storage.migrate()   // creates tokenwatch_usage table if it doesn't exist
+
+const tracker = createTracker({ storage })
+```
+
+### MySQL / MariaDB
+
+```bash
+npm install mysql2
+```
+
+```ts
+import mysql from 'mysql2/promise'
+import { MySQLStorage } from '@diogonzafe/tokenwatch/adapters'
+
+const pool = mysql.createPool({ uri: process.env.MYSQL_URL })
+const storage = new MySQLStorage(pool)
+await storage.migrate()
+
+const tracker = createTracker({ storage })
+```
+
+### MongoDB
+
+```bash
+npm install mongodb
+```
+
+```ts
+import { MongoClient } from 'mongodb'
+import { MongoStorage } from '@diogonzafe/tokenwatch/adapters'
+
+const client = new MongoClient(process.env.MONGO_URL!)
+await client.connect()
+const storage = new MongoStorage(client.db('myapp'))
+await storage.createIndexes()  // optional but recommended
+
+const tracker = createTracker({ storage })
+```
+
+### Custom adapter
+
+Any object that implements `IStorage` works:
+
+```ts
+import type { IStorage, UsageEntry } from '@diogonzafe/tokenwatch'
+
+class RedisStorage implements IStorage {
+  record(entry: UsageEntry): void { /* ... */ }
+  async getAll(): Promise<UsageEntry[]> { /* ... */ }
+  async clearAll(): Promise<void> { /* ... */ }
+  async clearSession(sessionId: string): Promise<void> { /* ... */ }
+}
+
+const tracker = createTracker({ storage: new RedisStorage() })
+```
+
 ---
 
 ## Alerts & Webhooks
@@ -235,13 +321,23 @@ npx tokenwatch help     # show help
 
 ---
 
+## Privacy & Security
+
+- Prompt and response **content is never read or stored** — only token counts and model names
+- API keys are **never accessed** by tokenwatch — they remain solely in the provider client
+- SQLite, Postgres, MySQL, and MongoDB data stays **entirely in your own infrastructure** — nothing is transmitted to external services
+- The wrapper is a thin `Proxy` with **no outbound network calls** of its own (only the daily price sync script fetches external data)
+
+---
+
 ## Behaviour Guarantees
 
 - `__sessionId` and `__userId` are **stripped before** the request reaches the API
 - The response object returned is **identical** to the original SDK response
-- Tracking operations are **synchronous and non-blocking** — zero latency added
+- `track()` is **synchronous and non-blocking** — zero latency added to API calls
 - 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

@@ -0,0 +1,218 @@
+"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/adapters/index.ts
+var adapters_exports = {};
+__export(adapters_exports, {
+  MongoStorage: () => MongoStorage,
+  MySQLStorage: () => MySQLStorage,
+  PostgresStorage: () => PostgresStorage
+});
+module.exports = __toCommonJS(adapters_exports);
+
+// src/adapters/postgres.ts
+var PostgresStorage = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Creates the `tokenwatch_usage` table if it does not already exist. */
+  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
+      )
+    `);
+  }
+  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)`,
+      [
+        entry.model,
+        entry.inputTokens,
+        entry.outputTokens,
+        entry.costUSD,
+        entry.sessionId ?? null,
+        entry.userId ?? null,
+        entry.timestamp
+      ]
+    ).catch((err) => {
+      console.warn("[tokenwatch] PostgresStorage.record failed:", err);
+    });
+  }
+  async getAll() {
+    const result = await this.client.query(
+      "SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC"
+    );
+    return result.rows.map(rowToEntry);
+  }
+  async clearAll() {
+    await this.client.query("DELETE FROM tokenwatch_usage");
+  }
+  async clearSession(sessionId) {
+    await this.client.query(
+      "DELETE FROM tokenwatch_usage WHERE session_id = $1",
+      [sessionId]
+    );
+  }
+};
+function rowToEntry(r) {
+  return {
+    model: r["model"],
+    inputTokens: r["input_tokens"],
+    outputTokens: r["output_tokens"],
+    costUSD: Number(r["cost_usd"]),
+    ...r["session_id"] != null && { sessionId: r["session_id"] },
+    ...r["user_id"] != null && { userId: r["user_id"] },
+    timestamp: r["timestamp"] instanceof Date ? r["timestamp"].toISOString() : r["timestamp"]
+  };
+}
+
+// src/adapters/mysql.ts
+var MySQLStorage = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Creates the `tokenwatch_usage` table if it does not already exist. */
+  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
+      )
+    `);
+  }
+  record(entry) {
+    this.client.execute(
+      `INSERT INTO tokenwatch_usage
+         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        entry.model,
+        entry.inputTokens,
+        entry.outputTokens,
+        entry.costUSD,
+        entry.sessionId ?? null,
+        entry.userId ?? null,
+        entry.timestamp
+      ]
+    ).catch((err) => {
+      console.warn("[tokenwatch] MySQLStorage.record failed:", err);
+    });
+  }
+  async getAll() {
+    const [rows] = await this.client.execute(
+      "SELECT * FROM tokenwatch_usage ORDER BY timestamp ASC"
+    );
+    return rows.map(rowToEntry2);
+  }
+  async clearAll() {
+    await this.client.execute("DELETE FROM tokenwatch_usage");
+  }
+  async clearSession(sessionId) {
+    await this.client.execute(
+      "DELETE FROM tokenwatch_usage WHERE session_id = ?",
+      [sessionId]
+    );
+  }
+};
+function rowToEntry2(r) {
+  return {
+    model: r["model"],
+    inputTokens: r["input_tokens"],
+    outputTokens: r["output_tokens"],
+    costUSD: Number(r["cost_usd"]),
+    ...r["session_id"] != null && { sessionId: r["session_id"] },
+    ...r["user_id"] != null && { userId: r["user_id"] },
+    timestamp: r["timestamp"] instanceof Date ? r["timestamp"].toISOString() : r["timestamp"]
+  };
+}
+
+// src/adapters/mongodb.ts
+var COLLECTION = "tokenwatch_usage";
+var MongoStorage = class {
+  col;
+  constructor(db) {
+    this.col = db.collection(COLLECTION);
+  }
+  /** Creates recommended indexes for query performance. Call once at startup. */
+  async createIndexes() {
+    await this.col.createIndex({ timestamp: 1 });
+    await this.col.createIndex({ sessionId: 1 });
+    await this.col.createIndex({ userId: 1 });
+    await this.col.createIndex({ model: 1 });
+  }
+  record(entry) {
+    this.col.insertOne({
+      model: entry.model,
+      inputTokens: entry.inputTokens,
+      outputTokens: entry.outputTokens,
+      costUSD: entry.costUSD,
+      sessionId: entry.sessionId ?? null,
+      userId: entry.userId ?? null,
+      timestamp: entry.timestamp
+    }).catch((err) => {
+      console.warn("[tokenwatch] MongoStorage.record failed:", err);
+    });
+  }
+  async getAll() {
+    const docs = await this.col.find({}).toArray();
+    return docs.map(docToEntry);
+  }
+  async clearAll() {
+    await this.col.deleteMany({});
+  }
+  async clearSession(sessionId) {
+    await this.col.deleteMany({ sessionId });
+  }
+};
+function docToEntry(doc) {
+  return {
+    model: doc.model,
+    inputTokens: doc.inputTokens,
+    outputTokens: doc.outputTokens,
+    costUSD: doc.costUSD,
+    ...doc.sessionId != null && { sessionId: doc.sessionId },
+    ...doc.userId != null && { userId: doc.userId },
+    timestamp: doc.timestamp
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MongoStorage,
+  MySQLStorage,
+  PostgresStorage
+});
+//# sourceMappingURL=adapters.cjs.map

package/dist/adapters.cjs.map

@@ -0,0 +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 Collection {\n  insertOne(doc: MongoDocument): Promise<unknown>\n  find(filter: Record<string, unknown>): { toArray(): Promise<MongoDocument[]> }\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({}).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"]}

package/dist/adapters.d.cts

@@ -0,0 +1,125 @@
+import { I as IStorage, U as UsageEntry } from './index-Cy_sl3FI.cjs';
+
+/**
+ * IStorage adapter for PostgreSQL using the `pg` driver.
+ *
+ * Install peer dep:  npm install pg
+ * Types (optional):  npm install -D @types/pg
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { PostgresStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+ * const storage = new PostgresStorage(pool)
+ * await storage.migrate()          // create table if it doesn't exist
+ *
+ * const tracker = createTracker({ storage })
+ * ```
+ */
+interface QueryClient$1 {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+declare class PostgresStorage implements IStorage {
+    private readonly client;
+    constructor(client: QueryClient$1);
+    /** Creates the `tokenwatch_usage` table if it does not already exist. */
+    migrate(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * IStorage adapter for MySQL / MariaDB using the `mysql2` driver.
+ *
+ * Install peer dep:  npm install mysql2
+ *
+ * @example
+ * ```ts
+ * import mysql from 'mysql2/promise'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { MySQLStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const pool = mysql.createPool({ uri: process.env.MYSQL_URL })
+ * const storage = new MySQLStorage(pool)
+ * await storage.migrate()          // create table if it doesn't exist
+ *
+ * const tracker = createTracker({ storage })
+ * ```
+ */
+interface QueryClient {
+    execute(sql: string, values?: unknown[]): Promise<[unknown]>;
+}
+declare class MySQLStorage implements IStorage {
+    private readonly client;
+    constructor(client: QueryClient);
+    /** Creates the `tokenwatch_usage` table if it does not already exist. */
+    migrate(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * IStorage adapter for MongoDB using the official `mongodb` driver.
+ *
+ * Install peer dep:  npm install mongodb
+ *
+ * @example
+ * ```ts
+ * import { MongoClient } from 'mongodb'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { MongoStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const client = new MongoClient(process.env.MONGO_URL!)
+ * await client.connect()
+ *
+ * const storage = new MongoStorage(client.db('myapp'))
+ * const tracker = createTracker({ storage })
+ * ```
+ *
+ * Recommended index (run once at startup):
+ * ```ts
+ * await storage.createIndexes()
+ * ```
+ */
+interface MongoDocument {
+    _id?: unknown;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+    sessionId?: string | null;
+    userId?: string | null;
+    timestamp: string;
+}
+interface Collection {
+    insertOne(doc: MongoDocument): Promise<unknown>;
+    find(filter: Record<string, unknown>): {
+        toArray(): Promise<MongoDocument[]>;
+    };
+    deleteMany(filter: Record<string, unknown>): Promise<unknown>;
+    createIndex(index: Record<string, unknown>): Promise<unknown>;
+}
+interface Database {
+    collection(name: string): Collection;
+}
+declare class MongoStorage implements IStorage {
+    private readonly col;
+    constructor(db: Database);
+    /** Creates recommended indexes for query performance. Call once at startup. */
+    createIndexes(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+export { MongoStorage, MySQLStorage, PostgresStorage };

package/dist/adapters.d.ts

@@ -0,0 +1,125 @@
+import { I as IStorage, U as UsageEntry } from './index-Cy_sl3FI.js';
+
+/**
+ * IStorage adapter for PostgreSQL using the `pg` driver.
+ *
+ * Install peer dep:  npm install pg
+ * Types (optional):  npm install -D @types/pg
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { PostgresStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+ * const storage = new PostgresStorage(pool)
+ * await storage.migrate()          // create table if it doesn't exist
+ *
+ * const tracker = createTracker({ storage })
+ * ```
+ */
+interface QueryClient$1 {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+declare class PostgresStorage implements IStorage {
+    private readonly client;
+    constructor(client: QueryClient$1);
+    /** Creates the `tokenwatch_usage` table if it does not already exist. */
+    migrate(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * IStorage adapter for MySQL / MariaDB using the `mysql2` driver.
+ *
+ * Install peer dep:  npm install mysql2
+ *
+ * @example
+ * ```ts
+ * import mysql from 'mysql2/promise'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { MySQLStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const pool = mysql.createPool({ uri: process.env.MYSQL_URL })
+ * const storage = new MySQLStorage(pool)
+ * await storage.migrate()          // create table if it doesn't exist
+ *
+ * const tracker = createTracker({ storage })
+ * ```
+ */
+interface QueryClient {
+    execute(sql: string, values?: unknown[]): Promise<[unknown]>;
+}
+declare class MySQLStorage implements IStorage {
+    private readonly client;
+    constructor(client: QueryClient);
+    /** Creates the `tokenwatch_usage` table if it does not already exist. */
+    migrate(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * IStorage adapter for MongoDB using the official `mongodb` driver.
+ *
+ * Install peer dep:  npm install mongodb
+ *
+ * @example
+ * ```ts
+ * import { MongoClient } from 'mongodb'
+ * import { createTracker } from '@diogonzafe/tokenwatch'
+ * import { MongoStorage } from '@diogonzafe/tokenwatch/adapters'
+ *
+ * const client = new MongoClient(process.env.MONGO_URL!)
+ * await client.connect()
+ *
+ * const storage = new MongoStorage(client.db('myapp'))
+ * const tracker = createTracker({ storage })
+ * ```
+ *
+ * Recommended index (run once at startup):
+ * ```ts
+ * await storage.createIndexes()
+ * ```
+ */
+interface MongoDocument {
+    _id?: unknown;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+    sessionId?: string | null;
+    userId?: string | null;
+    timestamp: string;
+}
+interface Collection {
+    insertOne(doc: MongoDocument): Promise<unknown>;
+    find(filter: Record<string, unknown>): {
+        toArray(): Promise<MongoDocument[]>;
+    };
+    deleteMany(filter: Record<string, unknown>): Promise<unknown>;
+    createIndex(index: Record<string, unknown>): Promise<unknown>;
+}
+interface Database {
+    collection(name: string): Collection;
+}
+declare class MongoStorage implements IStorage {
+    private readonly col;
+    constructor(db: Database);
+    /** Creates recommended indexes for query performance. Call once at startup. */
+    createIndexes(): Promise<void>;
+    record(entry: UsageEntry): void;
+    getAll(): Promise<UsageEntry[]>;
+    clearAll(): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+
+export { MongoStorage, MySQLStorage, PostgresStorage };