feat: add custom http headers support (#512)

.husky/commit-msg

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 npx --no -- commitlint --edit ${1}

README.md

@@ -143,6 +143,26 @@ Chromiumly.configure({
 });
 ```
 
+### Advanced Authentication with Custom HTTP Headers
+
+To implement advanced authentication or add custom HTTP headers to your requests, you can use the `customHttpHeaders` option within the `configure` method. This allows you to pass additional headers, such as authentication tokens or custom metadata, with each API call.
+
+For example, you can include a Bearer token for authentication along with a custom header as follows:
+
+```typescript
+const token = await generateToken();
+
+Chromiumly.configure({
+  endpoint: "http://localhost:3000",
+  customHttpHeaders: {
+    Authorization: `Bearer ${token}`,
+    "X-Custom-Header": "value",
+  },
+});
+```
+
+## Modules
+
 ## Modules
 
 Chromiumly introduces different classes that serve as wrappers to

src/chromium/converters/html.converter.ts

@@ -108,7 +108,8 @@ export class HtmlConverter extends Converter {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/chromium/converters/markdown.converter.ts

@@ -103,7 +103,8 @@ export class MarkdownConverter extends Converter {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/chromium/converters/url.converter.ts

@@ -100,7 +100,8 @@ export class UrlConverter extends Converter {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/chromium/screenshots/html.screenshot.ts

@@ -81,7 +81,8 @@ export class HtmlScreenshot extends Screenshot {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/chromium/screenshots/markdown.screenshot.ts

@@ -85,7 +85,8 @@ export class MarkdownScreenshot extends Screenshot {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/chromium/screenshots/url.screenshot.ts

@@ -82,7 +82,8 @@ export class UrlScreenshot extends Screenshot {
             this.endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/common/gotenberg.utils.ts

@@ -29,17 +29,23 @@ export class GotenbergUtils {
      * @param {string} endpoint - The Gotenberg endpoint URL.
      * @param {string} username - The username for basic authentication.
      * @param {string} password - The password for basic authentication.
+     * @param {Record<string, string>} [customHttpHeaders] - Custom HTTP headers to be sent with the request.
      * @param {FormData} data - The FormData object to be sent in the POST request.
+     * @param {Record<string, string>} customHeaders - List of custom headers to include in the fetch
      * @returns {Promise<Buffer>} A Promise that resolves to the response body as a Buffer.
      * @throws {Error} Throws an error if the HTTP response status is not OK.
      */
     public static async fetch(
         endpoint: string,
         data: FormData,
         username?: string,
-        password?: string
+        password?: string,
+        customHttpHeaders?: Record<string, string>
     ): Promise<Buffer> {
-        const headers: Record<string, string> = { ...data.getHeaders() };
+        const headers: Record<string, string> = {
+            ...data.getHeaders(),
+            ...customHttpHeaders
+        };
 
         if (username && password) {
             const authHeader =

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

@@ -41,17 +41,38 @@ describe('GotenbergUtils', () => {
         const endpoint = 'http://localhost:3000/forms/chromium/convert/html';
         const basicAuthUsername = 'username';
         const basicAuthPassword = 'pass';
+        const customHttpHeaders = { 'X-Custom-Header': 'value' };
 
         describe('when fetch request succeeds', () => {
-            it('should return a buffer', async () => {
+            it('should return a buffer and send correct headers', async () => {
                 mockFetch.mockResolvedValueOnce(new Response('content'));
+
                 const response = await GotenbergUtils.fetch(
                     endpoint,
                     data,
                     basicAuthUsername,
-                    basicAuthPassword
+                    basicAuthPassword,
+                    customHttpHeaders
                 );
+
                 await expect(response).toEqual(Buffer.from('content'));
+
+                expect(mockFetch).toHaveBeenCalledWith(
+                    endpoint,
+                    expect.objectContaining({
+                        method: 'post',
+                        headers: expect.objectContaining({
+                            Authorization: `Basic ${Buffer.from(
+                                `${basicAuthUsername}:${basicAuthPassword}`
+                            ).toString('base64')}`,
+                            'X-Custom-Header': 'value',
+                            'content-type': expect.stringMatching(
+                                /^multipart\/form-data; boundary=/
+                            )
+                        }),
+                        body: expect.any(Object)
+                    })
+                );
             });
         });
 
@@ -68,7 +89,8 @@ describe('GotenbergUtils', () => {
                             endpoint,
                             data,
                             basicAuthUsername,
-                            basicAuthPassword
+                            basicAuthPassword,
+                            customHttpHeaders
                         )
                     ).rejects.toThrow(errorMessage);
                 });
@@ -90,7 +112,8 @@ describe('GotenbergUtils', () => {
                             endpoint,
                             data,
                             basicAuthUsername,
-                            basicAuthPassword
+                            basicAuthPassword,
+                            customHttpHeaders
                         )
                     ).rejects.toThrow('500 Internal server error');
                 });

src/libre-office/libre-office.ts

@@ -62,7 +62,8 @@ export class LibreOffice {
             endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 }

src/main.config.ts

@@ -53,6 +53,12 @@ export class Chromiumly {
     private static gotenbergApiBasicAuthPassword: string | undefined =
         Gotenberg.password;
 
+    /**
+     * Custom HTTP headers to be sent with each request.
+     * @type {Record<string, string> | undefined}
+     */
+    private static customHttpHeaders: Record<string, string> | undefined;
+
     /**
      * The path for Chromium-related conversions.
      * @type {string}
@@ -113,11 +119,13 @@ export class Chromiumly {
      * @param {string} config.endpoint - The Gotenberg service endpoint.
      * @param {string} [config.username] - The username for basic authentication.
      * @param {string} [config.password] - The password for basic authentication.
+     * @param {Record<string, string>} [config.customHttpHeaders] - Custom HTTP headers to be sent with each request.
      */
     public static configure(config: {
         endpoint: string;
         username?: string;
         password?: string;
+        customHttpHeaders?: Record<string, string>;
     }): void {
         this.gotenbergEndpoint = config.endpoint;
 
@@ -127,6 +135,9 @@ export class Chromiumly {
         if (config.password !== undefined) {
             this.gotenbergApiBasicAuthPassword = config.password;
         }
+        if (config.customHttpHeaders !== undefined) {
+            this.customHttpHeaders = config.customHttpHeaders;
+        }
     }
 
     /**
@@ -156,4 +167,12 @@ export class Chromiumly {
     public static getGotenbergApiBasicAuthPassword(): string | undefined {
         return this.gotenbergApiBasicAuthPassword;
     }
+
+    /**
+     * Gets the custom HTTP headers.
+     * @returns {Record<string, string> | undefined}
+     */
+    public static getCustomHttpHeaders(): Record<string, string> | undefined {
+        return this.customHttpHeaders;
+    }
 }

src/pdf-engines/pdf-engines.ts

@@ -54,7 +54,8 @@ export class PDFEngines {
             endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 
@@ -93,7 +94,8 @@ export class PDFEngines {
             endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 
@@ -116,7 +118,8 @@ export class PDFEngines {
             endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }
 
@@ -145,7 +148,8 @@ export class PDFEngines {
             endpoint,
             data,
             Chromiumly.getGotenbergApiBasicAuthUsername(),
-            Chromiumly.getGotenbergApiBasicAuthPassword()
+            Chromiumly.getGotenbergApiBasicAuthPassword(),
+            Chromiumly.getCustomHttpHeaders()
         );
     }