@juspay/neurolink 12.28.4 → 12.29.0

package/dist/utils/providerHealth.js

@@ -14,8 +14,53 @@ export class ProviderHealthChecker {
     static healthCache = new Map();
     static DEFAULT_TIMEOUT = 5000; // 5 seconds
     static DEFAULT_CACHE_AGE = 300000; // 5 minutes
+    /**
+     * Fixed backoff window for the circuit breaker below, in milliseconds.
+     * Deliberately NOT the per-call `maxCacheAge` option: `consecutiveFailures`
+     * is a single process-wide map keyed only by provider name, shared by every
+     * caller (e.g. `checkFallbackProviderAvailability` hard-codes a 15s
+     * `maxCacheAge` for its own health-status cache). Evicting the breaker
+     * entry using whichever caller happens to read it next would let a
+     * short-TTL caller silently erase a backoff another caller is relying on
+     * — see `checkProviderHealth`. This constant governs breaker expiry alone
+     * and is intentionally independent of `maxCacheAge`/`DEFAULT_CACHE_AGE`.
+     */
+    static CIRCUIT_BREAKER_RESET_MS = 300000; // 5 minutes
     static CONSECUTIVE_FAILURE_THRESHOLD = ProviderHealthChecker.getValidatedFailureThreshold();
+    /**
+     * Circuit breaker state, keyed by provider.
+     *
+     * `count` is a count of consecutive failed CONNECTIVITY PROBES (plus the
+     * rare case of the check itself throwing) — never of "the provider is
+     * unconfigured". Those are different facts and only one of them is worth
+     * backing off from. A missing credential is a free, local, determinate
+     * answer that costs nothing to re-derive and flips the instant an env var
+     * is set; treating it as a failure is what let a sweep of ~38 providers
+     * (issue #1305 grew it from 8) blacklist every provider the machine
+     * happens not to have credentials for, after which the sweep reported
+     * `isConfigured: false` and no `responseTime` for a provider that was
+     * merely unconfigured — and kept reporting it after the key was supplied.
+     *
+     * `lastFailureAt` bounds how long a run of failures is held against a
+     * provider; see `checkProviderHealth`.
+     */
     static consecutiveFailures = new Map();
+    /**
+     * Hard cap on simultaneous per-provider checks inside
+     * `checkAllProvidersHealth`. Issue #1305: the sweep used to cover only 8
+     * of ~38 registered providers; now every non-opted-out descriptor is
+     * included (see `excludeFromHealthSweep`). Firing all ~38 at once via a
+     * single `Promise.allSettled` would be harmless by default
+     * (`includeConnectivityTest` defaults to false, so most calls never
+     * leave the process), but a caller who opts into
+     * `includeConnectivityTest: true` would otherwise open up to ~38
+     * concurrent outbound HTTP connections to that many different vendors in
+     * one burst. A worker pool keeps that bounded without reducing coverage
+     * — every provider is still checked, just not all in the same instant,
+     * and without the latency a fixed batch would add (see
+     * `checkAllProvidersHealth`).
+     */
+    static MAX_CONCURRENT_HEALTH_CHECKS = 8;
     /**
      * Validate and return a safe failure threshold value
      */
@@ -44,24 +89,49 @@ export class ProviderHealthChecker {
                 return cached;
             }
         }
