domma-cms 0.55.1 → 0.66.0

package/plugins/invoice/plugin.js

@@ -17,17 +17,33 @@
  *   POST   /invoices             admin   create invoice (auto-numbers if number omitted)
  *   PUT    /invoices/:id         admin   update invoice
  *   DELETE /invoices/:id         admin   delete invoice
- *   GET    /invoices/:id/print   admin   printable HTML (browser to PDF)
+ *   POST   /invoices/:id/duplicate    admin  copy into a fresh numbered draft
+ *   GET    /invoices/:id/print        admin  printable HTML (Bearer clients)
+ *   GET    /invoices/:id/print-html   admin  the same markup as {html} JSON, for the admin
+ *
+ *   GET    /settings             admin   plugin settings, defaults merged in
+ *   PUT    /settings             admin   save plugin settings (whitelisted)
+ *
+ *   POST   /invoices/batch-pdf-link    admin  mint a 2-minute link for MANY invoices
+ *   GET    /invoices/batch-pdf?token=         one PDF, a page per invoice (token auth)
+ *
+ *   GET    /templates                  admin  the print layouts on offer
+ *   GET    /templates/:id/preview      admin  a worked example in that layout
  */
 import path from 'path';
+import {randomUUID} from 'crypto';
 import fs from 'fs/promises';
 import {fileURLToPath} from 'url';
 
 import defaultConfig from './config.js';
-import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../server/services/collections.js';
+import {pdfCapability, renderPdf} from './pdf.js';
+import {getConfig} from '../../server/config.js';
+import {createTransport} from '../../server/services/email.js';
+import {createEntry, deleteEntry, getCollection, getEntry, listEntries, updateCollection, updateEntry} from '../../server/services/collections.js';
+import {getPluginStates, savePluginState} from '../../server/services/plugins.js';
+import {syncPluginSchemas} from '../_lib/schemaSync.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const TEMPLATE_PATH = path.join(__dirname, 'templates', 'invoice-print.html');
 
 const ISSUERS_SLUG   = 'invoice-issuers';
 const RECEIVERS_SLUG = 'invoice-receivers';
@@ -64,11 +80,112 @@ function computeTotals(invoice) {
     const vatRate = invoice.vatEnabled ? (Number(invoice.vatRate) || 0) : 0;
     const vat = round2(subtotal * (vatRate / 100));
     const total = round2(subtotal + vat);
-    return { subtotal, vat, total, vatRate };
+    const paid = round2((Array.isArray(invoice.payments) ? invoice.payments : [])
+        .reduce((sum, p) => sum + (Number(p?.amount) || 0), 0));
+    // Overpayment is a real thing (a rounding, a duplicate transfer), so the
+    // balance is allowed to go negative rather than being clamped into a lie.
+    const balance = round2(total - paid);
+    return { subtotal, vat, total, vatRate, paid, balance };
+}
+
+/** Settled once nothing is outstanding. A zero-total invoice is not "paid". */
+function isSettled(invoice) {
+    const t = computeTotals(invoice);
+    return t.total > 0 && t.balance <= 0;
+}
+
+/**
+ * Is this invoice past its due date and still unpaid?
+ *
+ * Derived on read rather than stored, for the same reason `totals` is: a stored
+ * flag needs a job to flip it and is wrong until the job runs. The stored
+ * `status` is left alone - this is an additional fact about it, not a rewrite -
+ * so a PUT round-trip cannot silently turn `sent` into `overdue`.
+ *
+ * @param {object} invoice
+ * @param {Date}   [now]
+ * @returns {boolean}
+ */
+function isOverdue(invoice, now = new Date()) {
+    if (!invoice.dueDate) return false;
+    if (invoice.status === 'paid' || invoice.status === 'cancelled') return false;
+    if (invoice.status === 'draft') return false;
+    // Paid in full but nobody moved the status: still not overdue.
+    if (computeTotals(invoice).balance <= 0) return false;
+    // Due "on" a date means the whole of that day is still in time.
+    const due = new Date(`${invoice.dueDate}T23:59:59.999Z`);
+    if (Number.isNaN(due.getTime())) return false;
+    return due.getTime() < now.getTime();
+}
+
+const VALID_STATUSES = ['draft', 'sent', 'paid', 'overdue', 'cancelled'];
+
+/**
+ * Keep only the three fields a line item has, and coerce them.
+ *
+ * The totals are computed from these on every read, so anything else a client
+ * sends is dead weight in the stored entry at best.
+ *
+ * @param {*} items
+ * @returns {Array<{description: string, quantity: number, unitPrice: number}>}
+ */
+function cleanLineItems(items) {
+    if (!Array.isArray(items)) return [];
+    return items.map((li) => ({
+        description: String(li?.description ?? ''),
+        quantity:    Number(li?.quantity) || 0,
+        unitPrice:   Number(li?.unitPrice) || 0
+    }));
+}
+
+/** Rough shape check. The SMTP server is the real judge; this catches typing. */
+const LOOKS_LIKE_EMAIL = /^[^\s@,;]+@[^\s@,;]+\.[^\s@,;]+$/;
+
+/**
+ * One invoice to a whole mailing list is a mistake, not a feature - and every
+ * recipient sees the others, because these go in To.
+ */
+const MAX_RECIPIENTS = 25;
+
+/**
+ * Normalise whatever the client called a recipient into a list of addresses.
+ *
+ * @param   {string|string[]|undefined} value
+ * @returns {string[]} unique, trimmed, in the order given
+ */
+function parseRecipients(value) {
+    const raw = Array.isArray(value) ? value : String(value ?? '').split(/[,;]/);
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        const address = String(item ?? '').trim();
+        if (!address) continue;
+        const key = address.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(address);
+    }
+    return out;
+}
+
+/**
+ * The due date a payment term implies.
+ *
+ * @param   {string} issueDate ISO yyyy-mm-dd
+ * @param   {number} days
+ * @returns {string} ISO yyyy-mm-dd, or '' when there is no term to apply
+ */
+function dueDateFrom(issueDate, days) {
+    const terms = Number(days);
+    if (!issueDate || !Number.isFinite(terms) || terms <= 0) return '';
+    const date = new Date(`${issueDate}T00:00:00Z`);
+    if (Number.isNaN(date.getTime())) return '';
+    date.setUTCDate(date.getUTCDate() + terms);
+    return date.toISOString().slice(0, 10);
 }
 
 function withTotals(invoice) {
-    return { ...invoice, totals: computeTotals(invoice) };
+    return { ...invoice, totals: computeTotals(invoice), overdue: isOverdue(invoice) };
 }
 
 function formatMoney(amount, currency = 'GBP') {
@@ -79,13 +196,76 @@ function formatMoney(amount, currency = 'GBP') {
     }
 }
 
+/**
+ * The issuer's payment details, as an invoice prints them.
+ *
+ * Structured fields first, each labelled, because "sort code" and "account
+ * number" are read off the page by a human typing them into a banking app -
+ * a free-text blob is fine to write and miserable to use. `bankDetails` is
+ * kept as the overflow for anything that does not fit the six fields, and is
+ * appended rather than replaced so no existing issuer loses what it had.
+ *
+ * @param   {object} issuer
+ * @returns {Array<{label: string, value: string}>}
+ */
+function paymentLines(issuer) {
+    const rows = [];
+    const add = (label, value) => {
+        const v = String(value ?? '').trim();
+        if (v) rows.push({ label, value: v });
+    };
+
+    add('Account name', issuer.accountName);
+    add('Bank', issuer.bankName);
+    add('Sort code', issuer.sortCode);
+    add('Account number', issuer.accountNumber);
+    add('IBAN', issuer.iban);
+    add('BIC / SWIFT', issuer.bic);
+    return rows;
+}
+
 function formatDate(iso) {
     if (!iso) return '';
     return new Date(iso).toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' });
 }
 
