@juspay/neurolink 11.13.0 → 11.13.2

package/dist/lib/utils/ttsProcessor.js

@@ -1,293 +0,0 @@
-/**
- * Text-to-Speech (TTS) Processing Utility
- *
- * Central orchestrator for all TTS operations across providers.
- * Manages provider-specific TTS handlers and audio generation.
- *
- * @module utils/ttsProcessor
- */
-import { logger } from "./logger.js";
-import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
-import { NeuroLinkError } from "./errorHandling.js";
-import { HandlerRegistry } from "../core/handlerRegistry.js";
-import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.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",
-    INVALID_INPUT: "TTS_INVALID_INPUT",
-};
-/**
- * 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
- *
- * Follows the same pattern as CSVProcessor, ImageProcessor, and PDFProcessor.
- * Provides a unified interface for TTS generation across multiple providers.
- *
- * @example
- * ```typescript
- * // Register a handler
- * TTSProcessor.registerHandler('google-ai', googleAIHandler);
- *
- * // Check if provider is supported
- * if (TTSProcessor.supports('google-ai')) {
- *   // Provider is registered
- * }
- * ```
- */
-export class TTSProcessor {
-    /**
-     * Handler registry mapping provider names to TTS handlers
-     *
-     * @private
-     */
-    static registry = new HandlerRegistry("TTSProcessor");
-    /**
-     * Default maximum text length for TTS synthesis (in bytes)
-     *
-     * 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;
-    /**
-     * Register a TTS handler for a specific provider
-     *
-     * Allows providers to register their TTS implementation at runtime.
-     *
-     * @param providerName - Provider identifier (e.g., 'google-ai', 'openai')
-     * @param handler - TTS handler implementation
-     *
-     * @example
-     * ```typescript
-     * const googleHandler: TTSHandler = {
-     *   synthesize: async (text, options) => { ... },
-     *   getVoices: async (languageCode) => { ... },
-     *   isConfigured: () => true
-     * };
-     *
-     * TTSProcessor.registerHandler('google-ai', googleHandler);
-     * ```
-     */
-    static registerHandler(providerName, handler) {
-        const normalizedName = providerName
-            ? providerName.toLowerCase()
-            : providerName;
-        this.registry.register(providerName, handler);
-        logger.debug(`[TTSProcessor] Registered TTS handler for provider: ${normalizedName}`);
-    }
-    /**
-     * Get a registered TTS handler by provider name.
-     *
-     * Exposed publicly so module-level auto-registration code can reuse an
-     * already-registered primary handler when backfilling its aliases —
-     * see `src/lib/voice/index.ts:registerDefaultTTSHandlers`.
-     *
-     * @param providerName - Provider identifier
-     * @returns Handler instance or undefined if not registered
-     */
-    static getHandler(providerName) {
-        return this.registry.get(providerName);
-    }
-    /**
-     * List the names of all registered providers.
-     */
-    static listProviders() {
-        return this.registry.list();
-    }
-    /**
-     * Removes every registered TTS handler. Primarily for test isolation —
-     * production code should not need to call this.
-     */
-    static clearHandlers() {
-        this.registry.clear();
-    }
-    /**
-     * Check if a provider is supported (has a registered TTS handler)
-     *
-     * @param providerName - Provider identifier
-     * @returns True if handler is registered
-     *
-     * @example
-     * ```typescript
-     * if (TTSProcessor.supports('google-ai')) {
-     *   console.log('Google AI TTS is supported');
-     * }
-     * ```
-     */
-    static supports(providerName) {
-        if (!providerName) {
-            logger.error("[TTSProcessor] Provider name is required for supports check");
-            return false;
-        }
-        const isSupported = this.registry.supports(providerName);
-        if (!isSupported) {
-            logger.debug(`[TTSProcessor] Provider ${providerName} is not supported`);
-        }
-        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 (timeout handled by provider)
-     * 5. Enriches result with metadata
-     *
-     * **Timeout Handling:**
-     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
-     * Providers typically use 30-second timeouts via `withTimeout()` utility or
-     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
-     *
-     * @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 or provider not supported/configured
-     *
-     * @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) {
-        // Create span early so preflight failures are captured
-        const span = SpanSerializer.createSpan(SpanType.TTS, "tts.synthesize", {
-            "tts.operation": "synthesize",
-            "tts.provider": provider,
-            "tts.voice": options.voice,
-            "tts.format": options.format,
-        });
-        try {
-            // 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: this.registry.list(),
-                    },
-                });
-            }
-            // 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 },
-                });
-            }
-            logger.debug(`[TTSProcessor] Starting synthesis with provider: ${provider}`);
-            // 5. Call handler.synthesize() - providers handle their own timeouts
-            const result = await handler.synthesize(trimmedText, options);
-            // 6. Post-processing: add metadata
-            const enrichedResult = {
-                ...result,
-                voice: result.voice ?? options.voice,
-            };
-            logger.info(`[TTSProcessor] Successfully synthesized ${result.size} bytes of audio`);
-            // 7. Record successful span
-            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
-            getMetricsAggregator().recordSpan(endedSpan);
-            // 8. Returns TTSResult with buffer, format, metadata
-            return enrichedResult;
-        }
-        catch (err) {
-            // Record error span
-            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR, err instanceof Error ? err.message : String(err));
-            getMetricsAggregator().recordSpan(endedSpan);
-            // 9. 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: text.trim().length,
-                    options,
-                },
-                originalError: err instanceof Error ? err : undefined,
-            });
-        }
-    }
-}
-//# sourceMappingURL=ttsProcessor.js.map

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

