chromiumly 2.7.0 → 2.9.0

package/src/chromium/utils/screenshot.utils.ts

@@ -0,0 +1,115 @@
+import {
+    ImageProperties,
+    ScreenshotOptions
+} from './../interfaces/screenshot.types';
+import FormData from 'form-data';
+
+import { GotenbergUtils } from '../../common';
+
+/**
+ * Utility class for handling common tasks related to screenshot.
+ */
+export class ScreenshotUtils {
+    /**
+     * Adds page properties to the FormData object based on the provided imageProperties.
+     *
+     * @param {FormData} data - The FormData object to which page properties will be added.
+     * @param {ImageProperties} imageProperties - The page properties to be added to the FormData.
+     */
+    public static addImageProperties(
+        data: FormData,
+        imageProperties: ImageProperties
+    ): void {
+        data.append('format', imageProperties.format);
+
+        if (imageProperties.quality) {
+            GotenbergUtils.assert(
+                imageProperties.format === 'jpeg',
+                'Compression quality is exclusively supported for JPEG format.'
+            );
+            GotenbergUtils.assert(
+                imageProperties.quality >= 0 && imageProperties.quality <= 100,
+                'Invalid compression quality. Please provide a value between 0 and 100.'
+            );
+
+            data.append('quality', imageProperties.quality);
+        }
+
+        if (imageProperties.omitBackground) {
+            data.append(
+                'omitBackground',
+                String(imageProperties.omitBackground)
+            );
+        }
+    }
+
+    /**
+     * Customizes the FormData object based on the provided screenshot options.
+     *
+     * @param {FormData} data - The FormData object to be customized.
+     * @param {ScreenshotOptions} options - The screenshot options to apply to the FormData.
+     * @returns {Promise<void>} A Promise that resolves once the customization is complete.
+     */
+    public static async customize(
+        data: FormData,
+        options: ScreenshotOptions
+    ): Promise<void> {
+        if (options.header) {
+            const { header } = options;
+            await GotenbergUtils.addFile(data, header, 'header.html');
+        }
+
+        if (options.footer) {
+            const { footer } = options;
+            await GotenbergUtils.addFile(data, footer, 'footer.html');
+        }
+
+        if (options.emulatedMediaType) {
+            data.append('emulatedMediaType', options.emulatedMediaType);
+        }
+
+        if (options.properties) {
+            ScreenshotUtils.addImageProperties(data, options.properties);
+        }
+
+        if (options.waitDelay) {
+            data.append('waitDelay', options.waitDelay);
+        }
+
+        if (options.waitForExpression) {
+            data.append('waitForExpression', options.waitForExpression);
+        }
+
+        if (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',
+                String(options.failOnConsoleExceptions)
+            );
+        }
+
+        if (options.skipNetworkIdleEvent) {
+            data.append(
+                'skipNetworkIdleEvent',
+                String(options.skipNetworkIdleEvent)
+            );
+        }
+
+        if (options.optimizeForSpeed) {
+            data.append('optimizeForSpeed', String(options.optimizeForSpeed));
+        }
+    }
+}

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

@@ -351,6 +351,19 @@ describe('GotenbergUtils', () => {
             });
         });
 
