fix: serialize wire fields at top level from every entry point (0.5.1)

The v0.5.0 contract defines model, provider, input_tokens, output_tokens,
total_tokens, duration_ms, ttft_ms, and cost as top-level Event properties
so the ingest server writes them into typed Postgres columns. Two SDK paths
leaked them into metadata instead, silently bypassing the typed-column
path once the server started reading them from the top of the payload:

  - Generation.event() took only (type, metadata) so wire fields passed
    via metadata stayed inside metadata rather than surfacing top-level.

  - Feature.generation() passed model top-level via the merged spread AND
    injected baseMetadata.model = this.defaults.model, duplicating it
    into metadata. It also didn't accept per-call tokens/cost/latency.

  - Feature.track() never forwarded model/provider defaults to TrackEvent
    top-level, only into metadata.feature.

Fix: Generation.event() now types wire keys explicitly on the metadata
param and destructures them out before sending (they land at the top of
TrackEvent, not metadata). Feature.generation() accepts per-call wire
fields and no longer duplicates model into baseMetadata. Feature.track()
forwards model/provider defaults top-level.

Added "wire-level fields" regression block in tests/tracking.test.ts
covering track(), generation(), gen.event(), feature.generation(),
feature.track(), feature-default, and per-call override paths. Updated
the test that asserted metadata.model == "gpt-4o" to assert top-level
and absence from metadata.

Author: JasonLovesDoggo

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylitmus/sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "files": [
     "dist"
   ],

src/client.ts

@@ -21,6 +21,7 @@
 
 import { AbandonDetector, DEFAULT_ABANDON_THRESHOLD_MS } from "./abandon.js";
 import { ConsentManager } from "./consent.js";
+import { collectStartupMetadata } from "./environment.js";
 import { Feature } from "./feature.js";
 import { Generation } from "./generation.js";
 import { createLogger, type Logger } from "./logger.js";
@@ -36,7 +37,6 @@ import type {
   TrackEvent,
 } from "./types.js";
 import { SDK_NAME, SDK_VERSION } from "./version.js";
