@ably/ai-transport 0.0.1 → 0.2.0

package/src/react/use-view.ts

@@ -0,0 +1,275 @@
+/**
+ * useView — reactive paginated view of the conversation.
+ *
+ * Subscribes to view updates and exposes the visible messages, msg-anchored
+ * branch navigation, write operations, pagination state, and a `loadOlder`
+ * callback. Pass `session` to use a session's default view, or `view` to
+ * subscribe to a specific {@link View} directly. When both are omitted,
+ * defaults to the nearest {@link ClientSessionProvider}'s session via context.
+ */
+
+import * as Ably from 'ably';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { CodecInputEvent, CodecMessage, CodecOutputEvent } from '../core/codec/types.js';
+import type { ActiveRun, BranchSelection, RunInfo, SendOptions, View } from '../core/transport/types.js';
+import { ErrorCode } from '../errors.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
+
+/** Options for {@link useView}. */
+export interface UseViewOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+  view?: View<TInput, TMessage> | null;
+  /** Maximum number of older Runs to reveal per page (the pagination unit is the Run, not the message). When provided, auto-loads the first page on mount. */
+  limit?: number;
+  /** When `true`, skip all subscriptions and return an empty handle immediately. */
+  skip?: boolean;
+}
+
+/** Handle for the paginated, branch-aware conversation view. */
+export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
+  /**
+   * The visible messages along the selected branch, concatenated across all
+   * visible Runs, each paired with its codec-message-id (see
+   * {@link CodecMessage}). Read the domain object from each entry's
+   * `message` field.
+   *
+   * Correlate a rendered message back to the View — `runOf`,
+   * `branchSelection`, `selectSibling`, `regenerate`, or `edit` — via its
+   * `codecMessageId`, which the SDK assigns and tracks independently of any
+   * identity the domain `message` may carry. See {@link View.getMessages}.
+   */
+  messages: CodecMessage<TMessage>[];
+  /** Whether there are older Runs that can be revealed via `loadOlder`. */
+  hasOlder: boolean;
+  /** Whether a page load is currently in progress. */
+  loading: boolean;
+  /**
+   * Set when the most recent `loadOlder` call failed.
+   * Cleared automatically on the next successful load.
+   * `undefined` when no error has occurred or when `skip` is `true`.
+   */
+  loadError: Ably.ErrorInfo | undefined;
+  /**
+   * Load older messages into the view. No-op if already loading.
+   * On failure, `loadError` is set; on success, `loadError` is cleared.
+   */
+  loadOlder: () => Promise<void>;
+  /**
+   * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+   * Returns `undefined` when the codec-message-id hasn't been observed.
+   * See {@link View.runOf}.
+   */
+  runOf: (codecMessageId: string) => RunInfo | undefined;
+  /**
+   * Direct lookup by runId. Returns `undefined` when the Run hasn't been
+   * observed. See {@link View.run}.
+   */
+  run: (runId: string) => RunInfo | undefined;
+  /**
+   * Snapshot of the visible Runs along the selected branch, in
+   * chronological order. Returns `[]` when the view isn't resolved.
+   * See {@link View.runs}.
+   */
+  runs: () => RunInfo[];
+  /**
+   * Resolve the {@link BranchSelection} bundle anchored at
+   * `codecMessageId`. Always returns a safe object — see
+   * {@link BranchSelection}. See {@link View.branchSelection}.
+   */
+  branchSelection: (codecMessageId: string) => BranchSelection<TMessage>;
+  /**
+   * Select a sibling at the branch point anchored at `codecMessageId`.
+   * `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when
+   * `codecMessageId` isn't a branch anchor. See {@link View.selectSibling}.
+   */
+  selectSibling: (codecMessageId: string, index: number) => void;
+  /**
+   * Send one or more TInputs on the channel and fire a POST. See {@link View.send}.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  send: (events: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Regenerate an assistant message, using this view's branch for history.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Edit a user message, forking from this view's branch.
+   * Rejects with an `Ably.ErrorInfo` (code {@link ErrorCode.InvalidArgument}) if no view is resolved — e.g. before the session is available, or when `skip` is `true`.
+   */
+  edit: (messageId: string, inputs: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+}
+
+/**
+ * Fallback returned by `branchSelection` when the view isn't resolved.
+ * Same shape the view returns for an unknown codec-message-id, so callers
+ * can destructure uniformly.
+ */
+const EMPTY_BRANCH_SELECTION: BranchSelection<never> = {
+  hasSiblings: false,
+  siblings: [],
+  index: 0,
+  selected: undefined,
+};
+
+/**
+ * Subscribe to a view and return the visible messages with pagination, navigation, and write operations.
+ *
+ * `view` takes priority over `session`. When neither is provided, the nearest
+ * {@link ClientSessionProvider}'s session is used. When `limit` is provided, auto-loads
+ * the first page on mount (SWR-style).
+ * @param props - Options for selecting the view source and configuring auto-load.
+ * @param props.session - Client session whose default view to subscribe to; defaults to the nearest provider.
+ * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `session`.
+ * @param props.limit - Max older Runs to reveal per page; when provided, auto-loads the first page on mount.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
+ * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
+ */
+export const useView = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
+  view,
+  limit,
+  skip,
+}: UseViewOptions<TInput, TOutput, TProjection, TMessage> = {}): ViewHandle<TInput, TMessage> => {
+  const resolvedSession = useResolvedSession({ session, skip });
+  const resolvedView = skip ? undefined : (view ?? resolvedSession?.view);
+
+  const [messages, setMessages] = useState<CodecMessage<TMessage>[]>(() => resolvedView?.getMessages() ?? []);
+  const [hasOlder, setHasOlder] = useState(() => resolvedView?.hasOlder() ?? false);
+  const [loading, setLoading] = useState(false);
+  const [loadError, setLoadError] = useState<Ably.ErrorInfo | undefined>();
+  const loadingRef = useRef(false);
+
+  // Auto-load first page on mount when limit is provided (SWR-style).
+  // Fires once per view instance — subsequent changes to limit
+  // only affect manual loadOlder() calls, not the initial auto-load.
+  const autoLoad = limit !== undefined;
+  const autoLoadedRef = useRef(false);
+
+  // Subscribe to view updates
+  useEffect(() => {
+    if (!resolvedView) {
+      setMessages([]);
+      setHasOlder(false);
+      setLoadError(undefined);
+      return;
+    }
+
+    // Reset auto-load flag so the new view gets its first page loaded
+    autoLoadedRef.current = false;
+
+    // Sync initial state
+    setMessages(resolvedView.getMessages());
+    setHasOlder(resolvedView.hasOlder());
+    setLoadError(undefined);
+
+    const unsub = resolvedView.on('update', () => {
+      setMessages(resolvedView.getMessages());
+      setHasOlder(resolvedView.hasOlder());
+    });
+    return unsub;
+  }, [resolvedView]);
+
+  const loadOlder = useCallback(async () => {
+    if (!resolvedView || loadingRef.current) return;
+    loadingRef.current = true;
+    setLoading(true);
+    try {
+      await resolvedView.loadOlder(limit);
+      setLoadError(undefined);
+    } catch (error) {
+      if (error instanceof Ably.ErrorInfo) {
+        setLoadError(error);
+      } else {
+        setLoadError(new Ably.ErrorInfo('Unknown error loading older messages', ErrorCode.BadRequest, 400));
+      }
+    } finally {
+      loadingRef.current = false;
+      setLoading(false);
+    }
+  }, [resolvedView, limit]);
+
+  useEffect(() => {
+    if (!autoLoad || autoLoadedRef.current || !resolvedView) return;
+    autoLoadedRef.current = true;
+    void loadOlder();
+  }, [autoLoad, resolvedView, loadOlder]);
+
+  // Run lookups
+  const runOf = useCallback(
+    (codecMessageId: string): RunInfo | undefined => resolvedView?.runOf(codecMessageId),
+    [resolvedView],
+  );
+
+  const run = useCallback((runId: string): RunInfo | undefined => resolvedView?.run(runId), [resolvedView]);
+
+  const runs = useCallback((): RunInfo[] => resolvedView?.runs() ?? [], [resolvedView]);
+
+  // Branch navigation
+  const branchSelection = useCallback(
+    (codecMessageId: string): BranchSelection<TMessage> =>
+      // CAST: `EMPTY_BRANCH_SELECTION` is typed `BranchSelection<never>`; `never` is
+      // assignable to any `TMessage`, so the empty bundle is a valid fallback for
+      // the not-yet-resolved view case.
+      resolvedView?.branchSelection(codecMessageId) ?? (EMPTY_BRANCH_SELECTION as BranchSelection<TMessage>),
+    [resolvedView],
+  );
+
+  const selectSibling = useCallback(
+    (codecMessageId: string, index: number) => {
+      resolvedView?.selectSibling(codecMessageId, index);
+    },
+    [resolvedView],
+  );
+
+  // Write operation callbacks
+  const send = useCallback(
+    async (events: TInput | TInput[], opts?: SendOptions) => {
+      if (!resolvedView)
+        throw new Ably.ErrorInfo('unable to send; view is not available', ErrorCode.InvalidArgument, 400);
+      return resolvedView.send(events, opts);
+    },
+    [resolvedView],
+  );
+
+  const regenerate = useCallback(
+    async (messageId: string, opts?: SendOptions) => {
+      if (!resolvedView)
+        throw new Ably.ErrorInfo('unable to regenerate; view is not available', ErrorCode.InvalidArgument, 400);
+      return resolvedView.regenerate(messageId, opts);
+    },
+    [resolvedView],
+  );
+
+  const edit = useCallback(
+    async (messageId: string, inputs: TInput | TInput[], opts?: SendOptions) => {
+      if (!resolvedView)
+        throw new Ably.ErrorInfo('unable to edit; view is not available', ErrorCode.InvalidArgument, 400);
+      return resolvedView.edit(messageId, inputs, opts);
+    },
+    [resolvedView],
+  );
+
+  return {
+    messages,
+    hasOlder,
+    loading,
+    loadError,
+    loadOlder,
+    runOf,
+    run,
+    runs,
+    branchSelection,
+    selectSibling,
+    send,
+    regenerate,
+    edit,
+  };
+};

