@juspay/neurolink 8.12.0 → 8.13.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [8.13.0](https://github.com/juspay/neurolink/compare/v8.12.0...v8.13.0) (2025-12-13)
+
+### Features
+
+- **(tts):** Implement TTSProcessor.synthesize() method ([d6f3567](https://github.com/juspay/neurolink/commit/d6f3567dda26191f0ca9fd82a8cd7ccff5c9f819))
+
 ## [8.12.0](https://github.com/juspay/neurolink/compare/v8.11.0...v8.12.0) (2025-12-13)
 
 ### Features

package/dist/lib/types/ttsTypes.d.ts

@@ -85,35 +85,6 @@ export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
  * Type guard to check if an object is a TTSResult
  */
 export declare function isTTSResult(value: unknown): value is TTSResult;
-/**
- * TTS Handler type for provider-specific implementations
- *
- * Each provider (Google AI, OpenAI, etc.) implements this type
- * to provide TTS generation capabilities using their respective APIs.
- */
-export type TTSHandler = {
-    /**
-     * Generate audio from text using provider-specific TTS API
-     *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
-     * @returns Audio buffer with metadata
-     */
-    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
-    /**
-     * Get available voices for the provider
-     *
-     * @param languageCode - Optional language filter (e.g., "en-US")
-     * @returns List of available voices
-     */
-    getVoices(languageCode?: string): Promise<TTSVoice[]>;
-    /**
-     * Validate that the provider is properly configured
-     *
-     * @returns True if provider can generate TTS
-     */
-    isConfigured(): boolean;
-};
 /**
  * Type guard to check if TTSOptions are valid
  */

package/dist/lib/utils/ttsProcessor.d.ts

@@ -6,7 +6,69 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSHandler } from "../types/ttsTypes.js";
+import type { TTSOptions, TTSResult, TTSVoice } from "../types/ttsTypes.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export declare const TTS_ERROR_CODES: {
+    readonly EMPTY_TEXT: "TTS_EMPTY_TEXT";
+    readonly TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG";
+    readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
+    readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
+    readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export declare class TTSError extends NeuroLinkError {
+    constructor(options: {
+        code: string;
+        message: string;
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+/**
+ * TTS Handler interface for provider-specific implementations
+ *
+ * Each provider (Google AI, OpenAI, etc.) implements this interface
+ * to provide TTS generation capabilities using their respective APIs.
+ */
+export interface TTSHandler {
+    /**
+     * Generate audio from text using provider-specific TTS API
+     *
+     * @param text - Text to convert to speech
+     * @param options - TTS configuration options
+     * @returns Audio buffer with metadata
+     */
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Get available voices for the provider
+     *
+     * @param languageCode - Optional language filter (e.g., "en-US")
+     * @returns List of available voices
+     */
+    getVoices?(languageCode?: string): Promise<TTSVoice[]>;
+    /**
+     * Validate that the provider is properly configured
+     *
+     * @returns True if provider can generate TTS
+     */
+    isConfigured(): boolean;
+    /**
+     * Maximum text length supported by this provider (in characters)
+     * Different providers have different limits
+     *
+     * @default 3000 if not specified
+     */
+    maxTextLength?: number;
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +94,26 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly handlers;
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @private
+     */
+    private static readonly DEFAULT_MAX_TEXT_LENGTH;
+    /**
+     * Default timeout for TTS synthesis operations (milliseconds)
+     *
+     * This timeout prevents indefinite hangs in provider API calls and serves as
+     * a safety net for all TTS operations. Individual handlers may implement
+     * shorter provider-specific timeouts.
+     *
+     * @private
+     */
+    private static readonly DEFAULT_SYNTHESIS_TIMEOUT_MS;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -74,4 +156,33 @@ export declare class TTSProcessor {
      * ```
      */
     static supports(providerName: string): boolean;
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 1. Validates input text (not empty, within length limits)
+     * 2. Looks up the provider handler
+     * 3. Verifies provider configuration
+     * 4. Delegates synthesis to the provider
+     * 5. Enriches result with metadata
+     *
+     * @param text - Text to convert to speech
+     * @param provider - Provider identifier
+     * @param options - TTS configuration options
+     * @returns Audio result with buffer and metadata
+     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
 }

package/dist/lib/utils/ttsProcessor.js

@@ -7,6 +7,35 @@
  * @module utils/ttsProcessor
  */
 import { logger } from "./logger.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export const TTS_ERROR_CODES = {
+    EMPTY_TEXT: "TTS_EMPTY_TEXT",
+    TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG",
+    PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
+    SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export class TTSError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.VALIDATION,
+            severity: options.severity ?? ErrorSeverity.MEDIUM,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "TTSError";
+    }
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +61,26 @@ export class TTSProcessor {
      * @private
      */
     static handlers = new Map();
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @private
+     */
+    static DEFAULT_MAX_TEXT_LENGTH = 3000;
+    /**
+     * Default timeout for TTS synthesis operations (milliseconds)
+     *
+     * This timeout prevents indefinite hangs in provider API calls and serves as
+     * a safety net for all TTS operations. Individual handlers may implement
+     * shorter provider-specific timeouts.
+     *
+     * @private
+     */
+    static DEFAULT_SYNTHESIS_TIMEOUT_MS = 60000;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -101,5 +150,138 @@ export class TTSProcessor {
         }
         return isSupported;
     }
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 1. Validates input text (not empty, within length limits)
+     * 2. Looks up the provider handler
+     * 3. Verifies provider configuration
+     * 4. Delegates synthesis to the provider
+     * 5. Enriches result with metadata
+     *
+     * @param text - Text to convert to speech
+     * @param provider - Provider identifier
+     * @param options - TTS configuration options
+     * @returns Audio result with buffer and metadata
+     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static async synthesize(text, provider, options) {
+        // Trim the text once at the start
+        const trimmedText = text.trim();
+        // 1. Text validation: reject empty text
+        if (!trimmedText) {
+            logger.error("[TTSProcessor] Text is required for synthesis");
+            throw new TTSError({
+                code: TTS_ERROR_CODES.EMPTY_TEXT,
+                message: "Text is required for TTS synthesis",
+                severity: ErrorSeverity.LOW,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        // 2. Handler lookup and error if provider not supported
+        const handler = this.getHandler(provider);
+        if (!handler) {
+            logger.error(`[TTSProcessor] Provider "${provider}" is not registered`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${provider}" is not supported. Use TTSProcessor.registerHandler() to register it.`,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    provider,
+                    availableProviders: Array.from(this.handlers.keys()),
+                },
+            });
+        }
+        // 3. Text validation: reject text exceeding provider-specific max length
+        const maxTextLength = handler.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH;
+        if (trimmedText.length > maxTextLength) {
+            logger.error(`[TTSProcessor] Text exceeds maximum length of ${maxTextLength} characters for provider "${provider}"`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.TEXT_TOO_LONG,
+                message: `Text length (${trimmedText.length}) exceeds maximum allowed length (${maxTextLength} characters) for provider "${provider}"`,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    maxLength: maxTextLength,
+                },
+            });
+        }
+        // 4. Configuration check
+        if (!handler.isConfigured()) {
+            logger.warn(`[TTSProcessor] Provider "${provider}" is not properly configured`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: `TTS provider "${provider}" is not configured. Please set the required API keys.`,
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        try {
+            logger.debug(`[TTSProcessor] Starting synthesis with provider: ${provider}`);
+            // 5. Call handler.synthesize() with timeout protection (60 second safety net)
+            const result = await withTimeout(handler.synthesize(trimmedText, options), this.DEFAULT_SYNTHESIS_TIMEOUT_MS, new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis timeout for provider "${provider}" after ${this.DEFAULT_SYNTHESIS_TIMEOUT_MS}ms`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    timeoutMs: this.DEFAULT_SYNTHESIS_TIMEOUT_MS,
+                    textLength: trimmedText.length,
+                },
+            }));
+            // 6. Post-processing: add metadata
+            const enrichedResult = {
+                ...result,
+                voice: result.voice ?? options.voice,
+            };
+            logger.info(`[TTSProcessor] Successfully synthesized ${result.size} bytes of audio`);
+            // 7. Returns TTSResult with buffer, format, metadata
+            return enrichedResult;
+        }
+        catch (err) {
+            // 8. Comprehensive error handling
+            // Re-throw TTSError as-is
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            // Wrap other errors in TTSError
+            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            logger.error(`[TTSProcessor] Synthesis failed for provider "${provider}": ${errorMessage}`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis failed for provider "${provider}": ${errorMessage}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    options,
+                },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
 }
 //# sourceMappingURL=ttsProcessor.js.map

package/dist/types/ttsTypes.d.ts

@@ -85,35 +85,6 @@ export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
  * Type guard to check if an object is a TTSResult
  */
 export declare function isTTSResult(value: unknown): value is TTSResult;
-/**
- * TTS Handler type for provider-specific implementations
- *
- * Each provider (Google AI, OpenAI, etc.) implements this type
- * to provide TTS generation capabilities using their respective APIs.
- */
-export type TTSHandler = {
-    /**
-     * Generate audio from text using provider-specific TTS API
-     *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
-     * @returns Audio buffer with metadata
-     */
-    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
-    /**
-     * Get available voices for the provider
-     *
-     * @param languageCode - Optional language filter (e.g., "en-US")
-     * @returns List of available voices
-     */
-    getVoices(languageCode?: string): Promise<TTSVoice[]>;
-    /**
-     * Validate that the provider is properly configured
-     *
-     * @returns True if provider can generate TTS
-     */
-    isConfigured(): boolean;
-};
 /**
  * Type guard to check if TTSOptions are valid
  */

package/dist/utils/ttsProcessor.d.ts

@@ -6,7 +6,69 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSHandler } from "../types/ttsTypes.js";
+import type { TTSOptions, TTSResult, TTSVoice } from "../types/ttsTypes.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export declare const TTS_ERROR_CODES: {
+    readonly EMPTY_TEXT: "TTS_EMPTY_TEXT";
+    readonly TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG";
+    readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
+    readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
+    readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export declare class TTSError extends NeuroLinkError {
+    constructor(options: {
+        code: string;
+        message: string;
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+/**
+ * TTS Handler interface for provider-specific implementations
+ *
+ * Each provider (Google AI, OpenAI, etc.) implements this interface
+ * to provide TTS generation capabilities using their respective APIs.
+ */
+export interface TTSHandler {
+    /**
+     * Generate audio from text using provider-specific TTS API
+     *
+     * @param text - Text to convert to speech
+     * @param options - TTS configuration options
+     * @returns Audio buffer with metadata
+     */
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Get available voices for the provider
+     *
+     * @param languageCode - Optional language filter (e.g., "en-US")
+     * @returns List of available voices
+     */
+    getVoices?(languageCode?: string): Promise<TTSVoice[]>;
+    /**
+     * Validate that the provider is properly configured
+     *
+     * @returns True if provider can generate TTS
+     */
+    isConfigured(): boolean;
+    /**
+     * Maximum text length supported by this provider (in characters)
+     * Different providers have different limits
+     *
+     * @default 3000 if not specified
+     */
+    maxTextLength?: number;
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +94,26 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly handlers;
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @private
+     */
+    private static readonly DEFAULT_MAX_TEXT_LENGTH;
+    /**
+     * Default timeout for TTS synthesis operations (milliseconds)
+     *
+     * This timeout prevents indefinite hangs in provider API calls and serves as
+     * a safety net for all TTS operations. Individual handlers may implement
+     * shorter provider-specific timeouts.
+     *
+     * @private
+     */
+    private static readonly DEFAULT_SYNTHESIS_TIMEOUT_MS;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -74,4 +156,33 @@ export declare class TTSProcessor {
      * ```
      */
     static supports(providerName: string): boolean;
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 1. Validates input text (not empty, within length limits)
+     * 2. Looks up the provider handler
+     * 3. Verifies provider configuration
+     * 4. Delegates synthesis to the provider
+     * 5. Enriches result with metadata
+     *
+     * @param text - Text to convert to speech
+     * @param provider - Provider identifier
+     * @param options - TTS configuration options
+     * @returns Audio result with buffer and metadata
+     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
 }

package/dist/utils/ttsProcessor.js

@@ -7,6 +7,35 @@
  * @module utils/ttsProcessor
  */
 import { logger } from "./logger.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export const TTS_ERROR_CODES = {
+    EMPTY_TEXT: "TTS_EMPTY_TEXT",
+    TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG",
+    PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
+    SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export class TTSError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.VALIDATION,
+            severity: options.severity ?? ErrorSeverity.MEDIUM,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "TTSError";
+    }
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +61,26 @@ export class TTSProcessor {
      * @private
      */
     static handlers = new Map();
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @private
+     */
+    static DEFAULT_MAX_TEXT_LENGTH = 3000;
+    /**
+     * Default timeout for TTS synthesis operations (milliseconds)
+     *
+     * This timeout prevents indefinite hangs in provider API calls and serves as
+     * a safety net for all TTS operations. Individual handlers may implement
+     * shorter provider-specific timeouts.
+     *
+     * @private
+     */
+    static DEFAULT_SYNTHESIS_TIMEOUT_MS = 60000;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -101,4 +150,137 @@ export class TTSProcessor {
         }
         return isSupported;
     }
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 1. Validates input text (not empty, within length limits)
+     * 2. Looks up the provider handler
+     * 3. Verifies provider configuration
+     * 4. Delegates synthesis to the provider
+     * 5. Enriches result with metadata
+     *
+     * @param text - Text to convert to speech
+     * @param provider - Provider identifier
+     * @param options - TTS configuration options
+     * @returns Audio result with buffer and metadata
+     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static async synthesize(text, provider, options) {
+        // Trim the text once at the start
+        const trimmedText = text.trim();
+        // 1. Text validation: reject empty text
+        if (!trimmedText) {
+            logger.error("[TTSProcessor] Text is required for synthesis");
+            throw new TTSError({
+                code: TTS_ERROR_CODES.EMPTY_TEXT,
+                message: "Text is required for TTS synthesis",
+                severity: ErrorSeverity.LOW,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        // 2. Handler lookup and error if provider not supported
+        const handler = this.getHandler(provider);
+        if (!handler) {
+            logger.error(`[TTSProcessor] Provider "${provider}" is not registered`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${provider}" is not supported. Use TTSProcessor.registerHandler() to register it.`,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    provider,
+                    availableProviders: Array.from(this.handlers.keys()),
+                },
+            });
+        }
+        // 3. Text validation: reject text exceeding provider-specific max length
+        const maxTextLength = handler.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH;
+        if (trimmedText.length > maxTextLength) {
+            logger.error(`[TTSProcessor] Text exceeds maximum length of ${maxTextLength} characters for provider "${provider}"`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.TEXT_TOO_LONG,
+                message: `Text length (${trimmedText.length}) exceeds maximum allowed length (${maxTextLength} characters) for provider "${provider}"`,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    maxLength: maxTextLength,
+                },
+            });
+        }
+        // 4. Configuration check
+        if (!handler.isConfigured()) {
+            logger.warn(`[TTSProcessor] Provider "${provider}" is not properly configured`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: `TTS provider "${provider}" is not configured. Please set the required API keys.`,
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        try {
+            logger.debug(`[TTSProcessor] Starting synthesis with provider: ${provider}`);
+            // 5. Call handler.synthesize() with timeout protection (60 second safety net)
+            const result = await withTimeout(handler.synthesize(trimmedText, options), this.DEFAULT_SYNTHESIS_TIMEOUT_MS, new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis timeout for provider "${provider}" after ${this.DEFAULT_SYNTHESIS_TIMEOUT_MS}ms`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    timeoutMs: this.DEFAULT_SYNTHESIS_TIMEOUT_MS,
+                    textLength: trimmedText.length,
+                },
+            }));
+            // 6. Post-processing: add metadata
+            const enrichedResult = {
+                ...result,
+                voice: result.voice ?? options.voice,
+            };
+            logger.info(`[TTSProcessor] Successfully synthesized ${result.size} bytes of audio`);
+            // 7. Returns TTSResult with buffer, format, metadata
+            return enrichedResult;
+        }
+        catch (err) {
+            // 8. Comprehensive error handling
+            // Re-throw TTSError as-is
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            // Wrap other errors in TTSError
+            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            logger.error(`[TTSProcessor] Synthesis failed for provider "${provider}": ${errorMessage}`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis failed for provider "${provider}": ${errorMessage}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    options,
+                },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.12.0",
+  "version": "8.13.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 9 major providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",