@signiphi/page-assembly 0.2.0-beta.2 → 0.2.0-beta.20

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,59 @@ 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[];
+    /** RADIO: each option's circle rect, top-origin, on `position.page`. */
+    optionPositions?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    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 +103,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 +194,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 +245,280 @@ 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' | 'date_signed' | '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;
+    /**
+     * RADIO: each option's circle widget rect on this page, top-origin, in
+     * option order — exactly as read, so a re-add can put every circle back
+     * where it was. `x/y/width/height` above is only the first circle.
+     */
+    optionPositions?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * One field's metadata entry, as stored in the block.
+ */
+interface SigniphiFieldMetadata {
+    fieldId?: string;
+    /**
+     * Persisted field type. Read for one value: `date_signed`, which the name
+     * guess can only see as a date. Every other key (`autofillTag`, `dateFormat`,
+     * …) is carried through the merge untouched without being declared here.
+     */
+    type?: ExtractedField['type'];
+    label?: string;
+    signer?: string;
+    placeholder?: string;
+    required?: boolean;
+    options?: string[];
+    acknowledgements?: Array<{
+        id: string;
+        title: string;
+        description: string;
+    }>;
+    /**
+     * TEXT_LABEL only: this entry's text is already in the page stream, so the
+     * sign-time pass must not redraw it. See `mergeSourceMetadata`, which sets it
+     * when a source that had baked its labels is merged with one that deferred.
+     */
+    textLabelBaked?: boolean;
+    /**
+     * CHECKBOX only: this field's caption is already in the page stream, written
+     * by document-prepare's bake. Declared so the merge carries it through — it
+     * is what pdf-signer's `checkboxLabelSource` actually decides on, the
+     * document-level `checkboxLabelsBaked` below being only the bake's mode.
+     * Nothing here sets or reads it.
+     */
+    checkboxCaptionBaked?: boolean;
+    /**
+     * Persisted geometry, written by `document-prepare` for RADIO and TEXT_LABEL
+     * fields only. Declared here for ONE reason: its `page` is the SOURCE
+     * document's page number, and the merge has to rewrite it to the combined
+     * one. Nothing in page-assembly reads x/y/width/height.
+     */
+    position?: SigniphiFieldPosition;
+    /** Radio-only, per-option. Re-paged alongside {@link SigniphiFieldMetadata.position}. */
+    radioPositions?: SigniphiFieldPosition[];
+    /** Radio-only bound list (options ↔ circle positions); its pages are re-paged too. */
+    radioOptions?: Array<{
+        label: string;
+        exportValue: string;
+        position: SigniphiFieldPosition;
+    }>;
+}
+/**
+ * A persisted field rect, as `document-prepare` writes it. `page` is 1-indexed
+ * and scoped to the document it was written in — which is exactly why the merge
+ * cannot carry it across unchanged.
+ */
+interface SigniphiFieldPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    page: number;
+}
+/**
+ * SigniphiMetadata structure stored in PDF Info dictionary.
+ *
+ * Exported because `getSigniphiMetadata` / `setSigniphiMetadata` are public
+ * (`utils/index.ts`) and a caller cannot name their argument otherwise — which
+ * is what pushed the call sites here into `as never` casts that would have
+ * silenced any future shape mismatch.
+ */
+interface SigniphiMetadata {
+    version: string;
+    fields: Record<string, SigniphiFieldMetadata>;
+    fieldIdIndex?: Record<string, string>;
+    /**
+     * Document-level: radio group and option text is already drawn into the page
+     * stream, so the sign-time pass must not redraw it. Absent on legacy PDFs,
+     * which pdf-signer reads as "draw".
+     */
+    radioLabelsBaked?: boolean;
+    /**
+     * Document-level: `false` means TEXT_LABEL text was deliberately NOT baked
+     * (multi-signer), so the sign-time pass redraws it per signer. Absent/`true`
+     * means it is already in the page stream.
+     */
+    textLabelsBaked?: boolean;
+    /**
+     * Document-level: `false` means CHECKBOX captions were deliberately NOT baked
+     * beside their boxes (multi-signer), so the sign-time pass draws them per
+     * signer. `true` means they are already in the page stream. Absent means the
+     * source predates baked captions, which pdf-signer also reads as "draw".
+     */
+    checkboxLabelsBaked?: boolean;
+}
+/**
+ * Extract SigniphiMetadata from a PDF document. Delegates to the contract
+ * package's reader; null when there is no block or it will not parse.
+ */
+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. Delegates to the contract package's
+ * writer, which stores hex and throws on failure.
+ */
+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",
+    /** A DATE the signer never edits: stamped at signing. Re-added exactly like DATE. */
+    DATE_SIGNED = "date_signed"
+}
+/**
+ * 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;
+    /**
+     * RADIO: each option's circle widget rect, top-origin, on `position.page`,
+     * as `extractFieldsFromPdf` read it. When it covers every option, the circles
+     * are re-added exactly there instead of being laid out afresh in `position`.
+     */
+    optionPositions?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * 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 };