@juspay/neurolink 9.22.3 → 9.24.0

package/dist/adapters/video/vertexVideoHandler.js

@@ -12,38 +12,17 @@
 import { readFile } from "node:fs/promises";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { TIMEOUTS } from "../../constants/timeouts.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
 import { isAbortError, NeuroLinkError, withTimeout, } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
 // ============================================================================
-// VIDEO ERROR CODES
+// VIDEO ERROR CODES (Re-exported for backward compatibility)
 // ============================================================================
 /**
- * Video generation runtime error codes
- *
- * These are for runtime/execution errors during video generation.
- * Pure option/shape validation (missing image option, invalid config values, etc.)
- * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
- *
- * Error categorization:
- * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
- * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
- *
- * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
+ * Video error codes - re-exported from constants module for backward compatibility.
+ * @see {@link VIDEO_ERROR_CODES} in constants/videoErrors.ts for definitions
  */
-export const VIDEO_ERROR_CODES = {
-    /** Video generation API call failed */
-    GENERATION_FAILED: "VIDEO_GENERATION_FAILED",
-    /** Provider (Vertex AI) not properly configured */
-    PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED",
-    /** Polling for video completion timed out */
-    POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT",
-    /**
-     * Runtime I/O error during input processing.
-     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
-     * NOT for: missing options or invalid config shapes (use parameterValidation).
-     */
-    INVALID_INPUT: "VIDEO_INVALID_INPUT",
-};
+export { VIDEO_ERROR_CODES };
 /**
  * Video generation error class
  * Extends NeuroLinkError for consistent error handling across the SDK
@@ -71,6 +50,8 @@ const VIDEO_GENERATION_TIMEOUT_MS = 180000;
 const POLL_INTERVAL_MS = 5000;
 /** Full model name for Veo 3.1 (IMPORTANT: not just "veo-3.1") */
 const VEO_MODEL = "veo-3.1-generate-001";
+/** Full model name for Veo 3.1 Fast (used for transitions) */
+const VEO_FAST_MODEL = "veo-3.1-fast-generate-001";
 /** Default location for Vertex AI */
 const DEFAULT_LOCATION = "us-central1";
 // ============================================================================
@@ -592,35 +573,185 @@ async function makePollRequest(pollEndpoint, operationName, accessToken, timeout
  * @throws {VideoError} On API error, timeout, or missing video data
  */
 async function pollVideoOperation(operationName, accessToken, project, location, timeoutMs) {
+    return pollOperation(VEO_MODEL, operationName, accessToken, project, location, timeoutMs);
+}
+// ============================================================================
+// TRANSITION GENERATION (Director Mode)
+// ============================================================================
+/**
+ * Generate a transition clip using Veo 3.1 Fast's first-and-last-frame interpolation.
+ *
+ * This calls the Veo API with both `image` (first frame) and `lastFrame` (last frame),
+ * producing a video that smoothly interpolates between the two frames.
+ *
+ * @param firstFrame - JPEG buffer of the first frame (last frame of clip N)
+ * @param lastFrame - JPEG buffer of the last frame (first frame of clip N+1)
+ * @param prompt - Transition prompt describing desired visual flow
+ * @param options - Video output options (resolution, aspect ratio, audio)
+ * @param durationSeconds - Duration of the transition clip (4, 6, or 8)
+ * @param region - Vertex AI region override
+ * @returns Video buffer of the transition clip
+ *
+ * @throws {VideoError} When API returns an error or polling times out
+ */
+export async function generateTransitionWithVertex(firstFrame, lastFrame, prompt, options = {}, durationSeconds = 4, region) {
+    if (!isVertexVideoConfigured()) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+            message: "Vertex AI credentials not configured for transition generation.",
+            category: ErrorCategory.CONFIGURATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+        });
+    }
+    const config = await getVertexConfig();
+    const project = config.project;
+    const location = region || config.location;
     const startTime = Date.now();
