@hed-hog/core 0.0.400 → 0.0.402

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('');
+  });
+});

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

@@ -0,0 +1,400 @@
+import { PdfThemeConfig } from '../interfaces/pdf-theme-config.interface';
+import type { PdfGenerateOptions } from '../pdf.service';
+import { buildFontImport, HCODE_NEUTRALS } from '../themes/hcode.theme';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Data contract
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Branding for commercial documents: the area theme plus the lines that used to
+ * be hardcoded per company (legal footer, partner line) and the font stacks.
+ * Everything comes from the `pdf` setting group, so another installation
+ * changes the look without touching code.
+ */
+export interface CommercialDocumentTheme extends PdfThemeConfig {
+  /** Legal line repeated in the footer of every page (company, tax id, address). */
+  legalFooter: string;
+  /** Small line under the cover metadata (partners, certifications). */
+  partnerLine: string;
+  fontFamily: string;
+  fontMono: string;
+}
+
+/**
+ * Blocks a section is made of. Strings are escaped by the template; only
+ * `html` goes through as is, so the caller must hand it already sanitized.
+ */
+export type CommercialProposalBlock =
+  | { type: 'html'; html: string }
+  | { type: 'paragraphs'; text: string }
+  | { type: 'list'; items: string[] }
+  | { type: 'callout'; title?: string; text: string; tone?: 'accent' | 'neutral' }
+  | {
+      type: 'table';
+      headers: string[];
+      rows: string[][];
+      /** Per column; defaults to left. */
+      align?: Array<'left' | 'right'>;
+    }
+  | {
+      type: 'totals';
+      rows: Array<{ label: string; value: string; emphasis?: boolean }>;
+    };
+
+export interface CommercialProposalSection {
+  /** Short uppercase label next to the number: `03 · INVESTIMENTO`. */
+  eyebrow: string;
+  /** Written as a short sentence, as the proposal standard asks. */
+  title: string;
+  blocks: CommercialProposalBlock[];
+}
+
+export interface CommercialProposalSignatory {
+  party: string;
+  name?: string;
+  role?: string;
+}
+
+export interface CommercialProposalData {
+  locale?: string;
+  /** Mono line above the title: `PROPOSTA COMERCIAL · BRA20260865`. */
+  eyebrow: string;
+  title: string;
+  /** Second title line, printed in the accent color. */
+  titleAccent?: string;
+  subtitle?: string;
+  meta: Array<{ label: string; value: string }>;
+  sections: CommercialProposalSection[];
+  signatureTitle?: string;
+  signatories?: CommercialProposalSignatory[];
+  /** Left side of the footer when no legal footer is configured. */
+  documentLabel?: string;
+  /** Word used between the page number and the total (`3 / 9`). */
+  pageSeparator?: string;
+}
+
+export interface CommercialProposalRender {
+  html: string;
+  pdfOptions: PdfGenerateOptions;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function escapePdfHtml(value: unknown): string {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** Only a plain hex color reaches the CSS; anything else falls back. */
+function safeColor(value: string, fallback: string): string {
+  return /^#[0-9a-f]{3,8}$/i.test(String(value ?? '').trim()) ? value.trim() : fallback;
+}
+
+/** Font stacks end up inside a `<style>`: drop what could close it. */
+function safeFontStack(value: string, fallback: string): string {
+  const cleaned = String(value ?? '').replace(/[<>{};]/g, '').trim();
+  return cleaned || fallback;
+}
+
+function sectionNumber(index: number): string {
+  return String(index + 1).padStart(2, '0');
+}
+
+function renderParagraphs(text: string): string {
+  return String(text ?? '')
+    .split(/\n{2,}/)
+    .map((paragraph) => paragraph.trim())
+    .filter(Boolean)
+    .map((paragraph) => `<p>${escapePdfHtml(paragraph).replace(/\n/g, '<br>')}</p>`)
+    .join('');
+}
+
+function renderBlock(block: CommercialProposalBlock): string {
+  switch (block.type) {
+    case 'html':
+      return `<div class="rich">${block.html}</div>`;
+    case 'paragraphs':
+      return `<div class="rich">${renderParagraphs(block.text)}</div>`;
+    case 'list':
+      return `<ul class="dash-list">${block.items
+        .map((item) => `<li>${escapePdfHtml(item)}</li>`)
+        .join('')}</ul>`;
+    case 'callout':
+      return `<div class="callout ${block.tone === 'neutral' ? 'callout-neutral' : 'callout-accent'} no-break">
+  ${block.title ? `<div class="label">${escapePdfHtml(block.title)}</div>` : ''}
+  ${renderParagraphs(block.text)}
+</div>`;
+    case 'table': {
+      const align = (index: number) => (block.align?.[index] === 'right' ? ' class="num"' : '');
+      return `<table class="grid-table">
+  <thead><tr>${block.headers
+    .map((header, index) => `<th${align(index)}>${escapePdfHtml(header)}</th>`)
+    .join('')}</tr></thead>
+  <tbody>${block.rows
+    .map(
+      (row) =>
+        `<tr>${row.map((cell, index) => `<td${align(index)}>${escapePdfHtml(cell)}</td>`).join('')}</tr>`,
+    )
+    .join('')}</tbody>
+</table>`;
+    }
+    case 'totals':
+      return `<div class="totals no-break">${block.rows
+        .map(
+          (row) =>
+            `<div class="totals-row${row.emphasis ? ' totals-strong' : ''}"><span>${escapePdfHtml(
+              row.label,
+            )}</span><span>${escapePdfHtml(row.value)}</span></div>`,
+        )
+        .join('')}</div>`;
+    default:
+      return '';
+  }
+}
+
+/** Uploaded logo when there is one, otherwise the company name as a wordmark. */
+function renderBrand(theme: CommercialDocumentTheme): string {
+  if (theme.logoOverride) {
+    return `<img class="brand-logo" src="${escapePdfHtml(theme.logoOverride)}" alt="${escapePdfHtml(
+      theme.companyName,
+    )}">`;
+  }
+  const name = String(theme.companyName || '').trim();
+  return `<div class="wordmark"><span class="accent">${escapePdfHtml(
+    name.slice(0, 1),
+  )}</span>${escapePdfHtml(name.slice(1))}<span class="wordmark-area"> | ${escapePdfHtml(
+    theme.area.toUpperCase(),
+  )}</span></div>`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Commercial proposal — cover with the metadata table, numbered sections
+ * (`01 · ESCOPO`), borderless tables, rounded cards and a footer with the
+ * legal line and `n / N` on every page.
+ *
+ * Pure function: the caller resolves the theme (see
+ * `PdfService.loadCommercialDocumentTheme`) and the data, so the same input
+ * always renders the same document.
+ */
+export function commercialProposalTemplate(
+  data: CommercialProposalData,
+  theme: CommercialDocumentTheme,
+): CommercialProposalRender {
+  const primary = safeColor(theme.primaryColor, '#FF760C');
+  const ink = HCODE_NEUTRALS.ink1;
+  const muted = HCODE_NEUTRALS.ink2;
+  const line = HCODE_NEUTRALS.line;
+  const surface = HCODE_NEUTRALS.surface2;
+  const fontFamily = safeFontStack(theme.fontFamily, "'Inter', sans-serif");
+  const fontMono = safeFontStack(theme.fontMono, "'JetBrains Mono', monospace");
+
+  const sections = data.sections
+    .filter((section) => section.blocks.length > 0)
+    .map(
+      (section, index) => `<section class="section">
+  <div class="section-eyebrow">${sectionNumber(index)} · ${escapePdfHtml(
+    section.eyebrow.toUpperCase(),
+  )}</div>
+  <h2>${escapePdfHtml(section.title)}</h2>
+  ${section.blocks.map(renderBlock).join('\n')}
+</section>`,
+    )
+    .join('\n');
+
+  const signatories = data.signatories?.length
+    ? `<section class="section signatures no-break">
+  ${data.signatureTitle ? `<h2>${escapePdfHtml(data.signatureTitle)}</h2>` : ''}
+  <div class="signature-grid">${data.signatories
+    .map(
+      (signatory) => `<div class="signature">
+    <div class="signature-line"></div>
+    <div class="label">${escapePdfHtml(signatory.party)}</div>
+    ${signatory.name ? `<div class="signature-name">${escapePdfHtml(signatory.name)}</div>` : ''}
+    ${signatory.role ? `<div class="signature-role">${escapePdfHtml(signatory.role)}</div>` : ''}
+  </div>`,
+    )
+    .join('')}</div>
+</section>`
+    : '';
+
+  const cover = `<div class="cover">
+  <div class="cover-brand">${renderBrand(theme)}</div>
+  <div class="cover-eyebrow">${escapePdfHtml(data.eyebrow.toUpperCase())}</div>
+  <h1 class="cover-title">${escapePdfHtml(data.title)}${
+    data.titleAccent ? `<br><span class="accent">${escapePdfHtml(data.titleAccent)}</span>` : ''
+  }</h1>
+  ${data.subtitle ? `<div class="cover-subtitle">${escapePdfHtml(data.subtitle)}</div>` : ''}
+  <table class="meta-table">
+    <tbody>${data.meta
+      .filter((item) => String(item.value ?? '').trim())
+      .map(
+        (item) =>
+          `<tr><th>${escapePdfHtml(item.label.toUpperCase())}</th><td>${escapePdfHtml(item.value)}</td></tr>`,
+      )
+      .join('')}</tbody>
+  </table>
+  ${theme.partnerLine ? `<div class="partner-line">${escapePdfHtml(theme.partnerLine.toUpperCase())}</div>` : ''}
+</div>`;
+
+  const html = `<!DOCTYPE html>
+<html lang="${escapePdfHtml(data.locale || 'pt-BR')}">
+<head>
+  <meta charset="UTF-8">
+  ${buildFontImport()}
+  <style>
+    :root {
+      --primary: ${primary};
+      --primary-soft: color-mix(in srgb, ${primary} 12%, #ffffff);
+      --ink: ${ink};
+      --muted: ${muted};
+      --line: ${line};
+      --surface: ${surface};
+      --font: ${fontFamily};
+      --mono: ${fontMono};
+    }
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body {
+      font-family: var(--font);
+      font-size: 10.5pt;
+      line-height: 1.55;
+      color: var(--ink);
+      background: #ffffff;
+      -webkit-print-color-adjust: exact;
+      print-color-adjust: exact;
+    }
+    .accent { color: var(--primary); }
+    .no-break { break-inside: avoid; page-break-inside: avoid; }
+    .label {
+      font-family: var(--mono);
+      font-size: 7.5pt;
+      letter-spacing: 0.14em;
+      text-transform: uppercase;
+      color: var(--muted);
+      margin-bottom: 6px;
+    }
+
+    /* Cover */
+    .cover { min-height: 245mm; display: flex; flex-direction: column; break-after: page; }
+    .cover-brand { margin-bottom: 48mm; }
+    .brand-logo { max-height: 40px; max-width: 180px; object-fit: contain; }
+    .wordmark { font-size: 26pt; font-weight: 300; letter-spacing: -0.01em; line-height: 1; }
+    .wordmark-area { font-family: var(--mono); font-size: 9pt; letter-spacing: 0.2em; color: #949494; }
+    .cover-eyebrow {
+      font-family: var(--mono);
+      font-size: 8pt;
+      letter-spacing: 0.16em;
+      color: var(--muted);
+      margin-bottom: 14px;
+    }
+    .cover-title { font-size: 30pt; font-weight: 700; line-height: 1.12; letter-spacing: -0.02em; margin-bottom: 14px; }
+    .cover-subtitle { font-size: 11.5pt; color: var(--muted); margin-bottom: 28px; }
+    .meta-table { width: 100%; border-collapse: collapse; margin-top: auto; }
+    .meta-table th, .meta-table td { padding: 7px 0; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }
+    .meta-table th {
+      width: 34%;
+      font-family: var(--mono);
+      font-size: 7.5pt;
+      font-weight: 400;
+      letter-spacing: 0.14em;
+      color: var(--muted);
+    }
+    .meta-table td { font-size: 10pt; }
+    .partner-line { margin-top: 18px; font-family: var(--mono); font-size: 7.5pt; letter-spacing: 0.16em; color: #949494; }
+
+    /* Sections */
+    .section { margin-bottom: 26px; }
+    .section-eyebrow { font-family: var(--mono); font-size: 8pt; letter-spacing: 0.16em; color: var(--primary); margin-bottom: 6px; }
+    h2 { font-size: 16pt; font-weight: 700; line-height: 1.25; letter-spacing: -0.01em; margin-bottom: 12px; break-after: avoid; }
+    .rich p { margin-bottom: 8px; }
+    .rich ul, .rich ol { margin: 0 0 8px 18px; }
+    .rich h3 { font-size: 11.5pt; margin: 12px 0 6px; }
+    .dash-list, .rich ul { list-style: none; margin-left: 0; }
+    .dash-list li, .rich ul li { position: relative; padding-left: 18px; margin-bottom: 5px; }
+    .dash-list li::before, .rich ul li::before {
+      content: '';
+      position: absolute;
+      left: 0;
+      top: 0.75em;
+      width: 9px;
+      height: 2px;
+      background: var(--primary);
+    }
+
+    /* Cards */
+    .callout { border-radius: 10px; padding: 14px 16px; margin: 10px 0; }
+    .callout p { margin-bottom: 6px; }
+    .callout p:last-child { margin-bottom: 0; }
+    .callout-accent { background: var(--primary-soft); }
+    .callout-accent .label { color: var(--primary); }
+    .callout-neutral { background: var(--surface); }
+
+    /* Tables: horizontal rules only, no grid */
+    .grid-table { width: 100%; border-collapse: collapse; margin: 6px 0 10px; font-size: 9.5pt; }
+    .grid-table th {
+      font-family: var(--mono);
+      font-size: 7.5pt;
+      font-weight: 400;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      color: var(--muted);
+      text-align: left;
+      padding: 0 7px 7px;
+      border-bottom: 1px solid var(--ink);
+    }
+    .grid-table td { padding: 8px 7px; border-bottom: 1px solid var(--line); vertical-align: top; }
+    .grid-table th:first-child, .grid-table td:first-child { padding-left: 0; }
+    .grid-table th:last-child, .grid-table td:last-child { padding-right: 0; }
+    .grid-table tr { break-inside: avoid; }
+    .grid-table .num { text-align: right; white-space: nowrap; }
+
+    .totals { margin: 6px 0 10px auto; width: 60%; }
+    .totals-row { display: flex; justify-content: space-between; padding: 6px 0; border-bottom: 1px solid var(--line); font-size: 10pt; }
+    .totals-strong { border-bottom: none; border-top: 2px solid var(--ink); font-weight: 700; font-size: 12pt; color: var(--primary); }
+
+    /* Signatures */
+    .signature-grid { display: flex; gap: 32px; margin-top: 36px; }
+    .signature { flex: 1; }
+    .signature-line { border-top: 1px solid var(--ink); margin-bottom: 8px; }
+    .signature-name { font-weight: 600; }
+    .signature-role { color: var(--muted); font-size: 9.5pt; }
+  </style>
+</head>
+<body>
+${cover}
+${sections}
+${signatories}
+</body>
+</html>`;
+
+  const footerLeft = theme.legalFooter || data.documentLabel || theme.companyName;
+  const separator = data.pageSeparator ?? '/';
+
+  const pdfOptions: PdfGenerateOptions = {
+    format: 'A4',
+    printBackground: true,
+    displayHeaderFooter: true,
+    headerTemplate: `<div style="position:absolute;top:0;left:0;right:0;height:6px;background:${primary};-webkit-print-color-adjust:exact;print-color-adjust:exact;"></div>`,
+    footerTemplate: `<div style="width:100%;margin:0 25mm;display:flex;justify-content:space-between;gap:16px;font-family:${escapePdfHtml(
+      fontMono,
+    )};font-size:6.5pt;letter-spacing:0.12em;color:#949494;-webkit-print-color-adjust:exact;"><span>${escapePdfHtml(
+      footerLeft.toUpperCase(),
+    )}</span><span style="white-space:nowrap;"><span class="pageNumber"></span> ${escapePdfHtml(
+      separator,
+    )} <span class="totalPages"></span></span></div>`,
+    margin: { top: '22mm', right: '25mm', bottom: '22mm', left: '25mm' },
+    label: 'commercial-proposal',
+  };
+
+  return { html, pdfOptions };
+}

package/src/setting/favicon.controller.spec.ts

@@ -0,0 +1,92 @@
+import { NotFoundException } from '@nestjs/common';
+import { FaviconController } from './favicon.controller';
+
+const makeRes = () => {
+  const res: any = { headers: {} as Record<string, string> };
+  res.setHeader = jest.fn((k: string, v: string) => (res.headers[k] = v));
+  res.send = jest.fn((body: Buffer) => (res.body = body));
+  return res;
+};
+
+const makeController = (settings: Record<string, string>) => {
+  const setting = { getSettingValues: jest.fn().mockResolvedValue(settings) };
+  const brandAsset = {
+    resolveAssetUrl: jest.fn(async (value: string) =>
+      value.startsWith('/') ? `https://app.example.com${value}` : value,
+    ),
+  };
+  return new FaviconController(setting as any, brandAsset as any);
+};
+
+const svg = '<svg xmlns="http://www.w3.org/2000/svg"/>';
+
+describe('FaviconController', () => {
+  const originalFetch = globalThis.fetch;
+  let fetchMock: jest.Mock;
+
+  beforeEach(() => {
+    fetchMock = jest.fn().mockResolvedValue(
+      new Response(svg, { headers: { 'content-type': 'image/svg+xml' } }),
+    );
+    globalThis.fetch = fetchMock as any;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('serves the Branding icon with the origin content type', async () => {
+    const controller = makeController({ 'icon-url': '/logo.svg' });
+    const res = makeRes();
+
+    await controller.favicon(res);
+
+    expect(fetchMock.mock.calls[0][0]).toBe('https://app.example.com/logo.svg');
+    expect(res.headers['Content-Type']).toBe('image/svg+xml');
+    expect(res.body.toString()).toBe(svg);
+  });
+
+  it('falls back to image-url and caches the download', async () => {
+    const controller = makeController({ 'icon-url': '', 'image-url': '/brand.svg' });
+
+    await controller.favicon(makeRes());
+    await controller.favicon(makeRes());
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toBe('https://app.example.com/brand.svg');
+  });
+
+  it('decodes a data URI without fetching', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+    const controller = makeController({
+      'icon-url': `data:image/png;base64,${png.toString('base64')}`,
+    });
+    const res = makeRes();
+
+    await controller.favicon(res);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(res.headers['Content-Type']).toBe('image/png');
+    expect(Buffer.compare(res.body, png)).toBe(0);
+  });
+
+  it('answers 404 when the source is not an image', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('<html/>', { headers: { 'content-type': 'text/html' } }),
+    );
+    const controller = makeController({ 'icon-url': '/logo.svg' });
+
+    await expect(controller.favicon(makeRes())).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+  });
+
+  it('answers 404 when nothing is configured', async () => {
+    const controller = makeController({});
+
+    await expect(controller.favicon(makeRes())).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});