chromiumly 2.1.0 → 2.3.1

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

@@ -3,39 +3,65 @@ import { constants, createReadStream, PathLike, promises } from "fs";
 import FormData from "form-data";
 
 import { GotenbergUtils, PdfFormat } from "../../common";
-import { IConverter } from "../interfaces/converter.interface";
-import { PageProperties } from "../interfaces/converter.types";
+import {
+  EmulatedMediaType,
+  PageProperties,
+} from "../interfaces/converter.types";
 import { ConverterUtils } from "../utils/converter.utils";
 import { Converter } from "./converter";
 import { ChromiumRoute } from "../../main.config";
 
-export class HtmlConverter extends Converter implements IConverter {
+export class HtmlConverter extends Converter {
   constructor() {
     super(ChromiumRoute.HTML);
   }
 
   async convert({
     html,
+    header,
+    footer,
     properties,
     pdfFormat,
+    pdfUA,
+    emulatedMediaType,
+    waitDelay,
+    waitForExpression,
+    userAgent,
+    extraHttpHeaders,
+    failOnConsoleExceptions,
   }: {
     html: PathLike;
+    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> {
-    try {
-      await promises.access(html, constants.R_OK);
-      const data = new FormData();
-      if (pdfFormat) {
-        data.append("pdfFormat", pdfFormat);
-      }
-      data.append("index.html", createReadStream(html));
-      if (properties) {
-        ConverterUtils.injectPageProperties(data, properties);
-      }
-      return GotenbergUtils.fetch(this.endpoint, data);
-    } catch (error) {
-      throw error;
-    }
+    await promises.access(html, constants.R_OK);
+    const data = new FormData();
+
+    data.append("index.html", createReadStream(html));
+
+    ConverterUtils.customize(data, {
+      header,
+      footer,
+      properties,
+      pdfFormat,
+      pdfUA,
+      emulatedMediaType,
+      waitDelay,
+      waitForExpression,
+      userAgent,
+      extraHttpHeaders,
+      failOnConsoleExceptions,
+    });
+
+    return GotenbergUtils.fetch(this.endpoint, data);
   }
 }

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

@@ -3,13 +3,15 @@ import { constants, createReadStream, PathLike, promises } from "fs";
 import FormData from "form-data";
 
 import { GotenbergUtils, PdfFormat } from "../../common";
-import { IConverter } from "../interfaces/converter.interface";
-import { PageProperties } from "../interfaces/converter.types";
+import {
+  EmulatedMediaType,
+  PageProperties,
+} from "../interfaces/converter.types";
 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);
   }
@@ -17,29 +19,53 @@ export class MarkdownConverter extends Converter implements IConverter {
   async convert({
     html,
     markdown,
+    header,
+    footer,
     properties,
     pdfFormat,
+    pdfUA,
+    emulatedMediaType,
+    waitDelay,
+    waitForExpression,
+    userAgent,
+    extraHttpHeaders,
+    failOnConsoleExceptions,
   }: {
     html: PathLike;
     markdown: PathLike;
+    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> {
-    try {
-      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 (properties) {
-        ConverterUtils.injectPageProperties(data, properties);
-      }
-      return GotenbergUtils.fetch(this.endpoint, data);
-    } catch (error) {
-      throw error;
-    }
+    await promises.access(html, constants.R_OK);
+    await promises.access(markdown, constants.R_OK);
+    const data = new FormData();
+
+    data.append("index.html", createReadStream(html));
+    data.append("file.md", createReadStream(markdown));
+
+    ConverterUtils.customize(data, {
+      header,
+      footer,
+      properties,
+      pdfFormat,
+      pdfUA,
+      emulatedMediaType,
+      waitDelay,
+      waitForExpression,
+      userAgent,
+      extraHttpHeaders,
+      failOnConsoleExceptions,
+    });
+
+    return GotenbergUtils.fetch(this.endpoint, data);
   }
 }

package/src/chromium/converters/tests/html.converter.test.ts

@@ -1,4 +1,5 @@
-import { promises, createReadStream } from "fs";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { createReadStream, promises } from "fs";
 
 import fetch from "node-fetch";
 import FormData from "form-data";
@@ -51,7 +52,7 @@ describe("HtmlConverter", () => {
           html: "path/to/index.html",
           pdfFormat: PdfFormat.A_1a,
         });
-        expect(mockFormDataAppend).toBeCalledTimes(2);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });
@@ -64,7 +65,63 @@ describe("HtmlConverter", () => {
           html: "path/to/index.html",
           properties: { size: { width: 8.3, height: 11.7 } },
         });
-        expect(mockFormDataAppend).toBeCalledTimes(3);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when header parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          header: "path/to/header.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when footer parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          footer: "path/to/footer.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when emulatedMediaType parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          emulatedMediaType: "screen",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when all parameters are passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          header: "path/to/header.html",
+          footer: "path/to/footer.html",
+          pdfFormat: PdfFormat.A_1a,
+          emulatedMediaType: "screen",
+          properties: { size: { width: 8.3, height: 11.7 } },
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(7);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });

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

@@ -1,7 +1,8 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { createReadStream, promises } from "fs";
 
-import fetch from "node-fetch";
 import FormData from "form-data";
+import fetch from "node-fetch";
 
 import { PdfFormat } from "../../../common";
 import { MarkdownConverter } from "../markdown.converter";
