feat(billing): 80mm thermal invoice layout (ADD-P001)

GET billing/invoices/:id/document?format=thermal renders a dedicated 80mm
receipt template (72mm printable, 4mm margins each side), not a CSS variant
of the A4 layout — the A4 CSS is absolutely-positioned/fixed-px, tuned for a
210mm page, and doesn't reflow at thermal width. No seal (not a thermal
convention, renders badly on 1-bit thermal heads); line items stack
(description, then qty x rate = amount) instead of a table, since a real
table leaves ~10-14 chars for description at this width.

PdfRenderService gains a thermal render path: full 80mm-width viewport,
content height measured via page.evaluate after settle (continuous-roll
receipts have no fixed page length), and a noFallback option — a Chromium
failure throws a clear error instead of silently degrading to the generic
A4/no-QR fallback, which would hand back a different document than what was
asked for. The frontend surfaces that as a toast pointing at the existing A4
download.

format is strictly validated (a4|thermal only, BadRequestException
otherwise), not silently coerced.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts

@@ -27,6 +27,27 @@ export type InvoiceDocumentKind = "INVOICE" | "RECEIPT";
  */
 export const pngDataUrl = (base64: string): string => `data:image/png;base64,${base64}`;
 
+// ── Shared HTML-builder helpers (buildHtml + buildThermalHtml) ──────────────────────────────────
+// `buildFallbackPdf`'s own currency/money/date closures are a deliberately different, already-
+// established convention (bare "ETB" vs "Birr (ETB)") for the vector renderer — not touched here.
+
+function esc(value: unknown): string {
+  return String(value ?? "-")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function money(amount: unknown, currency: string): string {
+  return `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
+}
+
+function formatDate(value: unknown): string {
+  return value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
+}
+
 /** One billed line on the document (charge type / fee type agnostic). */
 export interface InvoiceDocumentLine {
   description: string | null;
@@ -129,6 +150,117 @@ export class InvoiceDocumentService {
     };
   }
 
+  /**
+   * 80mm thermal invoice (ADD-P001) — physical page is the 80mm roll width; content stays within
+   * `THERMAL_MARGIN_MM` of each edge via `PdfRenderService`'s margin, not a narrower page, since
+   * thermal print mechanisms have a dead zone at the roll edge they can't reach either way.
+   *
+   * A genuinely different template from `buildHtml`, not a CSS variant of it: the A4 layout is
+   * absolutely-positioned and fixed-px (`.seal{right:28px}`, `.qr{right:160px}`,
+   * `.totals{width:330px}`), tuned for a 210mm page — none of it reflows at 72mm printable width.
+   * No seal here at all (a decorative wet-ink-style stamp is an A4/laser convention; no real POS
+   * thermal receipt carries one, and thermal heads render rotated circles badly) and line items
+   * are stacked (description, then `qty x rate = amount` below it) rather than a table — a real
+   * multi-column table leaves ~10-14 chars for description at this width, truncating almost every
+   * line, which stacking avoids entirely. No Chromium-less fallback — see `renderThermal`.
+   */
+  async renderThermal(model: InvoiceDocumentModel): Promise<{ filename: string; buffer: Buffer }> {
+    const logoImageUrl =
+      model.logoImageUrl !== undefined ? model.logoImageUrl : await this.logoSettings.getLogoImageUrl();
+    // Seal deliberately dropped — never fetched, so no stampSettings call either.
+    const resolvedModel: InvoiceDocumentModel = { ...model, logoImageUrl, stampImageUrl: null };
+
+    const html = this.buildThermalHtml(resolvedModel);
+    return {
+      filename: `${this.safeFilename(model.documentNumber)}-thermal.pdf`,
+      buffer: await this.pdf.htmlToPdfBuffer(html, {
+        label: `${model.title} thermal invoice`,
+        thermal: true,
+        // A generic A4-shaped, QR-less fallback is not an acceptable stand-in for "the thermal
+        // printer output" — fail loudly instead; the caller has the A4 download to fall back to.
+        noFallback: true,
+      }),
+    };
+  }
+
+  buildThermalHtml(model: InvoiceDocumentModel): string {
+    const heading = `${model.title} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}`;
+    const logoInner = logoMarkup(model.logoImageUrl, "thermal-logo");
+
+    const summaryRows = model.summary
+      .map(
+        (row) =>
+          `<div class="row"><span class="label">${esc(row.label)}</span><span class="value">${esc(row.value)}</span></div>`,
+      )
+      .join("");
+
+    const itemBlocks = model.lines
+      .map((item) => {
+        const currency = item.currency ?? model.currency;
+        return `<div class="item">
+        <div class="item-desc">${esc(item.description)}</div>
+        <div class="item-calc">${esc(item.quantity ?? 0)} x ${esc(money(item.unitRate, currency))} = <strong>${esc(money(item.amount, currency))}</strong></div>
+      </div>`;
+      })
+      .join("");
+
+    const totalRows = model.totals
+      .map(
+        (total) =>
+          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
+      )
+      .join("");
+
+    const qrMarkup = model.qrImageUrl
+      ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><div class="qr-caption">Scan to verify (MoR EIMS)</div></div>`
+      : "";
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>${esc(heading)}</title>
+  <style>
+    body { font-family: Arial, sans-serif; font-size: 9px; color: #0f172a; margin: 0; }
+    .doc { width: 100%; box-sizing: border-box; }
+    .thermal-logo { display: block; max-height: 28px; max-width: 100%; object-fit: contain; margin: 0 auto 4px; }
+    .brand { text-align: center; font-size: 9px; text-transform: uppercase; letter-spacing: .05em; }
+    .title { text-align: center; font-size: 13px; font-weight: 800; margin: 2px 0; }
+    .meta { text-align: center; font-size: 8px; color: #475569; margin-bottom: 4px; }
+    .rule { border-top: 1px dashed #334155; margin: 6px 0; }
+    .row { display: flex; justify-content: space-between; gap: 6px; font-family: monospace; font-size: 8.5px; padding: 1px 0; }
+    .row .label { color: #64748b; white-space: nowrap; }
+    .row .value { text-align: right; overflow-wrap: anywhere; }
+    .item { margin: 4px 0; }
+    .item-desc { font-size: 9px; overflow-wrap: anywhere; }
+    .item-calc { text-align: right; font-family: monospace; font-size: 8.5px; }
+    .total-row { display: flex; justify-content: space-between; font-size: 9px; padding: 2px 0; }
+    .total-row.grand { font-size: 11px; font-weight: 800; border-top: 1px solid #0f172a; margin-top: 3px; padding-top: 4px; }
+    .qr { text-align: center; margin: 8px 0; }
+    .qr img { width: 150px; height: 150px; }
+    .qr-caption { font-size: 7px; color: #64748b; margin-top: 2px; }
+    .footer { text-align: center; font-size: 7px; color: #94a3b8; margin-top: 8px; }
+  </style>
+</head>
+<body>
+  <div class="doc">
+    ${logoInner}
+    <div class="brand">Ethio-Djibouti Railway S.C.</div>
+    <div class="title">${esc(heading)}</div>
+    <div class="meta">${esc(model.documentNumber)} &middot; ${esc(formatDate(model.issuedAt))}</div>
+    <div class="rule"></div>
+    ${summaryRows}
+    <div class="rule"></div>
+    ${itemBlocks}
+    <div class="rule"></div>
+    ${totalRows}
+    ${qrMarkup}
+    <div class="footer">Thank you</div>
+  </div>
+</body>
+</html>`;
+  }
+
   /**
    * Vector-drawn styled invoice/receipt used when headless Chromium is
    * unavailable. Mirrors the HTML layout closely enough to pass as the same
@@ -250,18 +382,7 @@ export class InvoiceDocumentService {
   }
 
   buildHtml(model: InvoiceDocumentModel): string {
-    const esc = (value: unknown) =>
-      String(value ?? "-")
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&#39;");
-    const money = (amount: unknown, currency = model.currency) =>
-      `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
-    const date = (value: unknown) =>
-      value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
-
+    const date = formatDate;
     const showCategory = Boolean(model.categoryHeader);
     const sealText =
       model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
@@ -292,7 +413,7 @@ export class InvoiceDocumentService {
     const totalRows = model.totals
       .map(
         (total) =>
-          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount))}</strong></div>`,
+          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
       )
       .join("");