-        // Check if provider has consecutive failures (blacklisting)
-        const failureCount = this.consecutiveFailures.get(providerName) || 0;
-        if (failureCount >= this.CONSECUTIVE_FAILURE_THRESHOLD) {
-            const healthStatus = {
-                provider: providerName,
-                isHealthy: false,
-                isConfigured: false,
-                hasApiKey: false,
-                lastChecked: new Date(),
-                error: `Provider blacklisted after ${failureCount} consecutive failures`,
-                warning: "Provider will be retried after cache TTL expires",
-                configurationIssues: [
-                    `Blacklisted due to ${failureCount} consecutive failures`,
-                ],
-                recommendations: ["Check provider status and configuration"],
-            };
+        // Circuit breaker. It suppresses outbound PROBES, not the whole check:
+        // for most providers the step-1 configuration audit is local and free,
+        // so skipping it bought nothing and cost the caller a status object of
+        // a different shape — no `responseTime`, and a fabricated
+        // `isConfigured: false` for a provider nothing had looked at.
+        //
+        // LiteLLM and Ollama are the exception: their step-1 check
+        // (checkLiteLLMConfig/checkOllamaConfig) makes a real outbound request,
+        // because for a local runtime "configured" only means something if it
+        // means "reachable" — both providers have zero required env vars
+        // (`credentialsResolvedExternally` / no `apiKey`), so with no request at
+        // all every install would read as configured. Auto-select
+        // (`NeuroLink.hasProviderEnvVars`) depends on that: it always calls with
+        // `includeConnectivityTest: false`, so gating this probe on that flag
+        // instead of the breaker would make a dead local proxy look configured
+        // and win auto-select over a real, working cloud provider. So this
+        // probe still runs in shallow mode, but — like the step-3 connectivity
+        // probe — it is governed by the SAME breaker below (`allowRuntimeProbe`
+        // passed into checkEnvironmentConfiguration): skipped while blacklisted,
+        // and its outcome folded into `anyProbeFailed`/`anyProbeRan` further
+        // down, so a dead local proxy still gets backed off instead of eating a
+        // full timeout on every call forever.
+        //
+        // A run of failures older than CIRCUIT_BREAKER_RESET_MS is forgotten,
+        // which is what makes the "will be retried after cache TTL expires"
+        // warning below true. Nothing else could clear it, because the
+        // breaker's whole effect is to suppress the probe that would disprove
+        // it. This is deliberately the fixed CIRCUIT_BREAKER_RESET_MS window,
+        // not this call's own `maxCacheAge` — `consecutiveFailures` is a single
+        // shared map keyed only by provider name, so reusing whichever caller
+        // happens to invoke `checkProviderHealth` next (some call sites pass a
+        // much shorter `maxCacheAge` for their own unrelated caching needs)
+        // would let that caller silently evict a backoff a different caller is
+        // relying on.
+        const breaker = this.consecutiveFailures.get(providerName);
+        if (breaker !== undefined &&
+            Date.now() - breaker.lastFailureAt >= this.CIRCUIT_BREAKER_RESET_MS) {
+            this.consecutiveFailures.delete(providerName);
+        }
+        const failureCount = this.consecutiveFailures.get(providerName)?.count ?? 0;
+        const blacklisted = failureCount >= this.CONSECUTIVE_FAILURE_THRESHOLD;
+        if (blacklisted) {
             logger.warn(`Provider ${providerName} blacklisted due to consecutive failures`, { failureCount });
-            return healthStatus;
         }
         const startTime = Date.now();
         const healthStatus = {
@@ -74,18 +144,37 @@ export class ProviderHealthChecker {
             recommendations: [],
         };
         try {
-            // 1. Check environment configuration
-            await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout);
+            // 1. Check environment configuration. For LiteLLM/Ollama this
+            // includes a breaker-governed runtime probe — see the comment on
+            // `blacklisted` above.
+            const runtimeProbe = await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout, !blacklisted);
             // 2. Check API key validity (basic format validation)
             await this.checkApiKeyValidity(providerName, healthStatus);
-            // 3. Optional: Connectivity test
-            if (includeConnectivityTest) {
+            // 3. Optional: Connectivity test. Also governed by the breaker.
+            const issuesBeforeProbe = healthStatus.configurationIssues.length;
+            const probed = includeConnectivityTest && !blacklisted;
+            if (probed) {
                 await this.checkConnectivity(providerName, healthStatus, timeout);
             }
+            const probeFailed = probed && healthStatus.configurationIssues.length > issuesBeforeProbe;
+            // Fold the step-1 runtime probe (if this provider has one) together
+            // with the step-3 connectivity probe into one pair of breaker
+            // signals, so a call where BOTH run and fail still counts as exactly
+            // ONE failure (the breaker steps consecutive calls, not consecutive
+            // requests).
+            const anyProbeRan = probed || runtimeProbe.ran;
+            const anyProbeFailed = probeFailed || runtimeProbe.failed;
             // 4. Optional: Model validation
             if (includeModelValidation) {
                 await this.checkModelAvailability(providerName, healthStatus);
             }
+            if (blacklisted) {
+                healthStatus.error = `Provider blacklisted after ${failureCount} consecutive failures`;
+                healthStatus.warning =
+                    "Provider will be retried after cache TTL expires";
+                healthStatus.configurationIssues.push(`Blacklisted due to ${failureCount} consecutive failures`);
+                healthStatus.recommendations.push("Check provider status and configuration");
+            }
             // 5. Determine overall health
             healthStatus.isHealthy =
                 healthStatus.isConfigured &&
@@ -99,14 +188,17 @@ export class ProviderHealthChecker {
                     timestamp: Date.now(),
                 });
             }
