pdf-oxide 0.3.37 → 0.3.39

package/lib/managers/signature-manager.js

@@ -179,7 +179,9 @@ export class SignatureManager extends EventEmitter {
             try {
                 result = JSON.parse(this.native.verify_signatures());
             }
-            catch { /* defaults */ }
+            catch {
+                /* defaults */
+            }
         }
         this.setCached(cacheKey, result);
         this.emit('signaturesVerified', { isValid: result.isValid, issueCount: result.issues.length });
@@ -194,7 +196,9 @@ export class SignatureManager extends EventEmitter {
             try {
                 result = JSON.parse(this.native.verify_signature(signatureName));
             }
-            catch { /* defaults */ }
+            catch {
+                /* defaults */
+            }
         }
         this.setCached(cacheKey, result);
         return result;
@@ -236,12 +240,20 @@ export class SignatureManager extends EventEmitter {
             const certId = `cert_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
             const nativeResult = await this.document?.loadCertificate?.(certData, password, format);
             const info = nativeResult?.info ?? {
-                subject: nativeResult?.subject ?? 'Unknown', issuer: nativeResult?.issuer ?? 'Unknown',
-                serialNumber: nativeResult?.serialNumber ?? '', validFrom: new Date(nativeResult?.validFrom ?? Date.now()),
+                subject: nativeResult?.subject ?? 'Unknown',
+                issuer: nativeResult?.issuer ?? 'Unknown',
+                serialNumber: nativeResult?.serialNumber ?? '',
+                validFrom: new Date(nativeResult?.validFrom ?? Date.now()),
                 validTo: new Date(nativeResult?.validTo ?? Date.now() + 365 * 24 * 60 * 60 * 1000),
-                isValid: nativeResult?.isValid ?? false, isSelfSigned: nativeResult?.isSelfSigned ?? false,
+                isValid: nativeResult?.isValid ?? false,
+                isSelfSigned: nativeResult?.isSelfSigned ?? false,
+            };
+            const loadedCert = {
+                certificateId: certId,
+                info,
+                hasPrivateKey: nativeResult?.hasPrivateKey ?? true,
+                chain: nativeResult?.chain,
             };
-            const loadedCert = { certificateId: certId, info, hasPrivateKey: nativeResult?.hasPrivateKey ?? true, chain: nativeResult?.chain };
             this.loadedCertificates.set(certId, loadedCert);
             this.emit('certificate-loaded', { certificateId: certId, subject: info.subject });
             return loadedCert;
@@ -258,12 +270,19 @@ export class SignatureManager extends EventEmitter {
             if (!nativeResult)
                 throw new Error('Failed to load PEM certificate');
             const info = {
-                subject: nativeResult.subject ?? 'Unknown', issuer: nativeResult.issuer ?? 'Unknown',
-                serialNumber: nativeResult.serialNumber ?? '', validFrom: new Date(nativeResult.validFrom ?? Date.now()),
+                subject: nativeResult.subject ?? 'Unknown',
+                issuer: nativeResult.issuer ?? 'Unknown',
+                serialNumber: nativeResult.serialNumber ?? '',
+                validFrom: new Date(nativeResult.validFrom ?? Date.now()),
                 validTo: new Date(nativeResult.validTo ?? Date.now() + 365 * 24 * 60 * 60 * 1000),
-                isValid: nativeResult.isValid ?? false, isSelfSigned: nativeResult.isSelfSigned ?? false,
+                isValid: nativeResult.isValid ?? false,
+                isSelfSigned: nativeResult.isSelfSigned ?? false,
+            };
+            const loadedCert = {
+                certificateId: certId,
+                info,
+                hasPrivateKey: !!privateKeyPem,
             };
-            const loadedCert = { certificateId: certId, info, hasPrivateKey: !!privateKeyPem };
             this.loadedCertificates.set(certId, loadedCert);
             this.emit('certificate-loaded', { certificateId: certId, subject: info.subject });
             return loadedCert;
@@ -283,7 +302,7 @@ export class SignatureManager extends EventEmitter {
                 return null;
             if (cert.chain)
                 return cert.chain;
-            return await this.document?.getCertificateChain?.(certificateId) ?? null;
+            return (await this.document?.getCertificateChain?.(certificateId)) ?? null;
         }
         catch (error) {
             this.emit('error', error);
@@ -296,11 +315,19 @@ export class SignatureManager extends EventEmitter {
             if (!cert)
                 return { valid: false, errors: ['Certificate not found'], warnings: [] };
             const result = await this.document?.validateCertificate?.(certificateId);
-            return result ?? { valid: cert.info.isValid, errors: cert.info.isValid ? [] : ['Certificate validation failed'], warnings: [] };
+            return (result ?? {
+                valid: cert.info.isValid,
+                errors: cert.info.isValid ? [] : ['Certificate validation failed'],
+                warnings: [],
+            });
         }
         catch (error) {
             this.emit('error', error);
-            return { valid: false, errors: [error instanceof Error ? error.message : 'Unknown error'], warnings: [] };
+            return {
+                valid: false,
+                errors: [error instanceof Error ? error.message : 'Unknown error'],
+                warnings: [],
+            };
         }
     }
     getLoadedCertificates() {
@@ -317,7 +344,12 @@ export class SignatureManager extends EventEmitter {
     // ===========================================================================
     async addSignatureField(config) {
         try {
-            const result = await this.document?.addSignatureField?.(config.fieldName, config.pageIndex, config.x, config.y, config.width, config.height, { appearance: config.appearance, tooltip: config.tooltip, isRequired: config.isRequired, isReadOnly: config.isReadOnly });
+            const result = await this.document?.addSignatureField?.(config.fieldName, config.pageIndex, config.x, config.y, config.width, config.height, {
+                appearance: config.appearance,
+                tooltip: config.tooltip,
+                isRequired: config.isRequired,
+                isReadOnly: config.isReadOnly,
+            });
             if (result !== false) {
                 this.createdFields.set(config.fieldName, config);
                 this.clearCachePattern('signatures:');
@@ -347,7 +379,7 @@ export class SignatureManager extends EventEmitter {
     }
     async getSignatureFieldNames() {
         try {
-            return await this.document?.getSignatureFields?.() ?? [];
+            return (await this.document?.getSignatureFields?.()) ?? [];
         }
         catch (error) {
             this.emit('error', error);
@@ -387,7 +419,9 @@ export class SignatureManager extends EventEmitter {
             if (!cert.hasPrivateKey)
                 return { success: false, error: 'Certificate does not have private key' };
             const nativeResult = await this.document?.signDocument?.(fieldName, certId, {
-                reason: options?.reason, location: options?.location, contactInfo: options?.contactInfo,
+                reason: options?.reason,
+                location: options?.location,
+                contactInfo: options?.contactInfo,
                 signatureType: options?.signatureType ?? SignatureType.APPROVAL,
                 certificationPermission: options?.certificationPermission,
                 algorithm: options?.algorithm ?? SignatureAlgorithm.RSA_SHA256,
@@ -397,16 +431,28 @@ export class SignatureManager extends EventEmitter {
             const signingTime = new Date();
             let timestampTime;
             if (options?.embedTimestamp && options?.timestampServerUrl) {
-                const tsResult = await this.embedTimestamp(fieldName, { serverUrl: options.timestampServerUrl, hashAlgorithm: options.digestAlgorithm });
+                const tsResult = await this.embedTimestamp(fieldName, {
+                    serverUrl: options.timestampServerUrl,
+                    hashAlgorithm: options.digestAlgorithm,
+                });
                 if (tsResult.status === TimestampStatus.SUCCESS)
                     timestampTime = tsResult.timestamp;
             }
             if (options?.enableLtv)
-                await this.enableLtvForSignature(fieldName, { ocspResponderUrl: options.ocspResponderUrl, crlDistributionPoints: options.crlDistributionPoints });
+                await this.enableLtvForSignature(fieldName, {
+                    ocspResponderUrl: options.ocspResponderUrl,
+                    crlDistributionPoints: options.crlDistributionPoints,
+                });
             const signatureId = `sig_${fieldName}_${Date.now()}`;
             this.clearCachePattern('signatures:');
             this.emit('document-signed', { signatureId, fieldName, signingTime, timestampTime });
-            return { success: true, signatureId, signingTime, timestampTime, warnings: nativeResult?.warnings };
+            return {
+                success: true,
+                signatureId,
+                signingTime,
+                timestampTime,
+                warnings: nativeResult?.warnings,
+            };
         }
         catch (error) {
             this.emit('error', error);
@@ -414,7 +460,11 @@ export class SignatureManager extends EventEmitter {
         }
     }
     async certifyDocument(fieldName, certificate, permission, options) {
-        return this.signDocument(fieldName, certificate, { ...options, signatureType: SignatureType.CERTIFICATION, certificationPermission: permission });
+        return this.signDocument(fieldName, certificate, {
+            ...options,
+            signatureType: SignatureType.CERTIFICATION,
+            certificationPermission: permission,
+        });
     }
     async signInvisibly(certificate, options) {
         try {
@@ -430,7 +480,15 @@ export class SignatureManager extends EventEmitter {
     async counterSign(certificate, options) {
         try {
             const fieldName = `CounterSig_${Date.now()}`;
-            await this.addSignatureField({ fieldName, pageIndex: 0, x: 100, y: 100, width: 200, height: 50, appearance: options?.appearance });
+            await this.addSignatureField({
+                fieldName,
+                pageIndex: 0,
+                x: 100,
+                y: 100,
+                width: 200,
+                height: 50,
+                appearance: options?.appearance,
+            });
             return this.signDocument(fieldName, certificate, options);
         }
         catch (error) {
@@ -450,7 +508,10 @@ export class SignatureManager extends EventEmitter {
     }
     async prepareForExternalSigning(fieldName, options) {
         try {
-            const result = await this.document?.prepareForExternalSigning?.(fieldName, { estimatedSize: options?.estimatedSize ?? 8192, digestAlgorithm: options?.digestAlgorithm ?? DigestAlgorithm.SHA256 });
+            const result = await this.document?.prepareForExternalSigning?.(fieldName, {
+                estimatedSize: options?.estimatedSize ?? 8192,
+                digestAlgorithm: options?.digestAlgorithm ?? DigestAlgorithm.SHA256,
+            });
             this.emit('prepared-for-external-signing', { fieldName });
             return result ?? null;
         }
@@ -464,16 +525,36 @@ export class SignatureManager extends EventEmitter {
     // ===========================================================================
     async embedTimestamp(fieldName, config) {
         try {
-            const result = await this.document?.embedTimestamp?.(fieldName, { serverUrl: config.serverUrl, username: config.username, password: config.password, hashAlgorithm: config.hashAlgorithm ?? DigestAlgorithm.SHA256, timeout: config.timeout ?? 30000, policy: config.policy, nonce: config.nonce ?? true, certReq: config.certReq ?? true });
+            const result = await this.document?.embedTimestamp?.(fieldName, {
+                serverUrl: config.serverUrl,
+                username: config.username,
+                password: config.password,
+                hashAlgorithm: config.hashAlgorithm ?? DigestAlgorithm.SHA256,
+                timeout: config.timeout ?? 30000,
+                policy: config.policy,
+                nonce: config.nonce ?? true,
+                certReq: config.certReq ?? true,
+            });
             if (result?.success) {
                 this.emit('timestamp-embedded', { fieldName, timestamp: result.timestamp });
-                return { status: TimestampStatus.SUCCESS, timestamp: new Date(result.timestamp), serialNumber: result.serialNumber, tsaName: result.tsaName };
+                return {
+                    status: TimestampStatus.SUCCESS,
+                    timestamp: new Date(result.timestamp),
+                    serialNumber: result.serialNumber,
+                    tsaName: result.tsaName,
+                };
             }
-            return { status: TimestampStatus.FAILED, error: result?.error ?? 'Timestamp embedding failed' };
+            return {
+                status: TimestampStatus.FAILED,
+                error: result?.error ?? 'Timestamp embedding failed',
+            };
         }
         catch (error) {
             this.emit('error', error);
-            return { status: TimestampStatus.FAILED, error: error instanceof Error ? error.message : 'Unknown error' };
+            return {
+                status: TimestampStatus.FAILED,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
         }
     }
     async addDocumentTimestamp(config) {
@@ -483,18 +564,32 @@ export class SignatureManager extends EventEmitter {
             const result = await this.document?.addDocumentTimestamp?.(fieldName, config);
             if (result?.success) {
                 this.emit('document-timestamp-added', { timestamp: result.timestamp });
-                return { status: TimestampStatus.SUCCESS, timestamp: new Date(result.timestamp), serialNumber: result.serialNumber, tsaName: result.tsaName };
+                return {
+                    status: TimestampStatus.SUCCESS,
+                    timestamp: new Date(result.timestamp),
+                    serialNumber: result.serialNumber,
+                    tsaName: result.tsaName,
+                };
             }
-            return { status: TimestampStatus.FAILED, error: result?.error ?? 'Document timestamp failed' };
+            return {
+                status: TimestampStatus.FAILED,
+                error: result?.error ?? 'Document timestamp failed',
+            };
         }
         catch (error) {
             this.emit('error', error);
-            return { status: TimestampStatus.FAILED, error: error instanceof Error ? error.message : 'Unknown error' };
+            return {
+                status: TimestampStatus.FAILED,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
         }
     }
     async validateTimestamp(fieldName) {
         try {
-            return await this.document?.validateTimestamp?.(fieldName) ?? { valid: false, errors: ['Timestamp validation not available'] };
+            return ((await this.document?.validateTimestamp?.(fieldName)) ?? {
+                valid: false,
+                errors: ['Timestamp validation not available'],
+            });
         }
         catch (error) {
             this.emit('error', error);
@@ -503,7 +598,7 @@ export class SignatureManager extends EventEmitter {
     }
     async getTimestampInfo(fieldName) {
         try {
-            return await this.document?.getTimestampInfo?.(fieldName) ?? null;
+            return (await this.document?.getTimestampInfo?.(fieldName)) ?? null;
         }
         catch (error) {
             this.emit('error', error);
@@ -515,7 +610,10 @@ export class SignatureManager extends EventEmitter {
     // ===========================================================================
     async enableLtvForSignature(fieldName, options) {
         try {
-            const result = await this.document?.enableLtvForSignature?.(fieldName, { ocspResponderUrl: options?.ocspResponderUrl, crlDistributionPoints: options?.crlDistributionPoints });
+            const result = await this.document?.enableLtvForSignature?.(fieldName, {
+                ocspResponderUrl: options?.ocspResponderUrl,
+                crlDistributionPoints: options?.crlDistributionPoints,
+            });
             if (result)
                 this.emit('ltv-enabled', { fieldName });
             return !!result;
@@ -554,7 +652,7 @@ export class SignatureManager extends EventEmitter {
     }
     async hasLtvEnabled(fieldName) {
         try {
-            return await this.document?.hasLtvEnabled?.(fieldName) ?? false;
+            return (await this.document?.hasLtvEnabled?.(fieldName)) ?? false;
         }
         catch (error) {
             this.emit('error', error);
@@ -632,15 +730,20 @@ export class SignatureManager extends EventEmitter {
         try {
             const [notBefore, notAfter] = await this.getCertificateValidity(index);
             const certificate = {
-                subject: await this.getCertificateSubject(index), issuer: await this.getCertificateIssuer(index),
-                serial: await this.getCertificateSerial(index), notBefore, notAfter,
+                subject: await this.getCertificateSubject(index),
+                issuer: await this.getCertificateIssuer(index),
+                serial: await this.getCertificateSerial(index),
+                notBefore,
+                notAfter,
                 isValid: await this.isCertificateValidByIndex(index),
             };
             return {
-                signerName: await this.getSignerName(index), signingTime: await this.getSigningTime(index),
+                signerName: await this.getSignerName(index),
+                signingTime: await this.getSigningTime(index),
                 reason: (await this.getSigningReason(index)) || undefined,
                 location: (await this.getSigningLocation(index)) || undefined,
-                certificate, isValid: true,
+                certificate,
+                isValid: true,
             };
         }
         catch (error) {
@@ -1339,7 +1442,11 @@ export class SignatureManager extends EventEmitter {
         this.emit('cacheCleared');
     }
     getCacheStats() {
-        return { cacheSize: this.resultCache.size, maxCacheSize: this.maxCacheSize, entries: Array.from(this.resultCache.keys()) };
+        return {
+            cacheSize: this.resultCache.size,
+            maxCacheSize: this.maxCacheSize,
+            entries: Array.from(this.resultCache.keys()),
+        };
     }
     destroy() {
         this.loadedCertificates.clear();
@@ -1347,6 +1454,42 @@ export class SignatureManager extends EventEmitter {
         this.resultCache.clear();
         this.removeAllListeners();
     }
+    /**
+     * Sign a PDF from raw bytes using PEM credentials.
+     *
+     * Calls the native `signPdfBytes` FFI function (two-pass ByteRange writer).
+     * Credentials are loaded and freed within this call.
+     *
+     * @param pdfData - Buffer containing the PDF document bytes
+     * @param certPem - PEM-encoded certificate string
+     * @param keyPem  - PEM-encoded private key string
+     * @param reason  - Optional signature reason
+     * @param location - Optional signature location
+     * @returns Buffer containing the signed PDF
+     */
+    async signPdfData(pdfData, certPem, keyPem, reason, location) {
+        if (!this.native?.certificateLoadFromPem) {
+            throw new SignatureException('Native signing not available: certificateLoadFromPem not found');
+        }
+        if (!this.native?.signPdfBytes) {
+            throw new SignatureException('Native signing not available: signPdfBytes not found');
+        }
+        const certHandle = this.native.certificateLoadFromPem(certPem, keyPem);
+        if (!certHandle) {
+            throw new SignatureException('Failed to load PEM certificate');
+        }
+        try {
+            const result = this.native.signPdfBytes(pdfData, certHandle, reason ?? null, location ?? null);
+            if (!result)
+                throw new SignatureException('signPdfBytes returned null');
+            return Buffer.from(result);
+        }
+        finally {
+            if (this.native?.pdf_certificate_free) {
+                this.native.pdf_certificate_free(certHandle);
+            }
+        }
+    }
     // Private helpers
     setCached(key, value) {
         this.resultCache.set(key, value);
@@ -1357,8 +1500,10 @@ export class SignatureManager extends EventEmitter {
         }
     }
     clearCachePattern(prefix) {
-        const keysToDelete = Array.from(this.resultCache.keys()).filter(key => key.startsWith(prefix));
-        keysToDelete.forEach(key => this.resultCache.delete(key));
+        const keysToDelete = Array.from(this.resultCache.keys()).filter((key) => key.startsWith(prefix));
+        keysToDelete.forEach((key) => {
+            this.resultCache.delete(key);
+        });
     }
 }
 export default SignatureManager;

package/lib/managers/streams.js

@@ -70,10 +70,16 @@ export class SearchStream extends Readable {
         try {
             // Perform search
             if (this.pageIndex !== undefined) {
-                this._results = (this.searchManager.search(this.searchTerm, this.pageIndex, { caseSensitive: this.caseSensitive, wholeWords: this.wholeWords }) || []);
+                this._results = (this.searchManager.search(this.searchTerm, this.pageIndex, {
+                    caseSensitive: this.caseSensitive,
+                    wholeWords: this.wholeWords,
+                }) || []);
             }
             else {
-                this._results = (this.searchManager.searchAll(this.searchTerm, { caseSensitive: this.caseSensitive, wholeWords: this.wholeWords }) || []);
+                this._results = (this.searchManager.searchAll(this.searchTerm, {
+                    caseSensitive: this.caseSensitive,
+                    wholeWords: this.wholeWords,
+                }) || []);
             }
             // Apply max results limit
             if (this._results && this._results.length > this.maxResults) {

package/lib/managers/xfa-manager.js

@@ -142,7 +142,7 @@ export class XfaManager extends EventEmitter {
     }
     async getFieldValue(fieldName) {
         try {
-            return await this.document?.getXfaFieldValue?.(fieldName) ?? null;
+            return (await this.document?.getXfaFieldValue?.(fieldName)) ?? null;
         }
         catch (error) {
             this.emit('error', error);
@@ -300,21 +300,56 @@ export class XfaManager extends EventEmitter {
     // ===========================================================================
     // Field Creation (from XfaCreationManager)
     // ===========================================================================
-    async addTextField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.TEXT }); }
-    async addNumericField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.NUMERIC }); }
-    async addDateField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.DATE }); }
-    async addCheckboxField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.CHECKBOX }); }
-    async addRadioGroup(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.RADIO }); }
-    async addDropdownField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.DROPDOWN }); }
-    async addSignatureField(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.SIGNATURE }); }
-    async addButton(pageIndex, config) { return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.BUTTON }); }
+    async addTextField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.TEXT });
+    }
+    async addNumericField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.NUMERIC });
+    }
+    async addDateField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.DATE });
+    }
+    async addCheckboxField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.CHECKBOX });
+    }
+    async addRadioGroup(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.RADIO });
+    }
+    async addDropdownField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.DROPDOWN });
+    }
+    async addSignatureField(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.SIGNATURE });
+    }
+    async addButton(pageIndex, config) {
+        return this.addField(pageIndex, { ...config, fieldType: XfaFieldType.BUTTON });
+    }
     async addField(pageIndex, config) {
         try {
             if (!this.formCreated)
                 throw new Error('No XFA form created');
             const fieldId = `xfa_field_${config.name}_${Date.now()}`;
-            await this.document?.addXfaField?.(pageIndex, config.name, config.fieldType, config.x, config.y, config.width, config.height, { caption: config.caption, defaultValue: config.defaultValue, tooltip: config.tooltip, isRequired: config.isRequired, isReadOnly: config.isReadOnly, isHidden: config.isHidden, maxLength: config.maxLength, options: config.options, font: config.font, border: config.border, margin: config.margin, bindingType: config.bindingType, bindingPath: config.bindingPath });
-            const handle = { fieldId, name: config.name, fieldType: config.fieldType, pageIndex };
+            await this.document?.addXfaField?.(pageIndex, config.name, config.fieldType, config.x, config.y, config.width, config.height, {
+                caption: config.caption,
+                defaultValue: config.defaultValue,
+                tooltip: config.tooltip,
+                isRequired: config.isRequired,
+                isReadOnly: config.isReadOnly,
+                isHidden: config.isHidden,
+                maxLength: config.maxLength,
+                options: config.options,
+                font: config.font,
+                border: config.border,
+                margin: config.margin,
+                bindingType: config.bindingType,
+                bindingPath: config.bindingPath,
+            });
+            const handle = {
+                fieldId,
+                name: config.name,
+                fieldType: config.fieldType,
+                pageIndex,
+            };
             this.createdFields.set(fieldId, handle);
             this.emit('field-added', handle);
             return handle;
@@ -374,7 +409,9 @@ export class XfaManager extends EventEmitter {
     // ===========================================================================
     async importXfaData(data, options) {
         try {
-            const result = await this.document?.importXfaData?.(data, options.format, { validate: options.validateOnImport });
+            const result = await this.document?.importXfaData?.(data, options.format, {
+                validate: options.validateOnImport,
+            });
             this.emit('data-imported', { format: options.format });
             return !!result;
         }
@@ -385,7 +422,10 @@ export class XfaManager extends EventEmitter {
     }
     async exportXfaData(options) {
         try {
-            const result = await this.document?.exportXfaData?.(options.format, { includeEmpty: options.includeEmptyFields, includeCalculated: options.includeCalculatedFields });
+            const result = await this.document?.exportXfaData?.(options.format, {
+                includeEmpty: options.includeEmptyFields,
+                includeCalculated: options.includeCalculatedFields,
+            });
             this.emit('data-exported', { format: options.format });
             return result ?? null;
         }
@@ -396,7 +436,7 @@ export class XfaManager extends EventEmitter {
     }
     async exportAsXdp() {
         try {
-            return await this.document?.exportXfaAsXdp?.() ?? null;
+            return (await this.document?.exportXfaAsXdp?.()) ?? null;
         }
         catch (error) {
             this.emit('error', error);
@@ -455,18 +495,28 @@ export class XfaManager extends EventEmitter {
     // ===========================================================================
     async validateForm() {
         try {
-            return await this.document?.validateXfaForm?.() ?? { valid: true, issues: [] };
+            return (await this.document?.validateXfaForm?.()) ?? { valid: true, issues: [] };
         }
         catch (error) {
             this.emit('error', error);
             return { valid: false, issues: [error instanceof Error ? error.message : 'Unknown error'] };
         }
     }
-    getCreatedFields() { return Array.from(this.createdFields.values()); }
-    hasForm() { return this.formCreated || this.hasXfa(); }
-    clearCache() { this.cache.clear(); }
+    getCreatedFields() {
+        return Array.from(this.createdFields.values());
+    }
+    hasForm() {
+        return this.formCreated || this.hasXfa();
+    }
+    clearCache() {
+        this.cache.clear();
+    }
     getCacheStats() {
-        return { cacheSize: this.cache.size, maxCacheSize: this.maxCacheSize, entries: Array.from(this.cache.keys()) };
+        return {
+            cacheSize: this.cache.size,
+            maxCacheSize: this.maxCacheSize,
+            entries: Array.from(this.cache.keys()),
+        };
     }
     destroy() {
         this.createdFields.clear();

package/lib/native-loader.d.ts

@@ -0,0 +1,7 @@
+type NativeModule = Record<string, any>;
+/**
+ * Returns the loaded native module, loading it on first call. Throws if the
+ * prebuilt .node is missing and the development fallback also fails.
+ */
+export declare function getNative(): NativeModule;
+export {};

package/lib/native-loader.js

@@ -0,0 +1,62 @@
+// Shared loader for the pdf-oxide native N-API module.
+//
+// The top-level index.ts owns the primary load, but standalone classes like
+// Timestamp and TsaClient need access too. Rather than plumb the module
+// object through every constructor, both files import `getNative()` here.
+//
+// The loader resolves the prebuilt .node via the same prebuilds/<triple>
+// layout index.ts uses, with fallbacks for development builds.
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { arch, platform } from 'node:process';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+let cached = null;
+function prebuildPath() {
+    const paths = {
+        darwin: {
+            x64: '../prebuilds/darwin-x64/pdf_oxide.node',
+            arm64: '../prebuilds/darwin-arm64/pdf_oxide.node',
+        },
+        linux: {
+            x64: '../prebuilds/linux-x64/pdf_oxide.node',
+            arm64: '../prebuilds/linux-arm64/pdf_oxide.node',
+        },
+        win32: {
+            x64: '../prebuilds/win32-x64/pdf_oxide.node',
+        },
+    };
+    const plat = paths[platform];
+    const rel = plat?.[arch];
+    if (!rel) {
+        throw new Error(`Unsupported platform: ${platform}/${arch}`);
+    }
+    return join(__dirname, rel);
+}
+/**
+ * Returns the loaded native module, loading it on first call. Throws if the
+ * prebuilt .node is missing and the development fallback also fails.
+ */
+export function getNative() {
+    if (cached)
+        return cached;
+    try {
+        cached = require(prebuildPath());
+    }
+    catch (e) {
+        if (process.env.NODE_ENV === 'development' || process.env.NAPI_DEV) {
+            try {
+                cached = require('../build/Release/pdf_oxide.node');
+            }
+            catch {
+                throw e;
+            }
+        }
+        else {
+            throw e;
+        }
+    }
+    return cached;
+}

package/lib/native.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared loader for the pdf-oxide N-API addon.
+ *
+ * Extracted so that modules which can't import from `./index.ts`
+ * (due to the index ↔ editor / builder cycle) can still reach the
+ * addon through the same prebuild-aware resolver. The published
+ * package ships a platform-specific `.node` file under
+ * `prebuilds/<triple>/`; loading the addon through this helper is
+ * what makes `DocumentEditor` / `DocumentBuilder` work for consumers
+ * installed from npm (where `build/Release/` does not exist).
+ *
+ * In development mode (`NODE_ENV=development` or `NAPI_DEV` set), we
+ * fall back to `../build/Release/pdf_oxide.node` — the node-gyp
+ * output that in-tree tests run against.
+ */
+export declare function loadNative(): any;