@ably/ai-transport 0.1.0 → 0.2.0

package/dist/react/use-view.d.ts

@@ -1,26 +1,40 @@
-import { ActiveTurn, ClientTransport, MessageNode, SendOptions, View } from '../core/transport/types.js';
+import { CodecInputEvent, CodecMessage, CodecOutputEvent } from '../core/codec/types.js';
+import { ActiveRun, BranchSelection, RunInfo, SendOptions, View } from '../core/transport/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
 /**
  * useView — reactive paginated view of the conversation.
  *
- * Subscribes to view updates and exposes the visible nodes, branch navigation,
- * write operations, pagination state, and a `loadOlder` callback. Pass `transport`
- * to use a transport's default view, or `view` to subscribe to a specific
- * {@link View} directly. When both are omitted, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * 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';
-/** Options for configuring the view's initial load behavior. */
-export interface UseViewOptions {
-    /** Maximum number of older messages to load per page. Defaults to 100. */
+/** 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<TEvent, TMessage> {
-    /** The visible domain messages along the selected branch. */
-    messages: TMessage[];
-    /** Visible conversation nodes along the selected branch. */
-    nodes: MessageNode<TMessage>[];
-    /** Whether there are older messages that can be revealed via `loadOlder`. */
+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;
@@ -32,48 +46,65 @@ export interface ViewHandle<TEvent, TMessage> {
     loadError: Ably.ErrorInfo | undefined;
     /**
      * Load older messages into the view. No-op if already loading.
-     * On failure, `error` is set; on success, `error` is cleared.
+     * On failure, `loadError` is set; on success, `loadError` is cleared.
      */
     loadOlder: () => Promise<void>;
-    /** Select a sibling at a fork point by index. Triggers a view update with the new branch. */
-    select: (msgId: string, index: number) => void;
-    /** Index of the currently selected sibling at a fork point. */
-    getSelectedIndex: (msgId: string) => number;
-    /** 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;
-    /** Send one or more messages in the context of this view's selected branch. */
-    send: (messages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-    /** Regenerate an assistant message, using this view's branch for history. */
-    regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-    /** Edit a user message, forking from this view's branch. */
-    edit: (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-    /** Amend an existing message and start a continuation turn (e.g. tool results). */
-    update: (msgId: string, events: TEvent[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+    /**
+     * 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>;
 }
 /**
- * Subscribe to a view and return the visible node list with pagination, navigation, and write operations.
+ * Subscribe to a view and return the visible messages with pagination, navigation, and write operations.
  *
- * `view` takes priority over `transport`. When neither is provided, the nearest
- * {@link TransportProvider}'s transport is used. When `limit` is provided, auto-loads
+ * `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.transport - Client transport 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 `transport`.
- * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @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 nodes, pagination state, navigation, write operations, and loadOlder.
+ * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
  */
-export declare const useView: <TEvent, TMessage>({ transport, view, limit, skip, }?: {
-    /** Client transport whose default view to subscribe to; defaults to the nearest provider when omitted. */
-    transport?: ClientTransport<TEvent, TMessage> | null;
-    /** A specific {@link View} to subscribe to directly. Takes priority over `transport`. */
-    view?: View<TEvent, TMessage> | null;
-    /** When provided, auto-loads the first page on mount. Omit for manual loading. */
-    limit?: number;
-    /** When `true`, skip all subscriptions and return an empty handle immediately. */
-    skip?: boolean;
-}) => ViewHandle<TEvent, TMessage>;
+export declare const useView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, view, limit, skip, }?: UseViewOptions<TInput, TOutput, TProjection, TMessage>) => ViewHandle<TInput, TMessage>;

package/dist/utils.d.ts

@@ -7,11 +7,21 @@
  */
 import type * as Ably from 'ably';
 /**
- * Extract extras.headers from an Ably InboundMessage.
+ * 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 headers record, or an empty object if absent.
+ * @returns The transport headers record, or an empty object if absent.
  */
-export declare const getHeaders: (message: Ably.InboundMessage) => Record<string, string>;
+export declare const getTransportHeaders: (message: Ably.InboundMessage) => Record<string, string>;
+/**
+ * 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 declare const getCodecHeaders: (message: Ably.InboundMessage) => Record<string, string>;
 /**
  * Parse a JSON string, returning undefined on failure.
  * @param value - The JSON string to parse.
@@ -26,13 +36,6 @@ export declare const parseJson: (value: string | undefined) => unknown;
  * @param value - The value to set.
  */
 export declare const setIfPresent: (headers: Record<string, string>, key: string, value: unknown) => void;
-/**
- * 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 declare const setHeadersIfPresent: (headers: Record<string, string>, entries: Record<string, unknown>) => void;
 /**
  * Merge two header records into a new object. Later values override earlier ones.
  * Undefined inputs are treated as empty.
@@ -47,19 +50,24 @@ export declare const mergeHeaders: (base: Record<string, string> | undefined, ov
  * @returns True if "true", false for any other string, or undefined if absent.
  */
 export declare const parseBool: (value: string | undefined) => boolean | undefined;
+/** 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 declare const domainHeaders: (entries: Record<string, unknown>) => Record<string, string>;
+export declare const compareBySerial: (a: HasSerial, b: HasSerial) => number;
 /**
- * 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 declare const getDomainHeader: (headers: Record<string, string>, key: string) => string | undefined;
@@ -94,7 +102,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;
@@ -121,7 +129,8 @@ export interface DomainHeaderWriter {
     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.
+ * Create a {@link DomainHeaderWriter} for building a codec-tier headers record.
+ * @returns A fluent builder that accumulates codec headers under their bare keys.
  */
 export declare const headerWriter: () => DomainHeaderWriter;
+export {};