domma-cms 0.55.1 → 0.66.0

package/plugins/invoice/collections/invoice-issuers/schema.json

@@ -1,16 +1,82 @@
 {
-  "name": "invoice-issuers",
-  "label": "Invoice Issuers",
   "slug": "invoice-issuers",
-  "storage": { "adapter": "file" },
+  "title": "Invoice Issuers",
+  "description": "Businesses that issue invoices, managed by the Invoice plugin.",
+  "plugin": "invoice",
+  "storage": {
+    "adapter": "file"
+  },
   "fields": [
-    { "key": "name",         "label": "Trading Name",   "type": "text",     "required": true },
-    { "key": "email",        "label": "Email",          "type": "text" },
-    { "key": "phone",        "label": "Phone",          "type": "text" },
-    { "key": "website",      "label": "Website",        "type": "text" },
-    { "key": "address",      "label": "Address",        "type": "textarea" },
-    { "key": "vatNumber",    "label": "VAT Number",     "type": "text" },
-    { "key": "bankDetails",  "label": "Bank Details",   "type": "textarea" },
-    { "key": "logoUrl",      "label": "Logo URL",       "type": "text" }
+    {
+      "name": "name",
+      "label": "Trading Name",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "email",
+      "label": "Email",
+      "type": "text"
+    },
+    {
+      "name": "phone",
+      "label": "Phone",
+      "type": "text"
+    },
+    {
+      "name": "website",
+      "label": "Website",
+      "type": "text"
+    },
+    {
+      "name": "address",
+      "label": "Address",
+      "type": "textarea"
+    },
+    {
+      "name": "vatNumber",
+      "label": "VAT Number",
+      "type": "text"
+    },
+    {
+      "name": "accountName",
+      "label": "Account Name",
+      "type": "text"
+    },
+    {
+      "name": "bankName",
+      "label": "Bank",
+      "type": "text"
+    },
+    {
+      "name": "sortCode",
+      "label": "Sort Code",
+      "type": "text"
+    },
+    {
+      "name": "accountNumber",
+      "label": "Account Number",
+      "type": "text"
+    },
+    {
+      "name": "iban",
+      "label": "IBAN",
+      "type": "text"
+    },
+    {
+      "name": "bic",
+      "label": "BIC / SWIFT",
+      "type": "text"
+    },
+    {
+      "name": "bankDetails",
+      "label": "Other Payment Notes",
+      "type": "textarea"
+    },
+    {
+      "name": "logoUrl",
+      "label": "Logo URL",
+      "type": "text"
+    }
   ]
 }

package/plugins/invoice/collections/invoice-receivers/schema.json

@@ -1,15 +1,16 @@
 {
-  "name": "invoice-receivers",
-  "label": "Invoice Receivers",
   "slug": "invoice-receivers",
+  "title": "Invoice Receivers",
+  "description": "Clients invoices are billed to, managed by the Invoice plugin.",
+  "plugin": "invoice",
   "storage": { "adapter": "file" },
   "fields": [
-    { "key": "name",      "label": "Name",       "type": "text",     "required": true },
-    { "key": "company",   "label": "Company",    "type": "text" },
-    { "key": "email",     "label": "Email",      "type": "text" },
-    { "key": "phone",     "label": "Phone",      "type": "text" },
-    { "key": "address",   "label": "Address",    "type": "textarea" },
-    { "key": "vatNumber", "label": "VAT Number", "type": "text" },
-    { "key": "reference", "label": "Reference",  "type": "text" }
+    { "name": "name",      "label": "Name",       "type": "text",     "required": true },
+    { "name": "company",   "label": "Company",    "type": "text" },
+    { "name": "email",     "label": "Email",      "type": "text" },
+    { "name": "phone",     "label": "Phone",      "type": "text" },
+    { "name": "address",   "label": "Address",    "type": "textarea" },
+    { "name": "vatNumber", "label": "VAT Number", "type": "text" },
+    { "name": "reference", "label": "Reference",  "type": "text" }
   ]
 }

package/plugins/invoice/collections/invoices/schema.json

