@hed-hog/core 0.0.399 → 0.0.401

package/src/pdf/document/pdf-document.renderer.spec.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { escapeHtml, renderBlock, renderDocumentHtml } from './pdf-document.renderer';
+import { PdfDocumentTheme } from './pdf-document.theme';
+import { PdfDocumentBlock, PdfDocumentRow } from './pdf-document.types';
+
+const theme: PdfDocumentTheme = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+  logoUrl: 'data:image/svg+xml;charset=UTF-8,%3Csvg%3E%3C/svg%3E',
+  fontFamily: 'Arial, Helvetica, sans-serif',
+  chartPalette: ['#ff760c'],
+};
+
+const table = (rows: PdfDocumentRow[]): PdfDocumentBlock => ({
+  kind: 'table',
+  numbered: true,
+  columns: [{ header: 'Aluno' }, { header: 'Horas', align: 'right' }],
+  rows,
+});
+
+describe('escapeHtml', () => {
+  it('neutraliza os cinco caracteres que viram markup', () => {
+    expect(escapeHtml(`<script>alert("1" & '2')</script>`)).toBe(
+      '&lt;script&gt;alert(&quot;1&quot; &amp; &#39;2&#39;)&lt;/script&gt;',
+    );
+  });
+
+  it('trata nulo e indefinido como texto vazio', () => {
+    expect(escapeHtml(null)).toBe('');
+    expect(escapeHtml(undefined)).toBe('');
+  });
+});
+
+describe('tabela', () => {
+  // O pedido que originou o kit: cada linha numerada a partir de 1.
+  it('numera as linhas de 1 a N, na ordem recebida', () => {
+    const html = renderBlock(table([['Ana', '10h'], ['Bruno', '9h'], ['Carla', '8h']]));
+    const indices = [...html.matchAll(/<td class="idx">(\d+)<\/td>/g)].map((m) => m[1]);
+
+    expect(indices).toEqual(['1', '2', '3']);
+  });
+
+  // Sem `display: table-header-group` o cabeçalho some da segunda página em
+  // diante; o `<thead>` tem que existir de verdade para a regra pegar.
+  it('emite thead próprio, que o CSS manda repetir por página', () => {
+    const html = renderBlock(table([['Ana', '10h']]));
+
+    expect(html).toContain('<thead><tr>');
+    expect(html).toContain('<th class="idx">#</th>');
+  });
+
+  it('escapa o conteúdo das células e da segunda linha', () => {
+    const html = renderBlock({
+      kind: 'table',
+      columns: [{ header: 'Aluno' }],
+      rows: [[{ text: '<b>Ana</b>', sub: 'a&b@x.com' }]],
+    });
+
+    expect(html).toContain('&lt;b&gt;Ana&lt;/b&gt;');
+    expect(html).toContain('a&amp;b@x.com');
+    expect(html).not.toContain('<b>Ana</b>');
+  });
+
+  it('mostra um aviso no lugar da tabela quando não há linha nenhuma', () => {
+    const html = renderBlock({ kind: 'table', columns: [{ header: 'Aluno' }], rows: [] });
+
+    expect(html).toContain('table-empty');
+    expect(html).not.toContain('<table');
+  });
+
+  it('preenche célula vazia com travessão em vez de deixar buraco', () => {
+    const html = renderBlock(table([['Ana', null]]));
+
+    expect(html).toContain('—');
+  });
+});
+
+describe('documento', () => {
+  it('monta o letterhead com sobretítulo, título e metadados', () => {
+    const html = renderDocumentHtml(
+      {
+        title: 'Alunos',
+        eyebrow: 'Relatório de Alunos',
+        subtitle: 'BRClick',
+        meta: [{ label: 'Status', value: 'Todos os status' }],
+        generatedAt: new Date('2026-09-22T13:32:00Z'),
+        blocks: [{ kind: 'section', title: 'Resumo' }],
+      },
+      theme,
+    );
+
+    expect(html).toContain('<div class="eyebrow">Relatório de Alunos</div>');
+    expect(html).toContain('<h1>Alunos</h1>');
+    expect(html).toContain('Status: <span class="meta-value">Todos os status</span>');
+    expect(html).toContain('Gerado em:');
+  });
+
+  it('escapa o título também no <title> da página', () => {
+    const html = renderDocumentHtml(
+      { title: 'Turma <A>', blocks: [] },
+      theme,
+    );
+
+    expect(html).toContain('<title>Turma &lt;A&gt;</title>');
+  });
+
+  // O SVG é a única string injetada crua — e só os desenhistas do kit produzem.
+  it('injeta o SVG do gráfico sem escapar, mas escapa o título dele', () => {
+    const html = renderBlock({
+      kind: 'chart',
+      title: 'Matrículas & conclusões',
+      svg: '<svg><rect /></svg>' as never,
+    });
+
+    expect(html).toContain('<svg><rect /></svg>');
+    expect(html).toContain('Matrículas &amp; conclusões');
+  });
+
+  it('vira paisagem quando o documento pede', () => {
+    const html = renderDocumentHtml({ title: 'Frequência', landscape: true, blocks: [] }, theme);
+
+    expect(html).toContain('size: A4 landscape');
+  });
+});

