@ironsoftware/ironpdf 2026.5.1 → 2026.7.2

package/src/public/pdfDocument.ts

@@ -67,7 +67,10 @@ import {mergePdfs, renderHtmlToPdf, renderHtmlZipToPdf, renderUrlToPdf, renderHt
 import {disposePdf, getBinaryData, openPdfFileBuffer} from "../internal/grpc_layer/pdfium/io";
 import {Access} from "../internal/access";
 import {renderImagesBufferToPdf, renderImagesFilesToPdf} from "../internal/grpc_layer/chrome/image";
-import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree} from "../internal/grpc_layer/pdfium/compress";
+import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree, compressAndSaveAsAdvanced, compressAndSaveAsAdvancedFromBytes} from "../internal/grpc_layer/pdfium/compress";
+import {disableFormFontFallback, setFormFont} from "../internal/grpc_layer/pdfium/form";
+import {AdvancedCompressionOptions} from "./compression";
+import * as path from "path";
 import {
 	isLinearizedFromBytes,
 	linearizeCoreFromBytes,
@@ -88,11 +91,11 @@ import {
 	setPageRotation
 } from "../internal/grpc_layer/pdfium/page";
 import {extractRawImages, rasterizeToImageBuffers} from "../internal/grpc_layer/pdfium/image";
-import Jimp from "jimp";
+import {transcodeImage, writeImageFile} from "../internal/image_codec";
 import {extractAllText, replaceText} from "../internal/grpc_layer/pdfium/text";
 import {PdfAVersions, PdfUAVersions, toPdfA, toPdfUA, toPdfUAForScreenReader} from "../internal/grpc_layer/pdfium/pdfa";
 import {getMetadataDict, removeMetadata, setMetadata, setMetadataDict} from "../internal/grpc_layer/pdfium/metadata";
-import {getSignatureCount, getVerifiedSignatures, signPdf} from "../internal/grpc_layer/pdfium/signing";
+import {getSignatureCount, getVerifiedSignatures, PendingSignature, resolveCertificateBuffer, signPdf} from "../internal/grpc_layer/pdfium/signing";
 import {addHtmlAffix, addTextAffix} from "../internal/grpc_layer/pdfium/headerFooter";
 import {stampBarcode, stampHtml, stampImage, stampText} from "../internal/grpc_layer/chrome/stamp";
 import {addBackgroundForeground} from "../internal/grpc_layer/pdfium/BackgroundForeground";
@@ -471,6 +474,117 @@ export class PdfDocument{
 			(filePath, imageQuality);
 	}
 
+	/**
+	 * Apply the advanced compression pipeline and save the result to a file.
+	 *
+	 * Combines pdfium-side image DPI downsampling with qpdf-side structural
+	 * optimization in a single call.
+	 *
+	 * @param filePath the file path to save the compressed PDF
+	 * @param options  advanced compression options; pass an empty object `{}` to
+	 *                 reproduce the legacy compressAndSaveAs behaviour with no
+	 *                 image downsampling
+	 * @param password the PDF password (empty string if none)
+	 */
+	public async compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		return this.internal_compressAndSaveAsAdvanced(filePath, options, password);
+	}
+
+	/**
+	 * Apply the advanced compression pipeline to byte[] input and save the
+	 * compressed result to a file. Returns the compressed bytes as well.
+	 */
+	public static async compressAndSaveAsAdvancedFromBytes(
+		pdfBytes: Buffer,
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<Buffer> {
+		if (!pdfBytes || pdfBytes.length === 0) {
+			throw new Error("pdfBytes must not be null or empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		return compressAndSaveAsAdvancedFromBytes(pdfBytes, filePath, options, password ?? "");
+	}
+
+	//#endregion
+
+	//#region form (PDF-2184)
+
+	/**
+	 * Set the document-wide form font for subsequent form-field fills. When
+	 * set, the engine skips its automatic Tahoma/Arial fallback embed for
+	 * non-ASCII form values and registers the supplied font in the AcroForm
+	 * /DR /Font dictionary so default-appearance strings resolve correctly
+	 * at render time.
+	 *
+	 * File-size impact:
+	 * - Name-only mode (`fontData` omitted or empty): zero bytes added; the
+	 *   font must already be in the document.
+	 * - Bytes mode and the font is already embedded with usable glyph data:
+	 *   zero bytes added.
+	 * - Bytes mode and the font is missing or has no glyph data: the full
+	 *   font is embedded.
+	 * - Bytes mode with `forceEmbed = true`: a fresh font copy is added
+	 *   alongside any existing copy; the document grows on every call.
+	 *
+	 * @param fontName   PDF font name to register (e.g. "Poppins-Regular").
+	 *                   Allowed characters: letters, digits, `_`, `-`, `.`, `+`.
+	 * @param fontData   Raw TrueType/OpenType bytes; pass `undefined` or an
+	 *                   empty Buffer for name-only mode.
+	 * @param forceEmbed When true, embed `fontData` even if a font with the
+	 *                   same name and usable glyph data is already present.
+	 */
+	public async setFormFont(
+		fontName: string,
+		fontData?: Buffer,
+		forceEmbed = false
+	): Promise<void> {
+		return setFormFont(await this.internal_getId(), fontName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Load a TrueType/OpenType font from disk and apply it as the
+	 * document-wide form font. The PDF font name is derived from the file
+	 * name (without extension) when `fontName` is omitted.
+	 *
+	 * @param fontFilePath Path to a TTF/OTF/TTC font file
+	 * @param fontName     Optional PDF font name. When omitted the file name
+	 *                     (without extension) is used.
+	 * @param forceEmbed   When true, embed even if the font is already present.
+	 */
+	public async setFormFontFromFile(
+		fontFilePath: string,
+		fontName?: string,
+		forceEmbed = false
+	): Promise<void> {
+		if (!fontFilePath) {
+			throw new Error("fontFilePath must not be empty");
+		}
+		const fontData = fs.readFileSync(fontFilePath);
+		const resolvedName = fontName ?? deriveFontNameFromPath(fontFilePath);
+		return setFormFont(await this.internal_getId(), resolvedName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Suppress the automatic Tahoma/Arial fallback embed for non-ASCII form
+	 * values without registering any replacement font. Use when zero
+	 * file-size growth is required and the template's existing font
+	 * references are sufficient for the values being filled.
+	 *
+	 * Rendering of non-ASCII characters then depends entirely on the
+	 * viewer's font substitution.
+	 */
+	public async disableFormFontFallback(): Promise<void> {
+		return disableFormFontFallback(await this.internal_getId());
+	}
+
 	//#endregion
 
 	//#region linearize
@@ -1378,6 +1492,13 @@ export class PdfDocument{
 	 * @private
 	 */
 	private pdfPassword?: PdfPassword | undefined;
+	/**
+	 * Digital signatures whose placeholder fields have been added (via
+	 * {@link signDigitalSignature}) but still need to be cryptographically finalized when the
+	 * document is saved. See {@link internal_saveAsBuffer}.
+	 * @private
+	 */
+	private pendingSignatures: PendingSignature[] = [];
 
 	/**
 	 * Create a PdfDocument object from a {@link PdfInput}
@@ -1746,7 +1867,7 @@ export class PdfDocument{
 	 * @param saveOptions see {@link SaveOptions}
 	 */
 	private async internal_saveAsBuffer(saveOptions?: SaveOptions | undefined): Promise<Buffer> {
-		return getBinaryData(await this.internal_getId(), saveOptions);
+		return getBinaryData(await this.internal_getId(), saveOptions, this.pendingSignatures);
 	}
 
 	//#endregion
@@ -1839,6 +1960,34 @@ export class PdfDocument{
 		);
 	}
 
+	private async internal_compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		if (!filePath || filePath.trim().length === 0) {
+			throw new Error("filePath must not be empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		if (
+			options.jpegQuality !== undefined &&
+			options.jpegQuality !== null &&
+			(options.jpegQuality < 1 || options.jpegQuality > 100)
+		) {
+			throw new Error(
+				`Invalid jpegQuality (${options.jpegQuality}). Must be between 1 and 100.`
+			);
+		}
+		return await compressAndSaveAsAdvanced(
+			await this.internal_getId(),
+			filePath,
+			options,
+			password ?? ""
+		);
+	}
+
 	//#endregion
 
 	//#region linearize
@@ -2119,25 +2268,7 @@ export class PdfDocument{
 			await this.internal_getId(),
 			options?.fromPages ?? "all"
 		);
-		const jimpImageType: "image/bmp" | "image/png" | "image/jpeg" = (() => {
-			switch (options?.imageType) {
-				case ImageType.BMP:
-					return Jimp.MIME_BMP;
-				case ImageType.PNG:
-					return Jimp.MIME_PNG;
-				case ImageType.JPG:
-					return Jimp.MIME_JPEG;
-				default:
-					return Jimp.MIME_PNG;
-			}
-		})();
-		return Promise.all(
-			images.map(async (imageBuffer) => {
-				//convert output type
-				const jimp = await Jimp.read(imageBuffer);
-				return await jimp.getBufferAsync(jimpImageType);
-			})
-		);
+		return images.map((imageBuffer) => transcodeImage(imageBuffer, options?.imageType));
 	}
 
 	/**
@@ -2169,9 +2300,7 @@ export class PdfDocument{
 
 		const promises = images.map(async (imageBuffer, index) => {
 			const outputFileName = getFileName(filePath,index.toString(),getImageExtType(options?.type),"image");
-			await Jimp.read(imageBuffer).then((value) => {
-				return value.write(outputFileName);
-			});
+			await writeImageFile(imageBuffer, outputFileName, options?.type);
 			return outputFileName;
 		});
 
@@ -2273,7 +2402,64 @@ export class PdfDocument{
 	 * @param signature see {@link DigitalSignature}
 	 */
 	private async internal_signDigitalSignature(signature: DigitalSignature) {
-		return await signPdf(await this.internal_getId(), signature);
+		// Resolve the certificate up-front: signing finalizes at save time and the certificate
+		// has to be re-sent then (see internal_saveAsBuffer / getBinaryData). If we cannot resolve
+		// it we must fail before reserving a placeholder on the engine, otherwise we would be left
+		// with an un-fillable placeholder that silently produces an invalid signature on save.
+		const certificate = resolveCertificateBuffer(signature);
+		if (!certificate) {
+			throw new Error(
+				"A signing certificate is required: provide either certificatePath or certificateBuffer."
+			);
+		}
+
+		// Multiple signatures cannot be finalized in a single save: filling a later signature's
+		// placeholder rewrites bytes that an earlier signature already covers, which invalidates
+		// the earlier one. So whenever a signature from a previous signDigitalSignature() call is
+		// still pending, finalize it first (save + re-open) so the new signature is applied as a
+		// separate revision. This is the sign -> save -> re-open -> sign flow done transparently,
+		// and it keeps every signature valid.
+		await this.internal_finalizePendingSignatures();
+
+		// Reuse the already-resolved certificate so signPdf does not read the file a second time.
+		const index = await signPdf(await this.internal_getId(), {
+			...signature,
+			certificateBuffer: certificate,
+		});
+
+		// The signature field is only a placeholder until the document is saved. Remember the
+		// certificate so it can be re-sent to finalize the signing in internal_saveAsBuffer().
+		// At most one signature is ever pending here (earlier ones have already been finalized
+		// above), so each save only ever finalizes a single signature.
+		this.pendingSignatures.push({
+			index,
+			password: signature.certificatePassword ?? "",
+			timeStampUrl: signature.timeStampUrl ?? "",
+			certificate,
+		});
+	}
+
+	/**
+	 * Finalizes any currently-pending digital signatures into the document by saving it (which
+	 * fills the reserved placeholders) and re-opening the result, then swapping in the new
+	 * engine-side document. This isolates each signature in its own revision so that adding a
+	 * further signature does not invalidate the previous ones. No-op when nothing is pending.
+	 * @private
+	 */
+	private async internal_finalizePendingSignatures(): Promise<void> {
+		if (this.pendingSignatures.length === 0) {
+			return;
+		}
+		const finalized = await getBinaryData(
+			await this.internal_getId(),
+			undefined,
+			this.pendingSignatures
+		);
+		this.pendingSignatures = [];
+		this.pdfDocumentId = await openPdfFileBuffer(finalized, {
+			userPassword: this.pdfPassword?.userPassword,
+			ownerPassword: this.pdfPassword?.ownerPassword,
+		});
 	}
 
 	/**
@@ -2295,7 +2481,10 @@ export class PdfDocument{
 	 * Get all verified digital signatures from this PdfDocument.
 	 */
 	private async internal_getVerifiedSignatures(): Promise<VerifiedSignature[]> {
-		return await getVerifiedSignatures(await this.internal_getId());
+		// Verify against the finalized document bytes (including any pending signatures that are
+		// only applied at save time), otherwise the engine re-saves and invalidates the signature.
+		const data = await this.internal_saveAsBuffer();
+		return await getVerifiedSignatures(await this.internal_getId(), data);
 	}
 
 	//#endregion
@@ -2570,3 +2759,14 @@ export class PdfDocument{
 
 	//#endregion
 }
+
+/**
+ * Derive a PDF font name from a font file path: strip the directory and the
+ * extension. Used by {@link PdfDocument.setFormFontFromFile} when no
+ * explicit name is supplied.
+ */
+function deriveFontNameFromPath(fontFilePath: string): string {
+	const base = path.basename(fontFilePath);
+	const dot = base.lastIndexOf(".");
+	return dot > 0 ? base.substring(0, dot) : base;
+}