@tanstack/ai-client 0.5.3 → 0.6.0

package/dist/esm/video-generation-client.d.ts

@@ -0,0 +1,95 @@
+import { ConnectionAdapter } from './connection-adapters.js';
+import { GenerationClientState, GenerationFetcher, VideoGenerateInput, VideoGenerateResult, VideoGenerationClientOptions, VideoStatusInfo } from './generation-types.js';
+/**
+ * A specialized client for job-based video generation.
+ *
+ * Video generation is asynchronous: a job is created, then polled for status
+ * until completion. This client handles the full lifecycle.
+ *
+ * Supports two transport modes:
+ * - **ConnectionAdapter** — Server handles the polling loop internally and
+ *   streams status updates via CUSTOM events.
+ * - **Fetcher** — Direct async function that returns a completed
+ *   `VideoGenerateResult`.
+ *
+ * @example
+ * ```typescript
+ * // With ConnectionAdapter (server-driven polling)
+ * const client = new VideoGenerationClient({
+ *   connection: fetchServerSentEvents('/api/generate/video'),
+ *   onResultChange: setResult,
+ *   onVideoStatusChange: setVideoStatus,
+ * })
+ *
+ * // With fetcher (direct result)
+ * const client = new VideoGenerationClient({
+ *   fetcher: async (input) => {
+ *     const res = await fetch('/api/video/generate', {
+ *       method: 'POST',
+ *       body: JSON.stringify(input),
+ *     })
+ *     return res.json() // { jobId, status: 'completed', url, expiresAt }
+ *   },
+ * })
+ *
+ * await client.generate({ prompt: 'A flying car over a city' })
+ * ```
+ */
+export declare class VideoGenerationClient<TOutput = VideoGenerateResult> {
+    private connection;
+    private fetcher;
+    private body;
+    private result;
+    private jobId;
+    private videoStatus;
+    private isLoading;
+    private error;
+    private status;
+    private abortController;
+    private callbacksRef;
+    constructor(options: VideoGenerationClientOptions<TOutput> & ({
+        connection: ConnectionAdapter;
+        fetcher?: never;
+    } | {
+        fetcher: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>;
+        connection?: never;
+    }));
+    /**
+     * Trigger video generation.
+     * Only one generation can be in-flight at a time.
+     */
+    generate(input: VideoGenerateInput): Promise<void>;
+    /**
+     * Direct fetcher mode: call fetcher and set result.
+     */
+    private generateWithFetcher;
+    /**
+     * Process a stream of AG-UI events from the ConnectionAdapter.
+     * The server handles the polling loop and streams status updates.
+     */
+    private processStream;
+    /**
+     * Abort any in-flight generation or polling.
+     */
+    stop(): void;
+    /**
+     * Clear all state and return to idle.
+     */
+    reset(): void;
+    /**
+     * Update options without recreating the client.
+     */
+    updateOptions(options: Partial<Pick<VideoGenerationClientOptions<TOutput>, 'body' | 'onResult' | 'onError' | 'onProgress' | 'onChunk' | 'onJobCreated' | 'onStatusUpdate'>>): void;
+    getResult(): TOutput | null;
+    getJobId(): string | null;
+    getVideoStatus(): VideoStatusInfo | null;
+    getIsLoading(): boolean;
+    getError(): Error | undefined;
+    getStatus(): GenerationClientState;
+    private setResult;
+    private setJobId;
+    private setVideoStatus;
+    private setIsLoading;
+    private setError;
+    private setStatus;
+}

package/dist/esm/video-generation-client.js

