@tanstack/ai-client 0.18.5 → 0.19.0

package/dist/esm/generation-types.d.ts

@@ -0,0 +1,261 @@
+import { MediaPrompt, StreamChunk } from '@tanstack/ai/client';
+import { ConnectConnectionAdapter } from './connection-adapters.js';
+import { AIDevtoolsClientMetadata } from './devtools.js';
+import { GenerationDevtoolsBridgeFactory, VideoDevtoolsBridgeFactory } from './devtools-noop.js';
+/**
+ * Maps an `onResult` transform's raw return type to the stored output type.
+ *
+ * - A concrete return (excluding null/void/undefined) becomes the output type.
+ * - A return of only null/void/undefined falls back to TResult (the transform
+ *   reacted to the result or chose to keep it, rather than replacing it).
+ *
+ * Hooks infer `TReturn` directly from the `onResult` return position — a
+ * covariant inference site that works even for an optional nested property —
+ * which both contextually types the callback parameter as `TResult` and
+ * narrows `result`. See issue #848.
+ *
+ * @template TResult - The raw result type from the generation
+ * @template TReturn - The transform's return type (defaults to `void` when no
+ *   transform is provided)
+ */
+export type InferGenerationOutputFromReturn<TResult, TReturn> = [
+    Exclude<TReturn, null | void | undefined>
+] extends [never] ? TResult : Exclude<TReturn, null | void | undefined>;
+/**
+ * Infers the output type from an `onResult` callback's type.
+ *
+ * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.
+ * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.
+ *
+ * @template TResult - The raw result type from the generation
+ * @template TFn - The onResult callback type (or undefined if not provided)
+ */
+export type InferGenerationOutput<TResult, TFn> = TFn extends (result: any) => infer R ? InferGenerationOutputFromReturn<TResult, R> : TResult;
+/**
+ * State machine for generation clients.
+ * Simpler than ChatClientState since generation is a single request/response cycle.
+ */
+export type GenerationClientState = 'idle' | 'generating' | 'success' | 'error';
+/**
+ * Well-known CUSTOM event names used by generation clients.
+ * These events are emitted by the server-side streaming helpers
+ * and consumed by the client-side GenerationClient.
+ */
+export declare const GENERATION_EVENTS: {
+    /** The generation result payload */
+    readonly RESULT: "generation:result";
+    /** Progress update (0-100) with optional message */
+    readonly PROGRESS: "generation:progress";
+    /** Video job created with jobId */
+    readonly VIDEO_JOB_CREATED: "video:job:created";
+    /** Video job status update */
+    readonly VIDEO_STATUS: "video:status";
+};
+/**
+ * Options passed to a fetcher function by the generation client.
+ */
+export interface GenerationFetcherOptions {
+    /** AbortSignal that is triggered when the user calls `stop()` */
+    signal: AbortSignal;
+}
+/**
+ * A direct async function that performs a generation request.
+ *
+ * Can return the result directly, or return a `Response` with an SSE body
+ * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).
+ * When a `Response` is returned, the client will parse it as an SSE stream.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ */
+export type GenerationFetcher<TInput, TResult> = (input: TInput, options?: GenerationFetcherOptions) => Promise<TResult | Response>;
+/**
+ * Transport configuration for generation clients.
+ * Supports either a connect-based streaming adapter or a direct fetcher function.
+ */
+export type GenerationTransport<TInput, TResult> = {
+    connection: ConnectConnectionAdapter;
+    fetcher?: never;
+} | {
+    fetcher: GenerationFetcher<TInput, TResult>;
+    connection?: never;
+};
+/**
+ * Options for the GenerationClient.
+ *
+ * @template TInput - The input type for the generation request (used by consuming code)
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
+    /** Unique identifier for this generation client instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Metadata used to register this generation hook with TanStack AI Devtools */
+    devtools?: Partial<AIDevtoolsClientMetadata>;
+    /**
+     * Factory that constructs the devtools bridge. Default is a no-op
+     * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+     */
+    devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory;
+    /**
+     * Callback when a result is received. Can optionally return a transformed value
+     * that replaces the stored result.
+     *
+     * - Return a non-null value to transform and store it as the result
+     * - Return `null` to keep the previous result unchanged
+     * - Return nothing (`void`) to store the raw result as-is
+     */
+    onResult?: (result: TResult) => TOutput | null | void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when progress is reported (0-100) */
+    onProgress?: (progress: number, message?: string) => void;
+    /** Callback for each stream chunk (connect-based adapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+    /** @internal Called when result changes */
+    onResultChange?: (result: TOutput | null) => void;
+    /** @internal Called when loading state changes */
+    onLoadingChange?: (isLoading: boolean) => void;
+    /** @internal Called when error state changes */
+    onErrorChange?: (error: Error | undefined) => void;
+    /** @internal Called when generation status changes */
+    onStatusChange?: (status: GenerationClientState) => void;
+}
+/**
+ * Video status information returned during job polling.
+ */
+export interface VideoStatusInfo {
+    /** Job identifier */
+    jobId: string;
+    /** Current status of the video generation job */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Progress percentage (0-100), if available */
+    progress?: number;
+    /** URL to the generated video (when completed) */
+    url?: string;
+    /** Error message if status is 'failed' */
+    error?: string;
+}
+/**
+ * Composite result for video generation (job completion).
+ */
+export interface VideoGenerateResult {
+    /** Job identifier */
+    jobId: string;
+    /** Final status */
+    status: 'completed';
+    /** URL to the generated video */
+    url: string;
+    /** When the URL expires, if applicable */
+    expiresAt?: Date;
+}
+/**
+ * Options for the VideoGenerationClient.
+ */
+export interface VideoGenerationClientOptions<TOutput = VideoGenerateResult> extends Omit<GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>, 'devtoolsBridgeFactory'> {
+    /**
+     * Factory that constructs the video devtools bridge. Default is a no-op
+     * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+     */
+    devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory;
+    /** Callback when a video job is created */
+    onJobCreated?: (jobId: string) => void;
+    /** Callback on each status update */
+    onStatusUpdate?: (status: VideoStatusInfo) => void;
+    /** @internal Called when jobId changes */
+    onJobIdChange?: (jobId: string | null) => void;
+    /** @internal Called when video status changes */
+    onVideoStatusChange?: (status: VideoStatusInfo | null) => void;
+}
+/**
+ * Input for image generation.
+ */
+export interface ImageGenerateInput {
+    /**
+     * Description of the desired image(s): plain text, or an ordered array of
+     * content parts (text + image) for image-conditioned generation
+     * (image-to-image, multi-reference, edit / inpaint).
+     */
+    prompt: MediaPrompt;
+    /** Number of images to generate (default: 1) */
+    numberOfImages?: number;
+    /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
+    size?: string;
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}
+/**
+ * Input for audio generation (music, sound effects).
+ */
+export interface AudioGenerateInput {
+    /** Text description of the desired audio */
+    prompt: string;
+    /** Desired duration in seconds */
+    duration?: number;
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}
+/**
+ * Input for text-to-speech generation.
+ */
+export interface SpeechGenerateInput {
+    /** The text to convert to speech */
+    text: string;
+    /** The voice to use for generation */
+    voice?: string;
+    /** The output audio format */
+    format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
+    /** The speed of the generated audio (0.25 to 4.0) */
+    speed?: number;
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}
+/**
+ * Input for audio transcription.
+ */
+export interface TranscriptionGenerateInput {
+    /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */
+    audio: string | File | Blob | ArrayBuffer;
+    /** The language of the audio in ISO-639-1 format (e.g., 'en') */
+    language?: string;
+    /** An optional prompt to guide the transcription */
+    prompt?: string;
+    /** The format of the transcription output */
+    responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}
+/**
+ * Input for text summarization.
+ */
+export interface SummarizeGenerateInput {
+    /** The text to summarize */
+    text: string;
+    /** Maximum length of the summary */
+    maxLength?: number;
+    /** Style of the summary */
+    style?: 'bullet-points' | 'paragraph' | 'concise';
+    /** Topics to focus on */
+    focus?: Array<string>;
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}
+/**
+ * Input for video generation.
+ */
+export interface VideoGenerateInput {
+    /**
+     * Description of the desired video: plain text, or an ordered array of
+     * content parts (text + image) for image-conditioned generation
+     * (image-to-video, start/end frames).
+     */
+    prompt: MediaPrompt;
+    /** Video size — format depends on provider (e.g., "16:9", "1280x720") */
+    size?: string;
+    /** Video duration in seconds */
+    duration?: number;
+    /** Model-specific options */
+    modelOptions?: Record<string, any>;
+}

