@juspay/neurolink 12.47.14 → 12.48.1

package/dist/voice/providers/ElevenLabsSTT.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ElevenLabs Speech-to-Text (Scribe) Handler
+ *
+ * Batch transcription via `POST /v1/speech-to-text`. Shares the
+ * `ELEVENLABS_API_KEY` / `ELEVENLABS_BASE_URL` environment with the ElevenLabs
+ * TTS and music handlers — same account, different endpoint.
+ *
+ * @module voice/providers/ElevenLabsSTT
+ */
+import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
+/**
+ * ElevenLabs Scribe Speech-to-Text Handler
+ *
+ * Batch-only (no `transcribeStream`). Word timings and speaker labels come
+ * back on every response when the audio has them; `diarize` asks Scribe to
+ * attribute words to speakers.
+ *
+ * @see https://elevenlabs.io/docs/api-reference/speech-to-text/convert
+ */
+export declare class ElevenLabsSTT implements STTHandler {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /** Scribe accepts files up to 1 GB / ~4.5 hours; 2 hours is a conservative cap. */
+    readonly maxAudioDuration = 7200;
+    readonly supportsStreaming = false;
+    constructor(apiKey?: string);
+    isConfigured(): boolean;
+    getSupportedFormats(): TTSAudioFormat[];
+    getSupportedLanguages(): Promise<STTLanguage[]>;
+    transcribe(audio: Buffer | ArrayBuffer, options?: STTOptions): Promise<STTResult>;
+    private toSTTResult;
+    /** A finite number clamped to [0, 1]; `undefined` for anything else. */
+    private static unitInterval;
+    /** Mean `exp(logprob)` over the words that carry a finite one, clamped to [0, 1]; `undefined` when none does. */
+    private static meanWordConfidence;
+    /** Scribe takes ISO 639-1/3 codes; a BCP-47 tag like `en-US` or `pt_BR` is reduced to its primary subtag. */
+    private toScribeLanguageCode;
+    private getMimeType;
+    /** 429 and 5xx are worth a resend; every other status is a fixed error. */
+    private static isRetriableStatus;
+    private static normalizeBaseUrl;
+}

package/dist/voice/providers/ElevenLabsSTT.js

