@tanstack/ai-client 0.18.5 → 0.18.6

package/dist/esm/connection-adapters.d.ts

@@ -0,0 +1,203 @@
+import { ModelMessage, StreamChunk, UIMessage } from '@tanstack/ai/client';
+import { ChatFetcher } from './types.js';
+/**
+ * Resolve a chunk's run id, preferring the value on the chunk itself
+ * (RUN_STARTED / RUN_FINISHED / RUN_ERROR carry one) and falling back to the
+ * run the connect wrapper stamped it with.
+ */
+export declare function getChunkRunId(chunk: StreamChunk): string | undefined;
+/**
+ * Thrown when an SSE/HTTP stream ends with a non-empty unterminated buffer.
+ * Indicates the connection was cut mid-line (server crash, dropped TCP, proxy
+ * timeout) so the partial content cannot be safely parsed.
+ */
+export declare class StreamTruncatedError extends Error {
+    constructor();
+}
+/**
+ * Per-send context provided by the chat client to the connection adapter.
+ * The adapter combines this with serialized messages to build a full
+ * AG-UI `RunAgentInput` payload.
+ */
+export interface RunAgentInputContext {
+    threadId: string;
+    runId: string;
+    parentRunId?: string;
+    /** Client-declared tools to advertise in the request payload. */
+    clientTools?: Array<{
+        name: string;
+        description: string;
+        parameters: unknown;
+    }>;
+    /** Arbitrary user-controlled passthrough data. */
+    forwardedProps?: Record<string, unknown>;
+}
+export interface ConnectConnectionAdapter {
+    /**
+     * Connect and return an async iterable of StreamChunks.
+     */
+    connect: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal, runContext?: RunAgentInputContext) => AsyncIterable<StreamChunk>;
+}
+export interface SubscribeConnectionAdapter {
+    /**
+     * Subscribe to stream chunks.
+     */
+    subscribe: (abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>;
+    /**
+     * Send a request; chunks arrive through subscribe().
+     */
+    send: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal, runContext?: RunAgentInputContext) => Promise<void>;
+}
+/**
+ * Connection adapter union.
+ * Provide either `connect`, or `subscribe` + `send`.
+ */
+export type ConnectionAdapter = ConnectConnectionAdapter | SubscribeConnectionAdapter;
+/**
+ * Normalize a ConnectionAdapter to subscribe/send operations.
+ *
+ * If a connection provides native subscribe/send, that mode is used.
+ * Otherwise, connect() is wrapped using an async queue.
+ */
+export declare function normalizeConnectionAdapter(connection: ConnectionAdapter | undefined): SubscribeConnectionAdapter;
+/**
+ * Options for fetch-based connection adapters
+ */
+export interface FetchConnectionOptions {
+    headers?: Record<string, string> | Headers;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    body?: Record<string, any>;
+    fetchClient?: typeof globalThis.fetch;
+}
+/**
+ * Options for XHR-based connection adapters.
+ */
+export interface XhrConnectionOptions {
+    headers?: Record<string, string> | Headers;
+    withCredentials?: boolean;
+    signal?: AbortSignal;
+    body?: Record<string, any>;
+    xhrFactory?: () => XMLHttpRequest;
+}
+/**
+ * Create a Server-Sent Events connection adapter
+ *
+ * @param url - The API endpoint URL (or a function that returns the URL)
+ * @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+ * @returns A connection adapter for SSE streams
+ *
+ * @example
+ * ```typescript
+ * // Static URL
+ * const connection = fetchServerSentEvents('/api/chat');
+ *
+ * // Dynamic URL
+ * const connection = fetchServerSentEvents(() => `/api/chat?user=${userId}`);
+ *
+ * // With options
+ * const connection = fetchServerSentEvents('/api/chat', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * // With dynamic options
+ * const connection = fetchServerSentEvents('/api/chat', () => ({
+ *   headers: { 'Authorization': `Bearer ${getToken()}` }
+ * }));
+ *
+ * // With additional body data
+ * const connection = fetchServerSentEvents('/api/chat', async () => ({
+ *   body: {
+ *     provider: 'openai',
+ *     model: 'gpt-4o',
+ *   }
+ * }));
+ * ```
+ */
+export declare function fetchServerSentEvents(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ConnectConnectionAdapter;
+/**
+ * Create an HTTP streaming connection adapter (for raw streaming without SSE format)
+ *
+ * @param url - The API endpoint URL (or a function that returns the URL)
+ * @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+ * @returns A connection adapter for HTTP streams
+ *
+ * @example
+ * ```typescript
+ * // Static URL
+ * const connection = fetchHttpStream('/api/chat');
+ *
+ * // Dynamic URL
+ * const connection = fetchHttpStream(() => `/api/chat?user=${userId}`);
+ *
+ * // With options
+ * const connection = fetchHttpStream('/api/chat', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * // With dynamic options
+ * const connection = fetchHttpStream('/api/chat', () => ({
+ *   headers: { 'Authorization': `Bearer ${getToken()}` }
+ * }));
+ *
+ * // With additional body data
+ * const connection = fetchHttpStream('/api/chat', async () => ({
+ *   body: {
+ *     provider: 'openai',
+ *     model: 'gpt-4o',
+ *   }
+ * }));
+ * ```
+ */
+export declare function fetchHttpStream(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ConnectConnectionAdapter;
+type XhrConnectionOptionsResolver = XhrConnectionOptions | (() => XhrConnectionOptions | Promise<XhrConnectionOptions>);
+/**
+ * Create an XMLHttpRequest-backed Server-Sent Events connection adapter.
+ */
+export declare function xhrServerSentEvents(url: string | (() => string), options?: XhrConnectionOptionsResolver): ConnectConnectionAdapter;
+/**
+ * Create an XMLHttpRequest-backed newline-delimited JSON stream adapter.
+ */
+export declare function xhrHttpStream(url: string | (() => string), options?: XhrConnectionOptionsResolver): ConnectConnectionAdapter;
+/**
+ * Create a direct stream connection adapter (for server functions or direct streams)
+ *
+ * @param streamFactory - A function that returns an async iterable of StreamChunks
+ * @returns A connection adapter for direct streams
+ *
+ * @example
+ * ```typescript
+ * // With TanStack Start server function
+ * const connection = stream(() => serverFunction({ messages }));
+ *
+ * const client = new ChatClient({ connection });
+ * ```
+ */
+export declare function stream(streamFactory: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>): ConnectConnectionAdapter;
+/**
+ * Wrap a `ChatFetcher` as a `ConnectConnectionAdapter` so the chat client can
+ * consume it through the same `subscribe`/`send` plumbing used for SSE /
+ * HTTP-stream / RPC connections. May return either a `Response` (parsed as
+ * SSE) or an `AsyncIterable<StreamChunk>` (yielded directly).
+ *
+ * @internal
+ */
+export declare function fetcherToConnectionAdapter(fetcher: ChatFetcher): ConnectConnectionAdapter;
+/**
+ * Create an RPC stream connection adapter (for RPC-based streaming like Cap'n Web RPC)
+ *
+ * @param rpcCall - A function that accepts messages and returns an async iterable of StreamChunks
+ * @returns A connection adapter for RPC streams
+ *
+ * @example
+ * ```typescript
+ * // With Cap'n Web RPC
+ * const connection = rpcStream((messages, data) =>
+ *   api.streamMurfResponse(messages, data)
+ * );
+ *
+ * const client = new ChatClient({ connection });
+ * ```
+ */
+export declare function rpcStream(rpcCall: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>): ConnectConnectionAdapter;
+export {};