@juspay/neurolink 9.95.0 → 9.95.2

package/dist/utils/errorHandling.js

@@ -52,6 +52,8 @@ export const ERROR_CODES = {
     CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
+    PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
     // Rate limiter errors
     RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
     RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
@@ -553,6 +555,32 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PASSWORD_REQUIRED,
+            message: "This PDF is password-protected. Supply the password via " +
+                "`pdfOptions: { password: '…' }` (SDK) or `--pdf-password` (CLI).",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_INCORRECT_PASSWORD,
+            message: "The password supplied for this PDF is incorrect. Check the " +
+                "`pdfOptions.password` / `--pdf-password` value and try again.",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
     /**
      * Create an image too large error
      */

package/dist/utils/logger.d.ts

@@ -162,6 +162,17 @@ declare class NeuroLinkLogger {
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args: unknown[]): void;
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -200,6 +211,7 @@ export declare const logger: {
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
+    alwaysStderr: (...args: unknown[]) => void;
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;

package/dist/utils/logger.js

@@ -347,6 +347,19 @@ class NeuroLinkLogger {
     always(...args) {
         console.log(...args);
     }
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args) {
+        console.error(...args);
+    }
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -436,6 +449,9 @@ export const logger = {
     always: (...args) => {
         neuroLinkLogger.always(...args);
     },
+    alwaysStderr: (...args) => {
+        neuroLinkLogger.alwaysStderr(...args);
+    },
     table: (data) => {
         neuroLinkLogger.table(data);
     },

package/dist/utils/messageBuilder.js

@@ -1011,6 +1011,12 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                     buffer: result.content,
                     filename,
                     pageCount: result.metadata?.estimatedPages ?? null,
+                    // #258: carry the password so the image-fallback conversion can
+                    // decrypt an encrypted PDF for providers without native PDF support.
+                    password: options.pdfOptions?.password,
+                    // #260: carry the per-page canvas-pixel ceiling so the caller can
+                    // raise (or lower) the memory guard for the image-fallback render.
+                    maxCanvasPixels: options.pdfOptions?.maxCanvasPixels,
                 });
                 logger.info(`[PDF] ✅ Queued for multimodal: ${filename} (${result.metadata?.estimatedPages ?? "unknown"} pages)`);
             }
@@ -1103,7 +1109,13 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Check if this is a multimodal request
     const hasImages = (inp.images && inp.images.length > 0) ||
         (inp.content && inp.content.some((c) => c.type === "image"));
-    const hasPDFs = pdfFiles.length > 0;
+    // A PDF supplied only via input.content (type: "pdf", no explicit
+    // input.pdfFiles and no image alongside it) must still route through the
+    // multimodal path below — otherwise it silently falls through to the
+    // text-only branch and the PDF (and any pdfOptions) never reaches
+    // convertContentToProviderFormat at all.
+    const hasPDFs = pdfFiles.length > 0 ||
+        !!(inp.content && inp.content.some((c) => c.type === "pdf"));
     // If no images or PDFs, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages && !hasPDFs) {
         // #289: CSV content[] items don't need vision, so they never reach the
@@ -1139,8 +1151,11 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
             `Supported providers: ${ProviderImageAdapter.getVisionProviders().join(", ")}`);
     }
     const messages = [];
