@signiphi/page-assembly 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import * as React from 'react';
 import React__default from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
+import { PDFDocument } from 'pdf-lib';
 
 /**
  * Represents a single page in the page assembly system
@@ -39,6 +40,52 @@ type FileInfo = {
     /** Pages extracted from this file */
     pages: PageInfo[];
 };
+/**
+ * Form field with page tracking for assembly operations
+ */
+type TrackedFormField = {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: string;
+    /** Field position */
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        page: number;
+    };
+    /** Page ID this field is associated with (for tracking across page operations) */
+    pageId?: string;
+    /** Original file ID this field came from */
+    originalFileId?: string;
+    /** All other field properties */
+    label?: string;
+    required?: boolean;
+    options?: string[];
+    placeholder?: string;
+    defaultValue?: string;
+    assignedSignerEmail?: string;
+    fieldId?: string;
+    fontSize?: number;
+    multiline?: boolean;
+    maxLength?: number;
+    acknowledgements?: Array<{
+        id: string;
+        title: string;
+        description: string;
+    }>;
+};
+/**
+ * Extracted fields from a file
+ */
+type FileExtractedFields = {
+    /** File ID these fields came from */
+    fileId: string;
+    /** Extracted form fields */
+    fields: TrackedFormField[];
+};
 /**
  * State of the page assembler
  */
@@ -49,6 +96,10 @@ type PageAssemblerState = {
     selection: string[];
     /** ID of the last selected page (for range selection) */
     lastSelectedPageId?: string;
+    /** Form fields tracked across page operations */
+    formFields?: TrackedFormField[];
+    /** Extracted fields per file (for mapping after assembly) */
+    extractedFieldsByFile?: FileExtractedFields[];
 };
 /**
  * Options for assembling the final PDF
@@ -136,6 +187,18 @@ declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAtt
 declare function pdfToImages(pdfBytes: Uint8Array, options?: {
     hideFormFields?: boolean;
 }): Promise<PageImage[]>;
+declare function rasterizePdfToPdf(pdfBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Prepares uploaded PDF bytes for the pdf-lib based assembly pipeline.
+ * Regular PDFs pass through untouched. Encrypted PDFs (typically
+ * permission-restricted documents that open without a password) are
+ * decrypted once here so every downstream `PDFDocument.load` — assembly,
+ * field extraction — sees a normal document. When structural decryption is
+ * impossible the document is rebuilt from rendered pages as a last resort.
+ *
+ * @throws {PdfPasswordRequiredError} when the PDF needs a real password
+ */
+declare function normalizeUploadedPdfBytes(pdfBytes: Uint8Array): Promise<Uint8Array>;
 /**
  * Converts an image file to a PDF document with a single page
  *
@@ -175,4 +238,179 @@ declare function createPdfBlobUrl(pdfBytes: Uint8Array): string;
  */
 declare function downloadPdf(pdfBytes: Uint8Array, filename: string): void;
 
