@tanstack/ai 0.55.0 → 0.58.0

package/dist/esm/activities/generateSpeech/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/generateSpeech/adapter.ts"],"sourcesContent":["import type { TTSOptions, TTSResult } from '../../types'\n\n/**\n * Configuration for TTS adapter instances\n */\nexport interface TTSAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * TTS adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'tts-1')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface TTSAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'tts'\n  /** Adapter name identifier */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  /**\n   * Generate speech from text\n   */\n  generateSpeech: (options: TTSOptions<TProviderOptions>) => Promise<TTSResult>\n}\n\n/**\n * A TTSAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTTSAdapter = TTSAdapter<any, any>\n\n/**\n * Abstract base class for text-to-speech adapters.\n * Extend this class to implement a TTS adapter for a specific provider.\n *\n * Generic parameters match TTSAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTTSAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements TTSAdapter<TModel, TProviderOptions> {\n  readonly kind = 'tts' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  protected config: TTSAdapterConfig\n\n  constructor(model: TModel, config: TTSAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract generateSpeech(\n    options: TTSOptions<TProviderOptions>,\n  ): Promise<TTSResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA2DA,IAAsB,iBAAtB,MAGkD;CAChD,OAAgB;CAEhB;CAOA;CAEA,YAAY,OAAe,SAA2B,CAAC,GAAG;EACxD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAMA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/generateSpeech/adapter.ts"],"sourcesContent":["import type {\n  ListVoicesOptions,\n  ListVoicesResult,\n  TTSOptions,\n  TTSResult,\n} from '../../types'\n\n/**\n * What a TTS adapter can do beyond a single voice reading a single string.\n *\n * Declared statically so `generateSpeech()` can reject an unsupported request\n * before it reaches the provider, instead of surfacing a provider 422.\n */\nexport interface TTSCapabilities {\n  /**\n   * Maximum number of distinct voices accepted across `turns`\n   * (ElevenLabs 10, Gemini 2). Omit it when the adapter has no dialogue\n   * endpoint — then `turns` is rejected outright.\n   */\n  maxSpeakers?: number\n  /** Set when the adapter can honour `timestamps: true`. */\n  timestamps?: boolean\n}\n\n/**\n * Configuration for TTS adapter instances\n */\nexport interface TTSAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * TTS adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'tts-1')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface TTSAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'tts'\n  /** Adapter name identifier */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n  /**\n   * Optional static capability declaration. Absent means \"single voice, no\n   * timestamps\" — the contract every adapter had before dialogue existed.\n   */\n  readonly capabilities?: TTSCapabilities\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  /**\n   * Generate speech from text\n   */\n  generateSpeech: (options: TTSOptions<TProviderOptions>) => Promise<TTSResult>\n\n  /**\n   * List the voices this account can use.\n   *\n   * Optional, because only some providers have a catalog worth querying at\n   * runtime. A provider whose voices are a fixed list known at build time\n   * publishes that list from its own package instead (`GeminiTTSVoices`, or\n   * the `OpenAITTSVoice` union), which is strictly better than a network\n   * call. Implement this only when the catalog is per-account and can change,\n   * which is the case wherever `generateVoice()` can add to it.\n   */\n  listVoices?: (options?: ListVoicesOptions) => Promise<ListVoicesResult>\n}\n\n/**\n * A TTSAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTTSAdapter = TTSAdapter<any, any>\n\n/**\n * Abstract base class for text-to-speech adapters.\n * Extend this class to implement a TTS adapter for a specific provider.\n *\n * Generic parameters match TTSAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTTSAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements TTSAdapter<TModel, TProviderOptions> {\n  readonly kind = 'tts' as const\n  abstract readonly name: string\n  readonly model: TModel\n  declare readonly capabilities?: TTSCapabilities\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  protected config: TTSAdapterConfig\n\n  constructor(model: TModel, config: TTSAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract generateSpeech(\n    options: TTSOptions<TProviderOptions>,\n  ): Promise<TTSResult>\n\n  /**\n   * Not abstract: a provider with a fixed voice list has nothing to query and\n   * should not be forced to write a stub.\n   */\n  listVoices?(options?: ListVoicesOptions): Promise<ListVoicesResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AAkGA,IAAsB,iBAAtB,MAGkD;CAChD,OAAgB;CAEhB;CAQA;CAEA,YAAY,OAAe,SAA2B,CAAC,GAAG;EACxD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAYA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

package/dist/esm/activities/generateSpeech/index.d.ts

@@ -1,7 +1,7 @@
 import { DebugOption } from '../../logger/types.js';
 import { GenerationMiddleware } from '../middleware/types.js';
 import { TTSAdapter } from './adapter.js';
-import { StreamChunk, TTSResult } from '../../types.js';
+import { ListVoicesOptions, ListVoicesResult, StreamChunk, TTSResult, TTSTurn } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "tts";
 /**
@@ -19,15 +19,37 @@ export type TTSProviderOptions<TAdapter> = TAdapter extends {
  * @template TAdapter - The TTS adapter type
  * @template TStream - Whether to stream the output
  */
