domma-cms 0.54.2 → 0.66.0

package/plugins/invoice/admin/views/payments.js

@@ -0,0 +1,127 @@
+/**
+ * Invoice plugin - recording a payment.
+ *
+ * The ledger has its own routes rather than riding on PUT, which is what keeps
+ * the stored status reconciled with what has actually been paid; this dialog is
+ * the admin's way in. Same shape as the Send dialog: F.create for the form,
+ * light-DOM projection into the slideover, and the panel detached on close.
+ */
+const BASE = '/api/plugins/invoice';
+
+export const PAYMENT_METHODS = {
+    'bank-transfer': 'Bank transfer',
+    'card':          'Card',
+    'cash':          'Cash',
+    'cheque':        'Cheque',
+    'direct-debit':  'Direct debit',
+    'other':         'Other'
+};
+
+/**
+ * @param {string}   id        invoice id
+ * @param {number}   balance   what is still outstanding, prefilled as the amount
+ * @param {Function} [onSaved] called with the updated invoice
+ * @returns {void}
+ */
+export function openPaymentDialog(id, balance, onSaved) {
+    const form = F.create({
+        amount: {
+            type: 'number', label: 'Amount', required: true,
+            formConfig: { hint: 'Part payments are fine - the balance follows.' }
+        },
+        // Deliberately NO `type`.
+        //
+        // `type: 'date'` renders the right control and then makes the form
+        // impossible to submit: Forma maps it to <input type="date">, which
+        // writes a STRING back, while M.types.date accepts only a real Date
+        // instance - so validate() fails with "Expected type date" every time
+        // and the Record button silently does nothing. Declaring no type skips
+        // the type check entirely (models.js only checks when def.type is set),
+        // and the input is given its type below, after render.
+        date: { label: 'Date received', required: true },
+        method: {
+            type: 'select', label: 'Method',
+            options: Object.entries(PAYMENT_METHODS).map(([value, label]) => ({ value, label }))
+        },
+        reference: {
+            type: 'string', label: 'Reference',
+            formConfig: { placeholder: 'FT12345', hint: 'Whatever lets you find it on a statement.' }
+        }
+    }, {
+        amount: balance > 0 ? balance : '',
+        date: new Date().toISOString().slice(0, 10),
+        method: 'bank-transfer',
+        reference: ''
+    }, { showSubmitButton: false });
+
+    const wrapper = document.createElement('div');
+    wrapper.className = 'invoice-party-form';
+    const fields = document.createElement('div');
+    form.renderTo(fields);
+    // Domma's calendar, not `<input type="date">`: one control in every
+    // browser, and it writes ISO back through the input, which is what
+    // form.getData() reads. A payment cannot be received in the future.
+    const dateInput = fields.querySelector('[name="date"]');
+    const datePicker = dateInput && E.datePicker(dateInput, {
+        max: new Date().toISOString().slice(0, 10)
+    });
+    wrapper.appendChild(fields);
+
+    const actions = document.createElement('div');
+    actions.className = 'invoice-party-actions';
+    const cancelBtn = document.createElement('button');
+    cancelBtn.type = 'button';
+    cancelBtn.className = 'btn btn-ghost';
+    cancelBtn.textContent = 'Cancel';
+    const saveBtn = document.createElement('button');
+    saveBtn.type = 'button';
+    saveBtn.className = 'btn btn-primary';
+    saveBtn.textContent = 'Record payment';
+    actions.appendChild(cancelBtn);
+    actions.appendChild(saveBtn);
+    wrapper.appendChild(actions);
+
+    const slideover = E.slideover({
+        title: 'Record Payment',
+        size: 'md',
+        position: 'right',
+        onClose: () => setTimeout(() => {
+            datePicker?.destroy?.();
+            slideover.destroy();
+            slideover.element?.remove();
+        }, 350)
+    });
+    slideover.element.appendChild(wrapper);
+
+    cancelBtn.addEventListener('click', () => slideover.close());
+
+    saveBtn.addEventListener('click', async () => {
+        if (!form.validate()) return;
+        const values = form.getData();
+        if (!(Number(values.amount) > 0)) {
+            E.toast('The amount has to be more than zero.', { type: 'error' });
+            return;
+        }
+        saveBtn.disabled = true;
+        try {
+            const res = await H.post(`${BASE}/invoices/${id}/payments`, {
+                amount: Number(values.amount),
+                date: values.date,
+                method: values.method,
+                reference: values.reference
+            });
+            const out = res?.data ?? res;
+            if (out?.error) throw new Error(out.error);
+            slideover.close();
+            E.toast(out.totals?.balance <= 0 ? 'Payment recorded - this invoice is settled.' : 'Payment recorded.',
+                    { type: 'success' });
+            if (typeof onSaved === 'function') onSaved(out);
+        } catch (err) {
+            E.toast(err?.message ?? 'Could not record the payment.', { type: 'error' });
+            saveBtn.disabled = false;
+        }
+    });
+
+    slideover.open();
+    Domma.icons.scan(wrapper);
+}