package/src/react/vite.config.ts

@@ -19,11 +19,14 @@ export default defineConfig({
       formats: ['es', 'umd'],
     },
     rollupOptions: {
-      external: ['ably', 'react'],
+      external: ['ably', 'ably/react', 'react', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
       output: {
         globals: {
           ably: 'Ably',
+          'ably/react': 'AblyReact',
           react: 'React',
+          'react/jsx-runtime': 'ReactJsxRuntime',
+          'react/jsx-dev-runtime': 'ReactJsxDevRuntime',
         },
       },
     },

package/src/utils.ts

@@ -8,24 +8,48 @@
 
 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.
+ * Read one tier of the SDK's `extras.ai` namespace from an Ably message.
+ * `extras.ai` is the SDK's reserved corner of the message envelope, split into
+ * a `transport` tier (generic transport headers) and a `codec` tier (codec
+ * headers). The application's own `extras.headers` is deliberately left
+ * untouched.
+ * @param message - The Ably message to read from.
+ * @param tier - Which `extras.ai` sub-namespace to read.
+ * @returns The tier's headers record, or an empty object if absent.
  */
-export const getHeaders = (message: Ably.InboundMessage): Record<string, string> => {
+const getAiTier = (message: Ably.InboundMessage, tier: 'transport' | 'codec'): 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>
+  const ai = (extras as { ai?: unknown }).ai;
+  if (!ai || typeof ai !== 'object') return {};
+  const sub = (ai as Record<string, unknown>)[tier];
+  if (!sub || typeof sub !== 'object') return {};
+  // CAST: Ably wire protocol guarantees the tier is Record<string, string>
   // when present, verified by the runtime guards above.
-  return headers as Record<string, string>;
+  return sub as Record<string, string>;
 };
 
+/**
+ * Extract the transport-tier headers (`extras.ai.transport`) from an Ably
+ * InboundMessage. These are the generic transport headers (run/stream/identity/
+ * branching), set and read by the transport layer.
+ * @param message - The Ably message to extract headers from.
+ * @returns The transport headers record, or an empty object if absent.
+ */
+export const getTransportHeaders = (message: Ably.InboundMessage): Record<string, string> =>
+  getAiTier(message, 'transport');
+
+/**
+ * Extract the codec-tier headers (`extras.ai.codec`) from an Ably
+ * InboundMessage. These are the codec's own headers, with no prefix — the
+ * tier isolates them from transport headers.
+ * @param message - The Ably message to extract headers from.
+ * @returns The codec headers record, or an empty object if absent.
+ */
+export const getCodecHeaders = (message: Ably.InboundMessage): Record<string, string> => getAiTier(message, 'codec');
+
 /**
  * Parse a JSON string, returning undefined on failure.
  * @param value - The JSON string to parse.
@@ -58,18 +82,6 @@ export const setIfPresent = (headers: Record<string, string>, key: string, 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.
@@ -95,30 +107,36 @@ export const parseBool = (value: string | undefined): boolean | undefined => {
   return value === 'true';
 };
 
+/** A record carrying an optional Ably `serial`, orderable by {@link compareBySerial}. */
+interface HasSerial {
+  /** Ably serial, or undefined if the server has not yet assigned one. */
+  readonly serial?: string;
+}
+
 /**
- * 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.
+ * Comparator that orders records by their Ably `serial` ascending
+ * (chronological). Serials are lexicographically comparable; records whose
+ * serial is undefined sort last. Pass directly to `Array.prototype.sort`.
+ * @param a - First record to compare.
+ * @param b - Second record to compare.
+ * @returns Negative if `a` precedes `b`, positive if `a` follows `b`, 0 if equal.
  */
-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;
+export const compareBySerial = (a: HasSerial, b: HasSerial): number => {
+  if (a.serial === undefined && b.serial === undefined) return 0;
+  if (a.serial === undefined) return 1;
+  if (b.serial === undefined) return -1;
+  if (a.serial < b.serial) return -1;
+  if (a.serial > b.serial) return 1;
+  return 0;
 };
 
 /**
- * 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'`).
+ * Read a domain header value from a codec-tier headers record.
+ * @param headers - The codec headers record to read from.
+ * @param key - The domain key (e.g. `'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];
+export const getDomainHeader = (headers: Record<string, string>, key: string): string | undefined => headers[key];
 
 /**
  * Mapped type that converts properties whose type includes `undefined`
@@ -167,7 +185,7 @@ export interface DomainHeaderReader {
   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. */
+  /** Read a domain header as a boolean: `true` only for the exact string "true", `false` for any other present value, 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;
@@ -206,22 +224,22 @@ export interface DomainHeaderWriter {
 }
 
 /**
- * Create a {@link DomainHeaderWriter} for building a domain headers record.
- * @returns A fluent builder that prefixes each key with the domain header prefix.
+ * Create a {@link DomainHeaderWriter} for building a codec-tier headers record.
+ * @returns A fluent builder that accumulates codec headers under their bare keys.
  */
 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;
+      if (value !== undefined) h[key] = value;
       return writer;
     },
     bool: (key: string, value: boolean | undefined) => {
-      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = String(value);
+      if (value !== undefined) h[key] = String(value);
       return writer;
     },
     json: (key: string, value: unknown) => {
-      if (value !== undefined && value !== null) h[DOMAIN_HEADER_PREFIX + key] = JSON.stringify(value);
+      if (value !== undefined && value !== null) h[key] = JSON.stringify(value);
       return writer;
     },
     build: () => h,