-    // Use fetchPredictOperation endpoint - this is MODEL-SPECIFIC
-    const pollEndpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${VEO_MODEL}:fetchPredictOperation`;
+    const aspectRatio = options.aspectRatio || "16:9";
+    const resolution = options.resolution || "720p";
+    const generateAudio = options.audio ?? true;
+    logger.debug("Starting transition clip generation", {
+        model: VEO_FAST_MODEL,
+        durationSeconds,
+        firstFrameSize: firstFrame.length,
+        lastFrameSize: lastFrame.length,
+        promptLength: prompt.length,
+    });
+    try {
+        const firstFrameBase64 = firstFrame.toString("base64");
+        const lastFrameBase64 = lastFrame.toString("base64");
+        const firstMime = detectMimeType(firstFrame);
+        const lastMime = detectMimeType(lastFrame);
+        const accessToken = await getAccessToken();
+        // Use Veo 3.1 Fast for transitions (faster with minimal quality difference)
+        const endpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${VEO_FAST_MODEL}:predictLongRunning`;
+        const requestBody = {
+            instances: [
+                {
+                    prompt: prompt,
+                    image: {
+                        bytesBase64Encoded: firstFrameBase64,
+                        mimeType: firstMime,
+                    },
+                    lastFrame: {
+                        bytesBase64Encoded: lastFrameBase64,
+                        mimeType: lastMime,
+                    },
+                },
+            ],
+            parameters: {
+                sampleCount: 1,
+                durationSeconds: durationSeconds,
+                aspectRatio: aspectRatio,
+                resolution: resolution,
+                generateAudio: generateAudio,
+            },
+        };
+        const controller = new AbortController();
+        const requestTimeout = setTimeout(() => controller.abort(), 30000);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    "Content-Type": "application/json; charset=utf-8",
+                },
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            clearTimeout(requestTimeout);
+            if (isAbortError(error)) {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                    message: "Transition generation request timed out after 30 seconds",
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: true,
+                });
+            }
+            throw error;
+        }
+        clearTimeout(requestTimeout);
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                message: `Transition API error: ${response.status} - ${errorText}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: response.status >= 500,
+                context: { status: response.status, error: errorText },
+            });
+        }
+        const operation = await response.json();
+        const operationName = operation.name;
+        if (!operationName) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                message: "Transition API did not return an operation name",
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        // Poll with Veo Fast model endpoint
+        const remainingTime = VIDEO_GENERATION_TIMEOUT_MS - (Date.now() - startTime);
+        const videoBuffer = await pollTransitionOperation(operationName, accessToken, project, location, Math.max(1000, remainingTime));
+        logger.debug("Transition clip generated", {
+            processingTime: Date.now() - startTime,
+            videoSize: videoBuffer.length,
+        });
+        return videoBuffer;
+    }
+    catch (error) {
+        if (error instanceof VideoError) {
+            throw error;
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+            message: `Transition generation failed: ${error instanceof Error ? error.message : String(error)}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: true,
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+}
+/**
+ * Common polling helper that handles both video and transition operations.
+ * Accepts a model name to construct the appropriate endpoint.
+ */
+async function pollOperation(modelOrEndpoint, operationName, accessToken, project, location, timeoutMs) {
+    const startTime = Date.now();
+    const pollEndpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${modelOrEndpoint}:fetchPredictOperation`;
     while (Date.now() - startTime < timeoutMs) {
         const result = await makePollRequest(pollEndpoint, operationName, accessToken);
         if (result.done) {
             return extractVideoFromResult(result, operationName);
         }
-        const elapsed = Date.now() - startTime;
-        logger.debug("Polling video operation...", {
+        logger.debug("Polling operation...", {
             operationName,
-            elapsed,
-            remainingMs: timeoutMs - elapsed,
+            elapsed: Date.now() - startTime,
         });
-        // Wait before next poll
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
     }
-    // Timeout reached
     throw new VideoError({
         code: VIDEO_ERROR_CODES.POLL_TIMEOUT,
-        message: `Video generation timed out after ${Math.round(timeoutMs / 1000)}s while polling for completion`,
+        message: `Operation timed out after ${Math.round(timeoutMs / 1000)}s`,
         category: ErrorCategory.TIMEOUT,
-        severity: ErrorSeverity.HIGH,
+        severity: ErrorSeverity.MEDIUM,
         retriable: true,
-        context: {
-            operationName,
-            timeoutMs,
-            provider: "vertex",
-            suggestion: "Try again - video generation can take 1-3 minutes. Consider using a shorter duration or lower resolution.",
-        },
+        context: { operationName, timeoutMs },
     });
 }
+/**
+ * Poll Vertex AI operation for transition clip completion.
+ * Uses the Veo Fast model fetchPredictOperation endpoint.
+ */
+async function pollTransitionOperation(operationName, accessToken, project, location, timeoutMs) {
+    return pollOperation(VEO_FAST_MODEL, operationName, accessToken, project, location, timeoutMs);
+}

package/dist/adapters/video/videoMerger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Video Merger for Director Mode
+ *
+ * Concatenates multiple MP4 video buffers into a single MP4 using FFmpeg's
+ * concat demuxer for lossless concatenation when codecs match.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/videoMerger
+ */
+/**
+ * Merge multiple MP4 video buffers into a single MP4.
+ *
+ * Uses FFmpeg concat demuxer for lossless concatenation. If codecs don't match
+ * (unlikely since all clips come from Veo), falls back to re-encoding with H.264.
+ *
+ * @param videoBuffers - Array of MP4 video buffers to concatenate in order
+ * @returns Merged MP4 video buffer
+ * @throws {VideoError} If merge fails or no valid buffers provided
+ */
+export declare function mergeVideoBuffers(videoBuffers: Buffer[]): Promise<Buffer>;

package/dist/adapters/video/videoMerger.js

@@ -0,0 +1,171 @@
+/**
+ * Video Merger for Director Mode
+ *
+ * Concatenates multiple MP4 video buffers into a single MP4 using FFmpeg's
+ * concat demuxer for lossless concatenation when codecs match.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/videoMerger
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
+import { cleanupTempFiles, createTrackedTempDir, FFMPEG_MERGE_MAX_BUFFER, FFMPEG_MERGE_TIMEOUT_MS, isValidMp4Buffer, join, readFile, runFfmpeg, writeFile, } from "./ffmpegAdapter.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
+import { VideoError } from "./vertexVideoHandler.js";
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+/**
+ * Write clip buffers to temp files and build the FFmpeg concat list.
+ *
+ * @returns Paths of all written clip files
+ */
+async function writeClipsAndBuildConcatList(videoBuffers, tempDir, concatListPath) {
+    const inputPaths = [];
+    const concatLines = [];
+    for (let i = 0; i < videoBuffers.length; i++) {
+        const inputPath = join(tempDir, `clip_${i}.mp4`);
+        await writeFile(inputPath, videoBuffers[i]);
+        inputPaths.push(inputPath);
+        // Normalize backslashes to forward slashes for FFmpeg, then escape single quotes
+        const safePath = inputPath.replace(/\\/g, "/").replace(/'/g, "'\\''");
+        concatLines.push(`file '${safePath}'`);
+    }
+    await writeFile(concatListPath, concatLines.join("\n"));
+    return inputPaths;
+}
+/**
+ * Attempt lossless concat, falling back to H.264 re-encode on failure.
+ */
+async function concatWithFallback(concatListPath, outputPath) {
+    const ffmpegOpts = {
+        timeoutMs: FFMPEG_MERGE_TIMEOUT_MS,
+        maxBuffer: FFMPEG_MERGE_MAX_BUFFER,
+    };
+    try {
+        // Try lossless concat first (fastest — no re-encoding)
+        await runFfmpeg([
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            concatListPath,
+            "-c",
+            "copy",
+            outputPath,
+        ], ffmpegOpts);
+    }
+    catch (concatError) {
+        // Fallback: re-encode with H.264 if codecs mismatch
+        logger.warn("Lossless concat failed, falling back to H.264 re-encoding", {
+            error: concatError instanceof Error
+                ? concatError.message
+                : String(concatError),
+        });
+        await runFfmpeg([
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            concatListPath,
+            "-c:v",
+            "libx264",
+            "-preset",
+            "fast",
+            "-crf",
+            "18",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "192k",
+            "-movflags",
+            "+faststart",
+            outputPath,
+        ], ffmpegOpts);
+    }
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Merge multiple MP4 video buffers into a single MP4.
+ *
+ * Uses FFmpeg concat demuxer for lossless concatenation. If codecs don't match
+ * (unlikely since all clips come from Veo), falls back to re-encoding with H.264.
+ *
+ * @param videoBuffers - Array of MP4 video buffers to concatenate in order
+ * @returns Merged MP4 video buffer
+ * @throws {VideoError} If merge fails or no valid buffers provided
+ */
+export async function mergeVideoBuffers(videoBuffers) {
+    if (videoBuffers.length === 0) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+            message: "No video buffers provided to merge",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+        });
+    }
+    // Validate each input buffer
+    for (let i = 0; i < videoBuffers.length; i++) {
+        if (!isValidMp4Buffer(videoBuffers[i])) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+                message: `Clip ${i} is not a valid MP4 buffer (missing ftyp header or too small)`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    clipIndex: i,
+                    bufferSize: videoBuffers[i].length,
+                    headerHex: videoBuffers[i].subarray(0, 12).toString("hex"),
+                },
+            });
+        }
+    }
+    if (videoBuffers.length === 1) {
+        return videoBuffers[0];
+    }
+    const startTime = Date.now();
+    const tempDir = await createTrackedTempDir("merge");
+    const concatListPath = join(tempDir, "concat.txt");
+    const outputPath = join(tempDir, "merged.mp4");
+    let inputPaths = [];
+    try {
+        inputPaths = await writeClipsAndBuildConcatList(videoBuffers, tempDir, concatListPath);
+        await concatWithFallback(concatListPath, outputPath);
+        const mergedBuffer = await readFile(outputPath);
+        logger.info("Video merge complete", {
+            inputClips: videoBuffers.length,
+            totalInputSize: videoBuffers.reduce((sum, b) => sum + b.length, 0),
+            outputSize: mergedBuffer.length,
+            elapsedMs: Date.now() - startTime,
+        });
+        return mergedBuffer;
+    }
+    catch (error) {
+        // Re-throw VideoErrors as-is
+        if (error instanceof VideoError) {
+            throw error;
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+            message: `Video merge failed: ${error instanceof Error ? error.message : String(error)}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { clipCount: videoBuffers.length },
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+    finally {
+        await cleanupTempFiles(tempDir, concatListPath, outputPath, ...inputPaths);
+    }
+}

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

