@tanstack/ai-client 0.19.2 → 0.20.0

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

@@ -1,4 +1,5 @@
 import { MediaPrompt, StreamChunk } from '@tanstack/ai/client';
+import { TranscriptionResponseFormat } from '@tanstack/ai';
 import { ConnectConnectionAdapter } from './connection-adapters.js';
 import { AIDevtoolsClientMetadata } from './devtools.js';
 import { GenerationDevtoolsBridgeFactory, VideoDevtoolsBridgeFactory } from './devtools-noop.js';
@@ -223,7 +224,7 @@ export interface TranscriptionGenerateInput {
     /** An optional prompt to guide the transcription */
     prompt?: string;
     /** The format of the transcription output */
-    responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
+    responseFormat?: TranscriptionResponseFormat;
     /** Model-specific options */
     modelOptions?: Record<string, any>;
 }

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

@@ -1 +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;"}
+{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'\nimport type { TranscriptionResponseFormat } from '@tanstack/ai'\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?: TranscriptionResponseFormat\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":"AAqEO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -49,7 +49,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "0.39.1",
+    "@tanstack/ai": "0.40.0",
     "@tanstack/ai-event-client": "0.6.8",
     "@tanstack/ai-utils": "0.3.1"
   },

package/src/generation-types.ts

@@ -1,4 +1,5 @@
 import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'
+import type { TranscriptionResponseFormat } from '@tanstack/ai'
 import type { ConnectConnectionAdapter } from './connection-adapters'
 import type { AIDevtoolsClientMetadata } from './devtools'
 import type {
@@ -289,7 +290,7 @@ export interface TranscriptionGenerateInput {
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Model-specific options */
   modelOptions?: Record<string, any>
 }