@ably/ai-transport 0.0.1

package/src/react/use-conversation-tree.ts

@@ -0,0 +1,71 @@
+/**
+ * useConversationTree — reactive branch navigation for a ClientTransport.
+ *
+ * Subscribes to the transport's "message" notification and provides
+ * branch navigation primitives (getSiblings, selectSibling, hasSiblings)
+ * backed by the transport's ConversationTree.
+ *
+ * Branch selection state is local to the hook instance — each component
+ * (or tab) can navigate branches independently.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+
+import type { ClientTransport } from '../core/transport/types.js';
+
+/** Handle for navigating the branching conversation tree. */
+export interface ConversationTreeHandle<TMessage> {
+  /** Linear message list for the currently selected branch. */
+  messages: TMessage[];
+  /** Get all sibling messages at a fork point. */
+  getSiblings: (msgId: string) => TMessage[];
+  /** Whether a message has siblings (should show navigation arrows). */
+  hasSiblings: (msgId: string) => boolean;
+  /** Index of the currently selected sibling. */
+  getSelectedIndex: (msgId: string) => number;
+  /** Navigate to a sibling. Triggers re-render with updated messages. */
+  selectSibling: (msgId: string, index: number) => void;
+}
+
+/**
+ * Subscribe to transport message updates and provide branch navigation primitives.
+ * @param transport - The client transport whose conversation tree to navigate.
+ * @returns A {@link ConversationTreeHandle} with the current messages and navigation methods.
+ */
+export const useConversationTree = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage>,
+): ConversationTreeHandle<TMessage> => {
+  const [messages, setMessages] = useState<TMessage[]>(() => transport.getMessages());
+
+  useEffect(() => {
+    setMessages(transport.getMessages());
+
+    const unsub = transport.on('message', () => {
+      setMessages(transport.getMessages());
+    });
+    return unsub;
+  }, [transport]);
+
+  const getSiblings = useCallback((msgId: string) => transport.getTree().getSiblings(msgId), [transport]);
+
+  const hasSiblings = useCallback((msgId: string) => transport.getTree().hasSiblings(msgId), [transport]);
+
+  const getSelectedIndex = useCallback((msgId: string) => transport.getTree().getSelectedIndex(msgId), [transport]);
+
+  const selectSibling = useCallback(
+    (msgId: string, index: number) => {
+      transport.getTree().select(msgId, index);
+      // flatten() returns a new array after select(), triggering re-render.
+      setMessages(transport.getMessages());
+    },
+    [transport],
+  );
+
+  return {
+    messages,
+    getSiblings,
+    hasSiblings,
+    getSelectedIndex,
+    selectSibling,
+  };
+};

package/src/react/use-edit.ts

