pdf-lite 1.0.1-alpha.2 → 1.0.1-alpha.3

package/dist/pdf/pdf-document.d.ts

@@ -0,0 +1,277 @@
+import { PdfObject } from '../core/objects/pdf-object';
+import { PdfSecurityHandler } from '../security/handlers/base';
+import { PdfIndirectObject } from '../core/objects/pdf-indirect-object';
+import { PdfComment } from '../core/objects/pdf-comment';
+import { PdfToken } from '../core/tokens/token';
+import { PdfDictionary } from '../core/objects/pdf-dictionary';
+import { PdfObjectReference } from '../core/objects/pdf-object-reference';
+import { PdfXrefLookup } from './pdf-xref-lookup';
+import { PdfRevision } from './pdf-revision';
+import { PdfEncryptionDictionaryObject } from '../security/types';
+import { PdfTrailerEntries } from '../core/objects/pdf-trailer';
+import { PdfDocumentSecurityStoreObject } from '../signing/document-security-store';
+import { ByteArray } from '../types';
+import { PdfSigner } from '../signing/signer';
+/**
+ * Represents a PDF document with support for reading, writing, and modifying PDF files.
+ * Handles document structure, revisions, encryption, and digital signatures.
+ *
+ * @example
+ * ```typescript
+ * // Create a new document
+ * const document = new PdfDocument()
+ *
+ * // Read from bytes
+ * const document = await PdfDocument.fromBytes(fileBytes)
+ *
+ * // Add objects and commit
+ * document.add(pdfObject)
+ * await document.commit()
+ * ```
+ */
+export declare class PdfDocument extends PdfObject {
+    /** PDF version comment header */
+    header: PdfComment;
+    /** List of document revisions for incremental updates */
+    revisions: PdfRevision[];
+    /** Signer instance for digital signature operations */
+    signer: PdfSigner;
+    /** Security handler for encryption/decryption operations */
+    securityHandler?: PdfSecurityHandler;
+    private hasEncryptionDictionary?;
+    private toBeCommitted;
+    /**
+     * Creates a new PDF document instance.
+     *
+     * @param options - Configuration options for the document
+     * @param options.revisions - Pre-existing revisions for the document
+     * @param options.version - PDF version string (e.g., '1.7', '2.0') or version comment
+     * @param options.password - User password for encryption
+     * @param options.ownerPassword - Owner password for encryption
+     * @param options.securityHandler - Custom security handler for encryption
+     * @param options.signer - Custom signer for digital signatures
+     */
+    constructor(options?: {
+        revisions?: PdfRevision[];
+        version?: string | PdfComment;
+        password?: string;
+        ownerPassword?: string;
+        securityHandler?: PdfSecurityHandler;
+        signer?: PdfSigner;
+    });
+    /**
+     * Creates a PdfDocument from an array of PDF objects.
+     * Parses objects into revisions based on EOF comments.
+     *
+     * @param objects - Array of PDF objects to construct the document from
+     * @returns A new PdfDocument instance
+     */
+    static fromObjects(objects: PdfObject[]): PdfDocument;
+    /**
+     * Starts a new revision for incremental updates.
+     * Creates a new revision linked to the previous one.
+     *
+     * @returns The document instance for method chaining
+     */
+    startNewRevision(): PdfDocument;
+    /**
+     * Adds objects to the document's latest revision.
+     * Automatically starts a new revision if the current one is locked.
+     *
+     * @param objects - PDF objects to add to the document
+     */
+    add(...objects: PdfObject[]): void;
+    /**
+     * Gets the latest (most recent) revision of the document.
+     *
+     * @returns The latest PdfRevision
+     * @throws Error if the revision for the last StartXRef cannot be found
+     */
+    get latestRevision(): PdfRevision;
+    /**
+     * Gets the cross-reference lookup table for the latest revision.
+     *
+     * @returns The PdfXrefLookup for the latest revision
+     */
+    get xrefLookup(): PdfXrefLookup;
+    /**
+     * Gets the trailer dictionary from the cross-reference lookup.
+     *
+     * @returns The trailer dictionary containing document metadata references
+     */
+    get trailerDict(): PdfDictionary<PdfTrailerEntries>;
+    /**
+     * Gets all objects across all revisions in the document.
+     *
+     * @returns A readonly array of all PDF objects
+     */
+    get objects(): ReadonlyArray<PdfObject>;
+    /**
+     * Gets the encryption dictionary from the document if present.
+     *
+     * @returns The encryption dictionary object or undefined if not encrypted
+     * @throws Error if the encryption dictionary reference points to a non-dictionary object
+     */
+    get encryptionDictionary(): PdfEncryptionDictionaryObject | undefined;
+    /**
+     * Gets the document catalog (root) dictionary.
+     *
+     * @returns The root dictionary or undefined if not found
+     * @throws Error if the Root reference points to a non-dictionary object
+     */
+    get rootDictionary(): PdfDictionary | undefined;
+    /**
+     * Gets the reference to the metadata stream from the document catalog.
+     *
+     * @returns The metadata stream reference or undefined if not present
+     */
+    get metadataStreamReference(): PdfObjectReference | undefined;
+    private getSecurityHandler;
+    private initSecurityHandler;
+    /**
+     * Sets the user password for document encryption.
+     *
+     * @param password - The user password to set
+     * @throws Error if the security handler doesn't support password setting
+     */
+    setPassword(password: string): void;
+    /**
+     * Sets the owner password for document encryption.
+     *
+     * @param ownerPassword - The owner password to set
+     * @throws Error if the security handler doesn't support password setting
+     */
+    setOwnerPassword(ownerPassword: string): void;
+    /**
+     * Checks if a PDF object exists in the document.
+     *
+     * @param obj - The PDF object to check
+     * @returns True if the object exists in the document
+     */
+    hasObject(obj: PdfObject): boolean;
+    private isObjectEncryptable;
+    /**
+     * Decrypts all encrypted objects in the document.
+     * Removes the security handler and encryption dictionary after decryption.
+     */
+    decrypt(): Promise<void>;
+    /**
+     * Encrypts all objects in the document using the security handler.
+     * Creates and adds an encryption dictionary to all revisions.
+     */
+    encrypt(): Promise<void>;
+    /**
+     * Finds a compressed object by its object number within an object stream.
+     *
+     * @param options - Object identifier with objectNumber and optional generationNumber
+     * @returns The found indirect object or undefined if not found
+     * @throws Error if the object cannot be found in the expected object stream
+     */
+    findCompressedObject(options: {
+        objectNumber: number;
+        generationNumber?: number;
+    } | PdfObjectReference): Promise<PdfIndirectObject | undefined>;
+    /**
+     * Finds an uncompressed indirect object by its object number.
+     *
+     * @param options - Object identifier with objectNumber and optional generationNumber
+     * @returns The found indirect object or undefined if not found
+     * @throws FoundCompressedObjectError if the object is compressed (in an object stream)
+     */
+    findUncompressedObject(options: {
+        objectNumber: number;
+        generationNumber?: number;
+    } | PdfObjectReference): PdfIndirectObject | undefined;
+    /**
+     * Reads and optionally decrypts an object by its object number.
+     * Handles both compressed and uncompressed objects.
+     *
+     * @param options - Object lookup options
+     * @param options.objectNumber - The object number to find
+     * @param options.generationNumber - Optional generation number filter
+     * @param options.allowUnindexed - If true, searches unindexed objects as fallback
+     * @returns A cloned and decrypted copy of the object, or undefined if not found
+     */
+    readObject(options: {
+        objectNumber: number;
+        generationNumber?: number;
+        allowUnindexed?: boolean;
+    }): Promise<PdfIndirectObject | undefined>;
+    /**
+     * Deletes an object from all revisions in the document.
+     *
+     * @param obj - The PDF object to delete
+     */
+    deleteObject(obj: PdfObject | undefined): Promise<void>;
+    /**
+     * Sets the PDF version for the document.
+     *
+     * @param version - The PDF version string (e.g., '1.7', '2.0')
+     * @throws Error if attempting to change version after objects have been added in incremental mode
+     */
+    setVersion(version: string): void;
+    /**
+     * Sets whether the document should use incremental updates.
+     * When true, locks all existing revisions to preserve original content.
+     *
+     * @param value - True to enable incremental mode, false to disable
+     */
+    setIncremental(value: boolean): void;
+    /**
+     * Checks if the document is in incremental mode.
+     *
+     * @returns True if all revisions are locked for incremental updates
+     */
+    isIncremental(): boolean;
+    /**
+     * Commits pending objects to the document.
+     * Adds objects, applies encryption if configured, and updates the document structure.
+     *
+     * @param newObjects - Additional objects to add before committing
+     */
+    commit(...newObjects: PdfObject[]): Promise<void>;
+    /**
+     * Sets the Document Security Store (DSS) for the document.
+     * Used for long-term validation of digital signatures.
+     *
+     * @param dss - The Document Security Store object to set
+     * @throws Error if the document has no root dictionary
+     */
+    setDocumentSecurityStore(dss: PdfDocumentSecurityStoreObject): Promise<void>;
+    /**
+     * Returns tokens paired with their source objects.
+     * Useful for debugging and analysis of document structure.
+     *
+     * @returns Array of token-object pairs
+     */
+    tokensWithObjects(): {
+        token: PdfToken;
+        object: PdfObject | undefined;
+    }[];
+    protected tokenize(): PdfToken[];
+    private linkRevisions;
+    private linkOffsets;
+    private calculateOffsets;
+    private updateRevisions;
+    private update;
+    /**
+     * Serializes the document to a byte array.
+     *
+     * @returns The PDF document as a Uint8Array
+     */
+    toBytes(): ByteArray;
+    /**
+     * Creates a deep copy of the document.
+     *
+     * @returns A cloned PdfDocument instance
+     */
+    clone(): this;
+    /**
+     * Creates a PdfDocument from a byte stream.
+     *
+     * @param input - Async or sync iterable of byte arrays
+     * @returns A promise that resolves to the parsed PdfDocument
+     */
+    static fromBytes(input: AsyncIterable<ByteArray> | Iterable<ByteArray>): Promise<PdfDocument>;
+    isModified(): boolean;
+}