@juspay/neurolink 8.14.0 → 8.15.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [8.15.0](https://github.com/juspay/neurolink/compare/v8.14.0...v8.15.0) (2025-12-14)
+
+### Features
+
+- **(tts):** Implement synthesize method in GoogleTTSHandler ([9262e37](https://github.com/juspay/neurolink/commit/9262e37a08ef856eb5d16fd65fa922bd700897cb))
+
 ## [8.14.0](https://github.com/juspay/neurolink/compare/v8.13.2...v8.14.0) (2025-12-14)
 
 ### Features

package/dist/adapters/tts/googleTTSHandler.d.ts

@@ -1,35 +1,28 @@
-/**
- * Google Cloud Text-to-Speech Handler
- *
- * Handler for Google Cloud Text-to-Speech API integration.
- * Supports Neural2 and WaveNet voice models with 220+ voices across 40+ languages.
- *
- * @module adapters/tts/googleTTSHandler
- * @see https://cloud.google.com/text-to-speech/docs
- */
 import type { TTSHandler } from "../../utils/ttsProcessor.js";
 import type { TTSOptions, TTSResult, TTSVoice } from "../../types/ttsTypes.js";
-/**
- * Google Cloud TTS handler implementation
- *
- * Integrates with Google Cloud Text-to-Speech API for voice synthesis.
- * Supports authentication via:
- *   - Explicit service account JSON key path
- *   - GOOGLE_APPLICATION_CREDENTIALS environment variable
- */
 export declare class GoogleTTSHandler implements TTSHandler {
     private client;
     /**
-     * Maximum text length supported by Google Cloud TTS (5000 bytes)
-     * Different providers have different limits
+     * Google Cloud TTS maximum input size.
+     * ~5000 bytes INCLUDING SSML tags.
      */
     private static readonly DEFAULT_MAX_TEXT_LENGTH;
-    maxTextLength: number;
     /**
-     * Constructor for GoogleTTSHandler
+     * Default timeout for Google Cloud TTS API calls (milliseconds)
      *
-     * @param credentialsPath - Optional path to Google Cloud credentials JSON file
+     * Google typically responds within:
+     * - 1–5 seconds for short or normal text
+     * - 5–10 seconds for longer text or Neural2 voices
      */
+    private static readonly DEFAULT_API_TIMEOUT_MS;
+    /**
+     * Maximum text length supported by Google Cloud TTS (in bytes).
+     *
+     * NOTE:
+     * Validation against this limit is performed by the shared TTS processor
+     * before invoking provider handlers, not inside this class.
+     */
+    readonly maxTextLength: number;
     constructor(credentialsPath?: string);
     /**
      * Validate that the provider is properly configured
@@ -42,6 +35,7 @@ export declare class GoogleTTSHandler implements TTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
+     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
@@ -50,9 +44,27 @@ export declare class GoogleTTSHandler implements TTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
+     * @param text - Text or SSML to convert to speech
      * @param options - TTS configuration options
      * @returns Audio buffer with metadata
      */
-    synthesize(_text: string, _options: TTSOptions): Promise<TTSResult>;
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Extract language code from a Google Cloud voice name
+     *
+     * Example:
+     *   "en-US-Neural2-C" -> "en-US"
+     *
+     * @param voiceId - Google Cloud voice identifier
+     * @returns Language code compatible with Google TTS
+     */
+    private extractLanguageCode;
+    /**
+     * Map application audio format to Google Cloud audio encoding
+     *
+     * @param format - Audio format requested by the caller
+     * @returns Google Cloud AudioEncoding enum value
+     * @throws Error if format is unsupported
+     */
+    private mapFormat;
 }

package/dist/adapters/tts/googleTTSHandler.js

@@ -2,33 +2,36 @@
  * Google Cloud Text-to-Speech Handler
  *
  * Handler for Google Cloud Text-to-Speech API integration.
- * Supports Neural2 and WaveNet voice models with 220+ voices across 40+ languages.
  *
  * @module adapters/tts/googleTTSHandler
  * @see https://cloud.google.com/text-to-speech/docs
  */
 import { TextToSpeechClient } from "@google-cloud/text-to-speech";
-/**
- * Google Cloud TTS handler implementation
- *
- * Integrates with Google Cloud Text-to-Speech API for voice synthesis.
- * Supports authentication via:
- *   - Explicit service account JSON key path
- *   - GOOGLE_APPLICATION_CREDENTIALS environment variable
- */
+import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 export class GoogleTTSHandler {
     client = null;
     /**
-     * Maximum text length supported by Google Cloud TTS (5000 bytes)
-     * Different providers have different limits
+     * Google Cloud TTS maximum input size.
+     * ~5000 bytes INCLUDING SSML tags.
      */
     static DEFAULT_MAX_TEXT_LENGTH = 5000;
-    maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
     /**
-     * Constructor for GoogleTTSHandler
+     * Default timeout for Google Cloud TTS API calls (milliseconds)
+     *
+     * Google typically responds within:
+     * - 1–5 seconds for short or normal text
+     * - 5–10 seconds for longer text or Neural2 voices
+     */
+    static DEFAULT_API_TIMEOUT_MS = 30 * 1000;
+    /**
+     * Maximum text length supported by Google Cloud TTS (in bytes).
      *
-     * @param credentialsPath - Optional path to Google Cloud credentials JSON file
+     * NOTE:
+     * Validation against this limit is performed by the shared TTS processor
+     * before invoking provider handlers, not inside this class.
      */
+    maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
     constructor(credentialsPath) {
         const path = credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
         if (path) {
@@ -41,13 +44,14 @@ export class GoogleTTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured() {
-        throw new Error("Not implemented yet");
+        return this.client !== null;
     }
     /**
      * Get available voices for the provider
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
+     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
@@ -58,11 +62,158 @@ export class GoogleTTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
+     * @param text - Text or SSML to convert to speech
      * @param options - TTS configuration options
      * @returns Audio buffer with metadata
      */
-    async synthesize(_text, _options) {
-        throw new Error("Not implemented yet");
+    async synthesize(text, options) {
+        if (!this.client) {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        const startTime = Date.now();
+        try {
+            const isSSML = text.startsWith("<speak>") && text.endsWith("</speak>");
+            // Note: This validation only checks for the presence of opening and closing <speak> tags.
+            // Other SSML validation, such as malformed structure, unclosed inner tags, or invalid elements,
+            // will be handled by Google's API.
+            if ((text.startsWith("<speak>") && !text.endsWith("</speak>")) ||
+                (!text.startsWith("<speak>") && text.endsWith("</speak>"))) {
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.INVALID_INPUT,
+                    message: "Malformed SSML: missing opening <speak> or closing </speak> tag.",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                });
+            }
+            const voiceId = options.voice ?? "en-US-Neural2-C";
+            const languageCode = this.extractLanguageCode(voiceId);
+            const audioEncoding = this.mapFormat(options.format ?? "mp3");
+            const request = {
+                input: isSSML ? { ssml: text } : { text },
+                voice: {
+                    name: voiceId,
+                    languageCode,
+                },
+                audioConfig: {
+                    audioEncoding,
+                    speakingRate: options.speed ?? 1.0,
+                    pitch: options.pitch ?? 0.0,
+                    volumeGainDb: options.volumeGainDb ?? 0.0,
+                },
+            };
+            const [response] = await this.client.synthesizeSpeech(request, {
+                timeout: GoogleTTSHandler.DEFAULT_API_TIMEOUT_MS,
+            });
+            const audioContent = response.audioContent;
+            if (!audioContent) {
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                    message: "Google TTS returned empty audio content",
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                });
+            }
+            const buffer = audioContent instanceof Uint8Array
+                ? Buffer.from(audioContent)
+                : typeof audioContent === "string"
+                    ? Buffer.from(audioContent, "base64")
+                    : (() => {
+                        throw new TTSError({
+                            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                            message: "Unsupported audioContent type returned by Google TTS",
+                            category: ErrorCategory.EXECUTION,
+                            severity: ErrorSeverity.HIGH,
+                            retriable: true,
+                            context: { type: typeof audioContent },
+                        });
+                    })();
+            const latency = Date.now() - startTime;
+            return {
+                buffer,
+                format: options.format ?? "mp3",
+                size: buffer.length,
+                voice: voiceId,
+                metadata: {
+                    latency,
+                    provider: "google-ai",
+                },
+            };
+        }
+        catch (err) {
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            const latency = Date.now() - startTime;
+            const message = err instanceof Error ? err.message : "Unknown error";
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `Google TTS failed after ${latency}ms: ${message}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: { latency },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+    /**
+     * Extract language code from a Google Cloud voice name
+     *
+     * Example:
+     *   "en-US-Neural2-C" -> "en-US"
+     *
+     * @param voiceId - Google Cloud voice identifier
+     * @returns Language code compatible with Google TTS
+     */
+    extractLanguageCode(voiceId) {
+        const parts = voiceId.split("-");
+        if (parts.length >= 2) {
+            return `${parts[0]}-${parts[1]}`;
+        }
+        else {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.INVALID_INPUT,
+                message: `Invalid Google TTS voiceId format: "${voiceId}". Expected format like "en-US-Neural2-C".`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { voiceId },
+            });
+        }
+    }
+    /**
+     * Map application audio format to Google Cloud audio encoding
+     *
+     * @param format - Audio format requested by the caller
+     * @returns Google Cloud AudioEncoding enum value
+     * @throws Error if format is unsupported
+     */
+    mapFormat(format) {
+        switch (format.toLowerCase()) {
+            case "mp3":
+                return "MP3";
+            case "wav":
+                return "LINEAR16";
+            case "ogg":
+            case "opus":
+                return "OGG_OPUS";
+            default:
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.INVALID_INPUT,
+                    message: `Unsupported audio format: ${format}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { format },
+                });
+        }
     }
 }

package/dist/lib/adapters/tts/googleTTSHandler.d.ts

@@ -1,35 +1,28 @@
-/**
- * Google Cloud Text-to-Speech Handler
- *
- * Handler for Google Cloud Text-to-Speech API integration.
- * Supports Neural2 and WaveNet voice models with 220+ voices across 40+ languages.
- *
- * @module adapters/tts/googleTTSHandler
- * @see https://cloud.google.com/text-to-speech/docs
- */
 import type { TTSHandler } from "../../utils/ttsProcessor.js";
 import type { TTSOptions, TTSResult, TTSVoice } from "../../types/ttsTypes.js";
-/**
- * Google Cloud TTS handler implementation
- *
- * Integrates with Google Cloud Text-to-Speech API for voice synthesis.
- * Supports authentication via:
- *   - Explicit service account JSON key path
- *   - GOOGLE_APPLICATION_CREDENTIALS environment variable
- */
 export declare class GoogleTTSHandler implements TTSHandler {
     private client;
     /**
-     * Maximum text length supported by Google Cloud TTS (5000 bytes)
-     * Different providers have different limits
+     * Google Cloud TTS maximum input size.
+     * ~5000 bytes INCLUDING SSML tags.
      */
     private static readonly DEFAULT_MAX_TEXT_LENGTH;
-    maxTextLength: number;
     /**
-     * Constructor for GoogleTTSHandler
+     * Default timeout for Google Cloud TTS API calls (milliseconds)
      *
-     * @param credentialsPath - Optional path to Google Cloud credentials JSON file
+     * Google typically responds within:
+     * - 1–5 seconds for short or normal text
+     * - 5–10 seconds for longer text or Neural2 voices
      */
+    private static readonly DEFAULT_API_TIMEOUT_MS;
+    /**
+     * Maximum text length supported by Google Cloud TTS (in bytes).
+     *
+     * NOTE:
+     * Validation against this limit is performed by the shared TTS processor
+     * before invoking provider handlers, not inside this class.
+     */
+    readonly maxTextLength: number;
     constructor(credentialsPath?: string);
     /**
      * Validate that the provider is properly configured
@@ -42,6 +35,7 @@ export declare class GoogleTTSHandler implements TTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
+     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
@@ -50,9 +44,27 @@ export declare class GoogleTTSHandler implements TTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
+     * @param text - Text or SSML to convert to speech
      * @param options - TTS configuration options
      * @returns Audio buffer with metadata
      */
-    synthesize(_text: string, _options: TTSOptions): Promise<TTSResult>;
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Extract language code from a Google Cloud voice name
+     *
+     * Example:
+     *   "en-US-Neural2-C" -> "en-US"
+     *
+     * @param voiceId - Google Cloud voice identifier
+     * @returns Language code compatible with Google TTS
+     */
+    private extractLanguageCode;
+    /**
+     * Map application audio format to Google Cloud audio encoding
+     *
+     * @param format - Audio format requested by the caller
+     * @returns Google Cloud AudioEncoding enum value
+     * @throws Error if format is unsupported
+     */
+    private mapFormat;
 }

package/dist/lib/adapters/tts/googleTTSHandler.js

@@ -2,33 +2,36 @@
  * Google Cloud Text-to-Speech Handler
  *
  * Handler for Google Cloud Text-to-Speech API integration.
- * Supports Neural2 and WaveNet voice models with 220+ voices across 40+ languages.
  *
  * @module adapters/tts/googleTTSHandler
  * @see https://cloud.google.com/text-to-speech/docs
  */
 import { TextToSpeechClient } from "@google-cloud/text-to-speech";
-/**
- * Google Cloud TTS handler implementation
- *
- * Integrates with Google Cloud Text-to-Speech API for voice synthesis.
- * Supports authentication via:
- *   - Explicit service account JSON key path
- *   - GOOGLE_APPLICATION_CREDENTIALS environment variable
- */
+import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 export class GoogleTTSHandler {
     client = null;
     /**
-     * Maximum text length supported by Google Cloud TTS (5000 bytes)
-     * Different providers have different limits
+     * Google Cloud TTS maximum input size.
+     * ~5000 bytes INCLUDING SSML tags.
      */
     static DEFAULT_MAX_TEXT_LENGTH = 5000;
-    maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
     /**
-     * Constructor for GoogleTTSHandler
+     * Default timeout for Google Cloud TTS API calls (milliseconds)
+     *
+     * Google typically responds within:
+     * - 1–5 seconds for short or normal text
+     * - 5–10 seconds for longer text or Neural2 voices
+     */
+    static DEFAULT_API_TIMEOUT_MS = 30 * 1000;
+    /**
+     * Maximum text length supported by Google Cloud TTS (in bytes).
      *
-     * @param credentialsPath - Optional path to Google Cloud credentials JSON file
+     * NOTE:
+     * Validation against this limit is performed by the shared TTS processor
+     * before invoking provider handlers, not inside this class.
      */
+    maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
     constructor(credentialsPath) {
         const path = credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
         if (path) {
@@ -41,13 +44,14 @@ export class GoogleTTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured() {
-        throw new Error("Not implemented yet");
+        return this.client !== null;
     }
     /**
      * Get available voices for the provider
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
+     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
@@ -58,12 +62,159 @@ export class GoogleTTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
+     * @param text - Text or SSML to convert to speech
      * @param options - TTS configuration options
      * @returns Audio buffer with metadata
      */
-    async synthesize(_text, _options) {
-        throw new Error("Not implemented yet");
+    async synthesize(text, options) {
+        if (!this.client) {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        const startTime = Date.now();
+        try {
+            const isSSML = text.startsWith("<speak>") && text.endsWith("</speak>");
+            // Note: This validation only checks for the presence of opening and closing <speak> tags.
+            // Other SSML validation, such as malformed structure, unclosed inner tags, or invalid elements,
+            // will be handled by Google's API.
+            if ((text.startsWith("<speak>") && !text.endsWith("</speak>")) ||
+                (!text.startsWith("<speak>") && text.endsWith("</speak>"))) {
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.INVALID_INPUT,
+                    message: "Malformed SSML: missing opening <speak> or closing </speak> tag.",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                });
+            }
+            const voiceId = options.voice ?? "en-US-Neural2-C";
+            const languageCode = this.extractLanguageCode(voiceId);
+            const audioEncoding = this.mapFormat(options.format ?? "mp3");
+            const request = {
+                input: isSSML ? { ssml: text } : { text },
+                voice: {
+                    name: voiceId,
+                    languageCode,
+                },
+                audioConfig: {
+                    audioEncoding,
+                    speakingRate: options.speed ?? 1.0,
+                    pitch: options.pitch ?? 0.0,
+                    volumeGainDb: options.volumeGainDb ?? 0.0,
+                },
+            };
+            const [response] = await this.client.synthesizeSpeech(request, {
+                timeout: GoogleTTSHandler.DEFAULT_API_TIMEOUT_MS,
+            });
+            const audioContent = response.audioContent;
+            if (!audioContent) {
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                    message: "Google TTS returned empty audio content",
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                });
+            }
+            const buffer = audioContent instanceof Uint8Array
+                ? Buffer.from(audioContent)
+                : typeof audioContent === "string"
+                    ? Buffer.from(audioContent, "base64")
+                    : (() => {
+                        throw new TTSError({
+                            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                            message: "Unsupported audioContent type returned by Google TTS",
+                            category: ErrorCategory.EXECUTION,
+                            severity: ErrorSeverity.HIGH,
+                            retriable: true,
+                            context: { type: typeof audioContent },
+                        });
+                    })();
+            const latency = Date.now() - startTime;
+            return {
+                buffer,
+                format: options.format ?? "mp3",
+                size: buffer.length,
+                voice: voiceId,
+                metadata: {
+                    latency,
+                    provider: "google-ai",
+                },
+            };
+        }
+        catch (err) {
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            const latency = Date.now() - startTime;
+            const message = err instanceof Error ? err.message : "Unknown error";
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `Google TTS failed after ${latency}ms: ${message}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: { latency },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+    /**
+     * Extract language code from a Google Cloud voice name
+     *
+     * Example:
+     *   "en-US-Neural2-C" -> "en-US"
+     *
+     * @param voiceId - Google Cloud voice identifier
+     * @returns Language code compatible with Google TTS
+     */
+    extractLanguageCode(voiceId) {
+        const parts = voiceId.split("-");
+        if (parts.length >= 2) {
+            return `${parts[0]}-${parts[1]}`;
+        }
+        else {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.INVALID_INPUT,
+                message: `Invalid Google TTS voiceId format: "${voiceId}". Expected format like "en-US-Neural2-C".`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { voiceId },
+            });
+        }
+    }
+    /**
+     * Map application audio format to Google Cloud audio encoding
+     *
+     * @param format - Audio format requested by the caller
+     * @returns Google Cloud AudioEncoding enum value
+     * @throws Error if format is unsupported
+     */
+    mapFormat(format) {
+        switch (format.toLowerCase()) {
+            case "mp3":
+                return "MP3";
+            case "wav":
+                return "LINEAR16";
+            case "ogg":
+            case "opus":
+                return "OGG_OPUS";
+            default:
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.INVALID_INPUT,
+                    message: `Unsupported audio format: ${format}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { format },
+                });
+        }
     }
 }
 //# sourceMappingURL=googleTTSHandler.js.map

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