+        describe('when metadata parameter is passed', () => {
+            it('should append metadata', async () => {
+                await ConverterUtils.customize(data, {
+                    metadata: { Author: 'John Doe' }
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'metadata',
+                    JSON.stringify({ Author: 'John Doe' })
+                );
+            });
+        });
+
         describe('when all options are passed', () => {
             it('should append all options', async () => {
                 await ConverterUtils.customize(data, {
@@ -365,9 +378,12 @@ describe('GotenbergUtils', () => {
                     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
+                    failOnHttpStatusCodes: [499, 599],
+                    skipNetworkIdleEvent: true,
+                    failOnConsoleExceptions: true,
+                    metadata: { Author: 'John Doe' }
                 });
-                expect(mockFormDataAppend).toHaveBeenCalledTimes(12);
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(15);
                 expect(data.append).toHaveBeenNthCalledWith(
                     1,
                     'pdfa',
@@ -423,9 +439,24 @@ describe('GotenbergUtils', () => {
                 );
                 expect(data.append).toHaveBeenNthCalledWith(
                     12,
+                    'failOnHttpStatusCodes',
+                    JSON.stringify([499, 599])
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    13,
                     'failOnConsoleExceptions',
                     'true'
                 );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    14,
+                    'skipNetworkIdleEvent',
+                    'true'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    15,
+                    'metadata',
+                    JSON.stringify({ Author: 'John Doe' })
+                );
             });
         });
     });

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

@@ -0,0 +1,284 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import FormData from 'form-data';
+import { ScreenshotUtils } from './../screenshot.utils';
+
+describe('GotenbergUtils', () => {
+    const mockFormDataAppend = jest.spyOn(FormData.prototype, 'append');
+    const data = new FormData();
+
+    afterEach(() => {
+        jest.resetAllMocks();
+    });
+
+    describe('addImageProperties', () => {
+        describe('Image format', () => {
+            describe('when format parameter is set', () => {
+                it('should append format to data', () => {
+                    ScreenshotUtils.addImageProperties(data, {
+                        format: 'png'
+                    });
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                    expect(data.append).toHaveBeenCalledWith('format', 'png');
+                });
+            });
+        });
+
+        describe('Image background', () => {
+            describe('when omitBackground parameter is set', () => {
+                it('should append omitBackground to data', () => {
+                    ScreenshotUtils.addImageProperties(data, {
+                        format: 'png',
+                        omitBackground: true
+                    });
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                    expect(data.append).toHaveBeenCalledWith('format', 'png');
+                    expect(data.append).toHaveBeenNthCalledWith(
+                        2,
+                        'omitBackground',
+                        'true'
+                    );
+                });
+            });
+        });
+
+        describe('Image quality', () => {
+            describe('when omitBackground parameter is set', () => {
+                it('should append omitBackground to data', () => {
+                    ScreenshotUtils.addImageProperties(data, {
+                        format: 'jpeg',
+                        quality: 50
+                    });
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                    expect(data.append).toHaveBeenCalledWith('format', 'jpeg');
+                    expect(data.append).toHaveBeenNthCalledWith(
+                        2,
+                        'quality',
+                        50
+                    );
+                });
+            });
+        });
+    });
+
+    describe('customize', () => {
+        describe('when no option is passed', () => {
+            it('should not append anything', async () => {
+                await ScreenshotUtils.customize(data, {});
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(0);
+            });
+        });
+
+        describe('when header parameter is passed', () => {
+            it('should append header', async () => {
+                await ScreenshotUtils.customize(data, {
+                    header: Buffer.from('header')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'files',
+                    Buffer.from('header'),
+                    'header.html'
+                );
+            });
+        });
+
+        describe('when footer parameter is passed', () => {
+            it('should append footer', async () => {
+                await ScreenshotUtils.customize(data, {
+                    footer: Buffer.from('footer')
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'files',
+                    Buffer.from('footer'),
+                    'footer.html'
+                );
+            });
+        });
+
+        describe('when emulatedMediaType parameter is passed', () => {
+            it('should append emulatedMediaType', async () => {
+                await ScreenshotUtils.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 ScreenshotUtils.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 ScreenshotUtils.customize(data, {
+                    waitForExpression: "document.readyState === 'complete'"
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'waitForExpression',
+                    "document.readyState === 'complete'"
+                );
+            });
+        });
+
+        describe('when extraHttpHeaders parameter is passed', () => {
+            it('should append extraHttpHeaders', async () => {
+                const extraHttpHeaders = {
+                    'X-Custom-Header': 'value'
+                };
+
+                await ScreenshotUtils.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 ScreenshotUtils.customize(data, {
+                    failOnConsoleExceptions: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'failOnConsoleExceptions',
+                    'true'
+                );
+            });
+        });
+
+        describe('when failOnHttpStatusCodes parameter is passed', () => {
+            it('should append failOnHttpStatusCodes', async () => {
+                await ScreenshotUtils.customize(data, {
+                    failOnHttpStatusCodes: [499, 599]
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'failOnHttpStatusCodes',
+                    JSON.stringify([499, 599])
+                );
+            });
+        });
+
+        describe('when skipNetworkIdleEvent parameter is passed', () => {
+            it('should append skipNetworkIdleEvent', async () => {
+                await ScreenshotUtils.customize(data, {
+                    skipNetworkIdleEvent: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'skipNetworkIdleEvent',
+                    'true'
+                );
+            });
+        });
+
+        describe('when optimizeForSpeed parameter is passed', () => {
+            it('should append optimizeForSpeed', async () => {
+                await ScreenshotUtils.customize(data, {
+                    optimizeForSpeed: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith(
+                    'optimizeForSpeed',
+                    'true'
+                );
+            });
+        });
+
+        describe('when all options are passed', () => {
+            it('should append all options', async () => {
+                await ScreenshotUtils.customize(data, {
+                    header: Buffer.from('header.html'),
+                    footer: Buffer.from('footer.html'),
+                    emulatedMediaType: 'screen',
+                    failOnHttpStatusCodes: [499, 599],
+                    skipNetworkIdleEvent: true,
+                    failOnConsoleExceptions: true,
+                    properties: {
+                        format: 'jpeg',
+                        quality: 50
+                    },
+                    waitDelay: '5s',
+                    waitForExpression: "document.readyState === 'complete'",
+                    extraHttpHeaders: { 'X-Custom-Header': 'value' },
+                    optimizeForSpeed: true
+                });
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(12);
+                expect(data.append).toHaveBeenNthCalledWith(
+                    1,
+                    'files',
+                    Buffer.from('header.html'),
+                    'header.html'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    2,
+                    'files',
+                    Buffer.from('footer.html'),
+                    'footer.html'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    3,
+                    'emulatedMediaType',
+                    'screen'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    4,
+                    'format',
+                    'jpeg'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(5, 'quality', 50);
+                expect(data.append).toHaveBeenNthCalledWith(
+                    6,
+                    'waitDelay',
+                    '5s'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    7,
+                    'waitForExpression',
+                    "document.readyState === 'complete'"
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    8,
+                    'extraHttpHeaders',
+                    JSON.stringify({ 'X-Custom-Header': 'value' })
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    9,
+                    'failOnHttpStatusCodes',
+                    JSON.stringify([499, 599])
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    10,
+                    'failOnConsoleExceptions',
+                    'true'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    11,
+                    'skipNetworkIdleEvent',
+                    'true'
+                );
+                expect(data.append).toHaveBeenNthCalledWith(
+                    12,
+                    'optimizeForSpeed',
+                    'true'
+                );
+            });
+        });
+    });
+});

package/src/common/constants.ts

@@ -1,4 +1,8 @@
 export enum PdfFormat {
+    /**
+     * @deprecated Starting from Gotenberg version 7.6, LibreOffice no longer provides support for PDF/A-1a.
+     * @see {@link https://gotenberg.dev/docs/troubleshooting#pdfa-1a}
+     */
     A_1a = 'PDF/A-1a',
     A_2b = 'PDF/A-2b',
     A_3b = 'PDF/A-3b'

package/src/common/index.ts

@@ -1,3 +1,3 @@
 export { PdfFormat } from './constants';
 export { GotenbergUtils } from './gotenberg.utils';
-export { PathLikeOrReadStream } from './types';
+export { PathLikeOrReadStream, Metadata } from './types';

package/src/common/tests/gotenberg.utils.test.ts

@@ -1,3 +1,5 @@
+import { createReadStream, promises } from 'fs';
+import path from 'path';
 import fetch from 'node-fetch';
 import FormData from 'form-data';
 
@@ -8,6 +10,9 @@ const { Response, FetchError } = jest.requireActual('node-fetch');
 jest.mock('node-fetch', () => jest.fn());
 
 describe('GotenbergUtils', () => {
+    const mockFormDataAppend = jest.spyOn(FormData.prototype, 'append');
+    const data = new FormData();
+
     afterEach(() => {
         jest.resetAllMocks();
     });
@@ -75,4 +80,45 @@ describe('GotenbergUtils', () => {
             });
         });
     });
+
+    describe('addFile', () => {
+        const mockPromisesAccess = jest.spyOn(promises, 'access');
+        const __tmp__ = path.resolve(process.cwd(), '__tmp__');
+        const filePath = path.resolve(__tmp__, 'file.html');
+
+        beforeAll(async () => {
+            mockPromisesAccess.mockResolvedValue();
+            await promises.mkdir(path.resolve(__tmp__), { recursive: true });
+            await promises.writeFile(filePath, 'data');
+        });
+
+        afterAll(async () => {
+            await promises.rm(path.resolve(__tmp__), { recursive: true });
+        });
+
+        describe('when file is passed as read stream', () => {
+            it('should append file to data', async () => {
+                const file = createReadStream(filePath);
+                await GotenbergUtils.addFile(data, file, 'file');
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith('files', file, 'file');
+            });
+        });
+
+        describe('when file is passed as path', () => {
+            it('should append file to data', async () => {
+                await GotenbergUtils.addFile(data, filePath, 'file');
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+            });
+        });
+
+        describe('when file is passed as buffer', () => {
+            it('should append file to data', async () => {
+                const file = Buffer.from('data');
+                await GotenbergUtils.addFile(data, file, 'file');
+                expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                expect(data.append).toHaveBeenCalledWith('files', file, 'file');
+            });
+        });
+    });
 });

package/src/common/types.ts

@@ -1,3 +1,7 @@
 import { PathLike, ReadStream } from 'fs';
 
 export type PathLikeOrReadStream = PathLike | ReadStream;
+
+export type Metadata = {
+    [key: string]: boolean | number | string | string[];
+};

package/src/libre-office/utils/constants.ts

@@ -78,5 +78,6 @@ export const LIBRE_OFFICE_EXTENSIONS = [
     'odp',
     'odg',
     'dotx',
-    'xltx'
+    'xltx',
+    'key'
 ];

package/src/main.config.ts

@@ -15,7 +15,9 @@ export enum ChromiumRoute {
  * @enum {string}
  */
 enum PdfEngineRoute {
-    MERGE = 'merge'
+    MERGE = 'merge',
+    READ_METADATA = 'metadata/read',
+    WRITE_METADATA = 'metadata/write'
 }
 
 /**
@@ -42,6 +44,12 @@ export class Chromiumly {
      */
     public static readonly CHROMIUM_CONVERT_PATH = 'forms/chromium/convert';
 
+    /**
+     * The path for Chromium-related screenshots.
+     * @type {string}
+     */
+    public static readonly CHROMIUM_SCREENSHOT_PATH =
+        'forms/chromium/screenshot';
     /**
      * The path for PDF engine-related operations.
      * @type {string}
@@ -69,7 +77,9 @@ export class Chromiumly {
      * @type {Object}
      */
     public static readonly PDF_ENGINE_ROUTES = {
-        merge: PdfEngineRoute.MERGE
+        merge: PdfEngineRoute.MERGE,
+        readMetadata: PdfEngineRoute.READ_METADATA,
+        writeMetadata: PdfEngineRoute.WRITE_METADATA
     };
 
     /**

package/src/main.ts

@@ -1,3 +1,10 @@
 export { PdfFormat } from './common/constants';
-export { HtmlConverter, MarkdownConverter, UrlConverter } from './chromium';
+export {
+    HtmlConverter,
+    HtmlScreenshot,
+    MarkdownConverter,
+    MarkdownScreenshot,
+    UrlConverter,
+    UrlScreenshot
+} from './chromium';
 export { PDFEngine } from './pdf-engines';

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

@@ -4,7 +4,12 @@ import path from 'path';
 import FormData from 'form-data';
 
 import { Chromiumly } from '../main.config';
-import { GotenbergUtils, PathLikeOrReadStream, PdfFormat } from '../common';
+import {
+    GotenbergUtils,
+    PathLikeOrReadStream,
+    PdfFormat,
+    Metadata
+} from '../common';
 import { LibreOfficeUtils, PageProperties } from '../libre-office';
 import { PDFEngineUtils } from './utils/engine.utils';
 
@@ -50,6 +55,10 @@ export class PDFEngine {
     }: {
         files: PathLikeOrReadStream[];
         properties?: PageProperties;
+        /**
+         * @deprecated Starting from Gotenberg version 8.0.0, LibreOffice no longer provides support for pdfFormat.
+         * @see {@link https://github.com/gotenberg/gotenberg/releases/tag/v8.0.0}
+         */
         pdfFormat?: PdfFormat;
         pdfUA?: boolean;
         merge?: boolean;
@@ -79,6 +88,48 @@ export class PDFEngine {
         return GotenbergUtils.fetch(endpoint, data);
     }
 
+    /**
+     * Reads metadata from the provided files.
+     *
+     * @param {PathLikeOrReadStream[]} files An array of PathLikes or ReadStreams to the PDF files.
+     * @returns {Promise<Buffer>} A Promise resolving to the metadata buffer.
+     */
+    public static async readMetadata(
+        files: PathLikeOrReadStream[]
+    ): Promise<Buffer> {
+        const data = new FormData();
+
+        await PDFEngineUtils.addFiles(files, data);
+
+        const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.PDF_ENGINES_PATH}/${Chromiumly.PDF_ENGINE_ROUTES.readMetadata}`;
+
+        return GotenbergUtils.fetch(endpoint, data);
+    }
+
+    /**
+     * Writes metadata to the provided PDF files.
+     *
+     * @param {PathLikeOrReadStream[]} files - An array of PathLikes or ReadStreams to the PDF files.
+     * @param {Metadata} metadata - Metadata to be written.
+     * @returns {Promise<Buffer>} A Promise that resolves to the PDF file containing metadata as a buffer.
+     */
+    public static async writeMetadata({
+        files,
+        metadata
+    }: {
+        files: PathLikeOrReadStream[];
+        metadata: Metadata;
+    }): Promise<Buffer> {
+        const data = new FormData();
+        data.append('metadata', JSON.stringify(metadata));
+
+        await PDFEngineUtils.addFiles(files, data);
+
+        const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.PDF_ENGINES_PATH}/${Chromiumly.PDF_ENGINE_ROUTES.writeMetadata}`;
+
+        return GotenbergUtils.fetch(endpoint, data);
+    }
+
     /**
      * Generates a PDF file from a buffer and saves it to the "__generated__" directory.
      *