-export interface TTSActivityOptions<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false> {
+export type TTSActivityOptions<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false> = TTSActivityOptionsBase<TAdapter, TStream> & ({
+    /** The text to convert to speech */
+    text: string;
+    turns?: undefined;
+} | {
+    text?: undefined;
+    /**
+     * Multi-voice dialogue turns, one per line of the script. Mutually
+     * exclusive with `text`.
+     *
+     * Only adapters that declare `capabilities.maxSpeakers` accept these
+     * (ElevenLabs 10 voices, Gemini 2); anything else throws before the
+     * request leaves the process.
+     */
+    turns: Array<TTSTurn>;
+});
+/** Shared half of {@link TTSActivityOptions} — everything except text/turns. */
+interface TTSActivityOptionsBase<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false> {
     /** The TTS adapter to use (must be created with a model) */
     adapter: TAdapter & {
         kind: typeof kind;
     };
-    /** The text to convert to speech */
-    text: string;
     /** The voice to use for generation */
     voice?: string;
+    /**
+     * Ask for `alignment` (character/word timings) and `segments` (per-turn
+     * spans) on the result. Only adapters that declare
+     * `capabilities.timestamps` accept it — on ElevenLabs it is a different
+     * endpoint, on BytePlus a different request flag, so it cannot be inferred.
+     */
+    timestamps?: boolean;
     /** The output audio format */
     format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
     /** The speed of the generated audio (0.25 to 4.0) */
@@ -108,9 +130,37 @@ export type TTSActivityResult<TStream extends boolean = false> = TStream extends
  * ```
  */
 export declare function generateSpeech<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream>;
+/**
+ * Options for {@link listVoices}.
+ */
+export interface ListVoicesActivityOptions<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>> extends ListVoicesOptions {
+    /** The speech adapter whose catalog to read */
+    adapter: TAdapter & {
+        kind: typeof kind;
+    };
+}
+/**
+ * List the voices an account can pass to `generateSpeech()`.
+ *
+ * Only providers with a per-account catalog implement this. A provider whose
+ * voices are a fixed list publishes that list as a const in its package, so
+ * import it from there rather than calling this.
+ *
+ * @example Find the voices you created
+ * ```ts
+ * import { listVoices } from '@tanstack/ai'
+ * import { elevenlabsSpeech } from '@tanstack/ai-elevenlabs'
+ *
+ * const { voices } = await listVoices({
+ *   adapter: elevenlabsSpeech('eleven_v3'),
+ *   origins: ['generated', 'cloned'],
+ * })
+ * ```
+ */
+export declare function listVoices<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>>(options: ListVoicesActivityOptions<TAdapter>): Promise<ListVoicesResult>;
 /**
  * Create typed options for the generateSpeech() function without executing.
  */
 export declare function createSpeechOptions<TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityOptions<TAdapter, TStream>;
-export type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter.js';
+export type { TTSAdapter, TTSAdapterConfig, TTSCapabilities, AnyTTSAdapter, } from './adapter.js';
 export { BaseTTSAdapter } from './adapter.js';

package/dist/esm/activities/generateSpeech/index.js

@@ -17,6 +17,30 @@ function createId(prefix) {
 	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
 /**
+* Validate the text/turns/timestamps trio against what the adapter declares,
+* and return the `text` every adapter receives.
+*
+* For a dialogue request that text is the turn scripts joined by newlines:
+* dialogue-aware adapters read `turns` and ignore it, but it keeps `text`
+* non-optional on the adapter contract and gives the devtools event and the
+* artifact inputs something truthful to show.
+*/
+function resolveSpeechText(adapter, input) {
+	const { text, turns, timestamps } = input;
+	if (timestamps && !adapter.capabilities?.timestamps) throw new Error(`${adapter.name} cannot return timestamps. Drop \`timestamps: true\` — the result would have no alignment to read.`);
+	if (turns) {
+		if (text !== void 0) throw new Error("generateSpeech() takes either `text` or `turns`, not both.");
+		if (turns.length === 0) throw new Error("generateSpeech() `turns` must not be empty.");
+		const maxSpeakers = adapter.capabilities?.maxSpeakers;
+		if (maxSpeakers === void 0) throw new Error(`${adapter.name} cannot generate dialogue. Pass \`text\` (and \`voice\`) instead of \`turns\`.`);
+		const speakers = new Set(turns.map((turn) => turn.voice)).size;
+		if (speakers > maxSpeakers) throw new Error(`${adapter.name} accepts at most ${maxSpeakers} distinct voice${maxSpeakers === 1 ? "" : "s"} per request; received ${speakers}.`);
+		return turns.map((turn) => turn.text).join("\n");
+	}
+	if (text === void 0) throw new Error("generateSpeech() requires either `text` or `turns`.");
+	return text;
+}
+/**
 * TTS activity - generates speech from text.
 *
 * Uses AI text-to-speech models to create audio from natural language text.
@@ -59,6 +83,7 @@ function generateSpeech(options) {
 async function runGenerateSpeech(options) {
 	const { adapter, stream: _stream, debug: _debug, middleware, threadId, runId, timeout, abortSignal: callerAbortSignal, ...rest } = options;
 	const model = adapter.model;
+	const text = resolveSpeechText(adapter, rest);
 	const requestId = createId("speech");
 	const startTime = Date.now();
 	const logger = resolveDebugOption(options.debug);
@@ -74,7 +99,7 @@ async function runGenerateSpeech(options) {
 		model,
 		modelOptions: rest.modelOptions,
 		artifactInputs: {
-			text: rest.text,
+			text,
 			voice: rest.voice,
 			format: rest.format,
 			speed: rest.speed
@@ -88,7 +113,7 @@ async function runGenerateSpeech(options) {
 		requestId,
 		provider: adapter.name,
 		model,
-		text: rest.text,
+		text,
 		voice: rest.voice,
 		format: rest.format,
 		speed: rest.speed,
@@ -102,6 +127,7 @@ async function runGenerateSpeech(options) {
 	try {
 		const rawResult = await raceWithAbort(adapter.generateSpeech({
 			...rest,
+			text,
 			model,
 			logger,
 			...abortControls.signal ? { abortSignal: abortControls.signal } : {}
@@ -170,12 +196,36 @@ async function runGenerateSpeech(options) {
 	}
 }
 /**
+* List the voices an account can pass to `generateSpeech()`.
+*
+* Only providers with a per-account catalog implement this. A provider whose
+* voices are a fixed list publishes that list as a const in its package, so
+* import it from there rather than calling this.
+*
+* @example Find the voices you created
+* ```ts
+* import { listVoices } from '@tanstack/ai'
+* import { elevenlabsSpeech } from '@tanstack/ai-elevenlabs'
+*
+* const { voices } = await listVoices({
+*   adapter: elevenlabsSpeech('eleven_v3'),
+*   origins: ['generated', 'cloned'],
+* })
+* ```
+*/
+async function listVoices(options) {
+	const { adapter, ...rest } = options;
+	const list = adapter.listVoices;
+	if (!list) throw new Error(`The ${adapter.name} speech adapter has no per-account voice catalog to list. Its voices are a fixed set — import the voice list or union its package exports instead (for example \`GeminiTTSVoices\` from @tanstack/ai-gemini, or the \`OpenAITTSVoice\` union from @tanstack/ai-openai).`);
+	return await list.call(adapter, rest);
+}
+/**
 * Create typed options for the generateSpeech() function without executing.
 */
 function createSpeechOptions(options) {
 	return options;
 }
 //#endregion
