@tanstack/ai-client 0.5.3 → 0.7.1

package/src/generation-client.ts

@@ -0,0 +1,302 @@
+import { GENERATION_EVENTS } from './generation-types'
+import { parseSSEResponse } from './sse-parser'
+import type { StreamChunk } from '@tanstack/ai'
+import type { ConnectionAdapter } from './connection-adapters'
+import type {
+  GenerationClientOptions,
+  GenerationClientState,
+  GenerationFetcher,
+} from './generation-types'
+
+/**
+ * Callbacks stored in a ref so hooks can update them without recreating the client.
+ */
+interface GenerationCallbacks<TResult, TOutput> {
+  onResult?: (result: TResult) => TOutput | null | void
+  onError?: (error: Error) => void
+  onProgress?: (progress: number, message?: string) => void
+  onChunk?: (chunk: StreamChunk) => void
+  onResultChange?: (result: TOutput | null) => void
+  onLoadingChange?: (isLoading: boolean) => void
+  onErrorChange?: (error: Error | undefined) => void
+  onStatusChange?: (status: GenerationClientState) => void
+}
+
+/**
+ * A lightweight, generic client for one-shot generation tasks
+ * (image, speech, transcription, summarize).
+ *
+ * Supports two transport modes:
+ * - **ConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom).
+ *   Server wraps results in StreamChunk events with CUSTOM event names.
+ * - **Fetcher** — Direct async function call. No streaming protocol needed.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ *
+ * @example
+ * ```typescript
+ * // With ConnectionAdapter (streaming)
+ * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({
+ *   connection: fetchServerSentEvents('/api/generate/image'),
+ *   onResultChange: setResult,
+ *   onLoadingChange: setIsLoading,
+ * })
+ *
+ * // With fetcher (direct)
+ * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({
+ *   fetcher: async (input) => {
+ *     const res = await fetch('/api/generate/image', {
+ *       method: 'POST',
+ *       body: JSON.stringify(input),
+ *     })
+ *     return res.json()
+ *   },
+ * })
+ *
+ * await client.generate({ prompt: 'A sunset over mountains' })
+ * ```
+ */
+export class GenerationClient<
+  TInput extends Record<string, any>,
+  TResult,
+  TOutput = TResult,
+> {
+  private connection: ConnectionAdapter | undefined
+  private fetcher: GenerationFetcher<TInput, TResult> | undefined
+  private body: Record<string, any>
+  private result: TOutput | null = null
+  private isLoading = false
+  private error: Error | undefined = undefined
+  private status: GenerationClientState = 'idle'
+  private abortController: AbortController | null = null
+  private callbacksRef: GenerationCallbacks<TResult, TOutput>
+
+  constructor(
+    options: GenerationClientOptions<TInput, TResult, TOutput> &
+      (
+        | { connection: ConnectionAdapter; fetcher?: never }
+        | {
+            fetcher: GenerationFetcher<TInput, TResult>
+            connection?: never
+          }
+      ),
+  ) {
+    this.connection = options.connection
+    this.fetcher = options.fetcher
+    this.body = options.body ?? {}
+
+    this.callbacksRef = {
+      onResult: options.onResult,
+      onError: options.onError,
+      onProgress: options.onProgress,
+      onChunk: options.onChunk,
+      onResultChange: options.onResultChange,
+      onLoadingChange: options.onLoadingChange,
+      onErrorChange: options.onErrorChange,
+      onStatusChange: options.onStatusChange,
+    }
+  }
+
+  /**
+   * Trigger a generation request.
+   * Only one generation can be in-flight at a time; calling generate()
+   * while already generating will be a no-op.
+   */
+  async generate(input: TInput): Promise<void> {
+    if (this.isLoading) return
+
+    this.setIsLoading(true)
+    this.setStatus('generating')
+    this.setError(undefined)
+
+    const abortController = new AbortController()
+    this.abortController = abortController
+    const { signal } = abortController
+
+    try {
+      if (this.fetcher) {
+        // Direct fetch path
+        const result = await this.fetcher(input, { signal })
+        if (signal.aborted) return
+        if (result instanceof Response) {
+          // Server function returned SSE Response — parse stream
+          await this.processStream(parseSSEResponse(result, signal))
+        } else {
+          this.setResult(result)
+          this.setStatus('success')
+        }
+      } else if (this.connection) {
+        // ConnectionAdapter streaming path
+        const mergedData = { ...this.body, ...input }
+        const stream = this.connection.connect([], mergedData, signal)
+        await this.processStream(stream)
+      } else {
+        throw new Error(
+          'GenerationClient requires either a connection or fetcher option',
+        )
+      }
+    } catch (err: any) {
+      if (signal.aborted) return
+      const error = err instanceof Error ? err : new Error(String(err))
+      this.setError(error)
+      this.setStatus('error')
+      this.callbacksRef.onError?.(error)
+    } finally {
+      this.abortController = null
+      this.setIsLoading(false)
+    }
+  }
+
+  /**
+   * Process a stream of AG-UI events from the ConnectionAdapter.
+   */
+  private async processStream(
+    source: AsyncIterable<StreamChunk>,
+  ): Promise<void> {
+    for await (const chunk of source) {
+      if (this.abortController?.signal.aborted) break
+
+      this.callbacksRef.onChunk?.(chunk)
+
+      switch (chunk.type) {
+        case 'CUSTOM': {
+          if (chunk.name === GENERATION_EVENTS.RESULT) {
+            this.setResult(chunk.value as TResult)
+          } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {
+            const { progress, message } = chunk.value as {
+              progress: number
+              message?: string
+            }
+            this.callbacksRef.onProgress?.(progress, message)
+          }
+          break
+        }
+        case 'RUN_FINISHED': {
+          this.setStatus('success')
+          break
+        }
+        case 'RUN_ERROR': {
+          throw new Error(chunk.error.message)
+        }
+      }
+    }
+  }
+
+  /**
+   * Abort any in-flight generation request.
+   */
+  stop(): void {
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+    this.setIsLoading(false)
+    if (this.status === 'generating') {
+      this.setStatus('idle')
+    }
+  }
+
+  /**
+   * Clear the result, error, and return to idle state.
+   */
+  reset(): void {
+    this.stop()
+    this.setResult(null)
+    this.setError(undefined)
+    this.setStatus('idle')
+  }
+
+  /**
+   * Update options without recreating the client.
+   */
+  updateOptions(
+    options: Partial<
+      Pick<
+        GenerationClientOptions<TInput, TResult, TOutput>,
+        'body' | 'onResult' | 'onError' | 'onProgress' | 'onChunk'
+      >
+    >,
+  ): void {
+    if (options.body !== undefined) {
+      this.body = options.body ?? {}
+    }
+    if (options.onResult !== undefined) {
+      this.callbacksRef.onResult = options.onResult
+    }
+    if (options.onError !== undefined) {
+      this.callbacksRef.onError = options.onError
+    }
+    if (options.onProgress !== undefined) {
+      this.callbacksRef.onProgress = options.onProgress
+    }
+    if (options.onChunk !== undefined) {
+      this.callbacksRef.onChunk = options.onChunk
+    }
+  }
+
+  // ===========================
+  // Getters
+  // ===========================
+
+  getResult(): TOutput | null {
+    return this.result
+  }
+
+  getIsLoading(): boolean {
+    return this.isLoading
+  }
+
+  getError(): Error | undefined {
+    return this.error
+  }
+
+  getStatus(): GenerationClientState {
+    return this.status
+  }
+
+  // ===========================
+  // Private state setters
+  // ===========================
+
+  private setResult(rawResult: TResult | null): void {
+    if (rawResult === null) {
+      this.result = null
+      this.callbacksRef.onResultChange?.(null)
+      return
+    }
+
+    if (this.callbacksRef.onResult) {
+      const transformed = this.callbacksRef.onResult(rawResult)
+      if (transformed === null) {
+        // null return → keep previous result unchanged
+        return
+      }
+      if (transformed !== undefined) {
+        // Non-null, non-undefined → use transformed value
+        this.result = transformed
+        this.callbacksRef.onResultChange?.(this.result)
+        return
+      }
+    }
+
+    // No onResult callback, or callback returned void → use raw value
+    this.result = rawResult as unknown as TOutput
+    this.callbacksRef.onResultChange?.(this.result)
+  }
+
+  private setIsLoading(isLoading: boolean): void {
+    this.isLoading = isLoading
+    this.callbacksRef.onLoadingChange?.(isLoading)
+  }
+
+  private setError(error: Error | undefined): void {
+    this.error = error
+    this.callbacksRef.onErrorChange?.(error)
+  }
+
+  private setStatus(status: GenerationClientState): void {
+    this.status = status
+    this.callbacksRef.onStatusChange?.(status)
+  }
+}

