@ably/ai-transport 0.0.1

package/dist/vercel/react/index.d.ts

@@ -0,0 +1,3 @@
+export type { ChatTransport } from '../transport/chat-transport.js';
+export { useChatTransport } from './use-chat-transport.js';
+export { useMessageSync } from './use-message-sync.js';

package/dist/vercel/react/use-chat-transport.d.ts

@@ -0,0 +1,29 @@
+import { ClientTransport } from '../../core/transport/types.js';
+import { ChatTransport, ChatTransportOptions } from '../transport/chat-transport.js';
+import { VercelClientTransportOptions } from '../transport/index.js';
+/**
+ * useChatTransport: wraps a core ClientTransport into the ChatTransport
+ * shape that Vercel's useChat expects.
+ *
+ * Accepts either an existing ClientTransport or options to create one:
+ * - From an existing ClientTransport — wraps it directly
+ * - From options — creates a ClientTransport with UIMessageCodec and wraps it
+ *
+ * Both forms accept an optional second argument for ChatTransportOptions
+ * (e.g. prepareSendMessagesRequest for the persistence pattern).
+ *
+ * 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.
+ */
+import type * as AI from 'ai';
+/**
+ * Create and memoize a {@link ChatTransport} 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.
+ */
+export declare const useChatTransport: (transportOrOptions: ClientTransport<AI.UIMessageChunk, AI.UIMessage> | VercelClientTransportOptions, chatOptions?: ChatTransportOptions) => ChatTransport;

package/dist/vercel/react/use-message-sync.d.ts

@@ -0,0 +1,19 @@
+import { ClientTransport } from '../../core/transport/types.js';
+/**
+ * useMessageSync: wires transport message lifecycle events into useChat's setMessages.
+ *
+ * Subscribes to the transport's 'message' event and replaces messages state
+ * with the transport's authoritative message list. Events fire immediately
+ * on every store update (including during active streaming), so this hook
+ * keeps React state in sync in real time.
+ *
+ * Returns the unsubscribe function in the useEffect cleanup so handlers
+ * are removed on unmount or when dependencies change.
+ */
+import type * as AI from 'ai';
+/**
+ * Wire transport message updates into useChat's `setMessages` updater.
+ * @param transport - The client transport to observe, or null/undefined if not yet available.
+ * @param setMessages - The `setMessages` updater function from useChat.
+ */
+export declare const useMessageSync: (transport: ClientTransport<unknown, AI.UIMessage> | null | undefined, setMessages: (updater: (prev: AI.UIMessage[]) => AI.UIMessage[]) => void) => void;

package/dist/vercel/transport/chat-transport.d.ts

