@hed-hog/core 0.0.400 → 0.0.401

package/src/pdf/pdf.service.ts

@@ -1,9 +1,21 @@
-import { Inject, Injectable, InternalServerErrorException, Logger, forwardRef } from '@nestjs/common';
+import {
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  Logger,
+  ServiceUnavailableException,
+  forwardRef,
+} from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 
 import { BrandAssetService } from '../setting/brand-asset.service';
 import { SettingService } from '../setting/setting.service';
 import { PdfAreaType, PdfThemeConfig } from './interfaces/pdf-theme-config.interface';
+import {
+  CommercialDocumentTheme,
+  CommercialProposalData,
+  commercialProposalTemplate,
+} from './templates/commercial-proposal.template';
 import { hcodeInstitutionalTemplate } from './templates/hcode-institutional.template';
 import { AreaDefaults, HCODE_DEFAULTS } from './themes/hcode.theme';
 
@@ -20,8 +32,40 @@ export interface PdfGenerateOptions {
   width?: string;
   /** Explicit CSS page size (e.g. '1131px'). Takes precedence over `format`/`landscape` when set. */
   height?: string;
+
+  /**
+   * Turns on Chromium's own per-page header and footer. This is the only way to
+   * get a repeating accent bar and a real page number: `counter(page)` resolves
+   * to nothing outside `@page` margin boxes, so a footer rendered as flow
+   * content (like `pdfFooter()` in ./components) prints an empty page slot.
+   *
+   * The templates are mini-documents, not part of the page: they start at
+   * `font-size: 0`, need their own `print-color-adjust: exact` to keep
+   * backgrounds, and only `<span class="pageNumber">` / `<span class="totalPages">`
+   * get substituted. Keep `margin.top`/`margin.bottom` larger than the templates,
+   * or the page content prints over them.
+   */
+  displayHeaderFooter?: boolean;
+  headerTemplate?: string;
+  footerTemplate?: string;
+
+  /** `page.setContent` wait condition. Defaults to 'networkidle'. */
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+  /** Ceiling for `page.setContent`, in ms. Defaults to Playwright's own (30s). */
+  timeoutMs?: number;
+  scale?: number;
+  pageRanges?: string;
+  /** Short identifier for the logs when a render fails or the queue saturates. */
+  label?: string;
 }
 
