From 677debcff00d61daa58cf0a6fb676f0a3e6403d5 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 15 Feb 2026 00:45:34 +0000
Subject: [PATCH] Export header normalization helper for advanced integrations

Co-authored-by: Eric Allam <eric@trigger.dev>
---
 packages/ai/README.md                       |  1 +
 packages/ai/src/chatTransport.test.ts       | 15 +++++++++++++++
 packages/ai/src/chatTransport.ts            | 12 ++++++++++++
 packages/ai/src/chatTransport.types.test.ts |  9 +++++++++
 packages/ai/src/index.ts                    |  1 +
 5 files changed, 38 insertions(+)

diff --git a/packages/ai/README.md b/packages/ai/README.md
index b369ead67..b4be72ecb 100644
--- a/packages/ai/README.md
+++ b/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";
diff --git a/packages/ai/src/chatTransport.test.ts b/packages/ai/src/chatTransport.test.ts
index 87d31304d..c9e1a08e7 100644
--- a/packages/ai/src/chatTransport.test.ts
+++ b/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",
diff --git a/packages/ai/src/chatTransport.ts b/packages/ai/src/chatTransport.ts
index 288a53687..8aca04618 100644
--- a/packages/ai/src/chatTransport.ts
+++ b/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;
diff --git a/packages/ai/src/chatTransport.types.test.ts b/packages/ai/src/chatTransport.types.test.ts
index 1caa8b13a..b038dbce6 100644
--- a/packages/ai/src/chatTransport.types.test.ts
+++ b/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>();
+});
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index af095b2f1..3a5e71613 100644
--- a/packages/ai/src/index.ts
+++ b/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";