@juspay/neurolink 8.26.1 → 8.28.0

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

@@ -19,6 +19,19 @@ export declare const ERROR_CODES: {
     readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
     readonly INVALID_CONFIGURATION: "INVALID_CONFIGURATION";
     readonly MISSING_CONFIGURATION: "MISSING_CONFIGURATION";
+    readonly INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION";
+    readonly INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH";
+    readonly INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO";
+    readonly INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO";
+    readonly INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE";
+    readonly MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE";
+    readonly EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT";
+    readonly VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG";
+    readonly EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH";
+    readonly INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE";
+    readonly IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
+    readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
+    readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
 };
 /**
  * Enhanced error class with structured information
@@ -76,6 +89,58 @@ export declare class ErrorFactory {
      * Create a memory exhaustion error
      */
     static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
+    /**
+     * Create an invalid video resolution error
+     */
+    static invalidVideoResolution(resolution: string): NeuroLinkError;
+    /**
+     * Create an invalid video length error
+     */
+    static invalidVideoLength(length: number): NeuroLinkError;
+    /**
+     * Create an invalid video aspect ratio error
+     */
+    static invalidVideoAspectRatio(aspectRatio: string): NeuroLinkError;
+    /**
+     * Create an invalid video audio option error
+     */
+    static invalidVideoAudio(audio: unknown): NeuroLinkError;
+    /**
+     * Create an invalid video mode error
+     */
+    static invalidVideoMode(): NeuroLinkError;
+    /**
+     * Create a missing video image error
+     */
+    static missingVideoImage(): NeuroLinkError;
+    /**
+     * Create an empty video prompt error
+     */
+    static emptyVideoPrompt(): NeuroLinkError;
+    /**
+     * Create a video prompt too long error
+     */
+    static videoPromptTooLong(length: number, maxLength: number): NeuroLinkError;
+    /**
+     * Create an empty image path error
+     */
+    static emptyImagePath(): NeuroLinkError;
+    /**
+     * Create an invalid image type error
+     */
+    static invalidImageType(): NeuroLinkError;
+    /**
+     * Create an image too large error
+     */
+    static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
+    /**
+     * Create an image too small error
+     */
+    static imageTooSmall(): NeuroLinkError;
+    /**
+     * Create an invalid image format error
+     */
+    static invalidImageFormat(): NeuroLinkError;
 }
 /**
  * Timeout wrapper for async operations

package/dist/lib/utils/errorHandling.js

@@ -25,6 +25,21 @@ export const ERROR_CODES = {
     // Configuration errors
     INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
     MISSING_CONFIGURATION: "MISSING_CONFIGURATION",
+    // Video validation errors
+    INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION",
+    INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH",
+    INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO",
+    INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO",
+    INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE",
+    MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE",
+    EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT",
+    VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG",
+    // Image validation errors
+    EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH",
+    INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE",
+    IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
+    IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
+    INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
 };
 /**
  * Enhanced error class with structured information
@@ -164,6 +179,259 @@ export class ErrorFactory {
             toolName,
         });
     }
+    // ============================================================================
+    // VIDEO VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create an invalid video resolution error
+     */
+    static invalidVideoResolution(resolution) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_RESOLUTION,
+            message: `Invalid resolution '${resolution}'. Use '720p' or '1080p'`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.resolution",
+                providedValue: resolution,
+                suggestions: ["Use '720p' for standard HD", "Use '1080p' for full HD"],
+            },
+        });
+    }
+    /**
+     * Create an invalid video length error
+     */
+    static invalidVideoLength(length) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_LENGTH,
+            message: `Invalid length '${length}'. Use 4, 6, or 8 seconds`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.length",
+                providedValue: length,
+                suggestions: [
+                    "Use 4 for short clips",
+                    "Use 6 for balanced duration (recommended)",
+                    "Use 8 for longer videos",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video aspect ratio error
+     */
+    static invalidVideoAspectRatio(aspectRatio) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_ASPECT_RATIO,
+            message: `Invalid aspect ratio '${aspectRatio}'. Use '9:16' or '16:9'`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.aspectRatio",
+                providedValue: aspectRatio,
+                suggestions: [
+                    "Use '9:16' for portrait/vertical video",
+                    "Use '16:9' for landscape",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video audio option error
+     */
+    static invalidVideoAudio(audio) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_AUDIO,
+            message: `Invalid audio option '${audio}'. Must be true or false`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.audio",
+                providedValue: audio,
+                suggestions: [
+                    "Set audio: true to enable audio generation",
+                    "Set audio: false to disable",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video mode error
+     */
+    static invalidVideoMode() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_MODE,
+            message: "Video generation requires output.mode to be 'video'",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.mode",
+                suggestions: ["Set output: { mode: 'video' } for video generation"],
+            },
+        });
+    }
+    /**
+     * Create a missing video image error
+     */
+    static missingVideoImage() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.MISSING_VIDEO_IMAGE,
+            message: "Video generation requires an input image",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Provide an image via input.images array",
+                    "Example: input: { text: 'prompt', images: [imageBuffer] }",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an empty video prompt error
+     */
+    static emptyVideoPrompt() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.EMPTY_VIDEO_PROMPT,
+            message: "Video prompt cannot be empty",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.text",
+                suggestions: [
+                    "Provide a text prompt describing the desired video motion/content",
+                    "Example: 'Smooth camera pan with dramatic lighting'",
+                ],
+            },
+        });
+    }
+    /**
+     * Create a video prompt too long error
+     */
+    static videoPromptTooLong(length, maxLength) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.VIDEO_PROMPT_TOO_LONG,
+            message: `Video prompt must be ${maxLength} characters or less (got ${length})`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.text",
+                providedLength: length,
+                maxLength,
+                suggestions: [
+                    `Shorten your prompt to ${maxLength} characters or less`,
+                    "Focus on key visual elements and camera motion",
+                ],
+            },
+        });
+    }
+    // ============================================================================
+    // IMAGE VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create an empty image path error
+     */
+    static emptyImagePath() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.EMPTY_IMAGE_PATH,
+            message: "Image path or URL cannot be empty",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: ["Provide a valid file path or URL"],
+            },
+        });
+    }
+    /**
+     * Create an invalid image type error
+     */
+    static invalidImageType() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_TYPE,
+            message: "Image must be a Buffer, file path string, or URL",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Provide image as Buffer: fs.readFileSync('image.jpg')",
+                    "Or as file path string: './image.jpg'",
+                    "Or as URL: 'https://example.com/image.jpg'",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an image too large error
+     */
+    static imageTooLarge(sizeMB, maxMB) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.IMAGE_TOO_LARGE,
+            message: `Image size (${sizeMB}MB) exceeds maximum (${maxMB}MB)`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                sizeMB,
+                maxMB,
+                suggestions: [
+                    `Compress or resize the image to under ${maxMB}MB`,
+                    "Use a lower quality JPEG compression",
+                    "Reduce image dimensions",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an image too small error
+     */
+    static imageTooSmall() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.IMAGE_TOO_SMALL,
+            message: "Image data is too small to be a valid image file",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: ["Provide a valid JPEG, PNG, or WebP image file"],
+            },
+        });
+    }
+    /**
+     * Create an invalid image format error
+     */
+    static invalidImageFormat() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_FORMAT,
+            message: "Unsupported image format. Use JPEG, PNG, or WebP",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Convert your image to JPEG, PNG, or WebP format",
+                    "Ensure the file is not corrupted",
+                    "Check that the file extension matches the actual format",
+                ],
+            },
+        });
+    }
 }
 /**
  * Timeout wrapper for async operations

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

@@ -2,8 +2,11 @@
  * Parameter Validation Utilities
  * Provides consistent parameter validation across all tool interfaces
  */
