@shad0wz7/nestjs-pdf 4.0.0 → 5.0.0

package/dist/index.cjs

@@ -3,14 +3,12 @@ let node_path = require("node:path");
 let _nestjs_common = require("@nestjs/common");
 let pdf_lib = require("pdf-lib");
 let deepmerge_ts = require("deepmerge-ts");
-let node_dns_promises = require("node:dns/promises");
 let node_fs = require("node:fs");
+let node_dns_promises = require("node:dns/promises");
 let node_net = require("node:net");
 let node_url = require("node:url");
-let puppeteer = require("puppeteer");
-let _puppeteer_browsers = require("@puppeteer/browsers");
 let node_module = require("node:module");
-//#region src/exceptions/nestjs-pdf.exception.ts
+// src/exceptions/nestjs-pdf.exception.ts
 let NestjsPdfErrorCode = /* @__PURE__ */ function(NestjsPdfErrorCode) {
 	NestjsPdfErrorCode["ENGINE_NOT_AVAILABLE"] = "ENGINE_NOT_AVAILABLE";
 	NestjsPdfErrorCode["TEMPLATE_CONFIGURATION_ERROR"] = "TEMPLATE_CONFIGURATION_ERROR";
@@ -21,6 +19,7 @@ let NestjsPdfErrorCode = /* @__PURE__ */ function(NestjsPdfErrorCode) {
 	NestjsPdfErrorCode["SIGNATURE_DEPENDENCY_ERROR"] = "SIGNATURE_DEPENDENCY_ERROR";
 	NestjsPdfErrorCode["SIGNATURE_PLACEMENT_ERROR"] = "SIGNATURE_PLACEMENT_ERROR";
 	NestjsPdfErrorCode["WATERMARK_ERROR"] = "WATERMARK_ERROR";
+	NestjsPdfErrorCode["RENDERER_CONFIGURATION_ERROR"] = "RENDERER_CONFIGURATION_ERROR";
 	return NestjsPdfErrorCode;
 }({});
 var NestjsPdfException = class extends Error {
@@ -29,46 +28,43 @@ var NestjsPdfException = class extends Error {
 		this.name = this.constructor.name;
 	}
 };
-//#endregion
-//#region src/exceptions/browser-installation.exception.ts
+// src/exceptions/browser-installation.exception.ts
 var BrowserInstallationException = class extends NestjsPdfException {
 	code = "BROWSER_INSTALLATION_ERROR";
 };
-//#endregion
-//#region src/exceptions/browser-unavailable.exception.ts
+// src/exceptions/browser-unavailable.exception.ts
 var BrowserUnavailableException = class extends NestjsPdfException {
 	code = "BROWSER_UNAVAILABLE";
 };
-//#endregion
-//#region src/exceptions/engine-not-available.exception.ts
+// src/exceptions/engine-not-available.exception.ts
 var EngineNotAvailableException = class extends NestjsPdfException {
 	code = "ENGINE_NOT_AVAILABLE";
 	constructor(engineName, packageName, options) {
 		super(packageName ? `${engineName} engine is not available: the '${packageName}' package is not installed. Run \`npm install ${packageName}\` to use it.` : `${engineName} service is not available. If the problem persists, open an issue in the repo.`, options);
 	}
 };
-//#endregion
-//#region src/exceptions/pdf-generation.exception.ts
+// src/exceptions/pdf-generation.exception.ts
 var PdfGenerationException = class extends NestjsPdfException {
 	code = "PDF_GENERATION_ERROR";
 };
-//#endregion
-//#region src/exceptions/signature-dependency.exception.ts
+// src/exceptions/renderer-configuration.exception.ts
+/** The PDF provider is misconfigured, or asked for an option it does not support. */
+var RendererConfigurationException = class extends NestjsPdfException {
+	code = "RENDERER_CONFIGURATION_ERROR";
+};
+// src/exceptions/signature-dependency.exception.ts
 var SignatureDependencyException = class extends NestjsPdfException {
 	code = "SIGNATURE_DEPENDENCY_ERROR";
 };
-//#endregion
-//#region src/exceptions/signature-placement.exception.ts
+// src/exceptions/signature-placement.exception.ts
 var SignaturePlacementException = class extends NestjsPdfException {
 	code = "SIGNATURE_PLACEMENT_ERROR";
 };
-//#endregion
-//#region src/exceptions/template-configuration.exception.ts
+// src/exceptions/template-configuration.exception.ts
 var TemplateConfigurationException = class extends NestjsPdfException {
 	code = "TEMPLATE_CONFIGURATION_ERROR";
 };
-//#endregion
-//#region src/exceptions/template-render.exception.ts
+// src/exceptions/template-render.exception.ts
 var TemplateRenderException = class extends NestjsPdfException {
 	engine;
 	code = "TEMPLATE_RENDER_ERROR";
@@ -77,13 +73,11 @@ var TemplateRenderException = class extends NestjsPdfException {
 		this.engine = engine;
 	}
 };
-//#endregion
-//#region src/exceptions/watermark.exception.ts
+// src/exceptions/watermark.exception.ts
 var WatermarkException = class extends NestjsPdfException {
 	code = "WATERMARK_ERROR";
 };
-//#endregion
-//#region src/helpers/getRelativePath.helper.ts
+// src/helpers/getRelativePath.helper.ts
 /**
 * Get the relative path to a value from the module directory.
 * @param moduleDir the path of the module, typically __dirname
@@ -97,8 +91,7 @@ function getRelativePathToValue(moduleDir, relativeToModule) {
 	const fullTemplatePath = (0, node_path.resolve)(moduleDir, relativeToModule);
 	return (0, node_path.relative)(process.cwd(), fullTemplatePath);
 }
-//#endregion
-//#region src/helpers/signature.helper.ts
+// src/helpers/signature.helper.ts
 let pdfjsPromise;
 async function loadPdfjs() {
 	if (!pdfjsPromise) try {
@@ -241,8 +234,7 @@ async function addSignatureFieldUsingAnchor(pdf, fieldName = "SignatureDebtor",
 	}
 	return await pdfDoc.save();
 }
-//#endregion
-//#region src/helpers/watermark.helper.ts
+// src/helpers/watermark.helper.ts
 const DEFAULT_OPACITY = .15;
 const DEFAULT_ROTATION = 45;
 const DEFAULT_FONT_SIZE = 60;
@@ -385,8 +377,7 @@ async function addWatermark(pdf, options) {
 		throw new WatermarkException(`Failed to add watermark: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 }
-//#endregion
-//#region node_modules/.pnpm/yocto-queue@1.2.2/node_modules/yocto-queue/index.js
+// node_modules/.pnpm/yocto-queue@1.2.2/node_modules/yocto-queue/index.js
 var Node = class {
 	value;
 	next;
@@ -443,8 +434,7 @@ var Queue = class {
 		while (this.#head) yield this.dequeue();
 	}
 };
-//#endregion
-//#region node_modules/.pnpm/p-limit@7.3.3/node_modules/p-limit/index.js
+// node_modules/.pnpm/p-limit@7.3.3/node_modules/p-limit/index.js
 function pLimit(concurrency) {
 	let rejectOnClear = false;
 	if (typeof concurrency === "object") ({concurrency, rejectOnClear = false} = concurrency);
@@ -522,14 +512,296 @@ function pLimit(concurrency) {
 function validateConcurrency(concurrency) {
 	if (!((Number.isInteger(concurrency) || concurrency === Number.POSITIVE_INFINITY) && concurrency > 0)) throw new TypeError("Expected `concurrency` to be a number from 1 and up");
 }
-//#endregion
-//#region src/helpers/deepMergePdfparams.ts
+// src/helpers/deepMergePdfparams.ts
 function mergePuppeteerParameters(defaults, overrides) {
 	if (!overrides) return { ...defaults };
 	return (0, deepmerge_ts.deepmerge)(defaults, overrides);
 }
-//#endregion
-//#region src/helpers/request-guard.helper.ts
+// src/helpers/tokens.ts
+const PDF_PARAMETERS = "PDF_PARAMETERS";
+// src/renderers/pdf-renderer.interface.ts
+const PDF_RENDERER = "PDF_RENDERER";
+// src/renderers/http.utils.ts
+const MAX_ERROR_BODY_LENGTH = 500;
+/** Builds a `PdfGenerationException` from a failed HTTP response, body included. */
+async function httpError(provider, response) {
+	let body = "";
+	try {
+		body = (await response.text()).trim().slice(0, MAX_ERROR_BODY_LENGTH);
+	} catch {}
+	return new PdfGenerationException(`${provider} responded with HTTP ${response.status}${body ? `: ${body}` : ""}`);
+}
+/** Remote providers render on another machine: the local request guard cannot run there. */
+function assertNoRequestGuard(provider, options, hint) {
+	if (options.security) throw new RendererConfigurationException(`The 'security' option is only supported by the puppeteer provider, not by ${provider}. ${hint}`);
+}
+function requireNonEmpty(value, name, provider) {
+	if (!value?.trim()) throw new RendererConfigurationException(`The ${provider} provider requires a non-empty '${name}'`);
+	return value;
+}
+// src/renderers/pdf-options.mapper.ts
+/** Paper sizes in inches, as Puppeteer defines them. */
+const PAPER_FORMATS = {
+	letter: {
+		width: 8.5,
+		height: 11
+	},
+	legal: {
+		width: 8.5,
+		height: 14
+	},
+	tabloid: {
+		width: 11,
+		height: 17
+	},
+	ledger: {
+		width: 17,
+		height: 11
+	},
+	a0: {
+		width: 33.1102,
+		height: 46.811
+	},
+	a1: {
+		width: 23.3858,
+		height: 33.1102
+	},
+	a2: {
+		width: 16.5354,
+		height: 23.3858
+	},
+	a3: {
+		width: 11.6929,
+		height: 16.5354
+	},
+	a4: {
+		width: 8.2677,
+		height: 11.6929
+	},
+	a5: {
+		width: 5.8268,
+		height: 8.2677
+	},
+	a6: {
+		width: 4.1339,
+		height: 5.8268
+	}
+};
+const INCHES_PER_UNIT = {
+	px: 1 / 96,
+	in: 1,
+	cm: 1 / 2.54,
+	mm: 1 / 25.4
+};
+/**
+* Converts a Puppeteer length (a number of pixels, or a string with a
+* `px`/`in`/`cm`/`mm` unit) to inches.
+*/
+function toInches(value) {
+	if (typeof value === "number") return value * INCHES_PER_UNIT.px;
+	const match = /^\s*(-?\d*\.?\d+)\s*(px|in|cm|mm)?\s*$/i.exec(value);
+	if (!match) throw new RendererConfigurationException(`Invalid length '${value}': expected a number of pixels or a value in px, in, cm or mm`);
+	const unit = (match[2] ?? "px").toLowerCase();
+	return Number(match[1]) * INCHES_PER_UNIT[unit];
+}
+function formatInches(inches) {
+	return String(Math.round(inches * 1e4) / 1e4);
+}
+function resolvePrintLayout(pdfOptions) {
+	let width;
+	let height;
+	if (pdfOptions.width !== void 0 || pdfOptions.height !== void 0) {
+		const fallback = PAPER_FORMATS.letter;
+		width = pdfOptions.width === void 0 ? fallback.width : toInches(pdfOptions.width);
+		height = pdfOptions.height === void 0 ? fallback.height : toInches(pdfOptions.height);
+	} else {
+		const formatName = (pdfOptions.format ?? "letter").toLowerCase();
+		const format = PAPER_FORMATS[formatName];
+		if (!format) throw new RendererConfigurationException(`Unknown paper format '${pdfOptions.format}'`);
+		({width, height} = format);
+	}
+	const margin = {};
+	for (const side of [
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]) {
+		const value = pdfOptions.margin?.[side];
+		if (value !== void 0) margin[side] = toInches(value);
+	}
+	return {
+		width,
+		height,
+		margin
+	};
+}
+function toHtmlDocument(template) {
+	return /<html[\s>]/i.test(template) ? template : `<!DOCTYPE html><html><head></head><body>${template}</body></html>`;
+}
+function toGotenbergForm(pdfOptions) {
+	const { width, height, margin } = resolvePrintLayout(pdfOptions);
+	const fields = {
+		paperWidth: formatInches(width),
+		paperHeight: formatInches(height),
+		marginTop: formatInches(margin.top ?? 0),
+		marginRight: formatInches(margin.right ?? 0),
+		marginBottom: formatInches(margin.bottom ?? 0),
+		marginLeft: formatInches(margin.left ?? 0),
+		emulatedMediaType: "screen",
+		skipNetworkIdleEvent: "false"
+	};
+	if (pdfOptions.landscape !== void 0) fields.landscape = String(pdfOptions.landscape);
+	if (pdfOptions.printBackground !== void 0) fields.printBackground = String(pdfOptions.printBackground);
+	if (pdfOptions.omitBackground !== void 0) fields.omitBackground = String(pdfOptions.omitBackground);
+	if (pdfOptions.scale !== void 0) fields.scale = String(pdfOptions.scale);
+	if (pdfOptions.pageRanges) fields.nativePageRanges = pdfOptions.pageRanges;
+	if (pdfOptions.preferCSSPageSize !== void 0) fields.preferCssPageSize = String(pdfOptions.preferCSSPageSize);
+	if (pdfOptions.tagged !== void 0) fields.generateTaggedPdf = String(pdfOptions.tagged);
+	if (pdfOptions.outline !== void 0) fields.generateDocumentOutline = String(pdfOptions.outline);
+	const files = {};
+	if (pdfOptions.displayHeaderFooter) {
+		if (pdfOptions.headerTemplate) files["header.html"] = toHtmlDocument(pdfOptions.headerTemplate);
+		if (pdfOptions.footerTemplate) files["footer.html"] = toHtmlDocument(pdfOptions.footerTemplate);
+	}
+	return {
+		fields,
+		files
+	};
+}
+function toApi2PdfOptions(pdfOptions) {
+	const { width, height, margin } = resolvePrintLayout(pdfOptions);
+	const options = {
+		width: `${formatInches(width)}in`,
+		height: `${formatInches(height)}in`,
+		marginTop: `${formatInches(margin.top ?? 0)}in`,
+		marginRight: `${formatInches(margin.right ?? 0)}in`,
+		marginBottom: `${formatInches(margin.bottom ?? 0)}in`,
+		marginLeft: `${formatInches(margin.left ?? 0)}in`,
+		usePrintCss: false
+	};
+	for (const key of [
+		"landscape",
+		"printBackground",
+		"omitBackground",
+		"scale",
+		"pageRanges",
+		"displayHeaderFooter",
+		"headerTemplate",
+		"footerTemplate"
+	]) if (pdfOptions[key] !== void 0) options[key] = pdfOptions[key];
+	return options;
+}
+// src/renderers/api2pdf.renderer.ts
+const PROVIDER$1 = "Api2Pdf";
+const DEFAULT_BASE_URL = "https://v2.api2pdf.com";
+const ROUTE$1 = "/chrome/pdf/html";
+function isApi2Pdf(data) {
+	return typeof data === "object" && data !== null && ("Success" in data || "Error" in data || "FileUrl" in data);
+}
+var Api2PdfRenderer = class {
+	#endpoint;
+	#headers;
+	constructor(provider) {
+		const apiKey = requireNonEmpty(provider.apiKey, "apiKey", PROVIDER$1);
+		const baseUrl = requireNonEmpty(provider.baseUrl ?? DEFAULT_BASE_URL, "baseUrl", PROVIDER$1).replace(/\/+$/, "");
+		this.#endpoint = `${baseUrl}${ROUTE$1}?outputBinary=true`;
+		this.#headers = {
+			...provider.headers,
+			Authorization: apiKey,
+			"Content-Type": "application/json",
+			Accept: "application/pdf, application/json"
+		};
+	}
+	async render(html, options, signal) {
+		assertNoRequestGuard(PROVIDER$1, options, "Only render trusted HTML with a remote provider.");
+		const body = {
+			html,
+			inline: false,
+			options: {
+				...toApi2PdfOptions(options.pdfOptions ?? { format: "A4" }),
+				...options.api2pdfOptions?.options
+			}
+		};
+		if (options.api2pdfOptions?.fileName) body.fileName = options.api2pdfOptions.fileName;
+		const response = await fetch(this.#endpoint, {
+			method: "POST",
+			headers: this.#headers,
+			body: JSON.stringify(body),
+			signal
+		});
+		if (!response.ok) throw await httpError(PROVIDER$1, response);
+		if (!response.headers.get("content-type")?.includes("application/json")) return new Uint8Array(await response.arrayBuffer());
+		const result = await response.json();
+		if (!isApi2Pdf(result)) throw new PdfGenerationException(`${PROVIDER$1} returned an unexpected response: ${JSON.stringify(result)}`);
+		if (result.Success === false || !result.FileUrl) throw new PdfGenerationException(`${PROVIDER$1} could not generate the PDF: ${result.Error ?? "no file returned"}`);
+		const file = await fetch(result.FileUrl, { signal });
+		if (!file.ok) throw await httpError(PROVIDER$1, file);
+		return new Uint8Array(await file.arrayBuffer());
+	}
+};
+// src/renderers/gotenberg.renderer.ts
+const PROVIDER = "Gotenberg";
+const ROUTE = "/forms/chromium/convert/html";
+var GotenbergRenderer = class {
+	#endpoint;
+	#headers;
+	constructor(provider) {
+		const url = requireNonEmpty(provider.url, "url", PROVIDER);
+		this.#endpoint = `${url.replace(/\/+$/, "")}${ROUTE}`;
+		this.#headers = { ...provider.headers };
+		if (provider.basicAuth) {
+			const { username, password } = provider.basicAuth;
+			this.#headers.Authorization = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+		}
+	}
+	async render(html, options, signal) {
+		assertNoRequestGuard(PROVIDER, options, "Restrict outbound requests on the Gotenberg server instead, with '--chromium-allow-list' / '--chromium-deny-list'.");
+		const { fields, files } = toGotenbergForm(options.pdfOptions ?? { format: "A4" });
+		const form = new FormData();
+		form.append("files", new Blob([html], { type: "text/html" }), "index.html");
+		for (const [name, content] of Object.entries(files)) form.append("files", new Blob([content], { type: "text/html" }), name);
+		for (const asset of options.gotenbergOptions?.assets ?? []) form.append("files", new Blob([asset.content], { type: asset.contentType ?? "application/octet-stream" }), asset.filename);
+		const allFields = {
+			...fields,
+			...options.gotenbergOptions?.formFields
+		};
+		for (const [name, value] of Object.entries(allFields)) form.append(name, value);
+		const response = await fetch(this.#endpoint, {
+			method: "POST",
+			headers: this.#headers,
+			body: form,
+			signal
+		});
+		if (!response.ok) throw await httpError(PROVIDER, response);
+		return new Uint8Array(await response.arrayBuffer());
+	}
+};
+// src/puppeteer/libs/loadPuppeteer.utils.ts
+function isMissingPackage(error, packageName) {
+	const { code, message } = error;
+	return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && typeof message === "string" && message.includes(`'${packageName}'`);
+}
+/** Imports an optional peer dependency, turning "not installed" into a clear exception. */
+async function loadOptional(packageName, importer) {
+	try {
+		return await importer();
+	} catch (error) {
+		if (isMissingPackage(error, packageName)) throw new EngineNotAvailableException("Puppeteer", packageName, { cause: error });
+		throw error;
+	}
+}
+/**
+* Puppeteer is an optional peer dependency, only needed by the `puppeteer`
+* provider: it is imported on first use, never when the library loads.
+*/
+function loadPuppeteer() {
+	return loadOptional("puppeteer", () => import("puppeteer"));
+}
+function loadPuppeteerBrowsers() {
+	return loadOptional("@puppeteer/browsers", () => import("@puppeteer/browsers"));
+}
+// src/helpers/request-guard.helper.ts
 const blockedRanges = new node_net.BlockList();
 for (const [address, prefix] of [
 	["0.0.0.0", 8],
@@ -657,8 +929,9 @@ function describe(rawUrl) {
 * and closes the pop-ups a script could open to escape the filter.
 */
 async function installRequestGuard(context, page, options) {
+	const { TargetType } = await loadPuppeteer();
 	context.on("targetcreated", (target) => {
-		if (target.type() === puppeteer.TargetType.PAGE && target.opener()) target.page().then((popup) => popup?.close()).catch(() => void 0);
+		if (target.type() === TargetType.PAGE && target.opener()) target.page().then((popup) => popup?.close()).catch(() => void 0);
 	});
 	if (options.javascriptEnabled === false) await page.setJavaScriptEnabled(false);
 	await page.setRequestInterception(true);
@@ -676,31 +949,162 @@ async function installRequestGuard(context, page, options) {
 		})().catch(() => void 0);
 	});
 }
