@azuro-org/images-generator 1.3.15 → 2.0.0

package/README.md

@@ -1,80 +1,152 @@
 # @azuro-org/images-generator
 
+Puppeteer-based image generator: render HTML templates to PNG/JPEG. Uses a shared browser instance; relaunches automatically if the browser disconnects.
+
+## Installation
+
+```bash
+npm install @azuro-org/images-generator
+```
+
 ## Usage
 
+Create a `Generator` instance, call `run()` to start the browser, then use `generate()` for each image. Call `shutdown()` when done to close the browser.
+
 ```typescript
-import { generateImage } from '@azuro-org/images-generator';
-import template, { type Props } from '@azuro-org/images-generator/lib/templates/bet-nft';
+import { Generator } from '@azuro-org/images-generator';
+import template from '@azuro-org/images-generator/lib/templates/bet-nft';
 
-const props: Props = {
-  // ...
-}
+const generator = new Generator();
+
+await generator.run();
 
-// get image buffer
-const buffer = generateImage({
+// Single image – returns Uint8Array
+const buffer = await generator.generate({
   template,
-  props,
-})
+  props: { /* ... */ },
+});
 
-// create image file
-generateImage({
+// Save to file
+await generator.generate({
   template,
-  props,
+  props: { /* ... */ },
   output: './dist',
-})
+  filename: 'my-image',
+});
+
+await generator.shutdown();
+```
+
+### Batch generation with shutdown
+
+Run multiple generations in parallel and close the browser when finished:
+
+```typescript
+await generator.run();
+
+await Promise.all([
+  generator.generate({ template, props: props1, output: './dist', filename: 'image-1' }),
+  generator.generate({ template, props: props2, output: './dist', filename: 'image-2' }),
+]).finally(() => {
+  generator.shutdown();
+});
 ```
 
-## Options
+### Auto-recovery
+
+If the browser process exits or crashes, the next `generate()` call will launch a new browser automatically. You can also call `run()` again after a disconnect.
+
+## API
+
+### `Generator`
+
+**Constructor**
 
 ```typescript
-type PuppeteerOptions = Parameters<typeof puppeteer.launch>[0]
+const generator = new Generator(options?: GeneratorOptions);
+
+interface GeneratorOptions {
+  headless?: boolean;  // default: true
+  timeout?: number;    // default: 30000 (ms)
+  args?: string[];     // extra Chromium args
+}
+```
+
+**Methods**
+
+- **`run(): Promise<void>`** — Launches the browser. Idempotent if already running.
+- **`generate<P>(props: GenerateProps<P>): Promise<Uint8Array>`** — Renders the template with the given props. Ensures the browser is running (calls `run()` if needed).
+- **`shutdown(): Promise<void>`** — Closes the browser and cleans up.
+
+### `generate()` options
 
