@diogonzafe/tokenwatch 0.6.0 → 0.7.0

package/README.md

@@ -577,12 +577,27 @@ Anomaly webhook payload example:
 ```bash
 npx tokenwatch sync              # force update cached prices from remote
 npx tokenwatch prices            # list all models and current prices
-npx tokenwatch report            # show usage report from ~/.tokenwatch/usage.db
+npx tokenwatch report            # show usage report (SQLite default)
+npx tokenwatch report    --db postgres://user:pass@host:5432/db
 npx tokenwatch dashboard         # open local web dashboard (default port: 4242)
 npx tokenwatch dashboard --port 8080
+npx tokenwatch dashboard --db postgres://user:pass@host:5432/db
+npx tokenwatch dashboard --db mysql://user:pass@host:3306/db
+npx tokenwatch dashboard --db mongodb://user:pass@host:27017/db
 npx tokenwatch help              # show help
 ```
 
+Both `report` and `dashboard` accept a `--db <url>` flag to connect directly to any database — no SQLite required. The URL protocol determines the adapter automatically:
+
+| URL prefix | Adapter | Peer dep required |
+|---|---|---|
+| *(none)* | SQLite (`~/.tokenwatch/usage.db`) | `better-sqlite3` |
+| `postgres://` or `postgresql://` | `PostgresStorage` | `pg` |
+| `mysql://` | `MySQLStorage` | `mysql2` |
+| `mongodb://` or `mongodb+srv://` | `MongoStorage` | `mongodb` |
+
+If the required peer dep is not installed, a clear error message with the install command is shown.
+
 ### `tokenwatch report`
 
 Reads the local SQLite database and prints:
@@ -617,7 +632,16 @@ Spins up a local web server and opens a dark-themed dashboard with real-time cos
 - **Cost forecast** — projected daily and monthly spend based on recent burn rate
 - **Time filter tabs** — 1h | 24h | 7d | 30d | All; updates chart and tables in real-time via SSE
 
-Data updates automatically every 3 seconds without refreshing the page. Requires `storage: 'sqlite'` in your app and `better-sqlite3` installed. Zero external dependencies — pure Node.js HTTP server with Chart.js loaded from CDN.
+Data updates automatically every 3 seconds without refreshing the page. Zero external dependencies — pure Node.js HTTP server with Chart.js loaded from CDN.
+
+Works with **any storage backend** via `--db <url>`:
+
+```bash
+tokenwatch dashboard                                         # SQLite (default)
+tokenwatch dashboard --db postgres://user:pass@host:5432/db  # PostgreSQL
+tokenwatch dashboard --db mysql://user:pass@host:3306/db     # MySQL
+tokenwatch dashboard --db mongodb://user:pass@host:27017/db  # MongoDB
+```
 
 ---
 

package/dist/cli.js

