@octanejs/tanstack-ai 0.0.1

package/src/use-generate-audio.tsrx.d.ts

@@ -0,0 +1,88 @@
+// Declaration companion generated from use-generate-audio.tsrx.
+import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, AudioGenerateInput, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+/**
+ * Options for the useGenerateAudio hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
+ */
+export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for audio generation */
+    fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>;
+    /** 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 audio 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: AudioGenerationResult) => 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 useGenerateAudio hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
+    /** Trigger audio generation */
+    generate: (input: AudioGenerateInput) => Promise<void>;
+    /** The generation result containing audio, 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;
+}
+/**
+ * Octane hook for generating audio (music, sound effects) using AI models.
+ *
+ * Supports two transport modes:
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** — Direct async function call
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateAudio } from '@octanejs/tanstack-ai'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function AudioGenerator() {
+ *   const { generate, result, isLoading, error, reset } = useGenerateAudio({
+ *     connection: fetchServerSentEvents('/api/generate/audio'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ prompt: 'An upbeat electronic track', duration: 10 })}>
+ *         Generate
+ *       </button>
+ *       {isLoading && <p>Generating...</p>}
+ *       {error && <p>Error: {error.message}</p>}
+ *       {result?.audio.url && <audio src={result.audio.url} controls />}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useGenerateAudio<TTransformed = void>(options: Omit<UseGenerateAudioOptions, 'onResult'> & {
+    onResult?: (result: AudioGenerationResult) => TTransformed;
+}): UseGenerateAudioReturn<InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>>;

package/src/use-generate-image.tsrx

@@ -0,0 +1,127 @@
+import { useGeneration } from './use-generation.tsrx'
+import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  ImageGenerateInput,
+  InferGenerationOutputFromReturn,
+} 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> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for image generation */
+  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>
+  /** 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 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 (connect-based adapter 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
+}
+
+/**
+ * Octane hook for generating images using AI models.
+ *
+ * Supports two transport modes:
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** — Direct async function call
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateImage } from '@octanejs/tanstack-ai'
+ * 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 function useGenerateImage<TTransformed = void>(
+  options: Omit<UseGenerateImageOptions, 'onResult'> & {
+    onResult?: (result: ImageGenerationResult) => TTransformed
+  },
+): UseGenerateImageReturn<
+  InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
+> {
+  const devtools = {
+    ...options.devtools,
+    // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+    framework: 'octane',
+    hookName: 'useGenerateImage',
+    outputKind: 'image' as const,
+  }
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
+      ...options,
+      devtools,
+    })
+
+  return {
+    generate: generate as (input: ImageGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-generate-image.tsrx.d.ts

@@ -0,0 +1,90 @@
+// Declaration companion generated from use-generate-image.tsrx.
+import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, ImageGenerateInput, InferGenerationOutputFromReturn } 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> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for image generation */
+    fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>;
+    /** 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 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 (connect-based adapter 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;
+}
+/**
+ * Octane hook for generating images using AI models.
+ *
+ * Supports two transport modes:
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** — Direct async function call
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateImage } from '@octanejs/tanstack-ai'
+ * 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<TTransformed = void>(options: Omit<UseGenerateImageOptions, 'onResult'> & {
+    onResult?: (result: ImageGenerationResult) => TTransformed;
+}): UseGenerateImageReturn<InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>>;

package/src/use-generate-speech.tsrx

@@ -0,0 +1,121 @@
+import { useGeneration } from './use-generation.tsrx'
+import type { StreamChunk, TTSResult } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutputFromReturn,
+  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> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for speech generation */
+  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
+  /** 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 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 (connect-based adapter 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
+}
+
+/**
+ * Octane hook for generating speech (text-to-speech) using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateSpeech } from '@octanejs/tanstack-ai'
+ * 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 function useGenerateSpeech<TTransformed = void>(
+  options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
+    onResult?: (result: TTSResult) => TTransformed
+  },
+): UseGenerateSpeechReturn<
+  InferGenerationOutputFromReturn<TTSResult, TTransformed>
+> {
+  const devtools = {
+    ...options.devtools,
+    // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+    framework: 'octane',
+    hookName: 'useGenerateSpeech',
+    outputKind: 'audio' as const,
+  }
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
+      ...options,
+      devtools,
+    })
+
+  return {
+    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-generate-speech.tsrx.d.ts

@@ -0,0 +1,84 @@
+// Declaration companion generated from use-generate-speech.tsrx.
+import type { StreamChunk, TTSResult } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn, 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> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for speech generation */
+    fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>;
+    /** 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 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 (connect-based adapter 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;
+}
+/**
+ * Octane hook for generating speech (text-to-speech) using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateSpeech } from '@octanejs/tanstack-ai'
+ * 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<TTransformed = void>(options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
+    onResult?: (result: TTSResult) => TTransformed;
+}): UseGenerateSpeechReturn<InferGenerationOutputFromReturn<TTSResult, TTransformed>>;