Feat/ai metadata

packages/scrawn/src/core/ai/track.ts

@@ -20,7 +20,8 @@ export function buildAIPayload<TTag extends string = string>(
     inputCacheDebit: Debit<TTag>;
     outputCacheDebit: Debit<TTag>;
     provider?: string;
-  }
+  },
+  metadata?: Record<string, unknown>
 ): AITokenUsagePayload<TTag> {
   return {
     userId,
@@ -30,6 +31,7 @@ export function buildAIPayload<TTag extends string = string>(
     inputDebit: overrides.inputDebit ?? defaults.inputDebit,
     outputDebit: overrides.outputDebit ?? defaults.outputDebit,
     provider: overrides.provider ?? defaults.provider ?? model.provider,
+    metadata,
     inputCacheTokens: usage.inputCachedTokens,
     inputCacheDebit: overrides.inputCacheDebit ?? defaults.inputCacheDebit,
     outputCacheTokens: usage.outputCachedTokens,

packages/scrawn/src/core/ai/types.ts

@@ -24,6 +24,8 @@ export interface BillableAIOptions<TTag extends string = string> {
 export interface BillableCallParams<TTag extends string = string> {
   /** The user ID to bill against. If omitted, billing is skipped. */
   userId?: string;
+  /** Arbitrary metadata to associate with the event. */
+  metadata?: Record<string, unknown>;
   /** Override input token billing for this specific call. */
   inputDebit?: Debit<TTag>;
   /** Override output token billing for this specific call. */

packages/scrawn/src/core/ai/wrap.ts

@@ -91,6 +91,7 @@ export function createBillableAI<TTag extends string>(
           outputCacheDebit:
             billing.outputCacheDebit ?? defaults.outputCacheDebit,
           provider: billing.provider ?? defaults.provider,
+          metadata: billing.metadata,
         });
       };
 
@@ -123,6 +124,8 @@ function extractBillingParams<TTag extends string>(
       params.inputCacheDebit as BillableCallParams<TTag>["inputCacheDebit"],
     outputCacheDebit:
       params.outputCacheDebit as BillableCallParams<TTag>["outputCacheDebit"],
+    provider: params.provider as string | undefined,
+    metadata: params.metadata as Record<string, unknown> | undefined,
   };
 }
 

packages/scrawn/src/core/scrawn.ts

@@ -1238,6 +1238,7 @@ export class Scrawn<
     inputCacheDebit?: Debit<TTags>;
     outputCacheDebit?: Debit<TTags>;
     provider?: string;
+    metadata?: Record<string, unknown>;
   }): void {
     const {
       userId,
@@ -1247,6 +1248,7 @@ export class Scrawn<
       inputCacheDebit,
       outputCacheDebit,
       provider,
+      metadata,
     } = config;
     const usage = event.usage ?? event.totalUsage ?? {};
     const model: ModelInfo = event.model;
@@ -1270,7 +1272,8 @@ export class Scrawn<
         inputCacheDebit: inputCacheDebit ?? inputDebit,
         outputCacheDebit: outputCacheDebit ?? outputDebit,
         provider,
-      }
+      },
+      metadata
     );
     this.aiTokenStreamConsumer(
       (async function* () {