@ably/ai-transport 0.2.0 → 0.3.0

package/dist/react/contexts/client-session-context.d.ts

@@ -20,7 +20,7 @@ export interface ClientSessionSlot {
  * `nearest` is the slot from the innermost enclosing {@link ClientSessionProvider}.
  * `providers` is the full registry of all enclosing providers, keyed by channelName.
  */
-export interface ClientSessionContextValue {
+interface ClientSessionContextValue {
     /** The innermost {@link ClientSessionProvider}'s slot. `undefined` when no provider is present. */
     nearest: ClientSessionSlot | undefined;
     /** All registered session slots from enclosing providers, keyed by channelName. */
@@ -34,3 +34,4 @@ export interface ClientSessionContextValue {
  * read by {@link useClientSession} and internal hooks.
  */
 export declare const ClientSessionContext: import('react').Context<ClientSessionContextValue>;
+export {};

package/dist/react/contexts/client-session-provider.d.ts

@@ -46,6 +46,9 @@ export interface ClientSessionProviderProps<TInput extends CodecInputEvent, TOut
  * const { session: main } = useClientSession({ channelName: 'ai:main' });
  * const { session: aux }  = useClientSession({ channelName: 'ai:aux' });
  * ```
+ * `channelModes` must stay constant for the provider's lifetime: the session is
+ * only recreated when `channelName` changes, and removing the modes after mount
+ * silently reverts the channel's mode set without a reattach.
  * @param props - Provider configuration including `channelName`, `codec`, and all other {@link ClientSessionOptions} except `client`.
  * @param props.children - Descendant components that consume the session via {@link useClientSession}.
  * @returns A React element wrapping children with ClientSessionContext.

package/dist/react/index.d.ts

@@ -1,5 +1,6 @@
+export { OBJECT_MODES } from '../core/channel-options.js';
 export type { CodecMessage } from '../core/codec/types.js';
-export type { ActiveRun, BranchSelection, ClientSession, ConversationNode, EventsNode, InputNode, MessageNode, RunInfo, RunNode, SendOptions, } from '../core/transport/types.js';
+export type { ActiveRun, BranchSelection, ClientSession, ConversationNode, InputNode, MessageNode, RunInfo, RunNode, RunNodeState, SendOptions, } from '../core/transport/types.js';
 export type { ClientSessionSlot } from './contexts/client-session-context.js';
 export type { ClientSessionProviderProps } from './contexts/client-session-provider.js';
 export { ClientSessionProvider } from './contexts/client-session-provider.js';

package/dist/react/internal/skipped-session.d.ts

@@ -0,0 +1,8 @@
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+/**
+ * Create a throwing stub {@link ClientSession}. Held safely in state before a
+ * provider resolves; any access throws {@link Ably.ErrorInfo}.
+ * @returns A stub session whose every member throws.
+ */
+export declare const makeSkippedClientSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>() => ClientSession<TInput, TOutput, TProjection, TMessage>;

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

@@ -15,7 +15,7 @@ import * as Ably from 'ably';
 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. */
+    /** 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;
@@ -34,7 +34,7 @@ export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
      * identity the domain `message` may carry. See {@link View.getMessages}.
      */
     messages: CodecMessage<TMessage>[];
-    /** Whether there are older Runs that can be revealed via `loadOlder`. */
+    /** Whether there are older messages that can be revealed via `loadOlder`. */
     hasOlder: boolean;
     /** Whether a page load is currently in progress. */
     loading: boolean;
@@ -103,7 +103,7 @@ export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
  * @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.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 messages, pagination state, navigation, write operations, and loadOlder.
  */

package/dist/utils.d.ts

@@ -5,7 +5,22 @@
  * 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 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/
@@ -29,13 +44,13 @@ export declare const getCodecHeaders: (message: Ably.InboundMessage) => Record<s
  */
 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.
+ * 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 setIfPresent: (headers: Record<string, string>, key: string, value: 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.
@@ -64,13 +79,6 @@ interface HasSerial {
  * @returns Negative if `a` precedes `b`, positive if `a` follows `b`, 0 if equal.
  */
 export declare const compareBySerial: (a: HasSerial, b: HasSerial) => number;
-/**
- * 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;
 /**
  * Mapped type that converts properties whose type includes `undefined`
  * into optional properties with `undefined` excluded from the value.
@@ -93,44 +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` 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;
-}
-/**
- * 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 codec-tier headers record.
- * @returns A fluent builder that accumulates codec headers under their bare keys.
- */
-export declare const headerWriter: () => DomainHeaderWriter;
 export {};