-import { collectStartupMetadata } from "./environment.js";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -339,8 +339,8 @@ export class LitmusClient implements GenerationHost {
     // Sanitize numeric fields. NaN/Infinity would cause Postgres NUMERIC
     // columns to reject the entire batch insert.
     const sanitized = { ...event };
-    for (const key of ['cost', 'input_tokens', 'output_tokens', 'total_tokens', 'duration_ms', 'ttft_ms'] as const) {
-      if (key in sanitized && typeof sanitized[key] === 'number' && !Number.isFinite(sanitized[key])) {
+    for (const key of ["cost", "input_tokens", "output_tokens", "total_tokens", "duration_ms", "ttft_ms"] as const) {
+      if (key in sanitized && typeof sanitized[key] === "number" && !Number.isFinite(sanitized[key])) {
         delete sanitized[key];
       }
     }

src/environment.ts

@@ -13,13 +13,15 @@
 declare const Deno: unknown;
 declare const Bun: unknown;
 declare const EdgeRuntime: unknown;
-declare const process: undefined | {
-  versions?: { node?: string };
-  platform?: string;
-  arch?: string;
-  memoryUsage?: () => { rss: number };
-  env?: Record<string, string | undefined>;
-};
+declare const process:
+  | undefined
+  | {
+      versions?: { node?: string };
+      platform?: string;
+      arch?: string;
+      memoryUsage?: () => { rss: number };
+      env?: Record<string, string | undefined>;
+    };
 
 export function detectPlatform(): string {
   if (typeof Deno !== "undefined") return "deno";
@@ -73,9 +75,7 @@ function browserContext(): Record<string, unknown> {
 
     // User preferences
     if (typeof window.matchMedia === "function") {
-      ctx.prefers_color_scheme = window.matchMedia("(prefers-color-scheme: dark)").matches
-        ? "dark"
-        : "light";
+      ctx.prefers_color_scheme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
       ctx.prefers_reduced_motion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
     }
   }
@@ -103,9 +103,11 @@ function browserContext(): Record<string, unknown> {
 function detectCloud(env: Record<string, string | undefined>): Record<string, unknown> | undefined {
   // Order matters: more specific checks first.
   if (env.VERCEL) return { cloud_provider: "vercel", cloud_region: env.VERCEL_REGION };
-  if (env.AWS_REGION) return { cloud_provider: "aws", cloud_region: env.AWS_REGION, cloud_platform: env.AWS_EXECUTION_ENV };
+  if (env.AWS_REGION)
+    return { cloud_provider: "aws", cloud_region: env.AWS_REGION, cloud_platform: env.AWS_EXECUTION_ENV };
   if (env.FLY_REGION) return { cloud_provider: "fly", cloud_region: env.FLY_REGION };
-  if (env.RAILWAY_ENVIRONMENT_NAME) return { cloud_provider: "railway", cloud_environment: env.RAILWAY_ENVIRONMENT_NAME };
+  if (env.RAILWAY_ENVIRONMENT_NAME)
+    return { cloud_provider: "railway", cloud_environment: env.RAILWAY_ENVIRONMENT_NAME };
   if (env.RENDER) return { cloud_provider: "render", cloud_region: env.RENDER_REGION };
   if (env.GCP_PROJECT || env.GOOGLE_CLOUD_PROJECT) return { cloud_provider: "gcp" };
   if (env.WEBSITE_SITE_NAME && env.REGION_NAME) return { cloud_provider: "azure", cloud_region: env.REGION_NAME };

src/feature.ts

@@ -24,6 +24,12 @@ export interface FeatureHost {
     opts?: FeatureDefaults & {
       prompt_version?: string;
       metadata?: Record<string, unknown>;
+      input_tokens?: number;
+      output_tokens?: number;
+      total_tokens?: number;
+      duration_ms?: number;
+      ttft_ms?: number;
+      cost?: number;
     },
   ): Generation;
 }
@@ -40,30 +46,52 @@ export class Feature {
     this.defaults = { ...defaults, prompt_id: defaults.prompt_id ?? name };
   }
 
+  /**
+   * Create a generation scoped to this feature.
+   *
+   * Per-call wire fields (model, provider, tokens, latency, cost) win over
+   * the feature's defaults and land at the top of the event payload — the
+   * ingest server writes them to typed Postgres columns, NOT into metadata.
+   */
   generation(
     sessionId: string,
     opts?: {
       user_id?: string;
       prompt_version?: string;
       metadata?: Record<string, unknown>;
+      model?: string;
+      provider?: string;
+      input_tokens?: number;
+      output_tokens?: number;
+      total_tokens?: number;
+      duration_ms?: number;
+      ttft_ms?: number;
+      cost?: number;
     },
   ): Generation {
-    const baseMetadata: Record<string, unknown> = { feature: this.name };
-    if (this.defaults.model) baseMetadata.model = this.defaults.model;
-    const merged: FeatureDefaults = {
+    return this.host.generation(sessionId, {
       ...this.defaults,
       user_id: opts?.user_id ?? this.defaults.user_id,
       prompt_version: opts?.prompt_version ?? this.defaults.prompt_version,
-      metadata: { ...baseMetadata, ...this.defaults.metadata, ...opts?.metadata },
-    };
-    return this.host.generation(sessionId, merged);
+      model: opts?.model ?? this.defaults.model,
+      provider: opts?.provider ?? this.defaults.provider,
+      input_tokens: opts?.input_tokens,
+      output_tokens: opts?.output_tokens,
+      total_tokens: opts?.total_tokens,
+      duration_ms: opts?.duration_ms,
+      ttft_ms: opts?.ttft_ms,
+      cost: opts?.cost,
+      metadata: { feature: this.name, ...this.defaults.metadata, ...opts?.metadata },
+    });
   }
 
   track(event: Omit<TrackEvent, "prompt_id"> & { prompt_id?: string }) {
     this.host.track({
       ...event,
       prompt_id: event.prompt_id ?? this.defaults.prompt_id,
       user_id: event.user_id ?? this.defaults.user_id,
+      model: event.model ?? this.defaults.model,
+      provider: event.provider ?? this.defaults.provider,
       metadata: { ...this.defaults.metadata, feature: this.name, ...event.metadata },
     });
   }

src/generation.ts

@@ -66,21 +66,48 @@ export class Generation {
    *   gen.event("$rate", { value: 4, scale: "5-star" });
    *   gen.event("$view");  // passive — won't cancel auto-abandon
    */
-  event(type: SystemEvent | (string & {}), metadata?: Record<string, unknown>) {
+  event(
+    type: SystemEvent | (string & {}),
+    metadata?: Record<string, unknown> & {
+      // Wire-level fields are typed so callers get autocomplete. At send time
+      // we split them off into top-level fields on the event payload — they
+      // land in real Postgres columns, not JSONB keys.
+      model?: string;
+      provider?: string;
+      input_tokens?: number;
+      output_tokens?: number;
+      total_tokens?: number;
+      duration_ms?: number;
+      ttft_ms?: number;
+      cost?: number;
+    },
+  ) {
     // $view is passive observation — doesn't resolve auto-abandon.
     // Everything else indicates the user interacted with the output.
     if (type !== "$view") {
       this.host._resolveGeneration(this.id);
     }
 
+    // Split wire-level keys out of metadata so they serialize top-level.
+    const { model, provider, input_tokens, output_tokens, total_tokens, duration_ms, ttft_ms, cost, ...rest } =
+      metadata ?? {};
+
     this.host.track({
       type,
       session_id: this.sessionId,
       user_id: this.defaults.user_id,
       prompt_id: this.defaults.prompt_id,
       prompt_version: this.defaults.prompt_version,
       generation_id: this.id,
-      metadata: { ...this.defaults.metadata, ...metadata },
+      model,
+      provider,
+      input_tokens,
+      output_tokens,
+      total_tokens,
+      duration_ms,
+      ttft_ms,
+      cost,
+      metadata: { ...this.defaults.metadata, ...rest },
     });
   }
 

test/client.test.ts

@@ -3,6 +3,7 @@ import { LitmusClient } from "../src";
 import type { TrackEvent } from "../src";
 
 // Captures request bodies sent to the mock server.
+// Mirrors the wire shape defined in contract/openapi.yaml.
 interface CapturedEvent {
   id: string;
   type: string;
@@ -11,7 +12,16 @@ interface CapturedEvent {
   timestamp: string;
   generation_id?: string;
   prompt_id?: string;
+  prompt_version?: string;
   metadata?: Record<string, unknown>;
+  model?: string;
+  provider?: string;
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+  duration_ms?: number;
+  ttft_ms?: number;
+  cost?: number;
 }
 
 interface CapturedRequest {
@@ -849,8 +859,12 @@ describe("LitmusClient", () => {
       for (const e of events) {
         expect(e.user_id).toBe("user_99");
       }
-      // model in metadata
-      expect(events[0].metadata).toEqual(expect.objectContaining({ model: "claude-sonnet" }));
+      // model is a wire-level field — goes top-level on the $generation event,
+      // NOT duplicated into metadata. The ingest server writes it to the
+      // events.model column; metadata stays for freeform props only.
+      const genEvent = events.find((e: CapturedEvent) => e.type === "$generation")!;
+      expect(genEvent.model).toBe("claude-sonnet");
+      expect(genEvent.metadata).not.toHaveProperty("model");
 
       client.destroy();
       mock.restore();
@@ -926,6 +940,128 @@ describe("LitmusClient", () => {
     });
   });
 
+  describe("wire-level fields on every entry point", () => {
+    // Regression guard for the v0.5.0 bug where Feature.generation() and
+    // Feature.track() dropped wire fields or duplicated them into metadata.
+    // Every public entry point must (a) surface wire fields at the top of
+    // the event JSON and (b) NOT leak them into metadata alongside.
+    const SAMPLE = {
+      model: "gpt-4o",
+      provider: "openai",
+      input_tokens: 120,
+      output_tokens: 340,
+      total_tokens: 460,
+      duration_ms: 1850,
+      ttft_ms: 240,
+      cost: 0.0042,
+    } as const;
+
+    function assertTopLevelNoLeak(event: CapturedEvent) {
+      for (const [key, expected] of Object.entries(SAMPLE)) {
+        expect(event[key as keyof CapturedEvent]).toBe(expected);
+        expect(event.metadata).not.toHaveProperty(key);
+      }
+    }
+
+    it("track() serializes wire fields at top level", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      client.track({ type: "$generation", session_id: "s1", ...SAMPLE });
+      await client.flush();
+
+      assertTopLevelNoLeak(mock.requests[0].events[0]);
+      client.destroy();
+      mock.restore();
+    });
+
+    it("generation() serializes wire fields at top level", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      client.generation("s1", { prompt_id: "chat", ...SAMPLE });
+      await client.flush();
+
+      const gen = mock.requests[0].events.find((e) => e.type === "$generation")!;
+      assertTopLevelNoLeak(gen);
+      client.destroy();
+      mock.restore();
+    });
+
+    it("gen.event() serializes wire fields at top level", async () => {
+      // Mid-stream $switch_model needs to carry new model + token deltas.
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      const gen = client.generation("s1", { prompt_id: "chat" });
+      gen.event("$switch_model", { ...SAMPLE });
+      await client.flush();
+
+      const switchEvent = mock.requests[0].events.find((e) => e.type === "$switch_model")!;
+      assertTopLevelNoLeak(switchEvent);
+      client.destroy();
+      mock.restore();
+    });
+
+    it("feature.generation() serializes per-call wire fields at top level", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      const feat = client.feature("summarizer");
+      feat.generation("s1", { ...SAMPLE });
+      await client.flush();
+
+      const gen = mock.requests[0].events.find((e) => e.type === "$generation")!;
+      assertTopLevelNoLeak(gen);
+      client.destroy();
+      mock.restore();
+    });
+
+    it("feature.track() serializes wire fields at top level", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      const feat = client.feature("summarizer");
+      feat.track({ type: "$generation", session_id: "s1", ...SAMPLE });
+      await client.flush();
+
+      assertTopLevelNoLeak(mock.requests[0].events[0]);
+      client.destroy();
+      mock.restore();
+    });
+
+    it("feature defaults for model/provider go top-level, never into metadata", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      const feat = client.feature("content_gen", { model: "gpt-4o", provider: "openai" });
+      feat.generation("s1");
+      await client.flush();
+
+      const gen = mock.requests[0].events.find((e) => e.type === "$generation")!;
+      expect(gen.model).toBe("gpt-4o");
+      expect(gen.provider).toBe("openai");
+      expect(gen.metadata).not.toHaveProperty("model");
+      expect(gen.metadata).not.toHaveProperty("provider");
+      client.destroy();
+      mock.restore();
+    });
+
+    it("per-call model overrides feature default", async () => {
+      const mock = createMockServer([]);
+      const client = newClient();
+
+      const feat = client.feature("chat", { model: "gpt-4o-mini" });
+      feat.generation("s1", { model: "gpt-4o" });
+      await client.flush();
+
+      const gen = mock.requests[0].events.find((e) => e.type === "$generation")!;
+      expect(gen.model).toBe("gpt-4o");
+      client.destroy();
+      mock.restore();
+    });
+  });
+
   describe("attach()", () => {
     it("returns a Generation handle without emitting $generation", async () => {
       const mock = createMockServer([]);

tests/helpers.ts

@@ -15,7 +15,7 @@
 
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 
-/** Shape of a single event as it arrives at the server. */
+/** Shape of a single event as it arrives at the server. Mirrors contract/openapi.yaml. */
 export interface CapturedEvent {
   type: string;
   session_id: string;
@@ -26,6 +26,15 @@ export interface CapturedEvent {
   metadata?: Record<string, unknown>;
   id: string;
   timestamp: string;
+  // Wire-level fields that the ingest server writes to typed Postgres columns.
+  model?: string;
+  provider?: string;
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+  duration_ms?: number;
+  ttft_ms?: number;
+  cost?: number;
 }
 
 /** One POST body received by the server. */