@@ -28,11 +28,21 @@ export declare class CLICommandFactory {
      * Auto-configures provider, model, and tools settings for video generation
      */
     private static configureVideoMode;
+    /**
+     * Helper method to configure options for PPT generation mode
+     * Auto-configures provider, model, and tools settings for presentation generation
+     */
+    private static configurePPTMode;
     /**
      * Helper method to handle video file output
      * Saves generated video to file when --videoOutput flag is provided
      */
     private static handleVideoOutput;
+    /**
+     * Helper method to handle PPT file output
+     * Displays PPT generation result info
+     */
+    private static handlePPTOutput;
     private static isValidTokenUsage;
     private static normalizeTokenUsage;
     private static formatAnalyticsForTextMode;
@@ -111,6 +121,30 @@ export declare class CLICommandFactory {
      * Execute provider status command
      */
     private static executeProviderStatus;
+    /**
+     * Handle stdin input for generate command
+     */
+    private static handleGenerateStdinInput;
+    /**
+     * Detect output mode (video, ppt, or text) based on CLI arguments
+     */
+    private static detectGenerateOutputMode;
+    /**
+     * Process context for generation command
+     */
+    private static processGenerateContext;
+    /**
+     * Build multimodal input from CLI arguments
+     */
+    private static buildGenerateMultimodalInput;
+    /**
+     * Build output configuration for generate request
+     */
+    private static buildGenerateOutputConfig;
+    /**
+     * Handle successful generation result
+     */
+    private static handleGenerateSuccess;
     /**
      * Execute the generate command
      */