package/dist/esm/generation-types.js

@@ -0,0 +1,14 @@
+const GENERATION_EVENTS = {
+  /** The generation result payload */
+  RESULT: "generation:result",
+  /** Progress update (0-100) with optional message */
+  PROGRESS: "generation:progress",
+  /** Video job created with jobId */
+  VIDEO_JOB_CREATED: "video:job:created",
+  /** Video job status update */
+  VIDEO_STATUS: "video:status"
+};
+export {
+  GENERATION_EVENTS
+};
+//# sourceMappingURL=generation-types.js.map

package/dist/esm/generation-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type {\n  GenerationDevtoolsBridgeFactory,\n  VideoDevtoolsBridgeFactory,\n} from './devtools-noop'\n\n// ===========================\n// Inference Utilities\n// ===========================\n\n/**\n * Maps an `onResult` transform's raw return type to the stored output type.\n *\n * - A concrete return (excluding null/void/undefined) becomes the output type.\n * - A return of only null/void/undefined falls back to TResult (the transform\n *   reacted to the result or chose to keep it, rather than replacing it).\n *\n * Hooks infer `TReturn` directly from the `onResult` return position — a\n * covariant inference site that works even for an optional nested property —\n * which both contextually types the callback parameter as `TResult` and\n * narrows `result`. See issue #848.\n *\n * @template TResult - The raw result type from the generation\n * @template TReturn - The transform's return type (defaults to `void` when no\n *   transform is provided)\n */\nexport type InferGenerationOutputFromReturn<TResult, TReturn> = [\n  Exclude<TReturn, null | void | undefined>,\n] extends [never]\n  ? TResult\n  : Exclude<TReturn, null | void | undefined>\n\n/**\n * Infers the output type from an `onResult` callback's type.\n *\n * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.\n * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.\n *\n * @template TResult - The raw result type from the generation\n * @template TFn - The onResult callback type (or undefined if not provided)\n */\nexport type InferGenerationOutput<TResult, TFn> = TFn extends (\n  result: any,\n) => infer R\n  ? InferGenerationOutputFromReturn<TResult, R>\n  : TResult\n\n// ===========================\n// State\n// ===========================\n\n/**\n * State machine for generation clients.\n * Simpler than ChatClientState since generation is a single request/response cycle.\n */\nexport type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'\n\n// ===========================\n// Event Constants\n// ===========================\n\n/**\n * Well-known CUSTOM event names used by generation clients.\n * These events are emitted by the server-side streaming helpers\n * and consumed by the client-side GenerationClient.\n */\nexport const GENERATION_EVENTS = {\n  /** The generation result payload */\n  RESULT: 'generation:result',\n  /** Progress update (0-100) with optional message */\n  PROGRESS: 'generation:progress',\n  /** Video job created with jobId */\n  VIDEO_JOB_CREATED: 'video:job:created',\n  /** Video job status update */\n  VIDEO_STATUS: 'video:status',\n} as const\n\n// ===========================\n// Transport Types\n// ===========================\n\n/**\n * Options passed to a fetcher function by the generation client.\n */\nexport interface GenerationFetcherOptions {\n  /** AbortSignal that is triggered when the user calls `stop()` */\n  signal: AbortSignal\n}\n\n/**\n * A direct async function that performs a generation request.\n *\n * Can return the result directly, or return a `Response` with an SSE body\n * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).\n * When a `Response` is returned, the client will parse it as an SSE stream.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n */\nexport type GenerationFetcher<TInput, TResult> = (\n  input: TInput,\n  options?: GenerationFetcherOptions,\n) => Promise<TResult | Response>\n\n/**\n * Transport configuration for generation clients.\n * Supports either a connect-based streaming adapter or a direct fetcher function.\n */\nexport type GenerationTransport<TInput, TResult> =\n  | { connection: ConnectConnectionAdapter; fetcher?: never }\n  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }\n\n// ===========================\n// Client Options\n// ===========================\n\n/**\n * Options for the GenerationClient.\n *\n * @template TInput - The input type for the generation request (used by consuming code)\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)\nexport interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {\n  /** Unique identifier for this generation client instance */\n  id?: string\n\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n\n  /** Metadata used to register this generation hook with TanStack AI Devtools */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory\n\n  /**\n   * Callback when a result is received. Can optionally return a transformed value\n   * that replaces the stored result.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: TResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n\n  // Framework state callbacks (set by hooks, not users)\n  /** @internal Called when result changes */\n  onResultChange?: (result: TOutput | null) => void\n  /** @internal Called when loading state changes */\n  onLoadingChange?: (isLoading: boolean) => void\n  /** @internal Called when error state changes */\n  onErrorChange?: (error: Error | undefined) => void\n  /** @internal Called when generation status changes */\n  onStatusChange?: (status: GenerationClientState) => void\n}\n\n// ===========================\n// Video-Specific Options\n// ===========================\n\n/**\n * Video status information returned during job polling.\n */\nexport interface VideoStatusInfo {\n  /** Job identifier */\n  jobId: string\n  /** Current status of the video generation job */\n  status: 'pending' | 'processing' | 'completed' | 'failed'\n  /** Progress percentage (0-100), if available */\n  progress?: number\n  /** URL to the generated video (when completed) */\n  url?: string\n  /** Error message if status is 'failed' */\n  error?: string\n}\n\n/**\n * Composite result for video generation (job completion).\n */\nexport interface VideoGenerateResult {\n  /** Job identifier */\n  jobId: string\n  /** Final status */\n  status: 'completed'\n  /** URL to the generated video */\n  url: string\n  /** When the URL expires, if applicable */\n  expiresAt?: Date\n}\n\n/**\n * Options for the VideoGenerationClient.\n */\nexport interface VideoGenerationClientOptions<\n  TOutput = VideoGenerateResult,\n> extends Omit<\n  GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>,\n  'devtoolsBridgeFactory'\n> {\n  /**\n   * Factory that constructs the video devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory\n\n  /** Callback when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n\n  // Framework state callbacks\n  /** @internal Called when jobId changes */\n  onJobIdChange?: (jobId: string | null) => void\n  /** @internal Called when video status changes */\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n// ===========================\n// Input Types\n// ===========================\n\n/**\n * Input for image generation.\n */\nexport interface ImageGenerateInput {\n  /**\n   * Description of the desired image(s): plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-image, multi-reference, edit / inpaint).\n   */\n  prompt: MediaPrompt\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: string\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio generation (music, sound effects).\n */\nexport interface AudioGenerateInput {\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text-to-speech generation.\n */\nexport interface SpeechGenerateInput {\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio transcription.\n */\nexport interface TranscriptionGenerateInput {\n  /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text summarization.\n */\nexport interface SummarizeGenerateInput {\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary */\n  maxLength?: number\n  /** Style of the summary */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics to focus on */\n  focus?: Array<string>\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for video generation.\n */\nexport interface VideoGenerateInput {\n  /**\n   * Description of the desired video: plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-video, start/end frames).\n   */\n  prompt: MediaPrompt\n  /** Video size — format depends on provider (e.g., \"16:9\", \"1280x720\") */\n  size?: string\n  /** Video duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n"],"names":[],"mappings":"AAoEO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,20 @@
+export { AudioRecorder } from './audio-recorder.js';
+export type { AudioRecorderOptions, AudioRecorderState, AudioRecording, InferAudioRecordingOutput, } from './audio-recorder.js';
+export { ChatClient } from './chat-client.js';
+export { createMcpAppBridge } from './mcp-app-bridge.js';
+export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge.js';
+export { RealtimeClient } from './realtime-client.js';
+export { GenerationClient } from './generation-client.js';
+export { VideoGenerationClient } from './video-generation-client.js';
+export type { UIMessage, MessagePart, TextPart, ToolCallPart, ToolResultPart, ThinkingPart, StructuredOutputPart, ChatClientPersistence, ChatClientOptions, ClientContextOptionFromTools, ChatRequestBody, InferChatMessages, InferredClientContext, ChatClientState, ConnectionStatus, ChatFetcher, ChatFetcherInput, ChatFetcherOptions, ChatTransport, DistributedOmit, MultimodalContent, } from './types.js';
+export type { InferGenerationOutput, InferGenerationOutputFromReturn, GenerationClientState, GenerationClientOptions, GenerationFetcher, GenerationFetcherOptions, GenerationTransport, VideoGenerationClientOptions, VideoStatusInfo, VideoGenerateResult, ImageGenerateInput, AudioGenerateInput, SpeechGenerateInput, TranscriptionGenerateInput, SummarizeGenerateInput, VideoGenerateInput, } from './generation-types.js';
+export { GENERATION_EVENTS } from './generation-types.js';
+export { UnsupportedResponseStreamError } from './response-stream.js';
+export { clientTools, createChatClientOptions } from './types.js';
+export { createAIDevtoolsGenerationPreview, type AIDevtoolsClientMetadata, type AIDevtoolsDisplayOptions, type AIDevtoolsGenerationMediaItem, type AIDevtoolsGenerationPreview, type AIDevtoolsGenerationProgress, type AIDevtoolsGenerationVideoJob, } from './devtools.js';
+export type { ExtractToolNames, ExtractToolInput, ExtractToolOutput, } from './tool-types.js';
+export type { AnyClientTool } from '@tanstack/ai/client';
+export type { RealtimeAdapter, RealtimeConnection, RealtimeClientOptions, RealtimeClientState, RealtimeStateChangeCallback, } from './realtime-types.js';
+export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, StreamTruncatedError, type ConnectConnectionAdapter, type ConnectionAdapter, type FetchConnectionOptions, type RunAgentInputContext, type SubscribeConnectionAdapter, type XhrConnectionOptions, } from './connection-adapters.js';
+export { uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, convertMessagesToModelMessages, normalizeToUIMessage, generateMessageId, } from '@tanstack/ai/client';
+export { StreamProcessor, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, parsePartialJSON, PartialJSONParser, defaultJSONParser, type ChunkStrategy, type StreamProcessorOptions, type StreamProcessorEvents, type InternalToolCallState, type ToolCallState, type ToolResultState, type JSONParser, type ChunkRecording, type ProcessorResult, type ProcessorState, } from '@tanstack/ai/client';

