@juspay/neurolink 9.95.1 → 9.95.3

package/dist/lib/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
      *

package/dist/lib/utils/pdfProcessor.js

@@ -150,6 +150,13 @@ export class PDFProcessor {
             throw new Error(`PDF size ${sizeMB.toFixed(2)}MB exceeds ${config.maxSizeMB}MB limit for ${provider}`);
         }
         const metadata = PDFProcessor.extractBasicMetadata(content);
+        // #287: prefer an accurate page count (pdf-parse/pdfjs) over the unreliable
+        // header regex for both limit enforcement and returned metadata; fall back
+        // to the regex estimate when the accurate probe times out or fails.
+        const accuratePages = await PDFProcessor.getAccuratePageCount(content);
+        if (accuratePages !== null) {
+            metadata.estimatedPages = accuratePages;
+        }
         if (metadata.estimatedPages && metadata.estimatedPages > config.maxPages) {
             const enforceLimits = options?.enforceLimits !== false;
             if (enforceLimits) {
@@ -185,6 +192,10 @@ export class PDFProcessor {
                 ...metadata,
                 provider,
                 apiType: config.apiType,
+                // #349: surface the provider's citations requirement so downstream
+                // provider adapters (e.g. Bedrock Converse document blocks) can act on
+                // it, instead of the config field being read nowhere.
+                requiresCitations: config.requiresCitations,
             },
         };
     }
@@ -220,6 +231,35 @@ export class PDFProcessor {
             filename: undefined,
         };
     }
+    /**
+     * 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.
+     */
+    static async getAccuratePageCount(buffer) {
+        try {
+            const { PDFParse } = await import("pdf-parse");
+            const pdf = new PDFParse({ data: new Uint8Array(buffer) });
+            try {
+                const info = await Promise.race([
+                    pdf.getInfo(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("page-count timeout")), PDF_LIMITS.PAGE_COUNT_TIMEOUT_MS)),
+                ]);
+                const total = info.total;
+                return typeof total === "number" && total > 0 ? total : null;
+            }
+            finally {
+                await pdf.destroy?.();
+            }
+        }
+        catch (error) {
+            logger.debug(`[PDF] Accurate page count unavailable; using regex estimate: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
     static estimateTokens(pageCount, mode = "visual") {
         if (mode === "text-only") {
             return Math.ceil((pageCount / 3) * 1000);
@@ -231,6 +271,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,43 +331,32 @@ 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 = PDF_LIMITS.DEFAULT_SCALE, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, onProgress, } = options || {};
         const images = [];
         const warnings = [];
-        // ============================================================================
-        // INPUT VALIDATION (Security: Prevent malformed/malicious PDF processing)
-        // ============================================================================
-        // 0. Validate format is supported and case-sensitive
-        if (format !== "png") {
-            throw new Error(`Invalid format: "${format}". Only "png" format is currently supported.`);
-        }
-        // 0b. Validate the render scale. A non-finite or non-positive scale yields a
-        // degenerate viewport (blank/zero-dimension render), and an excessive scale
-        // can allocate hundreds of MB per page — reject both with a clear message.
-        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}.`);
-        }
-        // 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. " +
-                "A valid PDF must be at least 5 bytes (PDF header).");
-        }
-        // 2. Validate PDF magic bytes (%PDF-)
-        if (!PDFProcessor.isValidPDF(pdfBuffer)) {
-            throw new Error("Invalid PDF: File must start with %PDF- header. " +
-                "The provided buffer does not appear to be a valid PDF file.");
-        }
-        // 3. Validate maximum buffer size to prevent memory exhaustion
-        const sizeMB = pdfBuffer.length / (1024 * 1024);
-        if (sizeMB > PDF_LIMITS.MAX_SIZE_MB) {
-            throw new Error(`PDF too large for image conversion: ${sizeMB.toFixed(2)}MB exceeds ${PDF_LIMITS.MAX_SIZE_MB}MB limit. ` +
-                "Consider splitting the PDF or using a provider with native PDF support.");
-        }
+        const pageErrors = [];
+        // Validation shared with convertToImagesStream (#302).
+        const sizeMB = PDFProcessor.validateImageConversionInput(pdfBuffer, {
+            format,
+            scale,
+            maxCanvasPixels,
+        });
         logger.debug("[PDF→Image] ✅ PDF validation passed", {
             bufferSize: pdfBuffer.length,
             sizeMB: sizeMB.toFixed(2),
             maxPages,
         });