@@ -1,77 +0,0 @@
-/**
- * Type Utilities - Centralized type checking functions
- *
- * Consolidates common type checking patterns to reduce code duplication
- * and provide consistent type guards across the codebase.
- */
-/**
- * Type guard to check if a value is a non-null object
- * Excludes arrays and null values
- *
- * @param value - Value to check
- * @returns true if value is a non-null object (excluding arrays)
- */
-export declare function isObject(value: unknown): value is Record<string, unknown>;
-/**
- * Type guard to check if a value is a non-null object (including arrays)
- *
- * @param value - Value to check
- * @returns true if value is a non-null object (including arrays)
- */
-export declare function isNonNullObject(value: unknown): value is object;
-/**
- * Type guard to check if a value is a plain object with string keys
- *
- * @param value - Value to check
- * @returns true if value is a plain object with string keys
- */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-/**
- * Type guard to check if a value is an array
- *
- * @param value - Value to check
- * @returns true if value is an array
- */
-export declare function isArray(value: unknown): value is unknown[];
-/**
- * Type guard to check if a value is a string
- *
- * @param value - Value to check
- * @returns true if value is a string
- */
-export declare function isString(value: unknown): value is string;
-/**
- * Type guard to check if a value is a number
- *
- * @param value - Value to check
- * @returns true if value is a number and not NaN
- */
-export declare function isNumber(value: unknown): value is number;
-/**
- * Type guard to check if a value is a boolean
- *
- * @param value - Value to check
- * @returns true if value is a boolean
- */
-export declare function isBoolean(value: unknown): value is boolean;
-/**
- * Type guard to check if a value is a function
- *
- * @param value - Value to check
- * @returns true if value is a function
- */
-export declare function isFunction(value: unknown): value is Function;
-/**
- * Type guard to check if a value is null or undefined
- *
- * @param value - Value to check
- * @returns true if value is null or undefined
- */
-export declare function isNullish(value: unknown): value is null | undefined;
-/**
- * Type guard to check if a value is defined (not undefined)
- *
- * @param value - Value to check
- * @returns true if value is not undefined
- */
-export declare function isDefined<T>(value: T | undefined): value is T;

package/dist/lib/utils/typeUtils.js