-import type { ValidationSchema, StringArray } from "../types/typeAliases.js";
+import type { GenerateOptions } from "../types/generateTypes.js";
+import type { VideoOutputOptions } from "../types/multimodal.js";
 import type { EnhancedValidationResult } from "../types/tools.js";
+import type { StringArray, ValidationSchema } from "../types/typeAliases.js";
+import { NeuroLinkError } from "./errorHandling.js";
 /**
  * Custom error class for parameter validation failures
  * Provides detailed information about validation errors including field context and suggestions
@@ -74,6 +77,61 @@ export declare function validateToolBatch(tools: Record<string, unknown>): {
     invalidTools: string[];
     results: Record<string, EnhancedValidationResult>;
 };
+/**
+ * Validate video output options (resolution, length, aspect ratio, audio)
+ *
+ * @param options - VideoOutputOptions to validate
+ * @returns NeuroLinkError if invalid, null if valid
+ *
+ * @example
+ * ```typescript
+ * const error = validateVideoOutputOptions({ resolution: "4K", length: 10 });
+ * // error.code === "INVALID_VIDEO_RESOLUTION"
+ * ```
+ */
+export declare function validateVideoOutputOptions(options: VideoOutputOptions): NeuroLinkError | null;
+/**
+ * Validate image input for video generation
+ *
+ * Checks image format (magic bytes) and size constraints.
+ * Supports JPEG, PNG, and WebP formats.
+ *
+ * @param image - Image buffer to validate
+ * @param maxSize - Maximum allowed size in bytes (default: 10MB)
+ * @returns NeuroLinkError if invalid, null if valid
+ *
+ * @example
+ * ```typescript
+ * const imageBuffer = readFileSync("product.jpg");
+ * const error = validateImageForVideo(imageBuffer);
+ * if (error) throw error;
+ * ```
+ */
+export declare function validateImageForVideo(image: Buffer | string, maxSize?: number): NeuroLinkError | null;
+/**
+ * Validate complete video generation input
+ *
+ * Validates all requirements for video generation:
+ * - output.mode must be "video"
+ * - Must have exactly one input image
+ * - Prompt must be within length limits
+ * - Video output options must be valid
+ *
+ * @param options - GenerateOptions to validate for video generation
+ * @returns EnhancedValidationResult with errors, warnings, and suggestions
+ *
+ * @example
+ * ```typescript
+ * const validation = validateVideoGenerationInput({
+ *   input: { text: "Product showcase video", images: [imageBuffer] },
+ *   output: { mode: "video", video: { resolution: "1080p" } }
+ * });
+ * if (!validation.isValid) {
+ *   console.error(validation.errors);
+ * }
+ * ```
+ */
+export declare function validateVideoGenerationInput(options: GenerateOptions): EnhancedValidationResult;
 /**
  * Create a validation error summary for logging
  */