-export { createSpeechOptions, generateSpeech, kind };
+export { createSpeechOptions, generateSpeech, kind, listVoices };
 
 //# sourceMappingURL=index.js.map

package/dist/esm/activities/generateSpeech/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  applyGenerationResultTransforms,\n  createGenerationContext,\n  runGenerationAbort,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware/run'\nimport {\n  abortReasonMessage,\n  createActivityAbortControls,\n  isActivityAbortError,\n  raceWithAbort,\n} from '../../utilities/activity-abort'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware/types'\nimport type { TTSAdapter } from './adapter'\nimport type { StreamChunk, TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n  /** Stable conversation/thread id for correlating this run when persisted. */\n  threadId?: string\n  /** Stable run id for correlating this run when persisted. */\n  runId?: string\n  /**\n   * Maximum duration of this activity invocation in milliseconds.\n   * No SDK-wide default — choose a value suitable for the provider and job.\n   * Composed with {@link abortSignal}; the first abort wins.\n   */\n  timeout?: number\n  /**\n   * Caller cancellation signal (request disconnects, job/runtime cancellation).\n   * Composed with {@link timeout} into an effective signal forwarded to the\n   * adapter. Request-specific — not stored on global provider client config.\n   */\n  abortSignal?: AbortSignal\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiSpeech } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(\n      // Only `runId` is taken from the resolved wire identity. `threadId` stays\n      // the CALLER's: `streamGenerationResult` mints one for the RUN_* chunks\n      // when none was passed, and spreading that over the options would hand\n      // middleware a thread id known to nobody, which persistence would then\n      // file the run under. Matches `generateVideo`.\n      (resolved) => runGenerateSpeech({ ...options, runId: resolved.runId }),\n      options,\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    threadId,\n    runId,\n    timeout,\n    abortSignal: callerAbortSignal,\n    ...rest\n  } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const abortControls = createActivityAbortControls({\n    timeout,\n    abortSignal: callerAbortSignal,\n  })\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'tts',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    artifactInputs: {\n      text: rest.text,\n      voice: rest.voice,\n      format: rest.format,\n      speed: rest.speed,\n    },\n    threadId,\n    runId,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateSpeech provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const rawResult = await raceWithAbort(\n      adapter.generateSpeech({\n        ...rest,\n        model,\n        logger,\n        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),\n      }),\n      abortControls.signal,\n    )\n    abortControls.clear()\n    const result = await applyGenerationResultTransforms(mwCtx, rawResult)\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('speech:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {\n      bytes: result.audio.length,\n      contentType: result.contentType,\n    })\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    abortControls.clear()\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('speech:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    if (isActivityAbortError(error, abortControls.signal)) {\n      await runGenerationAbort(middleware, mwCtx, {\n        reason: abortReasonMessage(error, abortControls.signal),\n        duration,\n      })\n    } else {\n      await runGenerationError(middleware, mwCtx, {\n        error,\n        duration,\n      })\n    }\n    logger.errors('generateSpeech activity failed', {\n      error,\n      source: 'generateSpeech',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  applyGenerationResultTransforms,\n  createGenerationContext,\n  runGenerationAbort,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware/run'\nimport {\n  abortReasonMessage,\n  createActivityAbortControls,\n  isActivityAbortError,\n  raceWithAbort,\n} from '../../utilities/activity-abort'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware/types'\nimport type { TTSAdapter, TTSCapabilities } from './adapter'\nimport type {\n  ListVoicesOptions,\n  ListVoicesResult,\n  StreamChunk,\n  TTSResult,\n  TTSTurn,\n} from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport type TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> = TTSActivityOptionsBase<TAdapter, TStream> &\n  (\n    | {\n        /** The text to convert to speech */\n        text: string\n        turns?: undefined\n      }\n    | {\n        text?: undefined\n        /**\n         * Multi-voice dialogue turns, one per line of the script. Mutually\n         * exclusive with `text`.\n         *\n         * Only adapters that declare `capabilities.maxSpeakers` accept these\n         * (ElevenLabs 10 voices, Gemini 2); anything else throws before the\n         * request leaves the process.\n         */\n        turns: Array<TTSTurn>\n      }\n  )\n\n/** Shared half of {@link TTSActivityOptions} — everything except text/turns. */\ninterface TTSActivityOptionsBase<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The voice to use for generation */\n  voice?: string\n  /**\n   * Ask for `alignment` (character/word timings) and `segments` (per-turn\n   * spans) on the result. Only adapters that declare\n   * `capabilities.timestamps` accept it — on ElevenLabs it is a different\n   * endpoint, on BytePlus a different request flag, so it cannot be inferred.\n   */\n  timestamps?: boolean\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n  /** Stable conversation/thread id for correlating this run when persisted. */\n  threadId?: string\n  /** Stable run id for correlating this run when persisted. */\n  runId?: string\n  /**\n   * Maximum duration of this activity invocation in milliseconds.\n   * No SDK-wide default — choose a value suitable for the provider and job.\n   * Composed with {@link abortSignal}; the first abort wins.\n   */\n  timeout?: number\n  /**\n   * Caller cancellation signal (request disconnects, job/runtime cancellation).\n   * Composed with {@link timeout} into an effective signal forwarded to the\n   * adapter. Request-specific — not stored on global provider client config.\n   */\n  abortSignal?: AbortSignal\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n/**\n * Validate the text/turns/timestamps trio against what the adapter declares,\n * and return the `text` every adapter receives.\n *\n * For a dialogue request that text is the turn scripts joined by newlines:\n * dialogue-aware adapters read `turns` and ignore it, but it keeps `text`\n * non-optional on the adapter contract and gives the devtools event and the\n * artifact inputs something truthful to show.\n */\nfunction resolveSpeechText(\n  adapter: { name: string; capabilities?: TTSCapabilities },\n  input: { text?: string; turns?: Array<TTSTurn>; timestamps?: boolean },\n): string {\n  const { text, turns, timestamps } = input\n\n  if (timestamps && !adapter.capabilities?.timestamps) {\n    throw new Error(\n      `${adapter.name} cannot return timestamps. Drop \\`timestamps: true\\` — the result would have no alignment to read.`,\n    )\n  }\n\n  if (turns) {\n    if (text !== undefined) {\n      throw new Error(\n        'generateSpeech() takes either `text` or `turns`, not both.',\n      )\n    }\n    if (turns.length === 0) {\n      throw new Error('generateSpeech() `turns` must not be empty.')\n    }\n    const maxSpeakers = adapter.capabilities?.maxSpeakers\n    if (maxSpeakers === undefined) {\n      throw new Error(\n        `${adapter.name} cannot generate dialogue. Pass \\`text\\` (and \\`voice\\`) instead of \\`turns\\`.`,\n      )\n    }\n    const speakers = new Set(turns.map((turn) => turn.voice)).size\n    if (speakers > maxSpeakers) {\n      throw new Error(\n        `${adapter.name} accepts at most ${maxSpeakers} distinct voice${maxSpeakers === 1 ? '' : 's'} per request; received ${speakers}.`,\n      )\n    }\n    return turns.map((turn) => turn.text).join('\\n')\n  }\n\n  if (text === undefined) {\n    throw new Error('generateSpeech() requires either `text` or `turns`.')\n  }\n  return text\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiSpeech } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(\n      // Only `runId` is taken from the resolved wire identity. `threadId` stays\n      // the CALLER's: `streamGenerationResult` mints one for the RUN_* chunks\n      // when none was passed, and spreading that over the options would hand\n      // middleware a thread id known to nobody, which persistence would then\n      // file the run under. Matches `generateVideo`.\n      (resolved) => runGenerateSpeech({ ...options, runId: resolved.runId }),\n      options,\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    threadId,\n    runId,\n    timeout,\n    abortSignal: callerAbortSignal,\n    ...rest\n  } = options\n  const model = adapter.model\n  const text = resolveSpeechText(adapter, rest)\n  const requestId = createId('speech')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const abortControls = createActivityAbortControls({\n    timeout,\n    abortSignal: callerAbortSignal,\n  })\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'tts',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    artifactInputs: {\n      text,\n      voice: rest.voice,\n      format: rest.format,\n      speed: rest.speed,\n    },\n    threadId,\n    runId,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateSpeech provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const rawResult = await raceWithAbort(\n      adapter.generateSpeech({\n        ...rest,\n        text,\n        model,\n        logger,\n        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),\n      }),\n      abortControls.signal,\n    )\n    abortControls.clear()\n    const result = await applyGenerationResultTransforms(mwCtx, rawResult)\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('speech:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {\n      bytes: result.audio.length,\n      contentType: result.contentType,\n    })\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    abortControls.clear()\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('speech:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    if (isActivityAbortError(error, abortControls.signal)) {\n      await runGenerationAbort(middleware, mwCtx, {\n        reason: abortReasonMessage(error, abortControls.signal),\n        duration,\n      })\n    } else {\n      await runGenerationError(middleware, mwCtx, {\n        error,\n        duration,\n      })\n    }\n    logger.errors('generateSpeech activity failed', {\n      error,\n      source: 'generateSpeech',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Voice Catalog\n// ===========================\n\n/**\n * Options for {@link listVoices}.\n */\nexport interface ListVoicesActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n> extends ListVoicesOptions {\n  /** The speech adapter whose catalog to read */\n  adapter: TAdapter & { kind: typeof kind }\n}\n\n/**\n * List the voices an account can pass to `generateSpeech()`.\n *\n * Only providers with a per-account catalog implement this. A provider whose\n * voices are a fixed list publishes that list as a const in its package, so\n * import it from there rather than calling this.\n *\n * @example Find the voices you created\n * ```ts\n * import { listVoices } from '@tanstack/ai'\n * import { elevenlabsSpeech } from '@tanstack/ai-elevenlabs'\n *\n * const { voices } = await listVoices({\n *   adapter: elevenlabsSpeech('eleven_v3'),\n *   origins: ['generated', 'cloned'],\n * })\n * ```\n */\nexport async function listVoices<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: ListVoicesActivityOptions<TAdapter>): Promise<ListVoicesResult> {\n  const { adapter, ...rest } = options\n\n  const list = adapter.listVoices\n  if (!list) {\n    throw new Error(\n      `The ${adapter.name} speech adapter has no per-account voice catalog to list. Its voices are a fixed set — import the voice list or union its package exports instead (for example \\`GeminiTTSVoices\\` from @tanstack/ai-gemini, or the \\`OpenAITTSVoice\\` union from @tanstack/ai-openai).`,\n    )\n  }\n\n  return await list.call(adapter, rest)\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TTSAdapter,\n  TTSAdapterConfig,\n  TTSCapabilities,\n  AnyTTSAdapter,\n} from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"mappings":";;;;;;;;;;;;;;AA0CA,IAAa,OAAO;AA0HpB,SAAS,SAAS,QAAwB;CACxC,OAAO,GAAG,OAAO,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;AACzE;;;;;;;;;;AAWA,SAAS,kBACP,SACA,OACQ;CACR,MAAM,EAAE,MAAM,OAAO,eAAe;CAEpC,IAAI,cAAc,CAAC,QAAQ,cAAc,YACvC,MAAM,IAAI,MACR,GAAG,QAAQ,KAAK,mGAClB;CAGF,IAAI,OAAO;EACT,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MACR,4DACF;EAEF,IAAI,MAAM,WAAW,GACnB,MAAM,IAAI,MAAM,6CAA6C;EAE/D,MAAM,cAAc,QAAQ,cAAc;EAC1C,IAAI,gBAAgB,KAAA,GAClB,MAAM,IAAI,MACR,GAAG,QAAQ,KAAK,+EAClB;EAEF,MAAM,WAAW,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC;EAC1D,IAAI,WAAW,aACb,MAAM,IAAI,MACR,GAAG,QAAQ,KAAK,mBAAmB,YAAY,iBAAiB,gBAAgB,IAAI,KAAK,IAAI,yBAAyB,SAAS,EACjI;EAEF,OAAO,MAAM,KAAK,SAAS,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI;CACjD;CAEA,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,qDAAqD;CAEvE,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,eAGd,SAA4E;CAC5E,IAAI,QAAQ,QACV,OAAO,wBAMJ,aAAa,kBAAkB;EAAE,GAAG;EAAS,OAAO,SAAS;CAAM,CAAC,GACrE,OACF;CAEF,OAAO,kBAAkB,OAAO;AAClC;;;;AAKA,eAAe,kBAEb,SAAoE;CACpE,MAAM,EACJ,SACA,QAAQ,SACR,OAAO,QACP,YACA,UACA,OACA,SACA,aAAa,mBACb,GAAG,SACD;CACJ,MAAM,QAAQ,QAAQ;CACtB,MAAM,OAAO,kBAAkB,SAAS,IAAI;CAC5C,MAAM,YAAY,SAAS,QAAQ;CACnC,MAAM,YAAY,KAAK,IAAI;CAC3B,MAAM,SAAyB,mBAAmB,QAAQ,KAAK;CAC/D,MAAM,gBAAgB,4BAA4B;EAChD;EACA,aAAa;CACf,CAAC;CACD,MAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;CAEF,MAAM,QAAQ,wBAAwB;EACpC;EACA,UAAU;EACV,UAAU,QAAQ;EAClB;EACA,cAAc,KAAK;EACnB,gBAAgB;GACd;GACA,OAAO,KAAK;GACZ,QAAQ,KAAK;GACb,OAAO,KAAK;EACd;EACA;EACA;EACA;CACF,CAAC;CAED,MAAM,mBAAmB,YAAY,KAAK;CAE1C,cAAc,KAAK,0BAA0B;EAC3C;EACA,UAAU,QAAQ;EAClB;EACA;EACA,OAAO,KAAK;EACZ,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,cAAc,KAAK;EACnB,WAAW;CACb,CAAC;CAED,OAAO,QAAQ,oCAAoC,gBAAgB;EACjE,UAAU;EACV;CACF,CAAC;CAED,IAAI;EACF,MAAM,YAAY,MAAM,cACtB,QAAQ,eAAe;GACrB,GAAG;GACH;GACA;GACA;GACA,GAAI,cAAc,SAAS,EAAE,aAAa,cAAc,OAAO,IAAI,CAAC;EACtE,CAAC,GACD,cAAc,MAChB;EACA,cAAc,MAAM;EACpB,MAAM,SAAS,MAAM,gCAAgC,OAAO,SAAS;EACrE,MAAM,WAAW,KAAK,IAAI,IAAI;EAE9B,cAAc,KAAK,4BAA4B;GAC7C;GACA,UAAU,QAAQ;GAClB;GACA,OAAO,OAAO;GACd,QAAQ,OAAO;GACf,eAAe,OAAO;GACtB,aAAa,OAAO;GACpB;GACA,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EAED,IAAI,OAAO,OACT,cAAc,KAAK,gBAAgB;GACjC;GACA;GACA,OAAO,OAAO;GACd,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EAGH,OAAO,OAAO,iCAAiC,OAAO,MAAM,UAAU;GACpE,OAAO,OAAO,MAAM;GACpB,aAAa,OAAO;EACtB,CAAC;EAED,IAAI,OAAO,OAAO,MAAM,mBAAmB,YAAY,OAAO,OAAO,KAAK;EAC1E,MAAM,oBAAoB,YAAY,OAAO;GAC3C;GACA,OAAO,OAAO;EAChB,CAAC;EAED,OAAO;CACT,SAAS,OAAO;EACd,cAAc,MAAM;EACpB,MAAM,WAAW,KAAK,IAAI,IAAI;EAC9B,MAAM,MAAM;EACZ,cAAc,KAAK,wBAAwB;GACzC;GACA,UAAU,QAAQ;GAClB;GACA,OAAO;IAAE,SAAS,IAAI;IAAS,MAAM,IAAI;GAAK;GAC9C;GACA,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EACD,IAAI,qBAAqB,OAAO,cAAc,MAAM,GAClD,MAAM,mBAAmB,YAAY,OAAO;GAC1C,QAAQ,mBAAmB,OAAO,cAAc,MAAM;GACtD;EACF,CAAC;OAED,MAAM,mBAAmB,YAAY,OAAO;GAC1C;GACA;EACF,CAAC;EAEH,OAAO,OAAO,kCAAkC;GAC9C;GACA,QAAQ;EACV,CAAC;EACD,MAAM;CACR;AACF;;;;;;;;;;;;;;;;;;;AAkCA,eAAsB,WAEpB,SAAyE;CACzE,MAAM,EAAE,SAAS,GAAG,SAAS;CAE7B,MAAM,OAAO,QAAQ;CACrB,IAAI,CAAC,MACH,MAAM,IAAI,MACR,OAAO,QAAQ,KAAK,wQACtB;CAGF,OAAO,MAAM,KAAK,KAAK,SAAS,IAAI;AACtC;;;;AASA,SAAgB,oBAId,SACuC;CACvC,OAAO;AACT"}

package/dist/esm/activities/generateVoice/adapter.d.ts

@@ -0,0 +1,62 @@
+import { VoiceGenerationOptions, VoiceResult } from '../../types.js';
+/**
+ * Configuration for voice adapter instances
+ */
+export interface VoiceAdapterConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Voice adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'eleven_ttv_v3')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface VoiceAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>> {
+    /** Discriminator for adapter kind - used to determine API shape */
+    readonly kind: 'voice';
+    /** Adapter name identifier */
+    readonly name: string;
+    /** The model this adapter is configured for */
+    readonly model: TModel;
+    /**
+     * @internal Type-only properties for inference. Not assigned at runtime.
+     */
+    '~types': {
+        providerOptions: TProviderOptions;
+    };
+    /**
+     * Create a voice from a text description and/or reference audio
+     */
+    generateVoice: (options: VoiceGenerationOptions<TProviderOptions>) => Promise<VoiceResult>;
+}
+/**
+ * A VoiceAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyVoiceAdapter = VoiceAdapter<any, any>;
+/**
+ * Abstract base class for voice creation adapters.
+ * Extend this class to implement a voice adapter for a specific provider.
+ *
+ * Generic parameters match VoiceAdapter - all pre-resolved by the provider function.
+ */
+export declare abstract class BaseVoiceAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>> implements VoiceAdapter<TModel, TProviderOptions> {
+    readonly kind: "voice";
+    abstract readonly name: string;
+    readonly model: TModel;
+    '~types': {
+        providerOptions: TProviderOptions;
+    };
+    protected config: VoiceAdapterConfig;
+    constructor(model: TModel, config?: VoiceAdapterConfig);
+    abstract generateVoice(options: VoiceGenerationOptions<TProviderOptions>): Promise<VoiceResult>;
+    protected generateId(): string;
+}

