options doc for PR — TODO remove

Author: lawrence-forooghian

api-option-options.md

@@ -0,0 +1,78 @@
+# AIT-676: Options for the `api` default
+
+## Background
+
+The default HTTP endpoint `"/api/chat"` is currently hardcoded in the generic core transport, but it's a Vercel AI SDK / Next.js convention. It should not live in the generic layer.
+
+The Vercel AI SDK's own `HttpChatTransport` defaults to `"/api/chat"` internally — it's not exported as a constant, so we'd have to hardcode it too if we want to mirror the default.
+
+Two options for how the README `useChat` example changes:
+
+---
+
+## 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.
+
+```diff
+ 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);
+
+   const { messages, setMessages, sendMessage, stop } = useChat({
+     id: chatId,
+     transport: chatTransport,
+   });
+
+   useMessageSync(transport, setMessages);
+
+   const activeTurns = useActiveTurns(transport);
+   const view = useView(transport, { limit: 30 });
+```
+
+**Pros:** Simple implementation (one small commit), 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
+
+Make `api` required in core but optional in the Vercel layer. `useChatTransport` gains the ability to create the transport internally (applying the `"/api/chat"` default) and returns both the `ChatTransport` and the underlying `ClientTransport`.
+
+```diff
+ 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,
+     transport: chatTransport,
+   });
+
+   useMessageSync(transport, setMessages);
+
+   const activeTurns = useActiveTurns(transport);
+   const view = useView(transport, { limit: 30 });
+```
+
+**Pros:** Matches Vercel's own ergonomics (no endpoint needed), fewer imports, fewer lines.
+**Cons:** More complex implementation — new `ChatTransportHandle` return type, `useChatTransport` takes on transport creation responsibility.