/**
 * TTS Provider Interface
 *
 * Defines the contract for text-to-speech provider implementations.
 * All TTS providers (e.g., Kokoro, Chatterbox, Piper/OpenedAI) must implement this interface.
 *
 * Issue #389
 */

import type { SynthesizeOptions, SynthesisResult, VoiceInfo, SpeechTier } from "./speech-types";

/**
 * Interface for text-to-speech providers.
 *
 * Implementations wrap an OpenAI-compatible API endpoint for speech synthesis.
 * Each provider is associated with a SpeechTier (default, premium, fallback).
 *
 * @example
 * ```typescript
 * class KokoroProvider implements ITTSProvider {
 *   readonly name = "kokoro";
 *   readonly tier = "default";
 *
 *   async synthesize(text: string, options?: SynthesizeOptions): Promise<SynthesisResult> {
 *     // Call Kokoro API via OpenAI SDK
 *   }
 *
 *   async listVoices(): Promise<VoiceInfo[]> {
 *     // Return available voices
 *   }
 *
 *   async isHealthy(): Promise<boolean> {
 *     // Check endpoint health
 *   }
 * }
 * ```
 */
export interface ITTSProvider {
  /** Provider name for logging and identification */
  readonly name: string;

  /** Tier this provider serves (default, premium, fallback) */
  readonly tier: SpeechTier;

  /**
   * Synthesize text to audio.
   *
   * @param text - Text to convert to speech
   * @param options - Optional synthesis parameters (voice, format, speed)
   * @returns Synthesis result with audio buffer and metadata
   * @throws {Error} If synthesis fails
   */
  synthesize(text: string, options?: SynthesizeOptions): Promise<SynthesisResult>;

  /**
   * List available voices for this provider.
   *
   * @returns Array of voice information objects
   */
  listVoices(): Promise<VoiceInfo[]>;

  /**
   * Check if the provider is healthy and available.
   *
   * @returns true if the provider endpoint is reachable and ready
   */
  isHealthy(): Promise<boolean>;
}