@@ -0,0 +1,118 @@
+import { ClientTransport, CloseOptions } from '../../core/transport/types.js';
+/**
+ * Vercel chat transport: wraps a core ClientTransport to satisfy the
+ * ChatTransport interface that useChat expects.
+ *
+ * This is a thin adapter — the real logic lives in the core transport.
+ * The chat transport maps Vercel's sendMessages/reconnectToStream contract
+ * to the core transport's send/cancel methods.
+ *
+ * useChat manages message state before calling sendMessages:
+ * - submit-message: appends the new user message, passes the full array
+ * - regenerate-message: truncates after the target, passes the truncated array
+ *
+ * The adapter uses `trigger` to determine the history/messages split:
+ * - submit-message: last message is new (publish to channel), rest is history
+ * - regenerate-message: no new messages, entire array is history
+ */
+import type * as AI from 'ai';
+/**
+ * Context passed to {@link ChatTransportOptions.prepareSendMessagesRequest} for
+ * customizing the HTTP POST body and headers.
+ */
+export interface SendMessagesRequestContext {
+    /** Chat session ID (from useChat's id). */
+    id?: string;
+    /** What triggered the request: user sent a message, or requested regeneration. */
+    trigger: 'submit-message' | 'regenerate-message';
+    /**
+     * The message ID for regeneration requests. Identifies which assistant
+     * message to regenerate. Undefined for submit-message.
+     */
+    messageId?: string;
+    /** Previous messages in the conversation (context for the LLM). */
+    history: AI.UIMessage[];
+    /** The new message(s) being sent (to publish to the channel). Empty for regeneration. */
+    messages: AI.UIMessage[];
+    /** The msg-id of the message being forked (regenerated or edited). */
+    forkOf?: string;
+    /** The msg-id of the predecessor in the conversation thread. */
+    parent?: string | null;
+}
+/** Options for customizing the ChatTransport behavior. */
+export interface ChatTransportOptions {
+    /**
+     * Customize the POST body before sending. Called by sendMessages()
+     * with the conversation context. Return the body and headers for
+     * the HTTP POST.
+     *
+     * Default: sends all previous messages as `history` in the body.
+     * @param context - The conversation context for the current request.
+     * @returns The body and headers to use for the HTTP POST.
+     */
+    prepareSendMessagesRequest?: (context: SendMessagesRequestContext) => {
+        body?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    };
+}
+/**
+ * Additional options passed through from useChat alongside the core
+ * sendMessages/reconnectToStream parameters.
+ *
+ * Mirrors the AI SDK's internal ChatRequestOptions type, which is not
+ * exported from the `ai` package.
+ */
+interface ChatRequestOptions {
+    /** Additional headers for the request. */
+    headers?: Record<string, string> | Headers;
+    /** Additional JSON body properties for the request. */
+    body?: object;
+    /** Custom metadata to attach to the request. */
+    metadata?: unknown;
+}
+/**
+ * Transport interface for Vercel AI SDK's useChat hook.
+ *
+ * Structurally compatible with the AI SDK's internal `ChatTransport<UIMessage>`
+ * interface. Extended with `close()` for releasing the underlying Ably transport
+ * resources.
+ */
+export interface ChatTransport {
+    /** Send messages and return a streaming response of UIMessageChunk events. */
+    sendMessages: (options: {
+        /** The type of message submission — new message or regeneration. */
+        trigger: 'submit-message' | 'regenerate-message';
+        /** Unique identifier for the chat session. */
+        chatId: string;
+        /** ID of the message to regenerate, or undefined for new messages. */
+        messageId: string | undefined;
+        /** Array of UI messages representing the conversation history. */
+        messages: AI.UIMessage[];
+        /** Signal to abort the request if needed. */
+        abortSignal: AbortSignal | undefined;
+    } & ChatRequestOptions) => Promise<ReadableStream<AI.UIMessageChunk>>;
+    /**
+     * Reconnect to an existing streaming response. Returns null if no active
+     * stream exists for the specified chat session.
+     */
+    reconnectToStream: (options: {
+        /** Unique identifier for the chat session to reconnect to. */
+        chatId: string;
+    } & ChatRequestOptions) => Promise<ReadableStream<AI.UIMessageChunk> | null>;
+    /** Close the underlying transport, releasing all resources. */
+    close(options?: CloseOptions): Promise<void>;
+}
+/**
+ * Create a Vercel ChatTransport from a core ClientTransport.
+ *
+ * Maps Vercel's useChat contract to the core transport's methods:
+ * - trigger 'submit-message' → transport.send(lastMessage) with history in body
+ * - trigger 'regenerate-message' → transport.send([]) with all messages as history
+ * - abortSignal → transport.cancel({ all: true })
+ * - reconnectToStream → null (observer mode handles in-progress streams)
+ * @param transport - The core client transport to wrap.
+ * @param chatOptions - Optional hooks for customizing request construction.
+ * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
+ */
+export declare const createChatTransport: (transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>, chatOptions?: ChatTransportOptions) => ChatTransport;
+export {};

package/dist/vercel/transport/index.d.ts