@@ -1,15 +1,16 @@
 {
-  "name": "invoices",
-  "label": "Invoices",
   "slug": "invoices",
+  "title": "Invoices",
+  "description": "Invoices managed by the Invoice plugin.",
+  "plugin": "invoice",
   "storage": { "adapter": "file" },
   "fields": [
-    { "key": "number",      "label": "Number",       "type": "text", "required": true },
-    { "key": "issuerId",    "label": "Issuer",       "type": "text", "required": true },
-    { "key": "receiverId",  "label": "Receiver",     "type": "text", "required": true },
-    { "key": "issueDate",   "label": "Issue Date",   "type": "date", "required": true },
-    { "key": "dueDate",     "label": "Due Date",     "type": "date" },
-    { "key": "status",      "label": "Status",       "type": "select", "required": true,
+    { "name": "number",      "label": "Number",       "type": "text", "required": true },
+    { "name": "issuerId",    "label": "Issuer",       "type": "text", "required": true },
+    { "name": "receiverId",  "label": "Receiver",     "type": "text", "required": true },
+    { "name": "issueDate",   "label": "Issue Date",   "type": "date", "required": true },
+    { "name": "dueDate",     "label": "Due Date",     "type": "date" },
+    { "name": "status",      "label": "Status",       "type": "select", "required": true,
       "options": [
         { "value": "draft",     "label": "Draft" },
         { "value": "sent",      "label": "Sent" },
@@ -18,10 +19,15 @@
         { "value": "cancelled", "label": "Cancelled" }
       ]
     },
-    { "key": "currency",    "label": "Currency",     "type": "text" },
-    { "key": "vatEnabled",  "label": "VAT Enabled",  "type": "boolean" },
-    { "key": "vatRate",     "label": "VAT Rate %",   "type": "number" },
-    { "key": "lineItems",   "label": "Line Items",   "type": "json" },
-    { "key": "notes",       "label": "Notes",        "type": "textarea" }
+    { "name": "currency",    "label": "Currency",     "type": "text" },
+    { "name": "vatEnabled",  "label": "VAT Enabled",  "type": "boolean" },
+    { "name": "vatRate",     "label": "VAT Rate %",   "type": "number" },
+    { "name": "lineItems",   "label": "Line Items",   "type": "json" },
+    { "name": "notes",       "label": "Notes",        "type": "textarea" },
+    { "name": "sentAt",      "label": "Last Sent",    "type": "datetime" },
+    { "name": "sentTo",      "label": "Sent To",      "type": "text" },
+    { "name": "sendCount",   "label": "Times Sent",   "type": "number" },
+    { "name": "payments",    "label": "Payments",     "type": "json" },
+    { "name": "archived",    "label": "Archived",     "type": "boolean" }
   ]
 }

package/plugins/invoice/config.js

@@ -1,16 +1,37 @@
 /**
  * Invoice Plugin - Default Configuration
  *
- * numberPrefix    used in generated invoice numbers (e.g. INV-2026-0001)
- * numberPadding   minimum digits for the sequential portion
- * defaultVatRate  applied when VAT is enabled and no rate is set on the invoice
- * defaultCurrency ISO 4217 code; controls formatting + symbol
- * footerNote      optional small print appended to every printed invoice
+ * Everything here is editable at runtime from the cog in the plugin's banner
+ * (Settings > Defaults / Numbering / Email / Branding), which writes to
+ * config/plugins.json under `invoice.settings`. These are the fallbacks for a
+ * key that has never been set.
+ *
+ * numberPrefix            used in generated invoice numbers (e.g. INV-2026-0001)
+ * numberPadding           minimum digits for the sequential portion
+ * defaultVatRate          applied when VAT is enabled and no rate is set on the invoice
+ * defaultCurrency         ISO 4217 code; controls formatting + symbol
+ * vatEnabledByDefault     whether a new invoice starts with VAT switched on
+ * defaultPaymentTermsDays fills a new invoice's due date; 0 = leave it blank
+ * defaultIssuerId         the issuer a new invoice opens with; '' = none
+ * logoUrl                 house logo, used for any issuer without one of its own
+ * template                print layout: classic | modern | minimal (Settings > Templates)
+ * footerNote              optional small print appended to every printed invoice
+ * emailSubject            subject line; {{number}} {{issuer}} {{total}} {{dueDate}}
+ * emailIntro              the covering note above the invoice summary; same placeholders
+ * attachPdf               attach a rendered PDF when the host can make one
  */
 export default {
     numberPrefix: 'INV',
     numberPadding: 4,
     defaultVatRate: 20,
     defaultCurrency: 'GBP',
-    footerNote: 'Thank you for your business.'
+    vatEnabledByDefault: true,
+    defaultPaymentTermsDays: 30,
+    defaultIssuerId: '',
+    logoUrl: '',
+    template: 'classic',
+    footerNote: 'Thank you for your business.',
+    emailSubject: 'Invoice {{number}} from {{issuer}}',
+    emailIntro: 'Please find invoice {{number}} attached, for {{total}}.',
+    attachPdf: true
 };

package/plugins/invoice/pdf.js

@@ -0,0 +1,164 @@
+/**
+ * Invoice Plugin - server-side PDF.
+ *
+ * The printable HTML already exists and is the thing customers see, so the PDF
+ * is that same page rendered by a real browser rather than a second layout
+ * maintained in a drawing library. Chrome is the only renderer that agrees with
+ * what the Print button shows.
+ *
+ * `puppeteer-core` is an OPTIONAL dependency, the way `mongodb` is: it is pure
+ * JavaScript and installs anywhere, but it does not bring a browser with it -
+ * that is the whole point of -core. A host with no Chrome keeps working and the
+ * admin simply does not offer the button, rather than the install growing a
+ * few hundred megabytes for a feature many sites never use.
+ *
+ * The browser is launched per request and closed in a finally. A warm instance
+ * would save roughly a second, at the cost of a permanently resident Chrome on
+ * every site in a fleet - the wrong trade for a button pressed a few times a day.
+ */
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CMS_ROOT = path.resolve(__dirname, '..', '..');
+
+/** Where a Chrome might be, most specific first. CHROME_BIN wins. */
+const CHROME_CANDIDATES = [
+    process.env.CHROME_BIN,
+    process.env.PUPPETEER_EXECUTABLE_PATH,
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium'
+].filter(Boolean);
+
+/**
+ * Chrome installs puppeteer downloads for itself, newest first. puppeteer-core
+ * does not download one, but a host that also has `puppeteer` (or ran
+ * `npx puppeteer browsers install`) has one sitting here.
+ *
+ * @returns {string[]}
+ */
+function cachedChromes() {
+    const roots = [
+        process.env.PUPPETEER_CACHE_DIR,
+        path.join(process.env.HOME || '', '.cache', 'puppeteer')
+    ].filter(Boolean);
+
+    const found = [];
+    for (const root of roots) {
+        for (const kind of ['chrome', 'chrome-headless-shell']) {
+            const dir = path.join(root, kind);
+            let builds;
+            try {
+                builds = fs.readdirSync(dir).sort().reverse();
+            } catch {
+                continue;
+            }
+            for (const build of builds) {
+                for (const rel of [
+                    ['chrome-linux64', 'chrome'],
+                    ['chrome-headless-shell-linux64', 'chrome-headless-shell']
+                ]) {
+                    const bin = path.join(dir, build, ...rel);
+                    if (fs.existsSync(bin)) found.push(bin);
+                }
+            }
+        }
+    }
+    return found;
+}
+
+let cached = null;
+
+/**
+ * Can this host render a PDF, and if not, why not?
+ *
+ * Cached after the first call - the answer cannot change without a restart, and
+ * the admin asks on every editor mount.
+ *
+ * @param {boolean} [refresh]
+ * @returns {Promise<{available: boolean, chrome: string|null, reason: string|null}>}
+ */
+export async function pdfCapability(refresh = false) {
+    if (cached && !refresh) return cached;
+
+    let puppeteer = null;
+    try {
+        puppeteer = await import('puppeteer-core');
+    } catch {
+        cached = {
+            available: false,
+            chrome: null,
+            reason: 'puppeteer-core is not installed. It is an optional dependency: npm install puppeteer-core'
+        };
+        return cached;
+    }
+
+    const chrome = [...CHROME_CANDIDATES, ...cachedChromes()].find(p => {
+        try { return fs.existsSync(p); } catch { return false; }
+    });
+
+    cached = chrome
+        ? { available: true, chrome, reason: null, _puppeteer: puppeteer }
+        : {
+            available: false,
+            chrome: null,
+            reason: 'No Chrome executable found. Install one and set CHROME_BIN, or run: npx puppeteer browsers install chrome'
+        };
+    return cached;
+}
+
+/**
+ * Render a full HTML document to an A4 PDF.
+ *
+ * The HTML is set directly rather than served, so the print template's relative
+ * URLs would not resolve - `base` gives them something to resolve against, and
+ * `waitUntil: 'networkidle0'` is what makes a remote logo actually appear
+ * instead of racing the screenshot.
+ *
+ * @param {string} html
+ * @param {object} [opts]
+ * @param {string} [opts.base]      absolute URL for relative assets
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<Buffer>}
+ * @throws {Error} when no renderer is available
+ */
+export async function renderPdf(html, { base = null, timeoutMs = 30000 } = {}) {
+    const cap = await pdfCapability();
+    if (!cap.available) throw new Error(cap.reason);
+
+    const puppeteer = cap._puppeteer ?? await import('puppeteer-core');
+    const launch = puppeteer.default?.launch ?? puppeteer.launch;
+
+    const browser = await launch.call(puppeteer.default ?? puppeteer, {
+        executablePath: cap.chrome,
+        headless: true,
+        // No usable sandbox in a typical container or on a bare VPS, and the
+        // error when it is missing does not name it.
+        args: ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu']
+    });
+
+    try {
+        const page = await browser.newPage();
+        page.setDefaultTimeout(timeoutMs);
+        const doc = base && !/<base\s/i.test(html)
+            ? html.replace(/<head([^>]*)>/i, `<head$1><base href="${base}">`)
+            : html;
+        await page.setContent(doc, { waitUntil: 'networkidle0', timeout: timeoutMs });
+        // The template already carries @page/@media print rules.
+        await page.emulateMediaType('print');
+        return await page.pdf({
+            format: 'A4',
+            printBackground: true,
+            preferCSSPageSize: true,
+            margin: { top: '0mm', right: '0mm', bottom: '0mm', left: '0mm' }
+        });
+    } finally {
+        await browser.close().catch(() => {});
+    }
+}
+
+export { CMS_ROOT };