package/dist/esm/activities/generateVoice/adapter.js

@@ -0,0 +1,23 @@
+//#region src/activities/generateVoice/adapter.ts
+/**
+* Abstract base class for voice creation adapters.
+* Extend this class to implement a voice adapter for a specific provider.
+*
+* Generic parameters match VoiceAdapter - all pre-resolved by the provider function.
+*/
+var BaseVoiceAdapter = class {
+	kind = "voice";
+	model;
+	config;
+	constructor(model, config = {}) {
+		this.config = config;
+		this.model = model;
+	}
+	generateId() {
+		return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+	}
+};
+//#endregion
+export { BaseVoiceAdapter };
+
+//# sourceMappingURL=adapter.js.map

package/dist/esm/activities/generateVoice/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/generateVoice/adapter.ts"],"sourcesContent":["import type { VoiceGenerationOptions, VoiceResult } from '../../types'\n\n/**\n * Configuration for voice adapter instances\n */\nexport interface VoiceAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Voice adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'eleven_ttv_v3')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface VoiceAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'voice'\n  /** Adapter name identifier */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  /**\n   * Create a voice from a text description and/or reference audio\n   */\n  generateVoice: (\n    options: VoiceGenerationOptions<TProviderOptions>,\n  ) => Promise<VoiceResult>\n}\n\n/**\n * A VoiceAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyVoiceAdapter = VoiceAdapter<any, any>\n\n/**\n * Abstract base class for voice creation adapters.\n * Extend this class to implement a voice adapter for a specific provider.\n *\n * Generic parameters match VoiceAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseVoiceAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements VoiceAdapter<TModel, TProviderOptions> {\n  readonly kind = 'voice' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  protected config: VoiceAdapterConfig\n\n  constructor(model: TModel, config: VoiceAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract generateVoice(\n    options: VoiceGenerationOptions<TProviderOptions>,\n  ): Promise<VoiceResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA6DA,IAAsB,mBAAtB,MAGoD;CAClD,OAAgB;CAEhB;CAOA;CAEA,YAAY,OAAe,SAA6B,CAAC,GAAG;EAC1D,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAMA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

package/dist/esm/activities/generateVoice/index.d.ts

@@ -0,0 +1,133 @@
+import { DebugOption } from '../../logger/types.js';
+import { GenerationMiddleware } from '../middleware/types.js';
+import { VoiceAdapter } from './adapter.js';
+import { StreamChunk, VoiceResult } from '../../types.js';
+/** The adapter kind this activity handles */
+export declare const kind: "voice";
+/**
+ * Extract provider options from a VoiceAdapter via ~types.
+ */
+export type VoiceProviderOptions<TAdapter> = TAdapter extends {
+    '~types': {
+        providerOptions: infer P extends object;
+    };
+} ? P : object;
+/**
+ * Options for the voice activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The voice adapter type
+ * @template TStream - Whether to stream the output
+ */
+export interface VoiceActivityOptions<TAdapter extends VoiceAdapter<string, VoiceProviderOptions<TAdapter>>, TStream extends boolean = false> {
+    /** The voice adapter to use (must be created with a model) */
+    adapter: TAdapter & {
+        kind: typeof kind;
+    };
+    /**
+     * Text description of the voice to create, for design-capable models
+     * (e.g. `'A warm, gravelly narrator in his sixties'`).
+     */
+    prompt?: string;
+    /**
+     * Reference audio of the speaker to clone, for clone-capable models.
+     * Accepts a base64 string, base64 data URL, File, Blob, or ArrayBuffer.
+     * Remote URLs are not accepted; read the file and pass the bytes.
+     */
+    referenceAudio?: string | File | Blob | ArrayBuffer;
+    /**
+     * Name to store the voice under in the provider's voice library. Check
+     * `saved` on each returned voice to see whether it was actually persisted.
+     */
+    name?: string;
+    /** Human-readable description stored alongside the voice */
+    description?: string;
+    /** Provider-specific options for voice creation */
+    modelOptions?: VoiceProviderOptions<TAdapter>;
+    /**
+     * Whether to stream the generation result.
+     * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+     * When false or not provided, returns a Promise<VoiceResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
+    /**
+     * Enable debug logging. Pass `true` to enable all categories, `false` to
+     * silence everything including errors, or a `DebugConfig` object for granular
+     * control and/or a custom `Logger`.
+     */
+    debug?: DebugOption;
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
+    /** Stable conversation/thread id for correlating this run when persisted. */
+    threadId?: string;
+    /** Stable run id for correlating this run when persisted. */
+    runId?: string;
+    /**
+     * Maximum duration of this activity invocation in milliseconds.
+     * No SDK-wide default — choose a value suitable for the provider and job.
+     * Composed with {@link abortSignal}; the first abort wins.
+     */
+    timeout?: number;
+    /**
+     * Caller cancellation signal (request disconnects, job/runtime cancellation).
+     * Composed with {@link timeout} into an effective signal forwarded to the
+     * adapter. Request-specific — not stored on global provider client config.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result type for the voice activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<VoiceResult>
+ */
+export type VoiceActivityResult<TStream extends boolean = false> = TStream extends true ? AsyncIterable<StreamChunk> : Promise<VoiceResult>;
+/**
+ * Voice activity - creates a reusable voice.
+ *
+ * Providers create voices in one of two ways, and some support both: design a
+ * new voice from a text description, or clone one from reference audio. Either
+ * way the result carries voice ids you pass back to `generateSpeech()`.
+ *
+ * @example Design a voice from a description
+ * ```ts
+ * import { generateVoice, generateSpeech } from '@tanstack/ai'
+ * import { elevenlabsVoiceDesign, elevenlabsSpeech } from '@tanstack/ai-elevenlabs'
+ *
+ * const designed = await generateVoice({
+ *   adapter: elevenlabsVoiceDesign('eleven_ttv_v3'),
+ *   prompt: 'A warm, gravelly narrator in his sixties with a slight Irish lilt',
+ * })
+ *
+ * const [preview] = designed.voices
+ * if (!preview) throw new Error('No voice candidates returned')
+ *
+ * const speech = await generateSpeech({
+ *   adapter: elevenlabsSpeech('eleven_v3'),
+ *   text: 'Once upon a time...',
+ *   voice: preview.voiceId,
+ * })
+ * ```
+ *
+ * @example Save the voice to the provider's library
+ * ```ts
+ * const saved = await generateVoice({
+ *   adapter: elevenlabsVoiceDesign('eleven_ttv_v3'),
+ *   prompt: 'A bright, upbeat product demo host',
+ *   name: 'Demo Host',
+ *   description: 'Bright, upbeat, mid-30s',
+ * })
+ * ```
+ */
+export declare function generateVoice<TAdapter extends VoiceAdapter<string, VoiceProviderOptions<TAdapter>>, TStream extends boolean = false>(options: VoiceActivityOptions<TAdapter, TStream>): VoiceActivityResult<TStream>;
+/**
+ * Create typed options for the generateVoice() function without executing.
+ */
+export declare function createVoiceOptions<TAdapter extends VoiceAdapter<string, VoiceProviderOptions<TAdapter>>, TStream extends boolean = false>(options: VoiceActivityOptions<TAdapter, TStream>): VoiceActivityOptions<TAdapter, TStream>;
+export type { VoiceAdapter, VoiceAdapterConfig, AnyVoiceAdapter, } from './adapter.js';
+export { BaseVoiceAdapter } from './adapter.js';