-//#endregion
-//#region src/helpers/tokens.ts
-const PDF_PARAMETERS = "PDF_PARAMETERS";
-//#endregion
-//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateMetadata.js
+// src/renderers/puppeteer.renderer.ts
+const DEFAULT_ARGS = [
+	"--autoplay-policy=user-gesture-required",
+	"--disable-background-networking",
+	"--disable-background-timer-throttling",
+	"--disable-backgrounding-occluded-windows",
+	"--disable-breakpad",
+	"--disable-client-side-phishing-detection",
+	"--disable-component-update",
+	"--disable-default-apps",
+	"--disable-dev-shm-usage",
+	"--disable-domain-reliability",
+	"--disable-extensions",
+	"--disable-features=AudioServiceOutOfProcess",
+	"--disable-hang-monitor",
+	"--disable-ipc-flooding-protection",
+	"--disable-notifications",
+	"--disable-offer-store-unmasked-wallet-cards",
+	"--disable-print-preview",
+	"--disable-prompt-on-repost",
+	"--disable-renderer-backgrounding",
+	"--disable-setuid-sandbox",
+	"--disable-speech-api",
+	"--disable-sync",
+	"--hide-scrollbars",
+	"--ignore-gpu-blacklist",
+	"--metrics-recording-only",
+	"--mute-audio",
+	"--no-default-browser-check",
+	"--no-first-run",
+	"--no-pings",
+	"--password-store=basic",
+	"--use-gl=swiftshader",
+	"--use-mock-keychain",
+	"--disable-accelerated-2d-canvas",
+	"--no-zygote",
+	"--disable-gpu"
+];
+const PDF_OPTION_KEYS = {
+	scale: true,
+	displayHeaderFooter: true,
+	headerTemplate: true,
+	footerTemplate: true,
+	printBackground: true,
+	landscape: true,
+	pageRanges: true,
+	format: true,
+	width: true,
+	height: true,
+	preferCSSPageSize: true,
+	margin: true,
+	path: true,
+	omitBackground: true,
+	tagged: true,
+	outline: true,
+	timeout: true,
+	waitForFonts: true
+};
+function toPuppeteerPdfOptions(options) {
+	if (!options) return { format: "A4" };
+	const invalidKeys = Object.keys(options).filter((key) => !Object.hasOwn(PDF_OPTION_KEYS, key));
+	if (invalidKeys.length > 0) throw new RendererConfigurationException(`Invalid PDF options: ${invalidKeys.join(", ")}. Please check the documentation for valid options.`);
+	return options;
+}
+var PuppeteerRenderer = class {
+	#browserService;
+	constructor(browserService) {
+		this.#browserService = browserService;
+	}
+	async render(html, options, signal) {
+		if (options.chromiumRevision !== void 0) _nestjs_common.Logger.warn("Using `chromiumRevision` is no longer supported since the puppeteer update.");
+		const pdfOptions = toPuppeteerPdfOptions(options.pdfOptions);
+		const headless = options.headless ?? true;
+		const executablePath = options.executablePath || void 0;
+		const args = options.extraPuppeteerArgs || DEFAULT_ARGS;
+		let context = null;
+		let closing;
+		const onAbort = () => {
+			if (!context) return;
+			closing = context.close();
+			closing.catch(() => void 0);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			context = await this.#browserService.createContext(args, headless, executablePath);
+			signal?.throwIfAborted();
+			const page = await context.newPage();
+			if (options.security) await installRequestGuard(context, page, options.security);
+			await page.setContent(html, { waitUntil: "domcontentloaded" });
+			await page.emulateMediaType("screen");
+			await page.waitForNetworkIdle({
+				idleTime: 500,
+				timeout: 3e4
+			});
+			/* v8 ignore next */
+			await page.evaluate(() => document.fonts.ready);
+			return await page.pdf(pdfOptions);
+		} finally {
+			signal?.removeEventListener("abort", onAbort);
+			if (context) try {
+				if (closing) await closing;
+				else await context.close();
+			} catch (error) {
+				_nestjs_common.Logger.error(error);
+			}
+		}
+	}
+};
+// src/renderers/create-renderer.ts
+/** True when the PDFs are printed by the local Chromium (the default). */
+function usesPuppeteer(params) {
+	return (params.provider?.type ?? "puppeteer") === "puppeteer";
+}
+function createPdfRenderer(params, browserService) {
+	const provider = params.provider ?? { type: "puppeteer" };
+	switch (provider.type) {
+		case "puppeteer": return new PuppeteerRenderer(browserService);
+		case "gotenberg": return new GotenbergRenderer(provider);
+		case "api2pdf": return new Api2PdfRenderer(provider);
+		default: throw new RendererConfigurationException(`Unknown PDF provider '${String(provider.type)}': expected 'puppeteer', 'gotenberg' or 'api2pdf'`);
+	}
+}
+// src/puppeteer/libs/enum.utils.ts
+/**
+* Converts a string value to an enum member, throwing a RendererConfigurationException if the value is not a valid member of the enum.
+* @param enumObject
+* @param value
+* @param label
+* @throws RendererConfigurationException
+*/
+function toEnumMember(enumObject, value, label) {
+	const members = Object.values(enumObject);
+	const isMember = (candidate) => candidate === value;
+	const member = members.find(isMember);
+	if (member === void 0) throw new RendererConfigurationException(`Unsupported ${label} '${value}': expected one of ${members.map((m) => `'${m}'`).join(", ")}`);
+	return member;
+}
+// \0@oxc-project+runtime@0.156.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-//#endregion
-//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
 	};
 }
