@ably/ai-transport 0.0.1 → 0.2.0

package/src/react/internal/use-resolved-session.ts

@@ -0,0 +1,63 @@
+import { useContext } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession } from '../../core/transport/types.js';
+import { ClientSessionContext } from '../contexts/client-session-context.js';
+
+/**
+ * Shared base for hook options that accept an explicit session override.
+ * Extend this interface for any hook whose `session` option defaults to the
+ * nearest {@link ClientSessionProvider} when omitted. Pass `null` to defer
+ * resolution (e.g. when a split pane is collapsed) — the helper returns
+ * `undefined` rather than falling back to the nearest provider.
+ */
+export interface BaseSessionOption<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> {
+  /**
+   * Session to operate on; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `null` to defer (returns undefined; nearest provider is not used).
+   */
+  session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+}
+
+/**
+ * Resolve the active `ClientSession` for a hook.
+ *
+ * Reads `ClientSessionContext` and applies the standard three-way
+ * priority: explicit `session` argument → nearest provider → `undefined`.
+ * When `skip` is `true`, returns `undefined` regardless of context.
+ * When `session` is `null`, returns `undefined` (caller is deferring).
+ *
+ * Internal — not part of the public API.
+ * @param root0 - Options.
+ * @param root0.session - Explicit session; takes priority over the nearest provider. `null` to defer.
+ * @param root0.skip - When `true`, returns `undefined` immediately; context is still read but its value is ignored.
+ * @returns The resolved session, or `undefined` if none is available or `skip` is `true`.
+ */
+export const useResolvedSession = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({
+  session,
+  skip,
+}: {
+  /** Explicit session; takes priority over the nearest provider. `null` to defer. */
+  session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+  /** When `true`, return `undefined` immediately (context is still read, but ignored). */
+  skip?: boolean;
+} = {}): ClientSession<TInput, TOutput, TProjection, TMessage> | undefined => {
+  const { nearest } = useContext(ClientSessionContext);
+  // CAST: ClientSessionContext stores session with erased generics; types fixed at call site.
+  const nearestSession = nearest?.session as unknown as
+    | ClientSession<TInput, TOutput, TProjection, TMessage>
+    | undefined;
+  if (skip) return undefined;
+  if (session === null) return undefined;
+  return session ?? nearestSession;
+};

package/src/react/use-ably-messages.ts

@@ -1,37 +1,65 @@
 /**
- * useAblyMessages — reactive raw Ably message log from a ClientTransport.
+ * useAblyMessages — reactive raw Ably message log from a ClientSession.
  *
- * Returns the accumulated raw Ably InboundMessages in chronological order,
- * including both live messages (from the channel subscription) and
- * history-loaded messages (from transport.history() calls).
+ * Accumulates raw Ably InboundMessages from the session's tree
+ * 'ably-message' event. Messages are appended in arrival order.
  *
- * Subscribes to the transport's "ably-message" event and re-reads the
- * list on each update.
+ * When `session` is omitted, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
+ * Pass `skip: true` to bypass all subscriptions and return an empty array.
  */
 
 import type * as Ably from 'ably';
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
-import type { ClientTransport } from '../core/transport/types.js';
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
+
+/** Options for {@link useAblyMessages}. */
+export interface UseAblyMessagesOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** When `true`, skip all subscriptions and return an empty array. */
+  skip?: boolean;
+}
 
 /**
- * Subscribe to raw Ably message updates from a client transport.
- * @param transport - The client transport to observe.
- * @returns The accumulated raw Ably messages in chronological order.
+ * Subscribe to raw Ably message updates from a client session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session` and `skip`.
+ * @param props.session - Session to subscribe to; defaults to the nearest provider.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty array.
+ * @returns The accumulated raw Ably messages in event-arrival order — older history messages loaded later are appended after the live messages already present, so this is not strictly chronological.
  */