@@ -1,4 +1,286 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/adapters/postgres.ts
+var postgres_exports = {};
+__export(postgres_exports, {
+  PostgresStorage: () => PostgresStorage
+});
+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"]
+  };
+}
+var PostgresStorage;
+var init_postgres = __esm({
+  "src/adapters/postgres.ts"() {
+    "use strict";
+    PostgresStorage = class {
+      constructor(client) {
+        this.client = client;
+      }
+      client;
+      /** 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,
+        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, 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) => {
+          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]
+        );
+      }
+    };
+  }
+});
+
+// src/adapters/mysql.ts
+var mysql_exports = {};
+__export(mysql_exports, {
+  MySQLStorage: () => MySQLStorage
+});
+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"]
+  };
+}
+var MySQLStorage;
+var init_mysql = __esm({
+  "src/adapters/mysql.ts"() {
+    "use strict";
+    MySQLStorage = class {
+      constructor(client) {
+        this.client = client;
+      }
+      client;
+      /** 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,
+        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, 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) => {
+          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]
+        );
+      }
+    };
+  }
+});
+
+// src/adapters/mongodb.ts
+var mongodb_exports = {};
+__export(mongodb_exports, {
+  MongoStorage: () => MongoStorage
+});
+function docToEntry(doc) {
+  return {
+    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
+  };
+}
+var COLLECTION, MongoStorage;
+var init_mongodb = __esm({
+  "src/adapters/mongodb.ts"() {
+    "use strict";
+    COLLECTION = "tokenwatch_usage";
+    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,
+          ...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);
+        });
+      }
+      async getAll() {
+        const docs = await this.col.find({}).sort({ timestamp: 1 }).toArray();
+        return docs.map(docToEntry);
+      }
+      async clearAll() {
+        await this.col.deleteMany({});
+      }
+      async clearSession(sessionId) {
+        await this.col.deleteMany({ sessionId });
+      }
+    };
+  }
+});
 
 // bin/cli.ts
 import { readFileSync, existsSync as existsSync2 } from "fs";
@@ -245,7 +527,7 @@ function maybeSuggestCheaperModel(model, costUSD, inputTokens, outputTokens, lay
 
 // prices.json
 var prices_default = {
-  updated_at: "2026-04-23",
+  updated_at: "2026-04-24",
   source: "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
   models: {
     "gpt-4o": {
@@ -1562,6 +1844,12 @@ var prices_default = {
       cachedInput: 0.3,
       cacheCreationInput: 3.75,
       maxInputTokens: 1e6
+    },
+    "gpt-5.5": {
+      input: 5,
+      output: 30,
+      cachedInput: 0.5,
+      maxInputTokens: 272e3
     }
   }
 };
@@ -2746,7 +3034,82 @@ function startDashboardServer(storage, port) {
 
 // bin/cli.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var DB_PATH2 = join3(homedir3(), ".tokenwatch", "usage.db");
+var DEFAULT_DB_PATH = join3(homedir3(), ".tokenwatch", "usage.db");
+function getFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return void 0;
+  const value = args[idx + 1];
+  return value !== void 0 && !value.startsWith("--") ? value : void 0;
+}
+async function openStorage(dbUrl) {
+  if (!dbUrl) {
+    if (!existsSync2(DEFAULT_DB_PATH)) {
+      console.error(`No SQLite database found at ${DEFAULT_DB_PATH}`);
+      console.error("Start your app with storage: 'sqlite' to begin recording usage.");
+      console.error("Or pass --db <url> to connect to Postgres, MySQL, or MongoDB.");
+      process.exit(1);
+    }
+    let storage;
+    try {
+      storage = new SqliteStorage(DEFAULT_DB_PATH);
+    } catch {
+      console.error("Failed to open SQLite database. Is better-sqlite3 installed?");
+      console.error("Run: npm install better-sqlite3");
+      process.exit(1);
+    }
+    return { storage, close: async () => {
+    } };
+  }
+  if (dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://")) {
+    let pgMod;
+    try {
+      pgMod = (await import("pg")).default;
+    } catch {
+      console.error("[tokenwatch] Postgres requires the pg package.");
+      console.error("Run: npm install pg");
+      process.exit(1);
+    }
+    const { PostgresStorage: PostgresStorage2 } = await Promise.resolve().then(() => (init_postgres(), postgres_exports));
+    const pool = new pgMod.Pool({ connectionString: dbUrl });
+    const storage = new PostgresStorage2(pool);
+    return { storage, close: () => pool.end() };
+  }
+  if (dbUrl.startsWith("mysql://")) {
+    let mysqlMod;
+    try {
+      mysqlMod = await import("mysql2/promise");
+    } catch {
+      console.error("[tokenwatch] MySQL requires the mysql2 package.");
+      console.error("Run: npm install mysql2");
+      process.exit(1);
+    }
+    const { MySQLStorage: MySQLStorage2 } = await Promise.resolve().then(() => (init_mysql(), mysql_exports));
+    const pool = mysqlMod.createPool(dbUrl);
+    const storage = new MySQLStorage2(pool);
+    return { storage, close: () => pool.end() };
+  }
+  if (dbUrl.startsWith("mongodb://") || dbUrl.startsWith("mongodb+srv://")) {
+    let mongoMod;
+    try {
+      mongoMod = await import("mongodb");
+    } catch {
+      console.error("[tokenwatch] MongoDB requires the mongodb package.");
+      console.error("Run: npm install mongodb");
+      process.exit(1);
+    }
+    const { MongoStorage: MongoStorage2 } = await Promise.resolve().then(() => (init_mongodb(), mongodb_exports));
+    const urlObj = new URL(dbUrl);
+    const dbName = urlObj.pathname.replace(/^\//, "") || "tokenwatch";
+    const client = new mongoMod.MongoClient(dbUrl);
+    await client.connect();
+    const db = client.db(dbName);
+    const storage = new MongoStorage2(db);
+    return { storage, close: () => client.close() };
+  }
+  console.error(`[tokenwatch] Unsupported database URL: "${dbUrl}"`);
+  console.error("Supported protocols: postgres://, mysql://, mongodb://, mongodb+srv://");
+  process.exit(1);
+}
 function loadBundledPrices() {
   const pricesPath = join3(__dirname, "..", "prices.json");
   const raw = readFileSync(pricesPath, "utf8");
@@ -2779,22 +3142,16 @@ function cmdPrices() {
     console.log(`${row.model.padEnd(maxName)}  ${row.input.padStart(12)}  ${row.output.padStart(12)}`);
   }
 }
-async function cmdReport() {
-  if (!existsSync2(DB_PATH2)) {
-    console.log(`No SQLite database found at ${DB_PATH2}`);
-    console.log("Start your app with storage: 'sqlite' to begin recording usage.");
-    return;
-  }
-  let storage;
+async function cmdReport(args) {
+  const dbUrl = getFlag(args, "--db");
+  const { storage, close } = await openStorage(dbUrl);
+  let report;
   try {
-    storage = new SqliteStorage(DB_PATH2);
-  } catch {
-    console.error("Failed to open SQLite database. Is better-sqlite3 installed?");
-    console.error("Run: npm install better-sqlite3");
-    process.exit(1);
+    const tracker = createTracker({ storage, syncPrices: false });
+    report = await tracker.getReport();
+  } finally {
+    await close();
   }
-  const tracker = createTracker({ storage, syncPrices: false });
-  const report = await tracker.getReport();
   if (report.totalCostUSD === 0 && Object.keys(report.byModel).length === 0) {
     console.log("No usage recorded yet.");
     return;
@@ -2832,20 +3189,20 @@ async function cmdReport() {
   }
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
 }
-async function cmdDashboard(port) {
-  if (!existsSync2(DB_PATH2)) {
-    console.log(`No SQLite database found at ${DB_PATH2}`);
-    console.log("Start your app with storage: 'sqlite' to begin recording usage.");
-    process.exit(1);
-  }
-  let storage;
-  try {
-    storage = new SqliteStorage(DB_PATH2);
-  } catch {
-    console.error("Failed to open SQLite database. Is better-sqlite3 installed?");
-    console.error("Run: npm install better-sqlite3");
+async function cmdDashboard(args) {
+  const portFlag = getFlag(args, "--port");
+  const port = portFlag !== void 0 ? parseInt(portFlag, 10) : 4242;
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(`[tokenwatch] Invalid port: "${portFlag}". Must be a number between 1 and 65535.`);
     process.exit(1);
   }
+  const dbUrl = getFlag(args, "--db");
+  const { storage, close } = await openStorage(dbUrl);
+  const shutdown = () => {
+    void close().then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
   startDashboardServer(storage, port);
 }
 function cmdHelp() {
@@ -2853,11 +3210,23 @@ function cmdHelp() {
 tokenwatch \u2014 CLI
 
 Commands:
-  sync                  Fetch and cache latest model prices from remote
-  prices                List all bundled models and their current prices
-  report                Show last saved usage report (requires SQLite storage)
-  dashboard [--port N]  Open local web dashboard (default port: 4242)
-  help                  Show this help message
+  sync                        Fetch and cache latest model prices from remote
+  prices                      List all bundled models and their current prices
+  report [--db <url>]         Show usage report (default: SQLite at ~/.tokenwatch/usage.db)
+  dashboard [--port N]        Open local web dashboard (default port: 4242)
+            [--db <url>]      Connect to a database instead of the default SQLite
+
+Database URL formats:
+  (none)                      ~/.tokenwatch/usage.db  (SQLite, default)
+  postgres://user:pass@host:5432/dbname
+  mysql://user:pass@host:3306/dbname
+  mongodb://user:pass@host:27017/dbname
+
+Examples:
+  tokenwatch dashboard
+  tokenwatch dashboard --port 8080
+  tokenwatch dashboard --db postgres://user:pass@localhost:5432/myapp
+  tokenwatch report --db mysql://root:pass@localhost:3306/myapp
 `.trim());
 }
 async function main() {
@@ -2870,14 +3239,11 @@ async function main() {
       cmdPrices();
       break;
     case "report":
-      await cmdReport();
+      await cmdReport(args);
       break;
-    case "dashboard": {
-      const portFlagIdx = args.indexOf("--port");
-      const port = portFlagIdx !== -1 ? parseInt(args[portFlagIdx + 1] ?? "4242", 10) : 4242;
-      await cmdDashboard(port);
+    case "dashboard":
+      await cmdDashboard(args);
       break;
-    }
     case "help":
     case void 0:
       cmdHelp();