@@ -0,0 +1,36 @@
+import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTransportOptions } from '../../core/transport/types.js';
+/**
+ * Vercel AI SDK transport wrappers that pre-bind the UIMessageCodec.
+ *
+ * These are convenience factories so consumers don't need to pass the codec
+ * explicitly when using the Vercel AI SDK integration.
+ *
+ * ```ts
+ * import { createClientTransport } from '@ably/ai-transport/vercel';
+ *
+ * const transport = createClientTransport({ channel });
+ * ```
+ */
+export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext } from './chat-transport.js';
+export { createChatTransport } from './chat-transport.js';
+import type * as AI from 'ai';
+/** 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'>;
+/** 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'>;
+/**
+ * Create a client-side transport pre-configured with the Vercel AI SDK codec.
+ *
+ * Equivalent to calling the core `createClientTransport` with `codec: UIMessageCodec`.
+ * @param options - Configuration for the client transport (codec is provided automatically).
+ * @returns A new {@link ClientTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ */
+export declare const createClientTransport: (options: VercelClientTransportOptions) => ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
+/**
+ * Create a server-side transport pre-configured with the Vercel AI SDK codec.
+ *
+ * Equivalent to calling the core `createServerTransport` with `codec: UIMessageCodec`.
+ * @param options - Configuration for the server transport (codec is provided automatically).
+ * @returns A new {@link ServerTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ */
+export declare const createServerTransport: (options: VercelServerTransportOptions) => ServerTransport<AI.UIMessageChunk, AI.UIMessage>;

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@ably/ai-transport",
+  "version": "0.0.1",
+  "description": "Ably transport and codecs for building AI applications with Ably.",
+  "type": "module",
+  "main": "dist/ably-ai-transport.umd.cjs",
+  "module": "dist/ably-ai-transport.js",
+  "browser": "dist/ably-ai-transport.js",
+  "types": "dist/index.d.ts",
+  "react-native": "dist/ably-ai-transport.umd.cjs",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/ably-ai-transport.umd.cjs",
+      "import": "./dist/ably-ai-transport.js",
+      "require": "./dist/ably-ai-transport.umd.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "react-native": "./dist/react/ably-ai-transport-react.umd.cjs",
+      "import": "./dist/react/ably-ai-transport-react.js",
+      "require": "./dist/react/ably-ai-transport-react.umd.cjs"
+    },
+    "./vercel": {
+      "types": "./dist/vercel/index.d.ts",
+      "react-native": "./dist/vercel/ably-ai-transport-vercel.umd.cjs",
+      "import": "./dist/vercel/ably-ai-transport-vercel.js",
+      "require": "./dist/vercel/ably-ai-transport-vercel.umd.cjs"
+    },
+    "./vercel/react": {
+      "types": "./dist/vercel/react/index.d.ts",
+      "react-native": "./dist/vercel/react/ably-ai-transport-vercel-react.umd.cjs",
+      "import": "./dist/vercel/react/ably-ai-transport-vercel-react.js",
+      "require": "./dist/vercel/react/ably-ai-transport-vercel-react.umd.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "npm run build:clean && npm run build:core && npm run build:react && npm run build:vercel && npm run build:vercel-react",
+    "build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build:core": "vite build --config ./src/vite.config.ts",
+    "build:react": "vite build --config ./src/react/vite.config.ts --emptyOutDir",
+    "build:vercel": "vite build --config ./src/vercel/vite.config.ts --emptyOutDir",
+    "build:vercel-react": "vite build --config ./src/vercel/react/vite.config.ts --emptyOutDir",
+    "prepare": "npm run build",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .; (npm run format > /dev/null)",
+    "format": "prettier --list-different --write src demo/vercel/react/*/src",
+    "format:check": "prettier --check src demo/vercel/react/*/src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.config.integration.ts",
+    "check:error-codes": "tsx scripts/validate-error-codes.ts",
+    "precommit": "npm run format:check && npm run lint && npm run typecheck"
+  },
+  "files": [
+    "dist/**",
+    "src/**",
+    "react/**",
+    "vercel/**"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ably/ably-ai-transport-js.git"
+  },
+  "keywords": [
+    "ai",
+    "ably",
+    "ably-realtime",
+    "transport",
+    "websockets"
+  ],
+  "author": "Ably Realtime",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/ably/ably-ai-transport-js/issues"
+  },
+  "homepage": "https://github.com/ably/ably-ai-transport-js#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "ably": "^2.21.0",
+    "ai": "^6",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1.2.7",
+    "@eslint/eslintrc": "^3.3.0",
+    "@eslint/js": "^9.12.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "ai": "^6.0.137",
+    "eslint": "^9.31.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^60.7.0",
+    "eslint-plugin-prefer-arrow-functions": "^3.6.2",
+    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unicorn": "^61.0.2",
+    "globals": "^16.0.0",
+    "jiti": "^2.6.1",
+    "jsdom": "^29.0.1",
+    "prettier": "^3.5.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.0"
+  }
+}

package/react/README.md

@@ -0,0 +1,3 @@
+# @ably/ai-transport/react
+
+This directory contains re-exports of `dist/react`, allowing bundlers (such as Metro) which don't support the package.json `exports` field to resolve imports from `@ably/ai-transport/react`.

package/react/index.d.ts

@@ -0,0 +1 @@
+export * from '../dist/react';

package/react/index.js

@@ -0,0 +1 @@
+export * from '../dist/react/ably-ai-transport-react';