package/src/pdf/document/pdf-document.renderer.ts

@@ -0,0 +1,215 @@
+import { buildDocumentCss } from './pdf-document.css';
+import { PdfDocumentTheme } from './pdf-document.theme';
+import {
+  PdfDocumentBlock,
+  PdfDocumentCard,
+  PdfDocumentInput,
+  PdfDocumentRow,
+  PdfDocumentTableCell,
+  PdfDocumentTableColumn,
+} from './pdf-document.types';
+
+/**
+ * Único ponto por onde texto entra no HTML. Nome de aluno, título de curso e
+ * rótulo de tarefa são dados de usuário indo para um Chromium headless.
+ */
+export function escapeHtml(value: unknown): string {
+  if (value === null || value === undefined) return '';
+
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+const formatGeneratedAt = (date: Date, locale: string): string =>
+  new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: 'long',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+
+const toCell = (value: PdfDocumentRow[number]): PdfDocumentTableCell => {
+  if (value === null || value === undefined) return { text: '—', tone: 'muted' };
+  if (typeof value === 'object') return value;
+  return { text: String(value) };
+};
+
+const alignClass = (column: PdfDocumentTableColumn): string =>
+  column.align === 'right'
+    ? ' class="align-right"'
+    : column.align === 'center'
+      ? ' class="align-center"'
+      : '';
+
+function renderCards(items: PdfDocumentCard[], columns: number, variant: string): string {
+  const cards = items
+    .map(
+      (item) =>
+        `<div class="card"><div class="card-label">${escapeHtml(item.label)}</div>` +
+        `<div class="card-value">${escapeHtml(item.value)}</div>` +
+        (item.hint ? `<div class="card-hint">${escapeHtml(item.hint)}</div>` : '') +
+        '</div>',
+    )
+    .join('');
+
+  return `<div class="cards cards-${columns} cards-${variant}">${cards}</div>`;
+}
+
+function renderTable(block: Extract<PdfDocumentBlock, { kind: 'table' }>): string {
+  const {
+    columns,
+    rows,
+    numbered = false,
+    numberHeader = '#',
+    zebra = true,
+    compact = false,
+    emptyText = 'Nenhum registro no recorte selecionado.',
+    truncatedNote,
+  } = block;
+
+  if (rows.length === 0) {
+    return `<div class="table-empty">${escapeHtml(emptyText)}</div>`;
+  }
+
+  const head =
+    (numbered ? `<th class="idx">${escapeHtml(numberHeader)}</th>` : '') +
+    columns
+      .map(
+        (column) =>
+          `<th${alignClass(column)}${column.width ? ` style="width:${escapeHtml(column.width)}"` : ''}>` +
+          `${escapeHtml(column.header)}</th>`,
+      )
+      .join('');
+
+  // `push` + `join` em vez de concatenar em laço: uma conta grande gera milhares
+  // de linhas, e a string intermediária de cada passo é o que faz o render
+  // arrastar.
+  const body: string[] = [];
+
+  rows.forEach((row, index) => {
+    const cells: string[] = [];
+
+    if (numbered) cells.push(`<td class="idx">${index + 1}</td>`);
+
+    columns.forEach((column, columnIndex) => {
+      const cell = toCell(row[columnIndex]);
+      const tone = cell.tone && cell.tone !== 'default' ? ` tone-${cell.tone}` : '';
+      const align =
+        column.align === 'right' ? ' align-right' : column.align === 'center' ? ' align-center' : '';
+
+      cells.push(
+        `<td class="${(tone + align).trim()}">${escapeHtml(cell.text)}` +
+          (cell.sub ? `<div class="cell-sub">${escapeHtml(cell.sub)}</div>` : '') +
+          '</td>',
+      );
+    });
+
+    body.push(`<tr>${cells.join('')}</tr>`);
+  });
+
+  const table =
+    `<table class="doc-table${zebra ? ' zebra' : ''}${compact ? ' compact' : ''}">` +
+    `<thead><tr>${head}</tr></thead><tbody>${body.join('')}</tbody></table>`;
+
+  return truncatedNote ? `${table}<div class="note">${escapeHtml(truncatedNote)}</div>` : table;
+}
+
+export function renderBlock(block: PdfDocumentBlock): string {
+  switch (block.kind) {
+    case 'section':
+      return (
+        `<h2>${escapeHtml(block.title)}` +
+        (block.hint ? `<span class="section-hint">${escapeHtml(block.hint)}</span>` : '') +
+        '</h2>'
+      );
+
+    case 'cards':
+      return renderCards(block.items, block.columns ?? 4, block.variant ?? 'metric');
+
+    case 'table':
+      return renderTable(block);
+
+    case 'chart':
+      return (
+        '<div class="chart">' +
+        (block.title ? `<div class="chart-title">${escapeHtml(block.title)}</div>` : '') +
+        block.svg +
+        (block.caption ? `<div class="chart-caption">${escapeHtml(block.caption)}</div>` : '') +
+        '</div>'
+      );
+
+    case 'chartGrid':
+      return (
+        '<div class="chart-grid">' +
+        block.items
+          .map(
+            (item) =>
+              '<div class="chart">' +
+              (item.title ? `<div class="chart-title">${escapeHtml(item.title)}</div>` : '') +
+              item.svg +
+              (item.caption ? `<div class="chart-caption">${escapeHtml(item.caption)}</div>` : '') +
+              '</div>',
+          )
+          .join('') +
+        '</div>'
+      );
+
+    case 'note':
+      return `<div class="note${block.tone === 'accent' ? ' note-accent' : ''}">${escapeHtml(block.text)}</div>`;
+
+    case 'legend':
+      return `<div class="legend">${block.lines.map((l) => `<p>${escapeHtml(l)}</p>`).join('')}</div>`;
+
+    case 'pageBreak':
+      return '<div class="page-break"></div>';
+
+    default:
+      return '';
+  }
+}
+
+export function renderDocumentHtml(input: PdfDocumentInput, theme: PdfDocumentTheme): string {
+  const locale = input.locale ?? 'pt-BR';
+  const generatedAt = input.generatedAt ?? new Date();
+  const logo = input.logoDataUri || theme.logoUrl;
+
+  const meta = (input.meta ?? [])
+    .map(
+      (item) =>
+        `<div>${escapeHtml(item.label)}: <span class="meta-value">${escapeHtml(item.value)}</span></div>`,
+    )
+    .join('');
+
+  const body = input.blocks.map((block) => renderBlock(block)).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(locale)}">
+  <head>
+    <meta charset="utf-8" />
+    <title>${escapeHtml(input.title)}</title>
+    <style>${buildDocumentCss(theme, input.landscape ?? false)}</style>
+  </head>
+  <body>
+    <header>
+      <div class="brand">
+        <img src="${escapeHtml(logo)}" alt="${escapeHtml(theme.companyName)}" />
+        <div class="brand-text">
+          ${input.eyebrow ? `<div class="eyebrow">${escapeHtml(input.eyebrow)}</div>` : ''}
+          <h1>${escapeHtml(input.title)}</h1>
+          ${input.subtitle ? `<div class="company-name">${escapeHtml(input.subtitle)}</div>` : ''}
+        </div>
+      </div>
+      <div class="meta-block">
+        <div>Gerado em: <span class="meta-value">${escapeHtml(formatGeneratedAt(generatedAt, locale))}</span></div>
+        ${meta}
+      </div>
+    </header>
+    ${body}
+  </body>
+</html>`;
+}

package/src/pdf/document/pdf-document.service.ts

@@ -0,0 +1,77 @@
+import { Inject, Injectable, forwardRef } from '@nestjs/common';
+
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+import { PdfService } from '../pdf.service';
+import {
+  PDF_DOCUMENT_MARGIN,
+  buildAccentHeaderTemplate,
+  buildFooterTemplate,
+} from './pdf-document.chrome';
+import { renderDocumentHtml } from './pdf-document.renderer';
+import {
+  PdfDocumentTheme,
+  PdfDocumentThemeOverrides,
+  resolveDocumentTheme,
+} from './pdf-document.theme';
+import { PdfDocumentInput } from './pdf-document.types';
+
+/**
+ * Gera o documento PDF padrão do sistema: letterhead com logo, cards, tabelas,
+ * gráficos, barra de destaque no topo de toda página e paginação "X / N".
+ *
+ * Quem chama entrega blocos de dados ({@link PdfDocumentInput}); o HTML e o
+ * Chromium são responsabilidade daqui.
+ */
+@Injectable()
+export class PdfDocumentService {
+  constructor(
+    @Inject(forwardRef(() => PdfService))
+    private readonly pdf: PdfService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => BrandAssetService))
+    private readonly brandAsset: BrandAssetService,
+  ) {}
+
+  loadTheme(overrides?: PdfDocumentThemeOverrides): Promise<PdfDocumentTheme> {
+    return resolveDocumentTheme(this.settingService, this.brandAsset, overrides);
+  }
+
+  /** HTML puro, sem Chromium — serve aos testes e a quem quiser inspecionar. */
+  async buildHtml(input: PdfDocumentInput, theme?: PdfDocumentTheme): Promise<string> {
+    return renderDocumentHtml(input, theme ?? (await this.loadTheme()));
+  }
+
+  async render(
+    input: PdfDocumentInput,
+    options: { theme?: PdfDocumentTheme; label?: string; timeoutMs?: number } = {},
+  ): Promise<Buffer> {
+    const theme = options.theme ?? (await this.loadTheme());
+    const html = renderDocumentHtml(input, theme);
+
+    const generatedAt = input.generatedAt ?? new Date();
+    const footerLeft = [
+      input.footerLeft ?? 'Documento Confidencial',
+      `Gerado em ${new Intl.DateTimeFormat(input.locale ?? 'pt-BR').format(generatedAt)}`,
+      theme.companyName,
+    ]
+      .filter(Boolean)
+      .join(' · ');
+
+    return this.pdf.generatePdfFromHtml(html, {
+      format: 'A4',
+      landscape: input.landscape ?? false,
+      printBackground: true,
+      margin: PDF_DOCUMENT_MARGIN,
+      displayHeaderFooter: true,
+      headerTemplate: buildAccentHeaderTemplate(theme),
+      footerTemplate: buildFooterTemplate(theme, footerLeft),
+      // O logo já vem embutido como data URI e não há fonte web: esperar por
+      // rede ociosa só adicionaria o timeout do `networkidle` ao render.
+      waitUntil: 'load',
+      timeoutMs: options.timeoutMs ?? 60_000,
+      label: options.label,
+    });
+  }
+}

package/src/pdf/document/pdf-document.theme.ts

@@ -0,0 +1,146 @@
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+
+/**
+ * Tokens do documento padrão. São as mesmas settings que a proposta comercial
+ * do CRM lê, para que os dois PDFs saiam com a mesma identidade sem um copiar
+ * as cores do outro na mão.
+ */
+export interface PdfDocumentTheme {
+  primary: string;
+  /** Fundo suave dos cards e do cabeçalho da tabela. */
+  mutedBg: string;
+  /** Texto secundário: rótulos, legendas, rodapé. */
+  mutedFg: string;
+  /** Texto principal. */
+  ink: string;
+  /** Bordas. */
+  line: string;
+  companyName: string;
+  /** Data URI ou URL absoluta do logo do sistema. */
+  logoUrl: string;
+  fontFamily: string;
+  /** Cores categóricas dos gráficos, com a primária na frente. */
+  chartPalette: string[];
+}
+
+const FALLBACK = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+};
+
+/**
+ * Nenhuma fonte web: o container da API só tem `ttf-freefont`, e um `<link>`
+ * para o Google Fonts com `waitUntil: 'networkidle'` vira espera até o timeout
+ * quando o pod não tem saída para a internet.
+ */
+export const PDF_DOCUMENT_FONT = 'Arial, Helvetica, sans-serif';
+
+/** Paleta print-safe: sem amarelo puro nem cinza claro, que somem no papel. */
+const CATEGORICAL = [
+  '#2563eb',
+  '#16a34a',
+  '#9333ea',
+  '#dc2626',
+  '#0891b2',
+  '#b45309',
+  '#4f46e5',
+  '#475569',
+];
+
+const text = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+export interface PdfDocumentThemeOverrides {
+  companyName?: string;
+  primary?: string;
+}
+
+/**
+ * Lê as settings de marca. Qualquer falha cai nos valores de fábrica — um
+ * relatório sem cor certa ainda é um relatório; um relatório que não sai não é.
+ */
+export async function resolveDocumentTheme(
+  settingService: SettingService,
+  brandAsset: BrandAssetService,
+  overrides: PdfDocumentThemeOverrides = {},
+): Promise<PdfDocumentTheme> {
+  let values: Record<string, any> = {};
+
+  try {
+    values = await settingService.getSettingValues([
+      'theme-primary-light',
+      'theme-muted-light',
+      'theme-muted-foreground-light',
+      'theme-secondary-foreground-light',
+      'system-name',
+      'image-url',
+      'icon-url',
+    ]);
+  } catch {
+    values = {};
+  }
+
+  const primary = overrides.primary ?? text(values['theme-primary-light']) ?? FALLBACK.primary;
+
+  return {
+    primary,
+    mutedBg: text(values['theme-muted-light']) ?? FALLBACK.mutedBg,
+    mutedFg: text(values['theme-muted-foreground-light']) ?? FALLBACK.mutedFg,
+    ink: text(values['theme-secondary-foreground-light']) ?? FALLBACK.ink,
+    line: FALLBACK.line,
+    companyName: overrides.companyName ?? text(values['system-name']) ?? FALLBACK.companyName,
+    logoUrl: await resolveSystemLogo(brandAsset, values, primary),
+    fontFamily: PDF_DOCUMENT_FONT,
+    chartPalette: [primary, ...CATEGORICAL],
+  };
+}
+
+/**
+ * O Chromium renderiza sem sessão e, dentro do cluster, pode não ter rota para
+ * o host público — por isso a imagem é baixada e embutida como data URI, com a
+ * URL absoluta como segundo recurso e um wordmark inline como último.
+ */
+async function resolveSystemLogo(
+  brandAsset: BrandAssetService,
+  values: Record<string, any>,
+  primary: string,
+): Promise<string> {
+  const configured = text(values['image-url']) ?? text(values['icon-url']);
+
+  if (configured) {
+    try {
+      const absolute = await brandAsset.resolveAssetUrl(configured);
+      if (absolute) {
+        const dataUri = await brandAsset.fetchAsDataUri(absolute);
+        if (dataUri) return dataUri;
+        return absolute;
+      }
+    } catch {
+      // Cai no wordmark abaixo.
+    }
+  }
+
+  return inlineWordmark(primary);
+}
+
+export function inlineWordmark(primary: string): string {
+  const svg = encodeURIComponent(
+    [
+      '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="72" viewBox="0 0 240 72">',
+      '<rect width="240" height="72" rx="18" fill="#0f172a"/>',
+      `<circle cx="38" cy="36" r="18" fill="${primary}"/>`,
+      '<text x="72" y="43" fill="#ffffff" font-size="26" font-family="Arial, sans-serif" font-weight="700">HedHog</text>',
+      '</svg>',
+    ].join(''),
+  );
+
+  return `data:image/svg+xml;charset=UTF-8,${svg}`;
+}

package/src/pdf/document/pdf-document.types.ts

@@ -0,0 +1,97 @@
+/**
+ * Modelo de um documento PDF padrão: o chamador descreve **dados**, nunca HTML.
+ *
+ * É o que sustenta a regra de escape do renderer — se um serviço pudesse passar
+ * markup, o nome de um aluno com `<` viraria tag dentro de um Chromium headless.
+ * A única exceção é o SVG dos gráficos, que carrega o tipo {@link SafeSvg} e só
+ * pode ser produzido pelos desenhistas do próprio kit.
+ */
+
+/** SVG montado pelos helpers de gráfico do kit — a única string injetada sem escape. */
+export type SafeSvg = string & { readonly __safeSvg: unique symbol };
+
+/**
+ * Marca um SVG como seguro. Só os desenhistas de `./charts` devem chamar isto:
+ * quem passar conteúdo de usuário aqui reabre a porta que o modelo de blocos fecha.
+ */
+export const asSafeSvg = (svg: string): SafeSvg => svg as SafeSvg;
+
+export interface PdfDocumentMeta {
+  label: string;
+  value: string;
+}
+
+export interface PdfDocumentCard {
+  label: string;
+  value: string;
+  /** Linha pequena abaixo do valor, para a unidade ou a ressalva. */
+  hint?: string;
+}
+
+export interface PdfDocumentTableColumn {
+  header: string;
+  align?: 'left' | 'center' | 'right';
+  /**
+   * Largura CSS (ex.: '18%'). Sem ela o Chromium reparte pelo conteúdo e a
+   * tabela muda de forma a cada página.
+   */
+  width?: string;
+}
+
+export interface PdfDocumentTableCell {
+  text: string;
+  /** Segunda linha menor: o e-mail sob o nome, o "Em risco" sob o status. */
+  sub?: string;
+  tone?: 'default' | 'muted' | 'bold' | 'accent' | 'warn';
+}
+
+export type PdfDocumentRow = Array<string | number | null | undefined | PdfDocumentTableCell>;
+
+export type PdfDocumentBlock =
+  | { kind: 'section'; title: string; hint?: string }
+  | {
+      kind: 'cards';
+      items: PdfDocumentCard[];
+      /** Padrão: 4. */
+      columns?: 2 | 3 | 4 | 5;
+      /** 'metric' destaca o valor (indicador); 'filter' é o carimbo do recorte. */
+      variant?: 'metric' | 'filter';
+    }
+  | {
+      kind: 'table';
+      columns: PdfDocumentTableColumn[];
+      rows: PdfDocumentRow[];
+      /** Coluna "#" à esquerda, 1..N contínua entre páginas. */
+      numbered?: boolean;
+      numberHeader?: string;
+      zebra?: boolean;
+      /** Fonte menor, para tabela com muitas colunas. */
+      compact?: boolean;
+      emptyText?: string;
+      /** Aviso de corte quando a origem truncou as linhas. */
+      truncatedNote?: string;
+    }
+  | { kind: 'chart'; title?: string; svg: SafeSvg; caption?: string }
+  | { kind: 'chartGrid'; items: Array<{ title?: string; svg: SafeSvg; caption?: string }> }
+  | { kind: 'note'; text: string; tone?: 'muted' | 'accent' }
+  | { kind: 'legend'; lines: string[] }
+  | { kind: 'pageBreak' };
+
+export interface PdfDocumentInput {
+  /** O `h1` do letterhead. */
+  title: string;
+  /** Sobretítulo laranja, em caixa alta (ex.: "Relatório de Alunos"). */
+  eyebrow?: string;
+  /** Linha cinza abaixo do título — normalmente o nome da empresa. */
+  subtitle?: string;
+  /** Bloco alinhado à direita do letterhead. */
+  meta?: PdfDocumentMeta[];
+  blocks: PdfDocumentBlock[];
+  /** Data URI do logo; sem ele o kit usa o logo do sistema. */
+  logoDataUri?: string | null;
+  generatedAt?: Date;
+  locale?: string;
+  landscape?: boolean;
+  /** Padrão: 'Documento Confidencial'. */
+  footerLeft?: string;
+}

package/src/pdf/pdf.module.ts

@@ -2,6 +2,7 @@ import { forwardRef, Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 
 import { SettingModule } from '../setting/setting.module';
+import { PdfDocumentService } from './document/pdf-document.service';
 import { PdfController } from './pdf.controller';
 import { PdfService } from './pdf.service';
 
@@ -10,8 +11,8 @@ import { PdfService } from './pdf.service';
     ConfigModule,
     forwardRef(() => SettingModule),
   ],
-  providers: [PdfService],
-  exports: [PdfService],
+  providers: [PdfService, PdfDocumentService],
+  exports: [PdfService, PdfDocumentService],
   controllers: [PdfController],
 })
 export class PdfModule {}