fix(core): define RunEvent schema and update ApiClient validation

.changeset/define-runevent-schema.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Define RunEvent schema and update ApiClient to use it

packages/core/src/v3/apiClient/index.ts

@@ -28,6 +28,7 @@ import {
   EnvironmentVariableResponseBody,
   EnvironmentVariableWithSecret,
   ListQueueOptions,
+  ListRunEventsResponse,
   ListRunResponseItem,
   ListScheduleOptions,
   QueueItem,
@@ -42,6 +43,7 @@ import {
   RetrieveQueueParam,
   RetrieveRunResponse,
   RetrieveRunTraceResponseBody,
+  RunEvent,
   ScheduleObject,
   SendInputStreamResponseBody,
   StreamBatchItemsResponse,
@@ -700,7 +702,7 @@ export class ApiClient {
 
   listRunEvents(runId: string, requestOptions?: ZodFetchOptions) {
     return zodfetch(
-      z.any(), // TODO: define a proper schema for this
+      ListRunEventsResponse,
       `${this.baseUrl}/api/v1/runs/${runId}/events`,
       {
         method: "GET",

packages/core/src/v3/schemas/api-type.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { InitializeDeploymentRequestBody } from "./api.js";
+import { InitializeDeploymentRequestBody, RunEvent, ListRunEventsResponse } from "./api.js";
 import type { InitializeDeploymentRequestBody as InitializeDeploymentRequestBodyType } from "./api.js";
 
 describe("InitializeDeploymentRequestBody", () => {
@@ -139,3 +139,131 @@ describe("InitializeDeploymentRequestBody", () => {
     });
   });
 });
+
+describe("RunEvent Schema", () => {
+  const validEvent = {
+    spanId: "span_123",
+    parentId: "span_root",
+    runId: "run_abc",
+    message: "Test event",
+    style: {
+      icon: "task",
+      variant: "primary",
+    },
+    startTime: "2024-03-14T00:00:00Z",
+    duration: 1234,
+    isError: false,
+    isPartial: false,
+    isCancelled: false,
+    level: "INFO",
+    kind: "TASK",
+    attemptNumber: 1,
+  };
+
+  it("parses a valid event correctly", () => {
+    const result = RunEvent.safeParse(validEvent);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.spanId).toBe("span_123");
+      expect(result.data.startTime).toBeInstanceOf(Date);
+      expect(result.data.level).toBe("INFO");
+    }
+  });
+
+  it("fails on missing required fields", () => {
+    const invalidEvent = { ...validEvent };
+    delete (invalidEvent as any).spanId;
+    const result = RunEvent.safeParse(invalidEvent);
+    expect(result.success).toBe(false);
+  });
+
+  it("fails on invalid level", () => {
+    const invalidEvent = { ...validEvent, level: "INVALID_LEVEL" };
+    const result = RunEvent.safeParse(invalidEvent);
+    expect(result.success).toBe(false);
+  });
+
+  it("coerces startTime to Date", () => {
+    const result = RunEvent.parse(validEvent);
+    expect(result.startTime).toBeInstanceOf(Date);
+    expect(result.startTime.toISOString()).toBe("2024-03-14T00:00:00.000Z");
+  });
+
+  it("handles 19-digit nanosecond startTime strings", () => {
+    const event = { ...validEvent, startTime: "1710374400000000000" };
+    const result = RunEvent.parse(event);
+    expect(result.startTime).toBeInstanceOf(Date);
+    // 1710374400000000000 ns = 1710374400000 ms = 2024-03-14T00:00:00Z
+    expect(result.startTime.toISOString()).toBe("2024-03-14T00:00:00.000Z");
+  });
+
+  it("handles bigint nanosecond startTime", () => {
+    const event = { ...validEvent, startTime: 1710374400000000000n };
+    const result = RunEvent.parse(event as any);
+    expect(result.startTime).toBeInstanceOf(Date);
+    expect(result.startTime.toISOString()).toBe("2024-03-14T00:00:00.000Z");
+  });
+
+  it("allows optional/null parentId", () => {
+    const eventWithoutParent = { ...validEvent };
+    delete (eventWithoutParent as any).parentId;
+    expect(RunEvent.safeParse(eventWithoutParent).success).toBe(true);
+
+    const eventWithNullParent = { ...validEvent, parentId: null };
+    expect(RunEvent.safeParse(eventWithNullParent).success).toBe(true);
+  });
+
+  it("allows nullish attemptNumber", () => {
+    const eventWithNullAttempt = { ...validEvent, attemptNumber: null };
+    const result = RunEvent.safeParse(eventWithNullAttempt);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.attemptNumber).toBe(null);
+    }
+
+    const eventWithoutAttempt = { ...validEvent };
+    delete (eventWithoutAttempt as any).attemptNumber;
+    const result2 = RunEvent.safeParse(eventWithoutAttempt);
+    expect(result2.success).toBe(true);
+  });
+
+  it("supports taskSlug", () => {
+    const eventWithSlug = { ...validEvent, taskSlug: "my-task" };
+    const result = RunEvent.parse(eventWithSlug);
+    expect(result.taskSlug).toBe("my-task");
+  });
+});
+
+describe("ListRunEventsResponse Schema", () => {
+  it("parses a valid wrapped response", () => {
+    const response = {
+      events: [
+        {
+          spanId: "span_1",
+          runId: "run_1",
+          message: "Event 1",
+          style: {},
+          startTime: "2024-03-14T00:00:00Z",
+          duration: 100,
+          isError: false,
+          isPartial: false,
+          isCancelled: false,
+          level: "INFO",
+          kind: "TASK",
+        },
+      ],
+    };
+
+    const result = ListRunEventsResponse.safeParse(response);
+    expect(result.success).toBe(true);
+    if (result.success && result.data) {
+      expect(result.data.events[0]!.spanId).toBe("span_1");
+    }
+  });
+
+  it("fails on plain array", () => {
+    const response = [{ spanId: "span_1" }];
+    const result = ListRunEventsResponse.safeParse(response);
+    expect(result.success).toBe(false);
+  });
+});

