@tanstack/ai 0.12.0 → 0.14.0

package/src/activities/error-payload.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared error-narrowing helper for activities that convert thrown values
+ * into structured `RUN_ERROR` events.
+ *
+ * Accepts Error instances, objects with string-ish `message`/`code`, or bare
+ * strings; always returns a shape safe to serialize. Never leaks the full
+ * error object (which may carry request/response state from an SDK).
+ */
+export function toRunErrorPayload(
+  error: unknown,
+  fallbackMessage = 'Unknown error occurred',
+): { message: string; code: string | undefined } {
+  if (error instanceof Error) {
+    const codeField = (error as Error & { code?: unknown }).code
+    return {
+      message: error.message || fallbackMessage,
+      code: typeof codeField === 'string' ? codeField : undefined,
+    }
+  }
+  if (typeof error === 'object' && error !== null) {
+    const messageField = (error as { message?: unknown }).message
+    const codeField = (error as { code?: unknown }).code
+    return {
+      message:
+        typeof messageField === 'string' && messageField.length > 0
+          ? messageField
+          : fallbackMessage,
+      code: typeof codeField === 'string' ? codeField : undefined,
+    }
+  }
+  if (typeof error === 'string' && error.length > 0) {
+    return { message: error, code: undefined }
+  }
+  return { message: fallbackMessage, code: undefined }
+}

package/src/activities/generateAudio/adapter.ts

