transport: move /api/chat default from core to Vercel layer

lawrence-forooghian · claude · lawrence-forooghian · commit e3729c88df07 · 2026-04-09T13:54:24.000-03:00
The default HTTP endpoint "/api/chat" is the Vercel AI SDK's default
(set by DefaultChatTransport), but we were setting it in our generic
core transport. This violates the two-layer architecture principle
that the generic layer should know nothing about Vercel.

Make `api` required on core `ClientTransportOptions` and apply the
"/api/chat" default in the Vercel layer's `createClientTransport`
factory.

To avoid forcing useChat users to call `useClientTransport` (where
`api` would now be required), `useChatTransport` now returns a
`ChatTransportHandle` containing both the `ChatTransport` and the
underlying `ClientTransport`. Previously it only returned the
`ChatTransport`, so callers had no way to access the transport it
created internally — they needed a separate `useClientTransport`
call. The handle lets useChat users get the Vercel default without
extra configuration, while still having access to the transport for
`useMessageSync`, `useActiveTurns`, `useView`, etc.

[AIT-676]

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -144,15 +144,13 @@ export async function POST(req: Request) {
 
 import { useChat } from '@ai-sdk/react';
 import { useChannel } from 'ably/react';
-import { useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
+import { useActiveTurns, useView } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
 function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
   const { channel } = useChannel({ channelName: chatId });
 
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
-  const chatTransport = useChatTransport(transport);
+  const { chatTransport, transport } = useChatTransport({ channel, clientId });
 
   const { messages, setMessages, sendMessage, stop } = useChat({
     id: chatId,
diff --git a/demo/vercel/react/use-chat/src/app/chat.tsx b/demo/vercel/react/use-chat/src/app/chat.tsx
@@ -2,9 +2,8 @@
 
 import { useChat } from '@ai-sdk/react';
 import { useChannel } from 'ably/react';
-import { useClientTransport, useActiveTurns, useView, useAblyMessages } from '@ably/ai-transport/react';
+import { useActiveTurns, useView, useAblyMessages } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { useState } from 'react';
 import { MessageList } from './components/message-list';
 import { DebugPane } from './components/debug-pane';
@@ -17,8 +16,7 @@ export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clien
   const { channel } = useChannel({ channelName: chatId });
 
   // Create transport immediately (subscribes before attach — RTL7g)
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
-  const chatTransport = useChatTransport(transport);
+  const { chatTransport, transport } = useChatTransport({ channel, clientId });
 
   const { setMessages, sendMessage, stop, status, regenerate } = useChat({
     id: chatId,
diff --git a/demo/vercel/react/use-client-transport/src/app/components/chat.tsx b/demo/vercel/react/use-client-transport/src/app/components/chat.tsx
@@ -28,6 +28,7 @@ export function Chat({ chatId, clientId, historyLimit }: ChatProps) {
     channel,
     codec: UIMessageCodec,
     clientId,
+    api: '/api/chat',
     body: () => ({ id: chatId }),
   });
 
diff --git a/docs/concepts/transport.md b/docs/concepts/transport.md
@@ -83,7 +83,7 @@ In React, the hooks handle subscriptions and state management:
 import { useClientTransport, useView } from '@ably/ai-transport/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId, api: '/api/chat' });
 const { nodes, send } = useView(transport);
 ```
 
diff --git a/docs/features/branching.md b/docs/features/branching.md
@@ -135,7 +135,7 @@ With a single view, navigating to a different branch in one part of the UI chang
 ```typescript
 import { useClientTransport, useCreateView, useView } from '@ably/ai-transport/react';
 
-const transport = useClientTransport({ channel, codec, clientId });
+const transport = useClientTransport({ channel, codec, clientId, api: '/api/chat' });
 
 // Default view for the left pane
 const left = useView(transport, { limit: 50 });
diff --git a/docs/features/multi-client.md b/docs/features/multi-client.md
@@ -15,10 +15,10 @@ No special API is needed. Connect two clients to the same channel name, and mess
 
 ```typescript
 // Client A
-const transportA = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-a' });
+const transportA = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-a', api: '/api/chat' });
 
 // Client B (different browser tab, device, or user)
-const transportB = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-b' });
+const transportB = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-b', api: '/api/chat' });
 
 // When Client A sends a message and the server streams a response,
 // Client B sees both the user message and the assistant response
diff --git a/docs/frameworks/vercel-ai-sdk.md b/docs/frameworks/vercel-ai-sdk.md
@@ -20,13 +20,10 @@ The Vercel AI SDK provides model abstraction, streaming primitives, and React ho
 Wrap the transport in a `ChatTransport` adapter and pass it to Vercel's `useChat`. Message state is managed by `useChat` - the transport delivers messages over Ably instead of HTTP.
 
 ```typescript
-import { useClientTransport } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { useChat } from '@ai-sdk/react';
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
-const chatTransport = useChatTransport(transport);
+const { chatTransport, transport } = useChatTransport({ channel, clientId });
 
 const { messages, setMessages, sendMessage, stop } = useChat({
   id: chatId,
@@ -37,7 +34,7 @@ const { messages, setMessages, sendMessage, stop } = useChat({
 useMessageSync(transport, setMessages);
 ```
 
-`useChatTransport` wraps the core transport into the `ChatTransport` interface that `useChat` expects. `useMessageSync` pushes the transport's authoritative message list into `useChat`'s state - this is how messages from other clients appear.
+`useChatTransport` creates the core transport and wraps it into the `ChatTransport` interface that `useChat` expects, returning both as `{ chatTransport, transport }`. `useMessageSync` pushes the transport's authoritative message list into `useChat`'s state - this is how messages from other clients appear.
 
 ### Generic hooks path (more control)
 
@@ -51,7 +48,7 @@ import {
 } from '@ably/ai-transport/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId, api: '/api/chat' });
 const { nodes, hasOlder, loading, loadOlder, send, regenerate, edit, select, getSelectedIndex, getSiblings, hasSiblings } = useView(transport, { limit: 30 });
 const activeTurns = useActiveTurns(transport);
 ```
diff --git a/docs/get-started/vercel-use-chat.md b/docs/get-started/vercel-use-chat.md
@@ -155,36 +155,32 @@ Wire up `useChat` with the AI Transport hooks:
 
 import { useChat } from '@ai-sdk/react';
 import { useChannel, ChannelProvider } from 'ably/react';
-import { useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
+import { useActiveTurns, useView } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { useState } from 'react';
 
 function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string }) {
   const { channel } = useChannel({ channelName: chatId });
   const [input, setInput] = useState('');
 
-  // 1. Create the core transport - subscribes to the Ably channel and decodes
-  //    incoming messages through UIMessageCodec
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+  // 1. Create the transport and chat adapter in one step - subscribes to the
+  //    Ably channel and decodes incoming messages through UIMessageCodec
+  const { chatTransport, transport } = useChatTransport({ channel, clientId });
 
-  // 2. Wrap it for useChat compatibility
-  const chatTransport = useChatTransport(transport);
-
-  // 3. Use Vercel's useChat with the wrapped transport
+  // 2. Use Vercel's useChat with the chat transport adapter
   const { messages, setMessages, sendMessage, stop } = useChat({
     id: chatId,
     transport: chatTransport,
   });
 
-  // 4. Sync transport messages into useChat's state (for observer messages)
+  // 3. Sync transport messages into useChat's state (for observer messages)
   useMessageSync(transport, setMessages);
 
-  // 5. Track active turns for loading state
+  // 4. Track active turns for loading state
   const activeTurns = useActiveTurns(transport);
   const isStreaming = activeTurns.size > 0;
 
-  // 6. Load history on mount
+  // 5. Load history on mount
   useView(transport, { limit: 30 });
 
   return (
@@ -245,12 +241,11 @@ Open `http://localhost:3000`. Type a message - you'll see tokens stream in real
 
 ## What's happening
 
-1. `useClientTransport` creates a transport that subscribes to the Ably channel before it attaches - no messages are lost.
-2. `useChatTransport` wraps the transport into Vercel's `ChatTransport` interface, which `useChat` expects.
-3. When you send a message, `useChat` calls the chat transport's `sendMessages`, which fires an HTTP POST to `/api/chat` and opens a stream on the Ably channel.
-4. The server creates a turn, publishes user messages, streams the LLM response through the encoder to the channel, and publishes a turn-end event.
-5. The client transport decodes incoming Ably messages through `UIMessageCodec` and routes them to the stream.
-6. `useMessageSync` syncs messages from the transport (including messages from other clients) into `useChat`'s state.
+1. `useChatTransport` creates a transport that subscribes to the Ably channel before it attaches (no messages are lost), and wraps it into Vercel's `ChatTransport` interface, which `useChat` expects. It returns both the `chatTransport` adapter and the underlying `transport`.
+2. When you send a message, `useChat` calls the chat transport's `sendMessages`, which fires an HTTP POST to `/api/chat` and opens a stream on the Ably channel.
+3. The server creates a turn, publishes user messages, streams the LLM response through the encoder to the channel, and publishes a turn-end event.
+4. The client transport decodes incoming Ably messages through `UIMessageCodec` and routes them to the stream.
+5. `useMessageSync` syncs messages from the transport (including messages from other clients) into `useChat`'s state.
 
 For the conceptual details, see [Client and server transport](../concepts/transport.md) and [Turns](../concepts/turns.md).
 
diff --git a/docs/get-started/vercel-use-client-transport.md b/docs/get-started/vercel-use-client-transport.md
@@ -37,6 +37,7 @@ function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string })
     channel,
     codec: UIMessageCodec,
     clientId,
+    api: '/api/chat',
     body: () => ({ id: chatId }),
   });
 
diff --git a/docs/reference/react-hooks.md b/docs/reference/react-hooks.md
@@ -21,7 +21,7 @@ const transport = useClientTransport<TEvent, TMessage>(options: ClientTransportO
 | `options.channel` | `Ably.RealtimeChannel` | The Ably channel to subscribe to |
 | `options.codec` | `Codec<TEvent, TMessage>` | The codec for encoding/decoding |
 | `options.clientId` | `string?` | Client identity, sent to the server in POST body |
-| `options.api` | `string?` | Server endpoint URL. Default: `"/api/chat"` |
+| `options.api` | `string` | Server endpoint URL (required) |
 | `options.headers` | `Record<string, string> \| (() => Record<string, string>)?` | HTTP POST headers. Function form for dynamic values |
 | `options.body` | `Record<string, unknown> \| (() => Record<string, unknown>)?` | Additional POST body fields. Function form for dynamic values |
 | `options.credentials` | `RequestCredentials?` | Fetch credentials mode |
@@ -239,30 +239,38 @@ Import from `@ably/ai-transport/vercel/react`.
 
 ### useChatTransport
 
-Create and memoize a `ChatTransport` for Vercel's `useChat` hook.
+Create and memoize a `ChatTransport` and its underlying `ClientTransport` for Vercel's `useChat` hook.
 
 ```typescript
-const chatTransport = useChatTransport(
-  transportOrOptions: ClientTransport<UIMessageChunk, UIMessage> | VercelClientTransportOptions,
+// From options — creates the transport internally
+const { chatTransport, transport } = useChatTransport(
+  options: VercelClientTransportOptions,
+  chatOptions?: ChatTransportOptions,
+);
+
+// From an existing transport — wraps it
+const { chatTransport, transport } = useChatTransport(
+  transport: ClientTransport<UIMessageChunk, UIMessage>,
   chatOptions?: ChatTransportOptions,
 );
 ```
 
 | Parameter | Type | Description |
 |---|---|---|
-| `transportOrOptions` | `ClientTransport \| VercelClientTransportOptions` | An existing transport, or options to create one |
-| `chatOptions` | `ChatTransportOptions?` | Optional hooks for customizing request construction |
+| `transportOrOptions` | `ClientTransport \| VercelClientTransportOptions` | An existing transport to wrap, or options to create one |
+| `chatOptions` | `ChatTransportOptions?` | Optional hooks for customising request construction |
 
-**Returns:** `ChatTransport` - compatible with `useChat`'s `transport` option.
+**Returns:** `ChatTransportHandle`
 
-Two usage patterns:
-1. **Wrap an existing transport** - pass a `ClientTransport` created by `useClientTransport`
-2. **Create internally** - pass `VercelClientTransportOptions` and the hook creates the transport with `UIMessageCodec`
+| Property | Type | Description |
+|---|---|---|
+| `chatTransport` | `ChatTransport` | Compatible with `useChat`'s `transport` option |
+| `transport` | `ClientTransport<UIMessageChunk, UIMessage>` | The underlying transport for use with `useMessageSync`, `useActiveTurns`, `useView`, etc. |
 
-`ChatTransportOptions.prepareSendMessagesRequest` lets you customize the HTTP POST body and headers:
+`ChatTransportOptions.prepareSendMessagesRequest` lets you customise the HTTP POST body and headers:
 
 ```typescript
-const chatTransport = useChatTransport(transport, {
+const { chatTransport } = useChatTransport({ channel, clientId }, {
   prepareSendMessagesRequest: (context) => ({
     body: { history: context.history, sessionId: mySessionId },
     headers: { 'x-custom': 'value' },
diff --git a/src/core/transport/client-transport.ts b/src/core/transport/client-transport.ts
@@ -132,7 +132,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     this._channel = options.channel;
     this._codec = options.codec;
     this._clientId = options.clientId;
-    this._api = options.api ?? '/api/chat';
+    this._api = options.api;
     this._credentials = options.credentials;
     // CAST: TS can't narrow options.headers/body inside a closure because the outer
     // object is mutable. The truthiness check on the preceding line guarantees non-nullish.
diff --git a/src/core/transport/types.ts b/src/core/transport/types.ts
@@ -210,8 +210,8 @@ export interface ClientTransportOptions<TEvent, TMessage> {
   /** The client's identity. Sent to the server in the POST body. */
   clientId?: string;
 
-  /** Server endpoint URL for the HTTP POST. Defaults to `"/api/chat"`. */
-  api?: string;
+  /** Server endpoint URL for the HTTP POST. */
+  api: string;
 
   /** Headers for the HTTP POST. Function form for dynamic values (e.g. auth tokens). */
   headers?: Record<string, string> | (() => Record<string, string>);
diff --git a/src/vercel/react/index.ts b/src/vercel/react/index.ts
@@ -1,4 +1,5 @@
 // Vercel-specific React hooks
 export type { ChatTransport } from '../transport/chat-transport.js';
+export type { ChatTransportHandle } from './use-chat-transport.js';
 export { useChatTransport } from './use-chat-transport.js';
 export { useMessageSync } from './use-message-sync.js';
diff --git a/src/vercel/react/use-chat-transport.ts b/src/vercel/react/use-chat-transport.ts
@@ -9,6 +9,10 @@
  * Both forms accept an optional second argument for ChatTransportOptions
  * (e.g. prepareSendMessagesRequest for the persistence pattern).
  *
+ * Returns a {@link ChatTransportHandle} containing both the ChatTransport
+ * (for useChat) and the underlying ClientTransport (for useMessageSync,
+ * useActiveTurns, useView, etc.).
+ *
  * The hook does NOT auto-close the transport on unmount. Channel lifecycle is
  * managed by the Ably provider (useChannel). Auto-closing would break React
  * Strict Mode. Call chatTransport.close() explicitly if needed.
@@ -23,6 +27,18 @@ import { createChatTransport } from '../transport/chat-transport.js';
 import type { VercelClientTransportOptions } from '../transport/index.js';
 import { createClientTransport as createCoreClientTransport } from '../transport/index.js';
 
+/**
+ * Handle returned by {@link useChatTransport}, providing both the
+ * Vercel-compatible {@link ChatTransport} and the underlying
+ * {@link ClientTransport} for use with generic hooks.
+ */
+export interface ChatTransportHandle {
+  /** The ChatTransport adapter for Vercel's useChat hook. */
+  chatTransport: ChatTransport;
+  /** The underlying ClientTransport for useMessageSync, useActiveTurns, useView, etc. */
+  transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
+}
+
 /**
  * Type guard: distinguish an existing ClientTransport from options.
  * @param x - Either a transport instance or options object.
@@ -33,28 +49,34 @@ const isClientTransport = (
 ): x is ClientTransport<AI.UIMessageChunk, AI.UIMessage> => 'view' in x;
 
 /**
- * Create and memoize a {@link ChatTransport} for Vercel's useChat hook.
+ * Create and memoize a {@link ChatTransportHandle} for Vercel's useChat hook.
  *
  * Pass an existing `ClientTransport` to wrap it, or pass
  * `VercelClientTransportOptions` to create one internally with UIMessageCodec.
  * @param transportOrOptions - An existing ClientTransport, or options to create one.
- * @param chatOptions - Optional hooks for customizing request construction.
- * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
+ * @param chatOptions - Optional hooks for customising request construction.
+ * @returns A {@link ChatTransportHandle} containing the ChatTransport and underlying ClientTransport.
  */
 export const useChatTransport = (
   transportOrOptions: ClientTransport<AI.UIMessageChunk, AI.UIMessage> | VercelClientTransportOptions,
   chatOptions?: ChatTransportOptions,
-): ChatTransport => {
-  const chatTransportRef = useRef<ChatTransport | null>(null);
+): ChatTransportHandle => {
+  const handleRef = useRef<ChatTransportHandle | null>(null);
 
-  if (chatTransportRef.current === null) {
+  if (handleRef.current === null) {
     if (isClientTransport(transportOrOptions)) {
-      chatTransportRef.current = createChatTransport(transportOrOptions, chatOptions);
+      handleRef.current = {
+        chatTransport: createChatTransport(transportOrOptions, chatOptions),
+        transport: transportOrOptions,
+      };
     } else {
       const transport = createCoreClientTransport(transportOrOptions);
-      chatTransportRef.current = createChatTransport(transport, chatOptions);
+      handleRef.current = {
+        chatTransport: createChatTransport(transport, chatOptions),
+        transport,
+      };
     }
   }
 
-  return chatTransportRef.current;
+  return handleRef.current;
 };
diff --git a/src/vercel/transport/index.ts b/src/vercel/transport/index.ts
@@ -27,8 +27,11 @@ import type {
 } from '../../core/transport/types.js';
 import { UIMessageCodec } from '../codec/index.js';
 
-/** Options for creating a Vercel client transport. Same as core options but without the codec field. */
-export type VercelClientTransportOptions = Omit<ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
+/** Core client transport options with Vercel AI SDK types pre-applied. */
+type CoreClientOpts = ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>;
+
+/** Options for creating a Vercel client transport. Same as core options but without the codec field, and with `api` optional (defaults to `"/api/chat"`). */
+export type VercelClientTransportOptions = Omit<CoreClientOpts, 'codec' | 'api'> & Partial<Pick<CoreClientOpts, 'api'>>;
 
 /** Options for creating a Vercel server transport. Same as core options but without the codec field. */
 export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
@@ -42,7 +45,14 @@ export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMess
  */
 export const createClientTransport = (
   options: VercelClientTransportOptions,
-): ClientTransport<AI.UIMessageChunk, AI.UIMessage> => createCoreClientTransport({ ...options, codec: UIMessageCodec });
+): ClientTransport<AI.UIMessageChunk, AI.UIMessage> =>
+  createCoreClientTransport({
+    ...options,
+    codec: UIMessageCodec,
+    // Mirrors the Vercel AI SDK's HttpChatTransport default (Next.js convention).
+    // Hardcoded because the AI SDK does not export this as a constant.
+    api: options.api ?? '/api/chat',
+  });
 
 /**
  * Create a server-side transport pre-configured with the Vercel AI SDK codec.
diff --git a/test/core/transport/client-transport.integration.test.ts b/test/core/transport/client-transport.integration.test.ts
diff --git a/test/core/transport/client-transport.test.ts b/test/core/transport/client-transport.test.ts
diff --git a/test/react/use-client-transport.test.ts b/test/react/use-client-transport.test.ts
diff --git a/test/vercel/react/use-chat-transport.test.ts b/test/vercel/react/use-chat-transport.test.ts
diff --git a/test/vercel/transport/index.test.ts b/test/vercel/transport/index.test.ts