package/dist/lib/utils/parameterValidation.js

@@ -3,6 +3,7 @@
  * Provides consistent parameter validation across all tool interfaces
  */
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { ErrorFactory, NeuroLinkError } from "./errorHandling.js";
 import { isNonNullObject } from "./typeUtils.js";
 // ============================================================================
 // VALIDATION ERROR TYPES
@@ -407,6 +408,201 @@ export function validateToolBatch(tools) {
     };
 }
 // ============================================================================
+// VIDEO GENERATION VALIDATORS
+// ============================================================================
+/**
+ * Convert a NeuroLinkError to a ValidationError shape
+ * Used to maintain consistent error types in validation results
+ */
+function toValidationError(error) {
+    return new ValidationError(error.message, error.field, error.code, error.suggestions);
+}
+/**
+ * Valid video generation options
+ */
+const VALID_VIDEO_RESOLUTIONS = ["720p", "1080p"];
+const VALID_VIDEO_LENGTHS = [4, 6, 8];
+const VALID_VIDEO_ASPECT_RATIOS = ["9:16", "16:9"];
+const MAX_VIDEO_PROMPT_LENGTH = 500;
+const MAX_VIDEO_IMAGE_SIZE = 10 * 1024 * 1024; // 10MB
+/**
+ * Validate video output options (resolution, length, aspect ratio, audio)
+ *
+ * @param options - VideoOutputOptions to validate
+ * @returns NeuroLinkError if invalid, null if valid
+ *
+ * @example
+ * ```typescript
+ * const error = validateVideoOutputOptions({ resolution: "4K", length: 10 });
+ * // error.code === "INVALID_VIDEO_RESOLUTION"
+ * ```
+ */
+export function validateVideoOutputOptions(options) {
+    // Validate resolution
+    if (options.resolution &&
+        !VALID_VIDEO_RESOLUTIONS.includes(options.resolution)) {
+        return ErrorFactory.invalidVideoResolution(options.resolution);
+    }
+    // Validate length
+    if (options.length !== undefined &&
+        !VALID_VIDEO_LENGTHS.includes(options.length)) {
+        return ErrorFactory.invalidVideoLength(options.length);
+    }
+    // Validate aspect ratio
+    if (options.aspectRatio &&
+        !VALID_VIDEO_ASPECT_RATIOS.includes(options.aspectRatio)) {
+        return ErrorFactory.invalidVideoAspectRatio(options.aspectRatio);
+    }
+    // Validate audio (must be boolean if provided)
+    if (options.audio !== undefined && typeof options.audio !== "boolean") {
+        return ErrorFactory.invalidVideoAudio(options.audio);
+    }
+    return null;
+}
+/**
+ * Validate image input for video generation
+ *
+ * Checks image format (magic bytes) and size constraints.
+ * Supports JPEG, PNG, and WebP formats.
+ *
+ * @param image - Image buffer to validate
+ * @param maxSize - Maximum allowed size in bytes (default: 10MB)
+ * @returns NeuroLinkError if invalid, null if valid
+ *
+ * @example
+ * ```typescript
+ * const imageBuffer = readFileSync("product.jpg");
+ * const error = validateImageForVideo(imageBuffer);
+ * if (error) throw error;
+ * ```
+ */
+export function validateImageForVideo(image, maxSize = MAX_VIDEO_IMAGE_SIZE) {
+    // Handle null/undefined
+    if (image === null || image === undefined) {
+        return ErrorFactory.invalidImageType();
+    }
+    // If string (URL or path), skip detailed validation
+    if (typeof image === "string") {
+        // Basic URL/path validation
+        if (image.trim().length === 0) {
+            return ErrorFactory.emptyImagePath();
+        }
+        return null;
+    }
+    // Ensure it's a Buffer
+    if (!Buffer.isBuffer(image)) {
+        return ErrorFactory.invalidImageType();
+    }
+    // Check size
+    if (image.length > maxSize) {
+        const sizeMB = (image.length / 1024 / 1024).toFixed(2);
+        const maxMB = (maxSize / 1024 / 1024).toFixed(0);
+        return ErrorFactory.imageTooLarge(sizeMB, maxMB);
+    }
+    // Check minimum size (at least a few bytes for magic number detection)
+    if (image.length < 8) {
+        return ErrorFactory.imageTooSmall();
+    }
+    // Check magic bytes for supported formats
+    const isJPEG = image[0] === 0xff && image[1] === 0xd8 && image[2] === 0xff;
+    const isPNG = image[0] === 0x89 &&
+        image[1] === 0x50 &&
+        image[2] === 0x4e &&
+        image[3] === 0x47;
+    // WebP requires both RIFF header AND WEBP signature
+    // Check for WebP: RIFF at bytes 0-3 AND "WEBP" at bytes 8-11
+    const isWebP = image.length >= 12 &&
+        image[0] === 0x52 &&
+        image[1] === 0x49 &&
+        image[2] === 0x46 &&
+        image[3] === 0x46 && // RIFF header
+        image[8] === 0x57 &&
+        image[9] === 0x45 &&
+        image[10] === 0x42 &&
+        image[11] === 0x50; // WEBP signature
+    const isValidFormat = isJPEG || isPNG || isWebP;
+    if (!isValidFormat) {
+        return ErrorFactory.invalidImageFormat();
+    }
+    return null;
+}
+/**
+ * Validate complete video generation input
+ *
+ * Validates all requirements for video generation:
+ * - output.mode must be "video"
+ * - Must have exactly one input image
+ * - Prompt must be within length limits
+ * - Video output options must be valid
+ *
+ * @param options - GenerateOptions to validate for video generation
+ * @returns EnhancedValidationResult with errors, warnings, and suggestions
+ *
+ * @example
+ * ```typescript
+ * const validation = validateVideoGenerationInput({
+ *   input: { text: "Product showcase video", images: [imageBuffer] },
+ *   output: { mode: "video", video: { resolution: "1080p" } }
+ * });
+ * if (!validation.isValid) {
+ *   console.error(validation.errors);
+ * }
+ * ```
+ */
+export function validateVideoGenerationInput(options) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    // Must have video mode
+    if (options.output?.mode !== "video") {
+        errors.push(toValidationError(ErrorFactory.invalidVideoMode()));
+    }
+    // Must have at least one image
+    if (!options.input?.images || options.input.images.length === 0) {
+        errors.push(toValidationError(ErrorFactory.missingVideoImage()));
+    }
+    else if (options.input.images.length > 1) {
+        // Warn if multiple images provided - only first will be used
+        warnings.push("Only the first image will be used for video generation. Additional images will be ignored.");
+        suggestions.push("Provide a single image for video generation");
+    }
+    // Validate the first image if present
+    if (options.input?.images && options.input.images.length > 0) {
+        const firstImage = options.input.images[0];
+        // Handle ImageWithAltText type
+        const imageData = typeof firstImage === "object" && "data" in firstImage
+            ? firstImage.data
+            : firstImage;
+        // Skip validation for URL/path strings, validate Buffers
+        if (typeof imageData !== "string") {
+            const imageError = validateImageForVideo(imageData);
+            if (imageError) {
+                errors.push(toValidationError(imageError));
+            }
+        }
+    }
+    // Validate prompt/text - trim once for consistency
+    const trimmedPrompt = options.input?.text?.trim() || "";
+    if (trimmedPrompt.length === 0) {
+        errors.push(toValidationError(ErrorFactory.emptyVideoPrompt()));
+    }
+    else if (trimmedPrompt.length > MAX_VIDEO_PROMPT_LENGTH) {
+        errors.push(toValidationError(ErrorFactory.videoPromptTooLong(trimmedPrompt.length, MAX_VIDEO_PROMPT_LENGTH)));
+    }
+    // Validate video output options if provided
+    if (options.output?.video) {
+        const videoError = validateVideoOutputOptions(options.output.video);
+        if (videoError) {
+            errors.push(toValidationError(videoError));
+        }
+    }
+    // Add helpful suggestions
+    if (errors.length === 0 && warnings.length === 0) {
+        suggestions.push("Video generation takes 60-180 seconds. Consider setting a longer timeout.");
+    }
+    return { isValid: errors.length === 0, errors, warnings, suggestions };
+}
+// ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
 /**