+        // #297: surface an up-front memory estimate so an operator can spot a
+        // conversion that will allocate a lot before it runs. Uses the cheap regex
+        // page estimate (the accurate pdf-parse count runs in process(), not here).
+        const estimatedPages = Math.max(1, PDFProcessor.extractBasicMetadata(pdfBuffer).estimatedPages ?? 1);
+        const estimatedMemoryMB = PDFProcessor.estimateConversionMemoryUsage(pdfBuffer.length, estimatedPages, scale);
+        logger.info("[PDF→Image] Estimated memory usage before conversion", {
+            scale,
+            estimatedPages,
+            estimatedMemoryMB,
+            sizeMB: Number(sizeMB.toFixed(2)),
+        });
         try {
             // Dynamic import to avoid loading MuPDF binaries until needed
             const pdfToImgModule = await import("pdf-to-img");
@@ -303,32 +366,87 @@ export class PDFProcessor {
                 scale,
                 maxPages: maxPages || "all",
             });
-            // Create PDF document iterator
-            const document = await pdf(pdfBuffer, { scale });
-            let pageIndex = 0;
-            // Iterate through pages and convert to base64
-            for await (const page of document) {
-                // Check if we've reached the max pages limit
-                if (maxPages !== undefined && pageIndex >= maxPages) {
-                    warnings.push(`Stopped at page ${pageIndex} (maxPages limit: ${maxPages})`);
+            // #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 (password forwarded for encrypted PDFs, #258).
+            // pdf-to-img resolves `.length` (numPages) synchronously here and exposes
+            // `.getPage(n)`, so we drive an indexed loop rather than the async
+            // iterator — that lets one bad page be isolated instead of aborting all.
+            const document = await pdf(pdfBuffer, {
+                scale: effectiveScale,
+                ...(password ? { password } : {}),
+            });
+            const totalPages = document.length;
+            // #294: convert page-by-page with per-page isolation. A single page whose
+            // canvas render throws (e.g. a degenerate MediaBox) no longer discards
+            // every already-converted page — it is recorded in `errors` and the rest
+            // continue.
+            for (let pageNum = 1; pageNum <= totalPages; pageNum++) {
+                if (maxPages !== undefined && pageNum - 1 >= maxPages) {
+                    warnings.push(`Stopped at page ${pageNum - 1} (maxPages limit: ${maxPages})`);
                     break;
                 }
-                // Convert PNG buffer to base64
-                const base64Image = page.toString("base64");
-                images.push(base64Image);
-                pageIndex++;
-                logger.debug(`[PDF→Image] Converted page ${pageIndex}`, {
-                    imageSizeBytes: page.length,
-                    base64Length: base64Image.length,
-                });
+                try {
+                    const page = await document.getPage(pageNum);
+                    const base64Image = page.toString("base64");
+                    images.push(base64Image);
+                    logger.debug(`[PDF→Image] Converted page ${pageNum}`, {
+                        imageSizeBytes: page.length,
+                        base64Length: base64Image.length,
+                    });
+                    // #302: report progress after each successfully converted page.
+                    if (onProgress) {
+                        await onProgress({
+                            pagesConverted: images.length,
+                            totalPages,
+                            elapsedMs: Date.now() - startTime,
+                        });
+                    }
+                }
+                catch (pageError) {
+                    const msg = pageError instanceof Error ? pageError.message : String(pageError);
+                    logger.warn(`[PDF→Image] ⚠️ page ${pageNum} failed to render: ${msg}`);
+                    pageErrors.push({ page: pageNum, error: msg });
+                }
             }
-            // Check for empty PDF (0 pages)
+            // Empty PDF (0 pages) or every page failed → treat as a conversion
+            // failure (kept inside the try so the password/format mapping below still
+            // applies), otherwise return the pages that did convert.
             if (images.length === 0) {
+                if (pageErrors.length > 0) {
+                    throw new Error(`All ${pageErrors.length} page(s) failed to render. First error: ${pageErrors[0].error}`);
+                }
                 throw new Error("PDF has 0 pages. Cannot convert empty PDF to images.");
             }
             const conversionTimeMs = Date.now() - startTime;
             logger.info("[PDF→Image] ✅ PDF conversion completed", {
                 pageCount: images.length,
+                failedPages: pageErrors.length,
                 conversionTimeMs,
                 totalImageBytes: images.reduce((sum, img) => sum + img.length, 0),
             });
@@ -337,6 +455,7 @@ export class PDFProcessor {
                 pageCount: images.length,
                 conversionTimeMs,
                 warnings: warnings.length > 0 ? warnings : undefined,
+                errors: pageErrors.length > 0 ? pageErrors : undefined,
             };
         }
         catch (error) {
@@ -346,11 +465,111 @@ 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,
             });
         }
     }