-async function nextInvoiceNumber(prefix, padding) {
-    const year = new Date().getFullYear();
+/**
+ * Serialise this plugin's writes.
+ *
+ * FileAdapter's insert/update/delete are an unlocked read-modify-write over the
+ * whole collection file (server/services/adapters/FileAdapter.js): read the
+ * array, mutate it, write it back. Concurrent writes all read the same base and
+ * the last one wins - MEASURED, not assumed: twelve simultaneous creates each
+ * answered 201 with its own number and exactly one of them survived on disk.
+ *
+ * That is a core fault and it is not this plugin's to fix, but routing every
+ * mutating route here means the plugin cannot lose its own writes. It does not
+ * protect against another writer touching the same collection, and it holds
+ * only within a process.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+let writeGate = Promise.resolve();
+
+function withWriteLock(fn) {
+    const run = writeGate.then(fn);
+    // The chain must not stay rejected or every later write inherits the failure.
+    writeGate = run.then(() => {}, () => {});
+    return run;
+}
+
+/**
+ * Next number for the current year. Assumes the caller holds the write lock -
+ * taking it here as well would deadlock against withWriteLock.
+ *
+ * The high-water mark is remembered per year, so the scan happens once per
+ * process per year rather than once per invoice created.
+ */
+const highWater = new Map();   // "PREFIX-YYYY" -> highest sequence seen
+
+async function scanHighest(prefix, year) {
     const all = flattenList(await listEntries(INVOICES_SLUG, { limit: 100000 }));
     const re = new RegExp(`^${prefix}-${year}-(\\d+)$`);
     let max = 0;
@@ -96,11 +276,86 @@ async function nextInvoiceNumber(prefix, padding) {
             if (n > max) max = n;
         }
     }
-    return `${prefix}-${year}-${String(max + 1).padStart(padding, '0')}`;
+    return max;
+}
+
+async function allocateNumber(prefix, padding) {
+    const year = new Date().getFullYear();
+    const key = `${prefix}-${year}`;
+    if (!highWater.has(key)) highWater.set(key, await scanHighest(prefix, year));
+    const next = highWater.get(key) + 1;
+    highWater.set(key, next);
+    return `${prefix}-${year}-${String(next).padStart(padding, '0')}`;
 }
 