package/src/generation-types.ts

@@ -0,0 +1,270 @@
+import type { StreamChunk } from '@tanstack/ai'
+import type { ConnectionAdapter } from './connection-adapters'
+
+// ===========================
+// Inference Utilities
+// ===========================
+
+/**
+ * Infers the output type from an `onResult` callback's return type.
+ *
+ * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.
+ * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.
+ *
+ * @template TResult - The raw result type from the generation
+ * @template TFn - The onResult callback type (or undefined if not provided)
+ */
+export type InferGenerationOutput<TResult, TFn> = TFn extends (
+  result: any,
+) => infer R
+  ? [Exclude<R, null | void | undefined>] extends [never]
+    ? TResult
+    : Exclude<R, null | void | undefined>
+  : TResult
+
+// ===========================
+// State
+// ===========================
+
+/**
+ * State machine for generation clients.
+ * Simpler than ChatClientState since generation is a single request/response cycle.
+ */
+export type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'
+
+// ===========================
+// Event Constants
+// ===========================
+
+/**
+ * Well-known CUSTOM event names used by generation clients.
+ * These events are emitted by the server-side streaming helpers
+ * and consumed by the client-side GenerationClient.
+ */
+export const GENERATION_EVENTS = {
+  /** The generation result payload */
+  RESULT: 'generation:result',
+  /** Progress update (0-100) with optional message */
+  PROGRESS: 'generation:progress',
+  /** Video job created with jobId */
+  VIDEO_JOB_CREATED: 'video:job:created',
+  /** Video job status update */
+  VIDEO_STATUS: 'video:status',
+} as const
+
+// ===========================
+// Transport Types
+// ===========================
+
+/**
+ * Options passed to a fetcher function by the generation client.
+ */
+export interface GenerationFetcherOptions {
+  /** AbortSignal that is triggered when the user calls `stop()` */
+  signal: AbortSignal
+}
+
+/**
+ * A direct async function that performs a generation request.
+ *
+ * Can return the result directly, or return a `Response` with an SSE body
+ * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).
+ * When a `Response` is returned, the client will parse it as an SSE stream.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ */
+export type GenerationFetcher<TInput, TResult> = (
+  input: TInput,
+  options?: GenerationFetcherOptions,
+) => Promise<TResult | Response>
+
+/**
+ * Transport configuration for generation clients.
+ * Supports either a ConnectionAdapter (streaming) or a direct fetcher function.
+ */
+export type GenerationTransport<TInput, TResult> =
+  | { connection: ConnectionAdapter; fetcher?: never }
+  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }
+
+// ===========================
+// Client Options
+// ===========================
+
+/**
+ * Options for the GenerationClient.
+ *
+ * @template TInput - The input type for the generation request (used by consuming code)
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
+  /** Unique identifier for this generation client 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
+   * that replaces the stored result.
+   *
+   * - 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
+
+  // Framework state callbacks (set by hooks, not users)
+  /** @internal Called when result changes */
+  onResultChange?: (result: TOutput | null) => void
+  /** @internal Called when loading state changes */
+  onLoadingChange?: (isLoading: boolean) => void
+  /** @internal Called when error state changes */
+  onErrorChange?: (error: Error | undefined) => void
+  /** @internal Called when generation status changes */
+  onStatusChange?: (status: GenerationClientState) => void
+}
+
+// ===========================
+// Video-Specific Options
+// ===========================
+
+/**
+ * Video status information returned during job polling.
+ */
+export interface VideoStatusInfo {
+  /** Job identifier */
+  jobId: string
+  /** Current status of the video generation job */
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+  /** Progress percentage (0-100), if available */
+  progress?: number
+  /** URL to the generated video (when completed) */
+  url?: string
+  /** Error message if status is 'failed' */
+  error?: string
+}
+
+/**
+ * Composite result for video generation (job completion).
+ */
+export interface VideoGenerateResult {
+  /** Job identifier */
+  jobId: string
+  /** Final status */
+  status: 'completed'
+  /** URL to the generated video */
+  url: string
+  /** When the URL expires, if applicable */
+  expiresAt?: Date
+}
+
+/**
+ * Options for the VideoGenerationClient.
+ */
+export interface VideoGenerationClientOptions<
+  TOutput = VideoGenerateResult,
+> extends GenerationClientOptions<
+  VideoGenerateInput,
+  VideoGenerateResult,
+  TOutput
+> {
+  /** Callback when a video job is created */
+  onJobCreated?: (jobId: string) => void
+  /** Callback on each status update */
+  onStatusUpdate?: (status: VideoStatusInfo) => void
+
+  // Framework state callbacks
+  /** @internal Called when jobId changes */
+  onJobIdChange?: (jobId: string | null) => void
+  /** @internal Called when video status changes */
+  onVideoStatusChange?: (status: VideoStatusInfo | null) => void
+}
+
+// ===========================
+// Input Types
+// ===========================
+
+/**
+ * Input for image generation.
+ */
+export interface ImageGenerateInput {
+  /** Text description of the desired image(s) */
+  prompt: string
+  /** Number of images to generate (default: 1) */
+  numberOfImages?: number
+  /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
+  size?: string
+  /** Model-specific options */
+  modelOptions?: Record<string, any>
+}
+
+/**
+ * Input for text-to-speech generation.
+ */
+export interface SpeechGenerateInput {
+  /** The text to convert to speech */
+  text: string
+  /** The voice to use for generation */
+  voice?: string
+  /** The output audio format */
+  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'
+  /** The speed of the generated audio (0.25 to 4.0) */
+  speed?: number
+  /** Model-specific options */
+  modelOptions?: Record<string, any>
+}
+
+/**
+ * Input for audio transcription.
+ */
+export interface TranscriptionGenerateInput {
+  /** The audio data to transcribe - can be base64 string, File, or Blob */
+  audio: string | File | Blob
+  /** The language of the audio in ISO-639-1 format (e.g., 'en') */
+  language?: string
+  /** An optional prompt to guide the transcription */
+  prompt?: string
+  /** The format of the transcription output */
+  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  /** Model-specific options */
+  modelOptions?: Record<string, any>
+}
+
+/**
+ * Input for text summarization.
+ */
+export interface SummarizeGenerateInput {
+  /** The text to summarize */
+  text: string
+  /** Maximum length of the summary */
+  maxLength?: number
+  /** Style of the summary */
+  style?: 'bullet-points' | 'paragraph' | 'concise'
+  /** Topics to focus on */
+  focus?: Array<string>
+  /** Model-specific options */
+  modelOptions?: Record<string, any>
+}
+
+/**
+ * Input for video generation.
+ */
+export interface VideoGenerateInput {
+  /** Text description of the desired video */
+  prompt: string
+  /** Video size — format depends on provider (e.g., "16:9", "1280x720") */
+  size?: string
+  /** Video duration in seconds */
+  duration?: number
+  /** Model-specific options */
+  modelOptions?: Record<string, any>
+}

