@diogonzafe/tokenwatch 0.9.0 → 0.10.0

package/dist/exporters.d.cts

@@ -1,4 +1,4 @@
-import { I as IExporter, U as UsageEntry } from './index-fD5QLTWg.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-fD5QLTWg.js';
+import { I as IExporter, U as UsageEntry } from './index-B5OF0YCl.js';
 
 interface OTelAttributes {
     [key: string]: string | number | boolean | undefined;

package/dist/{index-fD5QLTWg.d.cts → index-B5OF0YCl.d.cts}

@@ -90,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 {
@@ -137,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;
@@ -192,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-fD5QLTWg.d.ts → index-B5OF0YCl.d.ts}

@@ -90,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 {
@@ -137,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;
@@ -192,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

@@ -91,6 +91,7 @@ var CloudExporter = class {
         sessionId: entry.sessionId,
         userId: entry.userId,
         feature: entry.feature,
+        metadata: entry.metadata,
         timestamp: entry.timestamp
       })
     }).catch(() => {
@@ -189,6 +190,7 @@ var SqliteStorage = class {
         user_id               TEXT,
         feature               TEXT,
         app_id                TEXT,
+        metadata              TEXT,
         timestamp             TEXT    NOT NULL
       )
     `);
@@ -208,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,
@@ -227,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
     );
   }
@@ -244,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
     }));
   }
@@ -1931,6 +1938,7 @@ ${issues}`);
     const byUser = {};
     const byFeature = {};
     const byApp = {};
+    const byMetadata = {};
     let totalInput = 0;
     let totalOutput = 0;
     let totalCost = 0;
@@ -1972,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;
@@ -1984,6 +2000,7 @@ ${issues}`);
       byUser,
       byFeature,
       byApp,
+      byMetadata,
       period: { from: periodFrom, to: lastTimestamp },
       ...pricesUpdatedAt ? { pricesUpdatedAt } : {}
     };
@@ -2088,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),
@@ -2102,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");
@@ -2174,6 +2192,7 @@ function emptyReport() {
     byUser: {},
     byFeature: {},
     byApp: {},
+    byMetadata: {},
     period: { from: now, to: now }
   };
 }
@@ -2230,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) {
@@ -2250,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,
@@ -2259,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;
@@ -2274,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, {
@@ -2282,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) {
@@ -2292,7 +2313,8 @@ function wrapOpenAI(client, tracker) {
             sessionId,
             userId,
             feature,
-            tracker
+            tracker,
+            metadata
           );
         }
         const completion = result;
@@ -2306,7 +2328,8 @@ function wrapOpenAI(client, tracker) {
           sessionId,
           userId,
           feature,
-          cachedTokens
+          cachedTokens,
+          metadata
         );
         return result;
       };
@@ -2323,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;
       };
     }
@@ -2344,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) {
@@ -2366,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,
@@ -2376,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;
@@ -2407,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, {
@@ -2415,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) {
@@ -2425,7 +2450,8 @@ function wrapAnthropic(client, tracker) {
             sessionId,
             userId,
             feature,
-            tracker
+            tracker,
+            metadata
           );
         }
         const message = result;
@@ -2441,7 +2467,8 @@ function wrapAnthropic(client, tracker) {
           userId,
           feature,
           cachedTokens,
-          cacheCreationTokens
+          cacheCreationTokens,
+          metadata
         );
         return result;
       };
@@ -2462,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, {
@@ -2480,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;
               };
@@ -2496,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(() => {
                 });