chromiumly 1.0.0

package/.github/workflows/publish

@@ -0,0 +1,17 @@
+name: Publish
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: yarn
+      - run: yarn publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Taha Abdelmoutaleb Cherfia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Chromiumly
+
+A lightweight Typescrpit library which interacts with [Gotenberg](https://gotenberg.dev/)'s Chromium module to convert HTML documents to PDF.
+
+## Prerequisites
+
+Before attempting to use Chromiumly, be sure you install [Docker](https://www.docker.com/) if you have not already done so.
+
+After that, you can start a default Docker container of [Gotenberg](https://gotenberg.dev/) as follows:
+
+```bash
+docker run --rm -p 3000:3000 gotenberg/gotenberg:7
+```
+
+## Get Started
+
+### Configuration
+
+Chromiumly supports both [dotenv](https://www.npmjs.com/package/dotenv) and [config](https://www.npmjs.com/package/config) configuration libraries to add Gotenberg endpoint to your project.
+
+#### dotenv
+
+```bash
+GOTENBERG_ENDPOINT=localhost:3000
+```
+
+#### config
+
+```json
+{
+  "gotenberg": {
+    "enpdoint": "localhost:3000"
+  }
+}
+```
+
+### Usage
+
+Chromiumly introduces different classes that serve as wrappers to Gotenberg's Chromium [routes](https://gotenberg.dev/docs/modules/chromium#routes).
+
+Each class comes with two methods :  
+
+#### convert
+
+This method takes either a `url`, an `html` file path or `html` and `markdown` file paths and returns a `buffer` which contains the converted PDF file content.
+
+#### generate
+
+ It is just a generic complementary method that takes the `buffer` returned by the `convert` method, and a chosen `filename` to generate the PDF file.
+
+Please note that all the PDF files can be found `__generated__` folder in the root folder of your project  
+
+### Modules
+
+#### URL
+
+```typescript
+import { UrlConverter } from "chromiumly";
+
+const urlConverter = new UrlConverter();
+const buffer = await urlConverter.convert({
+    url: "https://www.example.com/",
+});
+```
+
+#### HTML
+
+The only requirement is that the file name should be `index.html`.
+
+```typescript
+import { HtmlConverter } from "chromiumly";
+
+const htmlConverter = new HtmlConverter();
+const buffer = await htmlConverter.convert({
+    html: "path/to/index.html",
+});
+
+```
+
+#### Markdown
+
+This route accepts an `index.html` file plus a markdown file.
+
+```typescript
+import { MarkdownConverter } from "chromiumly";
+
+const markdownConverter = new MarkdownConverter();
+const buffer = await markdownConverter.convert({
+    html: "path/to/index.html",
+    markdown: "path/to/file.md",
+});
+```
+
+### Customization
+
+`convert()` method takes an optional `properties` parameter of the following type which dictates how the PDF generated file will look like.
+
+```typescript
+type PageProperties = {
+  size?: {
+    width: number; // Paper width, in inches (default 8.5)
+    height: number; //Paper height, in inches (default 11)
+  };
+  margins?: {
+    top: number; // Top margin, in inches (default 0.39)
+    bottom: number; // Bottom margin, in inches (default 0.39)
+    left: number; // Left margin, in inches (default 0.39)
+    right: number; // Right margin, in inches (default 0.39)
+  };
+  preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
+  printBackground?: boolean; // Print the background graphics (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
+};
+```
+
+### Snippet
+
+The following is a short snippet of how to use the library.
+
+```typescript
+import { UrlConverter } from "chromiumly";
+
+async function run() {
+  const urlConverter = new UrlConverter();
+  const buffer = await urlConverter.convert({
+    url: "https://gotenberg.dev/",
+  });
+
+  await urlConverter.generate("gotenberg.pdf", buffer);
+}
+
+run();
+```

package/dist/main.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlConverter = exports.MarkdownConverter = exports.HtmlConverter = void 0;
+var html_converter_1 = require("./converters/html.converter");
+Object.defineProperty(exports, "HtmlConverter", { enumerable: true, get: function () { return html_converter_1.HtmlConverter; } });
+var markdown_converter_1 = require("./converters/markdown.converter");
+Object.defineProperty(exports, "MarkdownConverter", { enumerable: true, get: function () { return markdown_converter_1.MarkdownConverter; } });
+var url_converter_1 = require("./converters/url.converter");
+Object.defineProperty(exports, "UrlConverter", { enumerable: true, get: function () { return url_converter_1.UrlConverter; } });
+//# sourceMappingURL=main.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "chromiumly",
+  "version": "1.0.0",
+  "description": "A lightweight Typescrpit library which interacts with Gotenberg's Chromium module to convert HTML documents to PDF.",
+  "main": "dist/main.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cherfia/chromiumly.git"
+  },
+  "author": "Taha Cherfia <taha.cherfia@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": "14.x"
+  },
+  "scripts": {
+    "clean": "rm -rf dist build",
+    "lint": "eslint src/ --ext .js,.ts",
+    "build": "yarn clean && tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/config": "^0.0.41",
+    "@types/dotenv": "^8.2.0",
+    "@types/form-data": "^2.5.0",
+    "@types/node": "^17.0.22",
+    "@types/node-fetch": "2",
+    "@typescript-eslint/eslint-plugin": "^5.16.0",
+    "@typescript-eslint/parser": "^5.16.0",
+    "eslint": "^8.11.0",
+    "ts-node": "^10.7.0",
+    "typescript": "^4.6.2"
+  },
+  "dependencies": {
+    "config": "^3.3.7",
+    "dotenv": "^16.0.0",
+    "form-data": "^4.0.0",
+    "node-fetch": "2"
+  }
+}

package/src/common/converter.interface.ts

@@ -0,0 +1,11 @@
+import { PathLike } from "fs";
+
+import { PageProperties } from "./converter.types";
+
+export interface IConverter {
+  convert({
+    ...args
+  }: {
+    [x: string]: string | PathLike | PageProperties;
+  }): Promise<Buffer>;
+}

package/src/common/converter.ts

@@ -0,0 +1,18 @@
+import { promises } from "fs";
+import path from "path";
+
+import { Chromiumly, Route } from "../main.config";
+
+export abstract class Converter {
+  readonly endpoint: string;
+
+  constructor(route: Route) {
+    this.endpoint = `${Chromiumly.endpoint}/${Chromiumly.path}/${Chromiumly.routes[route]}`;
+  }
+
+  async generate(filename: string, buffer: Buffer): Promise<void> {
+    const __generated__ = path.resolve(process.cwd(), "__generated__");
+    await promises.mkdir(path.resolve(__generated__), { recursive: true });
+    await promises.writeFile(path.resolve(__generated__, filename), buffer);
+  }
+}

package/src/common/converter.types.ts

@@ -0,0 +1,21 @@
+type PageSize = {
+  width: number; // Paper width, in inches (default 8.5)
+  height: number; //Paper height, in inches (default 11)
+};
+
+type PageMargins = {
+  top: number; // Top margin, in inches (default 0.39)
+  bottom: number; // Bottom margin, in inches (default 0.39)
+  left: number; // Left margin, in inches (default 0.39)
+  right: number; // Right margin, in inches (default 0.39)
+};
+
+export type PageProperties = {
+  size?: PageSize;
+  margins?: PageMargins;
+  preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
+  printBackground?: boolean; // Print the background graphics (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
+};

package/src/common/converter.utils.ts

@@ -0,0 +1,101 @@
+import FormData from "form-data";
+import fetch from "node-fetch";
+
+import { PageProperties } from "./converter.types";
+
+export class ConverterUtils {
+  private static assert(
+    condition: boolean,
+    message: string
+  ): asserts condition {
+    if (!condition) {
+      throw new Error(message);
+    }
+  }
+
+  public static injectPageProperties(
+    data: FormData,
+    pageProperties: PageProperties
+  ): void {
+    if (pageProperties) {
+      if (pageProperties.size) {
+        ConverterUtils.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)"
+        );
+
+        data.append("paperWidth", pageProperties.size.width);
+        data.append("paperHeight", pageProperties.size.height);
+      }
+
+      if (pageProperties.margins) {
+        ConverterUtils.assert(
+          pageProperties.margins.top >= 0 &&
+            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);
+      }
+
+      if (pageProperties.preferCssPageSize) {
+        data.append(
+          "preferCssPageSize",
+          String(pageProperties.preferCssPageSize)
+        );
+      }
+
+      if (pageProperties.printBackground) {
+        data.append("printBackground", String(pageProperties.printBackground));
+      }
+
+      if (pageProperties.landscape) {
+        data.append("landscape", String(pageProperties.landscape));
+      }
+
+      if (pageProperties.scale) {
+        ConverterUtils.assert(
+          pageProperties.scale >= 0.1 && pageProperties.scale <= 2.0,
+          "scale is outside of [0.1 - 2] range"
+        );
+
+        data.append("scale", pageProperties.scale);
+      }
+
+      if (pageProperties.nativePageRanges) {
+        ConverterUtils.assert(
+          pageProperties.nativePageRanges.from > 0 &&
+            pageProperties.nativePageRanges.to > 0 &&
+            pageProperties.nativePageRanges.to >=
+              pageProperties.nativePageRanges.from,
+          "page ranges syntax error"
+        );
+
+        data.append(
+          "nativePageRanges",
+          `${pageProperties.nativePageRanges.from}-${pageProperties.nativePageRanges.to}`
+        );
+      }
+    }
+  }
+
+  static async fetch(endpoint: string, data: FormData): Promise<Buffer> {
+    const response = await fetch(endpoint, {
+      method: "post",
+      body: data,
+      headers: {
+        ...data.getHeaders(),
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`);
+    }
+    return response.buffer();
+  }
+}

package/src/converters/html.converter.ts

@@ -0,0 +1,30 @@
+import { createReadStream, PathLike } from "fs";
+
+import FormData from "form-data";
+
+import { IConverter } from "../common/converter.interface";
+import { PageProperties } from "../common/converter.types";
+import { ConverterUtils } from "../common/converter.utils";
+import { Converter } from "../common/converter";
+import { Route } from "../main.config";
+
+export class HtmlConverter extends Converter implements IConverter {
+  constructor() {
+    super(Route.HTML);
+  }
+
+  async convert({
+    html,
+    properties,
+  }: {
+    html: PathLike;
+    properties?: PageProperties;
+  }): Promise<Buffer> {
+    const data = new FormData();
+    data.append("index.html", createReadStream(html));
+    if (properties) {
+      ConverterUtils.injectPageProperties(data, properties);
+    }
+    return ConverterUtils.fetch(this.endpoint, data);
+  }
+}

package/src/converters/markdown.converter.ts

@@ -0,0 +1,33 @@
+import { createReadStream, PathLike } from "fs";
+
+import FormData from "form-data";
+
+import { IConverter } from "../common/converter.interface";
+import { PageProperties } from "../common/converter.types";
+import { ConverterUtils } from "../common/converter.utils";
+import { Converter } from "../common/converter";
+import { Route } from "../main.config";
+
+export class MarkdownConverter extends Converter implements IConverter {
+  constructor() {
+    super(Route.MARKDOWN);
+  }
+
+  async convert({
+    html,
+    markdown,
+    properties,
+  }: {
+    html: PathLike;
+    markdown: PathLike;
+    properties?: PageProperties;
+  }): Promise<Buffer> {
+    const data = new FormData();
+    data.append("index.html", createReadStream(html));
+    data.append("file.md", createReadStream(markdown));
+    if (properties) {
+      ConverterUtils.injectPageProperties(data, properties);
+    }
+    return ConverterUtils.fetch(this.endpoint, data);
+  }
+}

package/src/converters/url.converter.ts

@@ -0,0 +1,35 @@
+import { URL } from "url";
+
+import FormData from "form-data";
+
+import { IConverter } from "../common/converter.interface";
+import { PageProperties } from "../common/converter.types";
+import { ConverterUtils } from "../common/converter.utils";
+import { Converter } from "../common/converter";
+import { Route } from "../main.config";
+
+export class UrlConverter extends Converter implements IConverter {
+  constructor() {
+    super(Route.URL);
+  }
+
+  async convert({
+    url,
+    properties,
+  }: {
+    url: string;
+    properties?: PageProperties;
+  }): Promise<Buffer> {
+    try {
+      const _url = new URL(url);
+      const data = new FormData();
+      data.append("url", _url.href);
+      if (properties) {
+        ConverterUtils.injectPageProperties(data, properties);
+      }
+      return ConverterUtils.fetch(this.endpoint, data);
+    } catch (error) {
+      throw error;
+    }
+  }
+}

package/src/gotenberg.ts

@@ -0,0 +1,9 @@
+process.env.SUPPRESS_NO_CONFIG_WARNING = "y";
+
+import "dotenv/config";
+import config from "config";
+
+export class Gotenberg {
+  public static endpoint: string =
+    process.env.GOTENBERG_ENDPOINT || config.get<string>("gotenberg.endpoint");
+}

package/src/main.config.ts

@@ -0,0 +1,23 @@
+import { Gotenberg } from "./gotenberg";
+
+export enum Route {
+  URL = "url",
+  HTML = "html",
+  MARKDOWN = "markdown",
+}
+
+export class Chromiumly {
+  private static readonly GOTENBERG_ENDPOINT = Gotenberg.endpoint;
+
+  private static readonly PATH = "forms/chromium/convert";
+
+  private static readonly ROUTES = {
+    url: Route.URL,
+    html: Route.HTML,
+    markdown: Route.MARKDOWN,
+  };
+
+  public static readonly endpoint = Chromiumly.GOTENBERG_ENDPOINT;
+  public static readonly path = Chromiumly.PATH;
+  public static readonly routes = Chromiumly.ROUTES;
+}

package/src/main.ts

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

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "importHelpers": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "experimentalDecorators": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "types": ["node"],
+    "lib": ["ES6"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}