@framers/agentos 0.1.110 → 0.1.111

package/dist/speech/providers/AssemblyAISTTProvider.d.ts

@@ -1,48 +1,148 @@
 import type { SpeechAudioInput, SpeechToTextProvider, SpeechTranscriptionOptions, SpeechTranscriptionResult } from '../types.js';
-/** Configuration for the AssemblyAISTTProvider. */
+/**
+ * Configuration for the {@link AssemblyAISTTProvider}.
+ *
+ * @see {@link AssemblyAISTTProvider} for usage examples
+ */
 export interface AssemblyAISTTProviderConfig {
-    /** AssemblyAI API key. */
+    /**
+     * AssemblyAI API key used for authentication.
+     * Sent as the `Authorization` header value (without a prefix like "Bearer").
+     * Obtain from https://www.assemblyai.com/dashboard/account
+     */
     apiKey: string;
     /**
-     * Custom fetch implementation, useful for testing.
-     * Defaults to the global `fetch`.
+     * Custom fetch implementation for dependency injection in tests.
+     * When omitted, the global `fetch` is used.
+     * @default globalThis.fetch
      */
     fetchImpl?: typeof fetch;
 }
 /**
  * Speech-to-text provider that uses the AssemblyAI async transcription API.
  *
- * The three-step workflow is:
- * 1. **Upload** – POST the raw audio to `/v2/upload` to obtain an upload URL.
- * 2. **Submit** – POST to `/v2/transcript` with the upload URL to start processing.
- * 3. **Poll** – GET `/v2/transcript/:id` every second until `status` is
- *    `completed` or `error`, or until the optional timeout elapses.
+ * ## Three-Step Workflow
+ *
+ * AssemblyAI uses an asynchronous transcription pipeline that requires three
+ * sequential HTTP requests:
+ *
+ * 1. **Upload** — `POST /v2/upload` sends the raw audio bytes to AssemblyAI's
+ *    CDN and returns an `upload_url`. This step is necessary because the
+ *    transcript endpoint accepts URLs, not raw audio.
+ *
+ * 2. **Submit** — `POST /v2/transcript` creates a transcription job referencing
+ *    the upload URL. Returns a transcript `id` used for polling. Optional
+ *    features like `speaker_labels` are enabled in this request's JSON body.
+ *
+ * 3. **Poll** — `GET /v2/transcript/:id` is called every {@link POLL_INTERVAL_MS}
+ *    (1 second) until the transcript `status` transitions to `'completed'` or
+ *    `'error'`. The polling loop is bounded by {@link DEFAULT_TIMEOUT_MS}
+ *    (120 seconds) to prevent indefinite waiting.
+ *
+ * ## AbortController Usage
+ *
+ * An optional `AbortSignal` can be passed via
+ * `options.providerSpecificOptions.signal` to cancel the transcription at any
+ * point. The signal is forwarded to all three fetch calls and also checked at
+ * the top of each polling iteration. When aborted, an error is thrown
+ * immediately without waiting for the current fetch to complete.
+ *
+ * ## Error Handling
+ *
+ * - Non-2xx responses at any step throw an `Error` with the HTTP status and body.
+ * - `status === 'error'` on the transcript throws with AssemblyAI's error message.
+ * - Timeout expiry throws with the transcript ID for manual inspection.
+ * - Aborted signals throw with a descriptive cancellation message.
+ *
+ * @see {@link AssemblyAISTTProviderConfig} for configuration options
+ * @see {@link AssemblyAITranscript} for the polling response shape
  *
  * @example
  * ```ts
- * const provider = new AssemblyAISTTProvider({ apiKey: process.env.ASSEMBLYAI_API_KEY! });
- * const result = await provider.transcribe({ data: audioBuffer }, { enableSpeakerDiarization: true });
- * console.log(result.text);
+ * const provider = new AssemblyAISTTProvider({
+ *   apiKey: process.env.ASSEMBLYAI_API_KEY!,
+ * });
+ *
+ * // Basic transcription
+ * const result = await provider.transcribe({ data: audioBuffer });
+ *
+ * // With diarization and cancellation support
+ * const controller = new AbortController();
+ * const result = await provider.transcribe(
+ *   { data: audioBuffer },
+ *   {
+ *     enableSpeakerDiarization: true,
+ *     providerSpecificOptions: { signal: controller.signal },
+ *   },
+ * );
  * ```
  */
 export declare class AssemblyAISTTProvider implements SpeechToTextProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "assemblyai";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "AssemblyAI";
