[AIT-676] Move /api/chat default from core to Vercel layer

[lawrence-forooghian]

Note: This is a Claude-generated thing but it reflects the result of my thinking and I've read through it all.

Summary

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.

Options considered

This PR implements Option B below. Feedback welcome on whether Option A would be preferable.

Both diffs are against the Client - React with useChat section of the README.

Option A: Make api required everywhere

Simplest change. Remove the default from core, make api required on ClientTransportOptions. All callers must specify it explicitly. No new types or return type changes.

 import { useChat } from '@ai-sdk/react';
 import { useChannel } from 'ably/react';
 import { useClientTransport, 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 transport = useClientTransport({ channel, codec: UIMessageCodec, clientId, api: '/api/chat' });
   const chatTransport = useChatTransport(transport);

Pros: Simple implementation, explicit, no new abstractions.
Cons: useChat users must specify api even though Vercel's own default transport doesn't require it.

Option B: Preserve the default in the Vercel layer (this PR)

Make api required in core but optional in the Vercel layer. useChatTransport returns both the ChatTransport and the underlying ClientTransport.

 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 });

Pros: Matches Vercel's own ergonomics (no endpoint needed), fewer imports, fewer lines.
Cons: Was there perhaps some motivation that I've missed — perhaps didactic, perhaps something else? — for requiring users to create the ClientTransport explicitly?

🤖 Generated with Claude Code