Export header normalization helper for advanced integrations

Co-authored-by: Eric Allam <eric@trigger.dev>

packages/ai/README.md

@@ -61,6 +61,7 @@ Typed request option helper aliases are exported:
 - `TriggerChatReconnectOptions`
 - `TriggerChatHeadersInput`
 - `TriggerChatTransportError` / `TriggerChatOnError`
+- `normalizeTriggerChatHeaders(...)`
 
 ```ts
 import type { TriggerChatTransportPayload } from "@trigger.dev/ai";

packages/ai/src/chatTransport.test.ts

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import {
   InMemoryTriggerChatRunStore,
   createTriggerChatTransport,
+  normalizeTriggerChatHeaders,
   TriggerChatTransport,
 } from "./chatTransport.js";
 import type { TriggerChatStream } from "./types.js";
@@ -462,6 +463,20 @@ describe("TriggerChatTransport", function () {
     });
   });
 
+  it("normalizes header helper input values consistently", function () {
+    expect(normalizeTriggerChatHeaders(undefined)).toBeUndefined();
+    expect(
+      normalizeTriggerChatHeaders([["x-array", "array-value"]])
+    ).toEqual({
+      "x-array": "array-value",
+    });
+    expect(
+      normalizeTriggerChatHeaders(new Headers([["x-headers", "headers-value"]]))
+    ).toEqual({
+      "x-headers": "headers-value",
+    });
+  });
+
   it("returns null on reconnect when no active run exists", async function () {
     const transport = new TriggerChatTransport({
       task: "chat-task",

packages/ai/src/chatTransport.ts

@@ -459,6 +459,18 @@ function normalizeHeaders(
   return result;
 }
 
+/**
+ * Converts supported header input shapes into a normalized plain object.
+ *
+ * @deprecated This helper is primarily exposed for advanced integrations and tests.
+ * Most users should rely on `TriggerChatTransport` internals to normalize request headers.
+ */
+export function normalizeTriggerChatHeaders(
+  headers: TriggerChatHeadersInput | undefined
+): Record<string, string> | undefined {
+  return normalizeHeaders(headers);
+}
+
 function isHeadersInstance(headers: unknown): headers is Headers {
   if (typeof Headers === "undefined") {
     return false;

packages/ai/src/chatTransport.types.test.ts

@@ -4,6 +4,7 @@ import {
   createTriggerChatTransport,
   TriggerChatTransport,
   InMemoryTriggerChatRunStore,
+  normalizeTriggerChatHeaders,
   TriggerChatTransportOptions,
   type TriggerChatOnError,
   type TriggerChatTransportError,
@@ -188,3 +189,11 @@ it("accepts custom run store implementations via options typing", function () {
 
   expectTypeOf(transport).toBeObject();
 });
+
+it("exports typed header normalization helper", function () {
+  const normalizedHeaders = normalizeTriggerChatHeaders({
+    "x-header": "value",
+  });
+
+  expectTypeOf(normalizedHeaders).toEqualTypeOf<Record<string, string> | undefined>();
+});

packages/ai/src/index.ts

@@ -2,6 +2,7 @@ export { ai, type ToolCallExecutionOptions, type ToolOptions } from "./ai.js";
 export {
   createTriggerChatTransport,
   InMemoryTriggerChatRunStore,
+  normalizeTriggerChatHeaders,
   TriggerChatTransport,
   type TriggerChatTransportOptions,
 } from "./chatTransport.js";