@tanstack/ai-react 0.6.3 → 0.7.1

package/dist/esm/index.d.ts

@@ -1,3 +1,17 @@
 export { useChat } from './use-chat.js';
+export { useRealtimeChat } from './use-realtime-chat.js';
 export type { UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, } from './types.js';
-export { fetchServerSentEvents, fetchHttpStream, stream, createChatClientOptions, type ConnectionAdapter, type FetchConnectionOptions, type InferChatMessages, } from '@tanstack/ai-client';
+export type { UseRealtimeChatOptions, UseRealtimeChatReturn, } from './realtime-types.js';
+export { useGeneration } from './use-generation.js';
+export type { UseGenerationOptions, UseGenerationReturn, } from './use-generation.js';
+export { useGenerateImage } from './use-generate-image.js';
+export type { UseGenerateImageOptions, UseGenerateImageReturn, } from './use-generate-image.js';
+export { useGenerateSpeech } from './use-generate-speech.js';
+export type { UseGenerateSpeechOptions, UseGenerateSpeechReturn, } from './use-generate-speech.js';
+export { useTranscription } from './use-transcription.js';
+export type { UseTranscriptionOptions, UseTranscriptionReturn, } from './use-transcription.js';
+export { useSummarize } from './use-summarize.js';
+export type { UseSummarizeOptions, UseSummarizeReturn } from './use-summarize.js';
+export { useGenerateVideo } from './use-generate-video.js';
+export type { UseGenerateVideoOptions, UseGenerateVideoReturn, } from './use-generate-video.js';
+export { fetchServerSentEvents, fetchHttpStream, stream, createChatClientOptions, type ConnectionAdapter, type FetchConnectionOptions, type InferChatMessages, type GenerationClientState, type ImageGenerateInput, type SpeechGenerateInput, type TranscriptionGenerateInput, type SummarizeGenerateInput, type VideoGenerateInput, type VideoGenerateResult, type VideoStatusInfo, } from '@tanstack/ai-client';

package/dist/esm/index.js

@@ -1,10 +1,24 @@
 import { useChat } from "./use-chat.js";
