@ssml-builder-js/azure-tts-client 2.18.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssml-builder-js/azure-tts-client",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "Azure Text-to-Speech client using the Microsoft Speech SDK",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@ssml-builder-js/ssml-core": "^2.18.0",
+    "@ssml-builder-js/ssml-core": "^2.19.0",
     "microsoft-cognitiveservices-speech-sdk": "1.51.0"
   }
 }

package/src/client.ts

@@ -19,7 +19,16 @@ export class AzureTtsClient {
   }
 
   async synthesize(ssml: string): Promise<ArrayBuffer> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     this.#options.logger?.debug?.("Using Azure TTS endpoint:", endpoint);
 
@@ -32,12 +41,23 @@ export class AzureTtsClient {
       timeoutMs,
       timeouts,
       retryOptions: this.#options.retryOptions,
+      customHeaders,
+      fingerprintSchemaVersion,
     };
     return synthesizeSpeech(ssml, config);
   }
 
   async synthesizeSsml(ssml: string, options: Partial<TtsConfig> = {}): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     this.#options.logger?.debug?.("Using Azure TTS endpoint:", endpoint);
 
@@ -58,6 +78,8 @@ export class AzureTtsClient {
       outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
       postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
       resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion,
     });
   }
 
@@ -65,7 +87,16 @@ export class AzureTtsClient {
     chunks: readonly (SsmlSynthesisChunk | string)[],
     options: SynthesizeChunksOptions = {},
   ): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     return synthesizeSsmlChunks(chunks, {
       endpoint,
@@ -86,6 +117,8 @@ export class AzureTtsClient {
       outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
       postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
       resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion,
     });
   }
 
@@ -106,6 +139,13 @@ export class AzureTtsClient {
       onProgress: options.onProgress ?? this.#options.onProgress,
       concurrency: options.concurrency ?? this.#options.concurrency,
       retryOptions: options.retryOptions ?? this.#options.retryOptions,
+      cancelOnFailure: options.cancelOnFailure ?? this.#options.cancelOnFailure,
+      customMerger: options.customMerger ?? this.#options.customMerger,
+      outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
+      resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? this.#options.customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? this.#options.fingerprintSchemaVersion,
     });
   }
 

package/src/deadline.ts

@@ -0,0 +1,52 @@
+import { SynthesisTimeoutError } from "./errors.ts";
+
+/** Coordinates one absolute deadline across validation, synthesis, retries, and merging. */
+export class DeadlineController {
+  readonly deadlineAtMs: number | undefined;
+  readonly signal: AbortSignal;
+  readonly #controller = new AbortController();
+  readonly #parent?: AbortSignal;
+  readonly #onParentAbort: () => void;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  #timedOut = false;
+
+  constructor(totalJobMs: number | undefined, parent?: AbortSignal) {
+    this.#parent = parent;
+    this.#onParentAbort = () => this.#controller.abort();
+    this.deadlineAtMs = totalJobMs !== undefined && totalJobMs > 0 ? Date.now() + totalJobMs : undefined;
+    this.signal = this.deadlineAtMs === undefined && parent ? parent : this.#controller.signal;
+    if (parent?.aborted) this.#controller.abort();
+    parent?.addEventListener("abort", this.#onParentAbort, { once: true });
+    if (this.deadlineAtMs !== undefined) {
+      this.#timer = setTimeout(
+        () => {
+          this.#timedOut = true;
+          this.#controller.abort();
+        },
+        Math.max(0, this.deadlineAtMs - Date.now()),
+      );
+    }
+  }
+
+  get timedOut(): boolean {
+    return this.#timedOut || (this.deadlineAtMs !== undefined && this.remainingMs <= 0);
+  }
+
+  get remainingMs(): number {
+    return this.deadlineAtMs === undefined ? Number.POSITIVE_INFINITY : Math.max(0, this.deadlineAtMs - Date.now());
+  }
+
+  throwIfExpired(): void {
+    if (this.timedOut) throw new SynthesisTimeoutError("Speech synthesis exceeded the total job deadline.");
+    if (this.signal.aborted) throw new Error("Speech synthesis was cancelled.");
+  }
+
+  abort(): void {
+    this.#controller.abort();
+  }
+
+  dispose(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#parent?.removeEventListener("abort", this.#onParentAbort);
+  }
+}