-            // Reset failure count on success
-            if (healthStatus.isHealthy) {
-                this.consecutiveFailures.delete(providerName);
+            // Only a probe that actually ran moves the breaker. A check that
+            // issued no request is not evidence either way: it neither proves the
+            // provider is failing nor that it has recovered.
+            if (anyProbeFailed) {
+                this.consecutiveFailures.set(providerName, {
+                    count: failureCount + 1,
+                    lastFailureAt: Date.now(),
+                });
             }
-            else {
-                // Track consecutive failures
-                const currentFailures = this.consecutiveFailures.get(providerName) || 0;
-                this.consecutiveFailures.set(providerName, currentFailures + 1);
+            else if (anyProbeRan) {
+                this.consecutiveFailures.delete(providerName);
             }
             logger.debug(`Health check completed for ${providerName}`, {
                 isHealthy: healthStatus.isHealthy,
@@ -119,12 +211,15 @@ export class ProviderHealthChecker {
             healthStatus.error = errorMessage;
             healthStatus.configurationIssues.push(`Health check failed: ${errorMessage}`);
             healthStatus.responseTime = Date.now() - startTime;
-            // Track consecutive failures
-            const currentFailures = this.consecutiveFailures.get(providerName) || 0;
-            this.consecutiveFailures.set(providerName, currentFailures + 1);
+            // A check that threw failed to answer at all, which is a failure in
+            // the sense the breaker is for — unlike an answered "not configured".
+            this.consecutiveFailures.set(providerName, {
+                count: failureCount + 1,
+                lastFailureAt: Date.now(),
+            });
             logger.warn(`Health check failed for ${providerName}`, {
                 error: errorMessage,
-                consecutiveFailures: currentFailures + 1,
+                consecutiveFailures: failureCount + 1,
             });
         }
         return healthStatus;
@@ -132,7 +227,7 @@ export class ProviderHealthChecker {
     /**
      * Check environment configuration for a provider
      */
-    static async checkEnvironmentConfiguration(providerName, healthStatus, timeout) {
+    static async checkEnvironmentConfiguration(providerName, healthStatus, timeout, allowRuntimeProbe) {
         const requiredEnvVars = this.getRequiredEnvironmentVariables(providerName);
         logger.debug(`[ProviderHealthChecker] Checking environment configuration for ${providerName}`, {
             requiredEnvVars,
@@ -163,7 +258,7 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push(`Set the following environment variables: ${missingVars.join(", ")}`);
         }
         // Provider-specific configuration checks
-        await this.checkProviderSpecificConfig(providerName, healthStatus, timeout);
+        return this.checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe);
     }
     /**
      * Check API key validity (format validation)
@@ -456,7 +551,7 @@ export class ProviderHealthChecker {
     /**
      * Provider-specific configuration checks
      */
-    static async checkProviderSpecificConfig(providerName, healthStatus, timeout) {
+    static async checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe) {
         switch (providerName) {
             case AIProviderName.VERTEX:
                 await this.checkVertexAIConfig(healthStatus);
@@ -468,12 +563,13 @@ export class ProviderHealthChecker {
                 await this.checkAzureConfig(healthStatus);
                 break;
             case AIProviderName.LITELLM:
-                await this.checkLiteLLMConfig(healthStatus, timeout);
-                break;
+                return this.checkLiteLLMConfig(healthStatus, timeout, allowRuntimeProbe);
             case AIProviderName.OLLAMA:
-                await this.checkOllamaConfig(healthStatus, timeout);
-                break;
+                return this.checkOllamaConfig(healthStatus, timeout, allowRuntimeProbe);
         }
+        // Every other provider's config check above is local (env vars, file
+        // existence) — never a network request, so there is no probe to report.
+        return { ran: false, failed: false };
     }
     /**
      * Check Vertex AI configuration
@@ -800,13 +896,22 @@ export class ProviderHealthChecker {
             };
         }
     }
-    static async checkLiteLLMConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
+    static async checkLiteLLMConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT, allowRuntimeProbe = true) {
         const liteLLMBase = this.getLiteLLMBaseUrl();
         if (!liteLLMBase.startsWith("http")) {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push("Invalid LITELLM_BASE_URL format");
             healthStatus.recommendations.push("Set LITELLM_BASE_URL to a valid URL (e.g., http://localhost:4000)");
-            return;
+            return { ran: false, failed: false };
+        }
+        if (!allowRuntimeProbe) {
+            // Blacklisted: don't issue the request. A repeatedly unreachable
+            // local provider is not usable, which is what auto-select needs —
+            // but the caller's blacklist block (checkProviderHealth) already adds
+            // the error/warning/configurationIssue for this, so nothing is
+            // duplicated here.
+            healthStatus.isConfigured = false;
+            return { ran: false, failed: false };
         }
         // Only pin the availability check to a specific model when the user
         // explicitly configured one. The fallback default ("openai/gpt-4o-mini")
@@ -840,20 +945,30 @@ export class ProviderHealthChecker {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push(`LiteLLM runtime check failed: ${failureReason}`);
             healthStatus.recommendations.push("Start the LiteLLM proxy and ensure the configured model is available from /v1/models");
-            return;
+            return { ran: true, failed: true };
         }
         healthStatus.isConfigured = true;
+        return { ran: true, failed: false };
     }
     /**
      * Check Ollama configuration
      */
-    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
+    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT, allowRuntimeProbe = true) {
         const ollamaBase = this.getOllamaBaseUrl();
         if (!ollamaBase.startsWith("http")) {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
             healthStatus.recommendations.push("Set OLLAMA_BASE_URL to a valid URL (e.g., http://localhost:11434). OLLAMA_API_BASE remains supported as a legacy alias.");
-            return;
+            return { ran: false, failed: false };
+        }
+        if (!allowRuntimeProbe) {
+            // Blacklisted: don't issue the request. A repeatedly unreachable
+            // local provider is not usable, which is what auto-select needs —
+            // but the caller's blacklist block (checkProviderHealth) already adds
+            // the error/warning/configurationIssue for this, so nothing is
+            // duplicated here.
+            healthStatus.isConfigured = false;
+            return { ran: false, failed: false };
         }
         const availability = await this.checkOllamaAvailability({
             model: this.getConfiguredOllamaModel(),
@@ -863,9 +978,10 @@ export class ProviderHealthChecker {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push(`Ollama runtime check failed: ${availability.reason ?? "unknown error"}`);
             healthStatus.recommendations.push("Start Ollama and install the configured model before using Ollama as a fallback provider");
-            return;
+            return { ran: true, failed: true };
         }
         healthStatus.isConfigured = true;
+        return { ran: true, failed: false };
     }
     /**
      * Get common models for a provider
@@ -1443,18 +1559,64 @@ export class ProviderHealthChecker {
         return null;
     }
     /**
-     * Get health status for all registered providers
+     * Get health status for all registered providers.
+     *
+     * Membership: every descriptor in PROVIDER_DESCRIPTORS EXCEPT those that
+     * explicitly opt out via `excludeFromHealthSweep` (none currently do).
+     * Before issue #1305's fix, membership was implicit opt-IN via
+     * `defaultHealthSweepPriority`, which only 8 of ~38 descriptors carried —
+     * every other registered provider was silently invisible to this sweep,
+     * including anything a caller had actually configured and could use.
+     *
+     * Order: `defaultHealthSweepPriority` still decides ORDER for the
+     * providers that set it (lower = first — order is behaviour for
+     * first-healthy-wins callers like `getBestHealthyProvider`); everything
+     * else sorts after them, in PROVIDER_DESCRIPTORS's own declaration order
+     * (Array.prototype.sort is stable, so ties never reshuffle).
+     *
+     * Checks run through a worker pool of at most
+     * MAX_CONCURRENT_HEALTH_CHECKS, so a full sweep of every provider can't
+     * fire dozens of concurrent requests at once when a caller opts into
+     * `includeConnectivityTest`, and no check waits on a slower one beside
+     * it.
      */
     static async checkAllProvidersHealth(options = {}) {
-        // Sweep membership and ORDER come from the descriptors. Order is
-        // behaviour: auto-select takes the first healthy provider, so the
-        // priority field, not the descriptor array's layout, decides preference.
-        const providers = PROVIDER_DESCRIPTORS.filter((d) => d.defaultHealthSweepPriority !== undefined)
-            .sort((a, b) => (a.defaultHealthSweepPriority ?? 0) -
-            (b.defaultHealthSweepPriority ?? 0))
+        const providers = PROVIDER_DESCRIPTORS.filter((d) => d.excludeFromHealthSweep !== true)
+            .sort((a, b) => (a.defaultHealthSweepPriority ?? Number.MAX_SAFE_INTEGER) -
+            (b.defaultHealthSweepPriority ?? Number.MAX_SAFE_INTEGER))
             .map((d) => d.name);
-        const healthChecks = providers.map((provider) => this.checkProviderHealth(provider, options));
-        const results = await Promise.allSettled(healthChecks);
+        // A fixed pool of workers pulling from a shared cursor, NOT
+        // chunk-and-await. Both bound concurrency to the same number, but
+        // chunking also makes every batch wait for its slowest member before
+        // the next one starts, so a sweep costs the SUM of the per-batch
+        // maxima. With `includeConnectivityTest` each check can burn the whole
+        // `timeout`, which turned a ~1x worst case into ~ceil(n/cap)x. Here a
+        // slot freed by a fast check immediately takes the next provider, so
+        // the bound costs nothing in latency.
+        const results = new Array(providers.length);
+        let cursor = 0;
+        const runWorker = async () => {
+            // `cursor++` is atomic here: there is no await between reading and
+            // incrementing, so two workers can never claim the same provider.
+            for (let index = cursor++; index < providers.length; index = cursor++) {
+                try {
+                    results[index] = {
+                        status: "fulfilled",
+                        value: await this.checkProviderHealth(providers[index], options),
+                    };
+                }
+                catch (reason) {
+                    results[index] = { status: "rejected", reason };
+                }
+            }
+        };
+        // Writing by index keeps results in provider order regardless of the
+        // order they complete in, which the rejected-case fallback below
+        // depends on. Zero providers means zero workers and an immediate
+        // return.
+        await Promise.all(Array.from({
+            length: Math.min(this.MAX_CONCURRENT_HEALTH_CHECKS, providers.length),
+        }, () => runWorker()));
         return results.map((result, index) => {
             if (result.status === "fulfilled") {
                 return result.value;

package/dist/utils/ttsProcessor.d.ts

@@ -6,7 +6,7 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSChunk, TTSOptions, TTSResult, TTSHandler } from "../types/index.js";
+import type { TTSChunk, TTSOptions, TTSResult, TTSHandler, TTSVoice } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { NeuroLinkError } from "./errorHandling.js";
 /**
@@ -128,6 +128,35 @@ export declare class TTSProcessor {
      * ```
      */
     static supports(providerName: string): boolean;
+    /**
+     * List the voices a registered provider offers.
+     *
+     * The counterpart to `synthesize()` for discovery: a caller cannot pass
+     * `TTSOptions.voice` without first knowing what the provider will accept,
+     * and `getVoices` is optional on `TTSHandler`, so asking the handler
+     * directly means every caller re-implements the same two guards. Both
+     * failures are reported as typed `TTSError`s rather than a `TypeError` on
+     * an absent member.
+     *
+     * `languageCode` is passed through verbatim; each handler decides what
+     * filtering it means. Google and Azure query their APIs with it, OpenAI's
+     * voice list is fixed and ignores it.
+     *
+     * @param providerName - Provider identifier, resolved case-insensitively
+     * @param options - Optional language filter
+     * @returns The provider's voices
+     * @throws TTSError if the provider is not registered or cannot list voices
+     *
+     * @example
+     * ```typescript
+     * const voices = await TTSProcessor.getVoices("google-ai", {
+     *   languageCode: "en-US",
+     * });
+     * ```
+     */
+    static getVoices(providerName: string, options?: {
+        languageCode?: string;
+    }): Promise<TTSVoice[]>;
     /**
      * Synthesize speech from text using a registered TTS provider
      *

package/dist/utils/ttsProcessor.js

@@ -323,6 +323,82 @@ export class TTSProcessor {
         }
         return isSupported;
     }
+    /**
+     * List the voices a registered provider offers.
+     *
+     * The counterpart to `synthesize()` for discovery: a caller cannot pass
+     * `TTSOptions.voice` without first knowing what the provider will accept,
+     * and `getVoices` is optional on `TTSHandler`, so asking the handler
+     * directly means every caller re-implements the same two guards. Both
+     * failures are reported as typed `TTSError`s rather than a `TypeError` on
+     * an absent member.
+     *
+     * `languageCode` is passed through verbatim; each handler decides what
+     * filtering it means. Google and Azure query their APIs with it, OpenAI's
+     * voice list is fixed and ignores it.
+     *
+     * @param providerName - Provider identifier, resolved case-insensitively
+     * @param options - Optional language filter
+     * @returns The provider's voices
+     * @throws TTSError if the provider is not registered or cannot list voices
+     *
+     * @example
+     * ```typescript
+     * const voices = await TTSProcessor.getVoices("google-ai", {
+     *   languageCode: "en-US",
+     * });
+     * ```
+     */
+    static async getVoices(providerName, options = {}) {
+        const handler = this.getHandler(providerName);
+        if (!handler) {
+            const registered = this.listProviders();
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${providerName}" is not registered. Registered providers: ${registered.length > 0 ? registered.join(", ") : "none"}`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { provider: providerName },
+            });
+        }
+        const listVoices = handler.getVoices;
+        if (typeof listVoices !== "function") {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${providerName}" does not support voice listing`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { provider: providerName },
+            });
+        }
+        // Same two guards synthesize() enforces, so getVoices() keeps the
+        // `@throws TTSError` contract above regardless of what a given handler's
+        // own implementation does: block on configuration before the handler
+        // runs at all, and shape whatever it throws through the same
+        // toSynthesisError() synthesize() uses, so `code`/`retriable`/category
+        // survive for a caller keying retry logic off them.
+        if (!handler.isConfigured()) {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: `TTS provider "${providerName}" is not configured. Please set the required API keys.`,
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { provider: providerName },
+            });
+        }
+        try {
+            return await listVoices.call(handler, options.languageCode);
+        }
+        catch (error) {
+            // `getVoices`'s own options ({ languageCode }) share no fields with
+            // `TTSOptions` — synthesize()'s options shape — so there is nothing
+            // meaningful to forward into toSynthesisError()'s context here.
+            throw this.toSynthesisError(error, providerName, "", {});
+        }
+    }
     /**
      * Synthesize speech from text using a registered TTS provider
      *