-type PuppeteerInitialOptions = {
-  headless: boolean
-  devtools: boolean
-  args: string[]
+```typescript
+interface GenerateProps<P> {
+  template: Template<P>;
+  props: P;
+  output?: string;   // folder path for the output file
+  filename?: string; // file name without extension (used with output)
+  options?: GenerateOptions;
 }
 
-generateImage({
-  output?: string // the folder path where the image will be generated
-  filename?: string // image name, default is "image"
-  props: any
-  modifyPuppeteerOptions?(options: PuppeteerInitialOptions): PuppeteerOptions
-})
+interface GenerateOptions {
+  quality?: number;           // JPEG quality, default 85
+  fullPage?: boolean;        // default false
+  waitForFonts?: boolean;    // default true
+  waitTimeout?: number;      // ms, default 2000
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'; // default 'domcontentloaded'
+  skipAnimations?: boolean;  // default true
+}
 ```
 
+## Templates
+
+Templates are in `lib/templates/<name>` (or `dist/templates/<name>` for ESM). Each template exports a default `Template` and a `Props` type.
+
+| Template           | Import path                                              |
+|--------------------|----------------------------------------------------------|
+| Bet NFT            | `@azuro-org/images-generator/lib/templates/bet-nft`      |
+| Bet OG             | `@azuro-org/images-generator/lib/templates/bet-og`      |
+| Combo Bet OG       | `@azuro-org/images-generator/lib/templates/combo-bet-og` |
+| Freebet            | `@azuro-org/images-generator/lib/templates/freebet`     |
+| Trendle Leaderboard| `@azuro-org/images-generator/lib/templates/trendle-leaderboard` |
+| Trendle Social     | `@azuro-org/images-generator/lib/templates/trendle-social`   |
+| Trendle Trading    | `@azuro-org/images-generator/lib/templates/trendle-trading`   |
 
-# Examples
+---
+
+## Examples
 
 <details>
 <summary><b>Bet Opengraph</b></summary>
 <p>
 
 ```typescript
-import { generateImage } from '@azuro-org/images-generator';
+import { Generator } from '@azuro-org/images-generator';
 import template from '@azuro-org/images-generator/lib/templates/bet-og';
 
-generateImage({
+const generator = new Generator();
+await generator.run();
+
+await generator.generate({
   template,
+  output: './dist',
+  filename: 'bet-og',
   props: {
     title: 'Decentralized betting is awesome!',
     game: {
       country: 'International Tournaments',
       league: 'ESL Challenger League North America',
       participants: [
-        {
-          name: 'WINDINGO',
-          image: 'https://content.bookmaker.xyz/avatars/provider-3/4757.png',
-        },
-        {
-          name: 'Los Grandes Academy',
-          image: 'https://content.bookmaker.xyz/avatars/provider-3/4739.png',
-        },
+        { name: 'WINDINGO', image: 'https://content.bookmaker.xyz/avatars/provider-3/4757.png' },
+        { name: 'Los Grandes Academy', image: 'https://content.bookmaker.xyz/avatars/provider-3/4739.png' },
       ],
       startsAt: Date.now(),
-    }
+    },
   },
-})
+});
+
+await generator.shutdown();
 ```
 
 ### Result
@@ -88,34 +160,27 @@ generateImage({
 <p>
 
 ```typescript
-import { generateImage } from '@azuro-org/images-generator';
+import { Generator } from '@azuro-org/images-generator';
 import template from '@azuro-org/images-generator/lib/templates/combo-bet-og';
 
-generateImage({
+const generator = new Generator();
+await generator.run();
+
+await generator.generate({
   template,
+  output: './dist',
+  filename: 'combo-bet-og',
   props: {
     title: 'Decentralized betting is awesome!',
     data: {
       totalOdds: 1.57,
       possiblePayout: 1017.17,
       asset: 'USDT',
-    }
+    },
   },
-})
+});
 
-// or (for "Winning" label)
-
-generateImage({
-  template,
-  props: {
-    title: 'Decentralized betting is awesome!',
-    data: {
-      totalOdds: 1.57,
-      payout: 500,
-      asset: 'USDT',
-    }
-  },
-})
+await generator.shutdown();
 ```
 
 ### Result
@@ -129,30 +194,31 @@ generateImage({
 <p>
 
 ```typescript
-import { generateImage } from '@azuro-org/images-generator';
+import { Generator } from '@azuro-org/images-generator';
 import template from '@azuro-org/images-generator/lib/templates/bet-nft';
 
-generateImage({
+const generator = new Generator();
+await generator.run();
+
+await generator.generate({
   template,
+  output: './dist',
+  filename: 'bet-nft',
   props: {
     type: 'match',
     sport: 'Football',
     league: 'International Tournaments · FIFA - World Cup',
-    team1: {
-      img: 'https://content.bookmaker.xyz/avatars/provider-3/4757.png',
-      name: 'Ecuador',
-    },
-    team2: {
-      img: 'https://content.bookmaker.xyz/avatars/provider-3/4739.png',
-      name: 'Senegal',
-    },
+    team1: { img: 'https://content.bookmaker.xyz/avatars/provider-3/4757.png', name: 'Ecuador' },
+    team2: { img: 'https://content.bookmaker.xyz/avatars/provider-3/4739.png', name: 'Senegal' },
     date: 'Dec 24, 2020',
     betAmount: '100 xDAI',
     outcome: 'Senegal',
     betOdds: '1.7',
     currentOdds: '1.2',
   },
-})
+});
+
+await generator.shutdown();
 ```
 
 ### Result
@@ -162,20 +228,27 @@ generateImage({
 </details>
 
 <details>
-<summary><b>Bet Opengraph</b></summary>
+<summary><b>Freebet</b></summary>
 <p>
 
 ```typescript
-import { generateImage } from '@azuro-org/images-generator';
+import { Generator } from '@azuro-org/images-generator';
 import template from '@azuro-org/images-generator/lib/templates/freebet';
 
-generateImage({
+const generator = new Generator();
+await generator.run();
+
+await generator.generate({
   template,
+  output: './dist',
+  filename: 'freebet',
   props: {
     amount: '5 xDAI',
     date: '12.01.2022',
   },
-})
+});
+
+await generator.shutdown();
 ```
 
 ### Result
@@ -184,53 +257,61 @@ generateImage({
 </p>
 </details>
 
+---
 
-# Contributing
-
-## Add new template
+## Contributing
 
-1. Copy `templates/_template` to `templates/{your_template_name}`.
-3. Use `index.html` for HTML. Write CSS in `index.html` file.
-4. Create `templates/{your_template_name}/images` folder for images if required.
+### Add a new template
 
+1. Copy `src/templates/_template` to `src/templates/{your_template_name}`.
+2. Put layout and styles in `index.html`.
+3. Add a `images` folder for static assets if needed.
 
-## Setup generator
+### Template definition
 
-Edit `{your_template_name}/index.ts` file:
+Use `Template<Props>`, `getBase64Image`, and `downloadImage` from `../../utils`:
 
 ```typescript
-import path from 'path'
-
-import { type Template, getFile, downloadImage, createGenerator } from '../../utils'
+import { type Template, downloadImage } from '../../utils';
+import html from './index.html';
 
 export type Props = {
-  team1ImageSrc: string
-  team2ImageSrc: string
-  date: string
-}
+  team1ImageSrc: string;
+  team2ImageSrc: string;
+  date: string;
+};
 
-const template = {
+const template: Template<Props> = {
   width: 800,
   height: 400,
   type: 'jpeg',
   html: async (props: Props) => {
-    const { team1ImageSrc, team2ImageSrc, date } = props
-
-    const html = getFile(path.join(__dirname, 'index.html'))
-
-    const team1Img = await downloadImage(team1ImageSrc)
-    const team2Img = await downloadImage(team2ImageSrc)
-
+    const { team1ImageSrc, team2ImageSrc, date } = props;
+    const team1Img = await downloadImage(team1ImageSrc);
+    const team2Img = await downloadImage(team2ImageSrc);
     return html
       .replace('{image1}', team1Img)
       .replace('{image2}', team2Img)
-      .replace('{date}', date)
+      .replace('{date}', date);
   },
-}
+};
 
-export default template
+export default template;
+```
+
+**Template shape**
+
+```typescript
+type Template<Props> = {
+  width: number;
+  height: number;
+  type: 'png' | 'jpeg';
+  html: (props: Props) => string | Promise<string>;
+  headless?: boolean;
+  scaleFactor?: 1 | 2;
+};
 ```
 
-## Publish
+### Publish
 
-Publish npm package with `npm run publish`. For access to `@azuro-org` scope ask Pavel Ivanov or Stas Onatskiy.
+Publish with `npm publish`. For access to the `@azuro-org` scope, contact the maintainers.

package/dist/generator.d.ts

@@ -0,0 +1,31 @@
+import { type Template } from './utils';
+interface GeneratorOptions {
+    headless?: boolean;
+    timeout?: number;
+    args?: string[];
+}
+interface GenerateOptions {
+    quality?: number;
+    fullPage?: boolean;
+    waitForFonts?: boolean;
+    waitTimeout?: number;
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    skipAnimations?: boolean;
+}
+type GenerateProps<P> = {
+    template: Template<P>;
+    props: P;
+    output?: string;
+    filename?: string;
+    options?: GenerateOptions;
+};
+declare class Generator {
+    private browser;
+    private readonly options;
+    constructor(options?: GeneratorOptions);
+    run(): Promise<void>;
+    generate<P>(props: GenerateProps<P>): Promise<Uint8Array>;
+    shutdown(): Promise<void>;
+    private cleanup;
+}
+export default Generator;