feat (ui): resolvable header, body, credentials in http chat transport (#7154)

## Background

For use cases such as credentials, it is important that the values of
body, headers, credentials can get resolved at request execution time if
needed.

## Summary

Switch from fixed object to resolvables.

## Related Issues

Resolves #7109
Addresses #7147

---------

Co-authored-by: nicoalbanese <gcalbanese96@gmail.com>

Author: lgrammel

.changeset/flat-falcons-happen.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (ui): resolvable header, body, credentials in http chat transport

content/docs/04-ai-sdk-ui/02-chatbot.mdx

@@ -369,6 +369,25 @@ const { messages, sendMessage } = useChat({
 });
 ```
 
+#### Dynamic Hook-Level Configuration
+
+You can also provide functions that return configuration values. This is useful for authentication tokens that need to be refreshed, or for configuration that depends on runtime conditions:
+
+```tsx
+const { messages, sendMessage } = useChat({
+  api: '/api/chat',
+  headers: () => ({
+    Authorization: `Bearer ${getAuthToken()}`,
+    'X-User-ID': getCurrentUserId(),
+  }),
+  body: () => ({
+    sessionId: getCurrentSessionId(),
+    preferences: getUserPreferences(),
+  }),
+  credentials: () => 'include',
+});
+```
+
 #### Request-Level Configuration (Recommended)
 
 <Note>

content/docs/04-ai-sdk-ui/21-transport.mdx

@@ -51,6 +51,27 @@ const { messages, sendMessage } = useChat({
 });
 ```
 
+### Dynamic Configuration
+
+You can also provide functions that return configuration values. This is useful for authentication tokens that need to be refreshed, or for configuration that depends on runtime conditions:
+
+```tsx
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    headers: () => ({
+      Authorization: `Bearer ${getAuthToken()}`,
+      'X-User-ID': getCurrentUserId(),
+    }),
+    body: () => ({
+      sessionId: getCurrentSessionId(),
+      preferences: getUserPreferences(),
+    }),
+    credentials: () => 'include',
+  }),
+});
+```
+
 ### Request Transformation
 
 Transform requests before sending to your API:

packages/ai/src/ui/http-chat-transport.test.ts

@@ -69,5 +69,114 @@ describe('HttpChatTransport', () => {
         }
       `);
     });
+
+    it('should include the body in the request when a function is provided', async () => {
+      server.urls['http://localhost/api/chat'].response = {
+        type: 'stream-chunks',
+        chunks: [],
+      };
+
+      const transport = new MockHttpChatTransport({
+        api: 'http://localhost/api/chat',
+        body: () => ({ someData: true }),
+      });
+
+      await transport.sendMessages({
+        chatId: 'c123',
+        messageId: 'm123',
+        trigger: 'submit-user-message',
+        messages: [
+          {
+            id: 'm123',
+            role: 'user',
+            parts: [{ text: 'Hello, world!', type: 'text' }],
+          },
+        ],
+        abortSignal: new AbortController().signal,
+      });
+
+      expect(await server.calls[0].requestBodyJson).toMatchInlineSnapshot(`
+        {
+          "id": "c123",
+          "messageId": "m123",
+          "messages": [
+            {
+              "id": "m123",
+              "parts": [
+                {
+                  "text": "Hello, world!",
+                  "type": "text",
+                },
+              ],
+              "role": "user",
+            },
+          ],
+          "someData": true,
+          "trigger": "submit-user-message",
+        }
+      `);
+    });
+  });
+
+  describe('headers', () => {
+    it('should include headers in the request by default', async () => {
+      server.urls['http://localhost/api/chat'].response = {
+        type: 'stream-chunks',
+        chunks: [],
+      };
+
+      const transport = new MockHttpChatTransport({
+        api: 'http://localhost/api/chat',
+        headers: { 'X-Test-Header': 'test-value' },
+      });
+
+      await transport.sendMessages({
+        chatId: 'c123',
+        messageId: 'm123',
+        trigger: 'submit-user-message',
+        messages: [
+          {
+            id: 'm123',
+            role: 'user',
+            parts: [{ text: 'Hello, world!', type: 'text' }],
+          },
+        ],
+        abortSignal: new AbortController().signal,
+      });
+
+      expect(server.calls[0].requestHeaders['x-test-header']).toBe(
+        'test-value',
+      );
+    });
+
+    it('should include headers in the request when a function is provided', async () => {
+      server.urls['http://localhost/api/chat'].response = {
+        type: 'stream-chunks',
+        chunks: [],
+      };
+
+      const transport = new MockHttpChatTransport({
+        api: 'http://localhost/api/chat',
+        headers: () => ({ 'X-Test-Header': 'test-value-fn' }),
+      });
+
+      await transport.sendMessages({
+        chatId: 'c123',
+        messageId: 'm123',
+        trigger: 'submit-user-message',
+        messages: [
+          {
+            id: 'm123',
+            role: 'user',
+            parts: [{ text: 'Hello, world!', type: 'text' }],
+          },
+        ],
+        abortSignal: new AbortController().signal,
+      });
+
+      expect(server.calls[0].requestHeaders['x-test-header']).toBe(
+        'test-value-fn',
+      );
+    });
   });
 });

packages/ai/src/ui/http-chat-transport.ts

@@ -1,4 +1,4 @@
-import { FetchFunction } from '@ai-sdk/provider-utils';
+import { FetchFunction, Resolvable, resolve } from '@ai-sdk/provider-utils';
 import { UIMessageChunk } from '../ui-message-stream/ui-message-chunks';
 import { ChatTransport } from './chat-transport';
 import { UIMessage } from './ui-messages';
@@ -52,20 +52,29 @@ export type PrepareReconnectToStreamRequest = (options: {
       api?: string;
     }>;
 
+/**
+ * Options for the `HttpChatTransport` class.
+ *
+ * @param UI_MESSAGE - The type of message to be used in the chat.
+ */
 export type HttpChatTransportInitOptions<UI_MESSAGE extends UIMessage> = {
+  /**
+   * The API URL to be used for the chat transport.
+   * Defaults to '/api/chat'.
+   */
   api?: string;
 
   /**
    * The credentials mode to be used for the fetch request.
    * Possible values are: 'omit', 'same-origin', 'include'.
    * Defaults to 'same-origin'.
    */
-  credentials?: RequestCredentials;
+  credentials?: Resolvable<RequestCredentials>;
 
   /**
    * HTTP headers to be sent with the API request.
    */
-  headers?: Record<string, string> | Headers;
+  headers?: Resolvable<Record<string, string> | Headers>;
 
   /**
    * Extra body object to be sent with the API request.
@@ -79,7 +88,7 @@ export type HttpChatTransportInitOptions<UI_MESSAGE extends UIMessage> = {
    * })
    * ```
    */
-  body?: object;
+  body?: Resolvable<object>;
 
   /**
   Custom fetch implementation. You can use it as a middleware to intercept requests,
@@ -98,16 +107,25 @@ export type HttpChatTransportInitOptions<UI_MESSAGE extends UIMessage> = {
    */
   prepareSendMessagesRequest?: PrepareSendMessagesRequest<UI_MESSAGE>;
 
+  /**
+   * When a function is provided, it will be used
+   * to prepare the request body for the chat API. This can be useful for
+   * customizing the request body based on the messages and data in the chat.
+   *
+   * @param id The id of the chat.
+   * @param messages The current messages in the chat.
+   * @param requestBody The request body object passed in the chat request.
+   */
   prepareReconnectToStreamRequest?: PrepareReconnectToStreamRequest;
 };
 
 export abstract class HttpChatTransport<UI_MESSAGE extends UIMessage>
   implements ChatTransport<UI_MESSAGE>
 {
   protected api: string;
-  protected credentials?: RequestCredentials;
-  protected headers?: Record<string, string> | Headers;
-  protected body?: object;
+  protected credentials: HttpChatTransportInitOptions<UI_MESSAGE>['credentials'];
+  protected headers: HttpChatTransportInitOptions<UI_MESSAGE>['headers'];
+  protected body: HttpChatTransportInitOptions<UI_MESSAGE>['body'];
   protected fetch?: FetchFunction;
   protected prepareSendMessagesRequest?: PrepareSendMessagesRequest<UI_MESSAGE>;
   protected prepareReconnectToStreamRequest?: PrepareReconnectToStreamRequest;
@@ -134,13 +152,17 @@ export abstract class HttpChatTransport<UI_MESSAGE extends UIMessage>
     abortSignal,
     ...options
   }: Parameters<ChatTransport<UI_MESSAGE>['sendMessages']>[0]) {
+    const resolvedBody = await resolve(this.body);
+    const resolvedHeaders = await resolve(this.headers);
+    const resolvedCredentials = await resolve(this.credentials);
+
     const preparedRequest = await this.prepareSendMessagesRequest?.({
       api: this.api,
       id: options.chatId,
       messages: options.messages,
-      body: { ...this.body, ...options.body },
-      headers: { ...this.headers, ...options.headers },
-      credentials: this.credentials,
+      body: { ...resolvedBody, ...options.body },
+      headers: { ...resolvedHeaders, ...options.headers },
+      credentials: resolvedCredentials,
       requestMetadata: options.metadata,
       trigger: options.trigger,
       messageId: options.messageId,
@@ -150,19 +172,19 @@ export abstract class HttpChatTransport<UI_MESSAGE extends UIMessage>
     const headers =
       preparedRequest?.headers !== undefined
         ? preparedRequest.headers
-        : { ...this.headers, ...options.headers };
+        : { ...resolvedHeaders, ...options.headers };
     const body =
       preparedRequest?.body !== undefined
         ? preparedRequest.body
         : {
-            ...this.body,
+            ...resolvedBody,
             ...options.body,
             id: options.chatId,
             messages: options.messages,
             trigger: options.trigger,
             messageId: options.messageId,
           };
-    const credentials = preparedRequest?.credentials ?? this.credentials;
+    const credentials = preparedRequest?.credentials ?? resolvedCredentials;
 
     // avoid caching globalThis.fetch in case it is patched by other libraries
     const fetch = this.fetch ?? globalThis.fetch;
@@ -194,21 +216,25 @@ export abstract class HttpChatTransport<UI_MESSAGE extends UIMessage>
   async reconnectToStream(
     options: Parameters<ChatTransport<UI_MESSAGE>['reconnectToStream']>[0],
   ): Promise<ReadableStream<UIMessageChunk> | null> {
+    const resolvedBody = await resolve(this.body);
+    const resolvedHeaders = await resolve(this.headers);
+    const resolvedCredentials = await resolve(this.credentials);
+
     const preparedRequest = await this.prepareReconnectToStreamRequest?.({
       api: this.api,
       id: options.chatId,
-      body: { ...this.body, ...options.body },
-      headers: { ...this.headers, ...options.headers },
-      credentials: this.credentials,
+      body: { ...resolvedBody, ...options.body },
+      headers: { ...resolvedHeaders, ...options.headers },
+      credentials: resolvedCredentials,
       requestMetadata: options.metadata,
     });
 
     const api = preparedRequest?.api ?? `${this.api}/${options.chatId}/stream`;
     const headers =
       preparedRequest?.headers !== undefined
         ? preparedRequest.headers
-        : { ...this.headers, ...options.headers };
-    const credentials = preparedRequest?.credentials ?? this.credentials;
+        : { ...resolvedHeaders, ...options.headers };
+    const credentials = preparedRequest?.credentials ?? resolvedCredentials;
 
     // avoid caching globalThis.fetch in case it is patched by other libraries
     const fetch = this.fetch ?? globalThis.fetch;