-async function loadPrintTemplate() {
-    return fs.readFile(TEMPLATE_PATH, 'utf8');
+/** A number supplied by hand still has to move the mark, or the next auto-number collides. */
+function noteNumber(number, prefix) {
+    const m = new RegExp(`^${prefix}-(\\d{4})-(\\d+)$`).exec(String(number || ''));
+    if (!m) return;
+    const key = `${prefix}-${m[1]}`;
+    const n = parseInt(m[2], 10);
+    if (!highWater.has(key) || n > highWater.get(key)) highWater.set(key, n);
+}
+
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+
+/** The shared print stylesheet, read once and inlined into every template. */
+let baseCssCache = null;
+
+async function loadBaseCss() {
+    if (baseCssCache === null) {
+        baseCssCache = await fs.readFile(path.join(TEMPLATES_DIR, '_base.css'), 'utf8')
+            .catch(() => '');
+    }
+    return baseCssCache;
+}
+
+/**
+ * The catalogue a site can choose from.
+ *
+ * Read from `templates/templates.json` rather than hard-coded, so dropping in
+ * `house-style.html` plus an entry is all it takes to add one.
+ *
+ * @returns {Promise<object[]>}
+ */
+async function loadTemplateCatalogue() {
+    try {
+        const raw = await fs.readFile(path.join(TEMPLATES_DIR, 'templates.json'), 'utf8');
+        const list = JSON.parse(raw).templates;
+        return Array.isArray(list) ? list : [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Pick the template file for a style, honouring whether there is a logo.
+ *
+ * An invoice with no logo does NOT get the logo template with an empty slot -
+ * a masthead that is a blank 80px gap reads as a page that failed to load. It
+ * gets a template built for having no logo, where the trading name takes that
+ * space. A style with nowhere to put a logo (minimal) has no `-nologo`
+ * sibling and is used as-is.
+ *
+ * @param   {string} style
+ * @param   {boolean} hasLogo
+ * @returns {Promise<string>} the template markup
+ */
+async function loadStyleTemplate(style, hasLogo) {
+    const id = String(style || 'classic').replace(/[^a-z0-9-]/gi, '');
+    const candidates = hasLogo
+        ? [`${id}.html`]
+        : [`${id}-nologo.html`, `${id}.html`];
+    // Always ends at the original file, so a site that has only ever had
+    // invoice-print.html keeps printing.
+    candidates.push('classic.html', 'invoice-print.html');
+
+    for (const name of candidates) {
+        try {
+            return await fs.readFile(path.join(TEMPLATES_DIR, name), 'utf8');
+        } catch { /* try the next one */ }
+    }
+    throw new Error('No invoice template could be read.');
 }
 
 function fillTemplate(template, vars) {
@@ -110,9 +365,138 @@ function fillTemplate(template, vars) {
     });
 }
 
+
+/**
+ * Pull the parts a printable invoice contributes to a merged document.
+ *
+ * Every template is a WHOLE html document (see templates/classic.html), so a
+ * batch cannot simply be concatenated - it would be N doctypes and N <head>s.
+ * The stylesheet is inline rather than fetched, which is what makes taking it
+ * apart with a regex reasonable here: the markup is ours, generated three
+ * lines earlier by fillTemplate, not arbitrary html off the network.
+ *
+ * @param   {string} html a full document from buildPrintHtml()
+ * @returns {{css: string, body: string}}
+ */
+function splitPrintDoc(html) {
+    const css = [...html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)]
+        .map((m) => m[1]).join('\n');
+    const body = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+    return { css, body: body ? body[1] : '' };
+}
+
+/**
+ * Selectors that mean "the page" and therefore have to become "this sheet".
+ *
+ * Anchored to the start of a rule - after `}`, after `{` (a rule inside
+ * `@media print`), after `;`, after a comment, or at the very beginning - so
+ * the word `body` inside a declaration, a string or a class name is left
+ * alone. `body.something` deliberately does not match: the lookahead demands
+ * the selector ends here.
+ */
+const SHEET_ROOT_SELECTOR = /(^|[{};]|\*\/)(\s*)(?:html\s*,\s*)?(?::root|body)(?=\s*[,{])/g;
+
+/**
+ * Confine one invoice's stylesheet to one sheet of a merged document.
+ *
+ * The templates were written to be alone in a document and they fight when
+ * they are not: `modern` hides `.top`, `classic-nologo` hides
+ * `.top .party .name`. A site only ever picks ONE style, but the logo and
+ * no-logo variants of it are chosen per invoice (see loadStyleTemplate), so a
+ * batch spanning an issuer with a logo and an issuer without one mixes two
+ * templates - and unscoped, the no-logo rule would delete the trading name
+ * from the invoices that do have a logo.
+ *
+ * `@scope` does the confining without rewriting a single selector, which is
+ * why it is used instead of prefixing: nested `@media` blocks, `*` and
+ * selector lists all keep working untouched. It is Chrome-only in practice and
+ * that is fine - Chrome is the only thing that ever renders this (see pdf.js).
+ *
+ * The exception is the handful of selectors that address the DOCUMENT rather
+ * than the invoice. `:scope` is outside nothing, so `body { padding: 24px }`
+ * would simply stop applying; rewritten to `:scope` it lands on the sheet
+ * wrapper, which is what the body used to be.
+ *
+ * @param   {string} css
+ * @param   {string} selector the sheet's own selector
+ * @returns {string}
+ */
+function scopeSheetCss(css, selector) {
+    const confined = css.replace(SHEET_ROOT_SELECTOR, (_, before, space) => `${before}${space}:scope`);
+    return `@scope (${selector}) {\n${confined}\n}`;
+}
+
+/**
+ * One A4 document holding many invoices, one per page.
+ *
+ * Identical stylesheets are emitted ONCE and shared by class rather than
+ * repeated per sheet - a batch of a hundred invoices is a hundred copies of
+ * the same eight kilobytes otherwise, and in the ordinary single-template case
+ * this collapses to exactly one `@scope` block for the whole document.
+ *
+ * @param   {string[]} docs full documents from buildPrintHtml()
+ * @param   {string}   title
+ * @returns {string}
+ */
+function mergePrintDocs(docs, title) {
+    const styles = [];       // distinct css, in first-seen order
+    const sheets = [];
+
+    for (const doc of docs) {
+        const { css, body } = splitPrintDoc(doc);
+        let index = styles.indexOf(css);
+        if (index === -1) index = styles.push(css) - 1;
+        sheets.push(`<div class="dm-sheet dm-sheet-s${index}">${body}</div>`);
+    }
+
+    const scoped = styles.map((css, index) => scopeSheetCss(css, `.dm-sheet-s${index}`)).join('\n');
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<style>
+/* The document's own rules. The per-invoice stylesheets below are scoped to a
+   sheet and no longer reach out here, so the page itself is dressed once. */
+:root { color-scheme: light; }
+html, body { margin: 0; padding: 0; background: #fff; }
+.dm-sheet + .dm-sheet { break-before: page; }
+/* A single invoice may still run to two pages; only the join is forced. */
+.dm-sheet { break-inside: auto; }
+${scoped}
+</style>
+</head>
+<body>
+${sheets.join('\n')}
+</body>
+</html>`;
+}
+
 export default async function invoicePlugin(fastify, options) {
     const { authenticate, requireAdmin } = options.auth;
-    const settings = { ...defaultConfig, ...(options.settings || {}) };
+
+    /**
+     * The settings as they are RIGHT NOW.
+     *
+     * `options.settings` is a snapshot taken when the plugin was registered, so
+     * a handler closing over it keeps serving the numbering prefix and the
+     * email wording the server booted with - and the settings panel appears to
+     * save nothing until someone restarts. getConfig() reads the file on every
+     * call (there is no cache behind it), so a fresh read per request is both
+     * correct and cheap.
+     *
+     * @returns {object}
+     */
+    function currentSettings() {
+        return { ...defaultConfig, ...(getPluginStates()?.invoice?.settings ?? options.settings ?? {}) };
+    }
+
+    // Payments, the send trail and the issuer's bank fields were all added
+    // after the collections were first created; without this they would exist
+    // only on a fresh install.
+    await syncPluginSchemas(path.join(__dirname, 'collections'),
+        {getCollection, updateCollection}, fastify.log);
     const adminGuard = { preHandler: [authenticate, requireAdmin] };
 
     // Issuers
@@ -125,21 +509,21 @@ export default async function invoicePlugin(fastify, options) {
         if (!body.name || typeof body.name !== 'string' || !body.name.trim()) {
             return reply.code(400).send({ error: 'name is required' });
         }
-        const entry = await createEntry(ISSUERS_SLUG, body, { source: 'admin' });
+        const entry = await withWriteLock(() => createEntry(ISSUERS_SLUG, body, { source: 'admin' }));
         return reply.code(201).send(toRecord(entry));
     });
 
     fastify.put('/issuers/:id', adminGuard, async (request, reply) => {
         const existing = await getEntry(ISSUERS_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Issuer not found' });
-        const updated = await updateEntry(ISSUERS_SLUG, request.params.id, { ...existing.data, ...(request.body ?? {}) });
+        const updated = await withWriteLock(() => updateEntry(ISSUERS_SLUG, request.params.id, { ...existing.data, ...(request.body ?? {}) }));
         return toRecord(updated);
     });
 
     fastify.delete('/issuers/:id', adminGuard, async (request, reply) => {
         const existing = await getEntry(ISSUERS_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Issuer not found' });
-        await deleteEntry(ISSUERS_SLUG, request.params.id);
+        await withWriteLock(() => deleteEntry(ISSUERS_SLUG, request.params.id));
         return { ok: true };
     });
 
@@ -153,21 +537,21 @@ export default async function invoicePlugin(fastify, options) {
         if (!body.name || typeof body.name !== 'string' || !body.name.trim()) {
             return reply.code(400).send({ error: 'name is required' });
         }
-        const entry = await createEntry(RECEIVERS_SLUG, body, { source: 'admin' });
+        const entry = await withWriteLock(() => createEntry(RECEIVERS_SLUG, body, { source: 'admin' }));
         return reply.code(201).send(toRecord(entry));
     });
 
     fastify.put('/receivers/:id', adminGuard, async (request, reply) => {
         const existing = await getEntry(RECEIVERS_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Receiver not found' });
-        const updated = await updateEntry(RECEIVERS_SLUG, request.params.id, { ...existing.data, ...(request.body ?? {}) });
+        const updated = await withWriteLock(() => updateEntry(RECEIVERS_SLUG, request.params.id, { ...existing.data, ...(request.body ?? {}) }));
         return toRecord(updated);
     });
 
     fastify.delete('/receivers/:id', adminGuard, async (request, reply) => {
         const existing = await getEntry(RECEIVERS_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Receiver not found' });
-        await deleteEntry(RECEIVERS_SLUG, request.params.id);
+        await withWriteLock(() => deleteEntry(RECEIVERS_SLUG, request.params.id));
         return { ok: true };
     });
 
@@ -184,48 +568,332 @@ export default async function invoicePlugin(fastify, options) {
     });
 
     fastify.post('/invoices', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
         const body = request.body ?? {};
         if (!body.issuerId)   return reply.code(400).send({ error: 'issuerId is required' });
         if (!body.receiverId) return reply.code(400).send({ error: 'receiverId is required' });
 
-        const data = {
-            number:      body.number || await nextInvoiceNumber(settings.numberPrefix, settings.numberPadding),
-            issuerId:    String(body.issuerId),
-            receiverId:  String(body.receiverId),
-            issueDate:   body.issueDate || new Date().toISOString().slice(0, 10),
-            dueDate:     body.dueDate || '',
-            status:      body.status || 'draft',
-            currency:    body.currency || settings.defaultCurrency,
-            vatEnabled:  body.vatEnabled !== undefined ? Boolean(body.vatEnabled) : true,
-            vatRate:     body.vatRate !== undefined ? Number(body.vatRate) : settings.defaultVatRate,
-            lineItems:   Array.isArray(body.lineItems) ? body.lineItems : [],
-            notes:       body.notes ?? ''
-        };
+        const issueDate = body.issueDate || new Date().toISOString().slice(0, 10);
+
+        const entry = await withWriteLock(async () => {
+            if (body.number) noteNumber(body.number, settings.numberPrefix);
+
+            const data = {
+                number:      body.number || await allocateNumber(settings.numberPrefix, settings.numberPadding),
+                issuerId:    String(body.issuerId),
+                receiverId:  String(body.receiverId),
+                issueDate,
+                // A blank due date is a real choice (invoices payable on
+                // receipt), so the term only fills one in when the client did
+                // not say - it never overrides an explicit ''.
+                dueDate:     body.dueDate !== undefined
+                    ? (body.dueDate || '')
+                    : dueDateFrom(issueDate, settings.defaultPaymentTermsDays),
+                status:      VALID_STATUSES.includes(body.status) ? body.status : 'draft',
+                currency:    body.currency || settings.defaultCurrency,
+                vatEnabled:  body.vatEnabled !== undefined
+                    ? Boolean(body.vatEnabled)
+                    : settings.vatEnabledByDefault !== false,
+                vatRate:     body.vatRate !== undefined ? Number(body.vatRate) : settings.defaultVatRate,
+                lineItems:   cleanLineItems(body.lineItems),
+                notes:       body.notes ?? ''
+            };
+            return createEntry(INVOICES_SLUG, data, { source: 'admin' });
+        });
 
-        const entry = await createEntry(INVOICES_SLUG, data, { source: 'admin' });
         return reply.code(201).send(withTotals(toRecord(entry)));
     });
 
     fastify.put('/invoices/:id', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
         const existing = await getEntry(INVOICES_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Invoice not found' });
-        const merged = { ...existing.data, ...(request.body ?? {}) };
-        if (Array.isArray(request.body?.lineItems)) merged.lineItems = request.body.lineItems;
-        const updated = await updateEntry(INVOICES_SLUG, request.params.id, merged);
+        const body = request.body ?? {};
+
+        // Whitelist rather than spread. A bare merge let a client write any key
+        // it liked onto the stored entry, including `totals`, which is supposed
+        // to be derived on read and would then sit there going stale.
+        const merged = { ...existing.data };
+        if (body.number     !== undefined) { merged.number = String(body.number).trim(); noteNumber(merged.number, settings.numberPrefix); }
+        if (body.issuerId   !== undefined) merged.issuerId   = String(body.issuerId);
+        if (body.receiverId !== undefined) merged.receiverId = String(body.receiverId);
+        if (body.issueDate  !== undefined) merged.issueDate  = String(body.issueDate);
+        if (body.dueDate    !== undefined) merged.dueDate    = body.dueDate ? String(body.dueDate) : '';
+        if (body.currency   !== undefined) merged.currency   = String(body.currency);
+        if (body.vatEnabled !== undefined) merged.vatEnabled = Boolean(body.vatEnabled);
+        if (body.vatRate    !== undefined) merged.vatRate    = Number(body.vatRate) || 0;
+        if (body.notes      !== undefined) merged.notes      = String(body.notes);
+        if (body.lineItems  !== undefined) merged.lineItems  = cleanLineItems(body.lineItems);
+        // Archived is a shelf, not a status: an archived invoice keeps whatever
+        // it was paid, cancelled or overdue, and the list simply stops showing
+        // it. Deleting a settled invoice is the thing nobody should have to do.
+        if (body.archived   !== undefined) merged.archived   = Boolean(body.archived);
+        // `payments` is deliberately NOT settable here: it has its own routes,
+        // which is what keeps the status reconciled with the ledger.
+        if (body.status     !== undefined) {
+            if (!VALID_STATUSES.includes(body.status)) {
+                return reply.code(400).send({ error: `status must be one of: ${VALID_STATUSES.join(', ')}` });
+            }
+            merged.status = body.status;
+        }
+
+        const updated = await withWriteLock(() => updateEntry(INVOICES_SLUG, request.params.id, merged));
         return withTotals(toRecord(updated));
     });
 
     fastify.delete('/invoices/:id', adminGuard, async (request, reply) => {
         const existing = await getEntry(INVOICES_SLUG, request.params.id);
         if (!existing) return reply.code(404).send({ error: 'Invoice not found' });
-        await deleteEntry(INVOICES_SLUG, request.params.id);
+        await withWriteLock(() => deleteEntry(INVOICES_SLUG, request.params.id));
         return { ok: true };
     });
 
-    // Print view (HTML; user prints to PDF from browser)
-    fastify.get('/invoices/:id/print', adminGuard, async (request, reply) => {
-        const entry = await getEntry(INVOICES_SLUG, request.params.id);
-        if (!entry) return reply.code(404).send('Invoice not found');
+    /**
+     * Copy an invoice into a fresh draft.
+     *
+     * Most invoices are last month's invoice with the dates moved on, which is
+     * otherwise a dozen fields retyped. The copy takes the parties, the money
+     * and the wording, and deliberately takes none of the history: it gets its
+     * own number, today's issue date, no payments and no send trail. A copy
+     * that inherited `sentAt` would claim to have been sent.
+     */
+    fastify.post('/invoices/:id/duplicate', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
+        const existing = await getEntry(INVOICES_SLUG, request.params.id);
+        if (!existing) return reply.code(404).send({ error: 'Invoice not found' });
+        const source = existing.data ?? {};
+
+        const entry = await withWriteLock(async () => createEntry(INVOICES_SLUG, {
+            number:     await allocateNumber(settings.numberPrefix, settings.numberPadding),
+            issuerId:   source.issuerId   ?? '',
+            receiverId: source.receiverId ?? '',
+            issueDate:  new Date().toISOString().slice(0, 10),
+            dueDate:    dueDateFrom(new Date().toISOString().slice(0, 10), settings.defaultPaymentTermsDays),
+            status:     'draft',
+            currency:   source.currency   ?? settings.defaultCurrency,
+            vatEnabled: source.vatEnabled !== false,
+            vatRate:    Number(source.vatRate) || settings.defaultVatRate,
+            lineItems:  cleanLineItems(source.lineItems),
+            notes:      source.notes ?? ''
+        }, { source: 'admin' }));
+
+        return reply.code(201).send(withTotals(toRecord(entry)));
+    });
+
+    // ---- Templates -------------------------------------------------------
+
+    /**
+     * The styles a printed invoice can be laid out in.
+     *
+     * `hasNoLogoVariant` is what the settings screen uses to tell somebody
+     * that a style behaves differently without a logo, rather than leaving
+     * them to discover it on a customer's invoice.
+     */
+    fastify.get('/templates', adminGuard, async () => {
+        const settings = currentSettings();
+        const catalogue = await loadTemplateCatalogue();
+        const [issuers] = await Promise.all([
+            listEntries(ISSUERS_SLUG, { limit: 1000 }).then(flattenList).catch(() => [])
+        ]);
+        return {
+            current: settings.template || 'classic',
+            // Whether a preview will actually show a logo: the house one, or
+            // any issuer carrying its own.
+            hasLogo: Boolean(settings.logoUrl) || issuers.some(i => i.logoUrl),
+            templates: catalogue.map(t => ({
+                id: t.id,
+                name: t.name || t.id,
+                description: t.description || '',
+                hasNoLogoVariant: t.nologo !== false
+            }))
+        };
+    });
+
+    /**
+     * A worked example in a given style, for the picker to show.
+     *
+     * Sample data rather than a real invoice, and deliberately: choosing a
+     * template is something you do before there are any invoices, and a
+     * preview that says "create an invoice first" is no help at all. The
+     * issuer is the real one where there is one, so the preview shows YOUR
+     * name and YOUR logo.
+     */
+    fastify.get('/templates/:id/preview', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
+        const style = String(request.params.id || 'classic');
+        const catalogue = await loadTemplateCatalogue();
+        if (catalogue.length && !catalogue.some(t => t.id === style)) {
+            return reply.code(404).send({ error: `No such template: ${style}` });
+        }
+
+        const issuers = await listEntries(ISSUERS_SLUG, { limit: 1000 })
+            .then(flattenList).catch(() => []);
+        const issuer = issuers.find(i => i.id === settings.defaultIssuerId) || issuers[0] || {};
+
+        // `?logo=0` previews the same style as an issuer with no logo sees it,
+        // which is the only way to look at the -nologo layout before you have
+        // an issuer without one.
+        const wantLogo = request.query.logo !== '0';
+        const logoTag = wantLogo ? logoFor(issuer, settings) : '';
+
+        const currency = settings.defaultCurrency || 'GBP';
+        const vatRate = Number(settings.defaultVatRate) || 0;
+        const lines = [
+            { description: 'Website design and build', quantity: 1, unitPrice: 2400 },
+            { description: 'Support retainer (March)', quantity: 3, unitPrice: 150 },
+            { description: 'Domain and hosting, annual', quantity: 1, unitPrice: 96 }
+        ];
+        const subtotal = round2(lines.reduce((sum, l) => sum + l.quantity * l.unitPrice, 0));
+        const vat = settings.vatEnabledByDefault !== false ? round2(subtotal * vatRate / 100) : 0;
+        const today = new Date().toISOString().slice(0, 10);
+
+        const template = await loadStyleTemplate(style, Boolean(logoTag));
+        const html = fillTemplate(template, {
+            baseCss:       await loadBaseCss(),
+            number:        `${settings.numberPrefix || 'INV'}-${new Date().getFullYear()}-${'1'.padStart(Number(settings.numberPadding) || 4, '0')}`,
+            issueDate:     escapeHtml(formatDate(today)),
+            dueDate:       `<div><strong>Due:</strong> ${escapeHtml(formatDate(dueDateFrom(today, settings.defaultPaymentTermsDays) || today))}</div>`,
+            status:        'SENT',
+            issuerLogo:    logoTag,
+            issuerName:    escapeHtml(issuer.name || 'Your Company'),
+            issuerAddress: escapeHtml(issuer.address || '1 Example Street\nYour Town\nAB1 2CD').replace(/\n/g, '<br>'),
+            issuerEmail:   escapeHtml(issuer.email || 'accounts@example.com'),
+            issuerPhone:   escapeHtml(issuer.phone || '01234 567890'),
+            issuerVat:     issuer.vatNumber ? `<div>VAT: ${escapeHtml(issuer.vatNumber)}</div>` : '<div>VAT: GB000000000</div>',
+            receiverName:    'Sample Client Ltd',
+            receiverAddress: '42 Client Road<br>Their Town<br>XY9 8ZZ',
+            receiverEmail:   'accounts@sampleclient.example',
+            receiverVat:     '',
+            items: lines.map(l => `<tr>
+  <td>${escapeHtml(l.description)}</td>
+  <td class="num">${l.quantity}</td>
+  <td class="num">${formatMoney(l.unitPrice, currency)}</td>
+  <td class="num">${formatMoney(round2(l.quantity * l.unitPrice), currency)}</td>
+</tr>`).join(''),
+            subtotal: formatMoney(subtotal, currency),
+            vatRow:   vat ? `<tr><th>VAT (${escapeHtml(String(vatRate))}%)</th><td class="num">${formatMoney(vat, currency)}</td></tr>` : '',
+            paidRows: '',
+            total:    formatMoney(round2(subtotal + vat), currency),
+            notes:    '<div class="notes"><strong>Notes</strong><br>Thanks very much - payment within the terms above, please.</div>',
+            bankDetails: buildPaymentBlock(issuer),
+            footerNote:  escapeHtml(settings.footerNote || ''),
+            // A preview must never raise a print dialog, and the Print button
+            // belongs to the printout rather than to a thumbnail of it.
+            autoPrint: '<style>.actions{display:none}</style>'
+        });
+
+        return { html, style, withLogo: Boolean(logoTag) };
+    });
+
+    // ---- Settings --------------------------------------------------------
+    //
+    // Plugin settings live in config/plugins.json under invoice.settings, and
+    // the way to reach them is getPluginStates() / savePluginState().
+    // getConfig()/saveConfig() in server/config.js take a FILE NAME, which is
+    // the mistake this same endpoint shipped with in two other plugins.
+
+    fastify.get('/settings', adminGuard, async () => {
+        return currentSettings();
+    });
+
+    fastify.put('/settings', adminGuard, async (request, reply) => {
+        const body = request.body ?? {};
+
+        const text = (key) => (body[key] !== undefined ? { [key]: String(body[key] ?? '') } : null);
+        const bool = (key) => (body[key] !== undefined ? { [key]: Boolean(body[key]) } : null);
+        const int  = (key, min, max, fallback) => {
+            if (body[key] === undefined) return null;
+            const n = Math.round(Number(body[key]));
+            return { [key]: Number.isFinite(n) ? Math.min(Math.max(n, min), max) : fallback };
+        };
+        const num  = (key, min, max, fallback) => {
+            if (body[key] === undefined) return null;
+            const n = Number(body[key]);
+            return { [key]: Number.isFinite(n) ? Math.min(Math.max(n, min), max) : fallback };
+        };
+
+        // A PATCH over what is stored, not over the defaults: the settings
+        // panel saves one tab at a time, and starting from defaultConfig would
+        // have saving the email wording quietly reset the currency and the
+        // numbering to factory values.
+        //
+        // Whitelisted, and clamped where a number has a sane range: the padding
+        // reaches padStart() and the VAT rate reaches arithmetic on every
+        // invoice, so "abc" or 10000 arriving here would be discovered later,
+        // in the totals, by someone reading a wrong invoice.
+        const merged = Object.assign(currentSettings(),
+            text('numberPrefix'),
+            int('numberPadding', 1, 10, defaultConfig.numberPadding),
+            num('defaultVatRate', 0, 100, defaultConfig.defaultVatRate),
+            text('defaultCurrency'),
+            bool('vatEnabledByDefault'),
+            int('defaultPaymentTermsDays', 0, 365, defaultConfig.defaultPaymentTermsDays),
+            text('defaultIssuerId'),
+            text('logoUrl'),
+            text('template'),
+            text('footerNote'),
+            text('emailSubject'),
+            text('emailIntro'),
+            bool('attachPdf')
+        );
+
+        // A currency code reaches Intl.NumberFormat, which THROWS on a bad one
+        // - and it is called while rendering, so a typo here would take the
+        // print route down rather than show a wrong symbol.
+        merged.defaultCurrency = String(merged.defaultCurrency || '').trim().toUpperCase();
+        if (!/^[A-Z]{3}$/.test(merged.defaultCurrency)) {
+            return reply.code(400).send({ error: 'defaultCurrency must be a three-letter ISO code, e.g. GBP.' });
+        }
+
+        savePluginState('invoice', { settings: merged });
+        return { ok: true, settings: merged };
+    });
+
+    /**
+     * The Payment panel: the six structured fields as a small table, then
+     * whatever free text the issuer kept in `bankDetails` beneath it.
+     *
+     * @param   {object} issuer
+     * @returns {string} markup, or '' when there is nothing to pay into
+     */
+    function buildPaymentBlock(issuer) {
+        const rows = paymentLines(issuer);
+        const notes = String(issuer.bankDetails ?? '').trim();
+        if (!rows.length && !notes) return '';
+
+        const table = rows.length
+            ? `<table class="pay">${rows.map(r =>
+                `<tr><th>${escapeHtml(r.label)}</th><td>${escapeHtml(r.value)}</td></tr>`).join('')}</table>`
+            : '';
+        const free = notes ? `<div class="pay-notes">${escapeHtml(notes).replace(/\n/g, '<br>')}</div>` : '';
+
+        return `<div class="bank"><strong>Payment</strong>${table}${free}</div>`;
+    }
+
+    /**
+     * The logo to print for an issuer: theirs, or the one from settings.
+     *
+     * @param   {object} issuer
+     * @param   {object} settings
+     * @returns {string} an <img> tag, or ''
+     */
+    function logoFor(issuer, settings) {
+        const src = String(issuer.logoUrl || settings.logoUrl || '').trim();
+        if (!src) return '';
+        return `<img src="${escapeHtml(src)}" alt="${escapeHtml(issuer.name || '')}" class="logo">`;
+    }
+
+    /**
+     * Build the printable A4 markup for one invoice.
+     *
+     * @param {string} invoiceId
+     * @param {boolean} autoPrint  emit the window.print() bootstrap
+     * @returns {Promise<string|null>} markup, or null when the invoice is gone
+     */
+    async function buildPrintHtml(invoiceId, autoPrint) {
+        const settings = currentSettings();
+        const entry = await getEntry(INVOICES_SLUG, invoiceId);
+        if (!entry) return null;
         const invoice = withTotals(toRecord(entry));
 
         const [issuerEntry, receiverEntry] = await Promise.all([
@@ -248,18 +916,31 @@ export default async function invoicePlugin(fastify, options) {
 </tr>`;
         }).join('');
 
+        const paidRows = invoice.totals.paid > 0
+            ? `<tr><th>Paid</th><td class="num">-${formatMoney(invoice.totals.paid, currency)}</td></tr>`
+              + `<tr class="balance${invoice.totals.balance <= 0 ? ' settled' : ''}">`
+              + `<th>${invoice.totals.balance <= 0 ? 'Paid in full' : 'Balance due'}</th>`
+              + `<td class="num">${formatMoney(Math.max(0, invoice.totals.balance), currency)}</td></tr>`
+            : '';
+
         const vatRow = invoice.vatEnabled
             ? `<tr><th>VAT (${escapeHtml(String(invoice.totals.vatRate))}%)</th><td class="num">${formatMoney(invoice.totals.vat, currency)}</td></tr>`
             : '';
 
-        const template = await loadPrintTemplate();
-        const html = fillTemplate(template, {
+        const logoTag = logoFor(issuer, settings);
+        const template = await loadStyleTemplate(settings.template, Boolean(logoTag));
+        return fillTemplate(template, {
+            baseCss:       await loadBaseCss(),
             number:        escapeHtml(invoice.number || ''),
             issueDate:     escapeHtml(formatDate(invoice.issueDate)),
             dueDate:       invoice.dueDate ? `<div><strong>Due:</strong> ${escapeHtml(formatDate(invoice.dueDate))}</div>` : '',
             status:        escapeHtml((invoice.status || 'draft').toUpperCase()),
             issuerName:    escapeHtml(issuer.name || ''),
-            issuerLogo:    issuer.logoUrl ? `<img src="${escapeHtml(issuer.logoUrl)}" alt="${escapeHtml(issuer.name || '')}" class="logo">` : '',
+            // The issuer's own logo wins; the one uploaded in settings is the
+            // house default, so a single-company install sets it once and every
+            // issuer it ever adds is already branded. Empty here means the
+            // -nologo template was chosen above, which has no slot for it.
+            issuerLogo:    logoTag,
             issuerAddress: escapeHtml(issuer.address || '').replace(/\n/g, '<br>'),
             issuerEmail:   escapeHtml(issuer.email || ''),
             issuerPhone:   escapeHtml(issuer.phone || ''),
@@ -271,13 +952,505 @@ export default async function invoicePlugin(fastify, options) {
             items:         itemsHtml || '<tr><td colspan="4" class="muted">No line items.</td></tr>',
             subtotal:      formatMoney(invoice.totals.subtotal, currency),
             vatRow,
+            paidRows,
             total:         formatMoney(invoice.totals.total, currency),
             notes:         invoice.notes ? `<div class="notes"><strong>Notes</strong><br>${escapeHtml(invoice.notes).replace(/\n/g, '<br>')}</div>` : '',
-            bankDetails:   issuer.bankDetails ? `<div class="bank"><strong>Payment</strong><br>${escapeHtml(issuer.bankDetails).replace(/\n/g, '<br>')}</div>` : '',
+            bankDetails:   buildPaymentBlock(issuer),
             footerNote:    escapeHtml(settings.footerNote || ''),
-            autoPrint:     request.query.print === '1' ? '<script>window.addEventListener("load",()=>setTimeout(()=>window.print(),200));</script>' : ''
+            autoPrint:     autoPrint ? '<script>window.addEventListener("load",()=>setTimeout(()=>window.print(),200));</script>' : ''
         });
+    }
 
+    // Print view (HTML; user prints to PDF from browser). Kept for Bearer-holding
+    // clients - a browser tab cannot reach it, see /print-html below.
+    fastify.get('/invoices/:id/print', adminGuard, async (request, reply) => {
+        const html = await buildPrintHtml(request.params.id, request.query.print === '1');
+        if (html === null) return reply.code(404).send('Invoice not found');
         reply.type('text/html').send(html);
     });
+
+    // ---- Payments --------------------------------------------------------
+
+    const PAYMENT_METHODS = ['bank-transfer', 'card', 'cash', 'cheque', 'direct-debit', 'other'];
+
+    /**
+     * Move the stored status to match what has actually been paid.
+     *
+     * Deliberately a transition triggered by recording or removing a payment,
+     * not something derived on read like `overdue`: "paid" is a claim about the
+     * real world that somebody made, and it should survive being looked at.
+     * Only the two statuses that describe an open invoice are touched, so a
+     * cancelled invoice stays cancelled whatever the ledger says.
+     *
+     * @param {object} data invoice data, with payments already applied
+     * @returns {object} the same object, possibly with a new status
+     */
+    function reconcileStatus(data) {
+        const settled = isSettled(data);
+        if (settled && (data.status === 'sent' || data.status === 'overdue' || data.status === 'draft')) {
+            data.status = 'paid';
+        } else if (!settled && data.status === 'paid') {
+            data.status = 'sent';
+        }
+        return data;
+    }
+
+    /** GET /invoices/:id/payments */
+    fastify.get('/invoices/:id/payments', adminGuard, async (request, reply) => {
+        const entry = await getEntry(INVOICES_SLUG, request.params.id);
+        if (!entry) return reply.code(404).send({ error: 'Invoice not found' });
+        const invoice = withTotals(toRecord(entry));
+        return { payments: invoice.payments ?? [], totals: invoice.totals };
+    });
+
+    /** POST /invoices/:id/payments */
+    fastify.post('/invoices/:id/payments', adminGuard, async (request, reply) => {
+        const body = request.body ?? {};
+
+        const amount = Number(body.amount);
+        if (!Number.isFinite(amount) || amount <= 0) {
+            return reply.code(400).send({ error: 'amount must be a positive number' });
+        }
+        if (body.method !== undefined && !PAYMENT_METHODS.includes(body.method)) {
+            return reply.code(400).send({ error: `method must be one of: ${PAYMENT_METHODS.join(', ')}` });
+        }
+
+        const updated = await withWriteLock(async () => {
+            const entry = await getEntry(INVOICES_SLUG, request.params.id);
+            if (!entry) return null;
+
+            const payment = {
+                id:        randomUUID(),
+                date:      body.date || new Date().toISOString().slice(0, 10),
+                amount:    round2(amount),
+                method:    body.method || 'bank-transfer',
+                reference: String(body.reference ?? '').trim(),
+                recordedAt: new Date().toISOString()
+            };
+
+            const data = {
+                ...entry.data,
+                payments: [...(Array.isArray(entry.data.payments) ? entry.data.payments : []), payment]
+            };
+            return updateEntry(INVOICES_SLUG, request.params.id, reconcileStatus(data));
+        });
+
+        if (!updated) return reply.code(404).send({ error: 'Invoice not found' });
+        return reply.code(201).send(withTotals(toRecord(updated)));
+    });
+
+    /** DELETE /invoices/:id/payments/:paymentId */
+    fastify.delete('/invoices/:id/payments/:paymentId', adminGuard, async (request, reply) => {
+        const result = await withWriteLock(async () => {
+            const entry = await getEntry(INVOICES_SLUG, request.params.id);
+            if (!entry) return { missing: 'invoice' };
+
+            const payments = Array.isArray(entry.data.payments) ? entry.data.payments : [];
+            const next = payments.filter(p => p.id !== request.params.paymentId);
+            if (next.length === payments.length) return { missing: 'payment' };
+
+            const data = { ...entry.data, payments: next };
+            return { updated: await updateEntry(INVOICES_SLUG, request.params.id, reconcileStatus(data)) };
+        });
+
+        if (result.missing) return reply.code(404).send({ error: `${result.missing === 'invoice' ? 'Invoice' : 'Payment'} not found` });
+        return withTotals(toRecord(result.updated));
+    });
+
+    // ---- Sending ---------------------------------------------------------
+
+    /**
+     * Email an invoice to its receiver.
+     *
+     * The PDF is attached when the host can render one; where it cannot, the
+     * printable invoice goes inline as the HTML body instead, so the mail is
+     * still a usable invoice rather than a note saying one exists.
+     *
+     * This calls transport.sendMail directly rather than the email service's
+     * sendEmail(), which destructures a fixed set of options and has no
+     * attachments parameter - and server/ is replaced wholesale by the updater,
+     * so it is not ours to extend. The cost is that these sends do not reach
+     * getLastSendResult(), i.e. they are absent from the SMTP line in Health.
+     */
+    /**
+     * What the Send dialog should open with.
+     *
+     * The subject and covering note are templated from settings, and templating
+     * them here rather than in the browser keeps one source of truth for them.
+     */
+    fastify.get('/invoices/:id/send-defaults', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
+        const entry = await getEntry(INVOICES_SLUG, request.params.id);
+        if (!entry) return reply.code(404).send({ error: 'Invoice not found' });
+        const invoice = withTotals(toRecord(entry));
+
+        const [issuerEntry, receiverEntry] = await Promise.all([
+            invoice.issuerId   ? getEntry(ISSUERS_SLUG,   invoice.issuerId)   : null,
+            invoice.receiverId ? getEntry(RECEIVERS_SLUG, invoice.receiverId) : null
+        ]);
+        const issuer   = issuerEntry   ? toRecord(issuerEntry)   : {};
+        const receiver = receiverEntry ? toRecord(receiverEntry) : {};
+
+        const vars = {
+            number:   invoice.number || '',
+            issuer:   issuer.name || '',
+            receiver: receiver.company || receiver.name || '',
+            total:    formatMoney(invoice.totals.total, invoice.currency || settings.defaultCurrency),
+            dueDate:  invoice.dueDate ? formatDate(invoice.dueDate) : ''
+        };
+
+        const cap = await pdfCapability();
+        return {
+            to:            receiver.email || '',
+            subject:       fillTemplate(settings.emailSubject, vars),
+            message:       fillTemplate(settings.emailIntro, vars),
+            canAttachPdf:  cap.available,
+            attachPdf:     cap.available && settings.attachPdf !== false,
+            sentAt:        invoice.sentAt || null,
+            sendCount:     Number(invoice.sendCount) || 0
+        };
+    });
+
+    fastify.post('/invoices/:id/send', adminGuard, async (request, reply) => {
+        const settings = currentSettings();
+        const body = request.body ?? {};
+
+        const entry = await getEntry(INVOICES_SLUG, request.params.id);
+        if (!entry) return reply.code(404).send({ error: 'Invoice not found' });
+        const invoice = withTotals(toRecord(entry));
+
+        const [issuerEntry, receiverEntry] = await Promise.all([
+            invoice.issuerId   ? getEntry(ISSUERS_SLUG,   invoice.issuerId)   : null,
+            invoice.receiverId ? getEntry(RECEIVERS_SLUG, invoice.receiverId) : null
+        ]);
+        const issuer   = issuerEntry   ? toRecord(issuerEntry)   : {};
+        const receiver = receiverEntry ? toRecord(receiverEntry) : {};
+
+        // `to` may be one address, a comma/semicolon list, or an array - the
+        // Send dialog builds it from a contact group, so a dozen recipients in
+        // one field is the ordinary case rather than the exotic one.
+        const recipients = parseRecipients(body.to ?? receiver.email);
+        if (!recipients.length) {
+            return reply.code(400).send({
+                error: 'No recipient. This receiver has no email address, so pass one in `to`.'
+            });
+        }
+        const rejected = recipients.filter(address => !LOOKS_LIKE_EMAIL.test(address));
+        if (rejected.length) {
+            return reply.code(400).send({ error: `Not an email address: ${rejected.join(', ')}` });
+        }
+        if (recipients.length > MAX_RECIPIENTS) {
+            return reply.code(400).send({
+                error: `That is ${recipients.length} recipients; ${MAX_RECIPIENTS} is the limit for one invoice.`
+            });
+        }
+        const to = recipients.join(', ');
+
+        const currency = invoice.currency || settings.defaultCurrency;
+        const vars = {
+            number:   invoice.number || '',
+            issuer:   issuer.name || '',
+            receiver: receiver.company || receiver.name || '',
+            total:    formatMoney(invoice.totals.total, currency),
+            dueDate:  invoice.dueDate ? formatDate(invoice.dueDate) : ''
+        };
+
+        const subject = String(body.subject || fillTemplate(settings.emailSubject, vars)).trim()
+            || `Invoice ${vars.number}`;
+        const intro = String(body.message ?? fillTemplate(settings.emailIntro, vars));
+
+        const html = await buildPrintHtml(request.params.id, false);
+        if (html === null) return reply.code(404).send({ error: 'Invoice not found' });
+
+        const wantPdf = body.attachPdf !== undefined ? Boolean(body.attachPdf) : settings.attachPdf !== false;
+        const cap = await pdfCapability();
+        const attachments = [];
+        if (wantPdf && cap.available) {
+            try {
+                attachments.push({
+                    filename: `${String(vars.number || 'invoice').replace(/[^\w.-]/g, '_')}.pdf`,
+                    content: await renderPdf(html, { base: `${request.protocol}://${request.hostname}/` }),
+                    contentType: 'application/pdf'
+                });
+            } catch (err) {
+                // An invoice that arrives without its attachment beats one that
+                // never arrives, so this is a warning and not a failure.
+                request.log.warn({ err }, '[invoice] PDF attach failed; sending without it');
+            }
+        }
+
+        const summary = [
+            `<p>${escapeHtml(intro)}</p>`,
+            '<ul>',
+            `<li><strong>Invoice:</strong> ${escapeHtml(vars.number)}</li>`,
+            `<li><strong>Total:</strong> ${escapeHtml(vars.total)}</li>`,
+            vars.dueDate ? `<li><strong>Due:</strong> ${escapeHtml(vars.dueDate)}</li>` : '',
+            '</ul>'
+        ].join('');
+
+        // No attachment means the invoice itself has to be the body.
+        const emailHtml = attachments.length
+            ? `<div style="font-family:system-ui,sans-serif;font-size:15px;line-height:1.5;">${summary}<p>${escapeHtml(settings.footerNote || '')}</p></div>`
+            : `<div style="font-family:system-ui,sans-serif;font-size:15px;line-height:1.5;">${summary}</div><hr>${html}`;
+
+        const text = [intro, '', `Invoice: ${vars.number}`, `Total: ${vars.total}`,
+            vars.dueDate ? `Due: ${vars.dueDate}` : '', '', settings.footerNote || ''
+        ].filter(Boolean).join('\n');
+
+        const smtp = getConfig('site').smtp || {};
+        try {
+            const transport = await createTransport(smtp);
+            await transport.sendMail({
+                from: smtp.fromName ? `"${smtp.fromName}" <${smtp.fromAddress}>` : smtp.fromAddress,
+                to,
+                subject,
+                text,
+                html: emailHtml,
+                attachments
+            });
+        } catch (err) {
+            request.log.error({ err }, '[invoice] send failed');
+            return reply.code(502).send({ error: `Could not send the invoice: ${err.message}` });
+        }
+
+        // The send trail, and the status move that goes with it. A draft that
+        // has been emailed is not a draft any more.
+        const merged = {
+            ...entry.data,
+            sentAt: new Date().toISOString(),
+            sentTo: to,
+            sendCount: (Number(entry.data.sendCount) || 0) + 1
+        };
+        const markSent = body.markSent !== undefined ? Boolean(body.markSent) : true;
+        if (markSent && merged.status === 'draft') merged.status = 'sent';
+
+        const updated = await withWriteLock(() => updateEntry(INVOICES_SLUG, request.params.id, merged));
+        return {
+            ok: true,
+            to,
+            subject,
+            attached: attachments.length > 0,
+            invoice: withTotals(toRecord(updated))
+        };
+    });
+
+    // ---- PDF -------------------------------------------------------------
+
+    const PDF_TOKEN_TYPE = 'invoice-pdf';
+
+    /** Can this host render one at all? The admin asks before offering the button. */
+    fastify.get('/pdf/status', adminGuard, async () => {
+        const cap = await pdfCapability();
+        return { available: cap.available, reason: cap.reason };
+    });
+
+    // A download is a browser NAVIGATION, and `authenticate` is Bearer-only, so
+    // the admin cannot simply link to the PDF route - that is the same 401 the
+    // Print button used to hit. The token goes in the QUERY STRING, not a path
+    // param: Fastify caps a route param at 100 characters and a signed token is
+    // far longer, so /pdf/:token would silently 404 (see previewLinks.js, which
+    // learned this the same way). Two minutes is short enough that there is
+    // nothing to revoke.
+    fastify.post('/invoices/:id/pdf-link', adminGuard, async (request, reply) => {
+        const cap = await pdfCapability();
+        if (!cap.available) return reply.code(501).send({ error: cap.reason });
+
+        const entry = await getEntry(INVOICES_SLUG, request.params.id);
+        if (!entry) return reply.code(404).send({ error: 'Invoice not found' });
+
+        const token = fastify.jwt.sign(
+            { type: PDF_TOKEN_TYPE, id: request.params.id },
+            { expiresIn: '2m' }
+        );
+        return {
+            url: `/api/plugins/invoice/invoices/${encodeURIComponent(request.params.id)}/pdf?token=${encodeURIComponent(token)}`,
+            filename: `${toRecord(entry).number || 'invoice'}.pdf`
+        };
+    });
+
+    fastify.get('/invoices/:id/pdf', async (request, reply) => {
+        const token = request.query?.token;
+        if (!token) return reply.code(401).send({ error: 'A download token is required' });
+
+        let claims;
+        try {
+            claims = fastify.jwt.verify(String(token));
+        } catch {
+            return reply.code(401).send({ error: 'That download link has expired' });
+        }
+        // A token minted for one invoice must not fetch another, and an ordinary
+        // access token must not be usable here.
+        if (claims.type !== PDF_TOKEN_TYPE || claims.id !== request.params.id) {
+            return reply.code(403).send({ error: 'Forbidden' });
+        }
+
+        const html = await buildPrintHtml(request.params.id, false);
+        if (html === null) return reply.code(404).send({ error: 'Invoice not found' });
+
+        const entry = await getEntry(INVOICES_SLUG, request.params.id);
+        const number = toRecord(entry).number || 'invoice';
+
+        let pdf;
+        try {
+            pdf = await renderPdf(html, { base: `${request.protocol}://${request.hostname}/` });
+        } catch (err) {
+            request.log.error({ err }, '[invoice] PDF render failed');
+            return reply.code(500).send({ error: `Could not render the PDF: ${err.message}` });
+        }
+
+        return reply
+            .type('application/pdf')
+            .header('Content-Disposition', `attachment; filename="${number.replace(/[^\w.-]/g, '_')}.pdf"`)
+            .header('Cache-Control', 'no-store')
+            .send(pdf);
+    });
+
+    // ---- Bulk PDF --------------------------------------------------------
+    //
+    // The list's CSV and Excel buttons export the rows; this exports the
+    // INVOICES - every one currently shown, as the documents a client would
+    // receive, one per page of a single file.
+    //
+    // A cap, because this is the one button here that can ask a machine for
+    // real work: Chrome lays out every sheet before a single byte comes back,
+    // and a careless "select everything" on a site with four years of history
+    // would otherwise hold a request open for minutes.
+    const BATCH_MAX = 100;
+
+    const BATCH_TOKEN_TYPE = 'invoice-pdf-batch';
+
+    /**
+     * Which invoices a batch token stands for.
+     *
+     * The ids do NOT travel in the token. A hundred uuids is four kilobytes of
+     * JWT and the token goes in a query string, which is the one place a long
+     * value is most likely to be truncated by something in the middle. The
+     * token carries a claim ticket instead and the list stays here.
+     *
+     * One-shot and short-lived, so this never grows: the entry is deleted when
+     * it is redeemed, and a sweep on write clears anything a cancelled
+     * download left behind.
+     *
+     * @type {Map<string, {ids: string[], expires: number}>}
+     */
+    const batchJobs = new Map();
+
+    /**
+     * @param   {string[]} ids
+     * @returns {string} the claim ticket
+     */
+    function stashBatch(ids) {
+        const now = Date.now();
+        for (const [key, job] of batchJobs) {
+            if (job.expires <= now) batchJobs.delete(key);
+        }
+        const ticket = randomUUID();
+        batchJobs.set(ticket, { ids, expires: now + 2 * 60 * 1000 });
+        return ticket;
+    }
+
+    /**
+     * Build one document holding every invoice asked for, in the order asked.
+     *
+     * Invoices that have been deleted since the list was drawn are skipped
+     * rather than failing the batch - the alternative is a download that dies
+     * because of a row somebody else removed a minute ago.
+     *
+     * @param   {string[]} ids
+     * @returns {Promise<{html: string|null, count: number}>}
+     */
+    async function buildBatchHtml(ids) {
+        const docs = [];
+        for (const id of ids) {
+            const html = await buildPrintHtml(id, false);
+            if (html !== null) docs.push(html);
+        }
+        if (!docs.length) return { html: null, count: 0 };
+        return { html: mergePrintDocs(docs, `Invoices (${docs.length})`), count: docs.length };
+    }
+
+    fastify.post('/invoices/batch-pdf-link', adminGuard, async (request, reply) => {
+        const cap = await pdfCapability();
+        if (!cap.available) return reply.code(501).send({ error: cap.reason });
+
+        const ids = Array.isArray(request.body?.ids)
+            ? request.body.ids.map(String).filter(Boolean)
+            : [];
+        if (!ids.length) return reply.code(400).send({ error: 'No invoices were selected.' });
+        if (ids.length > BATCH_MAX) {
+            return reply.code(400).send({
+                error: `That is ${ids.length} invoices. Narrow the filters to ${BATCH_MAX} or fewer and try again.`
+            });
+        }
+
+        const token = fastify.jwt.sign(
+            { type: BATCH_TOKEN_TYPE, ticket: stashBatch(ids) },
+            { expiresIn: '2m' }
+        );
+        return {
+            url: `/api/plugins/invoice/invoices/batch-pdf?token=${encodeURIComponent(token)}`,
+            filename: `invoices-${new Date().toISOString().slice(0, 10)}.pdf`,
+            count: ids.length
+        };
+    });
+
+    fastify.get('/invoices/batch-pdf', async (request, reply) => {
+        const token = request.query?.token;
+        if (!token) return reply.code(401).send({ error: 'A download token is required' });
+
+        let claims;
+        try {
+            claims = fastify.jwt.verify(String(token));
+        } catch {
+            return reply.code(401).send({ error: 'That download link has expired' });
+        }
+        if (claims.type !== BATCH_TOKEN_TYPE || !claims.ticket) {
+            return reply.code(403).send({ error: 'Forbidden' });
+        }
+
+        // Redeemed once. A token that has already produced its file cannot be
+        // replayed out of a browser's history or a proxy log.
+        const job = batchJobs.get(claims.ticket);
+        batchJobs.delete(claims.ticket);
+        if (!job || job.expires <= Date.now()) {
+            return reply.code(401).send({ error: 'That download link has expired' });
+        }
+
+        const { html, count } = await buildBatchHtml(job.ids);
+        if (html === null) return reply.code(404).send({ error: 'None of those invoices could be found.' });
+
+        let pdf;
+        try {
+            // Chrome lays the whole document out before it emits anything, so
+            // the ceiling has to grow with the batch - the single-invoice
+            // default would time out somewhere around the twentieth sheet.
+            pdf = await renderPdf(html, {
+                base: `${request.protocol}://${request.hostname}/`,
+                timeoutMs: Math.min(180000, 30000 + count * 1500)
+            });
+        } catch (err) {
+            request.log.error({ err, count }, '[invoice] batch PDF render failed');
+            return reply.code(500).send({ error: `Could not render the PDF: ${err.message}` });
+        }
+
+        const name = `invoices-${new Date().toISOString().slice(0, 10)}.pdf`;
+        return reply
+            .type('application/pdf')
+            .header('Content-Disposition', `attachment; filename="${name}"`)
+            .header('Cache-Control', 'no-store')
+            .send(pdf);
+    });
+
+    // Same markup, JSON-wrapped, for the admin.
+    //
+    // `authenticate` is Bearer-only and a target="_blank" navigation sends no
+    // Authorization header, so an <a href> straight to /print always 401s. The
+    // admin fetches through the intercepted H client (which does attach the
+    // token) and writes the result into a window it opened synchronously on the
+    // click, which is also what keeps the popup blocker out of it.
+    fastify.get('/invoices/:id/print-html', adminGuard, async (request, reply) => {
+        const html = await buildPrintHtml(request.params.id, request.query.print === '1');
+        if (html === null) return reply.code(404).send({ error: 'Invoice not found' });
+        return { html };
+    });
 }