+/** A render waiting for a Chromium slot. */
+type QueuedRender = {
+  resolve: () => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -33,6 +77,55 @@ function parsePxSize(value: string | undefined, fallback: number): number {
   return match ? Math.round(Number(match[1])) : fallback;
 }
 
+const ZERO_MARGIN = { top: '0', right: '0', bottom: '0', left: '0' };
+
+/**
+ * With `displayHeaderFooter` on, a template left undefined makes Chromium fall
+ * back to its own — the page URL and the print date. The unused slot gets
+ * something deliberately empty instead.
+ */
+const EMPTY_TEMPLATE = '<span></span>';
+
+const DEFAULT_MAX_CONCURRENCY = 2;
+const DEFAULT_QUEUE_WAIT_MS = 30_000;
+
+/**
+ * Builds the object handed to `page.pdf()`.
+ *
+ * Assembled key by key on purpose: a caller that passes none of the optional
+ * fields has to get exactly the object `page.pdf()` received before they
+ * existed — Chromium changes behaviour on the mere presence of some of them
+ * (`displayHeaderFooter` with a single template filled in brings back its own
+ * URL/date footer).
+ */
+export function buildPdfPageOptions(options: PdfGenerateOptions): Record<string, unknown> {
+  const pdfOptions: Record<string, unknown> =
+    options.width && options.height
+      ? {
+          width: options.width,
+          height: options.height,
+          printBackground: options.printBackground ?? true,
+          margin: options.margin ?? ZERO_MARGIN,
+        }
+      : {
+          format: options.format ?? 'A4',
+          printBackground: options.printBackground ?? true,
+          landscape: options.landscape ?? false,
+          margin: options.margin ?? ZERO_MARGIN,
+        };
+
+  if (options.displayHeaderFooter) {
+    pdfOptions.displayHeaderFooter = true;
+    pdfOptions.headerTemplate = options.headerTemplate ?? EMPTY_TEMPLATE;
+    pdfOptions.footerTemplate = options.footerTemplate ?? EMPTY_TEMPLATE;
+  }
+
+  if (options.scale !== undefined) pdfOptions.scale = options.scale;
+  if (options.pageRanges) pdfOptions.pageRanges = options.pageRanges;
+
+  return pdfOptions;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Service
 // ─────────────────────────────────────────────────────────────────────────────
@@ -41,6 +134,10 @@ function parsePxSize(value: string | undefined, fallback: number): number {
 export class PdfService {
   private readonly logger = new Logger(PdfService.name);
 
+  /** Renders holding a Chromium right now, and the ones waiting for a slot. */
+  private activeRenders = 0;
+  private readonly renderQueue: QueuedRender[] = [];
+
   constructor(
     @Inject(forwardRef(() => SettingService))
     private readonly settingService: SettingService,
@@ -120,15 +217,136 @@ export class PdfService {
     }
   }
 
-  // ── HTML → PDF ────────────────────────────────────────────────────────────
+  /**
+   * Theme for commercial documents (proposals and the like): the area theme
+   * plus the legal footer, partner line and font stacks of the `pdf` group.
+   * The logo is embedded as a data URI so the render does not depend on the
+   * API reaching its own public URL.
+   */
+  async loadCommercialDocumentTheme(
+    area: PdfAreaType = 'training',
+  ): Promise<CommercialDocumentTheme> {
+    const base = await this.loadThemeConfig(area);
+
+    let values: Record<string, any> = {};
+    try {
+      values = await this.settingService.getSettingValues([
+        'pdf-legal-footer',
+        'pdf-partner-line',
+        'pdf-font-family',
+        'pdf-font-mono',
+      ]);
+    } catch {
+      this.logger.warn('Could not load commercial PDF settings – using defaults.');
+    }
+
+    const logoOverride = base.logoOverride
+      ? ((await this.brandAsset.fetchAsDataUri(base.logoOverride)) ?? base.logoOverride)
+      : '';
+
+    return {
+      ...base,
+      logoOverride,
+      legalFooter: String(values['pdf-legal-footer'] ?? '').trim(),
+      partnerLine: String(values['pdf-partner-line'] ?? '').trim(),
+      fontFamily: String(values['pdf-font-family'] ?? '').trim() || "'Inter', sans-serif",
+      fontMono: String(values['pdf-font-mono'] ?? '').trim() || "'JetBrains Mono', monospace",
+    };
+  }
 
   /**
-   * Renders an HTML string to a PDF buffer using Playwright/Chromium.
+   * Renders a commercial proposal with the installation's branding. Returns
+   * the HTML too, so the caller can keep the exact source of what was printed.
+   */
+  async renderCommercialProposal(
+    data: CommercialProposalData,
+    area: PdfAreaType = 'training',
+  ): Promise<{ html: string; buffer: Buffer }> {
+    const theme = await this.loadCommercialDocumentTheme(area);
+    const { html, pdfOptions } = commercialProposalTemplate(data, theme);
+    const buffer = await this.generatePdfFromHtml(html, pdfOptions);
+    return { html, buffer };
+  }
+
+  // ── Chromium runtime ──────────────────────────────────────────────────────
+
+  private get maxConcurrency(): number {
+    const raw = Number(this.configService.get<string>('PDF_MAX_CONCURRENCY'));
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_MAX_CONCURRENCY;
+  }
+
+  private get queueWaitMs(): number {
+    const raw = Number(this.configService.get<string>('PDF_QUEUE_WAIT_MS'));
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_QUEUE_WAIT_MS;
+  }
+
+  /**
+   * Every render launches a Chromium of its own, which costs a few hundred MB.
+   * The API pod is capped well below what a burst of simultaneous report
+   * downloads would ask for, and an OOM kill takes the whole API down — not
+   * just the PDF. So renders queue, and a queue that waits too long answers a
+   * retryable 503 instead of dragging the process down with it.
+   */
+  private async acquireRenderSlot(label?: string): Promise<() => void> {
+    if (this.activeRenders < this.maxConcurrency) {
+      this.activeRenders += 1;
+    } else {
+      await new Promise<void>((resolve, reject) => {
+        const entry: QueuedRender = {
+          resolve,
+          reject,
+          timer: setTimeout(() => {
+            const index = this.renderQueue.indexOf(entry);
+            if (index >= 0) this.renderQueue.splice(index, 1);
+            this.logger.warn(
+              `PDF render queue is saturated; gave up after ${this.queueWaitMs}ms${label ? ` (${label})` : ''}.`,
+            );
+            reject(
+              new ServiceUnavailableException(
+                'The server is busy rendering other documents. Try again in a moment.',
+              ),
+            );
+          }, this.queueWaitMs),
+        };
+        this.renderQueue.push(entry);
+      });
+      // Resolved by releaseRenderSlot, which hands its slot over without
+      // decrementing — the counter already accounts for this render.
+    }
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.releaseRenderSlot();
+    };
+  }
+
+  private releaseRenderSlot(): void {
+    const next = this.renderQueue.shift();
+    if (next) {
+      clearTimeout(next.timer);
+      next.resolve();
+      return;
+    }
+    this.activeRenders = Math.max(0, this.activeRenders - 1);
+  }
+
+  /**
+   * Opens a Chromium page with the HTML loaded and hands it to `run`, taking
+   * care of the slot, the viewport and the teardown.
    *
    * Uses dynamic `import()` via `new Function` to remain compatible with
    * CommonJS bundle output (same pattern as operations.service.ts).
    */
-  async generatePdfFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
+  private async renderWithChromium(
+    kind: 'PDF' | 'Image',
+    html: string,
+    options: PdfGenerateOptions,
+    run: (page: any) => Promise<any>,
+  ): Promise<Buffer> {
+    const release = await this.acquireRenderSlot(options.label);
+
     const executablePath = this.configService.get<string>('CHROMIUM_EXECUTABLE_PATH');
     const noSandbox = this.configService.get<string>('CHROMIUM_NO_SANDBOX') === 'true';
 
@@ -163,25 +381,12 @@ export class PdfService {
         width: parsePxSize(options.width, 794),
         height: parsePxSize(options.height, 1123),
       });
-      await page.setContent(html, { waitUntil: 'networkidle' });
-
-      const pdfBuffer = await page.pdf(
-        options.width && options.height
-          ? {
-              width: options.width,
-              height: options.height,
-              printBackground: options.printBackground ?? true,
-              margin: options.margin ?? { top: '0', right: '0', bottom: '0', left: '0' },
-            }
-          : {
-              format: options.format ?? 'A4',
-              printBackground: options.printBackground ?? true,
-              landscape: options.landscape ?? false,
-              margin: options.margin ?? { top: '0', right: '0', bottom: '0', left: '0' },
-            },
-      );
+      await page.setContent(html, {
+        waitUntil: options.waitUntil ?? 'networkidle',
+        ...(options.timeoutMs ? { timeout: options.timeoutMs } : {}),
+      });
 
-      return Buffer.from(pdfBuffer);
+      return Buffer.from(await run(page));
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       const errorStack = error instanceof Error ? (error.stack ?? errorMessage) : String(error);
@@ -191,7 +396,7 @@ export class PdfService {
           errorMessage,
         );
 
-      this.logger.error(`PDF generation failed. ${errorMessage}`, errorStack);
+      this.logger.error(`${kind} generation failed. ${errorMessage}`, errorStack);
 
       if (missingRuntime) {
         throw new InternalServerErrorException(
@@ -199,7 +404,7 @@ export class PdfService {
         );
       }
 
-      throw new InternalServerErrorException(`PDF generation failed: ${errorMessage}`);
+      throw new InternalServerErrorException(`${kind} generation failed: ${errorMessage}`);
     } finally {
       if (browser) {
         try {
@@ -208,9 +413,21 @@ export class PdfService {
           // Ignore close errors
         }
       }
+      release();
     }
   }
 
+  // ── HTML → PDF ────────────────────────────────────────────────────────────
+
+  /**
+   * Renders an HTML string to a PDF buffer using Playwright/Chromium.
+   */
+  async generatePdfFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
+    const pdfOptions = buildPdfPageOptions(options);
+
+    return this.renderWithChromium('PDF', html, options, (page) => page.pdf(pdfOptions));
+  }
+
   // ── HTML → PNG image ──────────────────────────────────────────────────────
 
   /**
@@ -221,69 +438,15 @@ export class PdfService {
    * certificate thumbnails on the web/app.
    */
   async generateImageFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
-    const executablePath = this.configService.get<string>('CHROMIUM_EXECUTABLE_PATH');
-    const noSandbox = this.configService.get<string>('CHROMIUM_NO_SANDBOX') === 'true';
-
-    const launchArgs = noSandbox
-      ? ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
-      : [];
-
     const width = parsePxSize(options.width, 794);
     const height = parsePxSize(options.height, 1123);
 
-    let browser: any = null;
-
-    try {
-      const importPlaywright = new Function(
-        'moduleName',
-        'return import(moduleName);',
-      ) as (moduleName: string) => Promise<any>;
-
-      const playwright = await importPlaywright('playwright');
-
-      browser = await playwright.chromium.launch({
-        headless: true,
-        ...(executablePath ? { executablePath } : {}),
-        args: launchArgs,
-      });
-
-      const page = await browser.newPage();
-      await page.setViewportSize({ width, height });
-      await page.setContent(html, { waitUntil: 'networkidle' });
-
-      const imageBuffer = await page.screenshot({
+    return this.renderWithChromium('Image', html, options, (page) =>
+      page.screenshot({
         type: 'png',
         clip: { x: 0, y: 0, width, height },
-      });
-
-      return Buffer.from(imageBuffer);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      const errorStack = error instanceof Error ? (error.stack ?? errorMessage) : String(error);
-
-      const missingRuntime =
-        /Cannot find package ['"]playwright['"]|Cannot find module ['"]playwright['"]|Executable doesn't exist|browserType\.launch|Failed to launch|Please run the following command/i.test(
-          errorMessage,
-        );
-
-      this.logger.error(`Image generation failed. ${errorMessage}`, errorStack);
-
-      if (missingRuntime) {
-        throw new InternalServerErrorException(
-          'Playwright runtime is not available. Run `pnpm --filter api run playwright:install` in the API environment.',
-        );
-      }
-
-      throw new InternalServerErrorException(`Image generation failed: ${errorMessage}`);
-    } finally {
-      if (browser) {
-        try {
-          await browser.close();
-        } catch {
-          // Ignore close errors
-        }
-      }
-    }
+      }),
+    );
   }
 
   // ── Template engine ───────────────────────────────────────────────────────

package/src/pdf/templates/commercial-proposal.template.spec.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { PdfService } from '../pdf.service';
+import {
+  CommercialDocumentTheme,
+  CommercialProposalData,
+  commercialProposalTemplate,
+} from './commercial-proposal.template';
+
+const theme = (overrides: Partial<CommercialDocumentTheme> = {}): CommercialDocumentTheme => ({
+  area: 'training',
+  companyName: 'hcode',
+  logoOverride: '',
+  primaryColor: '#FF760C',
+  darkColor: '#C45400',
+  lightColor: '#FFF0E2',
+  legalFooter: '',
+  partnerLine: '',
+  fontFamily: "'Inter', sans-serif",
+  fontMono: "'JetBrains Mono', monospace",
+  ...overrides,
+});
+
+const data = (overrides: Partial<CommercialProposalData> = {}): CommercialProposalData => ({
+  eyebrow: 'Proposta Comercial · BRA20260865',
+  title: 'Workshop de IA',
+  titleAccent: 'ArcelorMittal',
+  meta: [
+    { label: 'Cliente', value: 'ArcelorMittal' },
+    { label: 'Contato', value: '' },
+  ],
+  sections: [
+    { eyebrow: 'Sumário executivo', title: 'O que propomos.', blocks: [{ type: 'paragraphs', text: 'Um dia.' }] },
+    { eyebrow: 'Vazia', title: 'Não aparece.', blocks: [] },
+    {
+      eyebrow: 'Investimento',
+      title: 'Itens e valores.',
+      blocks: [
+        { type: 'table', headers: ['Item', 'Total'], rows: [['Workshop', 'R$ 1,00']], align: ['left', 'right'] },
+        { type: 'totals', rows: [{ label: 'Total', value: 'R$ 1,00', emphasis: true }] },
+      ],
+    },
+  ],
+  ...overrides,
+});
+
+describe('commercialProposalTemplate', () => {
+  it('numera só as seções com conteúdo, na ordem', () => {
+    const { html } = commercialProposalTemplate(data(), theme());
+
+    expect(html).toContain('01 · SUMÁRIO EXECUTIVO');
+    expect(html).toContain('02 · INVESTIMENTO');
+    expect(html).not.toContain('Não aparece.');
+  });
+
+  it('escapa o texto e deixa passar só o bloco html', () => {
+    const { html } = commercialProposalTemplate(
+      data({
+        title: '<script>alert(1)</script>',
+        sections: [
+          {
+            eyebrow: 'Resumo',
+            title: 'Texto.',
+            blocks: [
+              { type: 'paragraphs', text: '<b>cru</b>' },
+              { type: 'html', html: '<p><strong>rico</strong></p>' },
+            ],
+          },
+        ],
+      }),
+      theme(),
+    );
+
+    expect(html).not.toContain('<script>alert(1)</script>');
+    expect(html).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+    expect(html).toContain('&lt;b&gt;cru&lt;/b&gt;');
+    expect(html).toContain('<p><strong>rico</strong></p>');
+  });
+
+  it('omite metadado vazio na capa', () => {
+    const { html } = commercialProposalTemplate(data(), theme());
+
+    expect(html).toContain('<th>CLIENTE</th>');
+    expect(html).not.toContain('<th>CONTATO</th>');
+  });
+
+  it('usa a logo quando há e o nome da empresa como wordmark quando não há', () => {
+    expect(commercialProposalTemplate(data(), theme({ logoOverride: 'data:image/png;base64,AA' })).html).toContain(
+      '<img class="brand-logo" src="data:image/png;base64,AA"',
+    );
+
+    const { html } = commercialProposalTemplate(data(), theme());
+    expect(html).toContain('<span class="accent">h</span>code');
+    expect(html).toContain(' | TRAINING');
+  });
+
+  it('põe o rodapé legal e a paginação n / N no rodapé de cada página', () => {
+    const { pdfOptions } = commercialProposalTemplate(
+      data(),
+      theme({ legalFooter: 'Grupo Hcode · CNPJ 24.700.731/0001-08' }),
+    );
+
+    expect(pdfOptions.displayHeaderFooter).toBe(true);
+    expect(pdfOptions.footerTemplate).toContain('GRUPO HCODE · CNPJ 24.700.731/0001-08');
+    expect(pdfOptions.footerTemplate).toContain('<span class="pageNumber"></span> / <span class="totalPages"></span>');
+    expect(pdfOptions.headerTemplate).toContain('background:#FF760C');
+  });
+
+  it('cai no rótulo do documento quando não há rodapé legal', () => {
+    const { pdfOptions } = commercialProposalTemplate(data({ documentLabel: 'hcode · Proposta' }), theme());
+
+    expect(pdfOptions.footerTemplate).toContain('HCODE · PROPOSTA');
+  });
+
+  it('mostra a linha de parceiros só quando configurada', () => {
+    expect(commercialProposalTemplate(data(), theme()).html).not.toContain('partner-line">');
+    expect(
+      commercialProposalTemplate(data(), theme({ partnerLine: 'Parceira oficial Anthropic' })).html,
+    ).toContain('PARCEIRA OFICIAL ANTHROPIC');
+  });
+
+  it('não deixa uma setting fora do formato quebrar o CSS', () => {
+    const { html } = commercialProposalTemplate(
+      data(),
+      theme({ primaryColor: 'red;}</style><script>', fontFamily: 'Arial;}</style>' }),
+    );
+
+    expect(html).toContain('--primary: #FF760C;');
+    expect(html).toContain('--font: Arial/style;');
+    expect(html).not.toContain('</style><script>');
+  });
+});
+
+describe('PdfService.loadCommercialDocumentTheme', () => {
+  const makeService = (values: Record<string, unknown>, dataUri: string | null) => {
+    const settingService = { getSettingValues: jest.fn(async () => values) };
+    const brandAsset = {
+      resolveAssetUrl: jest.fn(async (url: string) => `https://api.example.com${url}`),
+      fetchAsDataUri: jest.fn(async () => dataUri),
+    };
+    return new PdfService(settingService as any, brandAsset as any, { get: () => undefined } as any);
+  };
+
+  it('lê rodapé, parceiros e fontes das settings e embute a logo', async () => {
+    const service = makeService(
+      {
+        'pdf-company-name': 'hcode',
+        'pdf-logo': '/logo.svg',
+        'pdf-legal-footer': 'Grupo Hcode',
+        'pdf-partner-line': 'Parceira Anthropic',
+        'pdf-font-family': 'Roboto, sans-serif',
+        'pdf-font-mono': '',
+      },
+      'data:image/svg+xml;base64,AA',
+    );
+
+    const result = await service.loadCommercialDocumentTheme('training');
+
+    expect(result).toMatchObject({
+      companyName: 'hcode',
+      logoOverride: 'data:image/svg+xml;base64,AA',
+      legalFooter: 'Grupo Hcode',
+      partnerLine: 'Parceira Anthropic',
+      fontFamily: 'Roboto, sans-serif',
+      fontMono: "'JetBrains Mono', monospace",
+    });
+  });
+
+  it('mantém a URL da logo quando não consegue embutir', async () => {
+    const service = makeService({ 'pdf-logo': '/logo.svg' }, null);
+
+    const result = await service.loadCommercialDocumentTheme('training');
+
+    expect(result.logoOverride).toBe('https://api.example.com/logo.svg');
+    expect(result.legalFooter).toBe('');
+  });
+});