@velaro/cli 1.4.53 → 1.4.55

package/lib/pdf/billing-document.js

@@ -0,0 +1,534 @@
+// Shared PDF generator for BillingSubscriptionInvoice documents (invoice / receipt).
+//
+// Structured as a plain module with no CLI/yargs dependency so a future server-side endpoint
+// (e.g. a `GET /api/BillingSubscription/invoice/{id}/pdf` action, mirroring the existing
+// BillingInvoiceRecordController.GetPdfAsync pattern) can call `generateBillingDocument()`
+// directly instead of re-implementing layout. The CLI command
+// (`velaro billing-subscription document`, see ../commands/billing-subscription.js) is the only
+// current caller.
+//
+// Known layout bugs this module exists to fix (see task history — a hand-built fpdf2 receipt
+// shipped with a too-small logo and a totals block whose amounts ran off the right edge of the
+// page):
+//   1. Logo is sized to a fixed, legible mm width (not "whatever fits"), see LOGO_WIDTH_PT below.
+//   2. The totals block's rendered width is measured against the ACTUAL fonts/sizes used, using
+//      the real pdfkit doc instance, and is right-aligned against the true printable right
+//      margin — never an eyeballed offset. See computeTotalsLayout().
+//
+// Data contract: `invoice`/`subscription`/`payments`/`balance` are the exact camelCase JSON shapes
+// returned by GET /api/BillingSubscription/invoice/{invoiceId} and
+// GET /api/BillingSubscription/invoice/{invoiceId}/payments — see cli/lib/commands/billing-subscription.js
+// for the real request() calls. This module never talks to the network itself.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import PDFDocument from 'pdfkit';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const LOGO_PATH = path.join(__dirname, '..', '..', 'assets', 'velaro-logo-lockup-full-color.png');
+
+// Decorative background patterns — a small, FIXED, checked-in set (never generated per-invoice;
+// that would be wasteful and would make PDF generation depend on a live AI endpoint). Generated
+// once via Velaro Studio's image endpoint (POST /api/assist/generate-image), same mechanism
+// documented in the `generate-brand-image` skill. Each is a subtle, low-opacity, brand-blue
+// abstract pattern on a near-white base — see cli/assets/billing-doc-patterns/README (none of
+// these differ meaningfully enough to need per-file docs beyond the filenames themselves).
+export const PATTERN_DIR = path.join(__dirname, '..', '..', 'assets', 'billing-doc-patterns');
+export const PATTERN_FILES = [
+  'wave-lines.png',
+  'dot-grid.png',
+  'concentric-arcs.png',
+  'diagonal-hatch.png',
+  'hex-grid.png',
+];
+// Composited at very low opacity full-bleed behind everything else on the page — the opaque
+// header/nav bars, alternating row bands, and status band already drawn on top of it act as the
+// scrim for the line-item/totals text; this constant keeps the pattern itself faint enough that
+// even the unshielded areas (page margins, non-alternating table rows) never threaten contrast.
+export const PATTERN_OPACITY = 0.14;
+
+/**
+ * Deterministically picks a pattern index for a given invoice identifier: the same invoice
+ * number always resolves to the same pattern (stable across re-renders/reprints), while
+ * different invoice numbers rotate through the full pattern set — same principle as
+ * velaro-marketing/admin/linkedin-engine.js's pickMotif(), not the same implementation.
+ */
+export function pickPatternIndex(seed) {
+  const str = String(seed ?? '');
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 31 + str.charCodeAt(i)) >>> 0; // unsigned 32-bit, avoids negative mod
+  }
+  return hash % PATTERN_FILES.length;
+}
+
+export function pickPatternFile(seed) {
+  return PATTERN_FILES[pickPatternIndex(seed)];
+}
+
+const patternBufferCache = new Map();
+function loadPatternBuffer(filename) {
+  if (patternBufferCache.has(filename)) return patternBufferCache.get(filename);
+  const buffer = fs.readFileSync(path.join(PATTERN_DIR, filename));
+  patternBufferCache.set(filename, buffer);
+  return buffer;
+}
+
+// Velaro brand palette (velaro-marketing/CLAUDE.md "COLOR CONTRAST" rule mirrored here — this is
+// a customer-facing document, same standard applies): dark text on light backgrounds is never
+// lighter than #374151, white text on dark/vivid bands only.
+export const COLOR = {
+  primaryBlue:  '#1670E7',
+  darkNavy:     '#0d1535',
+  darkText:     '#111111',
+  mutedText:    '#374151',
+  white:        '#ffffff',
+  rule:         '#e2e8f0',
+  rowAlt:       '#f8fafc',
+  successGreen: '#2FBF71',
+  amberDue:     '#c98f00', // text-safe amber per brand palette (not the raw #FFBD22 swatch)
+};
+
+// Bank remittance details, KV-first per this repo's secrets rule -- never hardcoded here.
+// Set 2026-09-15 (real values confirmed by Alex from an existing customer invoice):
+// az keyvault secret set --vault-name velaro-eastus-prd-kv --name Billing<Name> --value <value>
+const BANK_INFO_VAULT = 'velaro-eastus-prd-kv';
+const BANK_INFO_SECRETS = {
+  accountNumber: 'BillingBankAccountNumber',
+  achRouting: 'BillingAchRoutingNumber',
+  wireRouting: 'BillingWireRoutingNumber',
+  swift: 'BillingSwiftCode',
+};
+let bankInfoCache = null;
+async function getBankingInfo() {
+  if (bankInfoCache) return bankInfoCache;
+  try {
+    const { SecretClient } = await import('@azure/keyvault-secrets');
+    const { DefaultAzureCredential } = await import('@azure/identity');
+    const client = new SecretClient(`https://${BANK_INFO_VAULT}.vault.azure.net`, new DefaultAzureCredential());
+    const entries = await Promise.all(
+      Object.entries(BANK_INFO_SECRETS).map(async ([key, secretName]) => {
+        const secret = await client.getSecret(secretName);
+        return [key, secret.value];
+      })
+    );
+    bankInfoCache = Object.fromEntries(entries);
+  } catch (err) {
+    // Non-fatal: an invoice with no banking line is far better than one that refuses to
+    // generate because Key Vault was unreachable. Logged loudly so it's never silently missing.
+    console.error(`[WARN] Could not load banking info from Key Vault (${BANK_INFO_VAULT}): ${err.message}. Invoice will omit the ACH/wire remittance line.`);
+    bankInfoCache = null;
+  }
+  return bankInfoCache;
+}
+
+const MM_TO_PT = 2.8346456692913;
+export const PAGE_MARGIN = 50; // pt, ~17.6mm
+export const LOGO_WIDTH_PT = 35 * MM_TO_PT; // ~99pt -- 42mm (2026-09-15) was a bit too big per Alex, split the difference
+
+export function money(cents) {
+  const value = (Number(cents) || 0) / 100;
+  return `$${value.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function formatDate(input) {
+  if (!input) return null;
+  const date = new Date(input);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric', timeZone: 'UTC' });
+}
+
+/**
+ * Computes {labelColWidth, valueColWidth, columnGap, totalWidth, valueFontSize} for a two-column
+ * totals block (label | value, one row each) and asserts the block fits within
+ * `printableWidth` — measured against the SAME `doc` instance the document is being rendered
+ * into, so this reflects the real fonts/sizes in play, never a guessed value.
+ *
+ * Tries progressively smaller value font sizes (largest first) before giving up. Throws a
+ * descriptive Error — never returns a layout wider than `printableWidth`.
+ */
+export function computeTotalsLayout(doc, rows, printableWidth, opts = {}) {
+  if (!rows || rows.length === 0) throw new Error('computeTotalsLayout: rows must be non-empty.');
+
+  const labelFont = opts.labelFont ?? 'Helvetica';
+  const valueFont = opts.valueFont ?? 'Helvetica-Bold';
+  const labelFontSize = opts.labelFontSize ?? 10;
+  const columnGap = opts.columnGap ?? 18;
+  const fontSizesToTry = opts.fontSizesToTry ?? [opts.valueFontSize ?? 13, 12, 11, 10, 9];
+
+  doc.font(labelFont).fontSize(labelFontSize);
+  const labelColWidth = Math.max(...rows.map(r => doc.widthOfString(r.label)));
+
+  let last = null;
+  for (const valueFontSize of fontSizesToTry) {
+    doc.font(valueFont).fontSize(valueFontSize);
+    const valueColWidth = Math.max(...rows.map(r => doc.widthOfString(r.value)));
+    const totalWidth = labelColWidth + columnGap + valueColWidth;
+    last = { labelColWidth, valueColWidth, columnGap, totalWidth, valueFontSize, labelFontSize };
+    if (totalWidth <= printableWidth) return last;
+  }
+
+  throw new Error(
+    `Totals block would overflow the printable width (${printableWidth.toFixed(1)}pt) even at the ` +
+    `smallest tried value font size (${last.valueFontSize}pt): the block needs ${last.totalWidth.toFixed(1)}pt. ` +
+    `Rows: ${rows.map(r => `${r.label}=${r.value}`).join(', ')}. ` +
+    `Refusing to draw a totals block that would run off the page.`
+  );
+}
+
+function drawTotalsBlock(doc, rows, { rightEdge, leftEdge, y, rowGap = 6 }) {
+  const printableWidth = rightEdge - leftEdge;
+  const layout = computeTotalsLayout(doc, rows, printableWidth);
+  const blockLeftX = rightEdge - layout.totalWidth;
+
+  // Defensive: computeTotalsLayout already guarantees totalWidth <= printableWidth, but assert
+  // the resulting left edge is never pushed past the page's own left margin either.
+  if (blockLeftX < leftEdge) {
+    throw new Error(
+      `Totals block left edge (${blockLeftX.toFixed(1)}pt) would fall left of the printable area ` +
+      `(${leftEdge}pt) -- this should be impossible given computeTotalsLayout's own assertion.`
+    );
+  }
+
+  let cursorY = y;
+  for (const row of rows) {
+    const rowHeight = Math.max(layout.labelFontSize, layout.valueFontSize) + 4;
+
+    doc.font('Helvetica').fontSize(layout.labelFontSize).fillColor(row.labelColor ?? COLOR.mutedText);
+    doc.text(row.label, blockLeftX, cursorY + (rowHeight - layout.labelFontSize) / 2, {
+      width: layout.labelColWidth,
+      align: 'left',
+    });
+
+    doc.font('Helvetica-Bold').fontSize(layout.valueFontSize).fillColor(row.valueColor ?? COLOR.darkText);
+    doc.text(row.value, rightEdge - layout.valueColWidth, cursorY, {
+      width: layout.valueColWidth,
+      align: 'right',
+    });
+
+    if (row.rule) {
+      doc.moveTo(blockLeftX, cursorY - rowGap / 2)
+        .lineTo(rightEdge, cursorY - rowGap / 2)
+        .lineWidth(0.75)
+        .strokeColor(COLOR.rule)
+        .stroke();
+    }
+
+    cursorY += rowHeight + rowGap;
+  }
+
+  return cursorY;
+}
+
+/**
+ * Draws the chosen decorative pattern full-bleed behind everything else on the CURRENT page, at
+ * PATTERN_OPACITY. Must be called before any other drawing on that page so the opaque bands drawn
+ * afterward (header rule, dates band, line-item table header/alt rows, status band) sit on top of
+ * it and act as its scrim over text-bearing areas.
+ */
+function drawBackgroundPattern(doc, patternBuffer, pageWidth, pageHeight) {
+  doc.save();
+  doc.opacity(PATTERN_OPACITY);
+  // `cover` (not width/height) -- the source patterns are square (1024x1024) but the page is not
+  // (612x792pt LETTER); plain width/height would stretch x and y independently (~29% differential
+  // distortion), turning e.g. concentric-arcs.png's circles into ellipses. `cover` scales
+  // uniformly and crops to fill instead, so the pattern always renders at its true aspect ratio.
+  doc.image(patternBuffer, 0, 0, { cover: [pageWidth, pageHeight] });
+  doc.restore(); // restores opacity to 1 for every subsequent draw call on this page
+}
+
+function loadLogoBuffer() {
+  try {
+    return fs.readFileSync(LOGO_PATH);
+  } catch (err) {
+    // Logo is a checked-in asset (cli/assets/) — a missing file is a packaging bug, not a
+    // reasonable runtime condition to silently degrade past for a customer-facing document.
+    throw new Error(`Could not load Velaro logo asset at ${LOGO_PATH}: ${err.message}`);
+  }
+}
+
+/**
+ * Reads width/height straight out of a PNG's IHDR chunk (bytes 16-23 of any valid PNG) rather
+ * than hardcoding the current logo asset's pixel ratio -- if the checked-in asset is ever swapped
+ * for a differently-proportioned export, the header text/logo layout stays correct automatically
+ * instead of silently drifting out of sync with a stale constant.
+ */
+function readPngDimensions(buffer) {
+  if (buffer.length < 24 || buffer.toString('ascii', 1, 4) !== 'PNG') {
+    throw new Error('Logo asset does not look like a valid PNG (missing PNG signature) -- cannot compute its aspect ratio.');
+  }
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+function paymentSummary(payments) {
+  const applied = (payments || []).filter(p => (p.status ?? 'applied') === 'applied');
+  if (applied.length === 0) return { date: null, method: null };
+  const latest = applied.reduce((a, b) => (new Date(a.paymentDate) > new Date(b.paymentDate) ? a : b));
+  const methods = new Set(applied.map(p => p.method));
+  const method = methods.size === 1 ? [...methods][0] : 'multiple methods';
+  return { date: latest.paymentDate, method };
+}
+
+/**
+ * Generates a branded invoice or receipt PDF for a single BillingSubscriptionInvoice.
+ *
+ * @param {object} params
+ * @param {object} params.invoice - camelCase JSON from GET /api/BillingSubscription/invoice/{id}
+ * @param {object} [params.subscription] - camelCase JSON subscription snapshot from the same endpoint
+ * @param {object[]} [params.payments] - rows from GET .../invoice/{id}/payments (`.payments`)
+ * @param {object} [params.balance] - `.balance` from the same payments endpoint
+ * @param {'invoice'|'receipt'|'quote'} params.type
+ * @param {string} [params.outPath] - if provided, the PDF is written here; the Buffer is still returned
+ * @returns {Promise<Buffer>}
+ */
+export async function generateBillingDocument({ invoice, subscription, payments = [], balance, type, outPath }) {
+  if (!invoice) throw new Error('generateBillingDocument: invoice is required.');
+  if (type !== 'invoice' && type !== 'receipt' && type !== 'quote') {
+    throw new Error(`generateBillingDocument: type must be "invoice", "receipt", or "quote", got "${type}".`);
+  }
+
+  // The receipt-type guard: never generate payment-thank-you framing for an invoice that isn't
+  // actually paid in full. This is the ONLY gate for --type receipt and it fails closed --
+  // missing/unknown balance data refuses just as a partial payment does.
+  if (type === 'receipt' && !(balance && balance.paidInFull === true)) {
+    const knownState = balance ? `paidInFull=${balance.paidInFull}, remaining=${money(balance.remainingCents ?? 0)}` : 'no payment/balance data available';
+    throw new Error(
+      `Refusing to generate a receipt for invoice ${invoice.invoiceNumberFormatted ?? invoice.id}: ` +
+      `it is not recorded as paid in full (${knownState}). Generate --type invoice instead, or record ` +
+      `the remaining payment first.`
+    );
+  }
+
+  // Only an unpaid invoice needs remittance instructions -- a receipt (already paid) or a
+  // quote (not yet a real bill) has no reason to show them.
+  const balanceDueForBanking = type === 'invoice' ? (balance?.remainingCents ?? invoice.totalCents ?? 0) : 0;
+  const bankInfo = balanceDueForBanking > 0 ? await getBankingInfo() : null;
+
+  const logoBuffer = loadLogoBuffer();
+  const patternFile = pickPatternFile(invoice.invoiceNumberFormatted ?? invoice.invoiceNumber ?? invoice.id);
+  const patternBuffer = loadPatternBuffer(patternFile);
+  const doc = new PDFDocument({ size: 'LETTER', margin: PAGE_MARGIN, bufferPages: true });
+
+  const chunks = [];
+  doc.on('data', (c) => chunks.push(c));
+  const done = new Promise((resolve, reject) => {
+    doc.on('end', resolve);
+    doc.on('error', reject);
+  });
+
+  const pageWidth = doc.page.width;
+  const pageHeight = doc.page.height;
+  const leftEdge = PAGE_MARGIN;
+  const rightEdge = pageWidth - PAGE_MARGIN;
+  const printableWidth = rightEdge - leftEdge;
+
+  const isReceipt = type === 'receipt';
+  const isQuote = type === 'quote';
+  const title = isReceipt ? 'RECEIPT' : isQuote ? 'QUOTE' : 'INVOICE';
+  const customerName = invoice.customerName || subscription?.customerName || '(customer name unavailable)';
+
+  // Reserve room at the bottom of every page for the footer band so nothing drawn above it can
+  // ever run into (or past) it. Any block that might grow (line items, totals, status band) must
+  // check ensureSpace() before drawing and flow onto a fresh page rather than silently overflow.
+  const FOOTER_RESERVE = 40;
+  const bottomLimit = pageHeight - PAGE_MARGIN - FOOTER_RESERVE;
+  function ensureSpace(requiredHeight) {
+    if (y + requiredHeight > bottomLimit) {
+      doc.addPage();
+      y = PAGE_MARGIN;
+      drawBackgroundPattern(doc, patternBuffer, pageWidth, pageHeight);
+    }
+  }
+
+  // Draw the background pattern first so every subsequent draw call (header, bands, table,
+  // totals, status, footer) lands on top of it.
+  drawBackgroundPattern(doc, patternBuffer, pageWidth, pageHeight);
+
+  // ── Header: logo top-left, company identity clear of it, title top-right ──
+  const logoDimensions = readPngDimensions(logoBuffer);
+  const logoHeight = LOGO_WIDTH_PT * (logoDimensions.height / logoDimensions.width); // derived from the actual loaded asset, not a hardcoded ratio
+  doc.image(logoBuffer, leftEdge, PAGE_MARGIN, { width: LOGO_WIDTH_PT });
+
+  const companyInfoX = leftEdge; // below the logo, not beside it -- avoids any overlap regardless of title width
+  const companyInfoY = PAGE_MARGIN + logoHeight + 8;
+  doc.font('Helvetica-Bold').fontSize(12).fillColor(COLOR.darkText)
+    .text('Velaro Incorporated', companyInfoX, companyInfoY);
+  doc.font('Helvetica').fontSize(9).fillColor(COLOR.mutedText)
+    .text('billing@velaro.com', companyInfoX, companyInfoY + 15);
+
+  doc.font('Helvetica-Bold').fontSize(22).fillColor(COLOR.primaryBlue)
+    .text(title, leftEdge, PAGE_MARGIN, { width: printableWidth, align: 'right' });
+  // A quote is not a bill -- never surface the real INV- invoice number under a QUOTE title, since
+  // that number is a live BillingSubscriptionInvoice id a customer could reference as if it were
+  // an actual invoice. Render a distinct QUO- reference derived from the same id instead.
+  const displayedRef = isQuote
+    ? `QUO-${invoice.invoiceNumber ?? invoice.id}`
+    : (invoice.invoiceNumberFormatted ?? `#${invoice.id}`);
+  doc.font('Helvetica').fontSize(11).fillColor(COLOR.mutedText)
+    .text(displayedRef, leftEdge, PAGE_MARGIN + 28, { width: printableWidth, align: 'right' });
+  if (invoice.poNumber) {
+    doc.font('Helvetica').fontSize(9).fillColor(COLOR.mutedText)
+      .text(`PO: ${invoice.poNumber}`, leftEdge, PAGE_MARGIN + 43, { width: printableWidth, align: 'right' });
+  }
+
+  const headerBottomY = Math.max(companyInfoY + 26, PAGE_MARGIN + 56);
+  doc.moveTo(leftEdge, headerBottomY).lineTo(rightEdge, headerBottomY)
+    .lineWidth(2).strokeColor(COLOR.darkNavy).stroke();
+
+  // ── Bill To / dates band ──
+  let y = headerBottomY + 16;
+  const bandHeight = 64;
+  doc.rect(leftEdge, y, printableWidth, bandHeight).fill(COLOR.rowAlt);
+
+  const datesX = leftEdge + printableWidth / 2;
+
+  doc.font('Helvetica').fontSize(9).fillColor(COLOR.mutedText)
+    .text('BILL TO', leftEdge + 12, y + 9);
+  doc.font('Helvetica-Bold').fontSize(12).fillColor(COLOR.darkText)
+    .text(customerName, leftEdge + 12, y + 22, { width: datesX - (leftEdge + 12) - 10 }); // bounded so a long customer name wraps instead of overlapping the dates column
+  const receiptPaymentSummary = isReceipt ? paymentSummary(payments) : null;
+  const dateRows = isQuote
+    ? [
+        ['Quote Date', formatDate(invoice.invoiceDate)],
+        ['Service Period', `${formatDate(invoice.servicePeriodStart) ?? '?'} - ${formatDate(invoice.servicePeriodEnd) ?? '?'}`],
+      ]
+    : [
+        [isReceipt ? 'Payment Date' : 'Invoice Date', formatDate(isReceipt ? receiptPaymentSummary.date : invoice.invoiceDate)],
+        [isReceipt ? 'Payment Method' : 'Due Date', isReceipt ? (receiptPaymentSummary.method ?? '(unknown)') : (formatDate(invoice.dueDate) ?? '(none on file)')],
+        ['Service Period', `${formatDate(invoice.servicePeriodStart) ?? '?'} - ${formatDate(invoice.servicePeriodEnd) ?? '?'}`],
+      ];
+  const dateValueX = datesX + 90;
+  const dateValueMaxWidth = rightEdge - dateValueX; // bounded so a long value (e.g. a wide service-period range) wraps instead of running past the right margin
+  let dateY = y + 10;
+  for (const [label, value] of dateRows) {
+    doc.font('Helvetica').fontSize(9).fillColor(COLOR.mutedText).text(label, datesX, dateY, { continued: false, width: dateValueX - datesX - 4 });
+    doc.font('Helvetica-Bold').fontSize(10).fillColor(COLOR.darkText).text(value ?? '(none on file)', dateValueX, dateY, { width: dateValueMaxWidth });
+    dateY += 15;
+  }
+
+  y += bandHeight + 20;
+
+  // ── Line items table ──
+  const lineItems = invoice.lineItems && invoice.lineItems.length > 0
+    ? invoice.lineItems
+    : [{ description: 'Services rendered', amountCents: invoice.totalCents }];
+
+  const descColWidth = printableWidth * 0.72;
+  const amtColWidth = printableWidth - descColWidth;
+
+  ensureSpace(24);
+  doc.rect(leftEdge, y, printableWidth, 24).fill(COLOR.darkNavy);
+  doc.font('Helvetica-Bold').fontSize(10).fillColor(COLOR.white)
+    .text('Description', leftEdge + 10, y + 7, { width: descColWidth - 10 });
+  doc.text('Amount', leftEdge + descColWidth, y + 7, { width: amtColWidth - 10, align: 'right' });
+  y += 24;
+
+  let alt = false;
+  for (const item of lineItems) {
+    const description = item.description ?? '';
+    doc.font('Helvetica').fontSize(10);
+    // Measure the actual wrapped height for THIS description at the column width it will be
+    // drawn in, rather than assuming a fixed single-line row -- a long description must not
+    // silently overlap the next row's background/text.
+    const textHeight = doc.heightOfString(description, { width: descColWidth - 20 });
+    const rowHeight = Math.max(24, textHeight + 14);
+
+    // A row that would run into the footer reserve flows onto a fresh page instead of being cut
+    // off or overlapping the totals/status/footer drawn below it -- see the many-line-item test.
+    ensureSpace(rowHeight);
+
+    if (alt) doc.rect(leftEdge, y, printableWidth, rowHeight).fill(COLOR.rowAlt);
+    alt = !alt;
+
+    doc.font('Helvetica').fontSize(10).fillColor(COLOR.darkText)
+      .text(description, leftEdge + 10, y + 7, { width: descColWidth - 20 });
+    doc.text(money(item.amountCents), leftEdge + descColWidth, y + 7, { width: amtColWidth - 10, align: 'right' });
+    y += rowHeight;
+  }
+
+  doc.moveTo(leftEdge, y).lineTo(rightEdge, y).lineWidth(1).strokeColor(COLOR.rule).stroke();
+  y += 20;
+
+  // ── Totals block (the historically buggy part -- see module doc comment) ──
+  const amountPaidCents = balance?.appliedCents ?? (isReceipt ? invoice.totalCents : 0);
+  const balanceDueCents = Math.max(0, invoice.totalCents - amountPaidCents);
+
+  const totalsRows = [];
+  if (isQuote) {
+    totalsRows.push({ label: 'Quoted Amount', value: money(invoice.totalCents), rule: true });
+  } else if (isReceipt) {
+    totalsRows.push({ label: 'Invoice Amount', value: money(invoice.totalCents) });
+    totalsRows.push({ label: 'Amount Paid', value: money(amountPaidCents), valueColor: COLOR.successGreen });
+    totalsRows.push({ label: 'Balance Due', value: money(0), rule: true, valueColor: COLOR.successGreen });
+  } else {
+    totalsRows.push({ label: 'Invoice Amount', value: money(invoice.totalCents) });
+    if (amountPaidCents > 0) {
+      totalsRows.push({ label: 'Amount Paid', value: money(amountPaidCents), valueColor: COLOR.successGreen });
+    }
+    totalsRows.push({
+      label: 'Balance Due',
+      value: money(balanceDueCents),
+      rule: true,
+      valueColor: balanceDueCents > 0 ? COLOR.amberDue : COLOR.successGreen,
+    });
+  }
+
+  // Generous overestimate of the totals block's own height (rowGap + max font size per row) --
+  // drawTotalsBlock computes the precise layout itself, this just keeps the block off a page edge.
+  ensureSpace(totalsRows.length * 30 + 10);
+  y = drawTotalsBlock(doc, totalsRows, { leftEdge, rightEdge, y });
+
+  // ── Status band (fills what would otherwise be dead space, per no-blank-filler rule) ──
+  y += 14;
+  ensureSpace(26 + 14);
+  // Only append "(Net N)" when the invoice's actual invoiceDate->dueDate gap really is N days --
+  // subscription.netTermsDays is the subscription's STANDARD terms, which don't necessarily match
+  // this specific invoice's due date (e.g. a shortened or negotiated deadline). Showing "(Net 30)"
+  // next to a due date that's actually 9 days out is a real, visible inconsistency, not cosmetic --
+  // exactly the kind of thing a disputing customer's counsel would flag.
+  const actualNetDays = invoice.dueDate && invoice.invoiceDate
+    ? Math.round((new Date(invoice.dueDate) - new Date(invoice.invoiceDate)) / 86400000)
+    : null;
+  const netTermsMatch = subscription?.netTermsDays && actualNetDays === subscription.netTermsDays;
+  const bandLabel = isQuote
+    ? 'This is a quote, not a bill -- no payment is due.'
+    : isReceipt
+      ? 'PAID IN FULL - thank you for your business.'
+      : balanceDueCents > 0
+        ? `Payment due ${formatDate(invoice.dueDate) ?? 'on receipt'}${netTermsMatch ? ` (Net ${subscription.netTermsDays})` : ''}.`
+        : 'PAID IN FULL.';
+  const statusColor = isQuote ? COLOR.primaryBlue : (isReceipt || balanceDueCents === 0 ? COLOR.successGreen : COLOR.primaryBlue);
+  doc.rect(leftEdge, y, printableWidth, 28).fill(statusColor);
+  doc.font('Helvetica-Bold').fontSize(10).fillColor(COLOR.white)
+    .text(bandLabel, leftEdge + 12, y + 9, { width: printableWidth - 24 });
+  y += 28;
+
+  // ── ACH / wire remittance info (unpaid invoices only, sourced from Key Vault) ──
+  if (bankInfo) {
+    y += 12;
+    doc.font('Helvetica').fontSize(8).fillColor(COLOR.mutedText)
+      .text(
+        `Account Number: ${bankInfo.accountNumber}   |   ACH Routing: ${bankInfo.achRouting}   |   Wire Routing: ${bankInfo.wireRouting}   |   SWIFT: ${bankInfo.swift}`,
+        leftEdge, y, { width: printableWidth }
+      );
+  }
+
+  // ── Footer ──
+  const footerY = pageHeight - PAGE_MARGIN - 18;
+  doc.moveTo(leftEdge, footerY).lineTo(rightEdge, footerY).lineWidth(1).strokeColor(COLOR.rule).stroke();
+  const copyrightYear = new Date().getFullYear();
+  doc.font('Helvetica').fontSize(8).fillColor(COLOR.mutedText)
+    .text(`© ${copyrightYear} Velaro Incorporated  -  billing@velaro.com`, leftEdge, footerY + 6, { width: printableWidth });
+
+  doc.end();
+  await done;
+  const buffer = Buffer.concat(chunks);
+
+  if (outPath) {
+    fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+    fs.writeFileSync(outPath, buffer);
+  }
+
+  return buffer;
+}