chromiumly 2.6.0 → 2.7.0

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

@@ -1,138 +1,162 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import {createReadStream} from "fs";
-import FormData from "form-data";
-import fetch from "node-fetch";
+import { createReadStream } from 'fs';
+import FormData from 'form-data';
+import fetch from 'node-fetch';
 
-import {PdfFormat} from "../../../common";
-import {UrlConverter} from "../url.converter";
+import { PdfFormat } from '../../../common';
+import { UrlConverter } from '../url.converter';
 
-const {Response} = jest.requireActual("node-fetch");
-jest.mock("node-fetch", () => jest.fn());
+const { Response } = jest.requireActual('node-fetch');
+jest.mock('node-fetch', () => jest.fn());
 
-describe("HtmlConverter", () => {
+describe('HtmlConverter', () => {
     const converter = new UrlConverter();
 
-    describe("endpoint", () => {
-        it("should route to Chromium HTML route", () => {
+    describe('endpoint', () => {
+        it('should route to Chromium HTML route', () => {
             expect(converter.endpoint).toEqual(
-                "http://localhost:3000/forms/chromium/convert/url"
+                'http://localhost:3000/forms/chromium/convert/url'
             );
         });
     });
 
-    describe("convert", () => {
+    describe('convert', () => {
         const mockFetch = fetch as jest.MockedFunction<typeof fetch>;
-        const mockFormDataAppend = jest.spyOn(FormData.prototype, "append");
+        const mockFormDataAppend = jest.spyOn(FormData.prototype, 'append');
 
         beforeEach(() => {
-            (createReadStream as jest.Mock) = jest.fn()
+            (createReadStream as jest.Mock) = jest.fn();
         });
 
         afterEach(() => {
             jest.resetAllMocks();
         });
 
-        describe("when URL is valid", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValueOnce(new Response("content"));
+        describe('when URL is valid', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
+                    url: 'http://www.example.com/'
                 });
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when header parameter is passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValueOnce(new Response("content"));
+        describe('when header parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    header: Buffer.from("header"),
+                    url: 'http://www.example.com/',
+                    header: Buffer.from('header')
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when footer parameter is passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValueOnce(new Response("content"));
+        describe('when footer parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    footer: Buffer.from("footer"),
+                    url: 'http://www.example.com/',
+                    footer: Buffer.from('footer')
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when pdf format parameter is passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValueOnce(new Response("content"));
+        describe('when pdf format parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    pdfFormat: PdfFormat.A_3b,
+                    url: 'http://www.example.com/',
+                    pdfFormat: PdfFormat.A_3b
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when page properties parameter is passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValueOnce(new Response("content"));
+        describe('when page properties parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValueOnce(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    properties: {size: {width: 8.3, height: 11.7}},
+                    url: 'http://www.example.com/',
+                    properties: { size: { width: 8.3, height: 11.7 } }
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(3);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when emulatedMediaType parameter is passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValue(new Response("content"));
+        describe('when emulatedMediaType parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    emulatedMediaType: "screen",
+                    url: 'http://www.example.com/',
+                    emulatedMediaType: 'screen'
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when all parameters are passed", () => {
-            it("should return a buffer", async () => {
-                mockFetch.mockResolvedValue(new Response("content"));
+        describe('when failOnHttpStatusCodes parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
                 const buffer = await converter.convert({
-                    url: "http://www.example.com/",
-                    header: Buffer.from("header"),
-                    footer: Buffer.from("footer"),
+                    url: 'http://www.example.com/',
+                    failOnHttpStatusCodes: [499, 599]
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when skipNetworkIdleEvent parameter is passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await converter.convert({
+                    url: 'http://www.example.com/',
+                    skipNetworkIdleEvent: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                expect(buffer).toEqual(Buffer.from('content'));
+            });
+        });
+
+        describe('when all parameters are passed', () => {
+            it('should return a buffer', async () => {
+                mockFetch.mockResolvedValue(new Response('content'));
+                const buffer = await converter.convert({
+                    url: 'http://www.example.com/',
+                    header: Buffer.from('header'),
+                    footer: Buffer.from('footer'),
                     pdfFormat: PdfFormat.A_1a,
-                    emulatedMediaType: "screen",
-                    properties: {size: {width: 8.3, height: 11.7}},
+                    emulatedMediaType: 'screen',
+                    properties: { size: { width: 8.3, height: 11.7 } }
                 });
                 expect(mockFormDataAppend).toHaveBeenCalledTimes(7);
-                expect(buffer).toEqual(Buffer.from("content"));
+                expect(buffer).toEqual(Buffer.from('content'));
             });
         });
 
-        describe("when URL is invalid", () => {
-            it("should throw an error", async () => {
+        describe('when URL is invalid', () => {
+            it('should throw an error', async () => {
                 await expect(() =>
-                    converter.convert({url: "invalid url"})
-                ).rejects.toThrow("Invalid URL");
+                    converter.convert({ url: 'invalid url' })
+                ).rejects.toThrow('Invalid URL');
             });
         });
 
-        describe("when fetch request fails", () => {
-            it("should throw an error", async () => {
+        describe('when fetch request fails', () => {
+            it('should throw an error', async () => {
                 const errorMessage =
-                    "FetchError: request to http://localhost:3000/forms/chromium/convert/html failed";
+                    'FetchError: request to http://localhost:3000/forms/chromium/convert/html failed';
                 mockFetch.mockRejectedValueOnce(new Error(errorMessage));
                 await expect(() =>
-                    converter.convert({url: "http://www.example.com/"})
+                    converter.convert({ url: 'http://www.example.com/' })
                 ).rejects.toThrow(errorMessage);
             });
         });

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

@@ -1,13 +1,11 @@
-import {URL} from "url";
-import FormData from "form-data";
-import {GotenbergUtils, PdfFormat, PathLikeOrReadStream} from "../../common";
-import {
-    EmulatedMediaType,
-    PageProperties,
-} from "../interfaces/converter.types";
-import {ConverterUtils} from "../utils/converter.utils";
-import {Converter} from "./converter";
-import {ChromiumRoute} from "../../main.config";
+import { URL } from 'url';
+import FormData from 'form-data';
+import { GotenbergUtils, PdfFormat, PathLikeOrReadStream } from '../../common';
+import { PageProperties } from '../interfaces/converter.types';
+import { ConverterUtils } from '../utils/converter.utils';
+import { Converter } from './converter';
+import { ChromiumRoute } from '../../main.config';
+import { EmulatedMediaType } from '../interfaces/common.types';
 
 /**
  * Class representing a URL converter that extends the base Converter class.
@@ -39,23 +37,27 @@ export class UrlConverter extends Converter {
      * @param {string} [options.waitForExpression] - JavaScript expression to wait for before completing the conversion.
      * @param {string} [options.userAgent] - User agent string to use during the conversion.
      * @param {Record<string, string>} [options.extraHttpHeaders] - Additional HTTP headers for the conversion.
+     * @param {number[]} [options.failOnHttpStatusCodes] - Whether to fail on HTTP status code.
      * @param {boolean} [options.failOnConsoleExceptions] - Whether to fail on console exceptions during conversion.
+     * @param {boolean} [options.skipNetworkIdleEvent] - Whether to skip network idle event.
      * @returns {Promise<Buffer>} A Promise resolving to the converted PDF content as a Buffer.
      */
     async convert({
-                      url,
-                      header,
-                      footer,
-                      properties,
-                      pdfFormat,
-                      pdfUA,
-                      emulatedMediaType,
-                      waitDelay,
-                      waitForExpression,
-                      userAgent,
-                      extraHttpHeaders,
-                      failOnConsoleExceptions,
-                  }: {
+        url,
+        header,
+        footer,
+        properties,
+        pdfFormat,
+        pdfUA,
+        emulatedMediaType,
+        waitDelay,
+        waitForExpression,
+        userAgent,
+        extraHttpHeaders,
+        failOnHttpStatusCodes,
+        failOnConsoleExceptions,
+        skipNetworkIdleEvent
+    }: {
         url: string;
         header?: PathLikeOrReadStream;
         footer?: PathLikeOrReadStream;
@@ -67,12 +69,14 @@ export class UrlConverter extends Converter {
         waitForExpression?: string;
         userAgent?: string;
         extraHttpHeaders?: Record<string, string>;
+        failOnHttpStatusCodes?: number[];
         failOnConsoleExceptions?: boolean;
+        skipNetworkIdleEvent?: boolean;
     }): Promise<Buffer> {
         const _url = new URL(url);
         const data = new FormData();
 
-        data.append("url", _url.href);
+        data.append('url', _url.href);
 
         await ConverterUtils.customize(data, {
             header,
@@ -85,9 +89,11 @@ export class UrlConverter extends Converter {
             waitForExpression,
             userAgent,
             extraHttpHeaders,
+            failOnHttpStatusCodes,
             failOnConsoleExceptions,
+            skipNetworkIdleEvent
         });
 
         return GotenbergUtils.fetch(this.endpoint, data);
     }
-}
+}

package/src/chromium/index.ts

@@ -1,3 +1,3 @@
-export {HtmlConverter} from "./converters/html.converter";
-export {MarkdownConverter} from "./converters/markdown.converter";
-export {UrlConverter} from "./converters/url.converter";
+export { HtmlConverter } from './converters/html.converter';
+export { MarkdownConverter } from './converters/markdown.converter';
+export { UrlConverter } from './converters/url.converter';

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

@@ -0,0 +1,15 @@
+import { PathLikeOrReadStream } from '../../common';
+
+export type EmulatedMediaType = 'screen' | 'print';
+
+export type ChromiumOptions = {
+    header?: PathLikeOrReadStream;
+    footer?: PathLikeOrReadStream;
+    emulatedMediaType?: EmulatedMediaType;
+    waitDelay?: string; // Duration (e.g, '5s') to wait when loading an HTML document before convertion.
+    waitForExpression?: string; // JavaScript's expression to wait before converting an HTML document into PDF until it returns true.
+    extraHttpHeaders?: Record<string, string>;
+    failOnHttpStatusCodes?: number[]; // Return a 409 Conflict response if the HTTP status code is in the list (default [499,599])
+    failOnConsoleExceptions?: boolean; // Return a 409 Conflict response if there are exceptions in the Chromium console (default false)
+    skipNetworkIdleEvent?: boolean; // Do not wait for Chromium network to be idle (default false)
+};

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

@@ -1,4 +1,5 @@
-import {PathLikeOrReadStream, PdfFormat} from "../../common";
+import { PdfFormat } from '../../common';
+import { ChromiumOptions } from './common.types';
 
 type PageSize = {
     width: number; // Paper width, in inches (default 8.5)
@@ -13,6 +14,7 @@ type PageMargins = {
 };
 
 export type PageProperties = {
+    singlePage?: boolean; // Print the entire content in one single page (default false)
     size?: PageSize;
     margins?: PageMargins;
     preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
@@ -23,19 +25,9 @@ export type PageProperties = {
     nativePageRanges?: { from: number; to: number }; // Page ranges to print
 };
 
-export type EmulatedMediaType = "screen" | "print";
-
-
-export type ConversionOptions = {
-    header?: PathLikeOrReadStream;
-    footer?: PathLikeOrReadStream;
+export type ConversionOptions = ChromiumOptions & {
     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's 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,12 +1,10 @@
-import {constants, createReadStream, promises} from "fs";
-import FormData from "form-data";
+import FormData from 'form-data';
 
 import {
     ConversionOptions,
-    PageProperties,
-} from "../interfaces/converter.types";
-import {GotenbergUtils, PathLikeOrReadStream} from "../../common";
-import {ReadStream} from "fs";
+    PageProperties
+} from '../interfaces/converter.types';
+import { GotenbergUtils } from '../../common';
 
 /**
  * Utility class for handling common tasks related to conversion.
@@ -22,94 +20,86 @@ export class ConverterUtils {
         data: FormData,
         pageProperties: PageProperties
     ): void {
+        if (pageProperties.singlePage) {
+            data.append('singlePage', String(pageProperties.singlePage));
+        }
+
         if (pageProperties.size) {
             GotenbergUtils.assert(
-                pageProperties.size.width >= 1.0 && pageProperties.size.height >= 1.5,
-                "size is smaller than the minimum printing requirements (i.e. 1.0 x 1.5 in)"
+                pageProperties.size.width >= 1.0 &&
+                    pageProperties.size.height >= 1.5,
+                'size is smaller than the minimum printing requirements (i.e. 1.0 x 1.5 in)'
             );
 
-            data.append("paperWidth", pageProperties.size.width);
-            data.append("paperHeight", pageProperties.size.height);
+            data.append('paperWidth', pageProperties.size.width);
+            data.append('paperHeight', pageProperties.size.height);
         }
 
         if (pageProperties.margins) {
             GotenbergUtils.assert(
                 pageProperties.margins.top >= 0 &&
-                pageProperties.margins.bottom >= 0 &&
-                pageProperties.margins.left >= 0 &&
-                pageProperties.margins.left >= 0,
-                "negative margins are not allowed"
+                    pageProperties.margins.bottom >= 0 &&
+                    pageProperties.margins.left >= 0 &&
+                    pageProperties.margins.left >= 0,
+                'negative margins are not allowed'
             );
 
-            data.append("marginTop", pageProperties.margins.top);
-            data.append("marginBottom", pageProperties.margins.bottom);
-            data.append("marginLeft", pageProperties.margins.left);
-            data.append("marginRight", pageProperties.margins.right);
+            data.append('marginTop', pageProperties.margins.top);
+            data.append('marginBottom', pageProperties.margins.bottom);
+            data.append('marginLeft', pageProperties.margins.left);
+            data.append('marginRight', pageProperties.margins.right);
         }
 
         if (pageProperties.preferCssPageSize) {
             data.append(
-                "preferCssPageSize",
+                'preferCssPageSize',
                 String(pageProperties.preferCssPageSize)
             );
         }
 
         if (pageProperties.printBackground) {
-            data.append("printBackground", String(pageProperties.printBackground));
+            data.append(
+                'printBackground',
+                String(pageProperties.printBackground)
+            );
         }
 
         if (pageProperties.omitBackground) {
-            data.append("omitBackground", String(pageProperties.omitBackground));
+            data.append(
+                'omitBackground',
+                String(pageProperties.omitBackground)
+            );
         }
 
         if (pageProperties.landscape) {
-            data.append("landscape", String(pageProperties.landscape));
+            data.append('landscape', String(pageProperties.landscape));
         }
 
         if (pageProperties.scale) {
             GotenbergUtils.assert(
                 pageProperties.scale >= 0.1 && pageProperties.scale <= 2.0,
-                "scale is outside of [0.1 - 2] range"
+                'scale is outside of [0.1 - 2] range'
             );
 
-            data.append("scale", pageProperties.scale);
+            data.append('scale', pageProperties.scale);
         }
 
         if (pageProperties.nativePageRanges) {
             GotenbergUtils.assert(
                 pageProperties.nativePageRanges.from > 0 &&
-                pageProperties.nativePageRanges.to > 0 &&
-                pageProperties.nativePageRanges.to >=
-                pageProperties.nativePageRanges.from,
-                "page ranges syntax error"
+                    pageProperties.nativePageRanges.to > 0 &&
+                    pageProperties.nativePageRanges.to >=
+                        pageProperties.nativePageRanges.from,
+                'page ranges syntax error'
             );
 
             data.append(
-                "nativePageRanges",
+                'nativePageRanges',
                 `${pageProperties.nativePageRanges.from}-${pageProperties.nativePageRanges.to}`
             );
         }
     }
 
-    /**
-     * Adds a file to the FormData object.
-     *
-     * @param {FormData} data - The FormData object to which the file will be added.
-     * @param {PathLikeOrReadStream} file - The file to be added (either a PathLike or a ReadStream).
-     * @param {string} name - The name to be used for the file in the FormData.
-     * @returns {Promise<void>} A Promise that resolves once the file has been added.
-     */
-    public static async addFile(data: FormData, file: PathLikeOrReadStream, name: string) {
-        if (Buffer.isBuffer(file)) {
-            data.append("files", file, name);
-        } else if (file instanceof ReadStream) {
-            data.append("files", file, name);
-        } else {
-            await promises.access(file, constants.R_OK);
-            data.append("files", createReadStream(file), name);
-        }
-    }
-
     /**
      * Customizes the FormData object based on the provided conversion options.
      *
@@ -122,25 +112,25 @@ export class ConverterUtils {
         options: ConversionOptions
     ): Promise<void> {
         if (options.pdfFormat) {
-            data.append("pdfa", options.pdfFormat);
+            data.append('pdfa', options.pdfFormat);
         }
 
         if (options.pdfUA) {
-            data.append("pdfua", String(options.pdfUA));
+            data.append('pdfua', String(options.pdfUA));
         }
 
         if (options.header) {
-            const {header} = options;
-            await ConverterUtils.addFile(data, header, "header.html")
+            const { header } = options;
+            await GotenbergUtils.addFile(data, header, 'header.html');
         }
 
         if (options.footer) {
-            const {footer} = options;
-            await ConverterUtils.addFile(data, footer, "footer.html")
+            const { footer } = options;
+            await GotenbergUtils.addFile(data, footer, 'footer.html');
         }
 
         if (options.emulatedMediaType) {
-            data.append("emulatedMediaType", options.emulatedMediaType);
+            data.append('emulatedMediaType', options.emulatedMediaType);
         }
 
         if (options.properties) {
@@ -148,26 +138,43 @@ export class ConverterUtils {
         }
 
         if (options.waitDelay) {
-            data.append("waitDelay", options.waitDelay);
+            data.append('waitDelay', options.waitDelay);
         }
 
         if (options.waitForExpression) {
-            data.append("waitForExpression", options.waitForExpression);
+            data.append('waitForExpression', options.waitForExpression);
         }
 
         if (options.userAgent) {
-            data.append("userAgent", options.userAgent);
+            data.append('userAgent', options.userAgent);
         }
 
         if (options.extraHttpHeaders) {
-            data.append("extraHttpHeaders", JSON.stringify(options.extraHttpHeaders));
+            data.append(
+                'extraHttpHeaders',
+                JSON.stringify(options.extraHttpHeaders)
+            );
+        }
+
+        if (options.failOnHttpStatusCodes) {
+            data.append(
+                'failOnHttpStatusCodes',
+                JSON.stringify(options.failOnHttpStatusCodes)
+            );
         }
 
         if (options.failOnConsoleExceptions) {
             data.append(
-                "failOnConsoleExceptions",
+                'failOnConsoleExceptions',
                 String(options.failOnConsoleExceptions)
             );
         }
+
+        if (options.skipNetworkIdleEvent) {
+            data.append(
+                'skipNetworkIdleEvent',
+                String(options.skipNetworkIdleEvent)
+            );
+        }
     }
 }