@@ -1,98 +0,0 @@
-/**
- * Type Utilities - Centralized type checking functions
- *
- * Consolidates common type checking patterns to reduce code duplication
- * and provide consistent type guards across the codebase.
- */
-/**
- * Type guard to check if a value is a non-null object
- * Excludes arrays and null values
- *
- * @param value - Value to check
- * @returns true if value is a non-null object (excluding arrays)
- */
-export function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/**
- * Type guard to check if a value is a non-null object (including arrays)
- *
- * @param value - Value to check
- * @returns true if value is a non-null object (including arrays)
- */
-export function isNonNullObject(value) {
-    return typeof value === "object" && value !== null;
-}
-/**
- * Type guard to check if a value is a plain object with string keys
- *
- * @param value - Value to check
- * @returns true if value is a plain object with string keys
- */
-export function isPlainObject(value) {
-    return isObject(value) && Object.getPrototypeOf(value) === Object.prototype;
-}
-/**
- * Type guard to check if a value is an array
- *
- * @param value - Value to check
- * @returns true if value is an array
- */
-export function isArray(value) {
-    return Array.isArray(value);
-}
-/**
- * Type guard to check if a value is a string
- *
- * @param value - Value to check
- * @returns true if value is a string
- */
-export function isString(value) {
-    return typeof value === "string";
-}
-/**
- * Type guard to check if a value is a number
- *
- * @param value - Value to check
- * @returns true if value is a number and not NaN
- */
-export function isNumber(value) {
-    return typeof value === "number" && !isNaN(value);
-}
-/**
- * Type guard to check if a value is a boolean
- *
- * @param value - Value to check
- * @returns true if value is a boolean
- */
-export function isBoolean(value) {
-    return typeof value === "boolean";
-}
-/**
- * Type guard to check if a value is a function
- *
- * @param value - Value to check
- * @returns true if value is a function
- */
-export function isFunction(value) {
-    return typeof value === "function";
-}
-/**
- * Type guard to check if a value is null or undefined
- *
- * @param value - Value to check
- * @returns true if value is null or undefined
- */
-export function isNullish(value) {
-    return value === null || value === undefined;
-}
-/**
- * Type guard to check if a value is defined (not undefined)
- *
- * @param value - Value to check
- * @returns true if value is not undefined
- */
-export function isDefined(value) {
-    return value !== undefined;
-}
-//# sourceMappingURL=typeUtils.js.map

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

@@ -1,24 +0,0 @@
-import { AIProviderName } from "../constants/enums.js";
-import type { ModelMessage } from "../types/index.js";
-/**
- * Check if messages contain video frames (images)
- * Only checks user messages to match buildContentParts behavior
- *
- * @param messages - Array of ModelMessage objects
- * @returns true if video frames are present in user messages
- */
-export declare function hasVideoFrames(messages: ModelMessage[]): boolean;
-/**
- * Execute video analysis on messages containing video frames
- *
- * @param messages - Array of ModelMessage objects with video frames
- * @param options - Video analysis options
- * @returns Video analysis text result
- * @throws Error if analysis fails
- */
-export declare function executeVideoAnalysis(messages: ModelMessage[], options: {
-    provider?: AIProviderName | string;
-    providerName?: AIProviderName;
-    region?: string;
-    model?: string;
-}): Promise<string>;

package/dist/lib/utils/videoAnalysisProcessor.js

