@ably/ai-transport 0.1.0 → 0.3.0

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

@@ -0,0 +1,178 @@
+/**
+ * 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 } from '../core/transport/types.js';
+import { ErrorCode } from '../errors.js';
+import { ClientSessionContext } from './contexts/client-session-context.js';
+import { makeSkippedClientSession } from './internal/skipped-session.js';
+
+/**
+ * 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: makeSkippedClientSession<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: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
+        sessionError: slot.sessionError,
+      };
+    }
+    return {
+      session: makeSkippedClientSession<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: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
+      sessionError: nearestSlot.sessionError,
+    };
+  }
+
+  return {
+    session: makeSkippedClientSession<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

@@ -1,56 +1,60 @@
 /**
  * useCreateView — create an independent view with the same API as useView.
  *
- * Calls {@link ClientTransport.createView} to create an independent view over
+ * 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
- * transport reference changes.
+ * session reference changes.
  *
- * Pass `null` or omit `transport` to defer creation (e.g. when a split pane is
- * collapsed). The returned handle has empty state until a transport is provided.
- * When `transport` is omitted entirely, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * 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 { useContext, useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 
-import type { ClientTransport, View } from '../core/transport/types.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
+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 transport changes.
- * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport`, `limit` for auto-load, and `skip`.
- * @param props.transport - Transport to create a view from; defaults to the nearest provider.
+ * 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 = <TEvent, TMessage>({
-  transport,
+export const useCreateView = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
   limit,
   skip,
-}: {
-  /** The transport to create a view from, or null/undefined to use the nearest provider. */
-  transport?: ClientTransport<TEvent, TMessage> | null;
-  /** 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;
-} = {}): ViewHandle<TEvent, TMessage> => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolved = skip
-    ? undefined
-    : ((transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | null | undefined);
+}: UseCreateViewOptions<TInput, TOutput, TProjection, TMessage> = {}): ViewHandle<TInput, TMessage> => {
+  const resolved = useResolvedSession({ session, skip });
 
-  const [view, setView] = useState<View<TEvent, TMessage> | undefined>();
+  const [view, setView] = useState<View<TInput, TMessage> | undefined>();
 
   useEffect(() => {
     if (!resolved) {

package/src/react/use-tree.ts

@@ -1,53 +1,84 @@
 /**
- * useTree — stable structural query callbacks for a ClientTransport's tree.
+ * 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 `transport.tree` — no local
+ * 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 `transport` is omitted, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * When `session` is omitted, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
  */
 
-import { useCallback, useContext } from 'react';
+import { useCallback } from 'react';
 
-import type { ClientTransport, MessageNode } from '../core/transport/types.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
+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<TMessage> {
-  /** Get all sibling messages at a fork point, ordered chronologically by serial. */
-  getSiblings: (msgId: string) => TMessage[];
-  /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
-  hasSiblings: (msgId: string) => boolean;
-  /** Get a node by msgId, or undefined if not found. */
-  getNode: (msgId: string) => MessageNode<TMessage> | undefined;
+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 transport's tree.
- * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport`.
- * @param props.transport - Transport to read tree structure from; defaults to the nearest provider.
+ * 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 = <TEvent, TMessage>({
-  transport,
-}: { transport?: ClientTransport<TEvent, TMessage> } = {}): TreeHandle<TMessage> => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolved = (transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | undefined;
+export const useTree = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
+}: UseTreeOptions<TInput, TOutput, TProjection, TMessage> = {}): TreeHandle<TProjection> => {
+  const resolved = useResolvedSession({ session });
 
-  const getSiblings = useCallback((msgId: string) => resolved?.tree.getSiblings(msgId) ?? [], [resolved]);
+  const getRunNode = useCallback(
+    (runId: string): RunNode<TProjection> | undefined => resolved?.tree.getRunNode(runId),
+    [resolved],
+  );
 
-  const hasSiblings = useCallback((msgId: string) => resolved?.tree.hasSiblings(msgId) ?? false, [resolved]);
+  const getNodeByCodecMessageId = useCallback(
+    (codecMessageId: string): ConversationNode<TProjection> | undefined =>
+      resolved?.tree.getNodeByCodecMessageId(codecMessageId),
+    [resolved],
+  );
 
-  const getNode = useCallback((msgId: string) => resolved?.tree.getNode(msgId), [resolved]);
+  const getSiblingNodes = useCallback(
+    (key: string): ConversationNode<TProjection>[] => resolved?.tree.getSiblingNodes(key) ?? [],
+    [resolved],
+  );
 
   return {
-    getSiblings,
-    hasSiblings,
-    getNode,
+    getRunNode,
+    getNodeByCodecMessageId,
+    getSiblingNodes,
   };
 };