From b8420dbc760351982cc2d5f5d944f728bcd063bb Mon Sep 17 00:00:00 2001
From: Devyash Saini <dysaini2004@gmail.com>
Date: Sat, 30 May 2026 12:03:34 +0530
Subject: [PATCH 1/3] feat: add metadata to BillableCallParams

---
 packages/scrawn/src/core/ai/types.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/scrawn/src/core/ai/types.ts b/packages/scrawn/src/core/ai/types.ts
index 70b5fff..750673c 100644
--- a/packages/scrawn/src/core/ai/types.ts
+++ b/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. */

From 1149dc49354eedc38da20e4198d894c4339a8697 Mon Sep 17 00:00:00 2001
From: Devyash Saini <dysaini2004@gmail.com>
Date: Sat, 30 May 2026 12:04:04 +0530
Subject: [PATCH 2/3] feat: add metadata param to buildAIPayload

---
 packages/scrawn/src/core/ai/track.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/scrawn/src/core/ai/track.ts b/packages/scrawn/src/core/ai/track.ts
index c93fd13..4073fdd 100644
--- a/packages/scrawn/src/core/ai/track.ts
+++ b/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,

From 146733d0b4bb363bfe8af61bf637f2ed5d9a088b Mon Sep 17 00:00:00 2001
From: Devyash Saini <dysaini2004@gmail.com>
Date: Sat, 30 May 2026 12:05:26 +0530
Subject: [PATCH 3/3] feat: add metadata to trackAI and biller.ai wrapper

---
 packages/scrawn/src/core/ai/wrap.ts | 3 +++
 packages/scrawn/src/core/scrawn.ts  | 5 ++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/scrawn/src/core/ai/wrap.ts b/packages/scrawn/src/core/ai/wrap.ts
index 7848a08..4a33b53 100644
--- a/packages/scrawn/src/core/ai/wrap.ts
+++ b/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,
   };
 }
 
diff --git a/packages/scrawn/src/core/scrawn.ts b/packages/scrawn/src/core/scrawn.ts
index 39ff19e..687d2be 100644
--- a/packages/scrawn/src/core/scrawn.ts
+++ b/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* () {