+    /**
+     * Streaming is not supported by this provider's async pipeline.
+     * AssemblyAI does offer a separate real-time streaming API via WebSocket,
+     * but that would be a different provider implementation.
+     */
     readonly supportsStreaming = false;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /**
+     * Creates a new AssemblyAISTTProvider.
+     *
+     * @param config - Provider configuration including the API key.
+     *
+     * @example
+     * ```ts
+     * const provider = new AssemblyAISTTProvider({
+     *   apiKey: 'your-assemblyai-api-key',
+     * });
+     * ```
+     */
     constructor(config: AssemblyAISTTProviderConfig);
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'AssemblyAI'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'AssemblyAI'
+     * ```
+     */
     getProviderName(): string;
     /**
-     * Transcribes an audio buffer via the AssemblyAI async pipeline.
+     * Transcribes an audio buffer via the AssemblyAI three-step async pipeline:
+     * upload, submit, and poll.
      *
-     * @param audio - Raw audio data and associated metadata.
+     * @param audio - Raw audio data and associated metadata. The `data` buffer
+     *   is uploaded to AssemblyAI's CDN in step 1.
      * @param options - Optional transcription settings. Pass
-     *   `providerSpecificOptions.signal` (an {@link AbortSignal}) to cancel.
-     * @returns A promise resolving to the normalised transcription result.
-     * @throws When the API returns a non-2xx status, when transcription fails,
-     *   or when the 120-second timeout is exceeded.
+     *   `providerSpecificOptions.signal` (an {@link AbortSignal}) to cancel
+     *   at any point in the pipeline.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the upload API returns a non-2xx status.
+     * @throws {Error} When the transcript submit API returns a non-2xx status.
+     * @throws {Error} When the polling API returns a non-2xx status.
+     * @throws {Error} When the transcript status becomes `'error'` (includes
+     *   AssemblyAI's error message, e.g. "Audio file could not be decoded").
+     * @throws {Error} When the 120-second timeout is exceeded (includes the
+     *   transcript ID for manual inspection via the AssemblyAI dashboard).
+     * @throws {Error} When the caller's AbortSignal is triggered.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: wavBuffer, mimeType: 'audio/wav' },
+     *   { enableSpeakerDiarization: true, language: 'en' },
+     * );
+     * console.log(result.text);
+     * console.log(result.segments?.map(s => `[${s.speaker}] ${s.text}`));
+     * ```
      */
     transcribe(audio: SpeechAudioInput, options?: SpeechTranscriptionOptions): Promise<SpeechTranscriptionResult>;
 }

package/dist/speech/providers/AssemblyAISTTProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssemblyAISTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AssemblyAISTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB,mDAAmD;AACnD,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAsDD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,YAAW,oBAAoB;IAOpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,SAAgB,EAAE,gBAAgB;IAClC,SAAgB,WAAW,gBAAgB;IAC3C,SAAgB,iBAAiB,SAAS;IAE1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,2BAA2B;IAIhE,gDAAgD;IAChD,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;OASG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAqGtC"}
+{"version":3,"file":"AssemblyAISTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AssemblyAISTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAmHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBAAa,qBAAsB,YAAW,oBAAoB;IA6BpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IA5BnC,uEAAuE;IACvE,SAAgB,EAAE,gBAAgB;IAElC,sDAAsD;IACtD,SAAgB,WAAW,gBAAgB;IAE3C;;;;OAIG;IACH,SAAgB,iBAAiB,SAAS;IAE1C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;;;;;;;;;OAWG;gBAC0B,MAAM,EAAE,2BAA2B;IAIhE;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAkHtC"}