package/dist/esm/index.js

@@ -0,0 +1,48 @@
+import { AudioRecorder } from "./audio-recorder.js";
+import { ChatClient } from "./chat-client.js";
+import { createMcpAppBridge } from "./mcp-app-bridge.js";
+import { RealtimeClient } from "./realtime-client.js";
+import { GenerationClient } from "./generation-client.js";
+import { VideoGenerationClient } from "./video-generation-client.js";
+import { GENERATION_EVENTS } from "./generation-types.js";
+import { UnsupportedResponseStreamError } from "./response-stream.js";
+import { clientTools, createChatClientOptions } from "./types.js";
+import { createAIDevtoolsGenerationPreview } from "./devtools.js";
+import { StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "./connection-adapters.js";
+import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, convertMessagesToModelMessages, defaultJSONParser, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, uiMessageToModelMessages } from "@tanstack/ai/client";
+export {
+  AudioRecorder,
+  BatchStrategy,
+  ChatClient,
+  CompositeStrategy,
+  GENERATION_EVENTS,
+  GenerationClient,
+  ImmediateStrategy,
+  PartialJSONParser,
+  PunctuationStrategy,
+  RealtimeClient,
+  StreamProcessor,
+  StreamTruncatedError,
+  UnsupportedResponseStreamError,
+  VideoGenerationClient,
+  WordBoundaryStrategy,
+  clientTools,
+  convertMessagesToModelMessages,
+  createAIDevtoolsGenerationPreview,
+  createChatClientOptions,
+  createMcpAppBridge,
+  defaultJSONParser,
+  fetchHttpStream,
+  fetchServerSentEvents,
+  generateMessageId,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  normalizeToUIMessage,
+  parsePartialJSON,
+  rpcStream,
+  stream,
+  uiMessageToModelMessages,
+  xhrHttpStream,
+  xhrServerSentEvents
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/esm/mcp-app-bridge.d.ts

@@ -0,0 +1,27 @@
+export interface CreateMcpAppBridgeOptions {
+    threadId: string;
+    callEndpoint: string;
+    chat: {
+        sendMessage: (content: string, body?: Record<string, unknown>) => Promise<void>;
+    };
+    fetchImpl?: typeof fetch;
+    onLink?: (url: string) => void;
+}
+export interface McpAppBridge {
+    callTool: (input: {
+        serverId?: string;
+        toolName: string;
+        args?: Record<string, unknown>;
+        /**
+         * Reserved — forwarded to the call handler for correlation purposes but
+         * not consumed by the handler. Accepted on the wire; the handler does not
+         * read it (mirrors the `meta` convention on `UIResourcePart`).
+         */
+        messageId?: string;
+    }) => Promise<unknown>;
+    sendPrompt: (text: string) => Promise<void>;
+    openLink: (url: string) => {
+        isError: boolean;
+    };
+}
+export declare function createMcpAppBridge(options: CreateMcpAppBridgeOptions): McpAppBridge;

package/dist/esm/mcp-app-bridge.js

@@ -0,0 +1,70 @@
+function isToolCallResponse(value) {
+  return value !== null && typeof value === "object" && "ok" in value && typeof value.ok === "boolean";
+}
+const SAFE_LINK_SCHEMES = /* @__PURE__ */ new Set(["http:", "https:", "mailto:"]);
+function isSafeLink(url) {
+  try {
+    return SAFE_LINK_SCHEMES.has(new URL(url).protocol);
+  } catch {
+    return false;
+  }
+}
+function createMcpAppBridge(options) {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options;
+  const doFetch = fetchImpl ?? fetch;
+  return {
+    async callTool(input) {
+      const response = await doFetch(callEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          threadId,
+          serverId: input.serverId,
+          toolName: input.toolName,
+          args: input.args,
+          messageId: input.messageId
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`MCP app tool call failed: HTTP ${response.status}`);
+      }
+      const raw = await response.json();
+      if (!isToolCallResponse(raw)) {
+        throw new Error("MCP app tool call failed");
+      }
+      if (!raw.ok) {
+        throw new Error(raw.error ?? "MCP app tool call failed");
+      }
+      return raw.result;
+    },
+    async sendPrompt(text) {
+      await chat.sendMessage(text);
+    },
+    openLink(url) {
+      if (!isSafeLink(url)) {
+        console.warn(
+          "[mcp-app-bridge] openLink rejected: unsupported URL scheme",
+          url
+        );
+        return { isError: true };
+      }
+      if (onLink) {
+        try {
+          onLink(url);
+          return { isError: false };
+        } catch (err) {
+          console.warn("[mcp-app-bridge] openLink: onLink handler threw", err);
+          return { isError: true };
+        }
+      }
+      console.warn(
+        "[mcp-app-bridge] openLink ignored: no onLink handler configured"
+      );
+      return { isError: true };
+    }
+  };
+}
+export {
+  createMcpAppBridge
+};
+//# sourceMappingURL=mcp-app-bridge.js.map