-    // Build enhanced system prompt
-    const systemPrompt = buildMultimodalSystemPrompt(options, pdfFiles.length > 0);
+    // Build enhanced system prompt. Gate on the same `hasPDFs` predicate used
+    // for routing above — a PDF supplied only via input.content (no explicit
+    // input.pdfFiles) must still get the "treat inlined content as an
+    // attachment" instruction, or the model can claim no files were attached.
+    const systemPrompt = buildMultimodalSystemPrompt(options, hasPDFs);
     if (systemPrompt.trim()) {
         messages.push({
             role: "system",
@@ -1206,7 +1221,7 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     try {
         let userContent;
         if (inp.content && inp.content.length > 0) {
-            userContent = await convertContentToProviderFormat(inp.content, provider, model);
+            userContent = await convertContentToProviderFormat(inp.content, provider, model, options.pdfOptions);
         }
         else if ((inp.images && inp.images.length > 0) || pdfFiles.length > 0) {
             userContent = await convertMultimodalToProviderFormat(inp.text ?? "", inp.images || [], pdfFiles, provider, model);
@@ -1285,7 +1300,7 @@ async function appendCsvContentToText(csvItems, baseText) {
 /**
  * Convert advanced content format to provider-specific format
  */
-async function convertContentToProviderFormat(content, provider, _model) {
+async function convertContentToProviderFormat(content, provider, _model, pdfOptions) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
     const pdfContent = content.filter((c) => c.type === "pdf");
@@ -1312,6 +1327,11 @@ async function convertContentToProviderFormat(content, provider, _model) {
         buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
         filename: pdf.metadata?.filename || "document.pdf",
         pageCount: pdf.metadata?.pages ?? null,
+        // #258/#260: carry password + canvas-pixel ceiling so a PDF supplied via
+        // the advanced `input.content` array gets the same decryption/memory
+        // guard as the `input.pdfFiles` path (see `processExplicitPdfFiles`).
+        password: pdfOptions?.password,
+        maxCanvasPixels: pdfOptions?.maxCanvasPixels,
     }));
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
@@ -1694,6 +1714,10 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
                 const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
                     scale: 2.0, // High quality for OCR/analysis
                     maxPages: 20, // Limit pages to prevent token overflow
+                    ...(pdf.password ? { password: pdf.password } : {}), // #258
+                    ...(pdf.maxCanvasPixels
+                        ? { maxCanvasPixels: pdf.maxCanvasPixels }
+                        : {}), // #260
                 });
                 logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
                 // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
@@ -1715,6 +1739,13 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 logger.error(`[PDF→Image] ❌ Failed to convert ${pdf.filename}: ${errorMessage}`);
+                // #258: password errors are already actionable typed errors — re-throw
+                // them unwrapped so the "supply a password" guidance isn't buried.
+                const code = error?.code;
+                if (code === "PDF_PASSWORD_REQUIRED" ||
+                    code === "PDF_INCORRECT_PASSWORD") {
+                    throw error;
+                }
                 // Re-throw so the user knows PDF processing failed
                 throw new Error(`PDF to image conversion failed for ${pdf.filename}: ${errorMessage}. ` +
                     `Provider ${provider} doesn't support native PDFs and image conversion failed.`, { cause: error });

package/dist/utils/multimodalOptionsBuilder.d.ts

@@ -51,6 +51,10 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
     csvOptions: import("../index.js").CSVProcessorOptions | undefined;
+    pdfOptions: {
+        password?: string;
+        maxCanvasPixels?: number;
+    } | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../index.js").ChatMessage[] | undefined;
     provider: string;

package/dist/utils/multimodalOptionsBuilder.js

@@ -51,6 +51,7 @@ export function buildMultimodalOptions(options, providerName, modelName) {
             pdfFiles: options.input?.pdfFiles,
         },
         csvOptions: options.csvOptions,
+        pdfOptions: options.pdfOptions,
         systemPrompt: options.systemPrompt,
         conversationHistory: options.conversationMessages,
         provider: providerName,

package/dist/utils/pdfProcessor.d.ts

@@ -21,6 +21,21 @@ export declare class PDFProcessor {
     private static isValidPDF;
     private static extractBasicMetadata;
     static estimateTokens(pageCount: number, mode?: "text-only" | "visual"): number;
+    /**
+     * Estimate the largest page's rendered pixel count from the PDF's MediaBox
+     * entries, WITHOUT rendering (#260). Parses `/MediaBox [llx lly urx ury]`
+     * (dimensions in points); rendered pixels ≈ (width·scale)·(height·scale).
+     * Returns 0 when no plaintext MediaBox is found (e.g. compressed object
+     * streams) — the caller then skips downscaling, matching prior behavior.
+     *
+     * A crafted/malformed MediaBox can have finite but astronomically large
+     * width/height; `width * height * scale * scale` can then overflow past
+     * `Number.MAX_VALUE` to `Infinity`. Clamp the product to
+     * `Number.MAX_SAFE_INTEGER` so it stays finite — a large-but-finite pixel
+     * estimate still triggers downscaling, whereas `Infinity` would collapse
+     * the computed downscale factor to 0 (see `convertToImages`).
+     */
+    private static largestPagePixels;
     /**
      * Convert a PDF buffer to an array of base64 PNG images
      *

package/dist/utils/pdfProcessor.js

@@ -231,6 +231,40 @@ export class PDFProcessor {
     // ============================================================================
     // PDF → Image Conversion (for providers without native PDF support)
     // ============================================================================
+    /**
+     * Estimate the largest page's rendered pixel count from the PDF's MediaBox
+     * entries, WITHOUT rendering (#260). Parses `/MediaBox [llx lly urx ury]`
+     * (dimensions in points); rendered pixels ≈ (width·scale)·(height·scale).
+     * Returns 0 when no plaintext MediaBox is found (e.g. compressed object
+     * streams) — the caller then skips downscaling, matching prior behavior.
+     *
+     * A crafted/malformed MediaBox can have finite but astronomically large
+     * width/height; `width * height * scale * scale` can then overflow past
+     * `Number.MAX_VALUE` to `Infinity`. Clamp the product to
+     * `Number.MAX_SAFE_INTEGER` so it stays finite — a large-but-finite pixel
+     * estimate still triggers downscaling, whereas `Infinity` would collapse
+     * the computed downscale factor to 0 (see `convertToImages`).
+     */
+    static largestPagePixels(pdfBuffer, scale) {
+        const text = pdfBuffer.toString("latin1");
+        const re = /\/MediaBox\s*\[\s*(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s*\]/g;
+        let max = 0;
+        let match;
+        while ((match = re.exec(text)) !== null) {
+            const width = Math.abs(parseFloat(match[3]) - parseFloat(match[1]));
+            const height = Math.abs(parseFloat(match[4]) - parseFloat(match[2]));
+            if (Number.isFinite(width) && Number.isFinite(height)) {
+                const pixels = width * height * scale * scale;
+                const boundedPixels = Number.isFinite(pixels)
+                    ? Math.min(pixels, Number.MAX_SAFE_INTEGER)
+                    : Number.MAX_SAFE_INTEGER;
+                if (boundedPixels > max) {
+                    max = boundedPixels;
+                }
+            }
+        }
+        return max;
+    }
     /**
      * Convert a PDF buffer to an array of base64 PNG images
      *
@@ -257,7 +291,7 @@ export class PDFProcessor {
      */
     static async convertToImages(pdfBuffer, options) {
         const startTime = Date.now();
-        const { scale = 2, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", } = options || {};
+        const { scale = 2, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, } = options || {};
         const images = [];
         const warnings = [];
         // ============================================================================
@@ -273,6 +307,11 @@ export class PDFProcessor {
         if (!Number.isFinite(scale) || scale <= 0 || scale > PDF_LIMITS.MAX_SCALE) {
             throw new Error(`Invalid scale: ${scale}. Scale must be a finite number greater than 0 and at most ${PDF_LIMITS.MAX_SCALE}.`);
         }
+        // 0c. Validate the per-page pixel ceiling (#260). A non-finite or
+        // non-positive value would disable the guard or yield a NaN downscale.
+        if (!Number.isFinite(maxCanvasPixels) || maxCanvasPixels <= 0) {
+            throw new Error(`Invalid maxCanvasPixels: ${maxCanvasPixels}. Must be a finite number greater than 0.`);
+        }
         // 1. Validate buffer is not empty or too small
         if (!pdfBuffer || pdfBuffer.length < 5) {
             throw new Error("Invalid PDF: Buffer is too small or empty. " +
@@ -303,8 +342,38 @@ export class PDFProcessor {
                 scale,
                 maxPages: maxPages || "all",
             });
-            // Create PDF document iterator
-            const document = await pdf(pdfBuffer, { scale });
+            // #260: pre-flight page-size check WITHOUT rendering. pdf-to-img applies
+            // `scale` uniformly with no per-page hook and no pixel guard, so a very
+            // large page (e.g. an architectural drawing with a huge MediaBox) can
+            // allocate gigabytes of canvas. Read the largest MediaBox from the PDF
+            // bytes and, if that page at the requested scale would exceed
+            // maxCanvasPixels, downscale the whole render uniformly to stay under it.
+            let effectiveScale = scale;
+            const largestPixels = PDFProcessor.largestPagePixels(pdfBuffer, scale);
+            if (largestPixels > maxCanvasPixels) {
+                const downscale = Math.sqrt(maxCanvasPixels / largestPixels);
+                // Floor the result: an astronomically large (but now finite, see
+                // `largestPagePixels`) pixel estimate would otherwise push `downscale`
+                // — and therefore `effectiveScale` — toward 0, handing `pdf-to-img` a
+                // degenerate viewport instead of a small-but-renderable page.
+                effectiveScale = Math.max(PDF_LIMITS.MIN_EFFECTIVE_SCALE, scale * downscale);
+                // Recompute the ratio actually applied (may differ from `downscale`
+                // when the floor above kicks in) so the logged estimate stays honest.
+                const actualDownscale = effectiveScale / scale;
+                const beforeMB = (largestPixels * 4) / (1024 * 1024);
+                const afterMB = (largestPixels * actualDownscale * actualDownscale * 4) /
+                    (1024 * 1024);
+                const msg = `Downscaled render (scale ${scale} → ${effectiveScale.toFixed(3)}): ` +
+                    `the largest page would allocate ~${beforeMB.toFixed(0)}MB, above the ` +
+                    `maxCanvasPixels ceiling; reduced to ~${afterMB.toFixed(0)}MB per page.`;
+                logger.warn(`[PDF→Image] ⚠️ ${msg}`);
+                warnings.push(msg);
+            }
+            // Create PDF document iterator (password forwarded for encrypted PDFs, #258)
+            const document = await pdf(pdfBuffer, {
+                scale: effectiveScale,
+                ...(password ? { password } : {}),
+            });
             let pageIndex = 0;
             // Iterate through pages and convert to base64
             for await (const page of document) {
@@ -346,6 +415,17 @@ export class PDFProcessor {
                 error: errorMessage,
                 conversionTimeMs,
             });
+            // #258: map pdfjs's PasswordException to an actionable typed error so a
+            // caller learns to supply (or correct) the password instead of seeing a
+            // generic "conversion failed". pdfjs code 1 = NEED_PASSWORD, 2 = INCORRECT.
+            const pdfErr = error;
+            if (pdfErr?.name === "PasswordException" ||
+                /password/i.test(errorMessage)) {
+                const incorrect = pdfErr.code === 2 || /incorrect|invalid/i.test(errorMessage);
+                throw incorrect
+                    ? ErrorFactory.pdfIncorrectPassword()
+                    : ErrorFactory.pdfPasswordRequired();
+            }
             throw new Error(`PDF to image conversion failed: ${errorMessage}`, {
                 cause: error,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.95.0",
+  "version": "9.95.2",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {