@tanstack/ai-client 0.18.5 → 0.18.6

package/dist/esm/chat-client.d.ts

@@ -0,0 +1,264 @@
+import { AnyClientTool, ModelMessage, StreamChunk } from '@tanstack/ai/client';
+import { ConnectionAdapter } from './connection-adapters.js';
+import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
+type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>> = {
+    connection?: ConnectionAdapter;
+    fetcher?: ChatFetcher;
+    /** @deprecated Use `forwardedProps` instead. */
+    body?: Record<string, any>;
+    forwardedProps?: Record<string, any>;
+    tools?: TTools;
+    onResponse?: (response?: Response) => void | Promise<void>;
+    onChunk?: (chunk: StreamChunk) => void;
+    onFinish?: (message: UIMessage) => void;
+    onError?: (error: Error) => void;
+    onSubscriptionChange?: (isSubscribed: boolean) => void;
+    onConnectionStatusChange?: (status: ConnectionStatus) => void;
+    onSessionGeneratingChange?: (isGenerating: boolean) => void;
+    onCustomEvent?: (eventType: string, data: unknown, context: {
+        toolCallId?: string;
+    }) => void;
+};
+type ClientToolResult = {
+    toolCallId: string;
+    tool: string;
+    output: any;
+    state?: 'output-available' | 'output-error';
+    errorText?: string;
+};
+export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown> {
+    private readonly processor;
+    private connection;
+    private readonly uniqueId;
+    private readonly threadId;
+    private readonly persistor?;
+    private currentRunId;
+    private bodyOption;
+    private forwardedPropsOption;
+    private context;
+    private pendingMessageBody;
+    private isLoading;
+    private isSubscribed;
+    private error;
+    private status;
+    private connectionStatus;
+    private abortController;
+    private readonly clientToolsRef;
+    private readonly devtoolsBridge;
+    /**
+     * Alias for `this.events`. The bridge installs an
+     * emitter that auto-attaches run/thread context and auto-emits a
+     * snapshot after every event, so chat-client only ever calls
+     * `this.events.X(...)` exactly like it did before devtools landed.
+     */
+    private readonly events;
+    private currentStreamId;
+    private currentMessageId;
+    private readonly postStreamActions;
+    private readonly pendingToolExecutions;
+    private activeClientTools;
+    private activeContext;
+    private continuationPending;
+    private subscriptionAbortController;
+    private processingResolve;
+    private errorReportedGeneration;
+    private streamGeneration;
+    private continuationSkipped;
+    private draining;
+    private sessionGenerating;
+    private readonly activeRunIds;
+    private devtoolsMounted;
+    private readonly callbacksRef;
+    constructor(options: ChatClientOptions<TTools, TContext>);
+    mountDevtools(): void;
+    /**
+     * Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
+     * still tracking. The persistor owns the cleared-run bookkeeping; the client
+     * owns the active-run / session / processing state.
+     */
+    private drainIgnoredRunlessChunk;
+    private updateRunLifecycle;
+    private generateUniqueId;
+    private setIsLoading;
+    private setStatus;
+    private setIsSubscribed;
+    private setConnectionStatus;
+    private setSessionGenerating;
+    private resetSessionGenerating;
+    private setError;
+    private buildDevtoolsBridgeOptions;
+    private getDevtoolsSnapshot;
+    private findMessageIdForToolCall;
+    private abortSubscriptionLoop;
+    private resolveProcessing;
+    private cancelInFlightStream;
+    private reportStreamError;
+    /**
+     * Start the background subscription loop.
+     */
+    private startSubscription;
+    /**
+     * Consume chunks from the connection subscription.
+     */
+    private consumeSubscription;
+    /**
+     * Ensure subscription loop is running, starting it if needed.
+     */
+    private ensureSubscription;
+    /**
+     * Create a promise that resolves when onStreamEnd fires.
+     * Used by streamResponse to await processing completion.
+     */
+    private waitForProcessing;
+    /**
+     * Send a message and stream the response.
+     * Supports both simple string content and multimodal content (images, audio, video, documents).
+     *
+     * @param content - The message content. Can be:
+     *   - A simple string for text-only messages
+     *   - A MultimodalContent object with content array and optional custom ID
+     * @param body - Optional body parameters to merge with the client's base body for this request.
+     *               Uses shallow merge with per-message body taking priority.
+     *
+     * @example
+     * ```ts
+     * // Simple text message
+     * await client.sendMessage('Hello!')
+     *
+     * // Text message with custom body params
+     * await client.sendMessage('Hello!', { temperature: 0.7 })
+     *
+     * // Multimodal message with image
+     * await client.sendMessage({
+     *   content: [
+     *     { type: 'text', content: 'What is in this image?' },
+     *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }
+     *   ]
+     * })
+     *
+     * // Multimodal message with custom ID and body params
+     * await client.sendMessage(
+     *   {
+     *     content: [
+     *       { type: 'text', content: 'Describe this audio' },
+     *       { type: 'audio', source: { type: 'data', value: 'base64...' } }
+     *     ],
+     *     id: 'custom-message-id'
+     *   },
+     *   { model: 'gpt-4-audio' }
+     * )
+     * ```
+     */
+    sendMessage(content: string | MultimodalContent, body?: Record<string, any>): Promise<void>;
+    /**
+     * Normalize the message input to extract content and optional id.
+     * Trims string content automatically.
+     */
+    private normalizeMessageInput;
+    /**
+     * Append a message and stream the response
+     */
+    append(message: UIMessage | ModelMessage): Promise<void>;
+    /**
+     * Stream a response from the LLM.
+     * Returns true if the stream completed successfully, false on abort or error.
+     */
+    private streamResponse;
+    /**
+     * Start the client subscription loop.
+     * This controls the connection lifecycle independently from request lifecycle.
+     */
+    subscribe(options?: {
+        restart?: boolean;
+    }): void;
+    /**
+     * Unsubscribe and fully tear down live behavior.
+     * This aborts an in-flight request and the subscription loop.
+     */
+    unsubscribe(): void;
+    /**
+     * Reload the last assistant message
+     */
+    reload(): Promise<void>;
+    /**
+     * Stop the current stream
+     */
+    stop(): void;
+    /**
+     * Clear all messages
+     */
+    clear(): void;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult(result: ClientToolResult): Promise<void>;
+    private addToolResultForClientTool;
+    private validateClientToolOutput;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse(response: {
+        id: string;
+        approved: boolean;
+    }): Promise<void>;
+    /**
+     * Queue an action to be executed after the current stream ends
+     */
+    private queuePostStreamAction;
+    /**
+     * Drain and execute all queued post-stream actions
+     */
+    private drainPostStreamActions;
+    /**
+     * Check if we should continue the flow and do so if needed
+     */
+    private checkForContinuation;
+    /**
+     * Check if all tool calls are complete and we should auto-send.
+     * Requires that there is at least one tool call in the last assistant message;
+     * a text-only response has nothing to auto-send.
+     */
+    private shouldAutoSend;
+    /**
+     * Get current messages
+     */
+    getMessages(): Array<UIMessage<TTools>>;
+    /**
+     * Get loading state
+     */
+    getIsLoading(): boolean;
+    /**
+     * Get current status
+     */
+    getStatus(): ChatClientState;
+    /**
+     * Get whether the subscription loop is active
+     */
+    getIsSubscribed(): boolean;
+    /**
+     * Get current connection lifecycle status
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Whether the shared session is actively generating.
+     * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+     * Unlike `isLoading` (request-local), this reflects shared generation
+     * activity visible to all subscribers (e.g. across tabs/devices).
+     */
+    getSessionGenerating(): boolean;
+    /**
+     * Get current error
+     */
+    getError(): Error | undefined;
+    /**
+     * Manually set messages
+     */
+    setMessagesManually(messages: Array<UIMessage<TTools>>): void;
+    /**
+     * Update options refs (for use in React hooks to avoid recreating client)
+     */
+    updateOptions(options: ChatClientUpdateOptionsWithoutContext<TTools>): void;
+    updateOptions(options: ChatClientUpdateOptionsWithoutContext<TTools> & Pick<ChatClientOptions<TTools, TContext>, 'context'>): void;
+    dispose(): void;
+}
+export {};