@@ -29,7 +30,9 @@ describe("MarkdownConverter", () => {
 
   describe("convert", () => {
     beforeEach(() => {
-      (createReadStream as jest.Mock) = jest.fn().mockImplementation(() => {});
+      (createReadStream as jest.Mock) = jest
+        .fn()
+        .mockImplementation((file) => file);
     });
 
     describe("when file exists", () => {
@@ -53,7 +56,7 @@ describe("MarkdownConverter", () => {
           markdown: "path/to/file.md",
           pdfFormat: PdfFormat.A_2b,
         });
-        expect(mockFormDataAppend).toBeCalledTimes(3);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });
@@ -67,7 +70,68 @@ describe("MarkdownConverter", () => {
           markdown: "path/to/file.md",
           properties: { size: { width: 8.3, height: 11.7 } },
         });
-        expect(mockFormDataAppend).toBeCalledTimes(4);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(4);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when header parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          markdown: "path/to/file.md",
+          header: "path/to/header.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when footer parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          markdown: "path/to/file.md",
+          footer: "path/to/footer.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when emulatedMediaType parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          markdown: "path/to/file.md",
+          emulatedMediaType: "screen",
+        });
+
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when all parameters are passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: "path/to/index.html",
+          markdown: "path/to/file.md",
+          header: "path/to/header.html",
+          footer: "path/to/footer.html",
+          pdfFormat: PdfFormat.A_1a,
+          emulatedMediaType: "screen",
+          properties: { size: { width: 8.3, height: 11.7 } },
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(8);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });

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

@@ -1,5 +1,7 @@
-import fetch from "node-fetch";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { createReadStream, promises } from "fs";
 import FormData from "form-data";
+import fetch from "node-fetch";
 
 import { PdfFormat } from "../../../common";
 import { UrlConverter } from "../url.converter";
@@ -10,9 +12,16 @@ jest.mock("node-fetch", () => jest.fn());
 describe("HtmlConverter", () => {
   const mockFetch = fetch as jest.MockedFunction<typeof fetch>;
   const mockFormDataAppend = jest.spyOn(FormData.prototype, "append");
+  const mockPromisesAccess = jest.spyOn(promises, "access");
 
   const converter = new UrlConverter();
 
+  beforeEach(() => {
+    (createReadStream as jest.Mock) = jest
+      .fn()
+      .mockImplementation((file) => file);
+  });
+
   afterEach(() => {
     jest.resetAllMocks();
   });
@@ -36,6 +45,34 @@ describe("HtmlConverter", () => {
       });
     });
 
+    describe("when header parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockFetch.mockResolvedValueOnce(new Response("content"));
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          url: "http://www.example.com/",
+          header: "path/to/header.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when footer parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockFetch.mockResolvedValueOnce(new Response("content"));
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          url: "http://www.example.com/",
+          footer: "path/to/footer.html",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
     describe("when pdf format parameter is passed", () => {
       it("should return a buffer", async () => {
         mockFetch.mockResolvedValueOnce(new Response("content"));
@@ -43,7 +80,7 @@ describe("HtmlConverter", () => {
           url: "http://www.example.com/",
           pdfFormat: PdfFormat.A_3b,
         });
-        expect(mockFormDataAppend).toBeCalledTimes(2);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });
@@ -55,7 +92,37 @@ describe("HtmlConverter", () => {
           url: "http://www.example.com/",
           properties: { size: { width: 8.3, height: 11.7 } },
         });
-        expect(mockFormDataAppend).toBeCalledTimes(3);
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when emulatedMediaType parameter is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          url: "http://www.example.com/",
+          emulatedMediaType: "screen",
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
+    describe("when all parameters are passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          url: "http://www.example.com/",
+          header: "path/to/header.html",
+          footer: "path/to/footer.html",
+          pdfFormat: PdfFormat.A_1a,
+          emulatedMediaType: "screen",
+          properties: { size: { width: 8.3, height: 11.7 } },
+        });
+        expect(mockFormDataAppend).toHaveBeenCalledTimes(7);
         expect(buffer).toEqual(Buffer.from("content"));
       });
     });
@@ -64,7 +131,7 @@ describe("HtmlConverter", () => {
       it("should throw an error", async () => {
         await expect(() =>
           converter.convert({ url: "invalid url" })
-        ).rejects.toThrow("Invalid URL: invalid url");
+        ).rejects.toThrow("Invalid URL");
       });
     });
 

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

@@ -1,41 +1,69 @@
+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 { PageProperties } from "../interfaces/converter.types";
+import {
+  EmulatedMediaType,
+  PageProperties,
+} from "../interfaces/converter.types";
 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);
   }
 
   async convert({
     url,
+    header,
+    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> {
-    try {
-      const _url = new URL(url);
-      const data = new FormData();
-      if (pdfFormat) {
-        data.append("pdfFormat", pdfFormat);
-      }
-      data.append("url", _url.href);
-      if (properties) {
-        ConverterUtils.injectPageProperties(data, properties);
-      }
-      return GotenbergUtils.fetch(this.endpoint, data);
-    } catch (error) {
-      throw error;
-    }
+    const _url = new URL(url);
+    const data = new FormData();
+
+    data.append("url", _url.href);
+
+    ConverterUtils.customize(data, {
+      header,
+      footer,
+      properties,
+      pdfFormat,
+      pdfUA,
+      emulatedMediaType,
+      waitDelay,
+      waitForExpression,
+      userAgent,
+      extraHttpHeaders,
+      failOnConsoleExceptions,
+    });
+
+    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,7 +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)
+      );
+    }
+  }
 }