/**
 * STT Provider Interface
 *
 * Defines the contract for speech-to-text provider implementations.
 * All STT providers (e.g., Speaches/faster-whisper) must implement this interface.
 *
 * Issue #389
 */

import type { TranscribeOptions, TranscriptionResult } from "./speech-types";

/**
 * Interface for speech-to-text providers.
 *
 * Implementations wrap an OpenAI-compatible API endpoint for transcription.
 *
 * @example
 * ```typescript
 * class SpeachesProvider implements ISTTProvider {
 *   readonly name = "speaches";
 *
 *   async transcribe(audio: Buffer, options?: TranscribeOptions): Promise<TranscriptionResult> {
 *     // Call speaches API via OpenAI SDK
 *   }
 *
 *   async isHealthy(): Promise<boolean> {
 *     // Check endpoint health
 *   }
 * }
 * ```
 */
export interface ISTTProvider {
  /** Provider name for logging and identification */
  readonly name: string;

  /**
   * Transcribe audio data to text.
   *
   * @param audio - Raw audio data as a Buffer
   * @param options - Optional transcription parameters
   * @returns Transcription result with text and metadata
   * @throws {Error} If transcription fails
   */
  transcribe(audio: Buffer, options?: TranscribeOptions): Promise<TranscriptionResult>;

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