pdf-oxide 0.3.37 → 0.3.38

package/lib/document-editor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Page rotation angles valid for {@link DocumentEditor.setPageRotation}.
+ */
+export type PageRotation = 0 | 90 | 180 | 270;
+/**
+ * PDF editor bound to a concrete file on disk. Open via
+ * {@link DocumentEditor.open}; always pair with {@link close} (or use
+ * `using` / the explicit-resource-management protocol once it's
+ * stable in your toolchain).
+ */
+export declare class DocumentEditor {
+    private _handle;
+    private _closed;
+    private constructor();
+    /** Open a PDF file for editing. */
+    static open(path: string): DocumentEditor;
+    /** True if the editor has been closed. Subsequent calls will throw. */
+    get closed(): boolean;
+    private _throwIfClosed;
+    /** Current page count. */
+    pageCount(): number;
+    /** True if the editor has unsaved modifications. */
+    isModified(): boolean;
+    setTitle(title: string): void;
+    setAuthor(author: string): void;
+    getProducer(): string;
+    setProducer(producer: string): void;
+    getCreationDate(): string;
+    setCreationDate(date: string): void;
+    /** Delete the page at `pageIndex` (zero-based). */
+    deletePage(pageIndex: number): void;
+    /** Move a page. Indices refer to positions before the move. */
+    movePage(fromIndex: number, toIndex: number): void;
+    /** Set rotation on a page (0/90/180/270). */
+    setPageRotation(pageIndex: number, degrees: PageRotation): void;
+    /**
+     * Append every page of another PDF to the end of this document.
+     */
+    mergeFrom(sourcePath: string): void;
+    /** Flatten form fields across the entire document. */
+    flattenForms(): void;
+    /** Flatten annotations. If `pageIndex` is omitted, flattens all pages. */
+    flattenAnnotations(pageIndex?: number): void;
+    /** Set a form field value by fully-qualified field name. */
+    setFormFieldValue(fieldName: string, value: string): void;
+    /** Import an FDF file (bytes) into the document's form. */
+    importFdfBytes(fdf: Buffer | Uint8Array): void;
+    /** Import an XFDF file (bytes) into the document's form. */
+    importXfdfBytes(xfdf: Buffer | Uint8Array): void;
+    /** Save the document to `path`. */
+    save(path: string): void;
+    /** Save with AES-256 encryption (user + owner passwords). */
+    saveEncrypted(path: string, userPassword: string, ownerPassword: string): void;
+    /** Release the native handle. Safe to call multiple times. */
+    close(): void;
+}
+export default DocumentEditor;

package/lib/document-editor.js

