@ably/ai-transport 0.1.0 → 0.2.0

package/dist/react/use-client-transport.d.ts

@@ -1,80 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/**
- * useClientTransport — read a ClientTransport from the nearest TransportProvider.
- *
- * The transport is created by {@link TransportProvider}, which also wraps the subtree
- * with Ably's `ChannelProvider`. This hook is a thin context reader — it does not
- * create or manage transport state.
- *
- * **Provider lookup**
- * - Omit `channelName` to use the innermost `TransportProvider` in the tree.
- * - Pass `channelName` to look up a specific provider by name.
- * - Pass `skip: true` to receive a stub transport 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 `createClientTransport`
- *   call threw, `transportError` 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 transport errors (e.g. send failures,
- *   channel continuity loss) without wiring `transport.on('error', ...)` manually.
- */
-import * as Ably from 'ably';
-/**
- * Return value of {@link useClientTransport}.
- *
- * `transport` is always a valid object. When `skip` is `true`, when no provider was
- * found, or when the provider's transport construction failed, `transport` is a stub
- * that throws {@link Ably.ErrorInfo} on every access.
- * Check `transportError` before using `transport` to avoid those throws.
- */
-export interface ClientTransportHandle<TEvent, TMessage> {
-    /**
-     * The resolved transport.
-     *
-     * A throwing stub when `skip` is `true`, when no matching {@link TransportProvider}
-     * was found in the tree, or when transport construction failed.
-     */
-    transport: ClientTransport<TEvent, TMessage>;
-    /**
-     * Set when no matching {@link TransportProvider} was found, when transport
-     * construction failed, and `skip` is `false`.
-     * `undefined` when the transport resolved successfully or when `skip` is `true`.
-     */
-    transportError?: Ably.ErrorInfo | undefined;
-}
-/**
- * Read a {@link ClientTransport} from the nearest {@link TransportProvider}.
- *
- * Returns `{ transport, transportError }`. When no provider is found or transport
- * construction failed, `transportError` is set and `transport` is a stub that throws
- * on access — the hook never throws during render.
- *
- * Pass `onError` to subscribe to post-construction transport errors
- * (e.g. {@link ErrorCode.TransportSendFailed}, {@link ErrorCode.ChannelContinuityLost})
- * without calling `transport.on('error', …)` manually. The subscription is
- * created when the transport 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 transport immediately without reading context.
- * @param props.onError - Called whenever the resolved transport emits an error event.
- * @returns `{ transport, transportError }`.
- */
-export declare const useClientTransport: <TEvent, TMessage>({ channelName, skip, onError, }?: {
-    /**
-     * Channel name passed to the enclosing {@link TransportProvider}.
-     * Omit to use the nearest provider in the tree.
-     */
-    channelName?: string;
-    /**
-     * When `true`, skip context lookup and return a stub transport that throws on
-     * any access. Use when a condition (auth, feature flag) is not yet resolved.
-     */
-    skip?: boolean;
-    /**
-     * Called whenever the resolved transport emits an error event.
-     * The subscription is established once the transport resolves and
-     * automatically removed on unmount or when the transport changes.
-     */
-    onError?: (error: Ably.ErrorInfo) => void;
-}) => ClientTransportHandle<TEvent, TMessage>;

package/dist/vercel/codec/accumulator.d.ts

@@ -1,21 +0,0 @@
-import { MessageAccumulator } from '../../core/codec/types.js';
-/**
- * Vercel AI SDK Message Accumulator
- *
- * Builds and maintains a UIMessage[] list from decoder outputs.
- * Implements MessageAccumulator<UIMessageChunk, UIMessage>.
- *
- * The accumulator consumes DecoderOutput[] from the decoder and groups
- * streaming events into UIMessage objects using lifecycle boundaries
- * (start/finish). Complete messages (from writeMessages) are inserted
- * directly.
- *
- * Multiple messages can be in-progress concurrently — each is identified
- * by the `messageId` field on DecoderOutput (read from x-ably-msg-id).
- */
-import type * as AI from 'ai';
-/**
- * Create a Vercel AI SDK accumulator that builds UIMessage[] from decoder outputs.
- * @returns A {@link MessageAccumulator} for UIMessageChunk/UIMessage.
- */
-export declare const createAccumulator: () => MessageAccumulator<AI.UIMessageChunk, AI.UIMessage>;

package/dist/vercel/react/use-staged-add-tool-approval-response.d.ts

