@diogonzafe/tokenwatch 0.8.0 → 0.10.0

package/dist/exporters.d.cts

@@ -1,4 +1,4 @@
-import { I as IExporter, U as UsageEntry } from './index-CFBI-1ab.cjs';
+import { I as IExporter, U as UsageEntry } from './index-B5OF0YCl.cjs';
 
 interface OTelAttributes {
     [key: string]: string | number | boolean | undefined;

package/dist/exporters.d.ts

@@ -1,4 +1,4 @@
-import { I as IExporter, U as UsageEntry } from './index-CFBI-1ab.js';
+import { I as IExporter, U as UsageEntry } from './index-B5OF0YCl.js';
 
 interface OTelAttributes {
     [key: string]: string | number | boolean | undefined;

package/dist/{index-CFBI-1ab.d.cts → index-B5OF0YCl.d.cts}

@@ -65,6 +65,10 @@ interface TrackerConfig {
     anomalyDetection?: AnomalyDetectionConfig;
     /** Custom exporter called after every tracked call (e.g. OTelExporter) */
     exporter?: IExporter;
+    /** TokenWatch Cloud API key — mirrors every tracked call to the cloud dashboard (fire-and-forget) */
+    cloudApiKey?: string;
+    /** Override the cloud ingest endpoint (default: https://api.tokenwatch.dev/v1/ingest) */
+    cloudEndpoint?: string;
 }
 interface UsageEntry {
     model: string;
@@ -86,6 +90,8 @@ interface UsageEntry {
     feature?: string;
     /** Application identifier — set once in TrackerConfig.appId and stamped on every entry */
     appId?: string;
+    /** Arbitrary key-value tags for custom dimensions (e.g. tenantId, region, plan) */
+    metadata?: Record<string, string>;
     timestamp: string;
 }
 interface ModelStats {
@@ -133,6 +139,11 @@ interface Report {
     byUser: Record<string, UserStats>;
     byFeature: Record<string, FeatureStats>;
     byApp: Record<string, AppStats>;
+    /** Grouped by each custom metadata key → value → stats */
+    byMetadata: Record<string, Record<string, {
+        costUSD: number;
+        calls: number;
+    }>>;
     period: {
         from: string;
         to: string;
@@ -188,6 +199,8 @@ interface TrackingMeta {
     __feature?: string;
     /** Override the tracker-level appId for this specific call */
     __appId?: string;
+    /** Arbitrary key-value tags for custom dimensions — appear in report.byMetadata */
+    __metadata?: Record<string, string>;
 }
 
 export type { AnomalyDetectionConfig as A, BudgetConfig as B, CostForecast as C, FeatureStats as F, IExporter as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, IStorage as d, ModelStats as e, PricesFile as f, ReportOptions as g, UserStats as h };

package/dist/{index-CFBI-1ab.d.ts → index-B5OF0YCl.d.ts}

@@ -65,6 +65,10 @@ interface TrackerConfig {
     anomalyDetection?: AnomalyDetectionConfig;
     /** Custom exporter called after every tracked call (e.g. OTelExporter) */
     exporter?: IExporter;
+    /** TokenWatch Cloud API key — mirrors every tracked call to the cloud dashboard (fire-and-forget) */
+    cloudApiKey?: string;
+    /** Override the cloud ingest endpoint (default: https://api.tokenwatch.dev/v1/ingest) */
+    cloudEndpoint?: string;
 }
 interface UsageEntry {
     model: string;
@@ -86,6 +90,8 @@ interface UsageEntry {
     feature?: string;
     /** Application identifier — set once in TrackerConfig.appId and stamped on every entry */
     appId?: string;
+    /** Arbitrary key-value tags for custom dimensions (e.g. tenantId, region, plan) */
+    metadata?: Record<string, string>;
     timestamp: string;
 }
 interface ModelStats {
@@ -133,6 +139,11 @@ interface Report {
     byUser: Record<string, UserStats>;
     byFeature: Record<string, FeatureStats>;
     byApp: Record<string, AppStats>;
+    /** Grouped by each custom metadata key → value → stats */
+    byMetadata: Record<string, Record<string, {
+        costUSD: number;
+        calls: number;
+    }>>;
     period: {
         from: string;
         to: string;
@@ -188,6 +199,8 @@ interface TrackingMeta {
     __feature?: string;
     /** Override the tracker-level appId for this specific call */
     __appId?: string;
+    /** Arbitrary key-value tags for custom dimensions — appear in report.byMetadata */
+    __metadata?: Record<string, string>;
 }
 
 export type { AnomalyDetectionConfig as A, BudgetConfig as B, CostForecast as C, FeatureStats as F, IExporter as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, IStorage as d, ModelStats as e, PricesFile as f, ReportOptions as g, UserStats as h };

package/dist/index.cjs

@@ -64,6 +64,41 @@ function calculateCost(inputTokens, outputTokens, price, cachedTokens = 0, cache
   return regularInputCost + cachedReadCost + cacheCreationCost + outputCost;
 }
 
+// src/exporters/cloud.ts
+var DEFAULT_ENDPOINT = "https://api.tokenwatch.dev/v1/ingest";
+var CloudExporter = class {
+  constructor(apiKey, endpoint) {
+    this.apiKey = apiKey;
+    this.endpoint = endpoint ?? DEFAULT_ENDPOINT;
+  }
+  apiKey;
+  endpoint;
+  export(entry) {
+    fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        model: entry.model,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        reasoningTokens: entry.reasoningTokens ?? 0,
+        cachedTokens: entry.cachedTokens ?? 0,
+        cacheCreationTokens: entry.cacheCreationTokens ?? 0,
+        costUSD: entry.costUSD,
+        sessionId: entry.sessionId,
+        userId: entry.userId,
+        feature: entry.feature,
+        metadata: entry.metadata,
+        timestamp: entry.timestamp
+      })
+    }).catch(() => {
+    });
+  }
+};
+
 // src/core/suggestions.ts
 var PROVIDER_PREFIXES = ["gpt-", "claude-", "gemini-", "deepseek-"];
 function getProviderPrefix(model) {
@@ -155,6 +190,7 @@ var SqliteStorage = class {
         user_id               TEXT,
         feature               TEXT,
         app_id                TEXT,
+        metadata              TEXT,
         timestamp             TEXT    NOT NULL
       )
     `);
@@ -174,13 +210,16 @@ var SqliteStorage = class {
     if (!cols.includes("app_id")) {
       this.db.exec(`ALTER TABLE usage ADD COLUMN app_id TEXT`);
     }
+    if (!cols.includes("metadata")) {
+      this.db.exec(`ALTER TABLE usage ADD COLUMN metadata TEXT`);
+    }
   }
   record(entry) {
     this.db.prepare(
       `INSERT INTO usage
          (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,
-          cost_usd, session_id, user_id, feature, app_id, timestamp)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          cost_usd, session_id, user_id, feature, app_id, metadata, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       entry.model,
       entry.inputTokens,
@@ -193,6 +232,7 @@ var SqliteStorage = class {
       entry.userId ?? null,
       entry.feature ?? null,
       entry.appId ?? null,
+      entry.metadata != null ? JSON.stringify(entry.metadata) : null,
       entry.timestamp
     );
   }
@@ -210,6 +250,7 @@ var SqliteStorage = class {
       ...r.user_id != null && { userId: r.user_id },
       ...r.feature != null && { feature: r.feature },
       ...r.app_id != null && { appId: r.app_id },
+      ...r.metadata != null && { metadata: JSON.parse(r.metadata) },
       timestamp: r.timestamp
     }));
   }
@@ -1725,7 +1766,9 @@ var TrackerConfigSchema = import_zod.z.object({
     mode: import_zod.z.enum(["once", "always"]).optional().default("once")
   }).optional(),
   exporter: import_zod.z.custom((v) => v !== null && typeof v === "object" && typeof v.export === "function").optional(),
-  appId: import_zod.z.string().optional()
+  appId: import_zod.z.string().optional(),
+  cloudApiKey: import_zod.z.string().optional(),
+  cloudEndpoint: import_zod.z.string().url().optional()
 });
 function createTracker(config = {}) {
   const parsed = TrackerConfigSchema.safeParse(config);
@@ -1745,9 +1788,12 @@ ${issues}`);
     suggestions,
     anomalyDetection,
     exporter,
-    appId
+    appId,
+    cloudApiKey,
+    cloudEndpoint
   } = parsed.data;
   const storage = typeof storageOption === "object" ? storageOption : createStorage(storageOption);
+  const cloudExporter = cloudApiKey ? new CloudExporter(cloudApiKey, cloudEndpoint) : null;
   let remotePrices;
   let pricesUpdatedAt = bundledUpdatedAt;
   if (syncPrices) {
@@ -1808,6 +1854,9 @@ ${issues}`);
       Promise.resolve(exporter.export(full)).catch(() => {
       });
     }
