@juspay/neurolink 9.95.1 → 9.95.3

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/fileDetector.js

@@ -1413,6 +1413,41 @@ export class FileDetector {
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
+        // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
+        // body. content-length is advisory (chunked responses omit it), so a
+        // missing/invalid header — or a server that refuses HEAD — falls through to
+        // the streaming byte guard below; only a genuine oversize rejection stops
+        // the GET from ever running.
+        //
+        // #323: skip the pre-flight entirely when this exact URL was recently seen
+        // (its Content-Type is still cached, whether from a prior loadFromURL GET
+        // or a MimeTypeStrategy HEAD) — issuing a fresh HEAD here would defeat the
+        // whole point of that cache. The streaming byte guard in the GET below
+        // still enforces maxSize even without a pre-flight, so this doesn't remove
+        // the oversize protection — it only skips the redundant round-trip for a
+        // URL we've already been talking to within the last 60s.
+        if (getCachedUrlContentType(url, Date.now()) === undefined) {
+            try {
+                const head = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "HEAD",
+                    headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                    bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                });
+                // Drain/close the (empty) HEAD body so the connection can be reused.
+                await head.body.dump();
+                const declaredLength = Number(head.headers["content-length"]);
+                if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
+                    throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && /File too large/.test(error.message)) {
+                    throw error;
+                }
+                logger.debug(`[FileDetector] HEAD pre-flight skipped for ${url}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         return withRetry(async () => {
             try {
                 const response = await request(url, {

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)`);
             }
@@ -1020,6 +1026,23 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
             throw error;
         }
     }
+    // #309: enforce the provider's page/size ceilings across ALL PDFs, not just
+    // per-file. N files each just under the single-file limit can still blow past
+    // it in aggregate (e.g. three 40-page PDFs → 120 pages for a 100-page API).
+    const aggregateConfig = PDFProcessor.getProviderConfig(provider);
+    if (aggregateConfig && pdfFiles.length > 1) {
+        const totalPages = pdfFiles.reduce((sum, f) => sum + (f.pageCount ?? 0), 0);
+        const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
+        if (totalPages > aggregateConfig.maxPages) {
+            throw new Error(`[PDF] Combined page count across ${pdfFiles.length} PDFs (${totalPages}) exceeds the ` +
+                `${aggregateConfig.maxPages}-page limit for ${provider}. ` +
+                `Split the request or reduce the number of PDFs.`);
+        }
+        if (totalMB > aggregateConfig.maxSizeMB) {
+            throw new Error(`[PDF] Combined size across ${pdfFiles.length} PDFs (${totalMB.toFixed(2)}MB) exceeds the ` +
+                `${aggregateConfig.maxSizeMB}MB limit for ${provider}.`);
+        }
+    }
     return pdfFiles;
 }
 /**
@@ -1103,7 +1126,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 +1168,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 +1238,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 +1317,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 +1344,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 +1731,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 +1756,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

@@ -7,7 +7,7 @@
  *
  * The conversion uses pdf-to-img package (MuPDF-based) for high-quality conversion.
  */
-import type { FileProcessingResult, PDFProcessorOptions, PDFProviderConfig, PDFImageConversionOptions, PDFImageConversionResult } from "../types/index.js";
+import type { FileProcessingResult, PDFProcessorOptions, PDFProviderConfig, PDFImageConversionOptions, PDFImageConversionResult, PDFImagePage } from "../types/index.js";
 export declare class PDFProcessor {
     private static readonly PDF_SIGNATURE;
     static process(content: Buffer, options?: PDFProcessorOptions): Promise<FileProcessingResult>;
@@ -20,7 +20,31 @@ export declare class PDFProcessor {
     static getProviderConfig(provider: string): PDFProviderConfig | null;
     private static isValidPDF;
     private static extractBasicMetadata;
+    /**
+     * Accurate page count via pdf-parse (pdfjs) (#287). The header regex in
+     * `extractBasicMetadata` only sees plaintext `/Type /Page` markers and misses
+     * compressed/object-stream PDFs (and miscounts when a page dict spans a chunk
+     * boundary). This parses the document properly, bounded by a timeout so a
+     * pathological PDF can't block; returns null on timeout/failure so the caller
+     * falls back to the regex estimate.
+     */
+    private static getAccuratePageCount;
     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
      *
@@ -46,6 +70,20 @@ export declare class PDFProcessor {
      * ```
      */
     static convertToImages(pdfBuffer: Buffer, options?: PDFImageConversionOptions): Promise<PDFImageConversionResult>;
+    /**
+     * Shared input validation for the image-conversion paths. Returns the PDF
+     * size in MB (needed by the memory-estimate log). Throws on any invalid input
+     * with the same messages the batch path has always used.
+     */
+    private static validateImageConversionInput;
+    /**
+     * Streaming variant of {@link convertToImages} (#302): yields each page's
+     * base64 PNG as soon as it renders instead of buffering the whole document,
+     * and reports progress via `options.onProgress`. A page that fails to render
+     * is yielded with `error` set (per-page isolation, #294) rather than aborting
+     * the stream. `convertToImages` is the batch wrapper over this contract.
+     */
+    static convertToImagesStream(pdfBuffer: Buffer, options?: PDFImageConversionOptions): AsyncGenerator<PDFImagePage, void, void>;
     /**
      * Convert a PDF file path to an array of base64 PNG images
      *