package/react/index.umd.cjs

@@ -0,0 +1 @@
+module.exports = require('../dist/react/ably-ai-transport-react.umd');

package/src/constants.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared constants used by both codec and transport layers.
+ *
+ * Header constants define the `x-ably-*` wire protocol. Message and event
+ * name constants define the transport lifecycle signals on the channel.
+ *
+ * These live at the top level (not in codec/ or transport/) because both
+ * layers need them — the codec core reads/writes stream and status headers,
+ * while the transport layer reads/writes turn, cancel, and role headers.
+ */
+
+// ---------------------------------------------------------------------------
+// Stream headers (used by codec encoder/decoder core)
+// ---------------------------------------------------------------------------
+
+/** Header: whether this Ably message uses streaming (message appends) or is discrete. Always "true" or "false". */
+export const HEADER_STREAM = 'x-ably-stream';
+
+/** Header: lifecycle status of a streamed message. Only set when x-ably-stream is "true". */
+export const HEADER_STATUS = 'x-ably-status';
+
+/** Header: stream identity. Set by the encoder on every streamed message; read by the decoder to correlate streams. */
+export const HEADER_STREAM_ID = 'x-ably-stream-id';
+
+// ---------------------------------------------------------------------------
+// Identity headers (used by transport for turn correlation)
+// ---------------------------------------------------------------------------
+
+/** Header: turn correlation ID. Set on every message in a turn. */
+export const HEADER_TURN_ID = 'x-ably-turn-id';
+
+/** Header: message identity. Assigned per message (user or assistant). Used for optimistic reconciliation on the client. */
+export const HEADER_MSG_ID = 'x-ably-msg-id';
+
+/** Header: clientId of the user who initiated the turn. Set by the server on stream messages. */
+export const HEADER_TURN_CLIENT_ID = 'x-ably-turn-client-id';
+
+/** Header: message role (e.g. "user", "assistant"). */
+export const HEADER_ROLE = 'x-ably-role';
+
+// ---------------------------------------------------------------------------
+// Cancel headers
+// ---------------------------------------------------------------------------
+
+/** Header: cancel a specific turn by ID. */
+export const HEADER_CANCEL_TURN_ID = 'x-ably-cancel-turn-id';
+
+/** Header: cancel all turns belonging to the sender's clientId. */
+export const HEADER_CANCEL_OWN = 'x-ably-cancel-own';
+
+/** Header: cancel all turns on the channel. */
+export const HEADER_CANCEL_ALL = 'x-ably-cancel-all';
+
+/** Header: cancel all turns belonging to a specific clientId. */
+export const HEADER_CANCEL_CLIENT_ID = 'x-ably-cancel-client-id';
+
+// ---------------------------------------------------------------------------
+// Fork / branching headers
+// ---------------------------------------------------------------------------
+
+/** Header: the msg-id of the immediately preceding message in this branch. */
+export const HEADER_PARENT = 'x-ably-parent';
+
+/** Header: the msg-id of the message this one replaces (creates a fork). */
+export const HEADER_FORK_OF = 'x-ably-fork-of';
+
+// ---------------------------------------------------------------------------
+// Turn lifecycle headers
+// ---------------------------------------------------------------------------
+
+/** Header: reason a turn ended (on x-ably-turn-end messages). */
+export const HEADER_TURN_REASON = 'x-ably-turn-reason';
+
+// ---------------------------------------------------------------------------
+// Message / event names
+// ---------------------------------------------------------------------------
+
+/** Message name: client->server cancel signal. */
+export const EVENT_CANCEL = 'x-ably-cancel';
+
+/** Message name: server publishes this to signal a turn has started. */
+export const EVENT_TURN_START = 'x-ably-turn-start';
+
+/** Message name: server publishes this to signal a turn has ended. */
+export const EVENT_TURN_END = 'x-ably-turn-end';
+
+/** Message name: transport-level abort signal (stream cancelled). */
+export const EVENT_ABORT = 'x-ably-abort';
+
+/** Message name: transport-level error signal. */
+export const EVENT_ERROR = 'x-ably-error';
+
+// ---------------------------------------------------------------------------
+// Domain header prefix (used by codec implementations)
+// ---------------------------------------------------------------------------
+
+/** Prefix for domain-specific headers. Distinguishes codec-layer headers from transport `x-ably-*` headers. */
+export const DOMAIN_HEADER_PREFIX = 'x-domain-';