+    if (cloudExporter) {
+      cloudExporter.export(full);
+    }
     maybeFireAlerts(full);
     if (anomalyDetection) maybeDetectAnomaly(full);
     if (suggestions) {
@@ -1889,6 +1938,7 @@ ${issues}`);
     const byUser = {};
     const byFeature = {};
     const byApp = {};
+    const byMetadata = {};
     let totalInput = 0;
     let totalOutput = 0;
     let totalCost = 0;
@@ -1930,6 +1980,14 @@ ${issues}`);
         a.costUSD += e.costUSD;
         a.calls += 1;
       }
+      if (e.metadata) {
+        for (const [key, val] of Object.entries(e.metadata)) {
+          const group = byMetadata[key] ??= {};
+          const slot = group[val] ??= { costUSD: 0, calls: 0 };
+          slot.costUSD += e.costUSD;
+          slot.calls += 1;
+        }
+      }
     }
     if (options && entries.length > 0) {
       periodFrom = entries[0]?.timestamp ?? periodFrom;
@@ -1942,6 +2000,7 @@ ${issues}`);
       byUser,
       byFeature,
       byApp,
+      byMetadata,
       period: { from: periodFrom, to: lastTimestamp },
       ...pricesUpdatedAt ? { pricesUpdatedAt } : {}
     };
@@ -2046,7 +2105,7 @@ ${issues}`);
   }
   async function exportCSV() {
     const entries = await Promise.resolve(storage.getAll());
-    const header = "timestamp,model,inputTokens,outputTokens,reasoningTokens,cachedTokens,cacheCreationTokens,costUSD,sessionId,userId,feature,appId";
+    const header = "timestamp,model,inputTokens,outputTokens,reasoningTokens,cachedTokens,cacheCreationTokens,costUSD,sessionId,userId,feature,appId,metadata";
     const rows = entries.map(
       (e) => [
         csvEscape(e.timestamp),
@@ -2060,7 +2119,8 @@ ${issues}`);
         csvEscape(e.sessionId ?? ""),
         csvEscape(e.userId ?? ""),
         csvEscape(e.feature ?? ""),
-        csvEscape(e.appId ?? "")
+        csvEscape(e.appId ?? ""),
+        csvEscape(e.metadata ? JSON.stringify(e.metadata) : "")
       ].join(",")
     );
     return [header, ...rows].join("\n");
@@ -2132,6 +2192,7 @@ function emptyReport() {
     byUser: {},
     byFeature: {},
     byApp: {},
+    byMetadata: {},
     period: { from: now, to: now }
   };
 }
@@ -2188,12 +2249,13 @@ function createLazyTracker() {
 
 // src/providers/openai.ts
 function extractMeta(params) {
-  const { __sessionId, __userId, __feature, ...cleaned } = params;
+  const { __sessionId, __userId, __feature, __metadata, ...cleaned } = params;
   return {
     cleaned,
     sessionId: typeof __sessionId === "string" ? __sessionId : void 0,
     userId: typeof __userId === "string" ? __userId : void 0,
-    feature: typeof __feature === "string" ? __feature : void 0
+    feature: typeof __feature === "string" ? __feature : void 0,
+    metadata: __metadata != null && typeof __metadata === "object" ? __metadata : void 0
   };
 }
 function extractUsage(usage) {
@@ -2208,7 +2270,7 @@ function extractUsage(usage) {
     cachedTokens
   };
 }
-function trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0) {
+function trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0, metadata) {
   tracker.track({
     model,
     inputTokens,
@@ -2217,10 +2279,11 @@ function trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningToken
     ...cachedTokens > 0 && { cachedTokens },
     ...sessionId !== void 0 && { sessionId },
     ...userId !== void 0 && { userId },
-    ...feature !== void 0 && { feature }
+    ...feature !== void 0 && { feature },
+    ...metadata !== void 0 && { metadata }
   });
 }
-async function* wrapStream(stream, model, sessionId, userId, feature, tracker) {
+async function* wrapStream(stream, model, sessionId, userId, feature, tracker, metadata) {
   let lastChunk;
   for await (const chunk of stream) {
     lastChunk = chunk;
@@ -2232,7 +2295,7 @@ async function* wrapStream(stream, model, sessionId, userId, feature, tracker) {
       `[tokenwatch] No usage data in stream for model "${model}". Cost recorded as $0. Pass stream_options: { include_usage: true } to get accurate costs.`
     );
   }
-  trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens);
+  trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens, metadata);
 }
 function wrapOpenAI(client, tracker) {
   const proxiedCompletions = new Proxy(client.chat.completions, {
@@ -2240,7 +2303,7 @@ function wrapOpenAI(client, tracker) {
       if (prop !== "create")
         return target[prop];
       return async function(params) {
-        const { cleaned, sessionId, userId, feature } = extractMeta(params);
+        const { cleaned, sessionId, userId, feature, metadata } = extractMeta(params);
         const model = typeof cleaned["model"] === "string" ? cleaned["model"] : "unknown";
         const result = await target.create(cleaned);
         if (result && typeof result === "object" && Symbol.asyncIterator in result) {
@@ -2250,7 +2313,8 @@ function wrapOpenAI(client, tracker) {
             sessionId,
             userId,
             feature,
-            tracker
+            tracker,
+            metadata
           );
         }
         const completion = result;
@@ -2264,7 +2328,8 @@ function wrapOpenAI(client, tracker) {
           sessionId,
           userId,
           feature,
-          cachedTokens
+          cachedTokens,
+          metadata
         );
         return result;
       };
@@ -2281,12 +2346,12 @@ function wrapOpenAI(client, tracker) {
       if (prop !== "create")
         return target[prop];
       return async function(params) {
-        const { cleaned, sessionId, userId, feature } = extractMeta(params);
+        const { cleaned, sessionId, userId, feature, metadata } = extractMeta(params);
         const model = typeof cleaned["model"] === "string" ? cleaned["model"] : "unknown";
         const result = await target.create(cleaned);
         const embedding = result;
         const inputTokens = embedding.usage?.total_tokens ?? 0;
-        trackWithMeta(tracker, embedding.model ?? model, inputTokens, 0, 0, sessionId, userId, feature);
+        trackWithMeta(tracker, embedding.model ?? model, inputTokens, 0, 0, sessionId, userId, feature, 0, metadata);
         return result;
       };
     }
@@ -2302,12 +2367,13 @@ function wrapOpenAI(client, tracker) {
 
 // src/providers/anthropic.ts
 function extractMeta2(params) {
-  const { __sessionId, __userId, __feature, ...cleaned } = params;
+  const { __sessionId, __userId, __feature, __metadata, ...cleaned } = params;
   return {
     cleaned,
     sessionId: typeof __sessionId === "string" ? __sessionId : void 0,
     userId: typeof __userId === "string" ? __userId : void 0,
-    feature: typeof __feature === "string" ? __feature : void 0
+    feature: typeof __feature === "string" ? __feature : void 0,
+    metadata: __metadata != null && typeof __metadata === "object" ? __metadata : void 0
   };
 }
 function extractUsage2(usage) {
@@ -2324,7 +2390,7 @@ function extractThinkingTokenApprox(content) {
   const chars = content.filter((b) => b.type === "thinking").reduce((sum, b) => sum + (b.thinking?.length ?? 0), 0);
   return chars > 0 ? Math.round(chars / 4) : 0;
 }
-function trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0, cacheCreationTokens = 0) {
+function trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0, cacheCreationTokens = 0, metadata) {
   tracker.track({
     model,
     inputTokens,
@@ -2334,10 +2400,11 @@ function trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningToke
     ...cacheCreationTokens > 0 && { cacheCreationTokens },
     ...sessionId !== void 0 && { sessionId },
     ...userId !== void 0 && { userId },
-    ...feature !== void 0 && { feature }
+    ...feature !== void 0 && { feature },
+    ...metadata !== void 0 && { metadata }
   });
 }
-async function* wrapStream2(stream, model, sessionId, userId, feature, tracker) {
+async function* wrapStream2(stream, model, sessionId, userId, feature, tracker, metadata) {
   let inputTokens = 0;
   let outputTokens = 0;
   let cachedTokens = 0;
@@ -2365,7 +2432,7 @@ async function* wrapStream2(stream, model, sessionId, userId, feature, tracker)
     }
   }
   const reasoningTokens = thinkingCharCount > 0 ? Math.round(thinkingCharCount / 4) : 0;
-  trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens, cacheCreationTokens);
+  trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens, cacheCreationTokens, metadata);
 }
 function wrapAnthropic(client, tracker) {
   const proxiedMessages = new Proxy(client.messages, {
@@ -2373,7 +2440,7 @@ function wrapAnthropic(client, tracker) {
       if (prop !== "create")
         return target[prop];
       return async function(params) {
-        const { cleaned, sessionId, userId, feature } = extractMeta2(params);
+        const { cleaned, sessionId, userId, feature, metadata } = extractMeta2(params);
         const model = typeof cleaned["model"] === "string" ? cleaned["model"] : "unknown";
         const result = await target.create(cleaned);
         if (result && typeof result === "object" && Symbol.asyncIterator in result) {
@@ -2383,7 +2450,8 @@ function wrapAnthropic(client, tracker) {
             sessionId,
             userId,
             feature,
-            tracker
+            tracker,
+            metadata
           );
         }
         const message = result;
@@ -2399,7 +2467,8 @@ function wrapAnthropic(client, tracker) {
           userId,
           feature,
           cachedTokens,
-          cacheCreationTokens
+          cacheCreationTokens,
+          metadata
         );
         return result;
       };
@@ -2420,10 +2489,11 @@ function wrapGemini(client, tracker) {
       if (prop !== "getGenerativeModel")
         return target[prop];
       return function(modelParams) {
-        const { __sessionId, __userId, __feature, ...cleanedParams } = modelParams;
+        const { __sessionId, __userId, __feature, __metadata, ...cleanedParams } = modelParams;
         const feature = typeof __feature === "string" ? __feature : void 0;
         const sessionId = typeof __sessionId === "string" ? __sessionId : void 0;
         const userId = typeof __userId === "string" ? __userId : void 0;
+        const metadata = __metadata != null && typeof __metadata === "object" ? __metadata : void 0;
         const modelInstance = target.getGenerativeModel(cleanedParams);
         const modelId = modelParams.model;
         return new Proxy(modelInstance, {
@@ -2438,7 +2508,8 @@ function wrapGemini(client, tracker) {
                   outputTokens: meta?.candidatesTokenCount ?? 0,
                   ...sessionId !== void 0 && { sessionId },
                   ...userId !== void 0 && { userId },
-                  ...feature !== void 0 && { feature }
+                  ...feature !== void 0 && { feature },
+                  ...metadata !== void 0 && { metadata }
                 });
                 return result;
               };
@@ -2454,7 +2525,8 @@ function wrapGemini(client, tracker) {
                     outputTokens: meta?.candidatesTokenCount ?? 0,
                     ...sessionId !== void 0 && { sessionId },
                     ...userId !== void 0 && { userId },
-                    ...feature !== void 0 && { feature }
+                    ...feature !== void 0 && { feature },
+                    ...metadata !== void 0 && { metadata }
                   });
                 }).catch(() => {
                 });