package/dist/esm/mcp-app-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app-bridge.js","sources":["../../src/mcp-app-bridge.ts"],"sourcesContent":["export interface CreateMcpAppBridgeOptions {\n  threadId: string\n  callEndpoint: string\n  chat: {\n    sendMessage: (\n      content: string,\n      body?: Record<string, unknown>,\n    ) => Promise<void>\n  }\n  fetchImpl?: typeof fetch\n  onLink?: (url: string) => void\n}\n\nexport interface McpAppBridge {\n  callTool: (input: {\n    serverId?: string\n    toolName: string\n    args?: Record<string, unknown>\n    /**\n     * Reserved — forwarded to the call handler for correlation purposes but\n     * not consumed by the handler. Accepted on the wire; the handler does not\n     * read it (mirrors the `meta` convention on `UIResourcePart`).\n     */\n    messageId?: string\n  }) => Promise<unknown>\n  sendPrompt: (text: string) => Promise<void>\n  openLink: (url: string) => { isError: boolean }\n}\n\ninterface ToolCallResponse {\n  ok: boolean\n  result?: unknown\n  error?: string\n}\n\nfunction isToolCallResponse(value: unknown): value is ToolCallResponse {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'ok' in value &&\n    typeof value.ok === 'boolean'\n  )\n}\n\n// Links arrive from an untrusted sandboxed widget. Only hand http(s)/mailto\n// URLs to the host's onLink; reject javascript:/data:/file:/etc. so a widget\n// can't smuggle a script-executing or local-resource URL through the bridge.\nconst SAFE_LINK_SCHEMES = new Set(['http:', 'https:', 'mailto:'])\nfunction isSafeLink(url: string): boolean {\n  try {\n    return SAFE_LINK_SCHEMES.has(new URL(url).protocol)\n  } catch {\n    return false\n  }\n}\n\nexport function createMcpAppBridge(\n  options: CreateMcpAppBridgeOptions,\n): McpAppBridge {\n  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options\n  const doFetch = fetchImpl ?? fetch\n\n  return {\n    async callTool(input) {\n      const response = await doFetch(callEndpoint, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json' },\n        body: JSON.stringify({\n          threadId,\n          serverId: input.serverId,\n          toolName: input.toolName,\n          args: input.args,\n          messageId: input.messageId,\n        }),\n      })\n\n      if (!response.ok) {\n        throw new Error(`MCP app tool call failed: HTTP ${response.status}`)\n      }\n\n      const raw: unknown = await response.json()\n      if (!isToolCallResponse(raw)) {\n        throw new Error('MCP app tool call failed')\n      }\n\n      if (!raw.ok) {\n        throw new Error(raw.error ?? 'MCP app tool call failed')\n      }\n\n      return raw.result\n    },\n\n    async sendPrompt(text) {\n      await chat.sendMessage(text)\n    },\n\n    openLink(url) {\n      if (!isSafeLink(url)) {\n        console.warn(\n          '[mcp-app-bridge] openLink rejected: unsupported URL scheme',\n          url,\n        )\n        return { isError: true }\n      }\n      if (onLink) {\n        try {\n          onLink(url)\n          return { isError: false }\n        } catch (err) {\n          console.warn('[mcp-app-bridge] openLink: onLink handler threw', err)\n          return { isError: true }\n        }\n      }\n      console.warn(\n        '[mcp-app-bridge] openLink ignored: no onLink handler configured',\n      )\n      return { isError: true }\n    },\n  }\n}\n"],"names":[],"mappings":"AAmCA,SAAS,mBAAmB,OAA2C;AACrE,SACE,UAAU,QACV,OAAO,UAAU,YACjB,QAAQ,SACR,OAAO,MAAM,OAAO;AAExB;AAKA,MAAM,oBAAoB,oBAAI,IAAI,CAAC,SAAS,UAAU,SAAS,CAAC;AAChE,SAAS,WAAW,KAAsB;AACxC,MAAI;AACF,WAAO,kBAAkB,IAAI,IAAI,IAAI,GAAG,EAAE,QAAQ;AAAA,EACpD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,mBACd,SACc;AACd,QAAM,EAAE,UAAU,cAAc,MAAM,WAAW,WAAW;AAC5D,QAAM,UAAU,aAAa;AAE7B,SAAO;AAAA,IACL,MAAM,SAAS,OAAO;AACpB,YAAM,WAAW,MAAM,QAAQ,cAAc;AAAA,QAC3C,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,mBAAA;AAAA,QAC3B,MAAM,KAAK,UAAU;AAAA,UACnB;AAAA,UACA,UAAU,MAAM;AAAA,UAChB,UAAU,MAAM;AAAA,UAChB,MAAM,MAAM;AAAA,UACZ,WAAW,MAAM;AAAA,QAAA,CAClB;AAAA,MAAA,CACF;AAED,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,IAAI,MAAM,kCAAkC,SAAS,MAAM,EAAE;AAAA,MACrE;AAEA,YAAM,MAAe,MAAM,SAAS,KAAA;AACpC,UAAI,CAAC,mBAAmB,GAAG,GAAG;AAC5B,cAAM,IAAI,MAAM,0BAA0B;AAAA,MAC5C;AAEA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI,MAAM,IAAI,SAAS,0BAA0B;AAAA,MACzD;AAEA,aAAO,IAAI;AAAA,IACb;AAAA,IAEA,MAAM,WAAW,MAAM;AACrB,YAAM,KAAK,YAAY,IAAI;AAAA,IAC7B;AAAA,IAEA,SAAS,KAAK;AACZ,UAAI,CAAC,WAAW,GAAG,GAAG;AACpB,gBAAQ;AAAA,UACN;AAAA,UACA;AAAA,QAAA;AAEF,eAAO,EAAE,SAAS,KAAA;AAAA,MACpB;AACA,UAAI,QAAQ;AACV,YAAI;AACF,iBAAO,GAAG;AACV,iBAAO,EAAE,SAAS,MAAA;AAAA,QACpB,SAAS,KAAK;AACZ,kBAAQ,KAAK,mDAAmD,GAAG;AACnE,iBAAO,EAAE,SAAS,KAAA;AAAA,QACpB;AAAA,MACF;AACA,cAAQ;AAAA,QACN;AAAA,MAAA;AAEF,aAAO,EAAE,SAAS,KAAA;AAAA,IACpB;AAAA,EAAA;AAEJ;"}

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

