@juspay/neurolink 8.41.1 → 8.42.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [8.42.0](https://github.com/juspay/neurolink/compare/v8.41.1...v8.42.0) (2026-02-02)
+
+### Features
+
+- **(cache):** Implemented LRU cache for image downloads ([6562c45](https://github.com/juspay/neurolink/commit/6562c45605a6031afe41bdfcc5de0a7687127c3f))
+
 ## [8.41.1](https://github.com/juspay/neurolink/compare/v8.41.0...v8.41.1) (2026-01-31)
 
 ### Bug Fixes

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

@@ -190,3 +190,54 @@ export type EnvVarValidationResult = {
     invalidVars: string[];
     warnings: string[];
 };
+/**
+ * Cached image entry structure for image cache
+ */
+export type CachedImage = {
+    /** The image data as a base64 data URI */
+    dataUri: string;
+    /** Content type of the image (e.g., "image/jpeg") */
+    contentType: string;
+    /** Size of the image in bytes */
+    size: number;
+    /** SHA-256 hash of the image content for deduplication */
+    contentHash: string;
+    /** Timestamp when the entry was created */
+    createdAt: number;
+    /** Timestamp of last access */
+    lastAccessedAt: number;
+    /** Number of times this entry was accessed */
+    accessCount: number;
+};
+/**
+ * Configuration options for the image cache
+ */
+export type ImageCacheConfig = {
+    /** Maximum number of entries in the cache (default: 100) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 30 minutes) */
+    ttlMs?: number;
+    /** Maximum size per image in bytes (default: 10MB) */
+    maxImageSize?: number;
+};
+/**
+ * Cache statistics for monitoring
+ */
+export type ImageCacheStats = {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of entries evicted due to size limits */
+    evictions: number;
+    /** Number of entries expired due to TTL */
+    expirations: number;
+    /** Total number of requests */
+    totalRequests: number;
+    /** Current number of entries in cache */
+    size: number;
+    /** Total size of cached images in bytes */
+    totalBytes: number;
+    /** Cache hit rate as percentage */
+    hitRate: number;
+};

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

@@ -0,0 +1,116 @@
+/**
+ * Image Cache Utility for NeuroLink
+ *
+ * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
+ * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction strategy
+ * - Configurable cache size and TTL
+ * - Cache hit/miss metrics
+ * - Content hash tracking for deduplication
+ *
+ * @module utils/imageCache
+ */
+import type { CachedImage, ImageCacheConfig, ImageCacheStats } from "../types/utilities.js";
+/**
+ * LRU Cache for downloaded images
+ *
+ * Uses URL as primary key and tracks content hashes for deduplication.
+ * Implements LRU eviction and configurable TTL for memory management.
+ */
+export declare class ImageCache {
+    private cache;
+    private contentHashIndex;
+    private maxSize;
+    private ttlMs;
+    private maxImageSize;
+    private enabled;
+    private stats;
+    constructor(config?: ImageCacheConfig);
+    /**
+     * Parse a config value with bounds checking
+     */
+    private parseConfigValue;
+    /**
+     * Normalize URL for consistent cache key generation
+     * Removes tracking parameters and normalizes the URL
+     */
+    private normalizeUrl;
+    /**
+     * Generate content hash from image data
+     */
+    private generateContentHash;
+    /**
+     * Check if an entry is expired based on TTL
+     */
+    private isExpired;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get a cached image by URL
+     * Returns null if not found or expired
+     */
+    get(url: string): CachedImage | null;
+    /**
+     * Get a cached image by content hash
+     * Useful for deduplication when the same image is accessed via different URLs
+     */
+    getByContentHash(contentHash: string): CachedImage | null;
+    /**
+     * Store an image in the cache
+     */
+    set(url: string, dataUri: string, contentType: string, imageData: Buffer): void;
+    /**
+     * Delete an entry from the cache
+     */
+    delete(url: string): boolean;
+    /**
+     * Evict the oldest (least recently used) entry
+     */
+    private evictOldest;
+    /**
+     * Clear all expired entries
+     */
+    evictExpired(): number;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): ImageCacheStats;
+    /**
+     * Check if a URL is cached and not expired
+     */
+    has(url: string): boolean;
+    /**
+     * Get the current cache size
+     */
+    getSize(): number;
+    /**
+     * Get cache configuration
+     */
+    getConfig(): {
+        enabled: boolean;
+        maxSize: number;
+        ttlMs: number;
+        maxImageSize: number;
+    };
+}
+/**
+ * Get the global image cache instance
+ * Creates a new instance if none exists
+ */
+export declare function getImageCache(config?: ImageCacheConfig): ImageCache;
+/**
+ * Reset the global image cache (useful for testing)
+ */
+export declare function resetImageCache(): void;
+/**
+ * Get image cache statistics from the global instance
+ */
+export declare function getImageCacheStats(): ImageCacheStats | null;

package/dist/lib/utils/imageCache.js

@@ -0,0 +1,377 @@
+/**
+ * Image Cache Utility for NeuroLink
+ *
+ * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
+ * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction strategy
+ * - Configurable cache size and TTL
+ * - Cache hit/miss metrics
+ * - Content hash tracking for deduplication
+ *
+ * @module utils/imageCache
+ */
+import { createHash } from "crypto";
+import { logger } from "./logger.js";
+/**
+ * LRU Cache for downloaded images
+ *
+ * Uses URL as primary key and tracks content hashes for deduplication.
+ * Implements LRU eviction and configurable TTL for memory management.
+ */
+export class ImageCache {
+    cache = new Map();
+    contentHashIndex = new Map(); // contentHash -> url
+    maxSize;
+    ttlMs;
+    maxImageSize;
+    enabled;
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        expirations: 0,
+        totalRequests: 0,
+    };
+    constructor(config = {}) {
+        // Parse configuration with environment variable overrides
+        const envEnabled = process.env.NEUROLINK_IMAGE_CACHE_ENABLED;
+        const envMaxSize = process.env.NEUROLINK_IMAGE_CACHE_SIZE;
+        const envTtlMs = process.env.NEUROLINK_IMAGE_CACHE_TTL_MS;
+        const envMaxImageSize = process.env.NEUROLINK_IMAGE_MAX_SIZE;
+        // Check if cache is enabled (default: false)
+        this.enabled =
+            envEnabled !== undefined ? envEnabled.toLowerCase() === "true" : false;
+        this.maxSize = this.parseConfigValue(envMaxSize, config.maxSize, 100, 1, 1000);
+        this.ttlMs = this.parseConfigValue(envTtlMs, config.ttlMs, 30 * 60 * 1000, // 30 minutes
+        1000, // 1 second min
+        24 * 60 * 60 * 1000);
+        this.maxImageSize = this.parseConfigValue(envMaxImageSize, config.maxImageSize, 10 * 1024 * 1024, // 10MB
+        1024, // 1KB min
+        100 * 1024 * 1024);
+        logger.debug("ImageCache initialized", {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        });
+    }
+    /**
+     * Parse a config value with bounds checking
+     */
+    parseConfigValue(envValue, configValue, defaultValue, min, max) {
+        let value;
+        if (envValue !== undefined) {
+            const parsed = parseInt(envValue, 10);
+            value = isNaN(parsed) ? defaultValue : parsed;
+        }
+        else if (configValue !== undefined) {
+            value = configValue;
+        }
+        else {
+            value = defaultValue;
+        }
+        // Apply bounds
+        if (value < min) {
+            logger.warn(`Cache config value ${value} below minimum ${min}, using min`);
+            return min;
+        }
+        if (value > max) {
+            logger.warn(`Cache config value ${value} above maximum ${max}, using max`);
+            return max;
+        }
+        return value;
+    }
+    /**
+     * Normalize URL for consistent cache key generation
+     * Removes tracking parameters and normalizes the URL
+     */
+    normalizeUrl(url) {
+        try {
+            const parsed = new URL(url);
+            // Remove common tracking parameters that don't affect content
+            const trackingParams = [
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "fbclid",
+                "gclid",
+                "_ga",
+            ];
+            trackingParams.forEach((param) => parsed.searchParams.delete(param));
+            return parsed.toString();
+        }
+        catch {
+            // If URL parsing fails, use the original URL
+            return url;
+        }
+    }
+    /**
+     * Generate content hash from image data
+     */
+    generateContentHash(data) {
+        const buffer = typeof data === "string" ? Buffer.from(data, "base64") : data;
+        return createHash("sha256").update(buffer).digest("hex").substring(0, 16);
+    }
+    /**
+     * Check if an entry is expired based on TTL
+     */
+    isExpired(entry) {
+        return Date.now() - entry.createdAt > this.ttlMs;
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get a cached image by URL
+     * Returns null if not found or expired
+     */
+    get(url) {
+        // Return null immediately if cache is disabled
+        if (!this.enabled) {
+            return null;
+        }
+        this.stats.totalRequests++;
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        if (!entry) {
+            this.stats.misses++;
+            logger.debug("Image cache miss", { url: normalizedUrl.substring(0, 50) });
+            return null;
+        }
+        // Check TTL expiration
+        if (this.isExpired(entry)) {
+            this.stats.expirations++;
+            this.delete(normalizedUrl);
+            logger.debug("Image cache entry expired", {
+                url: normalizedUrl.substring(0, 50),
+            });
+            return null;
+        }
+        // Update LRU info
+        entry.lastAccessedAt = Date.now();
+        entry.accessCount++;
+        // Move to end (most recently used) - delete and re-add
+        this.cache.delete(normalizedUrl);
+        this.cache.set(normalizedUrl, entry);
+        this.stats.hits++;
+        logger.debug("Image cache hit", {
+            url: normalizedUrl.substring(0, 50),
+            accessCount: entry.accessCount,
+        });
+        return entry;
+    }
+    /**
+     * Get a cached image by content hash
+     * Useful for deduplication when the same image is accessed via different URLs
+     */
+    getByContentHash(contentHash) {
+        const url = this.contentHashIndex.get(contentHash);
+        if (!url) {
+            return null;
+        }
+        return this.get(url);
+    }
+    /**
+     * Store an image in the cache
+     */
+    set(url, dataUri, contentType, imageData) {
+        // Skip caching if disabled
+        if (!this.enabled) {
+            logger.debug("Image caching disabled, skipping cache storage");
+            return;
+        }
+        const normalizedUrl = this.normalizeUrl(url);
+        const size = imageData.length;
+        // Skip caching if image exceeds max size
+        if (size > this.maxImageSize) {
+            logger.debug("Image too large to cache", {
+                url: normalizedUrl.substring(0, 50),
+                size,
+                maxSize: this.maxImageSize,
+            });
+            return;
+        }
+        // Generate content hash
+        const contentHash = this.generateContentHash(imageData);
+        // Check if same content already exists under different URL
+        const existingUrl = this.contentHashIndex.get(contentHash);
+        if (existingUrl && existingUrl !== normalizedUrl) {
+            // Content already cached under different URL - create a shallow copy
+            const existingEntry = this.cache.get(existingUrl);
+            if (existingEntry && !this.isExpired(existingEntry)) {
+                // Create a shallow copy for the new URL to avoid shared reference issues
+                this.cache.set(normalizedUrl, { ...existingEntry });
+                // Update content hash index to point to the new URL as well
+                this.contentHashIndex.set(contentHash, normalizedUrl);
+                logger.debug("Image cache dedup hit", {
+                    newUrl: normalizedUrl.substring(0, 50),
+                    existingUrl: existingUrl.substring(0, 50),
+                });
+                return;
+            }
+        }
+        // Evict if at capacity
+        while (this.cache.size >= this.maxSize) {
+            this.evictOldest();
+        }
+        const now = Date.now();
+        const entry = {
+            dataUri,
+            contentType,
+            size,
+            contentHash,
+            createdAt: now,
+            lastAccessedAt: now,
+            accessCount: 1,
+        };
+        this.cache.set(normalizedUrl, entry);
+        this.contentHashIndex.set(contentHash, normalizedUrl);
+        logger.debug("Image cached", {
+            url: normalizedUrl.substring(0, 50),
+            size,
+            contentHash: contentHash.substring(0, 8),
+            cacheSize: this.cache.size,
+        });
+    }
+    /**
+     * Delete an entry from the cache
+     */
+    delete(url) {
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        if (entry) {
+            // Remove from content hash index
+            if (this.contentHashIndex.get(entry.contentHash) === normalizedUrl) {
+                this.contentHashIndex.delete(entry.contentHash);
+            }
+            this.cache.delete(normalizedUrl);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Evict the oldest (least recently used) entry
+     */
+    evictOldest() {
+        // Map maintains insertion order, first entry is oldest
+        const oldestKey = this.cache.keys().next().value;
+        if (oldestKey !== undefined) {
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                if (this.contentHashIndex.get(entry.contentHash) === oldestKey) {
+                    this.contentHashIndex.delete(entry.contentHash);
+                }
+            }
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            logger.debug("Image cache eviction", {
+                url: String(oldestKey).substring(0, 50),
+            });
+        }
+    }
+    /**
+     * Clear all expired entries
+     */
+    evictExpired() {
+        let evicted = 0;
+        const now = Date.now();
+        for (const [url, entry] of this.cache.entries()) {
+            if (now - entry.createdAt > this.ttlMs) {
+                this.delete(url);
+                evicted++;
+                this.stats.expirations++;
+            }
+        }
+        if (evicted > 0) {
+            logger.debug(`Evicted ${evicted} expired image cache entries`);
+        }
+        return evicted;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.contentHashIndex.clear();
+        logger.debug(`Image cache cleared (${size} entries removed)`);
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let totalBytes = 0;
+        for (const entry of this.cache.values()) {
+            totalBytes += entry.size;
+        }
+        const hitRate = this.stats.totalRequests > 0
+            ? Number(((this.stats.hits / this.stats.totalRequests) * 100).toFixed(2))
+            : 0;
+        return {
+            ...this.stats,
+            size: this.cache.size,
+            totalBytes,
+            hitRate,
+        };
+    }
+    /**
+     * Check if a URL is cached and not expired
+     */
+    has(url) {
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        return entry !== null && entry !== undefined && !this.isExpired(entry);
+    }
+    /**
+     * Get the current cache size
+     */
+    getSize() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        };
+    }
+}
+// Global image cache instance
+let globalImageCache = null;
+/**
+ * Get the global image cache instance
+ * Creates a new instance if none exists
+ */
+export function getImageCache(config) {
+    if (!globalImageCache) {
+        globalImageCache = new ImageCache(config);
+    }
+    return globalImageCache;
+}
+/**
+ * Reset the global image cache (useful for testing)
+ */
+export function resetImageCache() {
+    if (globalImageCache) {
+        globalImageCache.clear();
+        globalImageCache = null;
+    }
+}
+/**
+ * Get image cache statistics from the global instance
+ */
+export function getImageCacheStats() {
+    return globalImageCache ? globalImageCache.getStats() : null;
+}
+//# sourceMappingURL=imageCache.js.map

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

@@ -138,6 +138,7 @@ export declare const imageUtils: {
      * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
      * @returns Promise<string> - Base64 data URI of the downloaded image
      * Rate-limited to 10 downloads per second to prevent DoS
+     * Uses LRU cache to avoid redundant downloads of the same URL
      */
     urlToBase64DataUri: (url: string, { timeoutMs, maxBytes, maxAttempts, }?: {
         timeoutMs?: number;

package/dist/lib/utils/imageProcessor.js

@@ -6,6 +6,7 @@ import { logger } from "./logger.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { withRetry } from "./retryHandler.js";
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { getImageCache } from "./imageCache.js";
 /**
  * Network error codes that should trigger a retry
  */
@@ -546,8 +547,16 @@ export const imageUtils = {
      * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
      * @returns Promise<string> - Base64 data URI of the downloaded image
      * Rate-limited to 10 downloads per second to prevent DoS
+     * Uses LRU cache to avoid redundant downloads of the same URL
      */
     urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024, maxAttempts = 3, } = {}) => {
+        // Check cache first
+        const cache = getImageCache();
+        const cached = cache.get(url);
+        if (cached) {
+            logger.debug("Using cached image for URL", { url: url.substring(0, 50) });
+            return cached.dataUri;
+        }
         // Apply rate limiting before download
         await urlDownloadRateLimiter.acquire();
         // Basic protocol whitelist - fail fast, no retry needed
@@ -575,8 +584,12 @@ export const imageUtils = {
                 if (buffer.byteLength > maxBytes) {
                     throw new Error(`Downloaded content too large: ${buffer.byteLength} bytes`);
                 }
-                const base64 = Buffer.from(buffer).toString("base64");
-                return `data:${contentType || "image/jpeg"};base64,${base64}`;
+                const imageBuffer = Buffer.from(buffer);
+                const base64 = imageBuffer.toString("base64");
+                const dataUri = `data:${contentType || "image/jpeg"};base64,${base64}`;
+                // Store in cache for future use
+                cache.set(url, dataUri, contentType || "image/jpeg", imageBuffer);
+                return dataUri;
             }
             finally {
                 clearTimeout(t);

package/dist/lib/utils/messageBuilder.js

@@ -10,6 +10,7 @@ import { FileDetector } from "./fileDetector.js";
 import { PDFProcessor, PDFImageConverter } from "./pdfProcessor.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { request, getGlobalDispatcher, interceptors } from "undici";
+import { getImageCache } from "./imageCache.js";
 import { readFileSync, existsSync } from "fs";
 /**
  * Type guard to check if an image input has alt text
@@ -625,9 +626,17 @@ function isInternetUrl(input) {
 /**
  * Download image from URL and convert to base64 data URI
  * Rate-limited to 10 downloads per second to prevent DoS
+ * Uses LRU cache to avoid redundant downloads of the same URL
  */
 async function downloadImageFromUrl(url) {
-    // Apply rate limiting before download
+    // Check cache first (before rate limiting)
+    const cache = getImageCache();
+    const cached = cache.get(url);
+    if (cached) {
+        logger.debug("Using cached image for URL", { url: url.substring(0, 50) });
+        return cached.dataUri;
+    }
+    // Apply rate limiting only if cache missed
     await urlDownloadRateLimiter.acquire();
     try {
         const response = await request(url, {
@@ -659,6 +668,8 @@ async function downloadImageFromUrl(url) {
         // Convert to base64 data URI
         const base64 = buffer.toString("base64");
         const dataUri = `data:${contentType};base64,${base64}`;
+        // Store in cache for future use
+        cache.set(url, dataUri, contentType, buffer);
         return dataUri;
     }
     catch (error) {

package/dist/types/utilities.d.ts

@@ -190,3 +190,54 @@ export type EnvVarValidationResult = {
     invalidVars: string[];
     warnings: string[];
 };
+/**
+ * Cached image entry structure for image cache
+ */
+export type CachedImage = {
+    /** The image data as a base64 data URI */
+    dataUri: string;
+    /** Content type of the image (e.g., "image/jpeg") */
+    contentType: string;
+    /** Size of the image in bytes */
+    size: number;
+    /** SHA-256 hash of the image content for deduplication */
+    contentHash: string;
+    /** Timestamp when the entry was created */
+    createdAt: number;
+    /** Timestamp of last access */
+    lastAccessedAt: number;
+    /** Number of times this entry was accessed */
+    accessCount: number;
+};
+/**
+ * Configuration options for the image cache
+ */
+export type ImageCacheConfig = {
+    /** Maximum number of entries in the cache (default: 100) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 30 minutes) */
+    ttlMs?: number;
+    /** Maximum size per image in bytes (default: 10MB) */
+    maxImageSize?: number;
+};
+/**
+ * Cache statistics for monitoring
+ */
+export type ImageCacheStats = {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of entries evicted due to size limits */
+    evictions: number;
+    /** Number of entries expired due to TTL */
+    expirations: number;
+    /** Total number of requests */
+    totalRequests: number;
+    /** Current number of entries in cache */
+    size: number;
+    /** Total size of cached images in bytes */
+    totalBytes: number;
+    /** Cache hit rate as percentage */
+    hitRate: number;
+};

package/dist/utils/imageCache.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Image Cache Utility for NeuroLink
+ *
+ * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
+ * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction strategy
+ * - Configurable cache size and TTL
+ * - Cache hit/miss metrics
+ * - Content hash tracking for deduplication
+ *
+ * @module utils/imageCache
+ */
+import type { CachedImage, ImageCacheConfig, ImageCacheStats } from "../types/utilities.js";
+/**
+ * LRU Cache for downloaded images
+ *
+ * Uses URL as primary key and tracks content hashes for deduplication.
+ * Implements LRU eviction and configurable TTL for memory management.
+ */
+export declare class ImageCache {
+    private cache;
+    private contentHashIndex;
+    private maxSize;
+    private ttlMs;
+    private maxImageSize;
+    private enabled;
+    private stats;
+    constructor(config?: ImageCacheConfig);
+    /**
+     * Parse a config value with bounds checking
+     */
+    private parseConfigValue;
+    /**
+     * Normalize URL for consistent cache key generation
+     * Removes tracking parameters and normalizes the URL
+     */
+    private normalizeUrl;
+    /**
+     * Generate content hash from image data
+     */
+    private generateContentHash;
+    /**
+     * Check if an entry is expired based on TTL
+     */
+    private isExpired;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get a cached image by URL
+     * Returns null if not found or expired
+     */
+    get(url: string): CachedImage | null;
+    /**
+     * Get a cached image by content hash
+     * Useful for deduplication when the same image is accessed via different URLs
+     */
+    getByContentHash(contentHash: string): CachedImage | null;
+    /**
+     * Store an image in the cache
+     */
+    set(url: string, dataUri: string, contentType: string, imageData: Buffer): void;
+    /**
+     * Delete an entry from the cache
+     */
+    delete(url: string): boolean;
+    /**
+     * Evict the oldest (least recently used) entry
+     */
+    private evictOldest;
+    /**
+     * Clear all expired entries
+     */
+    evictExpired(): number;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): ImageCacheStats;
+    /**
+     * Check if a URL is cached and not expired
+     */
+    has(url: string): boolean;
+    /**
+     * Get the current cache size
+     */
+    getSize(): number;
+    /**
+     * Get cache configuration
+     */
+    getConfig(): {
+        enabled: boolean;
+        maxSize: number;
+        ttlMs: number;
+        maxImageSize: number;
+    };
+}
+/**
+ * Get the global image cache instance
+ * Creates a new instance if none exists
+ */
+export declare function getImageCache(config?: ImageCacheConfig): ImageCache;
+/**
+ * Reset the global image cache (useful for testing)
+ */
+export declare function resetImageCache(): void;
+/**
+ * Get image cache statistics from the global instance
+ */
+export declare function getImageCacheStats(): ImageCacheStats | null;

package/dist/utils/imageCache.js

@@ -0,0 +1,376 @@
+/**
+ * Image Cache Utility for NeuroLink
+ *
+ * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
+ * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction strategy
+ * - Configurable cache size and TTL
+ * - Cache hit/miss metrics
+ * - Content hash tracking for deduplication
+ *
+ * @module utils/imageCache
+ */
+import { createHash } from "crypto";
+import { logger } from "./logger.js";
+/**
+ * LRU Cache for downloaded images
+ *
+ * Uses URL as primary key and tracks content hashes for deduplication.
+ * Implements LRU eviction and configurable TTL for memory management.
+ */
+export class ImageCache {
+    cache = new Map();
+    contentHashIndex = new Map(); // contentHash -> url
+    maxSize;
+    ttlMs;
+    maxImageSize;
+    enabled;
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        expirations: 0,
+        totalRequests: 0,
+    };
+    constructor(config = {}) {
+        // Parse configuration with environment variable overrides
+        const envEnabled = process.env.NEUROLINK_IMAGE_CACHE_ENABLED;
+        const envMaxSize = process.env.NEUROLINK_IMAGE_CACHE_SIZE;
+        const envTtlMs = process.env.NEUROLINK_IMAGE_CACHE_TTL_MS;
+        const envMaxImageSize = process.env.NEUROLINK_IMAGE_MAX_SIZE;
+        // Check if cache is enabled (default: false)
+        this.enabled =
+            envEnabled !== undefined ? envEnabled.toLowerCase() === "true" : false;
+        this.maxSize = this.parseConfigValue(envMaxSize, config.maxSize, 100, 1, 1000);
+        this.ttlMs = this.parseConfigValue(envTtlMs, config.ttlMs, 30 * 60 * 1000, // 30 minutes
+        1000, // 1 second min
+        24 * 60 * 60 * 1000);
+        this.maxImageSize = this.parseConfigValue(envMaxImageSize, config.maxImageSize, 10 * 1024 * 1024, // 10MB
+        1024, // 1KB min
+        100 * 1024 * 1024);
+        logger.debug("ImageCache initialized", {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        });
+    }
+    /**
+     * Parse a config value with bounds checking
+     */
+    parseConfigValue(envValue, configValue, defaultValue, min, max) {
+        let value;
+        if (envValue !== undefined) {
+            const parsed = parseInt(envValue, 10);
+            value = isNaN(parsed) ? defaultValue : parsed;
+        }
+        else if (configValue !== undefined) {
+            value = configValue;
+        }
+        else {
+            value = defaultValue;
+        }
+        // Apply bounds
+        if (value < min) {
+            logger.warn(`Cache config value ${value} below minimum ${min}, using min`);
+            return min;
+        }
+        if (value > max) {
+            logger.warn(`Cache config value ${value} above maximum ${max}, using max`);
+            return max;
+        }
+        return value;
+    }
+    /**
+     * Normalize URL for consistent cache key generation
+     * Removes tracking parameters and normalizes the URL
+     */
+    normalizeUrl(url) {
+        try {
+            const parsed = new URL(url);
+            // Remove common tracking parameters that don't affect content
+            const trackingParams = [
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "fbclid",
+                "gclid",
+                "_ga",
+            ];
+            trackingParams.forEach((param) => parsed.searchParams.delete(param));
+            return parsed.toString();
+        }
+        catch {
+            // If URL parsing fails, use the original URL
+            return url;
+        }
+    }
+    /**
+     * Generate content hash from image data
+     */
+    generateContentHash(data) {
+        const buffer = typeof data === "string" ? Buffer.from(data, "base64") : data;
+        return createHash("sha256").update(buffer).digest("hex").substring(0, 16);
+    }
+    /**
+     * Check if an entry is expired based on TTL
+     */
+    isExpired(entry) {
+        return Date.now() - entry.createdAt > this.ttlMs;
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get a cached image by URL
+     * Returns null if not found or expired
+     */
+    get(url) {
+        // Return null immediately if cache is disabled
+        if (!this.enabled) {
+            return null;
+        }
+        this.stats.totalRequests++;
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        if (!entry) {
+            this.stats.misses++;
+            logger.debug("Image cache miss", { url: normalizedUrl.substring(0, 50) });
+            return null;
+        }
+        // Check TTL expiration
+        if (this.isExpired(entry)) {
+            this.stats.expirations++;
+            this.delete(normalizedUrl);
+            logger.debug("Image cache entry expired", {
+                url: normalizedUrl.substring(0, 50),
+            });
+            return null;
+        }
+        // Update LRU info
+        entry.lastAccessedAt = Date.now();
+        entry.accessCount++;
+        // Move to end (most recently used) - delete and re-add
+        this.cache.delete(normalizedUrl);
+        this.cache.set(normalizedUrl, entry);
+        this.stats.hits++;
+        logger.debug("Image cache hit", {
+            url: normalizedUrl.substring(0, 50),
+            accessCount: entry.accessCount,
+        });
+        return entry;
+    }
+    /**
+     * Get a cached image by content hash
+     * Useful for deduplication when the same image is accessed via different URLs
+     */
+    getByContentHash(contentHash) {
+        const url = this.contentHashIndex.get(contentHash);
+        if (!url) {
+            return null;
+        }
+        return this.get(url);
+    }
+    /**
+     * Store an image in the cache
+     */
+    set(url, dataUri, contentType, imageData) {
+        // Skip caching if disabled
+        if (!this.enabled) {
+            logger.debug("Image caching disabled, skipping cache storage");
+            return;
+        }
+        const normalizedUrl = this.normalizeUrl(url);
+        const size = imageData.length;
+        // Skip caching if image exceeds max size
+        if (size > this.maxImageSize) {
+            logger.debug("Image too large to cache", {
+                url: normalizedUrl.substring(0, 50),
+                size,
+                maxSize: this.maxImageSize,
+            });
+            return;
+        }
+        // Generate content hash
+        const contentHash = this.generateContentHash(imageData);
+        // Check if same content already exists under different URL
+        const existingUrl = this.contentHashIndex.get(contentHash);
+        if (existingUrl && existingUrl !== normalizedUrl) {
+            // Content already cached under different URL - create a shallow copy
+            const existingEntry = this.cache.get(existingUrl);
+            if (existingEntry && !this.isExpired(existingEntry)) {
+                // Create a shallow copy for the new URL to avoid shared reference issues
+                this.cache.set(normalizedUrl, { ...existingEntry });
+                // Update content hash index to point to the new URL as well
+                this.contentHashIndex.set(contentHash, normalizedUrl);
+                logger.debug("Image cache dedup hit", {
+                    newUrl: normalizedUrl.substring(0, 50),
+                    existingUrl: existingUrl.substring(0, 50),
+                });
+                return;
+            }
+        }
+        // Evict if at capacity
+        while (this.cache.size >= this.maxSize) {
+            this.evictOldest();
+        }
+        const now = Date.now();
+        const entry = {
+            dataUri,
+            contentType,
+            size,
+            contentHash,
+            createdAt: now,
+            lastAccessedAt: now,
+            accessCount: 1,
+        };
+        this.cache.set(normalizedUrl, entry);
+        this.contentHashIndex.set(contentHash, normalizedUrl);
+        logger.debug("Image cached", {
+            url: normalizedUrl.substring(0, 50),
+            size,
+            contentHash: contentHash.substring(0, 8),
+            cacheSize: this.cache.size,
+        });
+    }
+    /**
+     * Delete an entry from the cache
+     */
+    delete(url) {
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        if (entry) {
+            // Remove from content hash index
+            if (this.contentHashIndex.get(entry.contentHash) === normalizedUrl) {
+                this.contentHashIndex.delete(entry.contentHash);
+            }
+            this.cache.delete(normalizedUrl);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Evict the oldest (least recently used) entry
+     */
+    evictOldest() {
+        // Map maintains insertion order, first entry is oldest
+        const oldestKey = this.cache.keys().next().value;
+        if (oldestKey !== undefined) {
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                if (this.contentHashIndex.get(entry.contentHash) === oldestKey) {
+                    this.contentHashIndex.delete(entry.contentHash);
+                }
+            }
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            logger.debug("Image cache eviction", {
+                url: String(oldestKey).substring(0, 50),
+            });
+        }
+    }
+    /**
+     * Clear all expired entries
+     */
+    evictExpired() {
+        let evicted = 0;
+        const now = Date.now();
+        for (const [url, entry] of this.cache.entries()) {
+            if (now - entry.createdAt > this.ttlMs) {
+                this.delete(url);
+                evicted++;
+                this.stats.expirations++;
+            }
+        }
+        if (evicted > 0) {
+            logger.debug(`Evicted ${evicted} expired image cache entries`);
+        }
+        return evicted;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.contentHashIndex.clear();
+        logger.debug(`Image cache cleared (${size} entries removed)`);
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let totalBytes = 0;
+        for (const entry of this.cache.values()) {
+            totalBytes += entry.size;
+        }
+        const hitRate = this.stats.totalRequests > 0
+            ? Number(((this.stats.hits / this.stats.totalRequests) * 100).toFixed(2))
+            : 0;
+        return {
+            ...this.stats,
+            size: this.cache.size,
+            totalBytes,
+            hitRate,
+        };
+    }
+    /**
+     * Check if a URL is cached and not expired
+     */
+    has(url) {
+        const normalizedUrl = this.normalizeUrl(url);
+        const entry = this.cache.get(normalizedUrl);
+        return entry !== null && entry !== undefined && !this.isExpired(entry);
+    }
+    /**
+     * Get the current cache size
+     */
+    getSize() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return {
+            enabled: this.enabled,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            maxImageSize: this.maxImageSize,
+        };
+    }
+}
+// Global image cache instance
+let globalImageCache = null;
+/**
+ * Get the global image cache instance
+ * Creates a new instance if none exists
+ */
+export function getImageCache(config) {
+    if (!globalImageCache) {
+        globalImageCache = new ImageCache(config);
+    }
+    return globalImageCache;
+}
+/**
+ * Reset the global image cache (useful for testing)
+ */
+export function resetImageCache() {
+    if (globalImageCache) {
+        globalImageCache.clear();
+        globalImageCache = null;
+    }
+}
+/**
+ * Get image cache statistics from the global instance
+ */
+export function getImageCacheStats() {
+    return globalImageCache ? globalImageCache.getStats() : null;
+}

package/dist/utils/imageProcessor.d.ts

@@ -138,6 +138,7 @@ export declare const imageUtils: {
      * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
      * @returns Promise<string> - Base64 data URI of the downloaded image
      * Rate-limited to 10 downloads per second to prevent DoS
+     * Uses LRU cache to avoid redundant downloads of the same URL
      */
     urlToBase64DataUri: (url: string, { timeoutMs, maxBytes, maxAttempts, }?: {
         timeoutMs?: number;

package/dist/utils/imageProcessor.js

@@ -6,6 +6,7 @@ import { logger } from "./logger.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { withRetry } from "./retryHandler.js";
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { getImageCache } from "./imageCache.js";
 /**
  * Network error codes that should trigger a retry
  */
@@ -546,8 +547,16 @@ export const imageUtils = {
      * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
      * @returns Promise<string> - Base64 data URI of the downloaded image
      * Rate-limited to 10 downloads per second to prevent DoS
+     * Uses LRU cache to avoid redundant downloads of the same URL
      */
     urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024, maxAttempts = 3, } = {}) => {
+        // Check cache first
+        const cache = getImageCache();
+        const cached = cache.get(url);
+        if (cached) {
+            logger.debug("Using cached image for URL", { url: url.substring(0, 50) });
+            return cached.dataUri;
+        }
         // Apply rate limiting before download
         await urlDownloadRateLimiter.acquire();
         // Basic protocol whitelist - fail fast, no retry needed
@@ -575,8 +584,12 @@ export const imageUtils = {
                 if (buffer.byteLength > maxBytes) {
                     throw new Error(`Downloaded content too large: ${buffer.byteLength} bytes`);
                 }
-                const base64 = Buffer.from(buffer).toString("base64");
-                return `data:${contentType || "image/jpeg"};base64,${base64}`;
+                const imageBuffer = Buffer.from(buffer);
+                const base64 = imageBuffer.toString("base64");
+                const dataUri = `data:${contentType || "image/jpeg"};base64,${base64}`;
+                // Store in cache for future use
+                cache.set(url, dataUri, contentType || "image/jpeg", imageBuffer);
+                return dataUri;
             }
             finally {
                 clearTimeout(t);

package/dist/utils/messageBuilder.js

@@ -10,6 +10,7 @@ import { FileDetector } from "./fileDetector.js";
 import { PDFProcessor, PDFImageConverter } from "./pdfProcessor.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { request, getGlobalDispatcher, interceptors } from "undici";
+import { getImageCache } from "./imageCache.js";
 import { readFileSync, existsSync } from "fs";
 /**
  * Type guard to check if an image input has alt text
@@ -625,9 +626,17 @@ function isInternetUrl(input) {
 /**
  * Download image from URL and convert to base64 data URI
  * Rate-limited to 10 downloads per second to prevent DoS
+ * Uses LRU cache to avoid redundant downloads of the same URL
  */
 async function downloadImageFromUrl(url) {
-    // Apply rate limiting before download
+    // Check cache first (before rate limiting)
+    const cache = getImageCache();
+    const cached = cache.get(url);
+    if (cached) {
+        logger.debug("Using cached image for URL", { url: url.substring(0, 50) });
+        return cached.dataUri;
+    }
+    // Apply rate limiting only if cache missed
     await urlDownloadRateLimiter.acquire();
     try {
         const response = await request(url, {
@@ -659,6 +668,8 @@ async function downloadImageFromUrl(url) {
         // Convert to base64 data URI
         const base64 = buffer.toString("base64");
         const dataUri = `data:${contentType};base64,${base64}`;
+        // Store in cache for future use
+        cache.set(url, dataUri, contentType, buffer);
         return dataUri;
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.41.1",
+  "version": "8.42.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",