packages/core/src/v3/schemas/api.ts

@@ -9,6 +9,8 @@ import {
 } from "./common.js";
 import { BackgroundWorkerMetadata } from "./resources.js";
 import { DequeuedMessage, MachineResources } from "./runEngine.js";
+import { TaskEventStyle } from "./style.js";
+import { SpanEvents } from "./openTelemetry.js";
 
 export const RunEngineVersion = z.union([z.literal("V1"), z.literal("V2")]);
 
@@ -1639,3 +1641,52 @@ export const SendInputStreamResponseBody = z.object({
   ok: z.boolean(),
 });
 export type SendInputStreamResponseBody = z.infer<typeof SendInputStreamResponseBody>;
+export const TaskEventLevel = z.enum(["TRACE", "DEBUG", "INFO", "LOG", "WARN", "ERROR"]);
+export type TaskEventLevel = z.infer<typeof TaskEventLevel>;
+export const NanosecondTimestampSchema = z
+  .union([z.string(), z.number(), z.bigint()])
+  .transform((val) => {
+    // If it's already a Date, return it (though union doesn't include it)
+    if (typeof val === "object" && val instanceof Date) return val;
+
+    const str = val.toString();
+
+    // 19 digits is nanoseconds (e.g., 1710374400000000000)
+    if (str.length === 19) {
+      return new Date(Number(BigInt(str) / 1000000n));
+    }
+
+    // 13 digits is milliseconds
+    if (str.length === 13) {
+      return new Date(Number(val));
+    }
+
+    // Default to standard date coercion
+    return new Date(val as any);
+  });
+
+export const RunEvent = z.object({
+  spanId: z.string(),
+  parentId: z.string().nullish(),
+  runId: z.string(),
+  message: z.string(),
+  style: TaskEventStyle,
+  startTime: NanosecondTimestampSchema,
+  duration: z.number(),
+  isError: z.boolean(),
+  isPartial: z.boolean(),
+  isCancelled: z.boolean(),
+  level: TaskEventLevel,
+  events: SpanEvents.optional(),
+  kind: z.string(),
+  attemptNumber: z.number().nullish(),
+  taskSlug: z.string().optional(),
+});
+
+export type RunEvent = z.infer<typeof RunEvent>;
+
+export const ListRunEventsResponse = z.object({
+  events: z.array(RunEvent),
+});
+
+export type ListRunEventsResponse = z.infer<typeof ListRunEventsResponse>;