-export { type AssembleOptions, Button, type FileInfo, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, createPdfBlobUrl, PageAssembler as default, downloadPdf, imageToPdf, pdfToImages };
+interface PdfPasswordRequiredErrorConstructor {
+    new (): PdfPasswordRequiredError;
+    readonly prototype: PdfPasswordRequiredError;
+}
+/**
+ * Thrown when the PDF needs a non-empty user password, which this package
+ * cannot supply. Match it with {@link isPdfPasswordRequiredError} rather than
+ * `instanceof` — see the header note on copies.
+ */
+interface PdfPasswordRequiredError extends Error {
+    /** Always `'PDF_PASSWORD_REQUIRED'`. The check that survives package boundaries. */
+    code: string;
+    recoverable: boolean;
+    userMessage: string;
+}
+declare const PdfPasswordRequiredError: PdfPasswordRequiredErrorConstructor;
+interface UnsupportedPdfEncryptionErrorConstructor {
+    new (detail: string): UnsupportedPdfEncryptionError;
+    readonly prototype: UnsupportedPdfEncryptionError;
+}
+/** Thrown for security handlers this decryptor does not implement. */
+interface UnsupportedPdfEncryptionError extends Error {
+    /** Always `'UnsupportedPdfEncryptionError'`. */
+    name: string;
+    /** The scheme that is not supported, e.g. `'V5 /R6'`. */
+    readonly detail: string;
+}
+declare const UnsupportedPdfEncryptionError: UnsupportedPdfEncryptionErrorConstructor;
+/**
+ * Decrypt an encrypted PDF that opens with an empty user password.
+ * Returns re-saved, fully decrypted bytes with `/Encrypt` removed.
+ *
+ * @throws {PdfPasswordRequiredError} when a non-empty password is required
+ * @throws {UnsupportedPdfEncryptionError} for non-standard security handlers
+ */
+declare const decryptPdf: (pdfBytes: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Ingestion gate — see `@signiphi/pdf-crypto`'s `normalizePdfEncryption`.
+ * Returns the bytes untouched (same reference) for ordinary PDFs; decrypts and
+ * re-saves encrypted ones so every downstream `PDFDocument.load` (page
+ * assembly, field extraction) sees a normal document.
+ *
+ * @throws {PdfPasswordRequiredError} when a non-empty password is required
+ * @throws {UnsupportedPdfEncryptionError} for non-standard security handlers
+ */
+declare function normalizePdfEncryption(pdfBytes: Uint8Array): Promise<Uint8Array>;
+
+/**
+ * PDF Field Extraction Utilities
+ * Extract form fields from PDFs with metadata support for preserving field properties
+ */
+
+/**
+ * Extracted field information
+ */
+interface ExtractedField {
+    name: string;
+    type: 'text' | 'signature' | 'initials' | 'date' | 'checkbox' | 'radio' | 'dropdown' | 'text_label';
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    required: boolean;
+    label?: string;
+    placeholder?: string;
+    options?: string[];
+    fieldId?: string;
+    signer?: string;
+}
+/**
+ * SigniphiMetadata structure stored in PDF Info dictionary
+ */
+interface SigniphiMetadata {
+    version: string;
+    fields: Record<string, {
+        fieldId?: string;
+        label?: string;
+        signer?: string;
+        placeholder?: string;
+        required?: boolean;
+        options?: string[];
+        acknowledgements?: Array<{
+            id: string;
+            title: string;
+            description: string;
+        }>;
+    }>;
+    fieldIdIndex?: Record<string, string>;
+}
+/**
+ * Extract SigniphiMetadata from a PDF document
+ */
+declare function getSigniphiMetadata(pdfDoc: PDFDocument): SigniphiMetadata | null;
+/**
+ * Extract form fields from a PDF document
+ * @param pdfBytes - PDF bytes
+ * @returns Array of extracted fields with all properties
+ */
+declare function extractFieldsFromPdf(pdfBytes: Uint8Array): Promise<ExtractedField[]>;
+/**
+ * Set SigniphiMetadata in a PDF document
+ */
+declare function setSigniphiMetadata(pdfDoc: PDFDocument, metadata: SigniphiMetadata): void;
+
+/**
+ * Add Form Fields to PDF
+ * Re-adds form fields to a PDF after page assembly operations
+ * This is the key to preserving form fields - don't try to preserve during copyPages,
+ * instead extract fields first, copy pages, then re-add fields with adjusted positions.
+ */
+/**
+ * Form field type enum matching document-prepare
+ */
+declare enum FormFieldType {
+    TEXT = "text",
+    SIGNATURE = "signature",
+    INITIALS = "initials",
+    DATE = "date",
+    CHECKBOX = "checkbox",
+    RADIO = "radio",
+    DROPDOWN = "dropdown",
+    TEXT_LABEL = "text_label"
+}
+/**
+ * Form field position
+ */
+interface FormFieldPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    page: number;
+}
+/**
+ * Form field for adding to PDF
+ */
+interface FormFieldForPdf {
+    name: string;
+    type: FormFieldType | string;
+    position: FormFieldPosition;
+    label?: string;
+    required?: boolean;
+    options?: string[];
+    defaultValue?: string;
+    placeholder?: string;
+    fontSize?: number;
+    multiline?: boolean;
+    maxLength?: number;
+    assignedSignerEmail?: string;
+}
+/**
+ * Add form fields to a PDF document
+ *
+ * @param pdfBytes - The PDF document bytes
+ * @param formFields - Array of form fields to add
+ * @param options - Options for field addition
+ * @returns Modified PDF bytes with form fields added
+ */
+declare function addFormFieldsToPdf(pdfBytes: Uint8Array, formFields: FormFieldForPdf[], options?: {
+    removeExistingFields?: boolean;
+    drawLabels?: boolean;
+}): Promise<Uint8Array>;
+/**
+ * Map field positions after page assembly
+ * Updates field page numbers based on the final page arrangement
+ *
+ * @param fields - Original fields with positions
+ * @param pageMapping - Map of "originalFileId_originalPageIndex" -> newPageNumber
+ * @returns Fields with updated page positions
+ */
+declare function mapFieldPositionsAfterAssembly<T extends {
+    position: FormFieldPosition;
+}>(fields: T[], pageMapping: Map<string, number>): T[];
+
+export { type AssembleOptions, Button, type ExtractedField, type FileExtractedFields, type FileInfo, type FormFieldForPdf, type FormFieldPosition, FormFieldType, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, PdfPasswordRequiredError, type TrackedFormField, UnsupportedPdfEncryptionError, addFormFieldsToPdf, createPdfBlobUrl, decryptPdf, downloadPdf, extractFieldsFromPdf, getSigniphiMetadata, imageToPdf, mapFieldPositionsAfterAssembly, normalizePdfEncryption, normalizeUploadedPdfBytes, pdfToImages, rasterizePdfToPdf, setSigniphiMetadata };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import * as React from 'react';
 import React__default from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
