Feat/reported timestamp

.changeset/spotty-plums-enter.md

@@ -0,0 +1,5 @@
+---
+"@scrawn/core": patch
+---
+
+feat: reported timestamp

packages/scrawn/src/core/scrawn.ts

@@ -475,6 +475,7 @@ export class Scrawn<
       userId: validationResult.data.userId,
       debit,
       metadata: validationResult.data.metadata,
+      reportedTimestamp: validationResult.data.reportedTimestamp,
     };
 
     const attempt = () =>
@@ -636,6 +637,7 @@ export class Scrawn<
           userId: extractedPayload.userId,
           debit: extractedPayload.debit,
           metadata: extractedPayload.metadata,
+          reportedTimestamp: extractedPayload.reportedTimestamp,
         };
         const validationResult = EventPayloadSchema.safeParse(rawPayload);
         if (!validationResult.success) {
@@ -661,6 +663,7 @@ export class Scrawn<
           userId: validationResult.data.userId,
           debit,
           metadata: validationResult.data.metadata,
+          reportedTimestamp: validationResult.data.reportedTimestamp,
         };
 
         this.consumeEvent(
@@ -763,6 +766,7 @@ export class Scrawn<
       userId: string;
       debit: NormalizedDebit;
       metadata?: Record<string, unknown>;
+      reportedTimestamp?: number;
     },
     authMethodName: K,
     eventType: "RAW" | "MIDDLEWARE_CALL",
@@ -792,6 +796,10 @@ export class Scrawn<
     // Build debit field — already normalized by caller
     const debitField = payload.debit;
 
+    // Resolve timestamp once — stable across retries
+    const resolvedTimestamp =
+      payload.reportedTimestamp ?? Math.floor(Date.now() / 1000);
+
     // Retry loop for retryable failures
     for (let attempt = 0; ; attempt++) {
       try {
@@ -811,7 +819,7 @@ export class Scrawn<
         const request = {
           type: EventType.BASIC_USAGE,
           userId: payload.userId,
-          reportedTimestamp: 0,
+          reportedTimestamp: resolvedTimestamp,
           eventId,
           idempotencyKey,
           basicUsage,
@@ -1153,7 +1161,8 @@ export class Scrawn<
       const request = {
         type: EventType.AI_TOKEN_USAGE,
         userId: validated.userId,
-        reportedTimestamp: 0,
+        reportedTimestamp:
+          validated.reportedTimestamp ?? Math.floor(Date.now() / 1000),
         eventId,
         idempotencyKey,
         aiTokenUsage,

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

@@ -98,6 +98,7 @@ export const EventPayloadSchema = z.object({
   userId: z.string().min(1, "userId must be a non-empty string"),
   debit: DebitSchemaNoTokens,
   metadata: z.record(z.string(), z.unknown()).optional(),
+  reportedTimestamp: z.number().int().nonnegative().optional(),
 });
 
 /**
@@ -160,6 +161,7 @@ export type EventPayload<TTag extends string = string> = {
   userId: string;
   debit: Debit<TTag>;
   metadata?: Record<string, unknown>;
+  reportedTimestamp?: number;
 };
 
 /**
@@ -348,6 +350,7 @@ export const AITokenUsagePayloadSchema = z.object({
     .nonnegative("outputCacheTokens must be non-negative")
     .optional(),
   outputCacheDebit: DebitSchemaWithTokens.optional(),
+  reportedTimestamp: z.number().int().nonnegative().optional(),
 });
 
 /**
@@ -425,4 +428,6 @@ export type AITokenUsagePayload<TTag extends string = string> = {
   outputCacheTokens?: number;
   /** Debit pricing for cached output tokens. */
   outputCacheDebit?: Debit<TTag>;
+  /** Unix timestamp (seconds) when this event was created. Auto-set if omitted. */
+  reportedTimestamp?: number;
 };