@@ -0,0 +1,184 @@
+/**
+ * DocumentEditor — thin TS wrapper around the N-API `editor*` exports
+ * in `binding.cc`. Mirrors the C# `DocumentEditor` / Go
+ * `DocumentEditor` surface.
+ *
+ * Every mutation is a synchronous call into the Rust core; the same
+ * handle is carried until {@link DocumentEditor.close}. Throws plain
+ * `Error` with the native message on failure.
+ *
+ * ```ts
+ * import { DocumentEditor } from 'pdf-oxide';
+ *
+ * const editor = DocumentEditor.open('in.pdf');
+ * try {
+ *   editor.mergeFrom('other.pdf');
+ *   editor.deletePage(0);
+ *   editor.movePage(0, 2);
+ *   editor.setPageRotation(0, 90);
+ *   editor.save('out.pdf');
+ * } finally {
+ *   editor.close();
+ * }
+ * ```
+ */
+// Load the native addon via the shared prebuild-aware loader.
+// Importing `./index.js` would create an ESM cycle (index.js imports
+// us back), so we go through `./native.js` — same resolver, no cycle,
+// resolves against `prebuilds/<triple>/pdf_oxide.node` in the
+// published package.
+import { loadNative } from './native.js';
+const native = loadNative();
+/**
+ * PDF editor bound to a concrete file on disk. Open via
+ * {@link DocumentEditor.open}; always pair with {@link close} (or use
+ * `using` / the explicit-resource-management protocol once it's
+ * stable in your toolchain).
+ */
+export class DocumentEditor {
+    constructor(handle) {
+        this._closed = false;
+        this._handle = handle;
+    }
+    /** Open a PDF file for editing. */
+    static open(path) {
+        if (typeof path !== 'string' || path.length === 0) {
+            throw new TypeError('path must be a non-empty string');
+        }
+        const handle = native.editorOpen(path);
+        return new DocumentEditor(handle);
+    }
+    /** True if the editor has been closed. Subsequent calls will throw. */
+    get closed() {
+        return this._closed;
+    }
+    _throwIfClosed() {
+        if (this._closed)
+            throw new Error('DocumentEditor is closed');
+    }
+    /** Current page count. */
+    pageCount() {
+        this._throwIfClosed();
+        return native.editorGetPageCount(this._handle);
+    }
+    /** True if the editor has unsaved modifications. */
+    isModified() {
+        this._throwIfClosed();
+        return native.editorIsModified(this._handle);
+    }
+    // ----- metadata ---------------------------------------------------
+    setTitle(title) {
+        this._throwIfClosed();
+        native.editorSetTitle(this._handle, title);
+    }
+    setAuthor(author) {
+        this._throwIfClosed();
+        native.editorSetAuthor(this._handle, author);
+    }
+    getProducer() {
+        this._throwIfClosed();
+        return native.editorGetProducer(this._handle);
+    }
+    setProducer(producer) {
+        this._throwIfClosed();
+        // NOTE: today this is a no-op in Rust core (src/ffi.rs:532-586).
+        // The wrapper is in place so the API surface matches
+        // Python / C# / Go.
+        if (native.editorSetProducer) {
+            native.editorSetProducer(this._handle, producer);
+        }
+    }
+    getCreationDate() {
+        this._throwIfClosed();
+        return native.editorGetCreationDate(this._handle);
+    }
+    setCreationDate(date) {
+        this._throwIfClosed();
+        // Same Rust-core stub note as setProducer.
+        if (native.editorSetCreationDate) {
+            native.editorSetCreationDate(this._handle, date);
+        }
+    }
+    // ----- page mutations ---------------------------------------------
+    /** Delete the page at `pageIndex` (zero-based). */
+    deletePage(pageIndex) {
+        this._throwIfClosed();
+        native.editorDeletePage(this._handle, pageIndex);
+    }
+    /** Move a page. Indices refer to positions before the move. */
+    movePage(fromIndex, toIndex) {
+        this._throwIfClosed();
+        native.editorMovePage(this._handle, fromIndex, toIndex);
+    }
+    /** Set rotation on a page (0/90/180/270). */
+    setPageRotation(pageIndex, degrees) {
+        this._throwIfClosed();
+        native.editorSetPageRotation(this._handle, pageIndex, degrees);
+    }
+    // ----- document-level mutations -----------------------------------
+    /**
+     * Append every page of another PDF to the end of this document.
+     */
+    mergeFrom(sourcePath) {
+        this._throwIfClosed();
+        if (typeof sourcePath !== 'string' || sourcePath.length === 0) {
+            throw new TypeError('sourcePath must be a non-empty string');
+        }
+        native.editorMergeFrom(this._handle, sourcePath);
+    }
+    /** Flatten form fields across the entire document. */
+    flattenForms() {
+        this._throwIfClosed();
+        native.editorFlattenForms(this._handle);
+    }
+    /** Flatten annotations. If `pageIndex` is omitted, flattens all pages. */
+    flattenAnnotations(pageIndex) {
+        this._throwIfClosed();
+        if (pageIndex === undefined) {
+            native.editorFlattenAnnotations(this._handle);
+        }
+        else {
+            native.editorFlattenAnnotations(this._handle, pageIndex);
+        }
+    }
+    /** Set a form field value by fully-qualified field name. */
+    setFormFieldValue(fieldName, value) {
+        this._throwIfClosed();
+        native.editorSetFormFieldValue(this._handle, fieldName, value);
+    }
+    /** Import an FDF file (bytes) into the document's form. */
+    importFdfBytes(fdf) {
+        this._throwIfClosed();
+        native.editorImportFdfBytes(this._handle, fdf);
+    }
+    /** Import an XFDF file (bytes) into the document's form. */
+    importXfdfBytes(xfdf) {
+        this._throwIfClosed();
+        native.editorImportXfdfBytes(this._handle, xfdf);
+    }
+    // ----- save paths -------------------------------------------------
+    /** Save the document to `path`. */
+    save(path) {
+        this._throwIfClosed();
+        if (typeof path !== 'string' || path.length === 0) {
+            throw new TypeError('path must be a non-empty string');
+        }
+        native.editorSave(this._handle, path);
+    }
+    /** Save with AES-256 encryption (user + owner passwords). */
+    saveEncrypted(path, userPassword, ownerPassword) {
+        this._throwIfClosed();
+        native.editorSaveEncrypted(this._handle, path, userPassword, ownerPassword);
+    }
+    // ----- lifecycle --------------------------------------------------
+    /** Release the native handle. Safe to call multiple times. */
+    close() {
+        if (!this._closed) {
+            if (native.editorFree) {
+                native.editorFree(this._handle);
+            }
+            this._closed = true;
+        }
+    }
+}
+export default DocumentEditor;

