@octanejs/tanstack-ai 0.0.1

package/src/use-audio-recorder.tsrx

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'octane'
+import { AudioRecorder } from '@tanstack/ai-client'
+import type {
+  AudioRecorderOptions,
+  AudioRecording,
+  InferAudioRecordingOutput,
+} from '@tanstack/ai-client'
+
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+  /**
+   * Optional transform applied to the recording when `stop()` resolves. Its
+   * (awaited) return value becomes `recording` and the resolved value of
+   * `stop()`. Return nothing to keep the raw `AudioRecording`.
+   */
+  onComplete?: TOnComplete
+}
+
+export interface UseAudioRecorderReturn<TOutput> {
+  /** Latest recording (transformed if `onComplete` provided), or null. */
+  recording: TOutput | null
+  /** True while actively capturing audio. */
+  isRecording: boolean
+  /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+  isSupported: boolean
+  /** Acquire the mic and begin recording. */
+  start: () => Promise<void>
+  /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+  stop: () => Promise<TOutput>
+  /** Discard the in-progress recording and release the mic. */
+  cancel: () => void
+}
+
+/**
+ * Octane hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+export function useAudioRecorder<
+  TOnComplete extends (recording: AudioRecording) => unknown,
+>(
+  options: UseAudioRecorderOptions<TOnComplete>,
+): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>
+export function useAudioRecorder(
+  options?: UseAudioRecorderOptions<undefined>,
+): UseAudioRecorderReturn<AudioRecording>
+export function useAudioRecorder(
+  options: UseAudioRecorderOptions<(recording: AudioRecording) => unknown> = {},
+): UseAudioRecorderReturn<unknown> {
+  const [isRecording, setIsRecording] = useState(false)
+  const [recording, setRecording] = useState<unknown>(null)
+  // Read the freshest callbacks at fire time without recreating the recorder.
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const recorder = useMemo(
+    () =>
+      new AudioRecorder({
+        ...(options.audio !== undefined && { audio: options.audio }),
+        ...(options.mimeType !== undefined && { mimeType: options.mimeType }),
+        onError: (err) => optionsRef.current.onError?.(err),
+      }),
+    // Recorder config (audio/mimeType) is captured once at mount, matching the
+    // other hooks' create-once pattern.
+    [],
+  )
+
+  useEffect(() => {
+    const unsubscribe = recorder.subscribe((state) => {
+      setIsRecording(state === 'recording')
+    })
+    return () => {
+      unsubscribe()
+      recorder.cancel()
+    }
+  }, [recorder])
+
+  const start = useCallback(() => recorder.start(), [recorder])
+  const stop = useCallback(async () => {
+    const recording = await recorder.stop()
+    const transformed = await optionsRef.current.onComplete?.(recording)
+    // Only `undefined` (returning nothing) falls back to the raw recording, so
+    // a transform that returns null is preserved — matching the inferred type,
+    // which excludes only undefined/void/null from the transform's return.
+    const output = transformed === undefined ? recording : transformed
+    setRecording(() => output)
+    return output
+  }, [recorder])
+  const cancel = useCallback(() => recorder.cancel(), [recorder])
+
+  return {
+    recording,
+    isRecording,
+    // recording is client-only; if SSR'd, gate UI on a mounted flag.
+    isSupported: AudioRecorder.isSupported(),
+    start,
+    stop,
+    cancel,
+  }
+}

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

@@ -0,0 +1,44 @@
+// Declaration companion generated from use-audio-recorder.tsrx.
+import type { AudioRecorderOptions, AudioRecording, InferAudioRecordingOutput } from '@tanstack/ai-client';
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+    /**
+     * Optional transform applied to the recording when `stop()` resolves. Its
+     * (awaited) return value becomes `recording` and the resolved value of
+     * `stop()`. Return nothing to keep the raw `AudioRecording`.
+     */
+    onComplete?: TOnComplete;
+};
+export interface UseAudioRecorderReturn<TOutput> {
+    /** Latest recording (transformed if `onComplete` provided), or null. */
+    recording: TOutput | null;
+    /** True while actively capturing audio. */
+    isRecording: boolean;
+    /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+    isSupported: boolean;
+    /** Acquire the mic and begin recording. */
+    start: () => Promise<void>;
+    /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+    stop: () => Promise<TOutput>;
+    /** Discard the in-progress recording and release the mic. */
+    cancel: () => void;
+}
+/**
+ * Octane hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+export declare function useAudioRecorder<TOnComplete extends (recording: AudioRecording) => unknown>(options: UseAudioRecorderOptions<TOnComplete>): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>;
+export declare function useAudioRecorder(options?: UseAudioRecorderOptions<undefined>): UseAudioRecorderReturn<AudioRecording>;

package/src/use-chat.tsrx

@@ -0,0 +1,363 @@
+import { ChatClient } from '@tanstack/ai-client'
+import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'octane'
+import type {
+  AnyClientTool,
+  InferSchemaType,
+  ModelMessage,
+  SchemaInput,
+  StreamChunk,
+} from '@tanstack/ai/client'
+import type {
+  ChatClientState,
+  ConnectionStatus,
+  InferredClientContext,
+  StructuredOutputPart,
+} from '@tanstack/ai-client'
+
+import type {
+  DeepPartial,
+  MultimodalContent,
+  UIMessage,
+  UseChatOptions,
+  UseChatReturn,
+} from './types'
+
+export function useChat<
+  const TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+  TContext = InferredClientContext<TTools>,
+>(
+  options: UseChatOptions<TTools, TSchema, TContext>,
+): UseChatReturn<TTools, TSchema> {
+  const hookId = useId()
+  const clientId = options.id || hookId
+
+  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(
+    options.initialMessages || [],
+  )
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | undefined>(undefined)
+  const [status, setStatus] = useState<ChatClientState>('ready')
+  const [isSubscribed, setIsSubscribed] = useState(false)
+  const [connectionStatus, setConnectionStatus] =
+    useState<ConnectionStatus>('disconnected')
+  const [sessionGenerating, setSessionGenerating] = useState(false)
+
+  type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
+  type Final = InferSchemaType<NonNullable<TSchema>>
+
+  // Track the rendered snapshot so a replacement client only synchronizes
+  // state when its messages actually differ.
+  const messagesRef = useRef<Array<UIMessage<TTools>>>(
+    options.initialMessages || [],
+  )
+  const activeClientRef = useRef<ChatClient | null>(null)
+  const cleanupInvalidationRef = useRef<ReturnType<typeof setTimeout> | null>(
+    null,
+  )
+
+  // Update ref synchronously during render so it's always current when useMemo runs.
+  messagesRef.current = messages
+
+  // Track current options in a ref to avoid recreating client when options change
+  const optionsRef = useRef<UseChatOptions<TTools, TSchema, TContext>>(options)
+  optionsRef.current = options
+
+  // Create ChatClient instance with callbacks to sync state
+  const client = useMemo(() => {
+    const messagesToUse = options.initialMessages || []
+
+    // Build options with conditional spreads for fields whose source
+    // type is `T | undefined` but the ChatClient target uses a strict
+    // optional (`field?: T`) — `exactOptionalPropertyTypes` rejects
+    // assigning `undefined` to those, so we omit the key when absent.
+    const initialOptions = optionsRef.current
+    const transport = initialOptions.connection
+      ? { connection: initialOptions.connection }
+      : { fetcher: initialOptions.fetcher }
+
+    const instance = new ChatClient<TTools, TContext>({
+      devtoolsBridgeFactory: createChatDevtoolsBridge,
+      ...transport,
+      id: clientId,
+      initialMessages: messagesToUse,
+      ...(initialOptions.body !== undefined && { body: initialOptions.body }),
+      ...(initialOptions.threadId !== undefined && {
+        threadId: initialOptions.threadId,
+      }),
+      ...(initialOptions.forwardedProps !== undefined && {
+        forwardedProps: initialOptions.forwardedProps,
+      }),
+      ...(initialOptions.persistence !== undefined && {
+        persistence: initialOptions.persistence,
+      }),
+      ...(initialOptions.context !== undefined && {
+        context: initialOptions.context,
+      }),
+      devtools: {
+        ...initialOptions.devtools,
+        // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+        framework: 'octane',
+        hookName: 'useChat',
+        outputKind: initialOptions.outputSchema ? 'structured' : 'chat',
+      },
+      onResponse: (response) => {
+        if (activeClientRef.current !== instance) return
+        void optionsRef.current.onResponse?.(response)
+      },
+      onChunk: (chunk: StreamChunk) => {
+        if (activeClientRef.current !== instance) return
+        optionsRef.current.onChunk?.(chunk)
+      },
+      onFinish: (message: UIMessage<TTools>) => {
+        if (activeClientRef.current !== instance) return
+        optionsRef.current.onFinish?.(message)
+      },
+      onError: (error: Error) => {
+        if (activeClientRef.current !== instance) return
+        optionsRef.current.onError?.(error)
+      },
+      ...(initialOptions.tools !== undefined && {
+        tools: initialOptions.tools,
+      }),
+      onCustomEvent: (eventType, data, context) => {
+        if (activeClientRef.current !== instance) return
+        optionsRef.current.onCustomEvent?.(eventType, data, context)
+      },
+      ...(options.streamProcessor !== undefined && {
+        streamProcessor: options.streamProcessor,
+      }),
+      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
+        if (activeClientRef.current !== instance) return
+        setMessages(newMessages)
+      },
+      onLoadingChange: (newIsLoading: boolean) => {
+        if (activeClientRef.current !== instance) return
+        setIsLoading(newIsLoading)
+      },
+      onErrorChange: (newError: Error | undefined) => {
+        if (activeClientRef.current !== instance) return
+        setError(newError)
+      },
+      onStatusChange: (status: ChatClientState) => {
+        if (activeClientRef.current !== instance) return
+        setStatus(status)
+      },
+      onSubscriptionChange: (nextIsSubscribed: boolean) => {
+        if (activeClientRef.current !== instance) return
+        setIsSubscribed(nextIsSubscribed)
+      },
+      onConnectionStatusChange: (nextStatus: ConnectionStatus) => {
+        if (activeClientRef.current !== instance) return
+        setConnectionStatus(nextStatus)
+      },
+      onSessionGeneratingChange: (isGenerating: boolean) => {
+        if (activeClientRef.current !== instance) return
+        setSessionGenerating(isGenerating)
+      },
+    })
+    activeClientRef.current = instance
+    return instance
+  }, [clientId])
+
+  useEffect(() => {
+    const clientMessages = client.getMessages()
+    if (clientMessages !== messagesRef.current) {
+      setMessages(clientMessages)
+    }
+  }, [client])
+
+  // OCTANE DIVERGENCE: upstream captures the initial transport. ChatClient
+  // owns transport swaps, including aborting an active request and
+  // resubscribing when needed, so keep its conversation state stable while
+  // applying the latest transport.
+  useEffect(() => {
+    const transport = options.connection
+      ? { connection: options.connection }
+      : { fetcher: options.fetcher }
+    client.updateOptions(transport)
+  }, [client, options.connection, options.fetcher])
+
+  // Sync each wire-payload slot in its own effect so an unrelated option
+  // changing doesn't re-run the others. `updateOptions` declares strict-optional
+  // fields and rejects explicit `undefined` under EOPT, so guard the optional
+  // slots before passing them.
+  useEffect(() => {
+    client.updateOptions({ body: options.body })
+  }, [client, options.body])
+
+  useEffect(() => {
+    if (options.forwardedProps !== undefined) {
+      client.updateOptions({ forwardedProps: options.forwardedProps })
+    }
+  }, [client, options.forwardedProps])
+
+  useEffect(() => {
+    if (options.tools !== undefined) {
+      client.updateOptions({ tools: options.tools })
+    }
+  }, [client, options.tools])
+
+  useEffect(() => {
+    client.updateOptions({ context: options.context })
+  }, [client, options.context])
+
+  useEffect(() => {
+    if (options.live) {
+      client.subscribe()
+    } else {
+      client.unsubscribe()
+    }
+  }, [client, options.live])
+
+  useEffect(() => {
+    if (cleanupInvalidationRef.current) {
+      clearTimeout(cleanupInvalidationRef.current)
+      cleanupInvalidationRef.current = null
+    }
+    activeClientRef.current = client
+    client.mountDevtools()
+
+    return () => {
+      cleanupInvalidationRef.current = setTimeout(() => {
+        if (activeClientRef.current === client) {
+          activeClientRef.current = null
+        }
+        cleanupInvalidationRef.current = null
+      }, 0)
+      // Subscribe/unsubscribe on `options.live` is owned by the dedicated
+      // effect above. This cleanup only fires on unmount or client swap,
+      // so read `live` through the ref to avoid disposing the client every
+      // time `live` toggles.
+      if (optionsRef.current.live) {
+        client.unsubscribe()
+      } else {
+        client.stop()
+      }
+      client.dispose()
+    }
+  }, [client])
+
+  const sendMessage = useCallback(
+    async (content: string | MultimodalContent) => {
+      await client.sendMessage(content)
+    },
+    [client],
+  )
+
+  const append = useCallback(
+    async (message: ModelMessage | UIMessage) => {
+      await client.append(message)
+    },
+    [client],
+  )
+
+  const reload = useCallback(async () => {
+    await client.reload()
+  }, [client])
+
+  const stop = useCallback(() => {
+    client.stop()
+  }, [client])
+
+  const clear = useCallback(() => {
+    client.clear()
+  }, [client])
+
+  const setMessagesManually = useCallback(
+    (newMessages: Array<UIMessage<TTools>>) => {
+      client.setMessagesManually(newMessages)
+    },
+    [client],
+  )
+
+  const addToolResult = useCallback(
+    async (result: {
+      toolCallId: string
+      tool: string
+      output: any
+      state?: 'output-available' | 'output-error'
+      errorText?: string
+    }) => {
+      await client.addToolResult(result)
+    },
+    [client],
+  )
+
+  const addToolApprovalResponse = useCallback(
+    async (response: { id: string; approved: boolean }) => {
+      await client.addToolApprovalResponse(response)
+    },
+    [client],
+  )
+
+  // The "active" structured-output part is the one on the assistant message
+  // that follows the latest user message. No such message exists between
+  // sendMessage() and the first chunk, so partial/final naturally read as
+  // cleared. Historical parts on earlier assistant messages remain available
+  // via `messages` directly.
+  //
+  // When there is NO user message yet (e.g. `initialMessages` contains only
+  // a stale assistant turn or a system prompt) we deliberately return null
+  // rather than scanning historical assistants — otherwise a `final` from a
+  // previous session would leak into the hook value on first render.
+  const renderedMessages = client.getMessages()
+
+  const activeStructuredPart = useMemo<StructuredOutputPart | null>(() => {
+    let lastUserIndex = -1
+    for (let i = renderedMessages.length - 1; i >= 0; i--) {
+      if (renderedMessages[i]?.role === 'user') {
+        lastUserIndex = i
+        break
+      }
+    }
+    if (lastUserIndex === -1) return null
+    for (let i = renderedMessages.length - 1; i > lastUserIndex; i--) {
+      const m = renderedMessages[i]
+      if (m?.role !== 'assistant') continue
+      const part = m.parts.find(
+        (p): p is StructuredOutputPart => p.type === 'structured-output',
+      )
+      if (part) return part
+    }
+    return null
+  }, [renderedMessages])
+
+  const partial = useMemo<Partial>(() => {
+    if (!activeStructuredPart) return {} as Partial
+    const v = activeStructuredPart.partial ?? activeStructuredPart.data
+    return (v ?? {}) as Partial
+  }, [activeStructuredPart])
+
+  const final = useMemo<Final | null>(() => {
+    if (!activeStructuredPart || activeStructuredPart.status !== 'complete') {
+      return null
+    }
+    return activeStructuredPart.data as Final
+  }, [activeStructuredPart])
+
+  // The runtime shape unconditionally exposes partial/final; the public
+  // return type hides them when no outputSchema was supplied. TS can't
+  // structurally narrow across that conditional, so the `as` is the seam.
+  // eslint-disable-next-line no-restricted-syntax -- hook return shape diverges from generic UseChatReturn<TTools, TSchema> due to conditional type on TSchema; TS can't structurally narrow
+  return {
+    messages: renderedMessages,
+    sendMessage,
+    append,
+    reload,
+    stop,
+    isLoading,
+    error,
+    status,
+    isSubscribed,
+    connectionStatus,
+    sessionGenerating,
+    setMessages: setMessagesManually,
+    clear,
+    addToolResult,
+    addToolApprovalResponse,
+    partial,
+    final,
+  } as unknown as UseChatReturn<TTools, TSchema>
+}

package/src/use-chat.tsrx.d.ts

@@ -0,0 +1,5 @@
+// Declaration companion generated from use-chat.tsrx.
+import type { AnyClientTool, SchemaInput } from '@tanstack/ai/client';
+import type { InferredClientContext } from '@tanstack/ai-client';
+import type { UseChatOptions, UseChatReturn } from './types';
+export declare function useChat<const TTools extends ReadonlyArray<AnyClientTool> = any, TSchema extends SchemaInput | undefined = undefined, TContext = InferredClientContext<TTools>>(options: UseChatOptions<TTools, TSchema, TContext>): UseChatReturn<TTools, TSchema>;

package/src/use-generate-audio.tsrx

@@ -0,0 +1,125 @@
+import { useGeneration } from './use-generation.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 function useGenerateAudio<TTransformed = void>(
+  options: Omit<UseGenerateAudioOptions, 'onResult'> & {
+    onResult?: (result: AudioGenerationResult) => TTransformed
+  },
+): UseGenerateAudioReturn<
+  InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
+> {
+  const devtools = {
+    ...options.devtools,
+    // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+    framework: 'octane',
+    hookName: 'useGenerateAudio',
+    outputKind: 'audio' as const,
+  }
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
+      ...options,
+      devtools,
+    })
+
+  return {
+    generate: generate as (input: AudioGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}