chromiumly 2.2.0 → 2.3.1

package/src/chromium/converters/markdown.converter.ts

@@ -3,7 +3,6 @@ import { constants, createReadStream, PathLike, promises } from "fs";
 import FormData from "form-data";
 
 import { GotenbergUtils, PdfFormat } from "../../common";
-import { IConverter } from "../interfaces/converter.interface";
 import {
   EmulatedMediaType,
   PageProperties,
@@ -12,7 +11,7 @@ import { ConverterUtils } from "../utils/converter.utils";
 import { Converter } from "./converter";
 import { ChromiumRoute } from "../../main.config";
 
-export class MarkdownConverter extends Converter implements IConverter {
+export class MarkdownConverter extends Converter {
   constructor() {
     super(ChromiumRoute.MARKDOWN);
   }
@@ -24,7 +23,13 @@ export class MarkdownConverter extends Converter implements IConverter {
     footer,
     properties,
     pdfFormat,
+    pdfUA,
     emulatedMediaType,
+    waitDelay,
+    waitForExpression,
+    userAgent,
+    extraHttpHeaders,
+    failOnConsoleExceptions,
   }: {
     html: PathLike;
     markdown: PathLike;
@@ -32,34 +37,34 @@ export class MarkdownConverter extends Converter implements IConverter {
     footer?: PathLike;
     properties?: PageProperties;
     pdfFormat?: PdfFormat;
+    pdfUA?: boolean;
     emulatedMediaType?: EmulatedMediaType;
+    waitDelay?: string;
+    waitForExpression?: string;
+    userAgent?: string;
+    extraHttpHeaders?: Record<string, string>;
+    failOnConsoleExceptions?: boolean;
   }): Promise<Buffer> {
     await promises.access(html, constants.R_OK);
     await promises.access(markdown, constants.R_OK);
     const data = new FormData();
-    if (pdfFormat) {
-      data.append("pdfFormat", pdfFormat);
-    }
+
     data.append("index.html", createReadStream(html));
     data.append("file.md", createReadStream(markdown));
 
-    if (header) {
-      await promises.access(header, constants.R_OK);
-      data.append("header.html", createReadStream(header));
-    }
-
-    if (footer) {
-      await promises.access(footer, constants.R_OK);
-      data.append("footer.html", createReadStream(footer));
-    }
-
-    if (emulatedMediaType) {
-      data.append("emulatedMediaType", emulatedMediaType);
-    }
-
-    if (properties) {
-      ConverterUtils.injectPageProperties(data, properties);
-    }
+    ConverterUtils.customize(data, {
+      header,
+      footer,
+      properties,
+      pdfFormat,
+      pdfUA,
+      emulatedMediaType,
+      waitDelay,
+      waitForExpression,
+      userAgent,
+      extraHttpHeaders,
+      failOnConsoleExceptions,
+    });
 
     return GotenbergUtils.fetch(this.endpoint, data);
   }

package/src/chromium/converters/url.converter.ts

@@ -1,11 +1,10 @@
-import { PathLike, constants, createReadStream, promises } from "fs";
+import { PathLike } from "fs";
 
 import { URL } from "url";
 
 import FormData from "form-data";
 
 import { GotenbergUtils, PdfFormat } from "../../common";
-import { IConverter } from "../interfaces/converter.interface";
 import {
   EmulatedMediaType,
   PageProperties,
@@ -14,7 +13,7 @@ import { ConverterUtils } from "../utils/converter.utils";
 import { Converter } from "./converter";
 import { ChromiumRoute } from "../../main.config";
 
-export class UrlConverter extends Converter implements IConverter {
+export class UrlConverter extends Converter {
   constructor() {
     super(ChromiumRoute.URL);
   }
@@ -25,40 +24,46 @@ export class UrlConverter extends Converter implements IConverter {
     footer,
     properties,
     pdfFormat,
+    pdfUA,
     emulatedMediaType,
+    waitDelay,
+    waitForExpression,
+    userAgent,
+    extraHttpHeaders,
+    failOnConsoleExceptions,
   }: {
     url: string;
     header?: PathLike;
     footer?: PathLike;
     properties?: PageProperties;
     pdfFormat?: PdfFormat;
+    pdfUA?: boolean;
     emulatedMediaType?: EmulatedMediaType;
+    waitDelay?: string;
+    waitForExpression?: string;
+    userAgent?: string;
+    extraHttpHeaders?: Record<string, string>;
+    failOnConsoleExceptions?: boolean;
   }): Promise<Buffer> {
     const _url = new URL(url);
     const data = new FormData();
-    if (pdfFormat) {
-      data.append("pdfFormat", pdfFormat);
-    }
 
     data.append("url", _url.href);
 
-    if (header) {
-      await promises.access(header, constants.R_OK);
-      data.append("header.html", createReadStream(header));
-    }
+    ConverterUtils.customize(data, {
+      header,
+      footer,
+      properties,
+      pdfFormat,
+      pdfUA,
+      emulatedMediaType,
+      waitDelay,
+      waitForExpression,
+      userAgent,
+      extraHttpHeaders,
+      failOnConsoleExceptions,
+    });
 
-    if (footer) {
-      await promises.access(footer, constants.R_OK);
-      data.append("footer.html", createReadStream(footer));
-    }
-
-    if (emulatedMediaType) {
-      data.append("emulatedMediaType", emulatedMediaType);
-    }
-
-    if (properties) {
-      ConverterUtils.injectPageProperties(data, properties);
-    }
     return GotenbergUtils.fetch(this.endpoint, data);
   }
 }

package/src/chromium/interfaces/converter.types.ts

@@ -1,3 +1,6 @@
+import { PathLike } from "fs";
+import { PdfFormat } from "../../common";
+
 type PageSize = {
   width: number; // Paper width, in inches (default 8.5)
   height: number; //Paper height, in inches (default 11)
@@ -15,9 +18,24 @@ export type PageProperties = {
   margins?: PageMargins;
   preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
   printBackground?: boolean; // Print the background graphics (default false)
+  omitBackground?: boolean; // Hide the default white background and allow generating PDFs with transparency (default false)
   landscape?: boolean; // Set the paper orientation to landscape (default false)
   scale?: number; // The scale of the page rendering (default 1.0)
   nativePageRanges?: { from: number; to: number }; // Page ranges to print
 };
 
 export type EmulatedMediaType = "screen" | "print";
+
+export type ConversionOptions = {
+  header?: PathLike;
+  footer?: PathLike;
+  properties?: PageProperties;
+  pdfFormat?: PdfFormat;
+  pdfUA?: boolean; // Enable PDF for Universal Access for optimal accessibility (default false)
+  emulatedMediaType?: EmulatedMediaType;
+  waitDelay?: string; // Duration (e.g, '5s') to wait when loading an HTML document before converting it into PDF
+  waitForExpression?: string; // JavaScript expression to wait before converting an HTML document into PDF until it returns true.
+  userAgent?: string;
+  extraHttpHeaders?: Record<string, string>;
+  failOnConsoleExceptions?: boolean; // Return a 409 Conflict response if there are exceptions in the Chromium console (default false)
+};

package/src/chromium/utils/converter.utils.ts

@@ -1,7 +1,11 @@
+import { constants, createReadStream, promises } from "fs";
 import FormData from "form-data";
 
 import { GotenbergUtils } from "../../common/gotenberg.utils";
-import { PageProperties } from "../interfaces/converter.types";
+import {
+  ConversionOptions,
+  PageProperties,
+} from "../interfaces/converter.types";
 
 export class ConverterUtils {
   public static injectPageProperties(
@@ -44,6 +48,10 @@ export class ConverterUtils {
       data.append("printBackground", String(pageProperties.printBackground));
     }
 
+    if (pageProperties.omitBackground) {
+      data.append("omitBackground", String(pageProperties.omitBackground));
+    }
+
     if (pageProperties.landscape) {
       data.append("landscape", String(pageProperties.landscape));
     }
@@ -72,4 +80,58 @@ export class ConverterUtils {
       );
     }
   }
+
+  public static async customize(
+    data: FormData,
+    options: ConversionOptions
+  ): Promise<void> {
+    if (options.pdfFormat) {
+      data.append("pdfa", options.pdfFormat);
+    }
+
+    if (options.pdfUA) {
+      data.append("pdfua", String(options.pdfUA));
+    }
+
+    if (options.header) {
+      await promises.access(options.header, constants.R_OK);
+      data.append("header.html", createReadStream(options.header));
+    }
+
+    if (options.footer) {
+      await promises.access(options.footer, constants.R_OK);
+      data.append("footer.html", createReadStream(options.footer));
+    }
+
+    if (options.emulatedMediaType) {
+      data.append("emulatedMediaType", options.emulatedMediaType);
+    }
+
+    if (options.properties) {
+      ConverterUtils.injectPageProperties(data, options.properties);
+    }
+
+    if (options.waitDelay) {
+      data.append("waitDelay", options.waitDelay);
+    }
+
+    if (options.waitForExpression) {
+      data.append("waitForExpression", options.waitForExpression);
+    }
+
+    if (options.userAgent) {
+      data.append("userAgent", options.userAgent);
+    }
+
+    if (options.extraHttpHeaders) {
+      data.append("extraHttpHeaders", JSON.stringify(options.extraHttpHeaders));
+    }
+
+    if (options.failOnConsoleExceptions) {
+      data.append(
+        "failOnConsoleExceptions",
+        String(options.failOnConsoleExceptions)
+      );
+    }
+  }
 }

package/src/chromium/utils/tests/converter.utils.test.ts

@@ -1,10 +1,20 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { createReadStream, promises } from "fs";
 import FormData from "form-data";
 import { ConverterUtils } from "../converter.utils";
+import { PdfFormat } from "../../../common";
 
 describe("ConverterUtils", () => {
   const mockFormDataAppend = jest.spyOn(FormData.prototype, "append");
+  const mockPromisesAccess = jest.spyOn(promises, "access");
   const data = new FormData();
 
+  beforeEach(() => {
+    (createReadStream as jest.Mock) = jest
+      .fn()
+      .mockImplementation((file) => file);
+  });
+
   afterEach(() => {
     jest.resetAllMocks();
   });
@@ -16,7 +26,7 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             size: { width: 8.3, height: 11.7 },
           });
-          expect(mockFormDataAppend).toBeCalledTimes(2);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
           expect(data.append).toHaveBeenCalledWith("paperWidth", 8.3);
           expect(data.append).toHaveBeenNthCalledWith(2, "paperHeight", 11.7);
         });
@@ -29,7 +39,7 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             margins: { top: 0.5, bottom: 0.5, left: 1, right: 1 },
           });