@@ -1,30 +0,0 @@
-import { ChatAddToolApproveResponseFunction } from 'ai';
-import { ClientTransport } from '../../core/transport/types.js';
-/**
- * useStagedAddToolApprovalResponse — wrap useChat's `addToolApprovalResponse`
- * so the approval response is also applied to the transport tree
- * synchronously at click time.
- *
- * Patching the tree at click time eliminates the useChat↔tree divergence
- * the ChatTransport would otherwise have to reconcile via a history
- * overlay, and closes the observer-turn race that could wipe the
- * approval state between `addToolApprovalResponse` and
- * `sendAutomaticallyWhen`'s evaluation.
- *
- * Use this in place of useChat's raw `addToolApprovalResponse` wherever
- * you wire Approve / Deny buttons.
- */
-import type * as AI from 'ai';
-/**
- * Returns a function with the same signature as useChat's
- * `addToolApprovalResponse`, but additionally applies the approval
- * response to the transport tree via `stageMessage` before delegating.
- *
- * If the tool call identified by `opts.id` isn't found in the tree,
- * the tree update is skipped and the raw function is still called —
- * matches useChat's tolerant behavior for stale approval ids.
- * @param transport - The client transport whose tree to patch.
- * @param addToolApprovalResponse - The raw function from `useChat()`.
- * @returns A drop-in replacement that patches the tree then delegates.
- */
-export declare const useStagedAddToolApprovalResponse: (transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>, addToolApprovalResponse: ChatAddToolApproveResponseFunction) => ChatAddToolApproveResponseFunction;

package/dist/vercel/tool-approvals.d.ts

@@ -1,124 +0,0 @@
-import { MessageNode, StreamResponseOptions, StreamResult, Turn } from '../core/transport/types.js';
-/**
- * Server-side helpers for processing a tool-approval turn.
- *
- * When a Vercel AI SDK tool is marked `needsApproval`, `streamText` pauses
- * after emitting a `dynamic-tool` part in state `approval-requested`. To
- * resume, the server must:
- *
- *   1. Patch the UIMessage history so the pending tool part reflects the
- *      user's decision (`approval-responded` or `output-denied`).
- *   2. Strip the client-appended "Approved: …" user message, because
- *      `streamText`'s multi-step loop only auto-executes pending tool
- *      calls when the conversation ends on a tool/assistant message.
- *   3. Disable `needsApproval` on just-approved tools so the multi-step
- *      loop doesn't immediately pause again on the same tool.
- *   4. Redirect the resulting `tool-output-available` / `tool-output-error`
- *      chunks back to the ORIGINAL assistant message (the one that held
- *      the `approval-requested` part) via `x-ably-amend`, instead of
- *      letting them land on the new assistant message this turn produces.
- *
- * `prepareApprovalTurn` covers steps 1–3; `streamResponseWithApprovalRedirect`
- * covers step 4.
- */
-import type * as AI from 'ai';
-/**
- * A user's decision on a pending tool approval. The client ships an array of
- * these to the server in the POST body; the server feeds them to
- * `prepareApprovalTurn` (to patch history) and
- * `streamResponseWithApprovalRedirect` (to route tool outputs back to the
- * original assistant message).
- *
- * Intentionally does not carry `toolName` or `input` — those are redundant
- * with what's already on the UIMessage history part.
- */
-export interface ToolApprovalDecision {
-    /**
-     * The `toolCallId` of the pending `dynamic-tool` part being approved/denied.
-     * Must match a part already in the history; decisions that don't match any
-     * part are ignored by {@link applyToolApprovalsToHistory}.
-     */
-    toolCallId: string;
-    /** Whether the user approved or denied the tool call. */
-    approved: boolean;
-    /**
-     * The `x-ably-msg-id` of the assistant message whose `dynamic-tool` part
-     * is being responded to. When approved and the tool executes successfully,
-     * the output is published cross-turn targeting this message.
-     */
-    targetMsgId: string;
-    /** Optional reason accompanying the response. */
-    reason?: string;
-}
-/**
- * Patch `dynamic-tool` parts in the history to reflect a batch of approval
- * decisions. Pure — returns a new array; input is not mutated.
- *
- * Approved decisions transition the matching part to `approval-responded`,
- * which `convertToModelMessages` will expand into a `tool-approval-response`
- * model message for `streamText`'s multi-step loop. Denied decisions
- * transition to `output-denied`.
- *
- * Messages and parts whose `toolCallId` is not referenced by any decision
- * are passed through by reference.
- * @param messages - The UIMessage history (user + assistant messages).
- * @param decisions - Approval decisions keyed by `toolCallId`.
- * @returns A new array with matching tool parts transitioned.
- */
-export declare const applyToolApprovalsToHistory: (messages: AI.UIMessage[], decisions: ToolApprovalDecision[]) => AI.UIMessage[];
-/** Options for {@link prepareApprovalTurn}. */
-export interface PrepareApprovalTurnOptions<T extends Record<string, object>> {
-    /** The full UIMessage history (user + assistant messages for this conversation). */
-    messages: AI.UIMessage[];
-    /** The user's approval decisions for this request, if any. */
-    decisions: ToolApprovalDecision[] | undefined;
-    /**
-     * The tool dictionary that will be passed to `streamText`. Typed with a
-     * structural `object` value constraint so it accepts `Record<string, Tool>`
-     * regardless of which copy of the `ai` peer dep typed it.
-     */
-    tools: T;
-}
-/** Result of {@link prepareApprovalTurn}. */
-export interface PrepareApprovalTurnResult<T extends Record<string, object>> {
-    /** Model-format messages ready to pass to `streamText({ messages })`. */
-    modelMessages: AI.ModelMessage[];
-    /** Tools with `needsApproval` disabled for any tool that was just approved. */
-    tools: T;
-}
-/**
- * One-shot transform to ready a history + tool dict for a `streamText` call
- * on an approval turn. Returns the patched model-message array and the
- * effective tools dict.
- *
- * When `decisions` is absent or empty, this is a thin wrapper around
- * `convertToModelMessages(messages)` that returns the original tools — so
- * callers can use it uniformly regardless of whether the request carries
- * approvals.
- * @param options - See {@link PrepareApprovalTurnOptions}.
- * @returns See {@link PrepareApprovalTurnResult}.
- */
-export declare const prepareApprovalTurn: <T extends Record<string, object>>(options: PrepareApprovalTurnOptions<T>) => Promise<PrepareApprovalTurnResult<T>>;
-/** Options for {@link streamResponseWithApprovalRedirect}. */
-export interface StreamResponseWithApprovalRedirectOptions extends StreamResponseOptions<AI.UIMessageChunk> {
-    /**
-     * The approval decisions this turn is resolving. Only approved decisions
-     * redirect tool outputs — denied decisions have already been reflected
-     * in the history and produce no tool output to capture.
-     */
-    decisions: ToolApprovalDecision[] | undefined;
-}
-export declare const streamResponseWithApprovalRedirect: (turn: Turn<AI.UIMessageChunk, AI.UIMessage>, stream: ReadableStream<AI.UIMessageChunk>, options: StreamResponseWithApprovalRedirectOptions) => Promise<StreamResult>;
-/**
- * Walk the conversation history and synthesize a {@link ToolApprovalDecision}
- * for each `dynamic-tool` part in `approval-responded` (approved) or
- * `output-denied` (denied) state.
- *
- * Use in server routes where the client flips the tool part state directly
- * (via useChat's `addToolApprovalResponse` and our
- * `useStagedAddToolApprovalResponse`) and ships it through the history
- * overlay instead of a separate `toolApprovals` body field.
- * @param history - The conversation history nodes from the POST body.
- * @returns Approval decisions derived from the history, in walk order.
- */
-export declare const extractApprovalDecisionsFromHistory: (history: readonly MessageNode<AI.UIMessage>[]) => ToolApprovalDecision[];