+import { PDFDocument } from 'pdf-lib';
 
 /**
  * Represents a single page in the page assembly system
@@ -39,6 +40,52 @@ type FileInfo = {
     /** Pages extracted from this file */
     pages: PageInfo[];
 };
+/**
+ * Form field with page tracking for assembly operations
+ */
+type TrackedFormField = {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: string;
+    /** Field position */
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        page: number;
+    };
+    /** Page ID this field is associated with (for tracking across page operations) */
+    pageId?: string;
+    /** Original file ID this field came from */
+    originalFileId?: string;
+    /** All other field properties */
+    label?: string;
+    required?: boolean;
+    options?: string[];
+    placeholder?: string;
+    defaultValue?: string;
+    assignedSignerEmail?: string;
+    fieldId?: string;
+    fontSize?: number;
+    multiline?: boolean;
+    maxLength?: number;
+    acknowledgements?: Array<{
+        id: string;
+        title: string;
+        description: string;
+    }>;
+};
+/**
+ * Extracted fields from a file
+ */
+type FileExtractedFields = {
+    /** File ID these fields came from */
+    fileId: string;
+    /** Extracted form fields */
+    fields: TrackedFormField[];
+};
 /**
  * State of the page assembler
  */
@@ -49,6 +96,10 @@ type PageAssemblerState = {
     selection: string[];
     /** ID of the last selected page (for range selection) */
     lastSelectedPageId?: string;
+    /** Form fields tracked across page operations */
+    formFields?: TrackedFormField[];
+    /** Extracted fields per file (for mapping after assembly) */
+    extractedFieldsByFile?: FileExtractedFields[];
 };
 /**
  * Options for assembling the final PDF
@@ -136,6 +187,18 @@ declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAtt
 declare function pdfToImages(pdfBytes: Uint8Array, options?: {
     hideFormFields?: boolean;
 }): Promise<PageImage[]>;
+declare function rasterizePdfToPdf(pdfBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Prepares uploaded PDF bytes for the pdf-lib based assembly pipeline.
+ * Regular PDFs pass through untouched. Encrypted PDFs (typically
+ * permission-restricted documents that open without a password) are
+ * decrypted once here so every downstream `PDFDocument.load` — assembly,
+ * field extraction — sees a normal document. When structural decryption is
+ * impossible the document is rebuilt from rendered pages as a last resort.
+ *
+ * @throws {PdfPasswordRequiredError} when the PDF needs a real password
+ */
+declare function normalizeUploadedPdfBytes(pdfBytes: Uint8Array): Promise<Uint8Array>;
 /**
  * Converts an image file to a PDF document with a single page
  *
@@ -175,4 +238,179 @@ declare function createPdfBlobUrl(pdfBytes: Uint8Array): string;
  */
 declare function downloadPdf(pdfBytes: Uint8Array, filename: string): void;
 