+import { useRealtimeChat } from "./use-realtime-chat.js";
+import { useGeneration } from "./use-generation.js";
+import { useGenerateImage } from "./use-generate-image.js";
+import { useGenerateSpeech } from "./use-generate-speech.js";
+import { useTranscription } from "./use-transcription.js";
+import { useSummarize } from "./use-summarize.js";
+import { useGenerateVideo } from "./use-generate-video.js";
 import { createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream } from "@tanstack/ai-client";
 export {
   createChatClientOptions,
   fetchHttpStream,
   fetchServerSentEvents,
   stream,
-  useChat
+  useChat,
+  useGenerateImage,
+  useGenerateSpeech,
+  useGenerateVideo,
+  useGeneration,
+  useRealtimeChat,
+  useSummarize,
+  useTranscription
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

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

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

@@ -0,0 +1,109 @@
+import { AnyClientTool, RealtimeMessage, RealtimeMode, RealtimeStatus, RealtimeToken } from '@tanstack/ai';
+import { RealtimeAdapter } from '@tanstack/ai-client';
+/**
+ * Options for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatOptions {
+    /**
+     * Function to fetch a realtime token from the server.
+     * Called on connect and when token needs refresh.
+     */
+    getToken: () => Promise<RealtimeToken>;
+    /**
+     * The realtime adapter to use (e.g., openaiRealtime())
+     */
+    adapter: RealtimeAdapter;
+    /**
+     * Client-side tools with execution logic
+     */
+    tools?: ReadonlyArray<AnyClientTool>;
+    /**
+     * Auto-play assistant audio (default: true)
+     */
+    autoPlayback?: boolean;
+    /**
+     * Request microphone access on connect (default: true)
+     */
+    autoCapture?: boolean;
+    /**
+     * System instructions for the assistant
+     */
+    instructions?: string;
+    /**
+     * Voice to use for audio output
+     */
+    voice?: string;
+    /**
+     * Voice activity detection mode (default: 'server')
+     */
+    vadMode?: 'server' | 'semantic' | 'manual';
+    /**
+     * Output modalities for responses (e.g., ['audio', 'text'])
+     */
+    outputModalities?: Array<'audio' | 'text'>;
+    /**
+     * Temperature for generation (provider-specific range)
+     */
+    temperature?: number;
+    /**
+     * Maximum number of tokens in a response
+     */
+    maxOutputTokens?: number | 'inf';
+    /**
+     * Eagerness level for semantic VAD ('low', 'medium', 'high')
+     */
+    semanticEagerness?: 'low' | 'medium' | 'high';
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (error: Error) => void;
+    onMessage?: (message: RealtimeMessage) => void;
+    onModeChange?: (mode: RealtimeMode) => void;
+    onInterrupted?: () => void;
+}
+/**
+ * Return type for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatReturn {
+    /** Current connection status */
+    status: RealtimeStatus;
+    /** Current error, if any */
+    error: Error | null;
+    /** Connect to the realtime session */
+    connect: () => Promise<void>;
+    /** Disconnect from the realtime session */
+    disconnect: () => Promise<void>;
+    /** Current mode (idle, listening, thinking, speaking) */
+    mode: RealtimeMode;
+    /** Conversation messages */
+    messages: Array<RealtimeMessage>;
+    /** User transcript while speaking (before finalized) */
+    pendingUserTranscript: string | null;
+    /** Assistant transcript while speaking (before finalized) */
+    pendingAssistantTranscript: string | null;
+    /** Start listening for voice input (manual VAD mode) */
+    startListening: () => void;
+    /** Stop listening for voice input (manual VAD mode) */
+    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 */
+    sendImage: (imageData: string, mimeType: string) => void;
+    /** Current input (microphone) volume level */
+    inputLevel: number;
+    /** Current output (speaker) volume level */
+    outputLevel: number;
+    /** Get frequency data for input audio visualization */
+    getInputFrequencyData: () => Uint8Array;
+    /** Get frequency data for output audio visualization */
+    getOutputFrequencyData: () => Uint8Array;
+    /** Get time domain data for input waveform */
+    getInputTimeDomainData: () => Uint8Array;
+    /** Get time domain data for output waveform */
+    getOutputTimeDomainData: () => Uint8Array;
+    /** Current VAD mode */
+    vadMode: 'server' | 'semantic' | 'manual';
+    /** Change VAD mode at runtime */
+    setVADMode: (mode: 'server' | 'semantic' | 'manual') => void;
+}

package/dist/esm/use-generate-image.d.ts