package/plugins/invoice/admin/views/print.js

@@ -0,0 +1,130 @@
+/**
+ * Invoice plugin - opening the printable invoice.
+ *
+ * `authenticate` is Bearer-only (see server/middleware/auth.js), so a plain
+ * <a href target="_blank"> to /invoices/:id/print arrives with no Authorization
+ * header and comes back 401 every time. The markup is fetched through H, which
+ * the admin's http-interceptor tokenises, and written into a window opened
+ * SYNCHRONOUSLY on the click - a window opened after an await counts as
+ * unsolicited and the pop-up blocker eats it.
+ */
+const BASE = '/api/plugins/invoice';
+
+const PLACEHOLDER = '<!doctype html><html><head><title>Invoice</title></head>' +
+    '<body style="font:14px system-ui,sans-serif;padding:2rem;color:#555;">Preparing invoice…</body></html>';
+
+/**
+ * @param {string} id      invoice id
+ * @param {boolean} [auto] have the printout raise the print dialog itself
+ * @returns {Promise<void>}
+ */
+export async function openPrintWindow(id, auto = false) {
+    const win = window.open('', '_blank');
+    if (!win) {
+        E.toast('Allow pop-ups for this site to print an invoice.', { type: 'error' });
+        return;
+    }
+    win.document.write(PLACEHOLDER);
+
+    try {
+        const res = await H.get(`${BASE}/invoices/${id}/print-html${auto ? '?print=1' : ''}`);
+        const html = (res?.data ?? res)?.html;
+        if (!html) throw new Error('The server returned an empty invoice.');
+        win.document.open();
+        win.document.write(html);
+        win.document.close();
+    } catch (err) {
+        win.close();
+        E.toast(err?.message ?? 'Could not open the printout.', { type: 'error' });
+    }
+}
+
+/**
+ * Does this host have a renderer? Asked once and remembered - the answer cannot
+ * change without a server restart, and both views ask on every mount.
+ *
+ * @returns {Promise<boolean>}
+ */
+let pdfAvailable = null;
+
+export async function canDownloadPdf() {
+    if (pdfAvailable !== null) return pdfAvailable;
+    try {
+        const res = await H.get(`${BASE}/pdf/status`);
+        pdfAvailable = Boolean((res?.data ?? res)?.available);
+    } catch {
+        pdfAvailable = false;
+    }
+    return pdfAvailable;
+}
+
+/**
+ * Download the server-rendered PDF.
+ *
+ * A download is a NAVIGATION, so it cannot carry the admin's bearer token - the
+ * same reason the Print button could not link straight at /print. The server
+ * mints a two-minute token bound to this one invoice and puts it in the query
+ * string, and an <a download> click is what turns that URL into a file without
+ * taking the SPA off its route.
+ *
+ * @param {string} id
+ * @returns {Promise<void>}
+ */
+export async function downloadPdf(id) {
+    try {
+        const res = await H.post(`${BASE}/invoices/${id}/pdf-link`, {});
+        const link = res?.data ?? res;
+        if (!link?.url) throw new Error(link?.error || 'No download link was returned.');
+
+        const a = document.createElement('a');
+        a.href = link.url;
+        a.download = link.filename || 'invoice.pdf';
+        a.rel = 'noopener';
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        E.toast('Preparing your PDF…', { type: 'info' });
+    } catch (err) {
+        E.toast(err?.message ?? 'Could not build the PDF.', { type: 'error' });
+    }
+}
+
+/**
+ * Download one PDF holding every invoice given, a page each.
+ *
+ * Same two-minute token dance as the single download, for the same reason - a
+ * download is a navigation and carries no bearer token. The ids are POSTed
+ * rather than put in the query string: the server keeps the list and the URL
+ * carries only a claim ticket, so the link stays short whether it is three
+ * invoices or a hundred.
+ *
+ * The toast is not decoration. Chrome lays out every sheet before the first
+ * byte arrives, so a large batch is several seconds during which an <a> click
+ * looks exactly like a button that did nothing.
+ *
+ * @param {string[]} ids
+ * @returns {Promise<void>}
+ */
+export async function downloadPdfBatch(ids) {
+    if (!ids.length) {
+        E.toast('There are no invoices to export.', { type: 'info' });
+        return;
+    }
+
+    try {
+        E.toast(`Building a PDF of ${ids.length} invoice${ids.length === 1 ? '' : 's'}…`, { type: 'info' });
+        const res = await H.post(`${BASE}/invoices/batch-pdf-link`, { ids });
+        const link = res?.data ?? res;
+        if (!link?.url) throw new Error(link?.error || 'No download link was returned.');
+
+        const a = document.createElement('a');
+        a.href = link.url;
+        a.download = link.filename || 'invoices.pdf';
+        a.rel = 'noopener';
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+    } catch (err) {
+        E.toast(err?.message ?? 'Could not build the PDF.', { type: 'error' });
+    }
+}