@@ -0,0 +1,89 @@
+import type { AudioGenerationOptions, AudioGenerationResult } from '../../types'
+
+/**
+ * Configuration for audio generation adapter instances
+ */
+export interface AudioAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Audio generation 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., 'fal-ai/diffrhythm')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface AudioAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'audio'
+  /** 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
+  }
+
+  /**
+   * Generate audio from a text prompt
+   */
+  generateAudio: (
+    options: AudioGenerationOptions<TProviderOptions>,
+  ) => Promise<AudioGenerationResult>
+}
+
+/**
+ * An AudioAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyAudioAdapter = AudioAdapter<any, any>
+
+/**
+ * Abstract base class for audio generation adapters.
+ * Extend this class to implement an audio adapter for a specific provider.
+ *
+ * Generic parameters match AudioAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseAudioAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements AudioAdapter<TModel, TProviderOptions> {
+  readonly kind = 'audio' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: AudioAdapterConfig
+
+  constructor(model: TModel, config: AudioAdapterConfig = {}) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateAudio(
+    options: AudioGenerationOptions<TProviderOptions>,
+  ): Promise<AudioGenerationResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateAudio/index.ts

@@ -0,0 +1,224 @@
+/**
+ * Audio Generation Activity
+ *
+ * Generates audio (music, sound effects, etc.) from text prompts.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import { aiEventClient } from '@tanstack/ai-event-client'
+import { streamGenerationResult } from '../stream-generation-result.js'
+import { resolveDebugOption } from '../../logger/resolve'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
+import type { AudioAdapter } from './adapter'
+import type { AudioGenerationResult, StreamChunk } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'audio' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract provider options from an AudioAdapter via ~types.
+ */
+export type AudioProviderOptions<TAdapter> =
+  TAdapter extends AudioAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the audio generation activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The audio adapter type
+ * @template TStream - Whether to stream the output
+ */
+export interface AudioActivityOptions<
+  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,
+  TStream extends boolean = false,
+> {
+  /** The audio adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** Text description of the desired audio */
+  prompt: string
+  /** Desired duration in seconds */
+  duration?: number
+  /** Provider-specific options for audio generation */
+  modelOptions?: AudioProviderOptions<TAdapter>
+  /**
+   * Whether to stream the generation result.
+   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+   * When false or not provided, returns a Promise<AudioGenerationResult>.
+   *
+   * @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
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/**
+ * Result type for the audio generation activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<AudioGenerationResult>
+ */
+export type AudioActivityResult<TStream extends boolean = false> =
+  TStream extends true
+    ? AsyncIterable<StreamChunk>
+    : Promise<AudioGenerationResult>
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Audio generation activity - generates audio from text prompts.
+ *
+ * Uses AI models to create music, sound effects, and other audio content.
+ *
+ * @example Generate music from a prompt
+ * ```ts
+ * import { generateAudio } from '@tanstack/ai'
+ * import { falAudio } from '@tanstack/ai-fal'
+ *
+ * const result = await generateAudio({
+ *   adapter: falAudio('fal-ai/diffrhythm'),
+ *   prompt: 'An upbeat electronic track with synths',
+ *   duration: 10
+ * })
+ *
+ * console.log(result.audio.url) // URL to generated audio
+ * ```
+ */
+export function generateAudio<
+  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,
+  TStream extends boolean = false,
+>(
+  options: AudioActivityOptions<TAdapter, TStream>,
+): AudioActivityResult<TStream> {
+  if (options.stream) {
+    return streamGenerationResult(() =>
+      runGenerateAudio(options),
+    ) as AudioActivityResult<TStream>
+  }
+  return runGenerateAudio(options) as AudioActivityResult<TStream>
+}
+
+/**
+ * Run the core audio generation logic (non-streaming).
+ */
+async function runGenerateAudio<
+  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,
+>(
+  options: AudioActivityOptions<TAdapter, boolean>,
+): Promise<AudioGenerationResult> {
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
+  const model = adapter.model
+  const requestId = createId('audio')
+  const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const providerName =
+    (adapter as { name?: string; provider?: string }).provider ??
+    (adapter as { name?: string }).name ??
+    'unknown'
+
+  aiEventClient.emit('audio:request:started', {
+    requestId,
+    provider: adapter.name,
+    model,
+    prompt: rest.prompt,
+    duration: rest.duration,
+    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+    timestamp: startTime,
+  })
+
+  logger.request(`activity=generateAudio provider=${providerName}`, {
+    provider: providerName,
+    model,
+  })
+
+  try {
+    const result = await adapter.generateAudio({ ...rest, model, logger })
+    const elapsedMs = Date.now() - startTime
+
+    aiEventClient.emit('audio:request:completed', {
+      requestId,
+      provider: adapter.name,
+      model,
+      audio: result.audio,
+      duration: elapsedMs,
+      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      timestamp: Date.now(),
+    })
+
+    logger.output(`activity=generateAudio provider=${providerName}`, {
+      contentType: result.audio.contentType,
+      audioDuration: result.audio.duration,
+    })
+
+    return result
+  } catch (error) {
+    const elapsedMs = Date.now() - startTime
+    const err = error as Error
+    aiEventClient.emit('audio:request:error', {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration: elapsedMs,
+      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      timestamp: Date.now(),
+    })
+    logger.errors('generateAudio activity failed', {
+      error,
+      source: 'generateAudio',
+    })
+    throw error
+  }
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateAudio() function without executing.
+ */
+export function createAudioOptions<
+  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,
+  TStream extends boolean = false,
+>(
+  options: AudioActivityOptions<TAdapter, TStream>,
+): AudioActivityOptions<TAdapter, TStream> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  AudioAdapter,
+  AudioAdapterConfig,
+  AnyAudioAdapter,
+} from './adapter'
+export { BaseAudioAdapter } from './adapter'

package/src/activities/generateImage/adapter.ts

@@ -96,7 +96,7 @@ export abstract class BaseImageAdapter<
 
   protected config: ImageAdapterConfig
 
-  constructor(config: ImageAdapterConfig = {}, model: TModel) {
+  constructor(model: TModel, config: ImageAdapterConfig = {}) {
     this.config = config
     this.model = model
   }

package/src/activities/generateImage/index.ts

@@ -7,6 +7,9 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import { resolveDebugOption } from '../../logger/resolve'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
 import type { ImageAdapter } from './adapter'
 import type { ImageGenerationResult, StreamChunk } from '../../types'
 
@@ -83,6 +86,12 @@ export type ImageActivityOptions<
    * @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
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
   ? {
       /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
@@ -188,10 +197,11 @@ async function runGenerateImage<
 >(
   options: ImageActivityOptions<TAdapter, boolean>,
 ): Promise<ImageGenerationResult> {
-  const { adapter, stream: _stream, ...rest } = options
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
   const model = adapter.model
   const requestId = createId('image')
   const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
 
   aiEventClient.emit('image:request:started', {
     requestId,
@@ -204,7 +214,13 @@ async function runGenerateImage<
     timestamp: startTime,
   })
 
-  return adapter.generateImages({ ...rest, model }).then((result) => {
+  logger.request(`activity=generateImage provider=${adapter.name}`, {
+    provider: adapter.name,
+    model,
+  })
+
+  try {
+    const result = await adapter.generateImages({ ...rest, model, logger })
     const duration = Date.now() - startTime
 
     aiEventClient.emit('image:request:completed', {
@@ -230,8 +246,18 @@ async function runGenerateImage<
       })
     }
 
+    logger.output(`activity=generateImage count=${result.images.length}`, {
+      count: result.images.length,
+    })
+
     return result
-  })
+  } catch (error) {
+    logger.errors('generateImage activity failed', {
+      error,
+      source: 'generateImage',
+    })
+    throw error
+  }
 }
 
 // ===========================

package/src/activities/generateSpeech/adapter.ts

@@ -72,7 +72,7 @@ export abstract class BaseTTSAdapter<
 
   protected config: TTSAdapterConfig
 
-  constructor(config: TTSAdapterConfig = {}, model: TModel) {
+  constructor(model: TModel, config: TTSAdapterConfig = {}) {
     this.config = config
     this.model = model
   }

package/src/activities/generateSpeech/index.ts

@@ -7,6 +7,9 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import { resolveDebugOption } from '../../logger/resolve'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 
@@ -41,7 +44,7 @@ export type TTSProviderOptions<TAdapter> =
  * @template TStream - Whether to stream the output
  */
 export interface TTSActivityOptions<
-  TAdapter extends TTSAdapter<string, object>,
+  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
   TStream extends boolean = false,
 > {
   /** The TTS adapter to use (must be created with a model) */
@@ -64,6 +67,12 @@ export interface TTSActivityOptions<
    * @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
 }
 
 // ===========================
@@ -117,7 +126,7 @@ function createId(prefix: string): string {
  * ```
  */
 export function generateSpeech<
-  TAdapter extends TTSAdapter<string, object>,
+  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
   TStream extends boolean = false,
 >(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {
   if (options.stream) {
@@ -131,13 +140,18 @@ export function generateSpeech<
 /**
  * Run the core TTS generation logic (non-streaming).
  */
-async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
-  options: TTSActivityOptions<TAdapter, boolean>,
-): Promise<TTSResult> {
-  const { adapter, stream: _stream, ...rest } = options
+async function runGenerateSpeech<
+  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
+>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {
+  const { adapter, stream: _stream, debug: _debug, ...rest } = options
   const model = adapter.model
   const requestId = createId('speech')
   const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const providerName =
+    (adapter as { name?: string; provider?: string }).provider ??
+    (adapter as { name?: string }).name ??
+    'unknown'
 
   aiEventClient.emit('speech:request:started', {
     requestId,
@@ -151,7 +165,13 @@ async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
     timestamp: startTime,
   })
 
-  return adapter.generateSpeech({ ...rest, model }).then((result) => {
+  logger.request(`activity=generateSpeech provider=${providerName}`, {
+    provider: providerName,
+    model,
+  })
+
+  try {
+    const result = await adapter.generateSpeech({ ...rest, model, logger })
     const duration = Date.now() - startTime
 
     aiEventClient.emit('speech:request:completed', {
@@ -167,8 +187,30 @@ async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
       timestamp: Date.now(),
     })
 
+    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
+      bytes: result.audio.length,
+      contentType: result.contentType,
+    })
+
     return result
-  })
+  } catch (error) {
+    const duration = Date.now() - startTime
+    const err = error as Error
+    aiEventClient.emit('speech:request:error', {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration,
+      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      timestamp: Date.now(),
+    })
+    logger.errors('generateSpeech activity failed', {
+      error,
+      source: 'generateSpeech',
+    })
+    throw error
+  }
 }
 
 // ===========================
@@ -179,7 +221,7 @@ async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
  * Create typed options for the generateSpeech() function without executing.
  */
 export function createSpeechOptions<
-  TAdapter extends TTSAdapter<string, object>,
+  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
   TStream extends boolean = false,
 >(
   options: TTSActivityOptions<TAdapter, TStream>,

package/src/activities/generateTranscription/adapter.ts

@@ -74,7 +74,7 @@ export abstract class BaseTranscriptionAdapter<
 
   protected config: TranscriptionAdapterConfig
 
-  constructor(config: TranscriptionAdapterConfig = {}, model: TModel) {
+  constructor(model: TModel, config: TranscriptionAdapterConfig = {}) {
     this.config = config
     this.model = model
   }