@@ -0,0 +1,87 @@
+import { ImageGenerationResult, StreamChunk } from '@tanstack/ai';
+import { ConnectionAdapter, GenerationClientState, GenerationFetcher, ImageGenerateInput, InferGenerationOutput } from '@tanstack/ai-client';
+/**
+ * Options for the useGenerateImage hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)
+ */
+export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
+    /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectionAdapter;
+    /** Direct async function for image generation */
+    fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with ConnectionAdapter requests */
+    body?: Record<string, any>;
+    /**
+     * Callback when images are generated. Can optionally return a transformed value.
+     *
+     * - 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: ImageGenerationResult) => 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 (ConnectionAdapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGenerateImage hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
+    /** Trigger image generation */
+    generate: (input: ImageGenerateInput) => Promise<void>;
+    /** The generation result containing images, or null */
+    result: TOutput | null;
+    /** Whether generation is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * React hook for generating images using AI models.
+ *
+ * Supports two transport modes:
+ * - **ConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** — Direct async function call
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateImage } from '@tanstack/ai-react'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function ImageGenerator() {
+ *   const { generate, result, isLoading, error, reset } = useGenerateImage({
+ *     connection: fetchServerSentEvents('/api/generate/image'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ prompt: 'A sunset over mountains' })}>
+ *         Generate
+ *       </button>
+ *       {isLoading && <p>Generating...</p>}
+ *       {error && <p>Error: {error.message}</p>}
+ *       {result?.images.map((img, i) => (
+ *         <img key={i} src={img.url || `data:image/png;base64,${img.b64Json}`} />
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useGenerateImage<TOnResult extends ((result: ImageGenerationResult) => any) | undefined = undefined>(options: Omit<UseGenerateImageOptions, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseGenerateImageReturn<InferGenerationOutput<ImageGenerationResult, TOnResult>>;

package/dist/esm/use-generate-image.js

@@ -0,0 +1,17 @@
+import { useGeneration } from "./use-generation.js";
+function useGenerateImage(options) {
+  const { generate, result, isLoading, error, status, stop, reset } = useGeneration(options);
+  return {
+    generate,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset
+  };
+}
+export {
+  useGenerateImage
+};
+//# sourceMappingURL=use-generate-image.js.map

package/dist/esm/use-generate-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-generate-image.js","sources":["../../src/use-generate-image.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'\nimport type {\n  ConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  ImageGenerateInput,\n  InferGenerationOutput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGenerateImage hook.\n *\n * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)\n */\nexport interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {\n  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectionAdapter\n  /** Direct async function for image generation */\n  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with ConnectionAdapter requests */\n  body?: Record<string, any>\n  /**\n   * Callback when images are generated. Can optionally return a transformed value.\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: ImageGenerationResult) => 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 (ConnectionAdapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n}\n\n/**\n * Return type for the useGenerateImage hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {\n  /** Trigger image generation */\n  generate: (input: ImageGenerateInput) => Promise<void>\n  /** The generation result containing images, or null */\n  result: TOutput | null\n  /** Whether generation is in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation */\n  status: GenerationClientState\n  /** Abort the current generation */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n}\n\n/**\n * React hook for generating images using AI models.\n *\n * Supports two transport modes:\n * - **ConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)\n * - **Fetcher** — Direct async function call\n *\n * @example\n * ```tsx\n * import { useGenerateImage } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function ImageGenerator() {\n *   const { generate, result, isLoading, error, reset } = useGenerateImage({\n *     connection: fetchServerSentEvents('/api/generate/image'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A sunset over mountains' })}>\n *         Generate\n *       </button>\n *       {isLoading && <p>Generating...</p>}\n *       {error && <p>Error: {error.message}</p>}\n *       {result?.images.map((img, i) => (\n *         <img key={i} src={img.url || `data:image/png;base64,${img.b64Json}`} />\n *       ))}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateImage<\n  TOnResult extends ((result: ImageGenerationResult) => any) | undefined =\n    undefined,\n>(\n  options: Omit<UseGenerateImageOptions, 'onResult'> & {\n    onResult?: TOnResult\n  },\n): UseGenerateImageReturn<\n  InferGenerationOutput<ImageGenerationResult, TOnResult>\n> {\n  const { generate, result, isLoading, error, status, stop, reset } =\n    useGeneration<ImageGenerateInput, ImageGenerationResult, TOnResult>(options)\n\n  return {\n    generate: generate as (input: ImageGenerateInput) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";AA8FO,SAAS,iBAId,SAKA;AACA,QAAM,EAAE,UAAU,QAAQ,WAAW,OAAO,QAAQ,MAAM,MAAA,IACxD,cAAoE,OAAO;AAE7E,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

package/dist/esm/use-generate-speech.d.ts

@@ -0,0 +1,81 @@
+import { StreamChunk, TTSResult } from '@tanstack/ai';
+import { ConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutput, SpeechGenerateInput } from '@tanstack/ai-client';
+/**
+ * Options for the useGenerateSpeech hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to TTSResult)
+ */
+export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
+    /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectionAdapter;
+    /** Direct async function for speech generation */
+    fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with ConnectionAdapter requests */
+    body?: Record<string, any>;
+    /**
+     * Callback when speech is generated. Can optionally return a transformed value.
+     *
+     * - 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: TTSResult) => 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 (ConnectionAdapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGenerateSpeech hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
+    /** Trigger speech generation */
+    generate: (input: SpeechGenerateInput) => Promise<void>;
+    /** The TTS result containing audio data, or null */
+    result: TOutput | null;
+    /** Whether generation is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * React hook for generating speech (text-to-speech) using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateSpeech } from '@tanstack/ai-react'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function SpeechGenerator() {
+ *   const { generate, result, isLoading } = useGenerateSpeech({
+ *     connection: fetchServerSentEvents('/api/generate/speech'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>
+ *         Generate Speech
+ *       </button>
+ *       {result && (
+ *         <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useGenerateSpeech<TOnResult extends ((result: TTSResult) => any) | undefined = undefined>(options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseGenerateSpeechReturn<InferGenerationOutput<TTSResult, TOnResult>>;

package/dist/esm/use-generate-speech.js

@@ -0,0 +1,17 @@
+import { useGeneration } from "./use-generation.js";
+function useGenerateSpeech(options) {
+  const { generate, result, isLoading, error, status, stop, reset } = useGeneration(options);
+  return {
+    generate,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset
+  };
+}
+export {
+  useGenerateSpeech
+};
+//# sourceMappingURL=use-generate-speech.js.map

package/dist/esm/use-generate-speech.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-generate-speech.js","sources":["../../src/use-generate-speech.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport type { StreamChunk, TTSResult } from '@tanstack/ai'\nimport type {\n  ConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutput,\n  SpeechGenerateInput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGenerateSpeech hook.\n *\n * @template TOutput - The output type after optional transform (defaults to TTSResult)\n */\nexport interface UseGenerateSpeechOptions<TOutput = TTSResult> {\n  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectionAdapter\n  /** Direct async function for speech generation */\n  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with ConnectionAdapter requests */\n  body?: Record<string, any>\n  /**\n   * Callback when speech is generated. Can optionally return a transformed value.\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: TTSResult) => 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 (ConnectionAdapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n}\n\n/**\n * Return type for the useGenerateSpeech hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateSpeechReturn<TOutput = TTSResult> {\n  /** Trigger speech generation */\n  generate: (input: SpeechGenerateInput) => Promise<void>\n  /** The TTS result containing audio data, or null */\n  result: TOutput | null\n  /** Whether generation is in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation */\n  status: GenerationClientState\n  /** Abort the current generation */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n}\n\n/**\n * React hook for generating speech (text-to-speech) using AI models.\n *\n * @example\n * ```tsx\n * import { useGenerateSpeech } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function SpeechGenerator() {\n *   const { generate, result, isLoading } = useGenerateSpeech({\n *     connection: fetchServerSentEvents('/api/generate/speech'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>\n *         Generate Speech\n *       </button>\n *       {result && (\n *         <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />\n *       )}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateSpeech<\n  TOnResult extends ((result: TTSResult) => any) | undefined = undefined,\n>(\n  options: Omit<UseGenerateSpeechOptions, 'onResult'> & {\n    onResult?: TOnResult\n  },\n): UseGenerateSpeechReturn<InferGenerationOutput<TTSResult, TOnResult>> {\n  const { generate, result, isLoading, error, status, stop, reset } =\n    useGeneration<SpeechGenerateInput, TTSResult, TOnResult>(options)\n\n  return {\n    generate: generate as (input: SpeechGenerateInput) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";AAwFO,SAAS,kBAGd,SAGsE;AACtE,QAAM,EAAE,UAAU,QAAQ,WAAW,OAAO,QAAQ,MAAM,MAAA,IACxD,cAAyD,OAAO;AAElE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

package/dist/esm/use-generate-video.d.ts

@@ -0,0 +1,92 @@
+import { StreamChunk } from '@tanstack/ai';
+import { ConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutput, VideoGenerateInput, VideoGenerateResult, VideoStatusInfo } from '@tanstack/ai-client';
+/**
+ * Options for the useGenerateVideo hook.
+ */
+export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
+    /** Connection adapter for streaming transport (server handles polling) */
+    connection?: ConnectionAdapter;
+    /** Direct async function that returns a completed video result */
+    fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with ConnectionAdapter requests */
+    body?: Record<string, any>;
+    /**
+     * Callback when video generation completes. Can optionally return a transformed value.
+     *
+     * - 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: VideoGenerateResult) => 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 when a video job is created */
+    onJobCreated?: (jobId: string) => void;
+    /** Callback on each status update */
+    onStatusUpdate?: (status: VideoStatusInfo) => void;
+    /** Callback for each stream chunk (ConnectionAdapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGenerateVideo hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
+    /** Trigger video generation */
+    generate: (input: VideoGenerateInput) => Promise<void>;
+    /** The final video result (with URL), or null */
+    result: TOutput | null;
+    /** The current job ID, or null */
+    jobId: string | null;
+    /** Current video generation status info, or null */
+    videoStatus: VideoStatusInfo | null;
+    /** Whether generation/polling is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current generation/polling */
+    stop: () => void;
+    /** Clear all state and return to idle */
+    reset: () => void;
+}
+/**
+ * React hook for generating videos using AI models.
+ *
+ * Video generation is asynchronous: a job is created, then polled for status
+ * until completion. This hook handles the full lifecycle.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateVideo } from '@tanstack/ai-react'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function VideoGenerator() {
+ *   const { generate, result, videoStatus, isLoading } = useGenerateVideo({
+ *     connection: fetchServerSentEvents('/api/generate/video'),
+ *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>
+ *         Generate Video
+ *       </button>
+ *       {isLoading && videoStatus && (
+ *         <p>Status: {videoStatus.status} ({videoStatus.progress}%)</p>
+ *       )}
+ *       {result && <video src={result.url} controls />}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useGenerateVideo<TOnResult extends ((result: VideoGenerateResult) => any) | undefined = undefined>(options: Omit<UseGenerateVideoOptions, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseGenerateVideoReturn<InferGenerationOutput<VideoGenerateResult, TOnResult>>;

package/dist/esm/use-generate-video.js

@@ -0,0 +1,83 @@
+import { VideoGenerationClient } from "@tanstack/ai-client";
+import { useId, useState, useRef, useMemo, useEffect, useCallback } from "react";
+function useGenerateVideo(options) {
+  const hookId = useId();
+  const clientId = options.id || hookId;
+  const [result, setResult] = useState(null);
+  const [jobId, setJobId] = useState(null);
+  const [videoStatus, setVideoStatus] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(void 0);
+  const [status, setStatus] = useState("idle");
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const client = useMemo(() => {
+    const opts = optionsRef.current;
+    const baseOptions = {
+      id: clientId,
+      body: opts.body,
+      onResult: (r) => optionsRef.current.onResult?.(r),
+      onError: (e) => optionsRef.current.onError?.(e),
+      onProgress: (p, m) => optionsRef.current.onProgress?.(p, m),
+      onChunk: (c) => optionsRef.current.onChunk?.(c),
+      onJobCreated: (id) => optionsRef.current.onJobCreated?.(id),
+      onStatusUpdate: (s) => optionsRef.current.onStatusUpdate?.(s),
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus,
+      onJobIdChange: setJobId,
+      onVideoStatusChange: setVideoStatus
+    };
+    if (opts.connection) {
+      return new VideoGenerationClient({
+        ...baseOptions,
+        connection: opts.connection
+      });
+    }
+    if (opts.fetcher) {
+      return new VideoGenerationClient({
+        ...baseOptions,
+        fetcher: opts.fetcher
+      });
+    }
+    throw new Error(
+      "useGenerateVideo requires either a connection or fetcher option"
+    );
+  }, [clientId]);
+  useEffect(() => {
+    client.updateOptions({ body: options.body });
+  }, [client, options.body]);
+  useEffect(() => {
+    return () => {
+      client.stop();
+    };
+  }, [client]);
+  const generate = useCallback(
+    async (input) => {
+      await client.generate(input);
+    },
+    [client]
+  );
+  const stop = useCallback(() => {
+    client.stop();
+  }, [client]);
+  const reset = useCallback(() => {
+    client.reset();
+  }, [client]);
+  return {
+    generate,
+    result,
+    jobId,
+    videoStatus,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset
+  };
+}
+export {
+  useGenerateVideo
+};
+//# sourceMappingURL=use-generate-video.js.map

package/dist/esm/use-generate-video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-generate-video.js","sources":["../../src/use-generate-video.ts"],"sourcesContent":["import { VideoGenerationClient } from '@tanstack/ai-client'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  ConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutput,\n  VideoGenerateInput,\n  VideoGenerateResult,\n  VideoStatusInfo,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGenerateVideo hook.\n */\nexport interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {\n  /** Connection adapter for streaming transport (server handles polling) */\n  connection?: ConnectionAdapter\n  /** Direct async function that returns a completed video result */\n  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with ConnectionAdapter requests */\n  body?: Record<string, any>\n  /**\n   * Callback when video generation completes. Can optionally return a transformed value.\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: VideoGenerateResult) => 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 when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n  /** Callback for each stream chunk (ConnectionAdapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n}\n\n/**\n * Return type for the useGenerateVideo hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {\n  /** Trigger video generation */\n  generate: (input: VideoGenerateInput) => Promise<void>\n  /** The final video result (with URL), or null */\n  result: TOutput | null\n  /** The current job ID, or null */\n  jobId: string | null\n  /** Current video generation status info, or null */\n  videoStatus: VideoStatusInfo | null\n  /** Whether generation/polling is in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation */\n  status: GenerationClientState\n  /** Abort the current generation/polling */\n  stop: () => void\n  /** Clear all state and return to idle */\n  reset: () => void\n}\n\n/**\n * React hook for generating videos using AI models.\n *\n * Video generation is asynchronous: a job is created, then polled for status\n * until completion. This hook handles the full lifecycle.\n *\n * @example\n * ```tsx\n * import { useGenerateVideo } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function VideoGenerator() {\n *   const { generate, result, videoStatus, isLoading } = useGenerateVideo({\n *     connection: fetchServerSentEvents('/api/generate/video'),\n *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>\n *         Generate Video\n *       </button>\n *       {isLoading && videoStatus && (\n *         <p>Status: {videoStatus.status} ({videoStatus.progress}%)</p>\n *       )}\n *       {result && <video src={result.url} controls />}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateVideo<\n  TOnResult extends ((result: VideoGenerateResult) => any) | undefined =\n    undefined,\n>(\n  options: Omit<UseGenerateVideoOptions, 'onResult'> & {\n    onResult?: TOnResult\n  },\n): UseGenerateVideoReturn<\n  InferGenerationOutput<VideoGenerateResult, TOnResult>\n> {\n  type TOutput = InferGenerationOutput<VideoGenerateResult, TOnResult>\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [jobId, setJobId] = useState<string | null>(null)\n  const [videoStatus, setVideoStatus] = useState<VideoStatusInfo | null>(null)\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<GenerationClientState>('idle')\n\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n\n  const client = useMemo(() => {\n    const opts = optionsRef.current\n\n    const baseOptions = {\n      id: clientId,\n      body: opts.body,\n      onResult: (r: VideoGenerateResult) => optionsRef.current.onResult?.(r),\n      onError: (e: Error) => optionsRef.current.onError?.(e),\n      onProgress: (p: number, m?: string) =>\n        optionsRef.current.onProgress?.(p, m),\n      onChunk: (c: StreamChunk) => optionsRef.current.onChunk?.(c),\n      onJobCreated: (id: string) => optionsRef.current.onJobCreated?.(id),\n      onStatusUpdate: (s: VideoStatusInfo) =>\n        optionsRef.current.onStatusUpdate?.(s),\n      onResultChange: setResult,\n      onLoadingChange: setIsLoading,\n      onErrorChange: setError,\n      onStatusChange: setStatus,\n      onJobIdChange: setJobId,\n      onVideoStatusChange: setVideoStatus,\n    }\n\n    if (opts.connection) {\n      return new VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGenerateVideo requires either a connection or fetcher option',\n    )\n  }, [clientId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    client.updateOptions({ body: options.body })\n  }, [client, options.body])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      client.stop()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: VideoGenerateInput) => {\n      await client.generate(input)\n    },\n    [client],\n  )\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const reset = useCallback(() => {\n    client.reset()\n  }, [client])\n\n  return {\n    generate,\n    result,\n    jobId,\n    videoStatus,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";;AAsGO,SAAS,iBAId,SAKA;AAEA,QAAM,SAAS,MAAA;AACf,QAAM,WAAW,QAAQ,MAAM;AAE/B,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAyB,IAAI;AACzD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AACtD,QAAM,CAAC,aAAa,cAAc,IAAI,SAAiC,IAAI;AAC3E,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,KAAK;AAChD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA4B,MAAS;AAC/D,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAgC,MAAM;AAElE,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,SAAS,QAAQ,MAAM;AAC3B,UAAM,OAAO,WAAW;AAExB,UAAM,cAAc;AAAA,MAClB,IAAI;AAAA,MACJ,MAAM,KAAK;AAAA,MACX,UAAU,CAAC,MAA2B,WAAW,QAAQ,WAAW,CAAC;AAAA,MACrE,SAAS,CAAC,MAAa,WAAW,QAAQ,UAAU,CAAC;AAAA,MACrD,YAAY,CAAC,GAAW,MACtB,WAAW,QAAQ,aAAa,GAAG,CAAC;AAAA,MACtC,SAAS,CAAC,MAAmB,WAAW,QAAQ,UAAU,CAAC;AAAA,MAC3D,cAAc,CAAC,OAAe,WAAW,QAAQ,eAAe,EAAE;AAAA,MAClE,gBAAgB,CAAC,MACf,WAAW,QAAQ,iBAAiB,CAAC;AAAA,MACvC,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,eAAe;AAAA,MACf,gBAAgB;AAAA,MAChB,eAAe;AAAA,MACf,qBAAqB;AAAA,IAAA;AAGvB,QAAI,KAAK,YAAY;AACnB,aAAO,IAAI,sBAA+B;AAAA,QACxC,GAAG;AAAA,QACH,YAAY,KAAK;AAAA,MAAA,CAClB;AAAA,IACH;AAEA,QAAI,KAAK,SAAS;AAChB,aAAO,IAAI,sBAA+B;AAAA,QACxC,GAAG;AAAA,QACH,SAAS,KAAK;AAAA,MAAA,CACf;AAAA,IACH;AAEA,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ,GAAG,CAAC,QAAQ,CAAC;AAGb,YAAU,MAAM;AACd,WAAO,cAAc,EAAE,MAAM,QAAQ,MAAM;AAAA,EAC7C,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;AAGzB,YAAU,MAAM;AACd,WAAO,MAAM;AACX,aAAO,KAAA;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,WAAW;AAAA,IACf,OAAO,UAA8B;AACnC,YAAM,OAAO,SAAS,KAAK;AAAA,IAC7B;AAAA,IACA,CAAC,MAAM;AAAA,EAAA;AAGT,QAAM,OAAO,YAAY,MAAM;AAC7B,WAAO,KAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,QAAQ,YAAY,MAAM;AAC9B,WAAO,MAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

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

@@ -0,0 +1,78 @@
+import { StreamChunk } from '@tanstack/ai';
+import { ConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutput } from '@tanstack/ai-client';
+/**
+ * Options for the useGeneration hook.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
+    /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectionAdapter;
+    /** Direct async function for one-shot generation (no streaming protocol needed) */
+    fetcher?: GenerationFetcher<TInput, TResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with ConnectionAdapter requests */
+    body?: Record<string, any>;
+    /**
+     * Callback when a result is received. Can optionally return a transformed value.
+     *
+     * - 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 (ConnectionAdapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGeneration hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerationReturn<TOutput> {
+    /** Trigger a generation request */
+    generate: (input: Record<string, any>) => Promise<void>;
+    /** The generation result, or null if not yet generated */
+    result: TOutput | null;
+    /** Whether a generation is currently in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation client */
+    status: GenerationClientState;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * Generic React hook for one-shot generation tasks.
+ *
+ * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,
+ * `useTranscription`, and `useSummarize`. You can also use it directly
+ * for custom generation types.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ *
+ * @example
+ * ```tsx
+ * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({
+ *   connection: fetchServerSentEvents('/api/generate/custom'),
+ * })
+ *
+ * await generate({ prompt: 'Hello' })
+ * ```
+ */
+export declare function useGeneration<TInput extends Record<string, any>, TResult, TOnResult extends ((result: TResult) => any) | undefined = undefined>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseGenerationReturn<InferGenerationOutput<TResult, TOnResult>>;