@@ -0,0 +1,98 @@
+import { AudioVisualization, RealtimeMessage, RealtimeMode, RealtimeStatus } from '@tanstack/ai/client';
+import { RealtimeClientOptions, RealtimeStateChangeCallback } from './realtime-types.js';
+/**
+ * Client for managing realtime voice conversations.
+ *
+ * Handles connection lifecycle, audio I/O, message state,
+ * and tool execution for realtime voice-to-voice AI interactions.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeClient } from '@tanstack/ai-client'
+ * import { openaiRealtime } from '@tanstack/ai-openai'
+ *
+ * const client = new RealtimeClient({
+ *   getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+ *   adapter: openaiRealtime(),
+ *   tools: [myTool.client(handler)],
+ *   onMessage: (msg) => console.log('Message:', msg),
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
+export declare class RealtimeClient {
+    private readonly options;
+    private connection;
+    private token;
+    private tokenRefreshTimeout;
+    private readonly clientTools;
+    private readonly stateChangeCallbacks;
+    private unsubscribers;
+    private state;
+    constructor(options: RealtimeClientOptions);
+    /**
+     * Connect to the realtime session.
+     * Fetches a token and establishes the connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the realtime session.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Start listening for voice input.
+     * Only needed when vadMode is 'manual'.
+     */
+    startListening(): void;
+    /**
+     * Stop listening for voice input.
+     * Only needed when vadMode is 'manual'.
+     */
+    stopListening(): void;
+    /**
+     * Interrupt the current assistant response.
+     */
+    interrupt(): void;
+    /**
+     * Send a text message instead of voice.
+     */
+    sendText(text: string): void;
+    /**
+     * Send an image to the conversation.
+     * @param imageData - Base64-encoded image data or a URL
+     * @param mimeType - MIME type of the image (e.g., 'image/png', 'image/jpeg')
+     */
+    sendImage(imageData: string, mimeType: string): void;
+    /** Get current connection status */
+    get status(): RealtimeStatus;
+    /** Get current mode */
+    get mode(): RealtimeMode;
+    /** Get conversation messages */
+    get messages(): Array<RealtimeMessage>;
+    /** Get current error, if any */
+    get error(): Error | null;
+    /** Get pending user transcript (while user is speaking) */
+    get pendingUserTranscript(): string | null;
+    /** Get pending assistant transcript (while assistant is speaking) */
+    get pendingAssistantTranscript(): string | null;
+    /** Get audio visualization data */
+    get audio(): AudioVisualization | null;
+    /**
+     * Subscribe to state changes.
+     * @returns Unsubscribe function
+     */
+    onStateChange(callback: RealtimeStateChangeCallback): () => void;
+    /**
+     * Clean up resources.
+     * Call this when disposing of the client.
+     */
+    destroy(): void;
+    private updateState;
+    private addMessage;
+    private scheduleTokenRefresh;
+    private refreshToken;
+    private subscribeToConnectionEvents;
+    private applySessionConfig;
+    private generateId;
+}