-export const useAblyMessages = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): Ably.InboundMessage[] => {
-  const [messages, setMessages] = useState<Ably.InboundMessage[]>(() => transport.getAblyMessages());
+export const useAblyMessages = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({ session, skip }: UseAblyMessagesOptions<TInput, TOutput, TProjection, TMessage> = {}): Ably.InboundMessage[] => {
+  const resolved = useResolvedSession({ session, skip });
+
+  const [messages, setMessages] = useState<Ably.InboundMessage[]>([]);
+  const messagesRef = useRef<Ably.InboundMessage[]>([]);
 
   useEffect(() => {
-    setMessages(transport.getAblyMessages());
+    // Reset on session change
+    messagesRef.current = [];
+    setMessages([]);
+
+    if (!resolved) return;
 
-    const unsub = transport.on('ably-message', () => {
-      setMessages(transport.getAblyMessages());
+    const unsub = resolved.tree.on('ably-message', (msg: Ably.InboundMessage) => {
+      const next = [...messagesRef.current, msg];
+      messagesRef.current = next;
+      setMessages(next);
     });
     return unsub;
-  }, [transport]);
+  }, [resolved]);
 
   return messages;
 };

package/src/react/use-client-session.ts

@@ -0,0 +1,201 @@
+/**
+ * useClientSession — read a ClientSession from the nearest ClientSessionProvider.
+ *
+ * The session is created by {@link ClientSessionProvider}, which reads the Ably
+ * Realtime client from the surrounding `<AblyProvider>`. This hook is a thin
+ * context reader — it does not create or manage session state.
+ *
+ * **Provider lookup**
+ * - Omit `channelName` to use the innermost `ClientSessionProvider` in the tree.
+ * - Pass `channelName` to look up a specific provider by name.
+ * - Pass `skip: true` to receive a stub session that throws on any access —
+ *   safe to hold in state before auth or other conditions are ready.
+ *
+ * **Error handling**
+ * - When no matching provider is found, or when the provider's `createClientSession`
+ *   call threw, `sessionError` is set on the returned object instead of throwing.
+ *   The component can render an error state without an error boundary.
+ * - Pass `onError` to receive post-construction session errors (e.g. send failures,
+ *   channel continuity loss) without wiring `session.on('error', ...)` manually.
+ */
+
+import * as Ably from 'ably';
+import { useContext, useEffect, useRef } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { ClientSession, Tree, View } from '../core/transport/types.js';
+import { ErrorCode } from '../errors.js';
+import { ClientSessionContext } from './contexts/client-session-context.js';
+
+const SKIPPED_SESSION: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> = {
+  get tree(): Tree<CodecOutputEvent, unknown> {
+    throw new Ably.ErrorInfo('unable to access tree; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  get view(): View<CodecInputEvent, unknown> {
+    throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  connect: () => {
+    throw new Ably.ErrorInfo('unable to connect; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  createView: (): View<CodecInputEvent, unknown> => {
+    throw new Ably.ErrorInfo('unable to create view; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  cancel: () => {
+    throw new Ably.ErrorInfo('unable to cancel; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  on: () => {
+    throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  close: () => {
+    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+};
+
+/**
+ * Return value of {@link useClientSession}.
+ *
+ * `session` is always a valid object. When `skip` is `true`, when no provider was
+ * found, or when the provider's session construction failed, `session` is a stub
+ * that throws {@link Ably.ErrorInfo} on every access.
+ * Check `sessionError` before using `session` to avoid those throws.
+ */
+export interface ClientSessionHandle<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> {
+  /**
+   * The resolved session.
+   *
+   * A throwing stub when `skip` is `true`, when no matching {@link ClientSessionProvider}
+   * was found in the tree, or when session construction failed.
+   */
+  session: ClientSession<TInput, TOutput, TProjection, TMessage>;
+  /**
+   * Set when no matching {@link ClientSessionProvider} was found, when session
+   * construction failed, and `skip` is `false`.
+   * `undefined` when the session resolved successfully or when `skip` is `true`.
+   */
+  sessionError?: Ably.ErrorInfo | undefined;
+}
+
+/**
+ * Read a {@link ClientSession} from the nearest {@link ClientSessionProvider}.
+ *
+ * Returns `{ session, sessionError }`. When no provider is found or session
+ * construction failed, `sessionError` is set and `session` is a stub that throws
+ * on access — the hook never throws during render.
+ *
+ * Pass `onError` to subscribe to post-construction session errors
+ * (e.g. {@link ErrorCode.SessionSendFailed}, {@link ErrorCode.ChannelContinuityLost})
+ * without calling `session.on('error', …)` manually. The subscription is
+ * created when the session resolves and removed on unmount.
+ * @param props - Hook options.
+ * @param props.channelName - Look up a specific provider by channel name; omit for the nearest.
+ * @param props.skip - When `true`, return the stub session immediately without resolving a provider slot.
+ * @param props.onError - Called whenever the resolved session emits an error event.
+ * @returns `{ session, sessionError }`.
+ */
+export const useClientSession = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({
+  channelName,
+  skip,
+  onError,
+}: {
+  /**
+   * Channel name passed to the enclosing {@link ClientSessionProvider}.
+   * Omit to use the nearest provider in the tree.
+   */
+  channelName?: string;
+  /**
+   * When `true`, skip context lookup and return a stub session that throws on
+   * any access. Use when a condition (auth, feature flag) is not yet resolved.
+   */
+  skip?: boolean;
+  /**
+   * Called whenever the resolved session emits an error event.
+   * The subscription is established once the session resolves and
+   * automatically removed on unmount or when the session changes.
+   */
+  onError?: (error: Ably.ErrorInfo) => void;
+} = {}): ClientSessionHandle<TInput, TOutput, TProjection, TMessage> => {
+  const { nearest: nearestSlot, providers } = useContext(ClientSessionContext);
+  const errorCallbackRef = useRef(onError);
+  errorCallbackRef.current = onError;
+
+  // Compute the session for the onError subscription *before* any conditional
+  // returns to satisfy React's rules of hooks (no hooks in branches).
+  // Erased generics — this local is only used in the useEffect below.
+  const resolvedForEffect: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> | undefined = skip
+    ? undefined
+    : channelName === undefined
+      ? nearestSlot?.session
+      : providers[channelName]?.session;
+
+  useEffect(() => {
+    if (!resolvedForEffect) return;
+    return resolvedForEffect.on('error', (errorInfo: Ably.ErrorInfo) => {
+      errorCallbackRef.current?.(errorInfo);
+    });
+  }, [resolvedForEffect]);
+
+  if (skip) {
+    return {
+      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+    };
+  }
+
+  if (channelName !== undefined) {
+    const slot = providers[channelName];
+    if (slot) {
+      if (slot.session) {
+        // CAST: ClientSessionContext stores sessions with erased generics.
+        // The caller is responsible for using type parameters matching those of the ClientSessionProvider.
+        return {
+          session: slot.session as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+        };
+      }
+      // Provider exists but construction failed.
+      return {
+        session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+        sessionError: slot.sessionError,
+      };
+    }
+    return {
+      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      sessionError: new Ably.ErrorInfo(
+        `unable to use session; no ClientSessionProvider found for channelName "${channelName}"`,
+        ErrorCode.BadRequest,
+        400,
+      ),
+    };
+  }
+
+  if (nearestSlot) {
+    if (nearestSlot.session) {
+      // CAST: ClientSessionContext stores session with erased generics; types fixed at call site.
+      return {
+        session: nearestSlot.session as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      };
+    }
+    // Nearest provider exists but construction failed.
+    return {
+      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      sessionError: nearestSlot.sessionError,
+    };
+  }
+
+  return {
+    session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+    sessionError: new Ably.ErrorInfo(
+      'unable to use session; no ClientSessionProvider found in the tree',
+      ErrorCode.BadRequest,
+      400,
+    ),
+  };
+};

package/src/react/use-create-view.ts

@@ -0,0 +1,72 @@
+/**
+ * useCreateView — create an independent view with the same API as useView.
+ *
+ * Calls {@link ClientSession.createView} to create an independent view over
+ * the same conversation tree, then subscribes to it exactly like
+ * {@link useView}. The view is closed automatically on unmount or when the
+ * session reference changes.
+ *
+ * Pass `null` or omit `session` to defer creation (e.g. when a split pane is
+ * collapsed). The returned handle has empty state until a session is provided.
+ * When `session` is omitted entirely, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
+ * Pass `skip: true` to bypass all context reads and view creation entirely.
+ */
+
+import { useEffect, useState } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { View } from '../core/transport/types.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
+import type { ViewHandle } from './use-view.js';
+import { useView } from './use-view.js';
+
+/** Options for {@link useCreateView}. */
+export interface UseCreateViewOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** When provided, auto-loads the first page on mount. Omit for manual load. */
+  limit?: number;
+  /** When `true`, skip view creation and return an empty handle immediately. */
+  skip?: boolean;
+}
+
+/**
+ * Create an independent {@link View} and subscribe to it.
+ * Returns the same {@link ViewHandle} as {@link useView}, but backed by a
+ * newly created view with its own branch selections and pagination state.
+ * The view is closed on unmount or when the session changes.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`, `limit` for auto-load, and `skip`.
+ * @param props.session - Session to create a view from; defaults to the nearest provider.
+ * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @param props.skip - When `true`, skip view creation and return an empty handle.
+ * @returns A {@link ViewHandle} with nodes, pagination, navigation, and write operations.
+ */
+export const useCreateView = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
+  limit,
+  skip,
+}: UseCreateViewOptions<TInput, TOutput, TProjection, TMessage> = {}): ViewHandle<TInput, TMessage> => {
+  const resolved = useResolvedSession({ session, skip });
+
+  const [view, setView] = useState<View<TInput, TMessage> | undefined>();
+
+  useEffect(() => {
+    if (!resolved) {
+      setView(undefined);
+      return;
+    }
+    const v = resolved.createView();
+    setView(v);
+    return () => {
+      v.close();
+    };
+  }, [resolved]);
+
+  return useView({ view, limit, skip });
+};

package/src/react/use-tree.ts

@@ -0,0 +1,84 @@
+/**
+ * useTree — stable structural query callbacks for a ClientSession's tree.
+ *
+ * Returns a {@link TreeHandle} with methods to inspect the tree structure.
+ * These are thin `useCallback` wrappers around `session.tree` — no local
+ * state or subscriptions. Branch navigation (select, getSelectedIndex) is
+ * on {@link ViewHandle} from {@link useView}.
+ *
+ * When `session` is omitted, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
+ */
+
+import { useCallback } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { ConversationNode, RunNode } from '../core/transport/types.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
+
+/** Handle for querying the conversation tree structure. */
+export interface TreeHandle<TProjection> {
+  /**
+   * Get the RunNode for `runId`, or undefined if no node is keyed by `runId`
+   * (or the keyed node is an input node, not a reply run).
+   */
+  getRunNode: (runId: string) => RunNode<TProjection> | undefined;
+  /**
+   * Get the node that owns a given codec-message-id, or undefined if not
+   * observed. Returns a {@link ConversationNode} union — narrow on `kind`
+   * (`'input'` vs `'run'`) before reading kind-specific fields.
+   */
+  getNodeByCodecMessageId: (codecMessageId: string) => ConversationNode<TProjection> | undefined;
+  /**
+   * Get the sibling group (both kinds) the node keyed by `key` belongs to —
+   * edit versions for an input node, regenerate runs for a reply run — ordered
+   * oldest-first. A single-element array when the node has no siblings; empty
+   * when `key` is unknown. `key` is a {@link RunNode.runId} or an
+   * {@link InputNode.codecMessageId}.
+   */
+  getSiblingNodes: (key: string) => ConversationNode<TProjection>[];
+}
+
+/** Options for {@link useTree}. */
+export type UseTreeOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> = BaseSessionOption<TInput, TOutput, TProjection, TMessage>;
+
+/**
+ * Provide stable structural query callbacks backed by the session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`.
+ * @param props.session - Session to read tree structure from; defaults to the nearest provider.
+ * @returns A {@link TreeHandle} with structural query methods.
+ */
+export const useTree = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
+}: UseTreeOptions<TInput, TOutput, TProjection, TMessage> = {}): TreeHandle<TProjection> => {
+  const resolved = useResolvedSession({ session });
+
+  const getRunNode = useCallback(
+    (runId: string): RunNode<TProjection> | undefined => resolved?.tree.getRunNode(runId),
+    [resolved],
+  );
+
+  const getNodeByCodecMessageId = useCallback(
+    (codecMessageId: string): ConversationNode<TProjection> | undefined =>
+      resolved?.tree.getNodeByCodecMessageId(codecMessageId),
+    [resolved],
+  );
+
+  const getSiblingNodes = useCallback(
+    (key: string): ConversationNode<TProjection>[] => resolved?.tree.getSiblingNodes(key) ?? [],
+    [resolved],
+  );
+
+  return {
+    getRunNode,
+    getNodeByCodecMessageId,
+    getSiblingNodes,
+  };
+};