domma-cms 0.66.0 → 0.69.4

package/plugins/invoice/plugin.js

@@ -1,1456 +0,0 @@
-/**
- * Invoice Plugin - Server
- *
- * Endpoints (mounted at /api/plugins/invoice):
- *   GET    /issuers              admin   list issuers
- *   POST   /issuers              admin   create issuer
- *   PUT    /issuers/:id          admin   update issuer
- *   DELETE /issuers/:id          admin   delete issuer
- *
- *   GET    /receivers            admin   list receivers
- *   POST   /receivers            admin   create receiver
- *   PUT    /receivers/:id        admin   update receiver
- *   DELETE /receivers/:id        admin   delete receiver
- *
- *   GET    /invoices             admin   list invoices (with computed totals)
- *   GET    /invoices/:id         admin   single invoice with computed totals
- *   POST   /invoices             admin   create invoice (auto-numbers if number omitted)
- *   PUT    /invoices/:id         admin   update invoice
- *   DELETE /invoices/:id         admin   delete invoice
- *   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 {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 ISSUERS_SLUG   = 'invoice-issuers';
-const RECEIVERS_SLUG = 'invoice-receivers';
-const INVOICES_SLUG  = 'invoices';
-
-function escapeHtml(str) {
-    return String(str ?? '')
-        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
-}
-
-function flattenList(result) {
-    const arr = Array.isArray(result) ? result : (result?.entries || []);
-    return arr.map((e) => ({ id: e.id, ...(e.data ?? e) }));
-}
-
-function toRecord(entry) {
-    return { id: entry.id, ...(entry.data ?? entry) };
-}
-
-function round2(n) {
-    return Math.round((Number(n) + Number.EPSILON) * 100) / 100;
-}
-
-function computeTotals(invoice) {
-    const items = Array.isArray(invoice.lineItems) ? invoice.lineItems : [];
-    let subtotal = 0;
-    for (const li of items) {
-        const qty   = Number(li.quantity) || 0;
-        const price = Number(li.unitPrice) || 0;
-        subtotal += qty * price;
-    }
-    subtotal = round2(subtotal);
-    const vatRate = invoice.vatEnabled ? (Number(invoice.vatRate) || 0) : 0;
-    const vat = round2(subtotal * (vatRate / 100));
-    const total = round2(subtotal + vat);
-    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), overdue: isOverdue(invoice) };
-}
-
-function formatMoney(amount, currency = 'GBP') {
-    try {
-        return new Intl.NumberFormat('en-GB', { style: 'currency', currency }).format(Number(amount) || 0);
-    } catch {
-        return `${currency} ${Number(amount).toFixed(2)}`;
-    }
-}
-
-/**
- * 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' });
-}
-
-/**
- * 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;
-    for (const inv of all) {
-        const m = re.exec(String(inv.number || ''));
-        if (m) {
-            const n = parseInt(m[1], 10);
-            if (n > max) max = n;
-        }
-    }
-    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')}`;
-}
-
-/** 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) {
-    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
-        const v = vars[key];
-        return v === undefined || v === null ? '' : String(v);
-    });
-}
-
-
-/**
- * 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;
-
-    /**
-     * 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
-    fastify.get('/issuers', adminGuard, async () => {
-        return flattenList(await listEntries(ISSUERS_SLUG, { limit: 1000 }));
-    });
-
-    fastify.post('/issuers', adminGuard, async (request, reply) => {
-        const body = request.body ?? {};
-        if (!body.name || typeof body.name !== 'string' || !body.name.trim()) {
-            return reply.code(400).send({ error: 'name is required' });
-        }
-        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 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 withWriteLock(() => deleteEntry(ISSUERS_SLUG, request.params.id));
-        return { ok: true };
-    });
-
-    // Receivers
-    fastify.get('/receivers', adminGuard, async () => {
-        return flattenList(await listEntries(RECEIVERS_SLUG, { limit: 1000 }));
-    });
-
-    fastify.post('/receivers', adminGuard, async (request, reply) => {
-        const body = request.body ?? {};
-        if (!body.name || typeof body.name !== 'string' || !body.name.trim()) {
-            return reply.code(400).send({ error: 'name is required' });
-        }
-        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 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 withWriteLock(() => deleteEntry(RECEIVERS_SLUG, request.params.id));
-        return { ok: true };
-    });
-
-    // Invoices
-    fastify.get('/invoices', adminGuard, async () => {
-        const list = flattenList(await listEntries(INVOICES_SLUG, { limit: 100000, sort: 'createdAt', order: 'desc' }));
-        return list.map(withTotals);
-    });
-
-    fastify.get('/invoices/:id', adminGuard, async (request, reply) => {
-        const entry = await getEntry(INVOICES_SLUG, request.params.id);
-        if (!entry) return reply.code(404).send({ error: 'Invoice not found' });
-        return withTotals(toRecord(entry));
-    });
-
-    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 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' });
-        });
-
-        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 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 withWriteLock(() => deleteEntry(INVOICES_SLUG, request.params.id));
-        return { ok: true };
-    });
-
-    /**
-     * 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([
-            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 currency = invoice.currency || settings.defaultCurrency;
-        const itemsHtml = (invoice.lineItems || []).map((li) => {
-            const qty   = Number(li.quantity) || 0;
-            const price = Number(li.unitPrice) || 0;
-            const lineTotal = round2(qty * price);
-            return `<tr>
-  <td>${escapeHtml(li.description || '')}</td>
-  <td class="num">${qty}</td>
-  <td class="num">${formatMoney(price, currency)}</td>
-  <td class="num">${formatMoney(lineTotal, currency)}</td>
-</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 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 || ''),
-            // 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 || ''),
-            issuerVat:     issuer.vatNumber ? `<div>VAT: ${escapeHtml(issuer.vatNumber)}</div>` : '',
-            receiverName:    escapeHtml(receiver.company || receiver.name || ''),
-            receiverAddress: escapeHtml(receiver.address || '').replace(/\n/g, '<br>'),
-            receiverEmail:   escapeHtml(receiver.email || ''),
-            receiverVat:     receiver.vatNumber ? `<div>VAT: ${escapeHtml(receiver.vatNumber)}</div>` : '',
-            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:   buildPaymentBlock(issuer),
-            footerNote:    escapeHtml(settings.footerNote || ''),
-            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 };
-    });
-}