@@ -0,0 +1,24 @@
+/**
+ * useEdit — stable callback for editing a user message.
+ *
+ * Delegates to `transport.edit()`, which automatically computes
+ * `forkOf`, `parent`, and history from the conversation tree.
+ */
+
+import { useCallback } from 'react';
+
+import type { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
+
+/**
+ * Return a stable `edit` callback bound to the given transport.
+ * @param transport - The client transport to edit through.
+ * @returns A function that edits a user message and returns an {@link ActiveTurn} handle.
+ */
+export const useEdit = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage>,
+): ((messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
+  useCallback(
+    async (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
+      transport.edit(messageId, newMessages, options),
+    [transport],
+  );

package/src/react/use-history.ts

@@ -0,0 +1,111 @@
+/**
+ * useHistory — history pagination handle for a ClientTransport.
+ *
+ * Returns a `HistoryHandle` with `load()`, `next()`, `hasNext`, and
+ * `loading` — mirroring the transport's `history()` and
+ * `PaginatedMessages` API.
+ *
+ * The transport's `history()` is branch-aware: `limit` means "keep loading
+ * until N new messages appear on the selected branch." Messages on
+ * unselected branches are loaded into the tree but not counted toward the
+ * limit. The returned `items` contain only the newly visible messages.
+ *
+ * When `options` are provided, auto-loads the first page on mount
+ * (SWR-style: options present = enabled). When omitted or null,
+ * no auto-load — call `load()` manually.
+ *
+ * Usage:
+ * ```tsx
+ * // Auto-load on mount
+ * const history = useHistory(transport, { limit: 30 });
+ *
+ * // Manual load (e.g. on button press)
+ * const history = useHistory(transport);
+ * // ...later: await history.load({ limit: 30 });
+ *
+ * // Scroll-back
+ * if (history.hasNext) await history.next();
+ * ```
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { ClientTransport, LoadHistoryOptions, PaginatedMessages } from '../core/transport/types.js';
+
+/** Handle for paginated history loading. */
+export interface HistoryHandle {
+  /** Are there older pages available? False until `load()` has been called. */
+  hasNext: boolean;
+  /** Is a page being fetched? */
+  loading: boolean;
+  /** Load the first page (or re-load with different options). Inserts into the conversation tree. */
+  load: (options?: LoadHistoryOptions) => Promise<void>;
+  /** Fetch the next (older) page. No-op if loading or no more pages. Inserts into the conversation tree. */
+  next: () => Promise<void>;
+}
+
+/**
+ * Paginated history handle for a client transport.
+ * @param transport - The client transport to load history from, or null/undefined if not yet available.
+ * @param options - When provided, auto-loads the first page on mount. Omit or pass null for manual loading.
+ * @returns A {@link HistoryHandle} for loading and paginating through history.
+ */
+export const useHistory = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage> | null | undefined,
+  options?: LoadHistoryOptions | null,
+): HistoryHandle => {
+  const [hasNext, setHasNext] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const loadingRef = useRef(false);
+  const pageRef = useRef<PaginatedMessages<TMessage> | null>(null);
+  const transportRef = useRef(transport);
+  transportRef.current = transport;
+
+  const load = useCallback(async (loadOptions?: LoadHistoryOptions) => {
+    if (!transportRef.current || loadingRef.current) return;
+    loadingRef.current = true;
+    setLoading(true);
+    try {
+      const page = await transportRef.current.history(loadOptions);
+      pageRef.current = page;
+      setHasNext(page.hasNext());
+    } finally {
+      loadingRef.current = false;
+      setLoading(false);
+    }
+  }, []);
+
+  const next = useCallback(async () => {
+    const page = pageRef.current;
+    if (!page || !page.hasNext() || loadingRef.current || !transportRef.current) return;
+
+    loadingRef.current = true;
+    setLoading(true);
+    try {
+      const older = await page.next();
+      if (older) {
+        pageRef.current = older;
+        setHasNext(older.hasNext());
+      } else {
+        setHasNext(false);
+      }
+    } finally {
+      loadingRef.current = false;
+      setLoading(false);
+    }
+  }, []);
+
+  // Auto-load first page on mount when options are provided (SWR-style).
+  const autoLoad = options !== undefined && options !== null;
+  const autoLoadedRef = useRef(false);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    if (!autoLoad || autoLoadedRef.current || !transportRef.current) return;
+    autoLoadedRef.current = true;
+    void load(optionsRef.current ?? undefined);
+  }, [autoLoad, load]);
+
+  return { hasNext, loading, load, next };
+};

package/src/react/use-messages.ts

@@ -0,0 +1,32 @@
+/**
+ * useMessages — reactive message list from a ClientTransport.
+ *
+ * Subscribes to the transport's "message" notification and returns
+ * the current message list as React state. Replaces the manual
+ * useState + useEffect + on("message") + getMessages() pattern.
+ */
+
+import { useEffect, useState } from 'react';
+
+import type { ClientTransport } from '../core/transport/types.js';
+
+/**
+ * Subscribe to transport message updates and return the current message list.
+ * @param transport - The client transport to observe.
+ * @returns The current list of decoded messages.
+ */
+export const useMessages = <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>): TMessage[] => {
+  const [messages, setMessages] = useState<TMessage[]>(() => transport.getMessages());
+
+  useEffect(() => {
+    // Sync initial state in case the transport already has messages
+    setMessages(transport.getMessages());
+
+    const unsub = transport.on('message', () => {
+      setMessages(transport.getMessages());
+    });
+    return unsub;
+  }, [transport]);
+
+  return messages;
+};