package/plugins/invoice/admin/views/receivers.js

@@ -1,22 +1,55 @@
 /**
- * Invoice plugin - receivers CRUD view.
+ * Invoice plugin - receivers screen.
+ *
+ * The same panel the settings slideover puts in its Receivers tab, plus the
+ * Contacts import - a receiver is a contact's billing side, and Contacts
+ * already holds the company name, the billing address and the VAT number.
  */
-import {mountPartyView} from './party-view.js?v=1';
+import {RECEIVER_FIELDS, mountPartyPanel} from './party-view.js?v=8';
+import {billingProfile, contactsAvailable, openContactPicker} from './contacts-source.js?v=8';
+import {disposeOnLeave} from './view-lifecycle.js?v=8';
 
 export const receiversView = {
     templateUrl: '/plugins/invoice/admin/templates/receivers.html',
-    onMount: ($container) => mountPartyView($container, {
-        kind: 'receiver',
-        endpoint: '/api/plugins/invoice/receivers',
-        label: 'Receiver',
-        fields: [
-            { key: 'name',      label: 'Contact Name',  required: true,  type: 'text' },
-            { key: 'company',   label: 'Company',       type: 'text' },
-            { key: 'email',     label: 'Email',         type: 'text' },
-            { key: 'phone',     label: 'Phone',         type: 'text' },
-            { key: 'vatNumber', label: 'VAT Number',    type: 'text' },
-            { key: 'reference', label: 'Reference',     type: 'text' },
-            { key: 'address',   label: 'Address',       type: 'textarea' }
-        ]
-    })
+
+    async onMount($container) {
+        const host = $container.find('#party-host').get(0);
+        if (!host) return;
+
+        const panel = mountPartyPanel(host, {
+            kind: 'receiver',
+            endpoint: '/api/plugins/invoice/receivers',
+            label: 'Receiver',
+            fields: RECEIVER_FIELDS
+        });
+
+        disposeOnLeave(host, panel.dispose);
+
+        if (await contactsAvailable()) {
+            const importBtn = document.createElement('button');
+            importBtn.type = 'button';
+            importBtn.className = 'btn btn-sm btn-outline';
+            importBtn.textContent = 'Import from Contacts';
+            importBtn.addEventListener('click', () => openContactPicker({
+                title: 'Import a receiver',
+                onPick: async (contact) => {
+                    try {
+                        // The billing profile uses the receiver's own field
+                        // names, which is the point of that endpoint - it goes
+                        // straight to POST /receivers with nothing to translate.
+                        const profile = await billingProfile(contact.id);
+                        const res = await H.post('/api/plugins/invoice/receivers', profile);
+                        if (res?.error) throw new Error(res.error);
+                        E.toast(`${profile.company || profile.name} imported.`, { type: 'success' });
+                        await panel.reload();
+                    } catch (err) {
+                        E.toast(err?.message ?? 'Could not import that contact.', { type: 'error' });
+                    }
+                }
+            }));
+            host.querySelector('.invoice-panel-head')?.prepend(importBtn);
+        }
+
+        Domma.icons.scan($container.get(0));
+    }
 };