package/dist/speech/providers/AssemblyAISTTProvider.js

@@ -1,20 +1,45 @@
+/** Base URL for all AssemblyAI API v2 endpoints. */
 const ASSEMBLYAI_BASE = 'https://api.assemblyai.com/v2';
-/** Maximum time (ms) to wait for a transcript before rejecting. */
+/**
+ * Maximum time (in milliseconds) to wait for a transcript to complete
+ * before throwing a timeout error.
+ *
+ * 120 seconds is generous — most transcripts complete within 10–30 seconds.
+ * The timeout exists to prevent indefinite polling in case of AssemblyAI
+ * service degradation or stuck transcripts.
+ */
 const DEFAULT_TIMEOUT_MS = 120000;
-/** Polling interval (ms) between transcript status checks. */
+/**
+ * Polling interval (in milliseconds) between transcript status checks.
+ *
+ * 1 second strikes a balance between responsiveness and API rate limiting.
+ * AssemblyAI does not document a rate limit for polling, but 1-second
+ * intervals are considered polite and are used in their official examples.
+ */
 const POLL_INTERVAL_MS = 1000;
 /**
  * Maps AssemblyAI word objects to {@link SpeechTranscriptionSegment} entries.
  *
  * Each word becomes its own segment so that per-word timing and speaker
- * attribution are preserved in the normalised result.
+ * attribution are preserved in the normalized result.
+ *
+ * **Important:** AssemblyAI returns word timings in milliseconds, so we
+ * divide by 1000 to convert to seconds for consistency with our normalized
+ * {@link SpeechTranscriptionSegment} interface (which uses seconds).
+ *
+ * @param words - Array of AssemblyAI word objects with millisecond timings.
+ * @returns An array of normalized transcription segments with second-based timings.
+ *
+ * @see {@link AssemblyAIWord} for the input shape
+ * @see {@link SpeechTranscriptionSegment} for the output shape
  */
 function wordsToSegments(words) {
     return words.map((w) => ({
         text: w.text,
-        startTime: w.start / 1000, // AssemblyAI returns milliseconds
+        startTime: w.start / 1000, // AssemblyAI returns milliseconds -> convert to seconds
         endTime: w.end / 1000,
         confidence: w.confidence,
+        // Convert null speaker labels to undefined for type consistency
         speaker: w.speaker ?? undefined,
         words: [
             {
@@ -29,45 +54,139 @@ function wordsToSegments(words) {
 /**
  * Speech-to-text provider that uses the AssemblyAI async transcription API.
  *
- * The three-step workflow is:
- * 1. **Upload** – POST the raw audio to `/v2/upload` to obtain an upload URL.
- * 2. **Submit** – POST to `/v2/transcript` with the upload URL to start processing.
- * 3. **Poll** – GET `/v2/transcript/:id` every second until `status` is
- *    `completed` or `error`, or until the optional timeout elapses.
+ * ## Three-Step Workflow
+ *
+ * AssemblyAI uses an asynchronous transcription pipeline that requires three
+ * sequential HTTP requests:
+ *
+ * 1. **Upload** — `POST /v2/upload` sends the raw audio bytes to AssemblyAI's
+ *    CDN and returns an `upload_url`. This step is necessary because the
+ *    transcript endpoint accepts URLs, not raw audio.
+ *
+ * 2. **Submit** — `POST /v2/transcript` creates a transcription job referencing
+ *    the upload URL. Returns a transcript `id` used for polling. Optional
+ *    features like `speaker_labels` are enabled in this request's JSON body.
+ *
+ * 3. **Poll** — `GET /v2/transcript/:id` is called every {@link POLL_INTERVAL_MS}
+ *    (1 second) until the transcript `status` transitions to `'completed'` or
+ *    `'error'`. The polling loop is bounded by {@link DEFAULT_TIMEOUT_MS}
+ *    (120 seconds) to prevent indefinite waiting.
+ *
+ * ## AbortController Usage
+ *
+ * An optional `AbortSignal` can be passed via
+ * `options.providerSpecificOptions.signal` to cancel the transcription at any
+ * point. The signal is forwarded to all three fetch calls and also checked at
+ * the top of each polling iteration. When aborted, an error is thrown
+ * immediately without waiting for the current fetch to complete.
+ *
+ * ## Error Handling
+ *
+ * - Non-2xx responses at any step throw an `Error` with the HTTP status and body.
+ * - `status === 'error'` on the transcript throws with AssemblyAI's error message.
+ * - Timeout expiry throws with the transcript ID for manual inspection.
+ * - Aborted signals throw with a descriptive cancellation message.
+ *
+ * @see {@link AssemblyAISTTProviderConfig} for configuration options
+ * @see {@link AssemblyAITranscript} for the polling response shape
  *
  * @example
  * ```ts
- * const provider = new AssemblyAISTTProvider({ apiKey: process.env.ASSEMBLYAI_API_KEY! });
- * const result = await provider.transcribe({ data: audioBuffer }, { enableSpeakerDiarization: true });
- * console.log(result.text);
+ * const provider = new AssemblyAISTTProvider({
+ *   apiKey: process.env.ASSEMBLYAI_API_KEY!,
+ * });
+ *
+ * // Basic transcription
+ * const result = await provider.transcribe({ data: audioBuffer });
+ *
+ * // With diarization and cancellation support
+ * const controller = new AbortController();
+ * const result = await provider.transcribe(
+ *   { data: audioBuffer },
+ *   {
+ *     enableSpeakerDiarization: true,
+ *     providerSpecificOptions: { signal: controller.signal },
+ *   },
+ * );
  * ```
  */
 export class AssemblyAISTTProvider {
+    /**
+     * Creates a new AssemblyAISTTProvider.
+     *
+     * @param config - Provider configuration including the API key.
+     *
+     * @example
+     * ```ts
+     * const provider = new AssemblyAISTTProvider({
+     *   apiKey: 'your-assemblyai-api-key',
+     * });
+     * ```
+     */
     constructor(config) {
         this.config = config;
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'assemblyai';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'AssemblyAI';
+        /**
+         * Streaming is not supported by this provider's async pipeline.
+         * AssemblyAI does offer a separate real-time streaming API via WebSocket,
+         * but that would be a different provider implementation.
+         */
         this.supportsStreaming = false;
         this.fetchImpl = config.fetchImpl ?? fetch;
     }
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'AssemblyAI'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'AssemblyAI'
+     * ```
+     */
     getProviderName() {
         return this.displayName;
     }
     /**
-     * Transcribes an audio buffer via the AssemblyAI async pipeline.
+     * Transcribes an audio buffer via the AssemblyAI three-step async pipeline:
+     * upload, submit, and poll.
      *
-     * @param audio - Raw audio data and associated metadata.
+     * @param audio - Raw audio data and associated metadata. The `data` buffer
+     *   is uploaded to AssemblyAI's CDN in step 1.
      * @param options - Optional transcription settings. Pass
-     *   `providerSpecificOptions.signal` (an {@link AbortSignal}) to cancel.
-     * @returns A promise resolving to the normalised transcription result.
-     * @throws When the API returns a non-2xx status, when transcription fails,
-     *   or when the 120-second timeout is exceeded.
+     *   `providerSpecificOptions.signal` (an {@link AbortSignal}) to cancel
+     *   at any point in the pipeline.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the upload API returns a non-2xx status.
+     * @throws {Error} When the transcript submit API returns a non-2xx status.
+     * @throws {Error} When the polling API returns a non-2xx status.
+     * @throws {Error} When the transcript status becomes `'error'` (includes
+     *   AssemblyAI's error message, e.g. "Audio file could not be decoded").
+     * @throws {Error} When the 120-second timeout is exceeded (includes the
+     *   transcript ID for manual inspection via the AssemblyAI dashboard).
+     * @throws {Error} When the caller's AbortSignal is triggered.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: wavBuffer, mimeType: 'audio/wav' },
+     *   { enableSpeakerDiarization: true, language: 'en' },
+     * );
+     * console.log(result.text);
+     * console.log(result.segments?.map(s => `[${s.speaker}] ${s.text}`));
+     * ```
      */
     async transcribe(audio, options = {}) {
+        // Extract the optional AbortSignal for cancellation support.
+        // Cast is safe because we document the expected type in the JSDoc.
         const signal = options.providerSpecificOptions?.signal;
         const timeoutMs = DEFAULT_TIMEOUT_MS;
-        // ── Step 1: Upload audio ────────────────────────────────────────────────
+        // ── Step 1: Upload audio to AssemblyAI's CDN ──────────────────────────
+        // The upload endpoint returns an `upload_url` that the transcript
+        // endpoint can reference. This avoids sending raw bytes to /transcript.
         const uploadResponse = await this.fetchImpl(`${ASSEMBLYAI_BASE}/upload`, {
             method: 'POST',
             headers: {
@@ -82,7 +201,9 @@ export class AssemblyAISTTProvider {
             throw new Error(`AssemblyAI upload failed (${uploadResponse.status}): ${msg}`);
         }
         const { upload_url } = (await uploadResponse.json());
-        // ── Step 2: Submit transcript request ───────────────────────────────────
+        // ── Step 2: Submit transcript request ─────────────────────────────────
+        // Create a transcription job with the uploaded audio URL and any
+        // optional features like speaker diarization.
         const submitPayload = {
             audio_url: upload_url,
             speaker_labels: options.enableSpeakerDiarization ?? false,
@@ -103,12 +224,16 @@ export class AssemblyAISTTProvider {
             throw new Error(`AssemblyAI transcript submit failed (${submitResponse.status}): ${msg}`);
         }
         const { id } = (await submitResponse.json());
-        // ── Step 3: Poll until completed ────────────────────────────────────────
+        // ── Step 3: Poll until completed or error ─────────────────────────────
+        // Check the transcript status every POLL_INTERVAL_MS until it reaches
+        // a terminal state or the timeout is exceeded.
         const deadline = Date.now() + timeoutMs;
         while (true) {
+            // Check for caller-initiated cancellation before each poll
             if (signal?.aborted) {
                 throw new Error('AssemblyAI transcription aborted by caller signal');
             }
+            // Check for timeout before each poll to avoid one extra unnecessary request
             if (Date.now() >= deadline) {
                 throw new Error(`AssemblyAI transcription timed out after ${timeoutMs / 1000}s (transcript id: ${id})`);
             }
@@ -121,9 +246,11 @@ export class AssemblyAISTTProvider {
                 throw new Error(`AssemblyAI poll failed (${pollResponse.status}): ${msg}`);
             }
             const transcript = (await pollResponse.json());
+            // Terminal state: transcription failed on AssemblyAI's side
             if (transcript.status === 'error') {
                 throw new Error(`AssemblyAI transcription error: ${transcript.error ?? 'unknown error'}`);
             }
+            // Terminal state: transcription succeeded — normalize and return
             if (transcript.status === 'completed') {
                 const text = transcript.text ?? '';
                 const durationSeconds = transcript.audio_duration ?? audio.durationSeconds;
@@ -133,17 +260,18 @@ export class AssemblyAISTTProvider {
                     language: transcript.language_code ?? options.language,
                     durationSeconds,
                     confidence: transcript.confidence ?? undefined,
-                    cost: 0,
+                    cost: 0, // Cost tracking is handled at a higher layer
                     segments: words.length > 0 ? wordsToSegments(words) : undefined,
                     providerResponse: transcript,
-                    isFinal: true,
+                    isFinal: true, // Async API always returns final results
                     usage: {
                         durationMinutes: (durationSeconds ?? 0) / 60,
                         modelUsed: 'assemblyai',
                     },
                 };
             }
-            // Still queued or processing — wait before polling again.
+            // Non-terminal state ('queued' or 'processing') — wait before polling again.
+            // Using setTimeout instead of a busy loop to yield the event loop.
             await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
         }
     }

package/dist/speech/providers/AssemblyAISTTProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AssemblyAISTTProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/AssemblyAISTTProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AssemblyAISTTProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/AssemblyAISTTProvider.ts"],"names":[],"mappings":"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"}

package/dist/speech/providers/AzureSpeechSTTProvider.d.ts

@@ -1,47 +1,151 @@
 import type { SpeechAudioInput, SpeechToTextProvider, SpeechTranscriptionOptions, SpeechTranscriptionResult } from '../types.js';
-/** Configuration for the AzureSpeechSTTProvider. */
+/**
+ * Configuration for the {@link AzureSpeechSTTProvider}.
+ *
+ * @see {@link AzureSpeechSTTProvider} for usage examples
+ * @see https://learn.microsoft.com/azure/ai-services/speech-service/rest-speech-to-text
+ */
 export interface AzureSpeechSTTProviderConfig {
-    /** Azure Cognitive Services subscription key. */
+    /**
+     * Azure Cognitive Services subscription key.
+     * Sent as the `Ocp-Apim-Subscription-Key` header — this is Azure's
+     * standard authentication mechanism for Cognitive Services REST APIs.
+     * Obtain from the Azure portal under your Speech resource's "Keys and Endpoint".
+     */
     key: string;
-    /** Azure region, e.g. `'eastus'` or `'westeurope'`. */
+    /**
+     * Azure region where the Speech resource is deployed, e.g. `'eastus'`,
+     * `'westeurope'`, `'southeastasia'`.
+     *
+     * The region determines the REST endpoint hostname:
+     * `https://{region}.stt.speech.microsoft.com`
+     *
+     * @see https://learn.microsoft.com/azure/ai-services/speech-service/regions
+     */
     region: string;
     /**
-     * Custom fetch implementation, useful for testing.
-     * Defaults to the global `fetch`.
+     * Custom fetch implementation for dependency injection in tests.
+     * @default globalThis.fetch
      */
     fetchImpl?: typeof fetch;
 }
 /**
  * Speech-to-text provider that uses the Azure Cognitive Services Speech REST API.
  *
- * Sends WAV audio as a raw binary body and returns a normalised
- * {@link SpeechTranscriptionResult}. A `RecognitionStatus` of `'NoMatch'`
- * is mapped to an empty text result rather than an error, matching the
- * Azure SDK behaviour.
+ * ## Azure REST Endpoint Format
+ *
+ * The endpoint URL follows this pattern:
+ * ```
+ * https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language={lang}
+ * ```
+ *
+ * - `{region}` — The Azure region from config (e.g. `eastus`, `westeurope`).
+ * - `{lang}` — BCP-47 language code from options or `'en-US'` default.
+ * - The `/conversation/` path segment selects the conversation recognition mode
+ *   (as opposed to `/interactive/` or `/dictation/`).
+ *
+ * ## Authentication: `Ocp-Apim-Subscription-Key`
+ *
+ * Azure Cognitive Services uses the `Ocp-Apim-Subscription-Key` HTTP header
+ * for authentication, which differs from the typical `Authorization: Bearer`
+ * pattern. The subscription key is sent as a plain-text header value — no
+ * "Bearer" or "Token" prefix.
+ *
+ * An alternative is to use a short-lived token from the token endpoint, but
+ * this provider uses the simpler key-based approach for reliability.
+ *
+ * ## NoMatch Handling
+ *
+ * When Azure's recognizer detects audio but cannot identify any speech, it
+ * returns `RecognitionStatus: 'NoMatch'` instead of raising an HTTP error.
+ * This provider maps `NoMatch` to an empty-text result (`text: ''`) with
+ * `isFinal: true`, matching the Azure Speech SDK's behaviour. This prevents
+ * the fallback proxy from unnecessarily trying another provider when the
+ * audio genuinely contains no speech.
+ *
+ * ## Limitations
+ *
+ * - Audio must be PCM WAV format. The `Content-Type` is hardcoded to
+ *   `audio/wav` regardless of the `audio.mimeType` value.
+ * - Streaming is not supported — use the Azure Speech SDK for real-time STT.
+ * - Speaker diarization is not available via the REST API.
+ *
+ * @see {@link AzureSpeechSTTProviderConfig} for configuration options
+ * @see {@link AzureSpeechTTSProvider} for the corresponding TTS provider
  *
  * @example
  * ```ts
- * const provider = new AzureSpeechSTTProvider({ key: process.env.AZURE_SPEECH_KEY!, region: 'eastus' });
- * const result = await provider.transcribe({ data: wavBuffer });
- * console.log(result.text);
+ * const provider = new AzureSpeechSTTProvider({
+ *   key: process.env.AZURE_SPEECH_KEY!,
+ *   region: 'eastus',
+ * });
+ * const result = await provider.transcribe(
+ *   { data: wavBuffer, mimeType: 'audio/wav' },
+ *   { language: 'de-DE' },
+ * );
+ * console.log(result.text); // '' if no speech detected
  * ```
  */
 export declare class AzureSpeechSTTProvider implements SpeechToTextProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "azure-speech-stt";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "Azure Speech (STT)";
+    /** This provider uses synchronous HTTP requests, not WebSocket streaming. */
     readonly supportsStreaming = false;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /**
+     * Creates a new AzureSpeechSTTProvider.
+     *
+     * @param config - Provider configuration including the subscription key and region.
+     *
+     * @example
+     * ```ts
+     * const provider = new AzureSpeechSTTProvider({
+     *   key: 'your-azure-subscription-key',
+     *   region: 'eastus',
+     * });
+     * ```
+     */
     constructor(config: AzureSpeechSTTProviderConfig);
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'Azure Speech (STT)'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'Azure Speech (STT)'
+     * ```
+     */
     getProviderName(): string;
     /**
      * Transcribes an audio buffer using the Azure Speech recognition REST endpoint.
      *
-     * @param audio - Raw audio data. Azure expects PCM WAV; pass `mimeType: 'audio/wav'`.
-     * @param options - Optional transcription settings (language…).
-     * @returns A promise resolving to the normalised transcription result.
-     * @throws When the Azure API returns a non-2xx status.
+     * Sends the raw audio as PCM WAV and returns a normalized result. Azure's
+     * `NoMatch` status is treated as an empty transcript (not an error).
+     *
+     * @param audio - Raw audio data. Azure expects PCM WAV format; the
+     *   Content-Type header is always set to `'audio/wav'` regardless of
+     *   `audio.mimeType`.
+     * @param options - Optional transcription settings. Only `language` is
+     *   supported by the Azure REST endpoint.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the Azure API returns a non-2xx HTTP status code.
+     *   The error message includes the status and response body text.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: wavBuffer, durationSeconds: 5 },
+     *   { language: 'fr-FR' },
+     * );
+     * if (result.text === '') {
+     *   console.log('No speech detected in the audio');
+     * }
+     * ```
      */
     transcribe(audio: SpeechAudioInput, options?: SpeechTranscriptionOptions): Promise<SpeechTranscriptionResult>;
 }

package/dist/speech/providers/AzureSpeechSTTProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AzureSpeechSTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechSTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoBD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IAOrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,SAAgB,EAAE,sBAAsB;IACxC,SAAgB,WAAW,wBAAwB;IACnD,SAAgB,iBAAiB,SAAS;IAE1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,4BAA4B;IAIjE,gDAAgD;IAChD,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CA0DtC"}
+{"version":3,"file":"AzureSpeechSTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechSTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IA0BrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzBnC,uEAAuE;IACvE,SAAgB,EAAE,sBAAsB;IAExC,sDAAsD;IACtD,SAAgB,WAAW,wBAAwB;IAEnD,6EAA6E;IAC7E,SAAgB,iBAAiB,SAAS;IAE1C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;;;;;;;;;;OAYG;gBAC0B,MAAM,EAAE,4BAA4B;IAIjE;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAmEtC"}