@tanstack/ai-react 0.15.14 → 0.15.15

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

@@ -0,0 +1,80 @@
+import { StreamChunk } from '@tanstack/ai';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, 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> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** 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 connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * 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 (connect-based adapter 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>>;

package/dist/esm/use-generation.js

@@ -0,0 +1,91 @@
+import { GenerationClient } from "@tanstack/ai-client";
+import { createGenerationDevtoolsBridge } from "@tanstack/ai-client/devtools";
+import { useId, useState, useRef, useMemo, useEffect, useCallback } from "react";
+function useGeneration(options) {
+  const hookId = useId();
+  const clientId = options.id || hookId;
+  const [result, setResult] = 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 clientOptions = {
+      id: clientId,
+      body: opts.body,
+      devtoolsBridgeFactory: createGenerationDevtoolsBridge,
+      devtools: {
+        hookName: "useGeneration",
+        framework: "react",
+        ...opts.devtools
+      },
+      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);
+      },
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus
+    };
+    if (opts.connection) {
+      return new GenerationClient({
+        ...clientOptions,
+        connection: opts.connection
+      });
+    }
+    if (opts.fetcher) {
+      return new GenerationClient({
+        ...clientOptions,
+        fetcher: opts.fetcher
+      });
+    }
+    throw new Error(
+      "useGeneration requires either a connection or fetcher option"
+    );
+  }, [clientId]);
+  useEffect(() => {
+    client.updateOptions({
+      ...options.body !== void 0 && { body: options.body }
+    });
+  }, [client, options.body]);
+  useEffect(() => {
+    client.mountDevtools();
+    return () => {
+      client.dispose();
+    };
+  }, [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,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset
+  };
+}
+export {
+  useGeneration
+};
+//# sourceMappingURL=use-generation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-generation.js","sources":["../../src/use-generation.ts"],"sourcesContent":["import { GenerationClient } from '@tanstack/ai-client'\nimport { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGeneration hook.\n *\n * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\nexport interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for one-shot generation (no streaming protocol needed) */\n  fetcher?: GenerationFetcher<TInput, TResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * Callback when a result is received. 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: 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\n/**\n * Return type for the useGeneration hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerationReturn<TOutput> {\n  /** Trigger a generation request */\n  generate: (input: Record<string, any>) => Promise<void>\n  /** The generation result, or null if not yet generated */\n  result: TOutput | null\n  /** Whether a generation is currently in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation client */\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 * Generic React hook for one-shot generation tasks.\n *\n * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,\n * `useTranscription`, and `useSummarize`. You can also use it directly\n * for custom generation types.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```tsx\n * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({\n *   connection: fetchServerSentEvents('/api/generate/custom'),\n * })\n *\n * await generate({ prompt: 'Hello' })\n * ```\n */\nexport function useGeneration<\n  TInput extends Record<string, any>,\n  TResult,\n  TOnResult extends ((result: TResult) => any) | undefined = undefined,\n>(\n  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {\n    onResult?: TOnResult\n  },\n): UseGenerationReturn<InferGenerationOutput<TResult, TOnResult>> {\n  type TOutput = InferGenerationOutput<TResult, TOnResult>\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [result, setResult] = useState<TOutput | 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    // Conditional spread for `body` (strict-optional in target;\n    // local source is `Record<string, any> | undefined`). Callbacks\n    // wrap optional ones in non-returning bodies so `?.()`'s\n    // implicit `undefined` doesn't pollute the function return type.\n    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {\n      id: clientId,\n      body: opts.body,\n      devtoolsBridgeFactory: createGenerationDevtoolsBridge,\n      devtools: {\n        hookName: 'useGeneration',\n        framework: 'react',\n        ...opts.devtools,\n      },\n      onResult: (r: TResult) => optionsRef.current.onResult?.(r),\n      onError: (e: Error) => {\n        optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        optionsRef.current.onChunk?.(c)\n      },\n      onResultChange: setResult,\n      onLoadingChange: setIsLoading,\n      onErrorChange: setError,\n      onStatusChange: setStatus,\n    }\n\n    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGeneration requires either a connection or fetcher option',\n    )\n  }, [clientId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    // Conditional spread: target uses strict-optional `body?: T`.\n    client.updateOptions({\n      ...(options.body !== undefined && { body: options.body }),\n    })\n  }, [client, options.body])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    client.mountDevtools()\n\n    return () => {\n      client.dispose()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: TInput) => {\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: generate as (input: Record<string, any>) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";;;AA0FO,SAAS,cAKd,SAGgE;AAEhE,QAAM,SAAS,MAAA;AACf,QAAM,WAAW,QAAQ,MAAM;AAE/B,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAyB,IAAI;AACzD,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;AAMxB,UAAM,gBAAmE;AAAA,MACvE,IAAI;AAAA,MACJ,MAAM,KAAK;AAAA,MACX,uBAAuB;AAAA,MACvB,UAAU;AAAA,QACR,UAAU;AAAA,QACV,WAAW;AAAA,QACX,GAAG,KAAK;AAAA,MAAA;AAAA,MAEV,UAAU,CAAC,MAAe,WAAW,QAAQ,WAAW,CAAC;AAAA,MACzD,SAAS,CAAC,MAAa;AACrB,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,YAAY,CAAC,GAAW,MAAe;AACrC,mBAAW,QAAQ,aAAa,GAAG,CAAC;AAAA,MACtC;AAAA,MACA,SAAS,CAAC,MAAmB;AAC3B,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,eAAe;AAAA,MACf,gBAAgB;AAAA,IAAA;AAGlB,QAAI,KAAK,YAAY;AACnB,aAAO,IAAI,iBAA2C;AAAA,QACpD,GAAG;AAAA,QACH,YAAY,KAAK;AAAA,MAAA,CAClB;AAAA,IACH;AAEA,QAAI,KAAK,SAAS;AAChB,aAAO,IAAI,iBAA2C;AAAA,QACpD,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;AAEd,WAAO,cAAc;AAAA,MACnB,GAAI,QAAQ,SAAS,UAAa,EAAE,MAAM,QAAQ,KAAA;AAAA,IAAK,CACxD;AAAA,EACH,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;AAGzB,YAAU,MAAM;AACd,WAAO,cAAA;AAEP,WAAO,MAAM;AACX,aAAO,QAAA;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,WAAW;AAAA,IACf,OAAO,UAAkB;AACvB,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,EAAA;AAEJ;"}