package/src/react/use-regenerate.ts

@@ -0,0 +1,24 @@
+/**
+ * useRegenerate — stable callback for regenerating an assistant message.
+ *
+ * Delegates to `transport.regenerate()`, which automatically computes
+ * `forkOf`, `parent`, and truncated history from the conversation tree.
+ */
+
+import { useCallback } from 'react';
+
+import type { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
+
+/**
+ * Return a stable `regenerate` callback bound to the given transport.
+ * @param transport - The client transport to regenerate through.
+ * @returns A function that regenerates an assistant message and returns an {@link ActiveTurn} handle.
+ */
+export const useRegenerate = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage>,
+): ((messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
+  useCallback(
+    async (messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
+      transport.regenerate(messageId, options),
+    [transport],
+  );

package/src/react/use-send.ts

@@ -0,0 +1,25 @@
+/**
+ * useSend — stable callback for sending messages through a ClientTransport.
+ *
+ * Returns a `send` function that sends one or more messages in a single
+ * turn via `transport.send()`. Callers construct the domain messages
+ * themselves; the hook provides a stable reference suitable for React deps.
+ */
+
+import { useCallback } from 'react';
+
+import type { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
+
+/**
+ * Return a stable `send` callback bound to the given transport.
+ * @param transport - The client transport to send through.
+ * @returns A function that sends messages and returns an {@link ActiveTurn} handle.
+ */
+export const useSend = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage>,
+): ((messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
+  useCallback(
+    async (messages: TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
+      transport.send(messages, options),
+    [transport],
+  );

package/src/react/vite.config.ts

@@ -0,0 +1,32 @@
+import { resolve } from 'path';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  root: resolve(__dirname, '.'),
+  plugins: [
+    dts({
+      entryRoot: resolve(__dirname, '.'),
+      insertTypesEntry: true,
+    }),
+  ],
+  build: {
+    outDir: '../../dist/react',
+    lib: {
+      entry: resolve(__dirname, 'index.ts'),
+      name: 'AblyAiTransportReact',
+      fileName: 'ably-ai-transport-react',
+      formats: ['es', 'umd'],
+    },
+    rollupOptions: {
+      external: ['ably', 'react'],
+      output: {
+        globals: {
+          ably: 'Ably',
+          react: 'React',
+        },
+      },
+    },
+    sourcemap: true,
+  },
+});

package/src/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "include": ["./**/*.ts", "./**/*.tsx"],
+  "exclude": ["**/vite.config.ts"],
+  "compilerOptions": {
+    "rootDir": ".",
+    "target": "es6",
+    "sourceMap": true,
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitThis": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "moduleResolution": "nodenext",
+    "module": "nodenext",
+    "skipLibCheck": true,
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "types": ["node"]
+  }
+}

package/src/utils.ts

@@ -0,0 +1,230 @@
+/**
+ * Shared utilities for working with Ably messages.
+ *
+ * These are general-purpose helpers used by both the codec and transport
+ * layers. They live at the top level to avoid either layer depending on
+ * the other.
+ */
+
+import type * as Ably from 'ably';
+
+import { DOMAIN_HEADER_PREFIX } from './constants.js';
+
+/**
+ * Extract extras.headers from an Ably InboundMessage.
+ * @param message - The Ably message to extract headers from.
+ * @returns The headers record, or an empty object if absent.
+ */
+export const getHeaders = (message: Ably.InboundMessage): Record<string, string> => {
+  // CAST: Ably SDK types `extras` as `any`; runtime checks below guard access.
+  const extras = message.extras as unknown;
+  if (!extras || typeof extras !== 'object') return {};
+  const headers = (extras as { headers?: unknown }).headers;
+  if (!headers || typeof headers !== 'object') return {};
+  // CAST: Ably wire protocol guarantees headers is Record<string, string>
+  // when present, verified by the runtime guards above.
+  return headers as Record<string, string>;
+};
+
+/**
+ * Parse a JSON string, returning undefined on failure.
+ * @param value - The JSON string to parse.
+ * @returns The parsed value, or undefined if parsing fails.
+ */
+export const parseJson = (value: string | undefined): unknown => {
+  if (value === undefined) return undefined;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Set a header value if defined, skipping undefined and null. Strings are set directly,
+ * booleans and numbers are stringified, objects are JSON-serialized.
+ * @param headers - The headers object to mutate.
+ * @param key - The header key.
+ * @param value - The value to set.
+ */
+export const setIfPresent = (headers: Record<string, string>, key: string, value: unknown): void => {
+  if (value === undefined || value === null) return;
+  if (typeof value === 'string') {
+    headers[key] = value;
+  } else if (typeof value === 'boolean' || typeof value === 'number') {
+    headers[key] = String(value);
+  } else if (typeof value === 'object') {
+    headers[key] = JSON.stringify(value);
+  }
+};
+
+/**
+ * Set multiple headers at once, skipping entries whose values are undefined or null.
+ * Each value is converted using the same rules as {@link setIfPresent}.
+ * @param headers - The headers object to mutate.
+ * @param entries - Key-value pairs to set.
+ */
+export const setHeadersIfPresent = (headers: Record<string, string>, entries: Record<string, unknown>): void => {
+  for (const [key, value] of Object.entries(entries)) {
+    setIfPresent(headers, key, value);
+  }
+};
+
+/**
+ * Merge two header records into a new object. Later values override earlier ones.
+ * Undefined inputs are treated as empty.
+ * @param base - Base headers (lower priority).
+ * @param overrides - Override headers (higher priority).
+ * @returns A new merged headers object.
+ */
+export const mergeHeaders = (
+  base: Record<string, string> | undefined,
+  overrides: Record<string, string> | undefined,
+): Record<string, string> => ({
+  ...base,
+  ...overrides,
+});
+
+/**
+ * Parse a boolean header ("true"/"false"), returning undefined if absent.
+ * @param value - The header string to parse.
+ * @returns True if "true", false for any other string, or undefined if absent.
+ */
+export const parseBool = (value: string | undefined): boolean | undefined => {
+  if (value === undefined) return undefined;
+  return value === 'true';
+};
+
+/**
+ * Build a domain headers record from key-value pairs. Each key is automatically
+ * prefixed with {@link DOMAIN_HEADER_PREFIX}. Values that are undefined or null
+ * are skipped; strings are set directly; booleans, numbers, and objects are
+ * converted using the same rules as {@link setIfPresent}.
+ * @param entries - Unprefixed key-value pairs (e.g. `{ toolCallId: 'tc-1' }` becomes `{ 'x-domain-toolCallId': 'tc-1' }`).
+ * @returns A new headers record with prefixed keys.
+ */
+export const domainHeaders = (entries: Record<string, unknown>): Record<string, string> => {
+  const h: Record<string, string> = {};
+  for (const [key, value] of Object.entries(entries)) {
+    setIfPresent(h, DOMAIN_HEADER_PREFIX + key, value);
+  }
+  return h;
+};
+
+/**
+ * Read a domain header value from a headers record.
+ * @param headers - The headers record to read from.
+ * @param key - The unprefixed domain key (e.g. `'toolCallId'` reads `'x-domain-toolCallId'`).
+ * @returns The header value, or undefined if absent.
+ */
+export const getDomainHeader = (headers: Record<string, string>, key: string): string | undefined =>
+  headers[DOMAIN_HEADER_PREFIX + key];
+
+/**
+ * Mapped type that converts properties whose type includes `undefined`
+ * into optional properties with `undefined` excluded from the value.
+ * Properties typed as `unknown` are kept required (since `undefined extends unknown`
+ * is always true, but `unknown` fields are intentionally broad, not optional).
+ */
+export type Stripped<T> = {
+  [K in keyof T as undefined extends T[K] ? (unknown extends T[K] ? K : never) : K]: T[K];
+} & {
+  [K in keyof T as undefined extends T[K] ? (unknown extends T[K] ? never : K) : never]?: Exclude<T[K], undefined>;
+};
+
+/**
+ * Remove all keys whose value is `undefined` from a shallow object.
+ * Returns a new object — the input is not mutated. Useful for building
+ * chunk literals with optional fields without conditional spread noise.
+ *
+ * The return type converts `{ foo: T | undefined }` to `{ foo?: T }`,
+ * matching the optional-field pattern used by the AI SDK chunk types.
+ * @param obj - The object to strip undefined values from.
+ * @returns A shallow copy with undefined-valued keys removed.
+ */
+export const stripUndefined = <T extends Record<string, unknown>>(obj: T): Stripped<T> => {
+  const result = {} as Record<string, unknown>;
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  // CAST: The runtime strip guarantees the Stripped<T> contract —
+  // required keys are always present, optional keys are absent when undefined.
+  return result as Stripped<T>;
+};
+
+// ---------------------------------------------------------------------------
+// DomainHeaderReader — typed accessors for domain headers
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed accessor wrapper around a headers record for reading domain headers.
+ * Reduces repetitive `getDomainHeader` + `parseBool` / `parseJson` chains.
+ */
+export interface DomainHeaderReader {
+  /** Read a domain header as a string, or undefined if absent. */
+  str(key: string): string | undefined;
+  /** Read a domain header as a string, falling back to a default if absent. */
+  strOr(key: string, fallback: string): string;
+  /** Read a domain header as a boolean ("true"/"false"), or undefined if absent. */
+  bool(key: string): boolean | undefined;
+  /** Read a domain header as parsed JSON, or undefined if absent or invalid. */
+  json(key: string): unknown;
+}
+
+/**
+ * Create a {@link DomainHeaderReader} over a headers record.
+ * @param headers - The raw headers record to read domain headers from.
+ * @returns A typed accessor for domain header values.
+ */
+export const headerReader = (headers: Record<string, string>): DomainHeaderReader => ({
+  str: (key: string) => getDomainHeader(headers, key),
+  strOr: (key: string, fallback: string) => getDomainHeader(headers, key) ?? fallback,
+  bool: (key: string) => parseBool(getDomainHeader(headers, key)),
+  json: (key: string) => parseJson(getDomainHeader(headers, key)),
+});
+
+// ---------------------------------------------------------------------------
+// DomainHeaderWriter — typed builder for domain headers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fluent builder for constructing domain header records with typed setters.
+ * Mirrors {@link DomainHeaderReader} with the same method names for symmetry.
+ * Undefined values are silently skipped on all setters.
+ */
+export interface DomainHeaderWriter {
+  /** Set a string domain header. Skips if value is undefined. */
+  str(key: string, value: string | undefined): DomainHeaderWriter;
+  /** Set a boolean domain header (serialized as "true"/"false"). Skips if value is undefined. */
+  bool(key: string, value: boolean | undefined): DomainHeaderWriter;
+  /** Set a JSON-serialized domain header. Skips if value is undefined or null. */
+  json(key: string, value: unknown): DomainHeaderWriter;
+  /** Return the accumulated headers record. */
+  build(): Record<string, string>;
+}
+
+/**
+ * Create a {@link DomainHeaderWriter} for building a domain headers record.
+ * @returns A fluent builder that prefixes each key with the domain header prefix.
+ */
+export const headerWriter = (): DomainHeaderWriter => {
+  const h: Record<string, string> = {};
+  const writer: DomainHeaderWriter = {
+    str: (key: string, value: string | undefined) => {
+      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = value;
+      return writer;
+    },
+    bool: (key: string, value: boolean | undefined) => {
+      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = String(value);
+      return writer;
+    },
+    json: (key: string, value: unknown) => {
+      if (value !== undefined && value !== null) h[DOMAIN_HEADER_PREFIX + key] = JSON.stringify(value);
+      return writer;
+    },
+    build: () => h,
+  };
+  return writer;
+};