@@ -0,0 +1,238 @@
+import { GENERATION_EVENTS } from "./generation-types.js";
+import { parseSSEResponse } from "./sse-parser.js";
+class VideoGenerationClient {
+  constructor(options) {
+    this.result = null;
+    this.jobId = null;
+    this.videoStatus = null;
+    this.isLoading = false;
+    this.error = void 0;
+    this.status = "idle";
+    this.abortController = null;
+    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,
+      onJobCreated: options.onJobCreated,
+      onStatusUpdate: options.onStatusUpdate,
+      onResultChange: options.onResultChange,
+      onLoadingChange: options.onLoadingChange,
+      onErrorChange: options.onErrorChange,
+      onStatusChange: options.onStatusChange,
+      onJobIdChange: options.onJobIdChange,
+      onVideoStatusChange: options.onVideoStatusChange
+    };
+  }
+  /**
+   * Trigger video generation.
+   * Only one generation can be in-flight at a time.
+   */
+  async generate(input) {
+    if (this.isLoading) return;
+    this.setIsLoading(true);
+    this.setStatus("generating");
+    this.setError(void 0);
+    this.setJobId(null);
+    this.setVideoStatus(null);
+    const abortController = new AbortController();
+    this.abortController = abortController;
+    const { signal } = abortController;
+    try {
+      if (this.fetcher) {
+        await this.generateWithFetcher(input, signal);
+      } else if (this.connection) {
+        const mergedData = { ...this.body, ...input };
+        const stream = this.connection.connect([], mergedData, signal);
+        await this.processStream(stream);
+      } else {
+        throw new Error(
+          "VideoGenerationClient requires either a connection or fetcher option"
+        );
+      }
+    } catch (err) {
+      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);
+    }
+  }
+  /**
+   * Direct fetcher mode: call fetcher and set result.
+   */
+  async generateWithFetcher(input, signal) {
+    if (!this.fetcher) return;
+    const result = await this.fetcher(input, { signal });
+    if (signal.aborted) return;
+    if (result instanceof Response) {
+      await this.processStream(parseSSEResponse(result, signal));
+    } else {
+      this.setResult(result);
+      this.setStatus("success");
+    }
+  }
+  /**
+   * Process a stream of AG-UI events from the ConnectionAdapter.
+   * The server handles the polling loop and streams status updates.
+   */
+  async processStream(source) {
+    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.VIDEO_JOB_CREATED) {
+            const { jobId } = chunk.value;
+            this.setJobId(jobId);
+            this.callbacksRef.onJobCreated?.(jobId);
+          } else if (chunk.name === GENERATION_EVENTS.VIDEO_STATUS) {
+            const statusInfo = chunk.value;
+            this.setVideoStatus(statusInfo);
+            this.callbacksRef.onStatusUpdate?.(statusInfo);
+            if (statusInfo.progress !== void 0) {
+              this.callbacksRef.onProgress?.(statusInfo.progress);
+            }
+          } else if (chunk.name === GENERATION_EVENTS.RESULT) {
+            this.setResult(chunk.value);
+          } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {
+            const { progress, message } = chunk.value;
+            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 or polling.
+   */
+  stop() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.setIsLoading(false);
+    if (this.status === "generating") {
+      this.setStatus("idle");
+    }
+  }
+  /**
+   * Clear all state and return to idle.
+   */
+  reset() {
+    this.stop();
+    this.setResult(null);
+    this.setJobId(null);
+    this.setVideoStatus(null);
+    this.setError(void 0);
+    this.setStatus("idle");
+  }
+  /**
+   * Update options without recreating the client.
+   */
+  updateOptions(options) {
+    if (options.body !== void 0) {
+      this.body = options.body ?? {};
+    }
+    if (options.onResult !== void 0) {
+      this.callbacksRef.onResult = options.onResult;
+    }
+    if (options.onError !== void 0) {
+      this.callbacksRef.onError = options.onError;
+    }
+    if (options.onProgress !== void 0) {
+      this.callbacksRef.onProgress = options.onProgress;
+    }
+    if (options.onChunk !== void 0) {
+      this.callbacksRef.onChunk = options.onChunk;
+    }
+    if (options.onJobCreated !== void 0) {
+      this.callbacksRef.onJobCreated = options.onJobCreated;
+    }
+    if (options.onStatusUpdate !== void 0) {
+      this.callbacksRef.onStatusUpdate = options.onStatusUpdate;
+    }
+  }
+  // ===========================
+  // Getters
+  // ===========================
+  getResult() {
+    return this.result;
+  }
+  getJobId() {
+    return this.jobId;
+  }
+  getVideoStatus() {
+    return this.videoStatus;
+  }
+  getIsLoading() {
+    return this.isLoading;
+  }
+  getError() {
+    return this.error;
+  }
+  getStatus() {
+    return this.status;
+  }
+  // ===========================
+  // Private state setters
+  // ===========================
+  setResult(rawResult) {
+    if (rawResult === null) {
+      this.result = null;
+      this.callbacksRef.onResultChange?.(null);
+      return;
+    }
+    if (this.callbacksRef.onResult) {
+      const transformed = this.callbacksRef.onResult(rawResult);
+      if (transformed === null) {
+        return;
+      }
+      if (transformed !== void 0) {
+        this.result = transformed;
+        this.callbacksRef.onResultChange?.(this.result);
+        return;
+      }
+    }
+    this.result = rawResult;
+    this.callbacksRef.onResultChange?.(this.result);
+  }
+  setJobId(jobId) {
+    this.jobId = jobId;
+    this.callbacksRef.onJobIdChange?.(jobId);
+  }
+  setVideoStatus(status) {
+    this.videoStatus = status;
+    this.callbacksRef.onVideoStatusChange?.(status);
+  }
+  setIsLoading(isLoading) {
+    this.isLoading = isLoading;
+    this.callbacksRef.onLoadingChange?.(isLoading);
+  }
+  setError(error) {
+    this.error = error;
+    this.callbacksRef.onErrorChange?.(error);
+  }
+  setStatus(status) {
+    this.status = status;
+    this.callbacksRef.onStatusChange?.(status);
+  }
+}
+export {
+  VideoGenerationClient
+};
+//# sourceMappingURL=video-generation-client.js.map