package/plugins/invoice/admin/views/send.js

@@ -0,0 +1,212 @@
+/**
+ * Invoice plugin - the Send dialog.
+ *
+ * The defaults (recipient, subject, covering note, whether a PDF can be
+ * attached) come from the server rather than being templated here, so the
+ * settings that shape the email have one reader.
+ *
+ * Recipients can also come from Contacts - one contact, or everybody in a
+ * group. They are appended to the To field as text rather than held in a
+ * parallel list, because the field has to stay typeable: half the time the
+ * address someone wants is an accounts inbox that is in nobody's contacts.
+ *
+ * The form is F.create - schema first, then .renderTo() - and the panel is
+ * projected into the slideover's light DOM, because setContent() sanitises and
+ * would strip the inputs.
+ */
+import {addressesFor, contactsAvailable, openContactPicker} from './contacts-source.js?v=8';
+
+const BASE = '/api/plugins/invoice';
+
+/**
+ * Merge new addresses into a comma-separated To field, without duplicates.
+ *
+ * @param   {string} current
+ * @param   {string[]} extra
+ * @returns {string}
+ */
+export function mergeRecipients(current, extra) {
+    const seen = new Set();
+    const out = [];
+    for (const item of [...String(current ?? '').split(/[,;]/), ...extra]) {
+        const address = String(item ?? '').trim();
+        if (!address || seen.has(address.toLowerCase())) continue;
+        seen.add(address.toLowerCase());
+        out.push(address);
+    }
+    return out.join(', ');
+}
+
+/**
+ * @param {string}   id        invoice id
+ * @param {Function} [onSent]  called with the updated invoice
+ * @returns {Promise<void>}
+ */
+export async function openSendDialog(id, onSent) {
+    let defaults;
+    try {
+        const res = await H.get(`${BASE}/invoices/${id}/send-defaults`);
+        defaults = res?.data ?? res;
+        if (defaults?.error) throw new Error(defaults.error);
+    } catch (err) {
+        E.toast(err?.message ?? 'Could not prepare the email.', { type: 'error' });
+        return;
+    }
+
+    const haveContacts = await contactsAvailable();
+
+    const schema = {
+        to:      { type: 'string', label: 'To', required: true,
+                   formConfig: { placeholder: 'name@example.com',
+                                 hint: defaults.to
+                                     ? 'Separate several addresses with commas.'
+                                     : 'This receiver has no email address on file.' } },
+        subject: { type: 'string', label: 'Subject', required: true },
+        message: { type: 'textarea', label: 'Covering note',
+                   formConfig: { rows: 3, hint: 'Sent above the invoice summary.' } }
+    };
+    if (defaults.canAttachPdf) {
+        schema.attachPdf = { type: 'boolean', label: 'Attach a PDF',
+                             formConfig: { hint: 'Without it the invoice is sent inline instead.' } };
+    }
+
+    const form = F.create(schema, {
+        to: defaults.to || '',
+        subject: defaults.subject || '',
+        message: defaults.message || '',
+        attachPdf: Boolean(defaults.attachPdf)
+    }, { showSubmitButton: false });
+
+    const wrapper = document.createElement('div');
+    wrapper.className = 'invoice-party-form';
+
+    if (defaults.sendCount) {
+        const trail = document.createElement('p');
+        trail.className = 'text-muted text-sm mb-0';
+        const when = defaults.sentAt ? D(defaults.sentAt).format('DD MMM YYYY HH:mm') : 'previously';
+        trail.textContent = `Last sent ${when} (${defaults.sendCount} ${defaults.sendCount === 1 ? 'time' : 'times'}).`;
+        wrapper.appendChild(trail);
+    }
+
+    const fields = document.createElement('div');
+    form.renderTo(fields);
+    wrapper.appendChild(fields);
+
+    // Contacts, appended to whatever is already in To. The value goes back
+    // through the MODEL as well as the input: Forma reads getData() off the
+    // model, so an input written behind its back would send the old address.
+    if (haveContacts) {
+        const toInput = fields.querySelector('[name="to"]');
+        if (toInput) {
+            const row = document.createElement('div');
+            row.className = 'invoice-recipient-actions';
+
+            /**
+             * @param   {object[]} contacts
+             * @returns {void}
+             */
+            const add = (contacts) => {
+                const found = contacts.flatMap((c) => addressesFor(c).slice(0, 1));
+                const missing = contacts.filter((c) => addressesFor(c).length === 0);
+                if (!found.length) {
+                    E.toast('None of those contacts has an email address.', { type: 'error' });
+                    return;
+                }
+                const merged = mergeRecipients(form.getData().to, found);
+                form.setData({ to: merged });
+                toInput.value = merged;
+                if (missing.length) {
+                    E.toast(`${missing.length} contact(s) had no email address and were skipped.`,
+                            { type: 'warning' });
+                }
+            };
+
+            const one = document.createElement('button');
+            one.type = 'button';
+            one.className = 'btn btn-sm btn-outline';
+            one.textContent = 'Add a contact';
+            one.addEventListener('click', () => openContactPicker({
+                title: 'Add a recipient',
+                onPick: (contact) => add([contact])
+            }));
+            row.appendChild(one);
+
+            const many = document.createElement('button');
+            many.type = 'button';
+            many.className = 'btn btn-sm btn-outline';
+            many.textContent = 'Add a group';
+            many.title = 'Filter by group, then Select all shown';
+            many.addEventListener('click', () => openContactPicker({
+                title: 'Add recipients',
+                multiple: true,
+                onPick: (contacts) => add(contacts)
+            }));
+            row.appendChild(many);
+
+            // Under the field it belongs to, whatever Forma wrapped it in.
+            (toInput.closest('.domma-form-field') || toInput.parentElement || wrapper).appendChild(row);
+        }
+    }
+
+    const actions = document.createElement('div');
+    actions.className = 'invoice-party-actions';
+    const cancelBtn = document.createElement('button');
+    cancelBtn.type = 'button';
+    cancelBtn.className = 'btn btn-ghost';
+    cancelBtn.textContent = 'Cancel';
+    const sendBtn = document.createElement('button');
+    sendBtn.type = 'button';
+    sendBtn.className = 'btn btn-primary';
+    sendBtn.textContent = 'Send';
+    actions.appendChild(cancelBtn);
+    actions.appendChild(sendBtn);
+    wrapper.appendChild(actions);
+
+    const slideover = E.slideover({
+        title: 'Send Invoice',
+        size: 'md',
+        position: 'right',
+        onClose: () => setTimeout(() => {
+            slideover.destroy();
+            slideover.element?.remove();
+        }, 350)
+    });
+    slideover.element.appendChild(wrapper);
+
+    cancelBtn.addEventListener('click', () => slideover.close());
+
+    sendBtn.addEventListener('click', async () => {
+        if (!form.validate()) return;
+        const values = form.getData();
+
+        // Sending is slow (rendering the PDF is about a second) and it is not
+        // repeatable - say so, and make a second click impossible.
+        sendBtn.disabled = true;
+        cancelBtn.disabled = true;
+        const original = sendBtn.textContent;
+        sendBtn.textContent = 'Sending…';
+
+        try {
+            const res = await H.post(`${BASE}/invoices/${id}/send`, {
+                to: values.to,
+                subject: values.subject,
+                message: values.message,
+                attachPdf: Boolean(values.attachPdf)
+            });
+            const out = res?.data ?? res;
+            if (out?.error) throw new Error(out.error);
+            slideover.close();
+            E.toast(out.attached ? `Sent to ${out.to} with the PDF attached.` : `Sent to ${out.to}.`,
+                    { type: 'success' });
+            if (typeof onSent === 'function') onSent(out.invoice);
+        } catch (err) {
+            E.toast(err?.message ?? 'The invoice could not be sent.', { type: 'error' });
+            sendBtn.disabled = false;
+            cancelBtn.disabled = false;
+            sendBtn.textContent = original;
+        }
+    });
+
+    slideover.open();
+    Domma.icons.scan(wrapper);
+}