+    /**
+     * 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.
+     */
+    static validateImageConversionInput(pdfBuffer, opts) {
+        if (opts.format !== "png") {
+            throw new Error(`Invalid format: "${opts.format}". Only "png" format is currently supported.`);
+        }
+        if (!Number.isFinite(opts.scale) ||
+            opts.scale < PDF_LIMITS.MIN_SCALE ||
+            opts.scale > PDF_LIMITS.MAX_SCALE) {
+            throw new Error(`Invalid scale: ${opts.scale}. Scale must be a finite number between ${PDF_LIMITS.MIN_SCALE} and ${PDF_LIMITS.MAX_SCALE}.`);
+        }
+        if (!Number.isFinite(opts.maxCanvasPixels) || opts.maxCanvasPixels <= 0) {
+            throw new Error(`Invalid maxCanvasPixels: ${opts.maxCanvasPixels}. Must be a finite number greater than 0.`);
+        }
+        if (!pdfBuffer || pdfBuffer.length < 5) {
+            throw new Error("Invalid PDF: Buffer is too small or empty. " +
+                "A valid PDF must be at least 5 bytes (PDF header).");
+        }
+        if (!PDFProcessor.isValidPDF(pdfBuffer)) {
+            throw new Error("Invalid PDF: File must start with %PDF- header. " +
+                "The provided buffer does not appear to be a valid PDF file.");
+        }
+        const sizeMB = pdfBuffer.length / (1024 * 1024);
+        if (sizeMB > PDF_LIMITS.MAX_SIZE_MB) {
+            throw new Error(`PDF too large for image conversion: ${sizeMB.toFixed(2)}MB exceeds ${PDF_LIMITS.MAX_SIZE_MB}MB limit. ` +
+                "Consider splitting the PDF or using a provider with native PDF support.");
+        }
+        return sizeMB;
+    }
+    /**
+     * 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 async *convertToImagesStream(pdfBuffer, options) {
+        const startTime = Date.now();
+        const { scale = PDF_LIMITS.DEFAULT_SCALE, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, onProgress, } = options || {};
+        PDFProcessor.validateImageConversionInput(pdfBuffer, {
+            format,
+            scale,
+            maxCanvasPixels,
+        });
+        const pdfToImgModule = await import("pdf-to-img");
+        const pdf = pdfToImgModule.pdf;
+        // #260: uniform downscale so the largest page stays under maxCanvasPixels.
+        let effectiveScale = scale;
+        const largestPixels = PDFProcessor.largestPagePixels(pdfBuffer, scale);
+        if (largestPixels > maxCanvasPixels) {
+            effectiveScale = scale * Math.sqrt(maxCanvasPixels / largestPixels);
+        }
+        const document = await pdf(pdfBuffer, {
+            scale: effectiveScale,
+            ...(password ? { password } : {}),
+        });
+        const totalPages = document.length;
+        let converted = 0;
+        for (let pageNum = 1; pageNum <= totalPages; pageNum++) {
+            if (maxPages !== undefined && pageNum - 1 >= maxPages) {
+                break;
+            }
+            try {
+                const page = await document.getPage(pageNum);
+                const base64Image = page.toString("base64");
+                converted++;
+                if (onProgress) {
+                    await onProgress({
+                        pagesConverted: converted,
+                        totalPages,
+                        elapsedMs: Date.now() - startTime,
+                    });
+                }
+                yield {
+                    pageIndex: pageNum,
+                    image: base64Image,
+                    imageSizeBytes: page.length,
+                };
+            }
+            catch (pageError) {
+                const msg = pageError instanceof Error ? pageError.message : String(pageError);
+                logger.warn(`[PDF→Image] ⚠️ page ${pageNum} failed to render (stream): ${msg}`);
+                yield { pageIndex: pageNum, image: "", imageSizeBytes: 0, error: msg };
+            }
+        }
+    }
     /**
      * Convert a PDF file path to an array of base64 PNG images
      *
@@ -386,7 +605,7 @@ export class PDFProcessor {
      * @param scale - Scale factor
      * @returns Estimated memory usage in MB
      */