package/dist/esm/use-realtime-chat.d.ts

@@ -0,0 +1,42 @@
+import { UseRealtimeChatOptions, UseRealtimeChatReturn } from './realtime-types.js';
+/**
+ * React hook for realtime voice conversations.
+ *
+ * Provides a simple interface for voice-to-voice AI interactions
+ * with support for multiple providers (OpenAI, ElevenLabs, etc.).
+ *
+ * @param options - Configuration options including adapter and callbacks
+ * @returns Hook return value with state and control methods
+ *
+ * @example
+ * ```typescript
+ * import { useRealtimeChat } from '@tanstack/ai-react'
+ * import { openaiRealtime } from '@tanstack/ai-openai'
+ *
+ * function VoiceChat() {
+ *   const {
+ *     status,
+ *     mode,
+ *     messages,
+ *     connect,
+ *     disconnect,
+ *     inputLevel,
+ *     outputLevel,
+ *   } = useRealtimeChat({
+ *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+ *     adapter: openaiRealtime(),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {status}</p>
+ *       <p>Mode: {mode}</p>
+ *       <button onClick={status === 'idle' ? connect : disconnect}>
+ *         {status === 'idle' ? 'Start' : 'Stop'}
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useRealtimeChat(options: UseRealtimeChatOptions): UseRealtimeChatReturn;

package/dist/esm/use-realtime-chat.js

@@ -0,0 +1,189 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { RealtimeClient } from "@tanstack/ai-client";
+const emptyFrequencyData = new Uint8Array(128);
+const emptyTimeDomainData = new Uint8Array(128).fill(128);
+function useRealtimeChat(options) {
+  const [status, setStatus] = useState("idle");
+  const [mode, setMode] = useState("idle");
+  const [messages, setMessages] = useState([]);
+  const [pendingUserTranscript, setPendingUserTranscript] = useState(null);
+  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState(null);
+  const [error, setError] = useState(null);
+  const [inputLevel, setInputLevel] = useState(0);
+  const [outputLevel, setOutputLevel] = useState(0);
+  const [vadMode, setVADModeState] = useState(
+    options.vadMode ?? "server"
+  );
+  const clientRef = useRef(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const animationFrameRef = useRef(null);
+  if (!clientRef.current) {
+    const initial = optionsRef.current;
+    clientRef.current = new RealtimeClient({
+      getToken: initial.getToken,
+      adapter: initial.adapter,
+      ...initial.tools !== void 0 && { tools: initial.tools },
+      ...initial.instructions !== void 0 && {
+        instructions: initial.instructions
+      },
+      ...initial.voice !== void 0 && { voice: initial.voice },
+      ...initial.autoPlayback !== void 0 && {
+        autoPlayback: initial.autoPlayback
+      },
+      ...initial.autoCapture !== void 0 && {
+        autoCapture: initial.autoCapture
+      },
+      ...initial.vadMode !== void 0 && { vadMode: initial.vadMode },
+      ...initial.outputModalities !== void 0 && {
+        outputModalities: initial.outputModalities
+      },
+      ...initial.temperature !== void 0 && {
+        temperature: initial.temperature
+      },
+      ...initial.maxOutputTokens !== void 0 && {
+        maxOutputTokens: initial.maxOutputTokens
+      },
+      ...initial.semanticEagerness !== void 0 && {
+        semanticEagerness: initial.semanticEagerness
+      },
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus);
+      },
+      onModeChange: (newMode) => {
+        setMode(newMode);
+        optionsRef.current.onModeChange?.(newMode);
+      },
+      onMessage: (message) => {
+        setMessages((prev) => [...prev, message]);
+        optionsRef.current.onMessage?.(message);
+      },
+      onError: (err) => {
+        setError(err);
+        optionsRef.current.onError?.(err);
+      },
+      onConnect: () => {
+        setError(null);
+        optionsRef.current.onConnect?.();
+      },
+      onDisconnect: () => {
+        optionsRef.current.onDisconnect?.();
+      },
+      onInterrupted: () => {
+        setPendingAssistantTranscript(null);
+        optionsRef.current.onInterrupted?.();
+      }
+    });
+    clientRef.current.onStateChange((state) => {
+      setPendingUserTranscript(state.pendingUserTranscript);
+      setPendingAssistantTranscript(state.pendingAssistantTranscript);
+    });
+  }
+  const client = clientRef.current;
+  useEffect(() => {
+    function updateLevels() {
+      if (clientRef.current?.audio) {
+        setInputLevel(clientRef.current.audio.inputLevel);
+        setOutputLevel(clientRef.current.audio.outputLevel);
+      }
+      animationFrameRef.current = requestAnimationFrame(updateLevels);
+    }
+    if (status === "connected") {
+      updateLevels();
+    }
+    return () => {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+        animationFrameRef.current = null;
+      }
+    };
+  }, [status]);
+  useEffect(() => {
+    return () => {
+      clientRef.current?.destroy();
+    };
+  }, []);
+  const connect = useCallback(async () => {
+    setError(null);
+    setMessages([]);
+    setPendingUserTranscript(null);
+    setPendingAssistantTranscript(null);
+    await client.connect();
+  }, [client]);
+  const disconnect = useCallback(async () => {
+    await client.disconnect();
+  }, [client]);
+  const startListening = useCallback(() => {
+    client.startListening();
+  }, [client]);
+  const stopListening = useCallback(() => {
+    client.stopListening();
+  }, [client]);
+  const interrupt = useCallback(() => {
+    client.interrupt();
+  }, [client]);
+  const sendText = useCallback(
+    (text) => {
+      client.sendText(text);
+    },
+    [client]
+  );
+  const sendImage = useCallback(
+    (imageData, mimeType) => {
+      client.sendImage(imageData, mimeType);
+    },
+    [client]
+  );
+  const getInputFrequencyData = useCallback(() => {
+    return clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData;
+  }, []);
+  const getOutputFrequencyData = useCallback(() => {
+    return clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData;
+  }, []);
+  const getInputTimeDomainData = useCallback(() => {
+    return clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData;
+  }, []);
+  const getOutputTimeDomainData = useCallback(() => {
+    return clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData;
+  }, []);
+  const setVADMode = useCallback(
+    (newMode) => {
+      setVADModeState(newMode);
+    },
+    []
+  );
+  return {
+    // Connection state
+    status,
+    error,
+    connect,
+    disconnect,
+    // Conversation state
+    mode,
+    messages,
+    pendingUserTranscript,
+    pendingAssistantTranscript,
+    // Voice control
+    startListening,
+    stopListening,
+    interrupt,
+    // Text input
+    sendText,
+    // Image input
+    sendImage,
+    // Audio visualization
+    inputLevel,
+    outputLevel,
+    getInputFrequencyData,
+    getOutputFrequencyData,
+    getInputTimeDomainData,
+    getOutputTimeDomainData,
+    // VAD control
+    vadMode,
+    setVADMode
+  };
+}
+export {
+  useRealtimeChat
+};
+//# sourceMappingURL=use-realtime-chat.js.map

package/dist/esm/use-realtime-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-realtime-chat.js","sources":["../../src/use-realtime-chat.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react'\nimport { RealtimeClient } from '@tanstack/ai-client'\nimport type {\n  RealtimeMessage,\n  RealtimeMode,\n  RealtimeStatus,\n} from '@tanstack/ai'\nimport type {\n  UseRealtimeChatOptions,\n  UseRealtimeChatReturn,\n} from './realtime-types'\n\n// Empty frequency data for when client is not connected\nconst emptyFrequencyData = new Uint8Array(128)\nconst emptyTimeDomainData = new Uint8Array(128).fill(128)\n\n/**\n * React hook for realtime voice conversations.\n *\n * Provides a simple interface for voice-to-voice AI interactions\n * with support for multiple providers (OpenAI, ElevenLabs, etc.).\n *\n * @param options - Configuration options including adapter and callbacks\n * @returns Hook return value with state and control methods\n *\n * @example\n * ```typescript\n * import { useRealtimeChat } from '@tanstack/ai-react'\n * import { openaiRealtime } from '@tanstack/ai-openai'\n *\n * function VoiceChat() {\n *   const {\n *     status,\n *     mode,\n *     messages,\n *     connect,\n *     disconnect,\n *     inputLevel,\n *     outputLevel,\n *   } = useRealtimeChat({\n *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),\n *     adapter: openaiRealtime(),\n *   })\n *\n *   return (\n *     <div>\n *       <p>Status: {status}</p>\n *       <p>Mode: {mode}</p>\n *       <button onClick={status === 'idle' ? connect : disconnect}>\n *         {status === 'idle' ? 'Start' : 'Stop'}\n *       </button>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useRealtimeChat(\n  options: UseRealtimeChatOptions,\n): UseRealtimeChatReturn {\n  // State\n  const [status, setStatus] = useState<RealtimeStatus>('idle')\n  const [mode, setMode] = useState<RealtimeMode>('idle')\n  const [messages, setMessages] = useState<Array<RealtimeMessage>>([])\n  const [pendingUserTranscript, setPendingUserTranscript] = useState<\n    string | null\n  >(null)\n  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState<\n    string | null\n  >(null)\n  const [error, setError] = useState<Error | null>(null)\n  const [inputLevel, setInputLevel] = useState(0)\n  const [outputLevel, setOutputLevel] = useState(0)\n  const [vadMode, setVADModeState] = useState<'server' | 'semantic' | 'manual'>(\n    options.vadMode ?? 'server',\n  )\n\n  // Refs\n  const clientRef = useRef<RealtimeClient | null>(null)\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const animationFrameRef = useRef<number | null>(null)\n\n  // Create client instance - use ref to ensure we reuse the same instance\n  // This handles React StrictMode double-rendering\n  if (!clientRef.current) {\n    // Each optional source field is spread conditionally because the\n    // `RealtimeClientOptions` target declares strict optionals\n    // (`field?: T`) and `exactOptionalPropertyTypes` rejects passing\n    // `undefined` for absent values.\n    const initial = optionsRef.current\n    clientRef.current = new RealtimeClient({\n      getToken: initial.getToken,\n      adapter: initial.adapter,\n      ...(initial.tools !== undefined && { tools: initial.tools }),\n      ...(initial.instructions !== undefined && {\n        instructions: initial.instructions,\n      }),\n      ...(initial.voice !== undefined && { voice: initial.voice }),\n      ...(initial.autoPlayback !== undefined && {\n        autoPlayback: initial.autoPlayback,\n      }),\n      ...(initial.autoCapture !== undefined && {\n        autoCapture: initial.autoCapture,\n      }),\n      ...(initial.vadMode !== undefined && { vadMode: initial.vadMode }),\n      ...(initial.outputModalities !== undefined && {\n        outputModalities: initial.outputModalities,\n      }),\n      ...(initial.temperature !== undefined && {\n        temperature: initial.temperature,\n      }),\n      ...(initial.maxOutputTokens !== undefined && {\n        maxOutputTokens: initial.maxOutputTokens,\n      }),\n      ...(initial.semanticEagerness !== undefined && {\n        semanticEagerness: initial.semanticEagerness,\n      }),\n      onStatusChange: (newStatus) => {\n        setStatus(newStatus)\n      },\n      onModeChange: (newMode) => {\n        setMode(newMode)\n        optionsRef.current.onModeChange?.(newMode)\n      },\n      onMessage: (message) => {\n        setMessages((prev) => [...prev, message])\n        optionsRef.current.onMessage?.(message)\n      },\n      onError: (err) => {\n        setError(err)\n        optionsRef.current.onError?.(err)\n      },\n      onConnect: () => {\n        setError(null)\n        optionsRef.current.onConnect?.()\n      },\n      onDisconnect: () => {\n        optionsRef.current.onDisconnect?.()\n      },\n      onInterrupted: () => {\n        setPendingAssistantTranscript(null)\n        optionsRef.current.onInterrupted?.()\n      },\n    })\n\n    // Subscribe to state changes for transcripts\n    clientRef.current.onStateChange((state) => {\n      setPendingUserTranscript(state.pendingUserTranscript)\n      setPendingAssistantTranscript(state.pendingAssistantTranscript)\n    })\n  }\n\n  const client = clientRef.current\n\n  // Audio level animation loop\n  useEffect(() => {\n    function updateLevels() {\n      if (clientRef.current?.audio) {\n        setInputLevel(clientRef.current.audio.inputLevel)\n        setOutputLevel(clientRef.current.audio.outputLevel)\n      }\n      animationFrameRef.current = requestAnimationFrame(updateLevels)\n    }\n\n    if (status === 'connected') {\n      updateLevels()\n    }\n\n    return () => {\n      if (animationFrameRef.current) {\n        cancelAnimationFrame(animationFrameRef.current)\n        animationFrameRef.current = null\n      }\n    }\n  }, [status])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      clientRef.current?.destroy()\n    }\n  }, [])\n\n  // Connection methods\n  const connect = useCallback(async () => {\n    setError(null)\n    setMessages([])\n    setPendingUserTranscript(null)\n    setPendingAssistantTranscript(null)\n    await client.connect()\n  }, [client])\n\n  const disconnect = useCallback(async () => {\n    await client.disconnect()\n  }, [client])\n\n  // Voice control methods\n  const startListening = useCallback(() => {\n    client.startListening()\n  }, [client])\n\n  const stopListening = useCallback(() => {\n    client.stopListening()\n  }, [client])\n\n  const interrupt = useCallback(() => {\n    client.interrupt()\n  }, [client])\n\n  // Text input\n  const sendText = useCallback(\n    (text: string) => {\n      client.sendText(text)\n    },\n    [client],\n  )\n\n  // Image input\n  const sendImage = useCallback(\n    (imageData: string, mimeType: string) => {\n      client.sendImage(imageData, mimeType)\n    },\n    [client],\n  )\n\n  // Audio visualization\n  const getInputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getOutputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getInputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  const getOutputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  // VAD mode control\n  const setVADMode = useCallback(\n    (newMode: 'server' | 'semantic' | 'manual') => {\n      setVADModeState(newMode)\n      // TODO: Update session config if connected\n    },\n    [],\n  )\n\n  return {\n    // Connection state\n    status,\n    error,\n    connect,\n    disconnect,\n\n    // Conversation state\n    mode,\n    messages,\n    pendingUserTranscript,\n    pendingAssistantTranscript,\n\n    // Voice control\n    startListening,\n    stopListening,\n    interrupt,\n\n    // Text input\n    sendText,\n\n    // Image input\n    sendImage,\n\n    // Audio visualization\n    inputLevel,\n    outputLevel,\n    getInputFrequencyData,\n    getOutputFrequencyData,\n    getInputTimeDomainData,\n    getOutputTimeDomainData,\n\n    // VAD control\n    vadMode,\n    setVADMode,\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,86 @@
+import { StreamChunk, SummarizationResult } from '@tanstack/ai';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutput, SummarizeGenerateInput } from '@tanstack/ai-client';
+/**
+ * Options for the useSummarize hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
+ */
+export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for summarization */
+    fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when summarization is complete. 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: SummarizationResult) => 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;
+}
+/**
+ * Return type for the useSummarize hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+    /** Trigger summarization */
+    generate: (input: SummarizeGenerateInput) => Promise<void>;
+    /** The summarization result, or null */
+    result: TOutput | null;
+    /** Whether summarization is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current summarization */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * React hook for summarizing text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useSummarize } from '@tanstack/ai-react'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Summarizer() {
+ *   const { generate, result, isLoading } = useSummarize({
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({
+ *         text: 'Long article text...',
+ *         style: 'bullet-points',
+ *         maxLength: 200,
+ *       })}>
+ *         Summarize
+ *       </button>
+ *       {isLoading && <p>Summarizing...</p>}
+ *       {result && <p>{result.summary}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSummarize<TOnResult extends ((result: SummarizationResult) => any) | undefined = undefined>(options: Omit<UseSummarizeOptions, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseSummarizeReturn<InferGenerationOutput<SummarizationResult, TOnResult>>;

package/dist/esm/use-summarize.js

@@ -0,0 +1,26 @@
+import { useGeneration } from "./use-generation.js";
+function useSummarize(options) {
+  const devtools = {
+    ...options.devtools,
+    framework: "react",
+    hookName: "useSummarize",
+    outputKind: "text"
+  };
+  const { generate, result, isLoading, error, status, stop, reset } = useGeneration({
+    ...options,
+    devtools
+  });
+  return {
+    generate,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset
+  };
+}
+export {
+  useSummarize
+};
+//# sourceMappingURL=use-summarize.js.map

package/dist/esm/use-summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-summarize.js","sources":["../../src/use-summarize.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport type { StreamChunk, SummarizationResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutput,\n  SummarizeGenerateInput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useSummarize hook.\n *\n * @template TOutput - The output type after optional transform (defaults to SummarizationResult)\n */\nexport interface UseSummarizeOptions<TOutput = SummarizationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for summarization */\n  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * Callback when summarization is complete. 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: SummarizationResult) => 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\n/**\n * Return type for the useSummarize hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseSummarizeReturn<TOutput = SummarizationResult> {\n  /** Trigger summarization */\n  generate: (input: SummarizeGenerateInput) => Promise<void>\n  /** The summarization result, or null */\n  result: TOutput | null\n  /** Whether summarization 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 summarization */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n}\n\n/**\n * React hook for summarizing text using AI models.\n *\n * @example\n * ```tsx\n * import { useSummarize } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function Summarizer() {\n *   const { generate, result, isLoading } = useSummarize({\n *     connection: fetchServerSentEvents('/api/summarize'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({\n *         text: 'Long article text...',\n *         style: 'bullet-points',\n *         maxLength: 200,\n *       })}>\n *         Summarize\n *       </button>\n *       {isLoading && <p>Summarizing...</p>}\n *       {result && <p>{result.summary}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useSummarize<\n  TOnResult extends ((result: SummarizationResult) => any) | undefined =\n    undefined,\n>(\n  options: Omit<UseSummarizeOptions, 'onResult'> & {\n    onResult?: TOnResult\n  },\n): UseSummarizeReturn<InferGenerationOutput<SummarizationResult, TOnResult>> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useSummarize',\n    outputKind: 'text' as const,\n  }\n  const { generate, result, isLoading, error, status, stop, reset } =\n    useGeneration<SummarizeGenerateInput, SummarizationResult, TOnResult>({\n      ...options,\n      devtools,\n    })\n\n  return {\n    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";AA8FO,SAAS,aAId,SAG2E;AAC3E,QAAM,WAAW;AAAA,IACf,GAAG,QAAQ;AAAA,IACX,WAAW;AAAA,IACX,UAAU;AAAA,IACV,YAAY;AAAA,EAAA;AAEd,QAAM,EAAE,UAAU,QAAQ,WAAW,OAAO,QAAQ,MAAM,MAAA,IACxD,cAAsE;AAAA,IACpE,GAAG;AAAA,IACH;AAAA,EAAA,CACD;AAEH,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

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

@@ -0,0 +1,91 @@
+import { StreamChunk, TranscriptionResult } from '@tanstack/ai';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutput, TranscriptionGenerateInput } from '@tanstack/ai-client';
+/**
+ * Options for the useTranscription hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to TranscriptionResult)
+ */
+export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for transcription */
+    fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when transcription is complete. 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: TranscriptionResult) => 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;
+}
+/**
+ * Return type for the useTranscription hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
+    /** Trigger transcription */
+    generate: (input: TranscriptionGenerateInput) => Promise<void>;
+    /** The transcription result, or null */
+    result: TOutput | null;
+    /** Whether transcription is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current transcription */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * React hook for transcribing audio to text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useTranscription } from '@tanstack/ai-react'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Transcriber() {
+ *   const { generate, result, isLoading } = useTranscription({
+ *     connection: fetchServerSentEvents('/api/transcribe'),
+ *   })
+ *
+ *   const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     const file = e.target.files?.[0]
+ *     if (file) {
+ *       const reader = new FileReader()
+ *       reader.onload = () => {
+ *         generate({ audio: reader.result as string, language: 'en' })
+ *       }
+ *       reader.readAsDataURL(file)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" accept="audio/*" onChange={handleFile} />
+ *       {isLoading && <p>Transcribing...</p>}
+ *       {result && <p>{result.text}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useTranscription<TOnResult extends ((result: TranscriptionResult) => any) | undefined = undefined>(options: Omit<UseTranscriptionOptions, 'onResult'> & {
+    onResult?: TOnResult;
+}): UseTranscriptionReturn<InferGenerationOutput<TranscriptionResult, TOnResult>>;