-          expect(mockFormDataAppend).toBeCalledTimes(4);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(4);
           expect(data.append).toHaveBeenCalledWith("marginTop", 0.5);
           expect(data.append).toHaveBeenNthCalledWith(2, "marginBottom", 0.5);
           expect(data.append).toHaveBeenNthCalledWith(3, "marginLeft", 1);
@@ -44,7 +54,7 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             preferCssPageSize: true,
           });
-          expect(mockFormDataAppend).toBeCalledTimes(1);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
           expect(data.append).toHaveBeenCalledWith("preferCssPageSize", "true");
         });
       });
@@ -56,10 +66,20 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             printBackground: true,
           });
-          expect(mockFormDataAppend).toBeCalledTimes(1);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
           expect(data.append).toHaveBeenCalledWith("printBackground", "true");
         });
       });
+
+      describe("when omitBackground parameter is set", () => {
+        it("should append omitBackground to data", () => {
+          ConverterUtils.injectPageProperties(data, {
+            omitBackground: true,
+          });
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+          expect(data.append).toHaveBeenCalledWith("omitBackground", "true");
+        });
+      });
     });
 
     describe("Page landscape", () => {
@@ -68,7 +88,7 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             landscape: true,
           });
-          expect(mockFormDataAppend).toBeCalledTimes(1);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
           expect(data.append).toHaveBeenCalledWith("landscape", "true");
         });
       });