-    static estimateConversionMemoryUsage(pdfSizeBytes, pageCount, scale = 2) {
+    static estimateConversionMemoryUsage(pdfSizeBytes, pageCount, scale = PDF_LIMITS.DEFAULT_SCALE) {
         // Rough estimation:
         // - Each page at scale 2 produces ~1-3MB PNG
         // - MuPDF needs ~2x PDF size for processing

package/dist/neurolink.js

@@ -3899,11 +3899,15 @@ Current user's request: ${currentInput}`;
             evaluationDomain: options.evaluationDomain,
             toolUsageContext: options.toolUsageContext,
             input: options.input,
-            // CSV processing options must survive the reconstruction into
-            // TextGenerationOptions — the message builder reads them (encoding,
-            // formatting, sanitization, parse timeout). Omitting them silently
-            // dropped every csvOptions field (incl. the CLI --csv-* flags).
+            // Multimodal file-processing options must survive the reconstruction
+            // into TextGenerationOptions — the message builder reads them downstream
+            // (csv encoding/formatting/sanitization/parse timeout, PDF
+            // password/decryption #258). Omitting them here silently dropped e.g.
+            // every csvOptions field (incl. the CLI --csv-* flags) or
+            // pdfOptions.password so the CLI --pdf-password / SDK pdfOptions never
+            // reached convertToImages.
             csvOptions: options.csvOptions,
+            pdfOptions: options.pdfOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,

package/dist/types/file.d.ts

@@ -95,6 +95,8 @@ export type FileProcessingResult = {
         estimatedPages?: number | null;
         provider?: string;
         apiType?: PDFAPIType;
+        /** Provider's citations requirement for visual PDF analysis (#349). */
+        requiresCitations?: boolean | "auto";
         officeFormat?: OfficeDocumentType;
         pageCount?: number;
         slideCount?: number;
@@ -210,6 +212,14 @@ export type PDFProviderConfig = {
     maxSizeMB: number;
     maxPages: number;
     supportsNative: boolean;
+    /**
+     * Whether this provider needs source citations enabled for visual PDF
+     * analysis (#349). `"auto"` = enable when the request requires visual
+     * grounding (currently Bedrock's Converse document blocks); `false` = the
+     * provider handles PDFs without an explicit citations flag. Surfaced on
+     * `FileProcessingResult.metadata.requiresCitations` so downstream provider
+     * adapters can act on it instead of the value being dead config.
+     */
     requiresCitations: boolean | "auto";
     apiType: PDFAPIType;
 };
@@ -226,6 +236,8 @@ export type PDFProcessorOptions = {
      * Set to false to bypass limit enforcement (logs warning instead)
      */
     enforceLimits?: boolean;
+    /** Password for an encrypted PDF (used on the image-conversion path) (#258). */
+    password?: string;
 };
 /**
  * Audio provider configuration for transcription services
@@ -395,10 +407,40 @@ export type PDFImageConversionOptions = {
     maxPages?: number;
     /** Output format (default: png). Only PNG is currently implemented by PDFProcessor. */
     format?: "png";
+    /**
+     * Per-page pixel ceiling (#260). Any page whose width×height×scale² would
+     * exceed this is uniformly downscaled to stay under it, preventing a huge
+     * page from allocating gigabytes of canvas. Default: PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS.
+     */
+    maxCanvasPixels?: number;
+    /** Password for an encrypted PDF (passed to the underlying renderer) (#258). */
+    password?: string;
+    /** Per-page progress callback invoked as each page is rendered (#302). */
+    onProgress?: (progress: PDFImageConversionProgress) => void | Promise<void>;
+};
+/** Progress reported per page during streaming conversion (#302). */
+export type PDFImageConversionProgress = {
+    /** Number of pages successfully converted so far. */
+    pagesConverted: number;
+    /** Total pages in the document (known up-front from the renderer). */
+    totalPages: number;
+    /** Elapsed time since conversion started, in milliseconds. */
+    elapsedMs: number;
+};
+/** A single streamed page result (#302). `error` is set when that page failed. */
+export type PDFImagePage = {
+    /** 1-based page index. */
+    pageIndex: number;
+    /** Base64-encoded PNG for the page (empty string when `error` is set). */
+    image: string;
+    /** Byte size of the rendered PNG (0 when `error` is set). */
+    imageSizeBytes: number;
+    /** Populated when this page failed to render (#294). */
+    error?: string;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
-    /** Array of base64-encoded PNG images (one per page) */
+    /** Array of base64-encoded PNG images (one per successfully converted page) */
     images: string[];
     /** Number of pages converted */
     pageCount: number;
@@ -406,6 +448,11 @@ export type PDFImageConversionResult = {
     conversionTimeMs: number;
     /** Any warnings during conversion */
     warnings?: string[];
+    /** Per-page failures — present only when some pages failed to render (#294). */
+    errors?: Array<{
+        page: number;
+        error: string;
+    }>;
 };
 /** Options for filename sanitization. */
 export type SanitizeFileNameOptions = {

package/dist/types/generate.d.ts

@@ -125,6 +125,13 @@ export type GenerateOptions = {
         music?: MusicOptions;
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;
@@ -1131,6 +1138,13 @@ export type TextGenerationOptions = {
     expectedOutcome?: string;
     evaluationCriteria?: string[];
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

package/dist/types/stream.d.ts

@@ -207,6 +207,13 @@ export type StreamOptions = {
         };
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;

package/dist/utils/errorHandling.d.ts

@@ -39,6 +39,8 @@ export declare const ERROR_CODES: {
     readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
     readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
+    readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
     readonly RATE_LIMITER_RESET: "RATE_LIMITER_RESET";
@@ -199,6 +201,14 @@ export declare class ErrorFactory {
      * Create a PDF page limit exceeded error
      */
     static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired(): NeuroLinkError;
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword(): NeuroLinkError;
     /**
      * Create an image too large error
      */