@juspay/neurolink 8.6.0 → 8.7.0

package/dist/lib/utils/imageProcessor.js

@@ -3,6 +3,57 @@
  * Handles format conversion for different AI providers
  */
 import { logger } from "./logger.js";
+import { withRetry } from "./retryHandler.js";
+import { SYSTEM_LIMITS } from "../core/constants.js";
+/**
+ * Network error codes that should trigger a retry
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "ERR_NETWORK",
+]);
+/**
+ * Determines if an HTTP error is retryable based on status code
+ * Only network errors and certain HTTP status codes should be retried
+ * 4xx client errors like 404 (Not Found) and 403 (Forbidden) should NOT be retried
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable, false otherwise
+ */
+function isRetryableDownloadError(error) {
+    // Network-related errors should be retried
+    if (error && typeof error === "object") {
+        const errorCode = error.code;
+        const errorName = error.name;
+        if (RETRYABLE_ERROR_CODES.has(errorCode || "") ||
+            errorName === "AbortError") {
+            return true;
+        }
+    }
+    // Check for HTTP status code in error message for retryable errors
+    // Only retry on 5xx server errors, 429 (Too Many Requests), and 408 (Request Timeout)
+    // Do NOT retry on 4xx client errors like 404 (Not Found) or 403 (Forbidden)
+    if (error instanceof Error) {
+        const message = error.message;
+        // Extract HTTP status from error message like "HTTP 503: Service Unavailable"
+        const statusMatch = message.match(/HTTP (\d{3}):/);
+        if (statusMatch) {
+            const status = parseInt(statusMatch[1], 10);
+            // Retry on 5xx server errors, 429 (rate limit), 408 (timeout)
+            return status >= 500 || status === 429 || status === 408;
+        }
+        // Check for timeout/network-related error messages
+        // Use more precise matching to avoid false positives like "No timeout specified"
+        if (/\b(request timed out|operation timed out|connection timed out|timed out)\b/i.test(message) ||
+            /\bnetwork (error|failure|unreachable|down)\b/i.test(message)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Image processor class for handling provider-specific image formatting
  */
@@ -16,9 +67,16 @@ export class ImageProcessor {
      * @returns Processed image as data URI
      */
     static async process(content, _options) {
+        // Validate content is non-empty before processing
+        if (content.length === 0) {
+            logger.error("Empty buffer provided");
+            throw new Error("Invalid image processing: buffer is empty");
+        }
         const mediaType = this.detectImageType(content);
         const base64 = content.toString("base64");
         const dataUri = `data:${mediaType};base64,${base64}`;
+        // Validate output before returning
+        this.validateProcessOutput(dataUri, base64, mediaType);
         return {
             type: "image",
             content: dataUri,
@@ -29,6 +87,37 @@ export class ImageProcessor {
             },
         };
     }
+    /**
+     * Validate processed output meets required format
+     * Checks:
+     * - Base64 content is non-empty
+     * - Data URI format is valid (data:{mimeType};base64,{content})
+     * - MIME type is in the allowed list
+     * @param dataUri - The complete data URI string
+     * @param base64 - The base64-encoded content
+     * @param mediaType - The MIME type of the image
+     * @throws Error if any validation fails
+     */
+    static validateProcessOutput(dataUri, base64, mediaType) {
+        // Validate base64 is non-empty (check first for better error message)
+        if (base64.length === 0) {
+            logger.error("Empty base64 content generated");
+            throw new Error("Invalid image processing: base64 content is empty");
+        }
+        // Validate data URI format with proper base64 character validation
+        // Base64 can only have 0, 1, or 2 padding characters at the end
+        const dataUriRegex = /^data:[^;]+;base64,[A-Za-z0-9+/]*={0,2}$/;
+        if (!dataUriRegex.test(dataUri)) {
+            logger.error("Invalid data URI format generated", { dataUri });
+            throw new Error("Invalid data URI format: must be data:{mimeType};base64,{content}");
+        }
+        // Defensive check: ensure detectImageType() returns valid MIME type
+        // This validation protects against future changes to detectImageType()
+        if (!this.validateImageFormat(mediaType)) {
+            logger.error("Invalid MIME type generated", { mediaType });
+            throw new Error(`Invalid MIME type: ${mediaType} is not in allowed list`);
+        }
+    }
     /**
      * Process image for OpenAI (requires data URI format)
      */
@@ -434,14 +523,35 @@ export const imageUtils = {
         }
     },
     /**
-     * Convert URL to base64 data URI by downloading the image
+     * Convert URL to base64 data URI by downloading the image.
+     * Implements retry logic with exponential backoff for network errors.
+     *
+     * Retries are performed for:
+     * - Network errors (ECONNRESET, ENOTFOUND, ECONNREFUSED, ETIMEDOUT, ERR_NETWORK, AbortError)
+     * - Server errors (5xx status codes)
+     * - Rate limiting (429 Too Many Requests)
+     * - Request timeouts (408 Request Timeout)
+     *
+     * Retries are NOT performed for:
+     * - Client errors (4xx status codes except 408, 429)
+     * - Invalid content type
+     * - Content size limit exceeded
+     * - Unsupported protocol
+     *
+     * @param url - The URL of the image to download
+     * @param options - Configuration options
+     * @param options.timeoutMs - Timeout for each download attempt (default: 15000ms)
+     * @param options.maxBytes - Maximum allowed file size (default: 10MB)
+     * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
+     * @returns Promise<string> - Base64 data URI of the downloaded image
      */
-    urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024 } = {}) => {
-        try {
-            // Basic protocol whitelist
-            if (!/^https?:\/\//i.test(url)) {
-                throw new Error("Unsupported protocol");
-            }
+    urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024, maxAttempts = 3, } = {}) => {
+        // Basic protocol whitelist - fail fast, no retry needed
+        if (!/^https?:\/\//i.test(url)) {
+            throw new Error("Unsupported protocol");
+        }
+        // Perform the actual download with retry logic
+        const performDownload = async () => {
             const controller = new AbortController();
             const t = setTimeout(() => controller.abort(), timeoutMs);
             try {
@@ -467,6 +577,20 @@ export const imageUtils = {
             finally {
                 clearTimeout(t);
             }
+        };
+        try {
+            return await withRetry(performDownload, {
+                maxAttempts,
+                initialDelay: SYSTEM_LIMITS.DEFAULT_INITIAL_DELAY,
+                backoffMultiplier: SYSTEM_LIMITS.DEFAULT_BACKOFF_MULTIPLIER,
+                maxDelay: SYSTEM_LIMITS.DEFAULT_MAX_DELAY,
+                retryCondition: isRetryableDownloadError,
+                onRetry: (attempt, error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    const attemptsLeft = maxAttempts - attempt;
+                    logger.warn(`⚠️ Image download attempt ${attempt} failed for ${url}: ${message}. ${attemptsLeft} ${attemptsLeft === 1 ? "attempt" : "attempts"} remaining...`);
+                },
+            });
         }
         catch (error) {
             throw new Error(`Failed to download and convert URL to base64: ${error instanceof Error ? error.message : "Unknown error"}`);

package/dist/lib/utils/pdfProcessor.js

@@ -1,6 +1,6 @@
 import { logger } from "./logger.js";
-import * as pdfjs from "pdfjs-dist/legacy/build/pdf.mjs";
-import { createCanvas } from "canvas";
+// Lazy-load pdfjs-dist to avoid DOMMatrix errors in Node.js server environment
+// import * as pdfjs from "pdfjs-dist/legacy/build/pdf.mjs";
 const PDF_PROVIDER_CONFIGS = {
     anthropic: {
         maxSizeMB: 5,
@@ -196,6 +196,28 @@ export class PDFProcessor {
         }
     }
     static async convertPDFToImages(pdfBuffer, options) {
+        // Dynamic import canvas - only load when actually needed
+        let createCanvas;
+        try {
+            const canvasModule = await import("canvas");
+            createCanvas = canvasModule.createCanvas;
+        }
+        catch {
+            throw new Error("Canvas dependency not available. " +
+                "PDF-to-image conversion requires the 'canvas' package with native bindings. " +
+                "Install with: pnpm install canvas\n" +
+                "Note: This requires native build tools (Python, C++ compiler).");
+        }
+        // Dynamic import pdfjs - only load when actually needed to avoid DOMMatrix errors
+        let pdfjs;
+        try {
+            pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+        }
+        catch {
+            throw new Error("pdfjs-dist dependency not available. " +
+                "PDF processing requires the 'pdfjs-dist' package. " +
+                "Install with: pnpm install pdfjs-dist");
+        }
         const maxPages = options?.maxPages || 10;
         const scale = options?.scale || 2.0;
         const format = options?.format || "png";

package/dist/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/types/fileTypes.d.ts

@@ -81,18 +81,7 @@ export type PDFProcessorOptions = {
     bedrockApiMode?: "converse" | "invokeModel";
 };
 /**
- * File detector options
- */
-export type FileDetectorOptions = {
-    maxSize?: number;
-    timeout?: number;
-    allowedTypes?: FileType[];
-    csvOptions?: CSVProcessorOptions;
-    confidenceThreshold?: number;
-    provider?: string;
-};
-/**
- * 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 +97,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/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/types/index.js

@@ -35,3 +35,5 @@ 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";

package/dist/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/types/ttsTypes.js

@@ -0,0 +1,57 @@
+/**
+ * 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;
+}

package/dist/utils/imageProcessor.d.ts

@@ -17,6 +17,18 @@ export declare class ImageProcessor {
      * @returns Processed image as data URI
      */
     static process(content: Buffer, _options?: unknown): Promise<FileProcessingResult>;
+    /**
+     * Validate processed output meets required format
+     * Checks:
+     * - Base64 content is non-empty
+     * - Data URI format is valid (data:{mimeType};base64,{content})
+     * - MIME type is in the allowed list
+     * @param dataUri - The complete data URI string
+     * @param base64 - The base64-encoded content
+     * @param mediaType - The MIME type of the image
+     * @throws Error if any validation fails
+     */
+    private static validateProcessOutput;
     /**
      * Process image for OpenAI (requires data URI format)
      */
@@ -104,11 +116,32 @@ export declare const imageUtils: {
      */
     fileToBase64DataUri: (filePath: string, maxBytes?: number) => Promise<string>;
     /**
-     * Convert URL to base64 data URI by downloading the image
-     */
-    urlToBase64DataUri: (url: string, { timeoutMs, maxBytes }?: {
-        timeoutMs?: number | undefined;
-        maxBytes?: number | undefined;
+     * Convert URL to base64 data URI by downloading the image.
+     * Implements retry logic with exponential backoff for network errors.
+     *
+     * Retries are performed for:
+     * - Network errors (ECONNRESET, ENOTFOUND, ECONNREFUSED, ETIMEDOUT, ERR_NETWORK, AbortError)
+     * - Server errors (5xx status codes)
+     * - Rate limiting (429 Too Many Requests)
+     * - Request timeouts (408 Request Timeout)
+     *
+     * Retries are NOT performed for:
+     * - Client errors (4xx status codes except 408, 429)
+     * - Invalid content type
+     * - Content size limit exceeded
+     * - Unsupported protocol
+     *
+     * @param url - The URL of the image to download
+     * @param options - Configuration options
+     * @param options.timeoutMs - Timeout for each download attempt (default: 15000ms)
+     * @param options.maxBytes - Maximum allowed file size (default: 10MB)
+     * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
+     * @returns Promise<string> - Base64 data URI of the downloaded image
+     */
+    urlToBase64DataUri: (url: string, { timeoutMs, maxBytes, maxAttempts, }?: {
+        timeoutMs?: number;
+        maxBytes?: number;
+        maxAttempts?: number;
     }) => Promise<string>;
     /**
      * Extract base64 data from data URI

package/dist/utils/imageProcessor.js

@@ -3,6 +3,57 @@
  * Handles format conversion for different AI providers
  */
 import { logger } from "./logger.js";
+import { withRetry } from "./retryHandler.js";
+import { SYSTEM_LIMITS } from "../core/constants.js";
+/**
+ * Network error codes that should trigger a retry
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "ERR_NETWORK",
+]);
+/**
+ * Determines if an HTTP error is retryable based on status code
+ * Only network errors and certain HTTP status codes should be retried
+ * 4xx client errors like 404 (Not Found) and 403 (Forbidden) should NOT be retried
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable, false otherwise
+ */
+function isRetryableDownloadError(error) {
+    // Network-related errors should be retried
+    if (error && typeof error === "object") {
+        const errorCode = error.code;
+        const errorName = error.name;
+        if (RETRYABLE_ERROR_CODES.has(errorCode || "") ||
+            errorName === "AbortError") {
+            return true;
+        }
+    }
+    // Check for HTTP status code in error message for retryable errors
+    // Only retry on 5xx server errors, 429 (Too Many Requests), and 408 (Request Timeout)
+    // Do NOT retry on 4xx client errors like 404 (Not Found) or 403 (Forbidden)
+    if (error instanceof Error) {
+        const message = error.message;
+        // Extract HTTP status from error message like "HTTP 503: Service Unavailable"
+        const statusMatch = message.match(/HTTP (\d{3}):/);
+        if (statusMatch) {
+            const status = parseInt(statusMatch[1], 10);
+            // Retry on 5xx server errors, 429 (rate limit), 408 (timeout)
+            return status >= 500 || status === 429 || status === 408;
+        }
+        // Check for timeout/network-related error messages
+        // Use more precise matching to avoid false positives like "No timeout specified"
+        if (/\b(request timed out|operation timed out|connection timed out|timed out)\b/i.test(message) ||
+            /\bnetwork (error|failure|unreachable|down)\b/i.test(message)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Image processor class for handling provider-specific image formatting
  */
@@ -16,9 +67,16 @@ export class ImageProcessor {
      * @returns Processed image as data URI
      */
     static async process(content, _options) {
+        // Validate content is non-empty before processing
+        if (content.length === 0) {
+            logger.error("Empty buffer provided");
+            throw new Error("Invalid image processing: buffer is empty");
+        }
         const mediaType = this.detectImageType(content);
         const base64 = content.toString("base64");
         const dataUri = `data:${mediaType};base64,${base64}`;
+        // Validate output before returning
+        this.validateProcessOutput(dataUri, base64, mediaType);
         return {
             type: "image",
             content: dataUri,
@@ -29,6 +87,37 @@ export class ImageProcessor {
             },
         };
     }
+    /**
+     * Validate processed output meets required format
+     * Checks:
+     * - Base64 content is non-empty
+     * - Data URI format is valid (data:{mimeType};base64,{content})
+     * - MIME type is in the allowed list
+     * @param dataUri - The complete data URI string
+     * @param base64 - The base64-encoded content
+     * @param mediaType - The MIME type of the image
+     * @throws Error if any validation fails
+     */
+    static validateProcessOutput(dataUri, base64, mediaType) {
+        // Validate base64 is non-empty (check first for better error message)
+        if (base64.length === 0) {
+            logger.error("Empty base64 content generated");
+            throw new Error("Invalid image processing: base64 content is empty");
+        }
+        // Validate data URI format with proper base64 character validation
+        // Base64 can only have 0, 1, or 2 padding characters at the end
+        const dataUriRegex = /^data:[^;]+;base64,[A-Za-z0-9+/]*={0,2}$/;
+        if (!dataUriRegex.test(dataUri)) {
+            logger.error("Invalid data URI format generated", { dataUri });
+            throw new Error("Invalid data URI format: must be data:{mimeType};base64,{content}");
+        }
+        // Defensive check: ensure detectImageType() returns valid MIME type
+        // This validation protects against future changes to detectImageType()
+        if (!this.validateImageFormat(mediaType)) {
+            logger.error("Invalid MIME type generated", { mediaType });
+            throw new Error(`Invalid MIME type: ${mediaType} is not in allowed list`);
+        }
+    }
     /**
      * Process image for OpenAI (requires data URI format)
      */
@@ -434,14 +523,35 @@ export const imageUtils = {
         }
     },
     /**
-     * Convert URL to base64 data URI by downloading the image
+     * Convert URL to base64 data URI by downloading the image.
+     * Implements retry logic with exponential backoff for network errors.
+     *
+     * Retries are performed for:
+     * - Network errors (ECONNRESET, ENOTFOUND, ECONNREFUSED, ETIMEDOUT, ERR_NETWORK, AbortError)
+     * - Server errors (5xx status codes)
+     * - Rate limiting (429 Too Many Requests)
+     * - Request timeouts (408 Request Timeout)
+     *
+     * Retries are NOT performed for:
+     * - Client errors (4xx status codes except 408, 429)
+     * - Invalid content type
+     * - Content size limit exceeded
+     * - Unsupported protocol
+     *
+     * @param url - The URL of the image to download
+     * @param options - Configuration options
+     * @param options.timeoutMs - Timeout for each download attempt (default: 15000ms)
+     * @param options.maxBytes - Maximum allowed file size (default: 10MB)
+     * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
+     * @returns Promise<string> - Base64 data URI of the downloaded image
      */
-    urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024 } = {}) => {
-        try {
-            // Basic protocol whitelist
-            if (!/^https?:\/\//i.test(url)) {
-                throw new Error("Unsupported protocol");
-            }
+    urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024, maxAttempts = 3, } = {}) => {
+        // Basic protocol whitelist - fail fast, no retry needed
+        if (!/^https?:\/\//i.test(url)) {
+            throw new Error("Unsupported protocol");
+        }
+        // Perform the actual download with retry logic
+        const performDownload = async () => {
             const controller = new AbortController();
             const t = setTimeout(() => controller.abort(), timeoutMs);
             try {
@@ -467,6 +577,20 @@ export const imageUtils = {
             finally {
                 clearTimeout(t);
             }
+        };
+        try {
+            return await withRetry(performDownload, {
+                maxAttempts,
+                initialDelay: SYSTEM_LIMITS.DEFAULT_INITIAL_DELAY,
+                backoffMultiplier: SYSTEM_LIMITS.DEFAULT_BACKOFF_MULTIPLIER,
+                maxDelay: SYSTEM_LIMITS.DEFAULT_MAX_DELAY,
+                retryCondition: isRetryableDownloadError,
+                onRetry: (attempt, error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    const attemptsLeft = maxAttempts - attempt;
+                    logger.warn(`⚠️ Image download attempt ${attempt} failed for ${url}: ${message}. ${attemptsLeft} ${attemptsLeft === 1 ? "attempt" : "attempts"} remaining...`);
+                },
+            });
         }
         catch (error) {
             throw new Error(`Failed to download and convert URL to base64: ${error instanceof Error ? error.message : "Unknown error"}`);