package/dist/vercel/tool-events.d.ts

@@ -1,26 +0,0 @@
-import { EventsNode, MessageNode } from '../core/transport/types.js';
-/**
- * Server-side helper for folding client-shipped events into an in-memory
- * history array before handing it to `convertToModelMessages` / `streamText`.
- *
- * When a client-executed tool resolves, the client stages the resulting
- * `tool-output-available` / `tool-output-error` chunk via
- * `transport.stageEvents(msgId, [...])`. The next send flushes it into the
- * POST body's `events` field. The server republishes the event on the
- * channel via `turn.addEvents`, and must also merge it into the in-memory
- * history so the LLM sees the tool result this turn.
- */
-import type * as AI from 'ai';
-/**
- * Fold a batch of client-shipped events into an in-memory history array.
- *
- * Mirrors the optimistic tree update in
- * `DefaultClientTransport._internalSend` (src/core/transport/client-transport.ts)
- * so the server can rebuild the same message state before handing it to
- * `convertToModelMessages` / `streamText`.
- * @param events - The events shipped by the client.
- * @param nodes - The history messages from the POST body.
- * @returns A new array with tool-result events applied to the matching
- *   messages. Non-targeted messages are passed through unchanged.
- */
-export declare const applyToolEventsToHistory: (events: EventsNode<AI.UIMessageChunk>[], nodes: MessageNode<AI.UIMessage>[]) => MessageNode<AI.UIMessage>[];