@ably/ai-transport 0.1.0 → 0.3.0

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

@@ -1,25 +1,39 @@
-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;
+    /** Number of older codecMessages to reveal per page (exactly `limit`, fewer only at the end of history). 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>[];
+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 messages that can be revealed via `loadOlder`. */
     hasOlder: boolean;
     /** Whether a page load is currently in progress. */
@@ -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 - Number of older codecMessages to reveal per page (exactly `limit`, fewer only at end of history); 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

@@ -5,13 +5,38 @@
  * layers. They live at the top level to avoid either layer depending on
  * the other.
  */
-import type * as Ably from 'ably';
+import * as Ably from 'ably';
 /**
- * Extract extras.headers from an Ably InboundMessage.
+ * Extract a human-readable message from an unknown thrown value.
+ * @param error - The thrown value.
+ * @returns The error's `message` when it is an `Error`, otherwise its string form.
+ */
+export declare const errorMessage: (error: unknown) => string;
+/**
+ * Narrow an unknown thrown value to an `Ably.ErrorInfo` for use as a wrapping
+ * `cause`, returning `undefined` when it is not one. Pass the result as the
+ * fourth argument to the `Ably.ErrorInfo` constructor to preserve the error
+ * chain without asserting a type the value may not have.
+ * @param error - The thrown value.
+ * @returns The value when it is an `Ably.ErrorInfo`, otherwise `undefined`.
+ */
+export declare const errorCause: (error: unknown) => Ably.ErrorInfo | undefined;
+/**
+ * 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.
@@ -19,20 +44,13 @@ export declare const getHeaders: (message: Ably.InboundMessage) => Record<string
  */
 export declare const parseJson: (value: string | undefined) => unknown;
 /**
- * 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 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.
+ * Parse a string as JSON, falling back to the raw string when it isn't valid
+ * JSON. An empty string yields `undefined`. Used for accumulated stream text
+ * whose payload may be JSON or a plain string.
+ * @param value - The string to parse.
+ * @returns The parsed value, the raw string on parse failure, or undefined if empty.
  */
-export declare const setHeadersIfPresent: (headers: Record<string, string>, entries: Record<string, unknown>) => void;
+export declare const parseJsonOrString: (value: string) => unknown;
 /**
  * Merge two header records into a new object. Later values override earlier ones.
  * Undefined inputs are treated as empty.
@@ -47,22 +65,20 @@ 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.
- */
-export declare const domainHeaders: (entries: Record<string, unknown>) => Record<string, string>;
-/**
- * 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.
+ * 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 getDomainHeader: (headers: Record<string, string>, key: string) => string | undefined;
+export declare const compareBySerial: (a: HasSerial, b: HasSerial) => number;
 /**
  * Mapped type that converts properties whose type includes `undefined`
  * into optional properties with `undefined` excluded from the value.
@@ -85,43 +101,4 @@ export type Stripped<T> = {
  * @returns A shallow copy with undefined-valued keys removed.
  */
 export declare const stripUndefined: <T extends Record<string, unknown>>(obj: T) => Stripped<T>;
-/**
- * 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 declare const headerReader: (headers: Record<string, string>) => DomainHeaderReader;
-/**
- * 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 declare const headerWriter: () => DomainHeaderWriter;
+export {};