pdf-oxide-fips 0.3.47

package/lib/managers/editing-manager.js

@@ -0,0 +1,387 @@
+/**
+ * EditingManager - Document Editing Manager for redaction and flattening operations
+ *
+ * Provides PDF document editing capabilities:
+ * - Content redaction (add, apply, count redaction areas)
+ * - Metadata scrubbing (remove Info, XMP, JavaScript)
+ * - Form flattening (all pages or single page)
+ * - Annotation flattening (all pages or single page)
+ *
+ * Uses native FFI functions:
+ * - pdf_redaction_add, pdf_redaction_apply, pdf_redaction_scrub_metadata, pdf_redaction_count
+ * - pdf_document_editor_flatten_forms, pdf_document_editor_flatten_forms_page
+ * - pdf_document_editor_flatten_annotations, pdf_document_editor_flatten_annotations_page
+ */
+import { EventEmitter } from 'events';
+import { mapFfiErrorCode } from '../errors.js';
+// =============================================================================
+// Canonical EditingManager
+// =============================================================================
+/**
+ * Manages document editing operations including redaction and flattening.
+ *
+ * @example
+ * ```typescript
+ * import { EditingManager } from 'pdf_oxide';
+ *
+ * const editor = new EditingManager(document);
+ *
+ * // Add redaction areas
+ * editor.addRedaction(0, { x1: 100, y1: 200, x2: 300, y2: 250 });
+ * editor.addRedaction(0, { x1: 50, y1: 400, x2: 200, y2: 450 }, { r: 0, g: 0, b: 0 });
+ *
+ * // Apply all queued redactions
+ * const count = editor.applyRedactions({ scrubMetadata: true });
+ * console.log(`Applied ${count} redactions`);
+ *
+ * // Flatten forms and annotations
+ * editor.flattenForms();
+ * editor.flattenAnnotations();
+ * ```
+ */
+export class EditingManager extends EventEmitter {
+    constructor(document) {
+        super();
+        this.document = document;
+        try {
+            this.native = require('../../index.node');
+        }
+        catch {
+            this.native = null;
+        }
+    }
+    // ===========================================================================
+    // Redaction Operations
+    // ===========================================================================
+    /**
+     * Adds a redaction area to the document.
+     *
+     * Queues a rectangular region on a page for redaction. The content within
+     * the rectangle will be permanently removed when {@link applyRedactions}
+     * is called.
+     *
+     * @param page - Zero-based page index
+     * @param rect - Rectangle coordinates defining the redaction area
+     * @param color - Optional fill color for the redacted area (defaults to black)
+     * @throws {PdfException} If the document handle is invalid or page is out of range
+     *
+     * @example
+     * ```typescript
+     * // Redact a region with default black fill
+     * editor.addRedaction(0, { x1: 100, y1: 200, x2: 300, y2: 250 });
+     *
+     * // Redact with a custom gray fill
+     * editor.addRedaction(1, { x1: 50, y1: 100, x2: 200, y2: 150 }, { r: 0.5, g: 0.5, b: 0.5 });
+     * ```
+     */
+    addRedaction(page, rect, color) {
+        const fillColor = color ?? { r: 0, g: 0, b: 0 };
+        if (this.native?.pdf_redaction_add) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_redaction_add(this.document?.handle ?? this.document, page, rect.x1, rect.y1, rect.x2, rect.y2, fillColor.r, fillColor.g, fillColor.b, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to add redaction area');
+            }
+        }
+        else if (this.document?.addRedaction) {
+            this.document.addRedaction(page, rect, fillColor);
+        }
+        this.emit('redactionAdded', { page, rect, color: fillColor });
+    }
+    /**
+     * Applies all queued redactions to the document.
+     *
+     * Permanently removes content within all previously added redaction
+     * rectangles. Optionally scrubs document metadata and applies a
+     * fill color overlay.
+     *
+     * @param options - Options controlling redaction behavior
+     * @returns Number of redactions applied
+     * @throws {PdfException} If redaction application fails
+     *
+     * @example
+     * ```typescript
+     * // Apply with metadata scrubbing
+     * const count = editor.applyRedactions({ scrubMetadata: true });
+     *
+     * // Apply with custom fill color
+     * const count = editor.applyRedactions({
+     *   fillColor: { r: 1.0, g: 1.0, b: 1.0 }
+     * });
+     * ```
+     */
+    applyRedactions(options) {
+        const scrubMetadata = options?.scrubMetadata ?? false;
+        const fillColor = options?.fillColor ?? { r: 0, g: 0, b: 0 };
+        if (this.native?.pdf_redaction_apply) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_redaction_apply(this.document?.handle ?? this.document, scrubMetadata, fillColor.r, fillColor.g, fillColor.b, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to apply redactions');
+            }
+            this.emit('redactionsApplied', { count: result, scrubMetadata });
+            return result;
+        }
+        else if (this.document?.applyRedactions) {
+            const count = this.document.applyRedactions(options);
+            this.emit('redactionsApplied', { count, scrubMetadata });
+            return count ?? 0;
+        }
+        return 0;
+    }
+    /**
+     * Scrubs sensitive metadata from the document.
+     *
+     * Removes document metadata fields that may contain sensitive information,
+     * such as author names, creation tools, and JavaScript.
+     *
+     * @param options - Options controlling which metadata to remove
+     * @throws {PdfException} If metadata scrubbing fails
+     *
+     * @example
+     * ```typescript
+     * // Remove all metadata
+     * editor.scrubMetadata();
+     *
+     * // Remove only Info dictionary and JavaScript
+     * editor.scrubMetadata({ removeInfo: true, removeXmp: false, removeJs: true });
+     * ```
+     */
+    scrubMetadata(options) {
+        const removeInfo = options?.removeInfo ?? true;
+        const removeXmp = options?.removeXmp ?? true;
+        const removeJs = options?.removeJs ?? true;
+        if (this.native?.pdf_redaction_scrub_metadata) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_redaction_scrub_metadata(this.document?.handle ?? this.document, removeInfo, removeXmp, removeJs, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to scrub metadata');
+            }
+        }
+        else if (this.document?.scrubMetadata) {
+            this.document.scrubMetadata(options);
+        }
+        this.emit('metadataScrubbed', { removeInfo, removeXmp, removeJs });
+    }
+    /**
+     * Gets the number of queued (pending) redaction areas.
+     *
+     * @returns Number of redaction areas queued for application
+     * @throws {PdfException} If the document handle is invalid
+     *
+     * @example
+     * ```typescript
+     * editor.addRedaction(0, { x1: 10, y1: 20, x2: 100, y2: 50 });
+     * editor.addRedaction(1, { x1: 30, y1: 40, x2: 200, y2: 80 });
+     * console.log(editor.getRedactionCount()); // 2
+     * ```
+     */
+    getRedactionCount() {
+        if (this.native?.pdf_redaction_count) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_redaction_count(this.document?.handle ?? this.document, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to get redaction count');
+            }
+            return result;
+        }
+        else if (this.document?.getRedactionCount) {
+            return this.document.getRedactionCount() ?? 0;
+        }
+        return 0;
+    }
+    // ===========================================================================
+    // Form Flattening Operations
+    // ===========================================================================
+    /**
+     * Flattens all form fields in the document.
+     *
+     * Renders form field widgets into page content and removes the AcroForm
+     * dictionary. After flattening, form fields become static content and
+     * can no longer be edited interactively.
+     *
+     * @throws {PdfException} If flattening fails
+     *
+     * @example
+     * ```typescript
+     * editor.flattenForms();
+     * ```
+     */
+    flattenForms() {
+        if (this.native?.pdf_document_editor_flatten_forms) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_document_editor_flatten_forms(this.document?.handle ?? this.document, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to flatten forms');
+            }
+        }
+        else if (this.document?.flattenForms) {
+            this.document.flattenForms();
+        }
+        this.emit('formsFlattened');
+    }
+    /**
+     * Flattens form fields on a specific page.
+     *
+     * Only flattens form field widgets located on the specified page,
+     * leaving form fields on other pages editable.
+     *
+     * @param page - Zero-based page index
+     * @throws {PdfException} If flattening fails or page is out of range
+     *
+     * @example
+     * ```typescript
+     * // Flatten forms on first page only
+     * editor.flattenFormsPage(0);
+     * ```
+     */
+    flattenFormsPage(page) {
+        if (this.native?.pdf_document_editor_flatten_forms_page) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_document_editor_flatten_forms_page(this.document?.handle ?? this.document, page, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, `Failed to flatten forms on page ${page}`);
+            }
+        }
+        else if (this.document?.flattenFormsPage) {
+            this.document.flattenFormsPage(page);
+        }
+        this.emit('formsPageFlattened', { page });
+    }
+    // ===========================================================================
+    // Annotation Flattening Operations
+    // ===========================================================================
+    /**
+     * Flattens all annotations in the document.
+     *
+     * Renders annotations into page content and removes them from
+     * annotation arrays. After flattening, annotations become static
+     * content and can no longer be edited or deleted.
+     *
+     * @throws {PdfException} If flattening fails
+     *
+     * @example
+     * ```typescript
+     * editor.flattenAnnotations();
+     * ```
+     */
+    flattenAnnotations() {
+        if (this.native?.pdf_document_editor_flatten_annotations) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_document_editor_flatten_annotations(this.document?.handle ?? this.document, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to flatten annotations');
+            }
+        }
+        else if (this.document?.flattenAnnotations) {
+            this.document.flattenAnnotations();
+        }
+        this.emit('annotationsFlattened');
+    }
+    /**
+     * Flattens annotations on a specific page.
+     *
+     * Only flattens annotations located on the specified page,
+     * leaving annotations on other pages editable.
+     *
+     * @param page - Zero-based page index
+     * @throws {PdfException} If flattening fails or page is out of range
+     *
+     * @example
+     * ```typescript
+     * // Flatten annotations on page 2
+     * editor.flattenAnnotationsPage(1);
+     * ```
+     */
+    flattenAnnotationsPage(page) {
+        if (this.native?.pdf_document_editor_flatten_annotations_page) {
+            const errorCode = { value: 0 };
+            const result = this.native.pdf_document_editor_flatten_annotations_page(this.document?.handle ?? this.document, page, errorCode);
+            if (result < 0 && errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, `Failed to flatten annotations on page ${page}`);
+            }
+        }
+        else if (this.document?.flattenAnnotationsPage) {
+            this.document.flattenAnnotationsPage(page);
+        }
+        this.emit('annotationsPageFlattened', { page });
+    }
+    // ===========================================================================
+    // Form Data Import/Export
+    // ===========================================================================
+    /**
+     * Import form data from a file (FDF or XFDF, auto-detected by extension).
+     * @param filePath Path to the FDF or XFDF file
+     * @returns Number of fields imported
+     */
+    importFormDataFromFile(filePath) {
+        if (this.native?.pdf_document_import_form_data) {
+            const errorCode = { value: 0 };
+            const count = this.native.pdf_document_import_form_data(this.document?.handle ?? this.document, filePath, errorCode);
+            if (errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, `Failed to import form data from ${filePath}`);
+            }
+            return count;
+        }
+        throw new Error('Form data import not available');
+    }
+    /**
+     * Import FDF form data from in-memory bytes.
+     * @param data FDF data bytes
+     * @returns Number of fields imported
+     */
+    importFdfBytes(data) {
+        if (this.native?.pdf_editor_import_fdf_bytes) {
+            const errorCode = { value: 0 };
+            const count = this.native.pdf_editor_import_fdf_bytes(this.document?.handle ?? this.document, data, data.length, errorCode);
+            if (errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to import FDF bytes');
+            }
+            return count;
+        }
+        throw new Error('FDF byte import not available');
+    }
+    /**
+     * Import XFDF form data from in-memory bytes.
+     * @param data XFDF data bytes
+     * @returns Number of fields imported
+     */
+    importXfdfBytes(data) {
+        if (this.native?.pdf_editor_import_xfdf_bytes) {
+            const errorCode = { value: 0 };
+            const count = this.native.pdf_editor_import_xfdf_bytes(this.document?.handle ?? this.document, data, data.length, errorCode);
+            if (errorCode.value !== 0) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to import XFDF bytes');
+            }
+            return count;
+        }
+        throw new Error('XFDF byte import not available');
+    }
+    /**
+     * Export form data to in-memory bytes.
+     * @param format 0 for FDF, 1 for XFDF
+     * @returns Exported form data bytes
+     */
+    exportFormDataToBytes(format = 0) {
+        if (this.native?.pdf_document_export_form_data_to_bytes) {
+            const errorCode = { value: 0 };
+            const outLen = { value: 0 };
+            const ptr = this.native.pdf_document_export_form_data_to_bytes(this.document?.handle ?? this.document, format, outLen, errorCode);
+            if (errorCode.value !== 0 || !ptr) {
+                throw mapFfiErrorCode(errorCode.value, 'Failed to export form data');
+            }
+            return Buffer.from(ptr, 0, outLen.value);
+        }
+        throw new Error('Form data export not available');
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    /**
+     * Releases resources held by this manager.
+     */
+    destroy() {
+        this.removeAllListeners();
+    }
+}
+export default EditingManager;