-//#endregion
-//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-//#endregion
-//#region src/puppeteer/browser/browser.service.ts
+// src/puppeteer/browser/browser.service.ts
+const DEFAULT_BROWSER = "chromium";
 async function sleep(ms) {
 	await new Promise((r) => setTimeout(r, ms));
 }
@@ -752,7 +1156,7 @@ let BrowserService = class BrowserService {
 		} catch (error) {
 			_nestjs_common.Logger.warn(`Failed to close browser on module destroy: ${error instanceof Error ? error.message : String(error)}`);
 		}
-		if (this.#options?.cleanupBrowserCacheOnExit !== false) await this.#cleanupCacheBestEffort();
+		if (this.#options !== void 0 && usesPuppeteer(this.#options) && this.#options.cleanupBrowserCacheOnExit !== false) await this.#cleanupCacheBestEffort();
 	}
 	/** Wait until no PDF job is in flight, or until the timeout elapses. */
 	async #waitForIdle(timeoutMs) {
@@ -834,11 +1238,12 @@ let BrowserService = class BrowserService {
 		}
 	}
 	async #doInstall(lock) {
-		const browser = this.#browser;
+		const { Browser: BrowserEnum, BrowserPlatform, canDownload, detectBrowserPlatform, install, resolveBuildId } = await loadPuppeteerBrowsers();
+		const browser = toEnumMember(BrowserEnum, this.#browser, "browser");
 		const versionTag = this.#browserTag;
-		const browserPlatform = (0, _puppeteer_browsers.detectBrowserPlatform)() ?? _puppeteer_browsers.BrowserPlatform.LINUX;
+		const browserPlatform = detectBrowserPlatform() ?? BrowserPlatform.LINUX;
 		let buildId;
-		if (this.#buildId === void 0) buildId = await (0, _puppeteer_browsers.resolveBuildId)(browser, browserPlatform, versionTag);
+		if (this.#buildId === void 0) buildId = await resolveBuildId(browser, browserPlatform, versionTag);
 		else buildId = this.#buildId;
 		_nestjs_common.Logger.log(`Browser ${browser} ${versionTag} build id: ${buildId}`, "NestJsPdf");
 		if (await this.hasBrowserInstalled(browser, buildId)) {
@@ -853,9 +1258,9 @@ let BrowserService = class BrowserService {
 				buildId,
 				baseUrl: this.#options?.browserInstallBaseUrl ?? void 0
 			};
-			if (await (0, _puppeteer_browsers.canDownload)(installOption)) {
+			if (await canDownload(installOption)) {
 				_nestjs_common.Logger.log(`Installing ${installOption.browser} ${installOption.buildId}`, "NestJsPdf");
-				const installedBrowser = await (0, _puppeteer_browsers.install)(installOption);
+				const installedBrowser = await install(installOption);
 				if (await this.hasBrowserInstalled(browser, buildId)) {
 					_nestjs_common.Logger.log("Browser installed successfully", "NestJsPdf");
 					if (lock) this.#writeLockFile(browser, buildId);
@@ -866,10 +1271,7 @@ let BrowserService = class BrowserService {
 		return null;
 	}
 	#loadBrowser() {
-		let browser;
-		if (this.#options?.browser === void 0) browser = _puppeteer_browsers.Browser.CHROMIUM;
-		else browser = this.#options.browser;
-		this.#browser = browser;
+		this.#browser = this.#options?.browser ?? DEFAULT_BROWSER;
 	}
 	getBrowser() {
 		return this.#browser;
@@ -877,7 +1279,7 @@ let BrowserService = class BrowserService {
 	#loadBrowserTag() {
 		let versionTag;
 		if (this.#options?.browserTag === void 0) {
-			if (this.#browser === _puppeteer_browsers.Browser.CHROMIUM) versionTag = "latest";
+			if (this.#browser === DEFAULT_BROWSER) versionTag = "latest";
 			else versionTag = "stable";
 		} else versionTag = this.#options.browserTag;
 		this.#browserTag = versionTag;
@@ -904,21 +1306,24 @@ let BrowserService = class BrowserService {
 		this.#useLockedBrowser = useLockedBrowser;
 	}
 	async hasBrowserInstalled(browser, buildId) {
-		return (await (0, _puppeteer_browsers.getInstalledBrowsers)({ cacheDir: this.#cacheDir })).find((insBrowser) => {
-			return insBrowser.browser === browser && insBrowser.buildId === buildId;
+		const { Browser: BrowserEnum, getInstalledBrowsers } = await loadPuppeteerBrowsers();
+		const expected = toEnumMember(BrowserEnum, browser, "browser");
+		return (await getInstalledBrowsers({ cacheDir: this.#cacheDir })).find((insBrowser) => {
+			return insBrowser.browser === expected && insBrowser.buildId === buildId;
 		}) !== void 0;
 	}
 	async getExecutablePath() {
-		const browser = this.#browser;
+		const { Browser: BrowserEnum, BrowserPlatform, detectBrowserPlatform, getInstalledBrowsers, resolveBuildId } = await loadPuppeteerBrowsers();
+		const browser = toEnumMember(BrowserEnum, this.#browser, "browser");
 		const versionTag = this.#browserTag;
-		const browserPlatform = (0, _puppeteer_browsers.detectBrowserPlatform)() ?? _puppeteer_browsers.BrowserPlatform.LINUX;
+		const browserPlatform = detectBrowserPlatform() ?? BrowserPlatform.LINUX;
 		let buildId = null;
 		if (this.#useLockedBrowser) {
 			buildId = this.getLockedBuildId(browser);
 			_nestjs_common.Logger.log(`Using locked browser ${buildId}`, "NestJsPdf");
 		}
-		buildId ??= await (0, _puppeteer_browsers.resolveBuildId)(browser, browserPlatform, versionTag);
-		const installedBrowser = (await (0, _puppeteer_browsers.getInstalledBrowsers)({ cacheDir: this.#cacheDir })).find((insBrowser) => {
+		buildId ??= await resolveBuildId(browser, browserPlatform, versionTag);
+		const installedBrowser = (await getInstalledBrowsers({ cacheDir: this.#cacheDir })).find((insBrowser) => {
 			return insBrowser.browser === browser && insBrowser.buildId === buildId;
 		});
 		if (installedBrowser === void 0) {
@@ -930,7 +1335,8 @@ let BrowserService = class BrowserService {
 	}
 	async #launchBrowser(args, headless, executablePathBin) {
 		const executablePath = executablePathBin ?? await this.getExecutablePath();
-		const browser = await (0, puppeteer.launch)({
+		const { launch } = await loadPuppeteer();
+		const browser = await launch({
 			executablePath,
 			headless,
 			args,
@@ -966,8 +1372,7 @@ BrowserService = __decorate([
 	__decorateParam(0, (0, _nestjs_common.Inject)("PDF_PARAMETERS")),
 	__decorateMetadata("design:paramtypes", [Object])
 ], BrowserService);
-//#endregion
-//#region src/puppeteer/libs/loadEngine.utils.ts
+// src/puppeteer/libs/loadEngine.utils.ts
 const requireEngine = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 /**
 * Load an optional template engine on first use, so the library can be imported
@@ -984,8 +1389,7 @@ function loadEngine(packageName, engineName) {
 	}
 	return mod.__esModule && "default" in mod ? mod.default : mod;
 }
-//#endregion
-//#region src/puppeteer/engines/ejs/ejs.service.ts
+// src/puppeteer/engines/ejs/ejs.service.ts
 let EjsService = class EjsService {
 	#ejs;
 	get #engine() {
@@ -1015,8 +1419,7 @@ let EjsService = class EjsService {
 	}
 };
 EjsService = __decorate([(0, _nestjs_common.Injectable)()], EjsService);
-//#endregion
-//#region src/puppeteer/engines/eta/eta.service.ts
+// src/puppeteer/engines/eta/eta.service.ts
 let EtaService = class EtaService {
 	#etaModule;
 	#eta;
@@ -1087,8 +1490,7 @@ let EtaService = class EtaService {
 	}
 };
 EtaService = __decorate([(0, _nestjs_common.Injectable)()], EtaService);
-//#endregion
-//#region src/puppeteer/engines/handlebars/handlebars.service.ts
+// src/puppeteer/engines/handlebars/handlebars.service.ts
 let HandlebarsService = class HandlebarsService {
 	#handlebars;
 	#cachedOptions;
@@ -1143,8 +1545,7 @@ let HandlebarsService = class HandlebarsService {
 	}
 };
 HandlebarsService = __decorate([(0, _nestjs_common.Injectable)()], HandlebarsService);
-//#endregion
-//#region src/puppeteer/engines/liquid/liquid.service.ts
+// src/puppeteer/engines/liquid/liquid.service.ts
 let LiquidService = class LiquidService {
 	#liquidModule;
 	#liquid;
@@ -1205,8 +1606,7 @@ let LiquidService = class LiquidService {
 	}
 };
 LiquidService = __decorate([(0, _nestjs_common.Injectable)()], LiquidService);
-//#endregion
-//#region src/puppeteer/engines/mjml/mjml.service.ts
+// src/puppeteer/engines/mjml/mjml.service.ts
 let MjmlService = class MjmlService {
 	#mjml;
 	get #engine() {
@@ -1232,8 +1632,7 @@ let MjmlService = class MjmlService {
 	}
 };
 MjmlService = __decorate([(0, _nestjs_common.Injectable)()], MjmlService);
-//#endregion
-//#region src/puppeteer/engines/mustache/mustache.service.ts
+// src/puppeteer/engines/mustache/mustache.service.ts
 let MustacheService = class MustacheService {
 	#mustache;
 	#templateCache = /* @__PURE__ */ new Map();
@@ -1296,8 +1695,7 @@ let MustacheService = class MustacheService {
 	}
 };
 MustacheService = __decorate([(0, _nestjs_common.Injectable)()], MustacheService);
-//#endregion
-//#region src/puppeteer/engines/nunjucks/nunjucks.service.ts
+// src/puppeteer/engines/nunjucks/nunjucks.service.ts
 let NunjucksService = class NunjucksService {
 	#nunjucks;
 	get #engine() {
@@ -1349,8 +1747,7 @@ let NunjucksService = class NunjucksService {
 	}
 };
 NunjucksService = __decorate([(0, _nestjs_common.Injectable)()], NunjucksService);
-//#endregion
-//#region src/puppeteer/engines/pug/pug.service.ts
+// src/puppeteer/engines/pug/pug.service.ts
 let PugService = class PugService {
 	#pug;
 	get #engine() {
@@ -1375,16 +1772,15 @@ let PugService = class PugService {
 	}
 };
 PugService = __decorate([(0, _nestjs_common.Injectable)()], PugService);
-//#endregion
-//#region src/puppeteer/libs/requireService.utils.ts
+// src/puppeteer/libs/requireService.utils.ts
 function requireService(service, name) {
 	if (!service) throw new EngineNotAvailableException(name);
 	return service;
 }
-//#endregion
-//#region src/puppeteer/puppeteer.service.ts
+// src/puppeteer/puppeteer.service.ts
 let PuppeteerService = class PuppeteerService {
-	#browserService;
+	#renderer;
+	#jobs;
 	#options;
 	#hbsService;
 	#mjmlService;
@@ -1394,8 +1790,9 @@ let PuppeteerService = class PuppeteerService {
 	#etaService;
 	#mustacheService;
 	#liquidService;
-	constructor(browserService, options, hbsService, mjmlService, pugService, ejsService, nunjucksService, etaService, mustacheService, liquidService) {
-		this.#browserService = browserService;
+	constructor(renderer, jobs, options, hbsService, mjmlService, pugService, ejsService, nunjucksService, etaService, mustacheService, liquidService) {
+		this.#renderer = renderer;
+		this.#jobs = jobs;
 		this.#options = options;
 		this.#hbsService = hbsService;
 		this.#mjmlService = mjmlService;
@@ -1414,87 +1811,19 @@ let PuppeteerService = class PuppeteerService {
 		const job = this.#limit(async () => {
 			signal?.throwIfAborted();
 			started = true;
-			const mergePuppeteerOptions = mergePuppeteerParameters(this.#options, options);
-			if (mergePuppeteerOptions.chromiumRevision !== void 0) _nestjs_common.Logger.warn("Using `chromiumRevision` is no longer supported since the puppeteer update.");
-			const headless = mergePuppeteerOptions.headless ?? true;
-			const executablePath = mergePuppeteerOptions.executablePath || void 0;
-			const args = mergePuppeteerOptions.extraPuppeteerArgs || [
-				"--autoplay-policy=user-gesture-required",
-				"--disable-background-networking",
-				"--disable-background-timer-throttling",
-				"--disable-backgrounding-occluded-windows",
-				"--disable-breakpad",
-				"--disable-client-side-phishing-detection",
-				"--disable-component-update",
-				"--disable-default-apps",
-				"--disable-dev-shm-usage",
-				"--disable-domain-reliability",
-				"--disable-extensions",
-				"--disable-features=AudioServiceOutOfProcess",
-				"--disable-hang-monitor",
-				"--disable-ipc-flooding-protection",
-				"--disable-notifications",
-				"--disable-offer-store-unmasked-wallet-cards",
-				"--disable-print-preview",
-				"--disable-prompt-on-repost",
-				"--disable-renderer-backgrounding",
-				"--disable-setuid-sandbox",
-				"--disable-speech-api",
-				"--disable-sync",
-				"--hide-scrollbars",
-				"--ignore-gpu-blacklist",
-				"--metrics-recording-only",
-				"--mute-audio",
-				"--no-default-browser-check",
-				"--no-first-run",
-				"--no-pings",
-				"--password-store=basic",
-				"--use-gl=swiftshader",
-				"--use-mock-keychain",
-				"--disable-accelerated-2d-canvas",
-				"--no-zygote",
-				"--disable-gpu"
-			];
-			this.#browserService.markJobStarted();
-			let context = null;
-			let closing;
-			const onAbort = () => {
-				if (!context) return;
-				closing = context.close();
-				closing.catch(() => void 0);
-			};
-			signal?.addEventListener("abort", onAbort, { once: true });
+			const mergedOptions = mergePuppeteerParameters(this.#options, options);
+			this.#jobs.markJobStarted();
 			try {
-				context = await this.#browserService.createContext(args, headless, executablePath);
-				signal?.throwIfAborted();
-				const page = await context.newPage();
-				if (mergePuppeteerOptions.security) await installRequestGuard(context, page, mergePuppeteerOptions.security);
-				const pdfOptions = mergePuppeteerOptions.pdfOptions ?? { format: "A4" };
-				await page.setContent(html, { waitUntil: "domcontentloaded" });
-				await page.emulateMediaType("screen");
-				await page.waitForNetworkIdle({
-					idleTime: 500,
-					timeout: 3e4
-				});
-				/* v8 ignore next */
-				await page.evaluate(() => document.fonts.ready);
-				const pdf = await page.pdf(pdfOptions);
+				const pdf = await this.#renderer.render(html, mergedOptions, signal);
 				signal?.throwIfAborted();
-				return mergePuppeteerOptions.watermark ? await addWatermark(pdf, mergePuppeteerOptions.watermark) : pdf;
+				return mergedOptions.watermark ? await addWatermark(pdf, mergedOptions.watermark) : pdf;
 			} catch (e) {
 				if (signal?.aborted) throw signal.reason;
 				_nestjs_common.Logger.error(e);
 				if (e instanceof NestjsPdfException) throw e;
 				throw new PdfGenerationException(`PDF generation failed: ${String(e)}`, { cause: e });
 			} finally {
-				signal?.removeEventListener("abort", onAbort);
-				if (context) try {
-					if (closing) await closing;
-					else await context.close();
-				} catch (error) {
-					_nestjs_common.Logger.error(error);
-				}
-				await this.#browserService.markJobFinished();
+				await this.#jobs.markJobFinished();
 			}
 		});
 		if (!signal) return job;
@@ -1578,8 +1907,9 @@ let PuppeteerService = class PuppeteerService {
 };
 PuppeteerService = __decorate([
 	(0, _nestjs_common.Injectable)(),
-	__decorateParam(1, (0, _nestjs_common.Inject)(PDF_PARAMETERS)),
-	__decorateParam(2, (0, _nestjs_common.Optional)()),
+	__decorateParam(0, (0, _nestjs_common.Inject)(PDF_RENDERER)),
+	__decorateParam(1, (0, _nestjs_common.Inject)(BrowserService)),
+	__decorateParam(2, (0, _nestjs_common.Inject)(PDF_PARAMETERS)),
 	__decorateParam(3, (0, _nestjs_common.Optional)()),
 	__decorateParam(4, (0, _nestjs_common.Optional)()),
 	__decorateParam(5, (0, _nestjs_common.Optional)()),
@@ -1587,8 +1917,10 @@ PuppeteerService = __decorate([
 	__decorateParam(7, (0, _nestjs_common.Optional)()),
 	__decorateParam(8, (0, _nestjs_common.Optional)()),
 	__decorateParam(9, (0, _nestjs_common.Optional)()),
+	__decorateParam(10, (0, _nestjs_common.Optional)()),
 	__decorateMetadata("design:paramtypes", [
-		typeof BrowserService === "undefined" ? Object : BrowserService,
+		Object,
+		Object,
 		Object,
 		typeof HandlebarsService === "undefined" ? Object : HandlebarsService,
 		typeof MjmlService === "undefined" ? Object : MjmlService,
@@ -1600,8 +1932,7 @@ PuppeteerService = __decorate([
 		typeof LiquidService === "undefined" ? Object : LiquidService
 	])
 ], PuppeteerService);
-//#endregion
-//#region src/nestjs-pdf.service.ts
+// src/nestjs-pdf.service.ts
 let NestjsPdfService = class NestjsPdfService {
 	#puppeteerService;
 	constructor(puppeteerService) {
@@ -1821,9 +2152,14 @@ let NestjsPdfService = class NestjsPdfService {
 	}
 };
 NestjsPdfService = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [typeof PuppeteerService === "undefined" ? Object : PuppeteerService])], NestjsPdfService);
-//#endregion
-//#region src/puppeteer/puppeteer.module.ts
+// src/puppeteer/puppeteer.module.ts
 var _PuppeteerModule;
+/** Builds the renderer of the configured provider, once the parameters are known. */
+const pdfRendererProvider = {
+	provide: PDF_RENDERER,
+	inject: [PDF_PARAMETERS, BrowserService],
+	useFactory: createPdfRenderer
+};
 let PuppeteerModule = _PuppeteerModule = class PuppeteerModule {
 	#browserService;
 	#pdfParams;
@@ -1832,7 +2168,12 @@ let PuppeteerModule = _PuppeteerModule = class PuppeteerModule {
 		this.#pdfParams = pdfParams;
 	}
 	async onModuleInit() {
-		if (!this.#pdfParams.executablePath) await this.#browserService.install(this.#pdfParams.useLockedBrowser ?? false);
+		if (!usesPuppeteer(this.#pdfParams)) return;
+		await loadPuppeteer();
+		if (!this.#pdfParams.executablePath) {
+			await loadPuppeteerBrowsers();
+			await this.#browserService.install(this.#pdfParams.useLockedBrowser ?? false);
+		}
 	}
 	static forRoot(pdfParameters) {
 		return {
@@ -1876,6 +2217,7 @@ let PuppeteerModule = _PuppeteerModule = class PuppeteerModule {
 				pdfParamsProvider,
 				PuppeteerService,
 				BrowserService,
+				pdfRendererProvider,
 				HandlebarsService,
 				MjmlService,
 				PugService,
@@ -1903,6 +2245,7 @@ PuppeteerModule = _PuppeteerModule = __decorate([
 		providers: [
 			PuppeteerService,
 			BrowserService,
+			pdfRendererProvider,
 			MjmlService,
 			PugService,
 			EjsService,
@@ -1922,11 +2265,11 @@ PuppeteerModule = _PuppeteerModule = __decorate([
 			LiquidService
 		]
 	}),
+	__decorateParam(0, (0, _nestjs_common.Inject)(BrowserService)),
 	__decorateParam(1, (0, _nestjs_common.Inject)(PDF_PARAMETERS)),
-	__decorateMetadata("design:paramtypes", [typeof BrowserService === "undefined" ? Object : BrowserService, Object])
+	__decorateMetadata("design:paramtypes", [Object, Object])
 ], PuppeteerModule);
-//#endregion
-//#region src/nestjs-pdf.module.ts
+// src/nestjs-pdf.module.ts
 var _NestjsPdfModule;
 let NestjsPdfModule = _NestjsPdfModule = class NestjsPdfModule {
 	static forRoot(options) {
@@ -1947,7 +2290,6 @@ let NestjsPdfModule = _NestjsPdfModule = class NestjsPdfModule {
 	}
 };
 NestjsPdfModule = _NestjsPdfModule = __decorate([(0, _nestjs_common.Module)({})], NestjsPdfModule);
-//#endregion
 exports.BrowserInstallationException = BrowserInstallationException;
 exports.BrowserUnavailableException = BrowserUnavailableException;
 Object.defineProperty(exports, "EjsService", {
@@ -2026,6 +2368,7 @@ Object.defineProperty(exports, "PuppeteerService", {
 		return PuppeteerService;
 	}
 });
+exports.RendererConfigurationException = RendererConfigurationException;
 exports.SignatureDependencyException = SignatureDependencyException;
 exports.SignaturePlacementException = SignaturePlacementException;
 exports.TemplateConfigurationException = TemplateConfigurationException;