package/src/errors.ts

@@ -5,7 +5,29 @@ export type SynthesisErrorKind =
   | "audio-format-mismatch"
   | "unsupported-format-error"
   | "cancelled"
-  | "timeout";
+  | "timeout"
+  | "incomplete-chunk-set";
+
+export type SerializedChunkErrorCode =
+  | "VALIDATION_ERROR"
+  | "AZURE_API_ERROR"
+  | "TIMEOUT"
+  | "CANCELLED"
+  | "MERGE_ERROR"
+  | "FORMAT_MISMATCH";
+
+export interface SerializedChunkError {
+  code: SerializedChunkErrorCode;
+  phase: "url-validation" | "synthesis" | "merge";
+  message: string;
+  isOriginalFailure: boolean;
+  isRetryable: boolean;
+  httpStatus?: number;
+  details?: Record<string, unknown>;
+}
+
+/** Backward-compatible name used by persisted execution-state consumers. */
+export type SerializedExecutionError = SerializedChunkError;
 
 export class AzureTtsError extends Error {
   readonly kind = "azure-api-error" as const;
@@ -95,6 +117,19 @@ export class SynthesisTimeoutError extends Error {
   }
 }
 
+export class IncompleteChunkSetError extends Error {
+  readonly kind = "incomplete-chunk-set" as const;
+  readonly totalChunks: number;
+  readonly missingChunkIndices: readonly number[];
+
+  constructor(totalChunks: number, missingChunkIndices: readonly number[]) {
+    super(`Cannot merge an incomplete chunk set; missing chunk indices: ${missingChunkIndices.join(", ")}.`);
+    this.name = "IncompleteChunkSetError";
+    this.totalChunks = totalChunks;
+    this.missingChunkIndices = [...missingChunkIndices];
+  }
+}
+
 export class MergeError extends Error {
   readonly kind = "merge-error" as const;
   readonly cause: unknown;
@@ -136,7 +171,52 @@ export type AzureTtsSynthesisError =
   | AudioFormatMismatchError
   | UnsupportedMergeFormatError
   | SynthesisCancelledError
-  | SynthesisTimeoutError;
+  | SynthesisTimeoutError
+  | IncompleteChunkSetError;
+
+export function serializeChunkError(
+  error: unknown,
+  phase: SerializedChunkError["phase"],
+  isOriginalFailure: boolean,
+): SerializedChunkError {
+  const message = error instanceof Error ? error.message : String(error);
+  const status = error instanceof AzureTtsError ? error.status : undefined;
+  const kind = error && typeof error === "object" && "kind" in error ? String(error.kind) : "";
+  const code: SerializedChunkErrorCode =
+    kind === "validation-error"
+      ? "VALIDATION_ERROR"
+      : kind === "timeout" || /tim(?:e|ed) ?out|deadline/i.test(message)
+        ? "TIMEOUT"
+        : kind === "cancelled" || /cancel|abort/i.test(message)
+          ? "CANCELLED"
+          : kind === "audio-format-mismatch" || kind === "unsupported-format-error"
+            ? "FORMAT_MISMATCH"
+            : kind === "merge-error" || phase === "merge"
+              ? "MERGE_ERROR"
+              : "AZURE_API_ERROR";
+  const details: Record<string, unknown> = {};
+  if (error instanceof AzureTtsError) {
+    details.statusText = error.statusText;
+    if (error.requestId) details.requestId = error.requestId;
+  }
+  if (error instanceof IncompleteChunkSetError) {
+    details.totalChunks = error.totalChunks;
+    details.missingChunkIndices = [...error.missingChunkIndices];
+  }
+  return {
+    code,
+    phase,
+    message,
+    isOriginalFailure,
+    isRetryable:
+      code === "AZURE_API_ERROR" &&
+      (status === 429 ||
+        (status !== undefined && status >= 500) ||
+        /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message)),
+    ...(status !== undefined && status > 0 ? { httpStatus: status } : {}),
+    ...(Object.keys(details).length > 0 ? { details } : {}),
+  };
+}
 
 export function toSynthesisError(
   error: unknown,
@@ -146,14 +226,16 @@ export function toSynthesisError(
   | AudioFormatMismatchError
   | UnsupportedMergeFormatError
   | SynthesisCancelledError
-  | SynthesisTimeoutError {
+  | SynthesisTimeoutError
+  | IncompleteChunkSetError {
   if (
     error instanceof AzureTtsError ||
     error instanceof MergeError ||
     error instanceof AudioFormatMismatchError ||
     error instanceof UnsupportedMergeFormatError ||
     error instanceof SynthesisCancelledError ||
-    error instanceof SynthesisTimeoutError
+    error instanceof SynthesisTimeoutError ||
+    error instanceof IncompleteChunkSetError
   )
     return error;
   const message = error instanceof Error ? error.message : String(error);

package/src/index.ts

@@ -36,10 +36,19 @@ export {
   MergeError,
   SynthesisCancelledError,
   SynthesisTimeoutError,
+  IncompleteChunkSetError,
+  serializeChunkError,
   UnsupportedMergeFormatError,
   getRetryAfterDelayMs,
 } from "./errors.ts";
-export type { AzureTtsSynthesisError, SynthesisErrorKind } from "./errors.ts";
+export type {
+  AzureTtsSynthesisError,
+  SerializedChunkError,
+  SerializedChunkErrorCode,
+  SerializedExecutionError,
+  SynthesisErrorKind,
+} from "./errors.ts";
+export { DeadlineController } from "./deadline.ts";
 export { AzureTtsClient } from "./client.ts";
 export { synthesizeSpeech } from "./synthesis.ts";
 export { synthesizeSsml } from "./synthesis.ts";
@@ -54,6 +63,7 @@ export {
 } from "./synthesis.ts";
 export type {
   InputAudioSpecs,
+  ChunkFingerprintOptions,
   MergeAudioFormat,
   MergeAudioOptions,
   MergeSynthesisOptions,

package/src/safe.ts

@@ -29,6 +29,8 @@ import type {
   ResumeValidationMode,
 } from "./types.ts";
 import type { AzureTtsOutputFormat } from "./outputFormats.ts";
+import { IncompleteChunkSetError, serializeChunkError } from "./errors.ts";
+import { DeadlineController } from "./deadline.ts";
 
 export interface SsmlValidationError {
   readonly kind: "validation-error";
@@ -129,6 +131,8 @@ export interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
 export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
   validation?: AzureValidationOptions;
   outputFormat?: string;
+  customHeaders?: Readonly<Record<string, string>>;
+  fingerprintSchemaVersion?: string;
   signal?: AbortSignal;
   timeoutMs?: number;
   timeouts?: SynthesisTimeouts;
@@ -303,14 +307,19 @@ export async function synthesizeSsmlSafe(
   ssml: string,
   options: SynthesizeSsmlSafeOptions = {},
 ): Promise<SsmlSynthesisSafeResult> {
-  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
+  const validationOptions = sharedValidationOptions(options.validation ?? options, deadline.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled."),
+    );
+    deadline.dispose();
     return failure(error);
   }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
+    deadline.dispose();
     return failure({
       kind: "validation-error",
       message: "SSML validation failed; the Azure Speech API was not called.",
@@ -318,27 +327,23 @@ export async function synthesizeSsmlSafe(
     });
   }
 
-  const jobScope =
-    options.timeouts?.totalJobMs !== undefined
-      ? createSafeAbortScope(options.signal, options.timeouts.totalJobMs)
-      : undefined;
   try {
     return {
       ok: true,
       success: true,
       status: "success",
       value: await client.synthesizeSsml(ssml, {
-        signal: jobScope?.signal ?? options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeouts?.perChunkMs,
-        timeouts: options.timeouts,
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: undefined } : undefined,
       }),
     };
   } catch (error) {
-    if (jobScope?.timedOut()) return failure(toSynthesisError(new Error("Speech synthesis timed out.")));
+    if (deadline.timedOut) return failure(toSynthesisError(new Error("Speech synthesis timed out.")));
     const synthesisError = toSynthesisError(error);
     return failure(synthesisError);
   } finally {
-    jobScope?.dispose();
+    deadline.dispose();
   }
 }
 
@@ -348,12 +353,16 @@ export async function synthesizeSsmlChunksSafe(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   options: SynthesizeSsmlChunksSafeOptions = {},
 ): Promise<SsmlSynthesisChunksSafeResult> {
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
   const validationOptions = sharedValidationOptions(
     { ...(options.validation ?? options), timeouts: options.timeouts },
-    options.signal,
+    deadline.signal,
   );
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled."),
+    );
+    deadline.dispose();
     return failure(error);
   }
   const pending = (index: number, status: SynthesisProgressEvent["status"], error?: unknown): void => {
@@ -387,8 +396,9 @@ export async function synthesizeSsmlChunksSafe(
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     }),
   );
-  if (options.signal?.aborted) {
+  if (deadline.signal.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    deadline.dispose();
     return failure(error);
   }
   const chunkDiagnostics = validations
@@ -397,6 +407,7 @@ export async function synthesizeSsmlChunksSafe(
   if (chunkDiagnostics.length > 0) {
     const error = new BatchChunkValidationError(chunkDiagnostics);
     for (const entry of chunkDiagnostics) pending(entry.chunkIndex, "failed", error);
+    deadline.dispose();
     return failure(error);
   }
 
@@ -410,9 +421,9 @@ export async function synthesizeSsmlChunksSafe(
       const value = await client.synthesizeChunks(normalizedChunks, {
         onProgress: options.onProgress,
         outputFormat: options.outputFormat,
-        signal: options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeoutMs,
-        timeouts: options.timeouts,
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: undefined } : undefined,
         sourceNodePath: options.sourceNodePath,
         concurrency: options.concurrency,
         retryOptions: options.retryOptions,
@@ -423,11 +434,18 @@ export async function synthesizeSsmlChunksSafe(
         outputMimeType: options.outputMimeType,
         postMergeValidator: options.postMergeValidator,
         resumeValidation: options.resumeValidation,
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion,
       });
       return { ok: true, success: true, status: "success", value };
     }
     const inputs = chunks.map((chunk) => (typeof chunk === "string" ? { ssml: chunk } : chunk));
-    const fingerprints = inputs.map((chunk) => computeChunkFingerprint(chunk.ssml, options.outputFormat));
+    const fingerprints = inputs.map((chunk) =>
+      computeChunkFingerprint(chunk.ssml, options.outputFormat, {
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion,
+      }),
+    );
     const results: Array<SsmlSynthesisResult | undefined> = new Array(chunks.length);
     const chunkStates: ChunkExecutionState[] = inputs.map((_chunk, chunkIndex) => ({
       chunkIndex,
@@ -449,14 +467,10 @@ export async function synthesizeSsmlChunksSafe(
     const shouldSynthesize = (index: number): boolean =>
       (!cachedChunks.has(index) || invalidCachedIndices.has(index)) &&
       (requestedIndices === undefined || requestedIndices.has(index) || invalidCachedIndices.has(index));
-    const jobStartedAt = Date.now();
-    const jobDeadlineAt =
-      options.timeouts?.totalJobMs !== undefined && options.timeouts.totalJobMs > 0
-        ? jobStartedAt + options.timeouts.totalJobMs
-        : undefined;
+    const jobDeadlineAt = deadline.deadlineAtMs;
     const jobScope =
       chunks.length > 1 || options.timeouts?.totalJobMs !== undefined
-        ? createSafeAbortScope(options.signal, options.timeouts?.totalJobMs)
+        ? createSafeAbortScope(deadline.signal, undefined)
         : undefined;
     fallbackJobScope = jobScope;
     const failedIndices = new Set<number>();
@@ -483,9 +497,9 @@ export async function synthesizeSsmlChunksSafe(
           const chunkTimeout = options.timeouts?.chunkWithRetriesMs ?? options.timeouts?.perChunkMs;
           const chunkScope =
             chunkTimeout !== undefined || jobScope
-              ? createSafeAbortScope(jobScope?.signal ?? options.signal, chunkTimeout ?? options.timeoutMs)
+              ? createSafeAbortScope(jobScope?.signal ?? deadline.signal, chunkTimeout ?? options.timeoutMs)
               : undefined;
-          const chunkSignal = chunkScope?.signal ?? options.signal;
+          const chunkSignal = chunkScope?.signal ?? deadline.signal;
           let result: SsmlSynthesisResult;
           try {
             result = await retryableSynthesis(
@@ -514,7 +528,7 @@ export async function synthesizeSsmlChunksSafe(
               jobDeadlineAt,
             );
           } catch (error) {
-            if (chunkScope?.timedOut())
+            if (chunkScope?.timedOut() || deadline.timedOut)
               throw new Error(`Speech synthesis timed out after ${chunkTimeout ?? options.timeoutMs} ms.`);
             throw error;
           } finally {
@@ -601,15 +615,17 @@ export async function synthesizeSsmlChunksSafe(
             durationMs: Date.now() - startedAt,
           });
         } catch (error) {
-          const wasCancelled = firstError !== undefined || Boolean(jobScope?.signal.aborted && !jobScope?.timedOut());
-          firstError ??= error;
+          const wasCancelled =
+            firstError !== undefined ||
+            (!deadline.timedOut && Boolean(jobScope?.signal.aborted && !jobScope?.timedOut()));
+          firstError ??= deadline.timedOut ? new Error("Speech synthesis timed out.") : error;
           if (!wasCancelled) failedIndices.add(index);
           chunkStates[index] = {
             chunkIndex: index,
             status: wasCancelled ? "cancelled" : "failed",
             isOriginalFailure: !wasCancelled,
             canResume: true,
-            error: error as ChunkExecutionState["error"],
+            error: serializeChunkError(error, "synthesis", !wasCancelled),
           };
           options.onProgress?.({
             currentChunk: completed,
@@ -656,6 +672,10 @@ export async function synthesizeSsmlChunksSafe(
       };
       throw error;
     }
+    const missingChunkIndices = Array.from({ length: chunks.length }, (_value, index) =>
+      results[index] === undefined ? index : undefined,
+    ).filter((index): index is number => index !== undefined);
+    if (missingChunkIndices.length > 0) throw new IncompleteChunkSetError(chunks.length, missingChunkIndices);
     const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
     return {
       ok: true,
@@ -663,7 +683,7 @@ export async function synthesizeSsmlChunksSafe(
       status: "success",
       value: await mergeSynthesisResults(orderedResults, {
         format: (options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3") as AzureTtsOutputFormat,
-        signal: jobScope?.signal ?? options.signal,
+        signal: jobScope?.signal ?? deadline.signal,
         customMerger: options.customMerger,
         outputMimeType: options.outputMimeType,
         postMergeValidator: options.postMergeValidator,
@@ -674,6 +694,7 @@ export async function synthesizeSsmlChunksSafe(
     return failure(synthesisError, partialResultFrom(error));
   } finally {
     fallbackJobScope?.dispose();
+    deadline.dispose();
   }
 }