@@ -80,7 +100,7 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             scale: 1.5,
           });
-          expect(mockFormDataAppend).toBeCalledTimes(1);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
           expect(data.append).toHaveBeenCalledWith("scale", 1.5);
         });
       });
@@ -92,10 +112,216 @@ describe("ConverterUtils", () => {
           ConverterUtils.injectPageProperties(data, {
             nativePageRanges: { from: 1, to: 6 },
           });
-          expect(mockFormDataAppend).toBeCalledTimes(1);
+          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
           expect(data.append).toHaveBeenCalledWith("nativePageRanges", "1-6");
         });
       });
     });
   });
+
+  describe("customize", () => {
+    describe("when no option is passed", () => {
+      it("should not append anything", async () => {
+        await ConverterUtils.customize(data, {});
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(0);
+      });
+    });
+
+    describe("when header parameter is passed", () => {
+      it("should append header", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        await ConverterUtils.customize(data, {
+          header: "path/to/header.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith(
+          "header.html",
+          "path/to/header.html"
+        );
+      });
+    });
+
+    describe("when footer parameter is passed", () => {
+      it("should append footer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        await ConverterUtils.customize(data, {
+          footer: "path/to/footer.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith(
+          "footer.html",
+          "path/to/footer.html"
+        );
+      });
+    });
+
+    describe("when pdf format parameter is passed", () => {
+      it("should append pdf format", async () => {
+        await ConverterUtils.customize(data, {
+          pdfFormat: PdfFormat.A_1a,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith("pdfa", "PDF/A-1a");
+      });
+    });
+
+    describe("when pdf universal access parameter is passed", () => {
+      it("should append pdfua format", async () => {
+        await ConverterUtils.customize(data, {
+          pdfUA: true,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith("pdfua", "true");
+      });
+    });
+
+    describe("when page properties parameter is passed", () => {
+      it("should append page propertiers", async () => {
+        await ConverterUtils.customize(data, {
+          properties: { size: { width: 8.3, height: 11.7 } },
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(data.append).toHaveBeenCalledWith("paperWidth", 8.3);
+        expect(data.append).toHaveBeenNthCalledWith(2, "paperHeight", 11.7);
+      });
+    });
+
+    describe("when emulatedMediaType parameter is passed", () => {
+      it("should append emulatedMediaType", async () => {
+        await ConverterUtils.customize(data, {
+          emulatedMediaType: "screen",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith("emulatedMediaType", "screen");
+      });
+    });
+
+    describe("when waitDelay parameter is passed", () => {
+      it("should append waitDelay", async () => {
+        await ConverterUtils.customize(data, {
+          waitDelay: "5s",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith("waitDelay", "5s");
+      });
+    });
+
+    describe("when waitForExpression parameter is passed", () => {
+      it("should append waitForExpression", async () => {
+        await ConverterUtils.customize(data, {
+          waitForExpression: "document.readyState === 'complete'",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith(
+          "waitForExpression",
+          "document.readyState === 'complete'"
+        );
+      });
+    });
+
+    describe("when userAgent parameter is passed", () => {
+      it("should append userAgent", async () => {
+        const userAgent =
+          "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36";
+
+        await ConverterUtils.customize(data, {
+          userAgent,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith("userAgent", userAgent);
+      });
+    });
+
+    describe("when extraHttpHeaders parameter is passed", () => {
+      it("should append extraHttpHeaders", async () => {
+        const extraHttpHeaders = {
+          "X-Custom-Header": "value",
+        };
+
+        await ConverterUtils.customize(data, {
+          extraHttpHeaders,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith(
+          "extraHttpHeaders",
+          JSON.stringify(extraHttpHeaders)
+        );
+      });
+    });
+
+    describe("when failOnConsoleExceptions parameter is passed", () => {
+      it("should append failOnConsoleExceptions", async () => {
+        await ConverterUtils.customize(data, {
+          failOnConsoleExceptions: true,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+        expect(data.append).toHaveBeenCalledWith(
+          "failOnConsoleExceptions",
+          "true"
+        );
+      });
+    });
+
+    describe("when all options are passed", () => {
+      it("should append all options", async () => {
+        mockPromisesAccess.mockResolvedValue();
+
+        await ConverterUtils.customize(data, {
+          header: "path/to/header.html",
+          footer: "path/to/footer.html",
+          pdfFormat: PdfFormat.A_1a,
+          pdfUA: true,
+          emulatedMediaType: "screen",
+          properties: { size: { width: 8.3, height: 11.7 } },
+          waitDelay: "5s",
+          waitForExpression: "document.readyState === 'complete'",
+          userAgent:
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
+          extraHttpHeaders: { "X-Custom-Header": "value" },
+          failOnConsoleExceptions: true,
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(12);
+        expect(data.append).toHaveBeenNthCalledWith(1, "pdfa", "PDF/A-1a");
+        expect(data.append).toHaveBeenNthCalledWith(2, "pdfua", "true");
+        expect(data.append).toHaveBeenNthCalledWith(
+          3,
+          "header.html",
+          "path/to/header.html"
+        );
+        expect(data.append).toHaveBeenNthCalledWith(
+          4,
+          "footer.html",
+          "path/to/footer.html"
+        );
+        expect(data.append).toHaveBeenNthCalledWith(
+          5,
+          "emulatedMediaType",
+          "screen"
+        );
+        expect(data.append).toHaveBeenNthCalledWith(6, "paperWidth", 8.3);
+        expect(data.append).toHaveBeenNthCalledWith(7, "paperHeight", 11.7);
+        expect(data.append).toHaveBeenNthCalledWith(8, "waitDelay", "5s");
+        expect(data.append).toHaveBeenNthCalledWith(
+          9,
+          "waitForExpression",
+          "document.readyState === 'complete'"
+        );
+        expect(data.append).toHaveBeenNthCalledWith(
+          10,
+          "userAgent",
+          "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36"
+        );
+        expect(data.append).toHaveBeenNthCalledWith(
+          11,
+          "extraHttpHeaders",
+          JSON.stringify({ "X-Custom-Header": "value" })
+        );
+        expect(data.append).toHaveBeenNthCalledWith(
+          12,
+          "failOnConsoleExceptions",
+          "true"
+        );
+      });
+    });
+  });
 });

package/src/pdf-engines/pdf.engine.ts

@@ -20,25 +20,37 @@ export class PDFEngine {
     files,
     properties,
     pdfFormat,
+    pdfUA,
     merge,
   }: {
     files: PathLike[];
     properties?: PageProperties;
     pdfFormat?: PdfFormat;
+    pdfUA?: boolean;
     merge?: boolean;
   }): Promise<Buffer> {
     const data = new FormData();
+
     if (pdfFormat) {
-      data.append("pdfFormat", pdfFormat);
+      data.append("pdfa", pdfFormat);
+    }
+
+    if (pdfUA) {
+      data.append("pdfUA", String(pdfUA));
     }
+
     if (merge) {
       data.append("merge", String(merge));
     }
+
     if (properties) {
       LibreOfficeUtils.injectPageProperties(data, properties);
     }
+
     await LibreOfficeUtils.injectFiles(files, data);
+
     const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.LIBRE_OFFICE_PATH}/${Chromiumly.LIBRE_OFFICE_ROUTES.convert}`;
+
     return GotenbergUtils.fetch(endpoint, data);
   }
 

package/src/pdf-engines/tests/pdf.engine.test.ts

@@ -47,10 +47,11 @@ describe("PDFEngine", () => {
           files: ["path/to/file.docx", "path/to/file.bib"],
           properties: { landscape: true },
           pdfFormat: PdfFormat.A_1a,
+          pdfUA: true,
           merge: true,
         });
         expect(buffer).toEqual(Buffer.from("content"));
-        expect(mockFormDataAppend).toHaveBeenCalledTimes(5);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(6);
       });
     });
   });

package/dist/chromium/interfaces/converter.interface.d.ts

@@ -1,10 +0,0 @@
-/// <reference types="node" />
-/// <reference types="node" />
-import { PathLike } from "fs";
-import { PdfFormat } from "../../common";
-import { PageProperties } from "./converter.types";
-export interface IConverter {
-    convert({ ...args }: {
-        [x: string]: string | PathLike | PageProperties | PdfFormat;
-    }): Promise<Buffer>;
-}

package/dist/chromium/interfaces/converter.interface.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=converter.interface.js.map

package/dist/chromium/interfaces/converter.interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"converter.interface.js","sourceRoot":"","sources":["../../../src/chromium/interfaces/converter.interface.ts"],"names":[],"mappings":""}

package/src/chromium/interfaces/converter.interface.ts

@@ -1,12 +0,0 @@
-import { PathLike } from "fs";
-
-import { PdfFormat } from "../../common";
-import { PageProperties } from "./converter.types";
-
-export interface IConverter {
-  convert({
-    ...args
-  }: {
-    [x: string]: string | PathLike | PageProperties | PdfFormat;
-  }): Promise<Buffer>;
-}