@@ -25,6 +25,10 @@ export type TTSOptions = {
     format?: AudioFormat;
     /** Speaking rate 0.25-4.0 (default: 1.0) */
     speed?: number;
+    /** Voice pitch adjustment -20.0 to 20.0 semitones (default: 0.0) */
+    pitch?: number;
+    /** Volume gain in dB -96.0 to 16.0 (default: 0.0) */
+    volumeGainDb?: number;
     /** Audio quality (default: standard) */
     quality?: TTSQuality;
     /** Output file path (optional) */
@@ -48,6 +52,15 @@ export type TTSResult = {
     voice?: string;
     /** Sample rate in Hz */
     sampleRate?: number;
+    /** Performance and request metadata */
+    metadata?: {
+        /** Request latency in milliseconds */
+        latency: number;
+        /** Provider name */
+        provider?: string;
+        /** Additional provider-specific metadata */
+        [key: string]: unknown;
+    };
 };
 /**
  * Result of saving audio to file
@@ -81,6 +94,8 @@ export type TTSVoice = {
 export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
 /** Valid TTS quality levels as an array for runtime validation */
 export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
+/** Valid Google TTS audio formats */
+export type GoogleAudioEncoding = "MP3" | "LINEAR16" | "OGG_OPUS";
 /**
  * Type guard to check if an object is a TTSResult
  */

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

@@ -18,6 +18,7 @@ export declare const TTS_ERROR_CODES: {
     readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
     readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
     readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+    readonly INVALID_INPUT: "TTS_INVALID_INPUT";
 };
 /**
  * TTS Error class for text-to-speech specific errors

package/dist/lib/utils/ttsProcessor.js

@@ -18,6 +18,7 @@ export const TTS_ERROR_CODES = {
     PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
     PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
     SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+    INVALID_INPUT: "TTS_INVALID_INPUT",
 };
 /**
  * TTS Error class for text-to-speech specific errors

package/dist/types/ttsTypes.d.ts

@@ -25,6 +25,10 @@ export type TTSOptions = {
     format?: AudioFormat;
     /** Speaking rate 0.25-4.0 (default: 1.0) */
     speed?: number;
+    /** Voice pitch adjustment -20.0 to 20.0 semitones (default: 0.0) */
+    pitch?: number;
+    /** Volume gain in dB -96.0 to 16.0 (default: 0.0) */
+    volumeGainDb?: number;
     /** Audio quality (default: standard) */
     quality?: TTSQuality;
     /** Output file path (optional) */
@@ -48,6 +52,15 @@ export type TTSResult = {
     voice?: string;
     /** Sample rate in Hz */
     sampleRate?: number;
+    /** Performance and request metadata */
+    metadata?: {
+        /** Request latency in milliseconds */
+        latency: number;
+        /** Provider name */
+        provider?: string;
+        /** Additional provider-specific metadata */
+        [key: string]: unknown;
+    };
 };
 /**
  * Result of saving audio to file
@@ -81,6 +94,8 @@ export type TTSVoice = {
 export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
 /** Valid TTS quality levels as an array for runtime validation */
 export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
+/** Valid Google TTS audio formats */
+export type GoogleAudioEncoding = "MP3" | "LINEAR16" | "OGG_OPUS";
 /**
  * Type guard to check if an object is a TTSResult
  */

package/dist/utils/ttsProcessor.d.ts

@@ -18,6 +18,7 @@ export declare const TTS_ERROR_CODES: {
     readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
     readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
     readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+    readonly INVALID_INPUT: "TTS_INVALID_INPUT";
 };
 /**
  * TTS Error class for text-to-speech specific errors

package/dist/utils/ttsProcessor.js

@@ -18,6 +18,7 @@ export const TTS_ERROR_CODES = {
     PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
     PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
     SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+    INVALID_INPUT: "TTS_INVALID_INPUT",
 };
 /**
  * TTS Error class for text-to-speech specific errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.14.0",
+  "version": "8.15.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",