@juspay/neurolink 8.6.0 → 8.8.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [8.8.0](https://github.com/juspay/neurolink/compare/v8.7.0...v8.8.0) (2025-12-11)
+
+### Features
+
+- **(types):** add AudioProviderConfig type definition for transcription providers ([c34f437](https://github.com/juspay/neurolink/commit/c34f437455fba20b803b84811b9dda143351427e))
+
+## [8.7.0](https://github.com/juspay/neurolink/compare/v8.6.0...v8.7.0) (2025-12-10)
+
+### Features
+
+- **(cli):** implement TTS audio file output (TTS-024) ([48af003](https://github.com/juspay/neurolink/commit/48af0033db12d3a7b7dd62b8fb5c965f61f20042))
+- **(ImageProcessor):** Add output validation to ImageProcessor.process() method ([6fe3a16](https://github.com/juspay/neurolink/commit/6fe3a16e8290a1a7640ab51865343583253418d0))
+- **(imageProcessor):** add retry logic with exponential backoff for URL downloads ([e6ab4df](https://github.com/juspay/neurolink/commit/e6ab4df4e974c3981d6a2e2de30d5b3e19ecccf9))
+- **(types):** add AudioProcessorOptions and audioOptions to FileDetectorOptions ([2bd877b](https://github.com/juspay/neurolink/commit/2bd877bd5f41fed786cabbdea6e57df95bd7debb))
+
+### Bug Fixes
+
+- **(deps):** convert canvas and pdfjs-dist to dynamic imports for SSR compatibility ([cc7d99e](https://github.com/juspay/neurolink/commit/cc7d99e33d5087ac4d8f442c0dfebdfad9c294c4))
+- **(deps):** force @semantic-release/npm v13 via pnpm override for OIDC support ([8a528c9](https://github.com/juspay/neurolink/commit/8a528c95e8c983ce3cb8d1196b8c08ae4ed93ec1))
+- **(lock):** add missing update for lockfile ([376b7ad](https://github.com/juspay/neurolink/commit/376b7ad0297e1f8f6fc68c5c58d30213bae9d23c))
+- **(release):** enable OIDC trusted publishing for npm ([3ba6dd9](https://github.com/juspay/neurolink/commit/3ba6dd9d7b6156e170550315f8a208ccafa5483a))
+- **(tts):** add audio property to GenerateResult type and improve type safety ([e85c7d0](https://github.com/juspay/neurolink/commit/e85c7d0435b6b4f81421ce816e2252b932e0b3ca))
+- **(workflows):** add job-level OIDC permissions and remove conflicting auth ([8ee4fb1](https://github.com/juspay/neurolink/commit/8ee4fb1ed3e0a996540032ddd92d4a491a2b53a1))
+- **(workflows):** add OIDC authentication for npm trusted publishing ([c6bb5bb](https://github.com/juspay/neurolink/commit/c6bb5bb33c34249ee89e8622d879f266025ecb9a))
+
 ## [8.6.0](https://github.com/juspay/neurolink/compare/v8.5.1...v8.6.0) (2025-12-06)
 
 ### Features

package/dist/cli/factories/commandFactory.d.ts

@@ -11,6 +11,11 @@ export declare class CLICommandFactory {
     private static processCliFiles;
     private static processOptions;
     private static handleOutput;
+    /**
+     * Helper method to handle TTS audio file output
+     * Saves audio to file when --tts-output flag is provided
+     */
+    private static handleTTSOutput;
     private static isValidTokenUsage;
     private static normalizeTokenUsage;
     private static formatAnalyticsForTextMode;

package/dist/cli/factories/commandFactory.js

@@ -16,6 +16,7 @@ import { logger } from "../../lib/utils/logger.js";
 import fs from "fs";
 import { handleSetup } from "../commands/setup.js";
 import { checkRedisAvailability } from "../../lib/utils/conversationMemoryUtils.js";
+import { saveAudioToFile, formatFileSize } from "../utils/audioFileUtils.js";
 /**
  * CLI Command Factory for generate commands
  */
@@ -194,6 +195,42 @@ export class CLICommandFactory {
             default: false,
             description: "Test command without making actual API calls (for testing)",
         },
+        // TTS (Text-to-Speech) options
+        tts: {
+            type: "boolean",
+            default: false,
+            description: "Enable text-to-speech output",
+        },
+        ttsVoice: {
+            type: "string",
+            description: "TTS voice to use (e.g., 'en-US-Neural2-C')",
+        },
+        ttsFormat: {
+            type: "string",
+            choices: ["mp3", "wav", "ogg", "opus"],
+            default: "mp3",
+            description: "Audio output format",
+        },
+        ttsSpeed: {
+            type: "number",
+            default: 1.0,
+            description: "Speaking rate (0.25-4.0, default: 1.0)",
+        },
+        ttsQuality: {
+            type: "string",
+            choices: ["standard", "hd"],
+            default: "standard",
+            description: "Audio quality level",
+        },
+        ttsOutput: {
+            type: "string",
+            description: "Save TTS audio to file (supports absolute and relative paths)",
+        },
+        ttsPlay: {
+            type: "boolean",
+            default: false,
+            description: "Auto-play generated audio",
+        },
     };
     // Helper method to build options for commands
     static buildOptions(yargs, additionalOptions = {}) {
@@ -302,6 +339,14 @@ export class CLICommandFactory {
             noColor: argv.noColor,
             configFile: argv.configFile,
             dryRun: argv.dryRun,
+            // TTS options
+            tts: argv.tts,
+            ttsVoice: argv.ttsVoice,
+            ttsFormat: argv.ttsFormat,
+            ttsSpeed: argv.ttsSpeed,
+            ttsQuality: argv.ttsQuality,
+            ttsOutput: argv.ttsOutput,
+            ttsPlay: argv.ttsPlay,
         };
     }
     // Helper method to handle output
@@ -343,6 +388,44 @@ export class CLICommandFactory {
             logger.always(output);
         }
     }
+    /**
+     * Helper method to handle TTS audio file output
+     * Saves audio to file when --tts-output flag is provided
+     */
+    static async handleTTSOutput(result, options) {
+        // Check if --tts-output flag is provided
+        const ttsOutputPath = options.ttsOutput;
+        if (!ttsOutputPath) {
+            return;
+        }
+        // Extract audio from result with proper type checking
+        if (!result || typeof result !== "object") {
+            return;
+        }
+        const generateResult = result;
+        const audio = generateResult.audio;
+        if (!audio) {
+            if (!options.quiet) {
+                logger.always(chalk.yellow("⚠️  No audio available in result. TTS may not be enabled for this request."));
+            }
+            return;
+        }
+        try {
+            // Save audio to file
+            const saveResult = await saveAudioToFile(audio, ttsOutputPath);
+            if (saveResult.success) {
+                if (!options.quiet) {
+                    logger.always(chalk.green(`🔊 Audio saved to: ${saveResult.path} (${formatFileSize(saveResult.size)})`));
+                }
+            }
+            else {
+                handleError(new Error(saveResult.error || "Failed to save audio file"), "TTS Output");
+            }
+        }
+        catch (error) {
+            handleError(error, "TTS Output");
+        }
+    }
     // Helper method to validate token usage data with fallback handling
     static isValidTokenUsage(tokens) {
         if (!tokens || typeof tokens !== "object" || tokens === null) {
@@ -1124,6 +1207,8 @@ export class CLICommandFactory {
             }
             // Handle output with universal formatting
             this.handleOutput(result, options);
+            // Handle TTS audio file output if --tts-output is provided
+            await this.handleTTSOutput(result, options);
             if (options.debug) {
                 logger.debug("\n" + chalk.yellow("Debug Information:"));
                 logger.debug("Provider:", result.provider);
@@ -1436,6 +1521,17 @@ export class CLICommandFactory {
                 logger.always(`\nOutput saved to ${options.output}`);
             }
         }
+        // Handle TTS audio output if --tts-output is provided
+        // Note: For streaming, TTS audio is collected during the stream
+        // and saved at the end if available
+        const ttsOutputPath = options.ttsOutput;
+        if (ttsOutputPath) {
+            // For now, streaming TTS output is not yet available
+            // This will be enabled when the TTS streaming infrastructure is complete
+            if (!options.quiet) {
+                logger.always(chalk.yellow("⚠️  TTS audio output for streaming is not yet available. Use 'generate' command for TTS output."));
+            }
+        }
         // Debug output for streaming
         if (options.debug) {
             await this.logStreamDebugInfo({

package/dist/cli/utils/audioFileUtils.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Audio file utilities for CLI
+ *
+ * Provides functionality for saving TTS audio to files with proper
+ * error handling and directory creation.
+ *
+ * @module cli/utils/audioFileUtils
+ */
+import type { TTSResult, AudioSaveResult, AudioFormat } from "../../lib/types/ttsTypes.js";
+/**
+ * Format file size in human-readable format
+ *
+ * @param bytes - Size in bytes
+ * @returns Formatted string (e.g., "32 KB", "1.5 MB")
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Resolve the output path, handling both absolute and relative paths
+ *
+ * @param outputPath - User-specified output path
+ * @returns Resolved absolute path
+ */
+export declare function resolveOutputPath(outputPath: string): string;
+/**
+ * Ensure parent directories exist, creating them if necessary
+ *
+ * @param filePath - Full path to the file
+ */
+export declare function ensureDirectoryExists(filePath: string): Promise<void>;
+/**
+ * Get appropriate file extension for audio format
+ *
+ * @param format - Audio format
+ * @returns File extension (including dot)
+ */
+export declare function getAudioExtension(format: AudioFormat): string;
+/**
+ * Validate and normalize output path, adding extension if needed
+ *
+ * @param outputPath - User-specified output path
+ * @param format - Audio format for extension
+ * @returns Normalized output path
+ */
+export declare function normalizeOutputPath(outputPath: string, format?: AudioFormat): string;
+/**
+ * Save TTS audio result to a file
+ *
+ * Creates parent directories if they don't exist and handles both
+ * absolute and relative paths.
+ *
+ * @param audio - TTS result containing audio buffer
+ * @param outputPath - Path where the audio should be saved
+ * @returns Save result with success status, path, and size
+ *
+ * @example
+ * ```typescript
+ * const result = await saveAudioToFile(audioResult, "./output/audio.mp3");
+ * if (result.success) {
+ *   console.log(`Saved to ${result.path} (${formatFileSize(result.size)})`);
+ * }
+ * ```
+ */
+export declare function saveAudioToFile(audio: TTSResult, outputPath: string): Promise<AudioSaveResult>;
+/**
+ * Validate that a path is writable
+ *
+ * @param filePath - Path to validate
+ * @returns True if the path is writable
+ */
+export declare function isPathWritable(filePath: string): Promise<boolean>;

package/dist/cli/utils/audioFileUtils.js

@@ -0,0 +1,174 @@
+/**
+ * Audio file utilities for CLI
+ *
+ * Provides functionality for saving TTS audio to files with proper
+ * error handling and directory creation.
+ *
+ * @module cli/utils/audioFileUtils
+ */
+import fs from "fs";
+import path from "path";
+/**
+ * Format file size in human-readable format
+ *
+ * @param bytes - Size in bytes
+ * @returns Formatted string (e.g., "32 KB", "1.5 MB")
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    else if (bytes < 1024 * 1024 * 1024) {
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+    }
+}
+/**
+ * Resolve the output path, handling both absolute and relative paths
+ *
+ * @param outputPath - User-specified output path
+ * @returns Resolved absolute path
+ */
+export function resolveOutputPath(outputPath) {
+    if (path.isAbsolute(outputPath)) {
+        return outputPath;
+    }
+    return path.resolve(process.cwd(), outputPath);
+}
+/**
+ * Ensure parent directories exist, creating them if necessary
+ *
+ * @param filePath - Full path to the file
+ */
+export async function ensureDirectoryExists(filePath) {
+    const directory = path.dirname(filePath);
+    try {
+        await fs.promises.access(directory, fs.constants.F_OK);
+    }
+    catch {
+        // Directory doesn't exist, create it recursively
+        await fs.promises.mkdir(directory, { recursive: true });
+    }
+}
+/**
+ * Get appropriate file extension for audio format
+ *
+ * @param format - Audio format
+ * @returns File extension (including dot)
+ */
+export function getAudioExtension(format) {
+    switch (format) {
+        case "mp3":
+            return ".mp3";
+        case "wav":
+            return ".wav";
+        case "ogg":
+            return ".ogg";
+        case "opus":
+            return ".opus";
+        default:
+            return ".mp3";
+    }
+}
+/**
+ * Validate and normalize output path, adding extension if needed
+ *
+ * @param outputPath - User-specified output path
+ * @param format - Audio format for extension
+ * @returns Normalized output path
+ */
+export function normalizeOutputPath(outputPath, format = "mp3") {
+    const resolvedPath = resolveOutputPath(outputPath);
+    const ext = path.extname(resolvedPath).toLowerCase();
+    // If no extension or wrong extension, add the correct one
+    const validExtensions = [".mp3", ".wav", ".ogg", ".opus"];
+    if (!ext || !validExtensions.includes(ext)) {
+        return resolvedPath + getAudioExtension(format);
+    }
+    return resolvedPath;
+}
+/**
+ * Save TTS audio result to a file
+ *
+ * Creates parent directories if they don't exist and handles both
+ * absolute and relative paths.
+ *
+ * @param audio - TTS result containing audio buffer
+ * @param outputPath - Path where the audio should be saved
+ * @returns Save result with success status, path, and size
+ *
+ * @example
+ * ```typescript
+ * const result = await saveAudioToFile(audioResult, "./output/audio.mp3");
+ * if (result.success) {
+ *   console.log(`Saved to ${result.path} (${formatFileSize(result.size)})`);
+ * }
+ * ```
+ */
+export async function saveAudioToFile(audio, outputPath) {
+    try {
+        // Normalize the output path
+        const normalizedPath = normalizeOutputPath(outputPath, audio.format);
+        // Ensure parent directories exist
+        await ensureDirectoryExists(normalizedPath);
+        // Write the audio buffer to file
+        await fs.promises.writeFile(normalizedPath, audio.buffer);
+        // Get the actual file size
+        const stats = await fs.promises.stat(normalizedPath);
+        return {
+            success: true,
+            path: normalizedPath,
+            size: stats.size,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+        return {
+            success: false,
+            path: outputPath,
+            size: 0,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Validate that a path is writable
+ *
+ * @param filePath - Path to validate
+ * @returns True if the path is writable
+ */
+export async function isPathWritable(filePath) {
+    try {
+        const resolvedPath = resolveOutputPath(filePath);
+        const directory = path.dirname(resolvedPath);
+        // Check if directory exists
+        try {
+            await fs.promises.access(directory, fs.constants.W_OK);
+            return true;
+        }
+        catch {
+            // Directory doesn't exist, check if we can create it
+            // by checking write access to the nearest existing parent
+            let parentDir = directory;
+            while (parentDir !== path.dirname(parentDir)) {
+                try {
+                    await fs.promises.access(parentDir, fs.constants.W_OK);
+                    return true;
+                }
+                catch {
+                    parentDir = path.dirname(parentDir);
+                }
+            }
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=audioFileUtils.js.map

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

@@ -337,6 +337,8 @@ export type GenerateResult = CommandResult & {
         name: string;
         description: string;
     }>;
+    /** TTS audio result when TTS is enabled */
+    audio?: import("./index.js").TTSResult;
 };
 /**
  * Stream result chunk

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

@@ -81,18 +81,53 @@ export type PDFProcessorOptions = {
     bedrockApiMode?: "converse" | "invokeModel";
 };
 /**
- * File detector options
+ * Audio provider configuration for transcription services
+ *
+ * Describes the capabilities and limitations of each audio transcription provider
+ * (e.g., OpenAI Whisper, Google Speech-to-Text, Azure Speech Services).
+ *
+ * @example OpenAI Whisper configuration
+ * ```typescript
+ * const openaiConfig: AudioProviderConfig = {
+ *   maxSizeMB: 25,
+ *   maxDurationSeconds: 600,
+ *   supportedFormats: ['mp3', 'mp4', 'm4a', 'wav', 'webm'],
+ *   supportsLanguageDetection: true,
+ *   requiresApiKey: true,
+ *   costPer60s: 0.006  // $0.006 per minute
+ * };
+ * ```
+ *
+ * @example Google Speech-to-Text configuration
+ * ```typescript
+ * const googleConfig: AudioProviderConfig = {
+ *   maxSizeMB: 10,
+ *   maxDurationSeconds: 480,
+ *   supportedFormats: ['flac', 'wav', 'mp3', 'ogg'],
+ *   supportsLanguageDetection: true,
+ *   requiresApiKey: true,
+ *   costPer15s: 0.004  // $0.016 per minute ($0.004 per 15 seconds)
+ * };
+ * ```
  */
-export type FileDetectorOptions = {
-    maxSize?: number;
-    timeout?: number;
-    allowedTypes?: FileType[];
-    csvOptions?: CSVProcessorOptions;
-    confidenceThreshold?: number;
-    provider?: string;
+export type AudioProviderConfig = {
+    /** Maximum audio file size in megabytes */
+    maxSizeMB: number;
+    /** Maximum audio duration in seconds */
+    maxDurationSeconds: number;
+    /** Supported audio formats (e.g., 'mp3', 'wav', 'm4a', 'flac', 'ogg') */
+    supportedFormats: string[];
+    /** Whether the provider supports automatic language detection */
+    supportsLanguageDetection: boolean;
+    /** Whether the provider requires an API key for authentication */
+    requiresApiKey: boolean;
+    /** Optional: Cost per 60 seconds of audio in USD */
+    costPer60s?: number;
+    /** Optional: Cost per 15 seconds of audio in USD */
+    costPer15s?: number;
 };
 /**
- * Audio processor options for transcription configuration
+ * Audio processor options
  */
 export type AudioProcessorOptions = {
     /** AI provider to use for transcription (e.g., 'openai', 'google', 'azure') */
@@ -108,6 +143,18 @@ export type AudioProcessorOptions = {
     /** Maximum file size in megabytes */
     maxSizeMB?: number;
 };
+/**
+ * File detector options
+ */
+export type FileDetectorOptions = {
+    maxSize?: number;
+    timeout?: number;
+    allowedTypes?: FileType[];
+    audioOptions?: AudioProcessorOptions;
+    csvOptions?: CSVProcessorOptions;
+    confidenceThreshold?: number;
+    provider?: string;
+};
 /**
  * Google AI Studio Files API types
  */

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

@@ -32,3 +32,4 @@ export * from "./utilities.js";
 export * from "./middlewareTypes.js";
 export * from "./fileTypes.js";
 export * from "./content.js";
+export * from "./ttsTypes.js";

package/dist/lib/types/index.js

@@ -35,4 +35,6 @@ export * from "./middlewareTypes.js";
 export * from "./fileTypes.js";
 // Content types for multimodal support
 export * from "./content.js";
+// TTS (Text-to-Speech) types
+export * from "./ttsTypes.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,91 @@
+/**
+ * Text-to-Speech (TTS) Type Definitions for NeuroLink
+ *
+ * This module defines types for TTS audio generation and output.
+ *
+ * @module types/ttsTypes
+ */
+/**
+ * Supported audio formats for TTS output
+ */
+export type AudioFormat = "mp3" | "wav" | "ogg" | "opus";
+/**
+ * TTS quality settings
+ */
+export type TTSQuality = "standard" | "hd";
+/**
+ * TTS configuration options
+ */
+export type TTSOptions = {
+    /** Enable TTS output */
+    enabled?: boolean;
+    /** Voice identifier (e.g., "en-US-Neural2-C") */
+    voice?: string;
+    /** Audio format (default: mp3) */
+    format?: AudioFormat;
+    /** Speaking rate 0.25-4.0 (default: 1.0) */
+    speed?: number;
+    /** Audio quality (default: standard) */
+    quality?: TTSQuality;
+    /** Output file path (optional) */
+    output?: string;
+    /** Auto-play audio after generation (default: false) */
+    play?: boolean;
+};
+/**
+ * TTS audio result returned from generation
+ */
+export type TTSResult = {
+    /** Audio data as Buffer */
+    buffer: Buffer;
+    /** Audio format */
+    format: AudioFormat;
+    /** Audio file size in bytes */
+    size: number;
+    /** Duration in seconds (if available) */
+    duration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};
+/**
+ * Result of saving audio to file
+ */
+export type AudioSaveResult = {
+    /** Whether the save was successful */
+    success: boolean;
+    /** Full path to the saved file */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** Error message if failed */
+    error?: string;
+};
+/**
+ * TTS voice information
+ */
+export type TTSVoice = {
+    /** Voice identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Language code (e.g., "en-US") */
+    languageCode: string;
+    /** Gender */
+    gender: "male" | "female" | "neutral";
+    /** Voice type */
+    type: "neural" | "wavenet" | "standard";
+};
+/** Valid audio formats as an array for runtime validation */
+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[];
+/**
+ * Type guard to check if an object is a TTSResult
+ */
+export declare function isTTSResult(value: unknown): value is TTSResult;
+/**
+ * Type guard to check if TTSOptions are valid
+ */
+export declare function isValidTTSOptions(options: unknown): options is TTSOptions;

package/dist/lib/types/ttsTypes.js

@@ -0,0 +1,58 @@
+/**
+ * Text-to-Speech (TTS) Type Definitions for NeuroLink
+ *
+ * This module defines types for TTS audio generation and output.
+ *
+ * @module types/ttsTypes
+ */
+/** Valid audio formats as an array for runtime validation */
+export const VALID_AUDIO_FORMATS = [
+    "mp3",
+    "wav",
+    "ogg",
+    "opus",
+];
+/** Valid TTS quality levels as an array for runtime validation */
+export const VALID_TTS_QUALITIES = ["standard", "hd"];
+/**
+ * Type guard to check if an object is a TTSResult
+ */
+export function isTTSResult(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const obj = value;
+    return (Buffer.isBuffer(obj.buffer) &&
+        typeof obj.format === "string" &&
+        VALID_AUDIO_FORMATS.includes(obj.format) &&
+        typeof obj.size === "number" &&
+        obj.size >= 0);
+}
+/**
+ * Type guard to check if TTSOptions are valid
+ */
+export function isValidTTSOptions(options) {
+    if (!options || typeof options !== "object") {
+        return false;
+    }
+    const opts = options;
+    if (opts.speed !== undefined) {
+        if (typeof opts.speed !== "number" ||
+            opts.speed < 0.25 ||
+            opts.speed > 4.0) {
+            return false;
+        }
+    }
+    if (opts.format !== undefined) {
+        if (!VALID_AUDIO_FORMATS.includes(opts.format)) {
+            return false;
+        }
+    }
+    if (opts.quality !== undefined) {
+        if (!VALID_TTS_QUALITIES.includes(opts.quality)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=ttsTypes.js.map