package/lib/managers/enterprise-manager.d.ts

@@ -0,0 +1,192 @@
+/**
+ * EnterpriseManager - Enterprise PDF Operations
+ *
+ * Provides enterprise-level PDF operations including:
+ * - Bates numbering (standard and advanced)
+ * - Page-level and document-level comparison
+ * - Header and footer stamping
+ *
+ * @since 1.0.0
+ */
+import { EventEmitter } from 'events';
+/**
+ * Position for Bates number placement.
+ */
+export declare enum BatesPosition {
+    TOP_LEFT = 0,
+    TOP_CENTER = 1,
+    TOP_RIGHT = 2,
+    BOTTOM_LEFT = 3,
+    BOTTOM_CENTER = 4,
+    BOTTOM_RIGHT = 5
+}
+/**
+ * Text alignment for header/footer stamps.
+ */
+export declare enum StampAlignment {
+    LEFT = 0,
+    CENTER = 1,
+    RIGHT = 2
+}
+/**
+ * Types of differences found in page comparison.
+ */
+export declare enum DifferenceType {
+    TEXT_ADDED = 0,
+    TEXT_REMOVED = 1,
+    TEXT_CHANGED = 2,
+    IMAGE_ADDED = 3,
+    IMAGE_REMOVED = 4,
+    IMAGE_CHANGED = 5,
+    LAYOUT_CHANGED = 6,
+    ANNOTATION_CHANGED = 7
+}
+/**
+ * A single difference found between two pages.
+ */
+export interface Difference {
+    /** Type of difference */
+    readonly type: DifferenceType;
+    /** Description of the difference */
+    readonly description: string;
+    /** Page region where the difference was found (x, y, width, height) */
+    readonly bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Result of comparing two pages.
+ */
+export interface PageComparisonResult {
+    /** Similarity score (0.0 - 1.0, where 1.0 means identical) */
+    readonly similarity: number;
+    /** Number of differences found */
+    readonly diffCount: number;
+    /** List of differences */
+    readonly differences: readonly Difference[];
+}
+/**
+ * Result of comparing two documents.
+ */
+export interface DocumentComparisonResult {
+    /** Overall similarity score (0.0 - 1.0) */
+    readonly similarity: number;
+    /** Per-page comparison results */
+    readonly pageResults: readonly PageComparisonResult[];
+    /** Number of pages in document A */
+    readonly pagesA: number;
+    /** Number of pages in document B */
+    readonly pagesB: number;
+    /** Total differences found across all pages */
+    readonly totalDifferences: number;
+}
+/**
+ * Manager for enterprise PDF operations.
+ *
+ * Provides methods for Bates numbering, document comparison,
+ * and header/footer stamping.
+ *
+ * @example
+ * ```typescript
+ * const enterprise = new EnterpriseManager(document);
+ *
+ * // Apply Bates numbering
+ * await enterprise.applyBates('DOC', 1, 6, BatesPosition.BOTTOM_RIGHT);
+ *
+ * // Compare pages
+ * const result = await enterprise.comparePages(docA, 0, docB, 0);
+ * console.log(`Pages are ${(result.similarity * 100).toFixed(1)}% similar`);
+ *
+ * // Stamp headers and footers
+ * await enterprise.stampHeader('CONFIDENTIAL', StampAlignment.CENTER, 12, 36);
+ * ```
+ */
+export declare class EnterpriseManager extends EventEmitter {
+    private document;
+    private native;
+    constructor(document: any);
+    /**
+     * Applies Bates numbering to the document.
+     *
+     * @param prefix - Text prefix before the number (e.g., 'DOC')
+     * @param startNumber - Starting number
+     * @param numDigits - Number of digits (zero-padded)
+     * @param position - Position on the page
+     * @throws PdfException if the operation fails
+     */
+    applyBates(prefix: string, startNumber: number, numDigits: number, position: BatesPosition): Promise<void>;
+    /**
+     * Applies advanced Bates numbering with full configuration.
+     *
+     * @param prefix - Text prefix before the number
+     * @param suffix - Text suffix after the number
+     * @param startNumber - Starting number
+     * @param numDigits - Number of digits (zero-padded)
+     * @param position - Position on the page
+     * @param fontSize - Font size in points
+     * @param margin - Margin from page edge in points
+     * @param startPage - Starting page index (0-based)
+     * @param endPage - Ending page index (0-based, -1 for last page)
+     * @throws PdfException if the operation fails
+     */
+    applyBatesAdvanced(prefix: string, suffix: string, startNumber: number, numDigits: number, position: BatesPosition, fontSize: number, margin: number, startPage: number, endPage: number): Promise<void>;
+    /**
+     * Compares two pages from potentially different documents.
+     *
+     * @param docA - First document handle
+     * @param pageA - Page index in first document (0-based)
+     * @param docB - Second document handle
+     * @param pageB - Page index in second document (0-based)
+     * @returns Comparison result with similarity score and differences
+     * @throws PdfException if the comparison fails
+     */
+    comparePages(docA: any, pageA: number, docB: any, pageB: number): Promise<PageComparisonResult>;
+    /**
+     * Compares two entire documents page by page.
+     *
+     * @param docA - First document handle
+     * @param docB - Second document handle
+     * @returns Document-level comparison result
+     * @throws PdfException if the comparison fails
+     */
+    compareDocuments(docA: any, docB: any): Promise<DocumentComparisonResult>;
+    /**
+     * Stamps a header on all pages of the document.
+     *
+     * @param text - Header text (supports placeholders: {page}, {pages}, {date})
+     * @param align - Text alignment
+     * @param size - Font size in points
+     * @param margin - Top margin in points
+     * @throws PdfException if the operation fails
+     */
+    stampHeader(text: string, align: StampAlignment, size: number, margin: number): Promise<void>;
+    /**
+     * Stamps a footer on all pages of the document.
+     *
+     * @param text - Footer text (supports placeholders: {page}, {pages}, {date})
+     * @param align - Text alignment
+     * @param size - Font size in points
+     * @param margin - Bottom margin in points
+     * @throws PdfException if the operation fails
+     */
+    stampFooter(text: string, align: StampAlignment, size: number, margin: number): Promise<void>;
+    /**
+     * Stamps both header and footer on all pages of the document.
+     *
+     * @param headerText - Header text
+     * @param footerText - Footer text
+     * @param align - Text alignment for both
+     * @param size - Font size in points
+     * @param margin - Margin from page edge in points
+     * @throws PdfException if the operation fails
+     */
+    stampHeaderFooter(headerText: string, footerText: string, align: StampAlignment, size: number, margin: number): Promise<void>;
+    /**
+     * Releases resources held by this manager.
+     */
+    destroy(): void;
+}
+export default EnterpriseManager;