@@ -0,0 +1,351 @@
+/**
+ * ElevenLabs Speech-to-Text (Scribe) Handler
+ *
+ * Batch transcription via `POST /v1/speech-to-text`. Shares the
+ * `ELEVENLABS_API_KEY` / `ELEVENLABS_BASE_URL` environment with the ElevenLabs
+ * TTS and music handlers — same account, different endpoint.
+ *
+ * @module voice/providers/ElevenLabsSTT
+ */
+import { logger } from "../../utils/logger.js";
+import { STTError } from "../errors.js";
+const PROVIDER = "elevenlabs-stt";
+const DEFAULT_BASE_URL = "https://api.elevenlabs.io/v1";
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Largest delay `setTimeout` honours; above it the timer fires at once. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** `scribe_v1` is deprecated in ElevenLabs' model list; v2 is the current batch model. */
+const DEFAULT_MODEL = "scribe_v2";
+/**
+ * ElevenLabs Scribe Speech-to-Text Handler
+ *
+ * Batch-only (no `transcribeStream`). Word timings and speaker labels come
+ * back on every response when the audio has them; `diarize` asks Scribe to
+ * attribute words to speakers.
+ *
+ * @see https://elevenlabs.io/docs/api-reference/speech-to-text/convert
+ */
+export class ElevenLabsSTT {
+    apiKey;
+    baseUrl;
+    /** Scribe accepts files up to 1 GB / ~4.5 hours; 2 hours is a conservative cap. */
+    maxAudioDuration = 7200;
+    supportsStreaming = false;
+    constructor(apiKey) {
+        const resolvedKey = (apiKey ?? process.env.ELEVENLABS_API_KEY ?? "").trim();
+        this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
+        this.baseUrl = ElevenLabsSTT.normalizeBaseUrl(process.env.ELEVENLABS_BASE_URL ?? DEFAULT_BASE_URL);
+    }
+    isConfigured() {
+        return this.apiKey !== null;
+    }
+    getSupportedFormats() {
+        return [
+            "mp3",
+            "wav",
+            "ogg",
+            "opus",
+            "m4a",
+            "flac",
+            "webm",
+            "mp4",
+            "mpeg",
+            "mpga",
+        ];
+    }
+    async getSupportedLanguages() {
+        // Scribe auto-detects among 99 languages; this is the commonly requested subset.
+        return [
+            {
+                code: "en",
+                name: "English",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "es",
+                name: "Spanish",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "fr",
+                name: "French",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "de",
+                name: "German",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "it",
+                name: "Italian",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "pt",
+                name: "Portuguese",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "hi",
+                name: "Hindi",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "ja",
+                name: "Japanese",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "ko",
+                name: "Korean",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "zh",
+                name: "Chinese",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+            {
+                code: "ar",
+                name: "Arabic",
+                supportsDiarization: true,
+                supportsPunctuation: true,
+            },
+        ];
+    }
+    async transcribe(audio, options = {}) {
+        if (!this.apiKey) {
+            throw STTError.providerNotConfigured(PROVIDER);
+        }
+        const audioBuffer = Buffer.isBuffer(audio) ? audio : Buffer.from(audio);
+        if (audioBuffer.length === 0) {
+            throw STTError.audioEmpty(PROVIDER);
+        }
+        const elevenOptions = options;
+        const model = elevenOptions.model ?? DEFAULT_MODEL;
+        const format = options.format ?? "wav";
+        const startTime = Date.now();
+        try {
+            const formData = new FormData();
+            formData.append("file", new Blob([new Uint8Array(audioBuffer)], {
+                type: this.getMimeType(format),
+            }), `audio.${format}`);
+            formData.append("model_id", model);
+            // Only forward a language the caller actually set: Scribe auto-detects
+            // otherwise, and an injected default would pin every request to one
+            // language. (STTProcessor passes options through untouched, so a caller
+            // who leaves `language` unset reaches here with it unset.)
+            if (options.language) {
+                formData.append("language_code", this.toScribeLanguageCode(options.language));
+            }
+            // ElevenLabs defaults this to true; a plain transcript is the better
+            // default for text that feeds a prompt.
+            formData.append("tag_audio_events", String(elevenOptions.tagAudioEvents ?? false));
+            const diarize = options.speakerDiarization ?? options.diarization ?? false;
+            formData.append("diarize", String(diarize));
+            if (diarize && options.speakerCount !== undefined) {
+                formData.append("num_speakers", String(options.speakerCount));
+            }
+            const baseUrl = elevenOptions.baseUrl
+                ? ElevenLabsSTT.normalizeBaseUrl(elevenOptions.baseUrl)
+                : this.baseUrl;
+            const timeoutMs = typeof elevenOptions.timeoutMs === "number" &&
+                Number.isFinite(elevenOptions.timeoutMs) &&
+                elevenOptions.timeoutMs > 0
+                ? Math.min(elevenOptions.timeoutMs, MAX_TIMEOUT_MS)
+                : DEFAULT_TIMEOUT_MS;
+            // The timer covers the response headers AND the JSON body: a server
+            // that stalls mid-body used to hold the transcription — and the
+            // generate() it fed — until undici's own ~5-minute body timeout, long
+            // after `timeoutMs` had passed.
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const timedOut = (err) => err instanceof Error && err.name === "AbortError"
+                ? STTError.transcriptionFailed(`ElevenLabs STT request timed out after ${timeoutMs}ms`, PROVIDER, err)
+                : undefined;
+            let data;
+            try {
+                let response;
+                try {
+                    response = await fetch(`${baseUrl}/speech-to-text`, {
+                        method: "POST",
+                        headers: { "xi-api-key": this.apiKey },
+                        body: formData,
+                        signal: controller.signal,
+                    });
+                }
+                catch (fetchErr) {
+                    throw timedOut(fetchErr) ?? fetchErr;
+                }
+                if (!response.ok) {
+                    // A body that PARSES to `null` isn't caught by `.catch()`, and
+                    // `.detail` on `null` throws — see ElevenLabsTTS.ts's identical fix.
+                    const errorData = (await response.json().catch(() => null)) ??
+                        Object.create(null);
+                    const detail = errorData.detail;
+                    const errorMessage = (typeof detail === "string" ? detail : detail?.message) ||
+                        `HTTP ${response.status}`;
+                    const failure = STTError.transcriptionFailed(errorMessage, PROVIDER);
+                    // `transcriptionFailed` defaults to retriable; a 4xx (bad audio, bad
+                    // key, unsupported option) can never succeed on resend.
+                    throw new STTError({
+                        code: failure.code,
+                        message: failure.message,
+                        category: failure.category,
+                        severity: failure.severity,
+                        retriable: ElevenLabsSTT.isRetriableStatus(response.status),
+                        context: { provider: PROVIDER, status: response.status },
+                    });
+                }
+                try {
+                    data = (await response.json());
+                }
+                catch (bodyErr) {
+                    throw (timedOut(bodyErr) ??
+                        STTError.transcriptionFailed(`ElevenLabs STT response body failed: ${bodyErr instanceof Error ? bodyErr.message : String(bodyErr)}`, PROVIDER, bodyErr instanceof Error ? bodyErr : undefined));
+                }
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            const latency = Date.now() - startTime;
+            const result = this.toSTTResult(data, model, latency);
+            logger.info(`[ElevenLabsSTTHandler] Transcribed ${audioBuffer.length} bytes in ${latency}ms`);
+            return result;
+        }
+        catch (err) {
+            if (err instanceof STTError) {
+                throw err;
+            }
+            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            logger.error(`[ElevenLabsSTTHandler] Transcription failed: ${errorMessage}`);
+            throw STTError.transcriptionFailed(errorMessage, PROVIDER, err instanceof Error ? err : undefined);
+        }
+    }
+    toSTTResult(data, model, latency) {
+        const spoken = (data.words ?? []).filter((word) => typeof word.text === "string" &&
+            word.type !== "spacing" &&
+            word.type !== "audio_event" &&
+            word.text.trim().length > 0);
+        // `confidence` is required on STTResult, so it is always a number — but
+        // which number is recorded, never guessed at. The transcript confidence
+        // proper is the mean per-word `exp(logprob)`, the same conversion
+        // Whisper's `avg_logprob` gets. When no word carries a logprob the field
+        // falls back to `language_probability` — how sure Scribe is about the
+        // LANGUAGE, not the words: garbled and clean audio both score ~0.99 on
+        // it — and when that is missing too it is 0. `metadata.confidenceSource`
+        // names the one used, and `languageProbability` is always kept under its
+        // own name so a caller can tell the two apart.
+        const wordConfidence = ElevenLabsSTT.meanWordConfidence(spoken);
+        const languageProbability = ElevenLabsSTT.unitInterval(data.language_probability);
+        let confidence;
+        let confidenceSource;
+        if (wordConfidence !== undefined) {
+            confidence = wordConfidence;
+            confidenceSource = "word_logprobs";
+        }
+        else if (languageProbability !== undefined) {
+            confidence = languageProbability;
+            confidenceSource = "language_probability";
+        }
+        else {
+            confidence = 0;
+            confidenceSource = "none";
+        }
+        const result = {
+            text: data.text ?? "",
+            confidence,
+            language: data.language_code,
+            metadata: {
+                latency,
+                provider: PROVIDER,
+                model,
+                confidenceSource,
+                languageProbability: data.language_probability,
+            },
+        };
+        if (spoken.length > 0) {
+            const speakers = new Set();
+            result.words = spoken.map((word) => {
+                if (word.speaker_id) {
+                    speakers.add(word.speaker_id);
+                }
+                return {
+                    word: word.text,
+                    startTime: word.start,
+                    endTime: word.end,
+                    speaker: word.speaker_id,
+                };
+            });
+            if (speakers.size > 0) {
+                result.speakers = [...speakers];
+            }
+            const last = spoken[spoken.length - 1];
+            if (typeof last?.end === "number") {
+                result.duration = last.end;
+            }
+        }
+        return result;
+    }
+    /** A finite number clamped to [0, 1]; `undefined` for anything else. */
+    static unitInterval(value) {
+        return typeof value === "number" && Number.isFinite(value)
+            ? Math.min(1, Math.max(0, value))
+            : undefined;
+    }
+    /** Mean `exp(logprob)` over the words that carry a finite one, clamped to [0, 1]; `undefined` when none does. */
+    static meanWordConfidence(words) {
+        let sum = 0;
+        let count = 0;
+        for (const word of words) {
+            if (typeof word.logprob === "number" && Number.isFinite(word.logprob)) {
+                sum += Math.exp(word.logprob);
+                count += 1;
+            }
+        }
+        return count === 0 ? undefined : Math.min(1, Math.max(0, sum / count));
+    }
+    /** Scribe takes ISO 639-1/3 codes; a BCP-47 tag like `en-US` or `pt_BR` is reduced to its primary subtag. */
+    toScribeLanguageCode(language) {
+        return (language.trim().split(/[-_]/, 1)[0] ?? language).toLowerCase();
+    }
+    getMimeType(format) {
+        const mimeTypes = {
+            mp3: "audio/mpeg",
+            mpeg: "audio/mpeg",
+            mpga: "audio/mpeg",
+            wav: "audio/wav",
+            ogg: "audio/ogg",
+            opus: "audio/ogg",
+            m4a: "audio/mp4",
+            mp4: "audio/mp4",
+            flac: "audio/flac",
+            webm: "audio/webm",
+        };
+        return mimeTypes[format] ?? "application/octet-stream";
+    }
+    /** 429 and 5xx are worth a resend; every other status is a fixed error. */
+    static isRetriableStatus(status) {
+        return status === 429 || status >= 500;
+    }
+    static normalizeBaseUrl(baseUrl) {
+        // A loop rather than /\/+$/: the input is caller-supplied and CodeQL
+        // flags that regex as polynomial on long runs of "/".
+        let end = baseUrl.length;
+        while (end > 0 && baseUrl.charCodeAt(end - 1) === 47) {
+            end--;
+        }
+        return baseUrl.slice(0, end);
+    }
+}

package/dist/voice/providers/ElevenLabsTTS.d.ts

@@ -16,6 +16,10 @@ import type { TTSHandler, TTSOptions, TTSResult, TTSVoice } from "../../types/in
 export declare class ElevenLabsTTS implements TTSHandler {
     private readonly apiKey;
     private readonly baseUrl;
+    /** `ELEVENLABS_VOICE_ID`, else Rachel; a per-request `voice` still wins. */
+    private readonly defaultVoiceId;
+    /** `ELEVENLABS_MODEL`, else `eleven_multilingual_v2`; a per-request `model` still wins. */
+    private readonly defaultModel;
     private voicesCache;
     private static readonly CACHE_TTL_MS;
     /**
@@ -23,15 +27,91 @@ export declare class ElevenLabsTTS implements TTSHandler {
      */
     readonly maxTextLength = 5000;
     constructor(apiKey?: string);
+    /** A trimmed, non-empty environment value, else `undefined`. */
+    private static envValue;
     isConfigured(): boolean;
     getVoices(languageCode?: string): Promise<TTSVoice[]>;
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+    /**
+     * Issue the synthesis request, retrying on 429 / 5xx / network failure /
+     * per-attempt timeout up to `retries` more times. A `Retry-After` header
+     * sets the pause before the next attempt (capped); otherwise exponential
+     * backoff from 500 ms. Any other failure — 4xx, or a body that is not audio
+     * — is thrown on the first attempt.
+     *
+     * Total wall-clock is bounded by `timeoutMs × (1 + retries)` plus the pauses
+     * between attempts; `BaseProvider`'s outer synthesis timeout is raised to at
+     * least that figure (see `resolveTTSHandlerBudgetMs`).
+     *
+     * `signal` is the caller's cancellation: once it fires, the attempt in
+     * flight is aborted and no further attempt is made. Without it, a caller
+     * that had already given up (its own timeout, an aborted request) left the
+     * loop to pause and issue a second, billable request nobody consumed.
+     */
+    private fetchWithRetry;
+    /**
+     * A backoff pause that ends as soon as `signal` fires, so a cancelled
+     * caller never waits it out. The timer is owned here and cleared on the
+     * way out: racing a bare `delay()` against the signal settled the promise
+     * at the abort but left the backoff timer armed for up to `RETRY_AFTER_CAP_MS`,
+     * holding the event loop open after the caller had already been answered.
+     */
+    private static pause;
+    /** The non-retriable error a caller-cancelled synthesis surfaces as. */
+    private static cancelledError;
+    /**
+     * One attempt, end to end: the per-attempt timer covers the response
+     * headers AND the audio body, so a stalled or truncated body is a timed-out
+     * attempt the retry loop can resend rather than a hang that only the outer
+     * provider budget ends. The caller's `signal` aborts the same controller,
+     * and an abort it caused is reported as a cancellation, not a timeout.
+     */
+    private fetchOnce;
+    /** Map an abort from the per-attempt timer to a retriable timeout error. */
+    private static asAttemptError;
+    private static isRetriableStatus;
+    /**
+     * 429 / 5xx, a per-attempt timeout or broken body (already a retriable
+     * `TTSError`), or a transport failure. Any other throw — a `TypeError` for
+     * an invalid header value or URL, thrown before a request exists — is
+     * permanent and is not retried; it used to be, on the grounds that it was
+     * an `Error`.
+     */
+    private static isRetriableFailure;
+    /**
+     * A socket-level failure: undici wraps one as `TypeError("fetch failed")`
+     * with the system error on `cause`, and the codes are checked on both.
+     */
+    private static isTransportError;
+    private static errorCode;
+    /** A BCP-47 tag reduced to its ISO 639-1 primary subtag: `en-US` → `en`, `pt_BR` → `pt`. */
+    private static toIso639Primary;
+    /** One of `allowed`, else `fallback` with a warning — never an unlisted value in `output_format`. */
+    private static resolveBitrate;
+    /** `Retry-After` as delta-seconds or an HTTP-date, in milliseconds. */
+    private static parseRetryAfter;
+    /** A positive finite `timeoutMs`, clamped to the largest delay a timer honours; otherwise the default. */
+    private static resolveTimeoutMs;
+    private static resolveRetries;
+    private static normalizeBaseUrl;
+    /**
+     * Assemble `voice_settings`. The camelCase options are the documented
+     * surface; `voiceSettings` passes raw fields through and wins on conflict.
+     * `speed` comes from the generic `TTSOptions.speed` (0.25–4.0) clamped into
+     * ElevenLabs' accepted 0.7–1.2 — clamped with a warning rather than
+     * rejected, because the generic validator has already accepted the value.
+     */
+    private buildVoiceSettings;
     /**
      * Map gender string to standard type
      */
     private mapGender;
     /**
-     * Map TTSAudioFormat to ElevenLabs output format
+     * Map TTSAudioFormat to an ElevenLabs `output_format`.
+     *
+     * ElevenLabs has no `ogg_*` family: Ogg/Opus is `opus_48000_<kbps>`. Both
+     * `ogg` and `opus` map there. `wav` maps to raw `pcm_44100` (headerless —
+     * see `effectiveFormat`). Anything else falls back to `mp3_44100_128`.
      */
     private mapFormat;
     /**