@@ -1,61 +0,0 @@
-import { AIProviderName } from "../constants/enums.js";
-import { logger } from "./logger.js";
-/**
- * Check if messages contain video frames (images)
- * Only checks user messages to match buildContentParts behavior
- *
- * @param messages - Array of ModelMessage objects
- * @returns true if video frames are present in user messages
- */
-export function hasVideoFrames(messages) {
-    return messages.some((msg) => {
-        // Only check user messages to match buildContentParts behavior
-        if (msg.role !== "user") {
-            return false;
-        }
-        if (Array.isArray(msg.content)) {
-            // Count image parts — only route to video analysis pipeline when there are
-            // multiple frames (3+), indicating actual video frame extraction.
-            // Single images or pairs should use the model's native vision capability.
-            const imageCount = msg.content.filter((part) => typeof part === "object" &&
-                part !== null &&
-                "type" in part &&
-                part.type === "image").length;
-            return imageCount >= 3;
-        }
-        return false;
-    });
-}
-/**
- * Execute video analysis on messages containing video frames
- *
- * @param messages - Array of ModelMessage objects with video frames
- * @param options - Video analysis options
- * @returns Video analysis text result
- * @throws Error if analysis fails
- */
-export async function executeVideoAnalysis(messages, options) {
-    logger.debug("[VideoAnalysisProcessor] Video frames detected, triggering analysis");
-    const { analyzeVideo } = await import("../adapters/video/videoAnalyzer.js");
-    const provider = options.provider === AIProviderName.GOOGLE_AI ||
-        (options.provider === AIProviderName.AUTO && process.env.GOOGLE_AI_API_KEY)
-        ? AIProviderName.GOOGLE_AI
-        : options.provider === AIProviderName.VERTEX ||
-            options.providerName === AIProviderName.VERTEX
-            ? AIProviderName.VERTEX
-            : AIProviderName.AUTO;
-    const videoAnalysisText = await analyzeVideo(messages, {
-        provider: provider,
-        project: options.region
-            ? undefined
-            : process.env.GOOGLE_VERTEX_PROJECT || process.env.GOOGLE_CLOUD_PROJECT,
-        location: options.region || process.env.GOOGLE_VERTEX_LOCATION,
-        model: options.model || "gemini-2.5-flash",
-    });
-    logger.debug("[VideoAnalysisProcessor] Video analysis completed", {
-        hasResult: !!videoAnalysisText,
-        resultLength: videoAnalysisText?.length,
-    });
-    return videoAnalysisText;
-}
-//# sourceMappingURL=videoAnalysisProcessor.js.map

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

@@ -1,64 +0,0 @@
-/**
- * Video Generation Processing Utility
- *
- * Central registry + dispatch for video-generation handlers across
- * providers (Vertex Veo, Kling, Runway, Replicate-hosted models, etc.).
- *
- * Mirrors the static-handler-registry pattern established by
- * `TTSProcessor` (`utils/ttsProcessor.ts`) and `STTProcessor`
- * (`utils/sttProcessor.ts`).
- *
- * @module utils/videoProcessor
- */
-import { VIDEO_ERROR_CODES } from "../constants/videoErrors.js";
-import type { VideoGenerationResult, VideoHandler, VideoOutputOptions, VideoTransitionOptions } from "../types/index.js";
-import { VideoError } from "../adapters/video/vertexVideoHandler.js";
-export { VideoError, VIDEO_ERROR_CODES };
-/**
- * Static processor managing the video handler registry.
- *
- * Handlers register themselves during `ProviderRegistry._doRegister()`
- * via `VideoProcessor.registerHandler(name, instance)`. Lookups are
- * O(1) on a normalised lower-case provider key.
- */
-export declare class VideoProcessor {
-    private static readonly registry;
-    /**
-     * Register a video handler for a specific provider.
-     */
-    static registerHandler(providerName: string, handler: VideoHandler): void;
-    /**
-     * Check if a provider has a registered video handler.
-     */
-    static supports(providerName: string): boolean;
-    /**
-     * List the names of all registered providers.
-     */
-    static listProviders(): string[];
-    private static getHandler;
-    /**
-     * Clear all registered handlers (for testing).
-     */
-    static clearHandlers(): void;
-    private static buildSpanAttributes;
-    /**
-     * Generate a single video clip via the registered handler.
-     *
-     * @param provider - Registered provider name (e.g. "vertex", "kling")
-     * @param image - Source image buffer
-     * @param prompt - Text prompt describing the desired motion / content
-     * @param options - Resolution / length / aspect-ratio / audio options
-     * @param region - Optional region override (Vertex location, etc.)
-     * @throws VideoError on registry miss, handler-not-configured, or
-     *         generation failure
-     */
-    static generate(provider: string, image: Buffer, prompt: string, options: VideoOutputOptions, region?: string): Promise<VideoGenerationResult>;
-    /**
-     * Generate a transition clip via the registered handler (Director Mode).
-     *
-     * Providers without first-and-last-frame interpolation surface a typed
-     * `TRANSITION_NOT_SUPPORTED` error here; callers should fall back to
-     * generating a regular clip with a transition prompt.
-     */
-    static generateTransition(provider: string, firstFrame: Buffer, lastFrame: Buffer, prompt: string, options?: VideoTransitionOptions, region?: string): Promise<Buffer>;
-}