package/lib/errors.js

@@ -135,9 +135,7 @@ export class PdfException extends Error {
             parts.push(`Context:\n${contextStr}`);
         }
         if (this.recovery.suggestions.length > 0) {
-            const suggestionsStr = this.recovery.suggestions
-                .map((s) => `  • ${s}`)
-                .join('\n');
+            const suggestionsStr = this.recovery.suggestions.map((s) => `  • ${s}`).join('\n');
             parts.push(`Recovery Suggestions:\n${suggestionsStr}`);
         }
         if (this.recovery.alternativeApproach) {
@@ -931,7 +929,8 @@ export function mapFfiErrorCode(errorCode, message) {
         case 11:
             return new AccessibilityException(message ?? 'Accessibility error: Tagging, structure tree, or alt text operation failed');
         case 12:
-            return new OptimizationException(message ?? 'Optimization error: Font subsetting, image downsampling, or deduplication failed');
+            return new OptimizationException(message ??
+                'Optimization error: Font subsetting, image downsampling, or deduplication failed');
         default:
             return new UnknownError(message ?? `Unknown error (code: ${errorCode})`);
     }

package/lib/form-field-manager.js

@@ -560,7 +560,9 @@ export class FormFieldManager extends EventEmitter {
     clearCachePattern(pattern) {
         const regex = new RegExp(pattern);
         const keysToDelete = Array.from(this.resultCache.keys()).filter((key) => regex.test(key));
-        keysToDelete.forEach((key) => this.resultCache.delete(key));
+        keysToDelete.forEach((key) => {
+            this.resultCache.delete(key);
+        });
     }
 }
 export default FormFieldManager;

package/lib/index.d.ts

@@ -1,11 +1,31 @@
+import { AnnotationBuilder, ConversionOptionsBuilder, DocumentBuilder, EmbeddedFont, MetadataBuilder, PageBuilder, PdfBuilder, SearchOptionsBuilder } from './builders/index';
+import { DocumentEditor } from './document-editor';
+import { AccessibilityException, CertificateLoadFailed, ComplianceException, EncryptionException, ErrorCategory, ErrorSeverity, InvalidStateException, IoException, mapFfiErrorCode, OcrException, OptimizationException, ParseException, PdfException, RedactionException, RenderingException, SearchException, SignatureException, SigningFailed, UnknownError, UnsupportedFeatureException, ValidationException, wrapAsyncMethod, wrapError, wrapMethod } from './errors';
+import { AnnotationManager, type BatchDocument, BatchManager, type BatchOptions, type BatchProgress, type BatchResult, type BatchStatistics, createExtractionStream, createMetadataStream, createSearchStream, ExtractionManager, ExtractionStream, LayerManager, MetadataManager, MetadataStream, OutlineManager, RenderingManager, SearchManager, SearchStream, SecurityManager } from './managers/index';
 import type { Table } from './types/common.js';
-import { PdfException, ParseException, IoException, EncryptionException, UnsupportedFeatureException, InvalidStateException, ValidationException, RenderingException, SearchException, ComplianceException, OcrException, SignatureException, CertificateLoadFailed, SigningFailed, RedactionException, AccessibilityException, OptimizationException, UnknownError, ErrorCategory, ErrorSeverity, wrapError, wrapMethod, wrapAsyncMethod, mapFfiErrorCode } from './errors';
-import { PdfBuilder, ConversionOptionsBuilder, MetadataBuilder, AnnotationBuilder, SearchOptionsBuilder } from './builders/index';
-import { OutlineManager, MetadataManager, ExtractionManager, SearchManager, SecurityManager, AnnotationManager, LayerManager, RenderingManager, SearchStream, ExtractionStream, MetadataStream, createSearchStream, createExtractionStream, createMetadataStream, BatchManager, type BatchDocument, type BatchProgress, type BatchResult, type BatchOptions, type BatchStatistics } from './managers/index';
+import type { WorkerResult, WorkerTask } from './workers/index';
 import { WorkerPool, workerPool } from './workers/index';
-import type { WorkerTask, WorkerResult } from './workers/index';
 declare const OcrManager: any, OCRManager: any, OCRDetectionMode: any, ComplianceManager: any, PdfALevel: any, PdfXLevel: any, PdfUALevel: any, ComplianceIssueType: any, IssueSeverity: any, SignatureManager: any, SignatureAlgorithm: any, DigestAlgorithm: any, BarcodeManager: any, BarcodeFormat: any, BarcodeErrorCorrection: any, FormFieldManager: any, FormFieldType: any, FieldVisibility: any, ResultAccessorsManager: any, SearchResultProperties: any, FontProperties: any, ImageProperties: any, AnnotationProperties: any, ThumbnailManager: any, ThumbnailSize: any, ImageFormat: any, HybridMLManager: any, PageComplexity: any, ContentType: any, XfaManager: any, XfaFormType: any, XfaFieldType: any, CacheManager: any, EditingManager: any, AccessibilityManager: any, OptimizationManager: any, EnterpriseManager: any;
 declare const OCRLanguage: any;
+/**
+ * Options mirroring Rust's `RenderOptions` struct
+ * (see `src/rendering/page_renderer.rs:41`). Used by
+ * {@link PdfDocumentImpl.renderPageWithOptions}.
+ */
+export interface RenderOptions {
+    /** Resolution (default 150). */
+    dpi?: number;
+    /** Output format (default PNG). */
+    format?: 'png' | 'jpeg';
+    /** RGBA 0..=1 tuple (default opaque white). */
+    background?: [number, number, number, number];
+    /** Drop background fill entirely (overrides `background`). */
+    transparentBackground?: boolean;
+    /** Render annotation layer (default true). */
+    renderAnnotations?: boolean;
+    /** JPEG quality 1..=100 (default 85). */
+    jpegQuality?: number;
+}
 declare class PdfDocumentImpl {
     private _handle;
     private _closed;
@@ -47,6 +67,18 @@ declare class PdfDocumentImpl {
     extractTables(pageIndex: number): Table[];
     extractPaths(pageIndex: number): any;
     ocrExtractText(pageIndex: number, engineHandle: any): any;
+    /**
+     * Render a page with the full Rust `RenderOptions` surface
+     * (DPI, format, RGBA background, transparency, annotation toggle,
+     * JPEG quality). Returns the image bytes.
+     */
+    renderPageWithOptions(pageIndex: number, options?: RenderOptions): Uint8Array;
+    /**
+     * Estimate render time (milliseconds) for a page at a given DPI.
+     * Thin wrapper around the existing `estimateRenderTime` N-API
+     * export — exposed in TS for the first time as part of gap L.
+     */
+    estimateRenderTime(pageIndex: number, dpi?: number): number;
     page(index: number): Page;
     [Symbol.iterator](): Iterator<Page>;
     close(): void;
@@ -88,5 +120,7 @@ declare const ConversionOptions: any;
 declare const SearchOptions: any;
 declare const SearchResult: any;
 declare const TextSearcher: any;
-export { getVersion, getPdfOxideVersion, PdfDocument, Pdf, Page, PdfError, PdfException, ParseException, IoException, EncryptionException, UnsupportedFeatureException, InvalidStateException, ValidationException, RenderingException, SearchException, ComplianceException, OcrException, SignatureException, CertificateLoadFailed, SigningFailed, RedactionException, AccessibilityException, OptimizationException, UnknownError, PageSize, Rect, Point, Color, ConversionOptions, SearchOptions, SearchResult, TextSearcher, ErrorCategory, ErrorSeverity, wrapError, wrapMethod, wrapAsyncMethod, mapFfiErrorCode, PdfBuilder, ConversionOptionsBuilder, MetadataBuilder, AnnotationBuilder, SearchOptionsBuilder, OutlineManager, MetadataManager, ExtractionManager, SearchManager, SecurityManager, AnnotationManager, LayerManager, RenderingManager, OcrManager, OCRManager, OCRLanguage, OCRDetectionMode, ComplianceManager, PdfALevel, PdfXLevel, PdfUALevel, ComplianceIssueType, IssueSeverity, SignatureManager, SignatureAlgorithm, DigestAlgorithm, BarcodeManager, BarcodeFormat, BarcodeErrorCorrection, FormFieldManager, FormFieldType, FieldVisibility, ResultAccessorsManager, SearchResultProperties, FontProperties, ImageProperties, AnnotationProperties, ThumbnailManager, ThumbnailSize, ImageFormat, HybridMLManager, PageComplexity, ContentType, XfaManager, XfaFormType, XfaFieldType, CacheManager, EditingManager, AccessibilityManager, OptimizationManager, EnterpriseManager, SearchStream, ExtractionStream, MetadataStream, createSearchStream, createExtractionStream, createMetadataStream, BatchManager, WorkerPool, workerPool, };
-export type { WorkerTask, WorkerResult, BatchDocument, BatchProgress, BatchResult, BatchOptions, BatchStatistics, Table, };
+export { Timestamp, TimestampHashAlgorithm } from './timestamp.js';
+export { TsaClient, type TsaClientOptions } from './tsa-client.js';
+export type { BatchDocument, BatchOptions, BatchProgress, BatchResult, BatchStatistics, Table, WorkerResult, WorkerTask, };
+export { AccessibilityException, AccessibilityManager, AnnotationBuilder, AnnotationManager, AnnotationProperties, BarcodeErrorCorrection, BarcodeFormat, BarcodeManager, BatchManager, CacheManager, CertificateLoadFailed, Color, ComplianceException, ComplianceIssueType, ComplianceManager, ContentType, ConversionOptions, ConversionOptionsBuilder, createExtractionStream, createMetadataStream, createSearchStream, DigestAlgorithm, DocumentBuilder, DocumentEditor, EditingManager, EmbeddedFont, EncryptionException, EnterpriseManager, ErrorCategory, ErrorSeverity, ExtractionManager, ExtractionStream, FieldVisibility, FontProperties, FormFieldManager, FormFieldType, getPdfOxideVersion, getVersion, HybridMLManager, ImageFormat, ImageProperties, InvalidStateException, IoException, IssueSeverity, LayerManager, MetadataBuilder, MetadataManager, MetadataStream, mapFfiErrorCode, OCRDetectionMode, OCRLanguage, OCRManager, OcrException, OcrManager, OptimizationException, OptimizationManager, OutlineManager, Page, PageBuilder, PageComplexity, PageSize, ParseException, Pdf, PdfALevel, PdfBuilder, PdfDocument, PdfError, PdfException, PdfUALevel, PdfXLevel, Point, Rect, RedactionException, RenderingException, RenderingManager, ResultAccessorsManager, SearchException, SearchManager, SearchOptions, SearchOptionsBuilder, SearchResult, SearchResultProperties, SearchStream, SecurityManager, SignatureAlgorithm, SignatureException, SignatureManager, SigningFailed, TextSearcher, ThumbnailManager, ThumbnailSize, UnknownError, UnsupportedFeatureException, ValidationException, WorkerPool, workerPool, wrapAsyncMethod, wrapError, wrapMethod, XfaFieldType, XfaFormType, XfaManager, };