@ably/ai-transport 0.0.1 → 0.1.0

package/README.md

@@ -89,14 +89,14 @@ import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
 import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { TreeNode } from '@ably/ai-transport';
 
 interface ChatRequestBody {
   turnId: string;
   clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
-  id: string;
+  messages: TreeNode<UIMessage>[];
+  history?: TreeNode<UIMessage>[];
+  chatId: string;
   forkOf?: string;
   parent?: string | null;
 }
@@ -104,9 +104,9 @@ interface ChatRequestBody {
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 export async function POST(req: Request) {
-  const { messages, history, id, turnId, clientId, forkOf, parent } = (await req.json()) as ChatRequestBody;
+  const { messages, history, chatId, turnId, clientId, forkOf, parent } = (await req.json()) as ChatRequestBody;
 
-  const channel = ably.channels.get(id);
+  const channel = ably.channels.get(chatId);
   const transport = createServerTransport({ channel });
   const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
 
@@ -120,7 +120,7 @@ export async function POST(req: Request) {
   const newMsgs = messages.map((m) => m.message);
 
   const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
+    model: anthropic('claude-sonnet-4-6'),
     system: 'You are a helpful assistant.',
     messages: await convertToModelMessages([...historyMsgs, ...newMsgs]),
     abortSignal: turn.abortSignal,
@@ -143,26 +143,26 @@ export async function POST(req: Request) {
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import { useChannel } from 'ably/react';
-import { useClientTransport, useActiveTurns, useHistory } from '@ably/ai-transport/react';
-import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import {
+  ChatTransportProvider,
+  useChatTransport,
+  useMessageSync,
+  useActiveTurns,
+  useView,
+} from '@ably/ai-transport/vercel/react';
 
-function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
-  const { channel } = useChannel({ channelName: chatId });
-
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
-  const chatTransport = useChatTransport(transport);
+function ChatInner({ chatId }: { chatId: string }) {
+  const { chatTransport } = useChatTransport();
 
   const { messages, setMessages, sendMessage, stop } = useChat({
     id: chatId,
     transport: chatTransport,
   });
 
-  useMessageSync(transport, setMessages);
+  useMessageSync({ setMessages });
 
-  const activeTurns = useActiveTurns(transport);
-  const history = useHistory(transport, { limit: 30 });
+  const activeTurns = useActiveTurns();
+  useView({ limit: 30 });
 
   return (
     <div>
@@ -189,6 +189,17 @@ function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
     </div>
   );
 }
+
+function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
+  return (
+    <ChatTransportProvider
+      channelName={chatId}
+      clientId={clientId}
+    >
+      <ChatInner chatId={chatId} />
+    </ChatTransportProvider>
+  );
+}
 ```
 
 ### Authentication
@@ -271,8 +282,8 @@ transport.close();
 
 ## Package exports
 
-| Export path                               | Purpose                                     | Peer dependencies     |
-| ----------------------------------------- | ------------------------------------------- | --------------------- |
+| Export path                       | Purpose                                     | Peer dependencies     |
+| --------------------------------- | ------------------------------------------- | --------------------- |
 | `@ably/ai-transport`              | Core transport, codec interfaces, utilities | `ably`                |
 | `@ably/ai-transport/react`        | React hooks for any codec                   | `ably`, `react`       |
 | `@ably/ai-transport/vercel`       | Vercel AI SDK codec, transport factories    | `ably`, `ai`          |
@@ -280,19 +291,15 @@ transport.close();
 
 ### React hooks
 
-| Hook                  | Entry point     | Description                                         |
-| --------------------- | --------------- | --------------------------------------------------- |
-| `useClientTransport`  | `/react`        | Create and memoize a client transport instance      |
-| `useMessages`         | `/react`        | Subscribe to decoded messages                       |
-| `useSend`             | `/react`        | Stable send callback                                |
-| `useRegenerate`       | `/react`        | Regenerate a message (fork the conversation)        |
-| `useEdit`             | `/react`        | Edit a message and regenerate from that point       |
-| `useActiveTurns`      | `/react`        | Track active turns by client ID                     |
-| `useHistory`          | `/react`        | Paginate through conversation history               |
-| `useConversationTree` | `/react`        | Navigate branches in a forked conversation          |
-| `useAblyMessages`     | `/react`        | Access raw Ably messages                            |
-| `useChatTransport`    | `/vercel/react` | Wrap transport for Vercel's `useChat`               |
-| `useMessageSync`      | `/vercel/react` | Sync transport state with `useChat`'s `setMessages` |
+| Hook                 | Entry point     | Description                                         |
+| -------------------- | --------------- | --------------------------------------------------- |
+| `useClientTransport` | `/react`        | Create and memoize a client transport instance      |
+| `useView`            | `/react`        | Subscribe to messages with history loading          |
+| `useActiveTurns`     | `/react`        | Track active turns by client ID                     |
+| `useTree`            | `/react`        | Navigate branches in a forked conversation          |
+| `useAblyMessages`    | `/react`        | Access raw Ably messages                            |
+| `useChatTransport`   | `/vercel/react` | Wrap transport for Vercel's `useChat`               |
+| `useMessageSync`     | `/vercel/react` | Sync transport state with `useChat`'s `setMessages` |
 
 ---
 
@@ -303,7 +310,7 @@ transport.close();
 Two mechanisms cover different failure modes:
 
 - **Network blips** - Ably's connection protocol automatically reconnects and delivers any messages published while the client was disconnected. No application code required.
-- **Resumable streams** - A client that joins or rejoins a channel mid-response (after a page refresh, on a new device, or as a second participant) receives the in-progress stream immediately on subscribing. Load previous conversation history from the channel via `history()`, or from your own database.
+- **Resumable streams** - A client that joins or rejoins a channel mid-response (after a page refresh, on a new device, or as a second participant) receives the in-progress stream immediately on subscribing. Load previous conversation history from the channel via `view.loadOlder()`, or from your own database.
 
 ### Cancellation
 
@@ -316,7 +323,7 @@ await transport.cancel({ turnId: 'turn-abc' });
 
 // Server: the turn's abortSignal fires automatically
 const result = streamText({
-  model: anthropic('claude-sonnet-4-20250514'),
+  model: anthropic('claude-sonnet-4-6'),
   messages,
   abortSignal: turn.abortSignal, // Aborted when client cancels
 });
@@ -334,7 +341,7 @@ const turn = await transport.regenerate(assistantMessageId);
 const turn = await transport.edit(userMessageId, [newMessage]);
 
 // Navigate branches
-const tree = transport.getTree();
+const tree = transport.tree;
 const siblings = tree.getSiblings(messageId);
 tree.select(messageId, 1); // Switch to second branch
 ```
@@ -344,22 +351,22 @@ tree.select(messageId, 1); // Switch to second branch
 Load previous conversation state when a client joins or returns to a session.
 
 ```typescript
-const page = await transport.history({ limit: 50 });
-console.log(page.items); // Decoded messages
+const view = transport.view;
+await view.loadOlder(50);
+// view.flattenNodes() returns the messages loaded so far
 
-if (page.hasNext()) {
-  const older = await page.next();
-}
+// Load more older messages
+await view.loadOlder(50);
 ```
 
 ### Events
 
 ```typescript
-transport.on('message', () => {
-  console.log(transport.getMessages());
+transport.view.on('update', () => {
+  console.log(transport.view.flattenNodes().map((n) => n.message));
 });
 
-transport.on('turn', (event) => {
+transport.tree.on('turn', (event) => {
   console.log(event.turnId, event.type); // 'x-ably-turn-start' | 'x-ably-turn-end'
 });
 
@@ -377,7 +384,7 @@ Detailed documentation lives in the [`docs/`](./docs/) directory:
 - **[Concepts](./docs/concepts/)** - [Transport architecture](./docs/concepts/transport.md), [Turns](./docs/concepts/turns.md)
 - **[Get started](./docs/get-started/)** - [Vercel AI SDK with useChat](./docs/get-started/vercel-use-chat.md), [Vercel AI SDK with useClientTransport](./docs/get-started/vercel-use-client-transport.md)
 - **[Frameworks](./docs/frameworks/)** - [Vercel AI SDK](./docs/frameworks/vercel-ai-sdk.md)
-- **[Features](./docs/features/)** - [Streaming](./docs/features/streaming.md), [Cancellation](./docs/features/cancel.md), [Barge-in](./docs/features/barge-in.md), [Optimistic updates](./docs/features/optimistic-updates.md), [History](./docs/features/history.md), [Branching](./docs/features/branching.md), [Multi-client sync](./docs/features/multi-client.md), [Tool calls](./docs/features/tool-calls.md), [Concurrent turns](./docs/features/concurrent-turns.md)
+- **[Features](./docs/features/)** - [Streaming](./docs/features/streaming.md), [Cancellation](./docs/features/cancel.md), [Interruption](./docs/features/interruption.md), [Optimistic updates](./docs/features/optimistic-updates.md), [History](./docs/features/history.md), [Branching](./docs/features/branching.md), [Multi-client sync](./docs/features/multi-client.md), [Concurrent turns](./docs/features/concurrent-turns.md)
 - **[Reference](./docs/reference/)** - [React hooks](./docs/reference/react-hooks.md), [Error codes](./docs/reference/error-codes.md)
 - **[Internals](./docs/internals/)** - Architecture details for contributors
 
@@ -410,7 +417,7 @@ npm run precommit         # format:check + lint + typecheck
 src/
 ├── core/               # Generic transport and codec (no framework deps)
 │   ├── codec/          # Codec interfaces and core encoder/decoder
-│   └── transport/      # ClientTransport, ServerTransport, ConversationTree
+│   └── transport/      # ClientTransport, ServerTransport, Tree
 ├── react/              # React hooks for any codec
 ├── vercel/             # Vercel AI SDK codec and transport adapters
 │   ├── codec/          # UIMessageCodec