package/src/index.ts

@@ -1,4 +1,7 @@
 export { ChatClient } from './chat-client'
+export { RealtimeClient } from './realtime-client'
+export { GenerationClient } from './generation-client'
+export { VideoGenerationClient } from './video-generation-client'
 export type {
   // Core message types (re-exported from @tanstack/ai via types.ts)
   UIMessage,
@@ -15,6 +18,24 @@ export type {
   // Multimodal content input type
   MultimodalContent,
 } from './types'
+// Generation client types
+export type {
+  InferGenerationOutput,
+  GenerationClientState,
+  GenerationClientOptions,
+  GenerationFetcher,
+  GenerationFetcherOptions,
+  GenerationTransport,
+  VideoGenerationClientOptions,
+  VideoStatusInfo,
+  VideoGenerateResult,
+  ImageGenerateInput,
+  SpeechGenerateInput,
+  TranscriptionGenerateInput,
+  SummarizeGenerateInput,
+  VideoGenerateInput,
+} from './generation-types'
+export { GENERATION_EVENTS } from './generation-types'
 export { clientTools, createChatClientOptions } from './types'
 export type {
   ExtractToolNames,
@@ -22,6 +43,13 @@ export type {
   ExtractToolOutput,
 } from './tool-types'
 export type { AnyClientTool } from '@tanstack/ai'
+export type {
+  RealtimeAdapter,
+  RealtimeConnection,
+  RealtimeClientOptions,
+  RealtimeClientState,
+  RealtimeStateChangeCallback,
+} from './realtime-types'
 export {
   fetchServerSentEvents,
   fetchHttpStream,