-export { type AssembleOptions, Button, type FileInfo, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, createPdfBlobUrl, PageAssembler as default, downloadPdf, imageToPdf, pdfToImages };
+interface PdfPasswordRequiredErrorConstructor {
+    new (): PdfPasswordRequiredError;
+    readonly prototype: PdfPasswordRequiredError;
+}
+/**
+ * Thrown when the PDF needs a non-empty user password, which this package
+ * cannot supply. Match it with {@link isPdfPasswordRequiredError} rather than
+ * `instanceof` — see the header note on copies.
+ */
+interface PdfPasswordRequiredError extends Error {
+    /** Always `'PDF_PASSWORD_REQUIRED'`. The check that survives package boundaries. */
+    code: string;
+    recoverable: boolean;
+    userMessage: string;
+}
+declare const PdfPasswordRequiredError: PdfPasswordRequiredErrorConstructor;
+interface UnsupportedPdfEncryptionErrorConstructor {
+    new (detail: string): UnsupportedPdfEncryptionError;
+    readonly prototype: UnsupportedPdfEncryptionError;
+}
+/** Thrown for security handlers this decryptor does not implement. */
+interface UnsupportedPdfEncryptionError extends Error {
+    /** Always `'UnsupportedPdfEncryptionError'`. */
+    name: string;
+    /** The scheme that is not supported, e.g. `'V5 /R6'`. */
+    readonly detail: string;
+}
+declare const UnsupportedPdfEncryptionError: UnsupportedPdfEncryptionErrorConstructor;
+/**
+ * Decrypt an encrypted PDF that opens with an empty user password.
+ * Returns re-saved, fully decrypted bytes with `/Encrypt` removed.
+ *
+ * @throws {PdfPasswordRequiredError} when a non-empty password is required
+ * @throws {UnsupportedPdfEncryptionError} for non-standard security handlers
+ */
+declare const decryptPdf: (pdfBytes: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Ingestion gate — see `@signiphi/pdf-crypto`'s `normalizePdfEncryption`.
+ * Returns the bytes untouched (same reference) for ordinary PDFs; decrypts and
+ * re-saves encrypted ones so every downstream `PDFDocument.load` (page
+ * assembly, field extraction) sees a normal document.
+ *
+ * @throws {PdfPasswordRequiredError} when a non-empty password is required
+ * @throws {UnsupportedPdfEncryptionError} for non-standard security handlers
+ */
+declare function normalizePdfEncryption(pdfBytes: Uint8Array): Promise<Uint8Array>;
+
+/**
+ * PDF Field Extraction Utilities
+ * Extract form fields from PDFs with metadata support for preserving field properties
+ */
+
+/**
+ * Extracted field information
+ */
+interface ExtractedField {
+    name: string;
+    type: 'text' | 'signature' | 'initials' | 'date' | 'checkbox' | 'radio' | 'dropdown' | 'text_label';
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    required: boolean;
+    label?: string;
+    placeholder?: string;
+    options?: string[];
+    fieldId?: string;
+    signer?: string;
+}
+/**
+ * SigniphiMetadata structure stored in PDF Info dictionary
+ */
+interface SigniphiMetadata {
+    version: string;
+    fields: Record<string, {
+        fieldId?: string;
+        label?: string;
+        signer?: string;
+        placeholder?: string;
+        required?: boolean;
+        options?: string[];
+        acknowledgements?: Array<{
+            id: string;
+            title: string;
+            description: string;
+        }>;
+    }>;
+    fieldIdIndex?: Record<string, string>;
+}
+/**
+ * Extract SigniphiMetadata from a PDF document
+ */
+declare function getSigniphiMetadata(pdfDoc: PDFDocument): SigniphiMetadata | null;
+/**
+ * Extract form fields from a PDF document
+ * @param pdfBytes - PDF bytes
+ * @returns Array of extracted fields with all properties
+ */
+declare function extractFieldsFromPdf(pdfBytes: Uint8Array): Promise<ExtractedField[]>;
+/**
+ * Set SigniphiMetadata in a PDF document
+ */
+declare function setSigniphiMetadata(pdfDoc: PDFDocument, metadata: SigniphiMetadata): void;
+
+/**
+ * Add Form Fields to PDF
+ * Re-adds form fields to a PDF after page assembly operations
+ * This is the key to preserving form fields - don't try to preserve during copyPages,
+ * instead extract fields first, copy pages, then re-add fields with adjusted positions.
+ */
+/**
+ * Form field type enum matching document-prepare
+ */
+declare enum FormFieldType {
+    TEXT = "text",
+    SIGNATURE = "signature",
+    INITIALS = "initials",
+    DATE = "date",
+    CHECKBOX = "checkbox",
+    RADIO = "radio",
+    DROPDOWN = "dropdown",
+    TEXT_LABEL = "text_label"
+}
+/**
+ * Form field position
+ */
+interface FormFieldPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    page: number;
+}
+/**
+ * Form field for adding to PDF
+ */
+interface FormFieldForPdf {
+    name: string;
+    type: FormFieldType | string;
+    position: FormFieldPosition;
+    label?: string;
+    required?: boolean;
+    options?: string[];
+    defaultValue?: string;
+    placeholder?: string;
+    fontSize?: number;
+    multiline?: boolean;
+    maxLength?: number;
+    assignedSignerEmail?: string;
+}
+/**
+ * Add form fields to a PDF document
+ *
+ * @param pdfBytes - The PDF document bytes
+ * @param formFields - Array of form fields to add
+ * @param options - Options for field addition
+ * @returns Modified PDF bytes with form fields added
+ */
+declare function addFormFieldsToPdf(pdfBytes: Uint8Array, formFields: FormFieldForPdf[], options?: {
+    removeExistingFields?: boolean;
+    drawLabels?: boolean;
+}): Promise<Uint8Array>;
+/**
+ * Map field positions after page assembly
+ * Updates field page numbers based on the final page arrangement
+ *
+ * @param fields - Original fields with positions
+ * @param pageMapping - Map of "originalFileId_originalPageIndex" -> newPageNumber
+ * @returns Fields with updated page positions
+ */
+declare function mapFieldPositionsAfterAssembly<T extends {
+    position: FormFieldPosition;
+}>(fields: T[], pageMapping: Map<string, number>): T[];
+
+export { type AssembleOptions, Button, type ExtractedField, type FileExtractedFields, type FileInfo, type FormFieldForPdf, type FormFieldPosition, FormFieldType, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, PdfPasswordRequiredError, type TrackedFormField, UnsupportedPdfEncryptionError, addFormFieldsToPdf, createPdfBlobUrl, decryptPdf, downloadPdf, extractFieldsFromPdf, getSigniphiMetadata, imageToPdf, mapFieldPositionsAfterAssembly, normalizePdfEncryption, normalizeUploadedPdfBytes, pdfToImages, rasterizePdfToPdf, setSigniphiMetadata };