chromiumly 2.2.0 → 2.4.0

package/src/chromium/converters/html.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 HtmlConverter extends Converter implements IConverter {
+export class HtmlConverter extends Converter {
   constructor() {
     super(ChromiumRoute.HTML);
   }
@@ -23,41 +22,49 @@ export class HtmlConverter extends Converter implements IConverter {
     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> {
-    await promises.access(html, constants.R_OK);
     const data = new FormData();
 
-    if (pdfFormat) {
-      data.append("pdfFormat", pdfFormat);
+    if (Buffer.isBuffer(html)) {
+      data.append("files", html, "index.html");
+    } else {
+      await promises.access(html, constants.R_OK);
+      data.append("files", createReadStream(html), "index.html");
     }
 
-    data.append("index.html", createReadStream(html));
-
-    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/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,43 @@ 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 (Buffer.isBuffer(html)) {
+      data.append("files", html, "index.html");
+    } else {
+      await promises.access(html, constants.R_OK);
+      data.append("files", createReadStream(html), "index.html");
     }
 
-    if (emulatedMediaType) {
-      data.append("emulatedMediaType", emulatedMediaType);
+    if (Buffer.isBuffer(markdown)) {
+      data.append("files", createReadStream(markdown), "file.md");
+    } else {
+      await promises.access(markdown, constants.R_OK);
+      data.append("file.md", createReadStream(markdown));
     }
 
-    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/tests/html.converter.test.ts

@@ -44,6 +44,17 @@ describe("HtmlConverter", () => {
       });
     });
 
+    describe("when buffer is passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: Buffer.from("html"),
+        });
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
     describe("when pdf format parameter is passed", () => {
       it("should return a buffer", async () => {
         mockPromisesAccess.mockResolvedValue();

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

@@ -35,7 +35,7 @@ describe("MarkdownConverter", () => {
         .mockImplementation((file) => file);
     });
 
-    describe("when file exists", () => {
+    describe("when files exist", () => {
       it("should return a buffer", async () => {
         mockPromisesAccess.mockResolvedValue();
         mockFetch.mockResolvedValue(new Response("content"));
@@ -47,6 +47,18 @@ describe("MarkdownConverter", () => {
       });
     });
 
+    describe("when buffers passed", () => {
+      it("should return a buffer", async () => {
+        mockPromisesAccess.mockResolvedValue();
+        mockFetch.mockResolvedValue(new Response("content"));
+        const buffer = await converter.convert({
+          html: Buffer.from("html"),
+          markdown: Buffer.from("markdown"),
+        });
+        expect(buffer).toEqual(Buffer.from("content"));
+      });
+    });
+
     describe("when pdf format parameter is passed", () => {
       it("should return a buffer", async () => {
         mockPromisesAccess.mockResolvedValue();

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 | Buffer;
+  footer?: PathLike | Buffer;
+  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,68 @@ 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) {
+      const { header } = options;
+      if (Buffer.isBuffer(header)) {
+        data.append("files", header, "header.html");
+      } else {
+        await promises.access(options.header, constants.R_OK);
+        data.append("files", createReadStream(options.header), "header.html");
+      }
+    }
+
+    if (options.footer) {
+      const { footer } = options;
+      if (Buffer.isBuffer(footer)) {
+        data.append("files", footer, "footer.html");
+      } else {
+        await promises.access(options.footer, constants.R_OK);
+        data.append("files", createReadStream(options.footer), "footer.html");
+      }
+    }
+
+    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)
+      );
+    }
+  }
 }