package/dist/esm/video-generation-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-generation-client.js","sources":["../../src/video-generation-client.ts"],"sourcesContent":["import { GENERATION_EVENTS } from './generation-types'\nimport { parseSSEResponse } from './sse-parser'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type { ConnectionAdapter } from './connection-adapters'\nimport type {\n  GenerationClientState,\n  GenerationFetcher,\n  VideoGenerateInput,\n  VideoGenerateResult,\n  VideoGenerationClientOptions,\n  VideoStatusInfo,\n} from './generation-types'\n\n/**\n * Callbacks stored in a ref so hooks can update them without recreating the client.\n */\ninterface VideoCallbacks<TOutput> {\n  onResult?: (result: VideoGenerateResult) => TOutput | null | void\n  onError?: (error: Error) => void\n  onProgress?: (progress: number, message?: string) => void\n  onChunk?: (chunk: StreamChunk) => void\n  onJobCreated?: (jobId: string) => void\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n  onResultChange?: (result: TOutput | null) => void\n  onLoadingChange?: (isLoading: boolean) => void\n  onErrorChange?: (error: Error | undefined) => void\n  onStatusChange?: (status: GenerationClientState) => void\n  onJobIdChange?: (jobId: string | null) => void\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n/**\n * A specialized client for job-based video generation.\n *\n * Video generation is asynchronous: a job is created, then polled for status\n * until completion. This client handles the full lifecycle.\n *\n * Supports two transport modes:\n * - **ConnectionAdapter** — Server handles the polling loop internally and\n *   streams status updates via CUSTOM events.\n * - **Fetcher** — Direct async function that returns a completed\n *   `VideoGenerateResult`.\n *\n * @example\n * ```typescript\n * // With ConnectionAdapter (server-driven polling)\n * const client = new VideoGenerationClient({\n *   connection: fetchServerSentEvents('/api/generate/video'),\n *   onResultChange: setResult,\n *   onVideoStatusChange: setVideoStatus,\n * })\n *\n * // With fetcher (direct result)\n * const client = new VideoGenerationClient({\n *   fetcher: async (input) => {\n *     const res = await fetch('/api/video/generate', {\n *       method: 'POST',\n *       body: JSON.stringify(input),\n *     })\n *     return res.json() // { jobId, status: 'completed', url, expiresAt }\n *   },\n * })\n *\n * await client.generate({ prompt: 'A flying car over a city' })\n * ```\n */\nexport class VideoGenerationClient<TOutput = VideoGenerateResult> {\n  private connection: ConnectionAdapter | undefined\n  private fetcher:\n    | GenerationFetcher<VideoGenerateInput, VideoGenerateResult>\n    | undefined\n  private body: Record<string, any>\n\n  private result: TOutput | null = null\n  private jobId: string | null = null\n  private videoStatus: VideoStatusInfo | null = null\n  private isLoading = false\n  private error: Error | undefined = undefined\n  private status: GenerationClientState = 'idle'\n  private abortController: AbortController | null = null\n  private callbacksRef: VideoCallbacks<TOutput>\n\n  constructor(\n    options: VideoGenerationClientOptions<TOutput> &\n      (\n        | { connection: ConnectionAdapter; fetcher?: never }\n        | {\n            fetcher: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>\n            connection?: never\n          }\n      ),\n  ) {\n    this.connection = options.connection\n    this.fetcher = options.fetcher\n    this.body = options.body ?? {}\n\n    this.callbacksRef = {\n      onResult: options.onResult,\n      onError: options.onError,\n      onProgress: options.onProgress,\n      onChunk: options.onChunk,\n      onJobCreated: options.onJobCreated,\n      onStatusUpdate: options.onStatusUpdate,\n      onResultChange: options.onResultChange,\n      onLoadingChange: options.onLoadingChange,\n      onErrorChange: options.onErrorChange,\n      onStatusChange: options.onStatusChange,\n      onJobIdChange: options.onJobIdChange,\n      onVideoStatusChange: options.onVideoStatusChange,\n    }\n  }\n\n  /**\n   * Trigger video generation.\n   * Only one generation can be in-flight at a time.\n   */\n  async generate(input: VideoGenerateInput): Promise<void> {\n    if (this.isLoading) return\n\n    this.setIsLoading(true)\n    this.setStatus('generating')\n    this.setError(undefined)\n    this.setJobId(null)\n    this.setVideoStatus(null)\n\n    const abortController = new AbortController()\n    this.abortController = abortController\n    const { signal } = abortController\n\n    try {\n      if (this.fetcher) {\n        await this.generateWithFetcher(input, signal)\n      } else if (this.connection) {\n        const mergedData = { ...this.body, ...input }\n        const stream = this.connection.connect([], mergedData, signal)\n        await this.processStream(stream)\n      } else {\n        throw new Error(\n          'VideoGenerationClient requires either a connection or fetcher option',\n        )\n      }\n    } catch (err: any) {\n      if (signal.aborted) return\n      const error = err instanceof Error ? err : new Error(String(err))\n      this.setError(error)\n      this.setStatus('error')\n      this.callbacksRef.onError?.(error)\n    } finally {\n      this.abortController = null\n      this.setIsLoading(false)\n    }\n  }\n\n  /**\n   * Direct fetcher mode: call fetcher and set result.\n   */\n  private async generateWithFetcher(\n    input: VideoGenerateInput,\n    signal: AbortSignal,\n  ): Promise<void> {\n    if (!this.fetcher) return\n\n    // Fetcher returns a completed result directly, or a Response with SSE body\n    const result = await this.fetcher(input, { signal })\n    if (signal.aborted) return\n\n    if (result instanceof Response) {\n      // Server function returned SSE Response — parse stream\n      await this.processStream(parseSSEResponse(result, signal))\n    } else {\n      this.setResult(result)\n      this.setStatus('success')\n    }\n  }\n\n  /**\n   * Process a stream of AG-UI events from the ConnectionAdapter.\n   * The server handles the polling loop and streams status updates.\n   */\n  private async processStream(\n    source: AsyncIterable<StreamChunk>,\n  ): Promise<void> {\n    for await (const chunk of source) {\n      if (this.abortController?.signal.aborted) break\n\n      this.callbacksRef.onChunk?.(chunk)\n\n      switch (chunk.type) {\n        case 'CUSTOM': {\n          if (chunk.name === GENERATION_EVENTS.VIDEO_JOB_CREATED) {\n            const { jobId } = chunk.value as { jobId: string }\n            this.setJobId(jobId)\n            this.callbacksRef.onJobCreated?.(jobId)\n          } else if (chunk.name === GENERATION_EVENTS.VIDEO_STATUS) {\n            const statusInfo = chunk.value as VideoStatusInfo\n            this.setVideoStatus(statusInfo)\n            this.callbacksRef.onStatusUpdate?.(statusInfo)\n            if (statusInfo.progress !== undefined) {\n              this.callbacksRef.onProgress?.(statusInfo.progress)\n            }\n          } else if (chunk.name === GENERATION_EVENTS.RESULT) {\n            this.setResult(chunk.value as VideoGenerateResult)\n          } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {\n            const { progress, message } = chunk.value as {\n              progress: number\n              message?: string\n            }\n            this.callbacksRef.onProgress?.(progress, message)\n          }\n          break\n        }\n        case 'RUN_FINISHED': {\n          this.setStatus('success')\n          break\n        }\n        case 'RUN_ERROR': {\n          throw new Error(chunk.error.message)\n        }\n      }\n    }\n  }\n\n  /**\n   * Abort any in-flight generation or polling.\n   */\n  stop(): void {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    this.setIsLoading(false)\n    if (this.status === 'generating') {\n      this.setStatus('idle')\n    }\n  }\n\n  /**\n   * Clear all state and return to idle.\n   */\n  reset(): void {\n    this.stop()\n    this.setResult(null)\n    this.setJobId(null)\n    this.setVideoStatus(null)\n    this.setError(undefined)\n    this.setStatus('idle')\n  }\n\n  /**\n   * Update options without recreating the client.\n   */\n  updateOptions(\n    options: Partial<\n      Pick<\n        VideoGenerationClientOptions<TOutput>,\n        | 'body'\n        | 'onResult'\n        | 'onError'\n        | 'onProgress'\n        | 'onChunk'\n        | 'onJobCreated'\n        | 'onStatusUpdate'\n      >\n    >,\n  ): void {\n    if (options.body !== undefined) {\n      this.body = options.body ?? {}\n    }\n    if (options.onResult !== undefined) {\n      this.callbacksRef.onResult = options.onResult\n    }\n    if (options.onError !== undefined) {\n      this.callbacksRef.onError = options.onError\n    }\n    if (options.onProgress !== undefined) {\n      this.callbacksRef.onProgress = options.onProgress\n    }\n    if (options.onChunk !== undefined) {\n      this.callbacksRef.onChunk = options.onChunk\n    }\n    if (options.onJobCreated !== undefined) {\n      this.callbacksRef.onJobCreated = options.onJobCreated\n    }\n    if (options.onStatusUpdate !== undefined) {\n      this.callbacksRef.onStatusUpdate = options.onStatusUpdate\n    }\n  }\n\n  // ===========================\n  // Getters\n  // ===========================\n\n  getResult(): TOutput | null {\n    return this.result\n  }\n\n  getJobId(): string | null {\n    return this.jobId\n  }\n\n  getVideoStatus(): VideoStatusInfo | null {\n    return this.videoStatus\n  }\n\n  getIsLoading(): boolean {\n    return this.isLoading\n  }\n\n  getError(): Error | undefined {\n    return this.error\n  }\n\n  getStatus(): GenerationClientState {\n    return this.status\n  }\n\n  // ===========================\n  // Private state setters\n  // ===========================\n\n  private setResult(rawResult: VideoGenerateResult | null): void {\n    if (rawResult === null) {\n      this.result = null\n      this.callbacksRef.onResultChange?.(null)\n      return\n    }\n\n    if (this.callbacksRef.onResult) {\n      const transformed = this.callbacksRef.onResult(rawResult)\n      if (transformed === null) {\n        // null return → keep previous result unchanged\n        return\n      }\n      if (transformed !== undefined) {\n        // Non-null, non-undefined → use transformed value\n        this.result = transformed\n        this.callbacksRef.onResultChange?.(this.result)\n        return\n      }\n    }\n\n    // No onResult callback, or callback returned void → use raw value\n    this.result = rawResult as unknown as TOutput\n    this.callbacksRef.onResultChange?.(this.result)\n  }\n\n  private setJobId(jobId: string | null): void {\n    this.jobId = jobId\n    this.callbacksRef.onJobIdChange?.(jobId)\n  }\n\n  private setVideoStatus(status: VideoStatusInfo | null): void {\n    this.videoStatus = status\n    this.callbacksRef.onVideoStatusChange?.(status)\n  }\n\n  private setIsLoading(isLoading: boolean): void {\n    this.isLoading = isLoading\n    this.callbacksRef.onLoadingChange?.(isLoading)\n  }\n\n  private setError(error: Error | undefined): void {\n    this.error = error\n    this.callbacksRef.onErrorChange?.(error)\n  }\n\n  private setStatus(status: GenerationClientState): void {\n    this.status = status\n    this.callbacksRef.onStatusChange?.(status)\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Framework-agnostic headless client for TanStack AI",
   "author": "",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "0.6.2"
+    "@tanstack/ai": "0.6.3"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",

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)
+  }
+}