domma-cms 0.113.0 → 0.114.0

package/plugins/support/plugin.js

@@ -0,0 +1,350 @@
+/**
+ * Support - a customer asks Domma for help from their own admin, and the two
+ * talk it through. Mounted at /api/plugins/support.
+ *
+ * ONE plugin, TWO sides, chosen by where it runs:
+ *
+ *   site     (every site; it can SEND only when the manager started it - MANAGER_URL + FLEET_TOKEN)
+ *     GET  /mode                   which side, whether connected, and the contact card
+ *     GET  /meta · GET /count      categories etc.; sidebar badge: replies not yet read
+ *     GET  /tickets                this site's requests (sends any waiting first)
+ *     POST /tickets                a new request: kept here, then sent
+ *     POST /tickets/:ref/messages  write again
+ *     POST /tickets/:ref/close     mark resolved
+ *     PUT  /tickets/:ref/seen      Domma's latest reply has been read
+ *
+ *   manager  (Site Manager is installed beside it)
+ *     POST /fleet/tickets · POST /fleet/messages · GET /fleet/mine   from the sites (Bearer fleet token)
+ *     GET  /mode · /meta · /count  the badge counts requests waiting on Domma, red while one is urgent
+ *     GET  /tickets · GET /tickets/:id
+ *     POST /tickets/:id/reply      answer (and set the status), emailing the customer
+ *     PUT  /tickets/:id            status, priority, internal notes
+ *     DELETE /tickets/:id
+ *
+ * A standalone site (not started by a manager) still gets the contact card -
+ * Support is for everyone - but has nowhere to send a conversation.
+ *
+ * Nothing the browser sends says who wrote or which site it came from: the user
+ * is the session's, the site is the one the fleet token names.
+ */
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import defaults from './config.js';
+import {
+    CATEGORIES, PRIORITIES, STATUSES, buildMessagePayload, buildTicketPayload, cleanMessage, cleanRequest, cleanUpdate,
+    contactCard, createThrottle, lastDommaAt, senderView, toCustomerEmail, toDommaEmail
+} from './lib/shape.js';
+import {createOutbox, flush, managerApi, managerOf, mergeTickets, newRef} from './lib/sender.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const NAME = 'support';
+
+/** The CMS this site runs, from the updater's marker (the site's package.json is the SITE's version). */
+function cmsVersion() {
+    for (const f of [path.join(process.cwd(), '.domma'), path.join(process.cwd(), '.cmsVersion')]) {
+        try {
+            const raw = fs.readFileSync(f, 'utf8');
+            try { return String(JSON.parse(raw).cmsVersion || ''); } catch { return raw.trim(); }
+        } catch { /* try the next */ }
+    }
+    try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).version || ''; } catch { return ''; }
+}
+
+export default async function supportPlugin(fastify, options) {
+    const {authenticate, requirePermission} = options.auth;
+    const hooks = options.hooks || {};
+    const can = (action) => ({preHandler: [authenticate, requirePermission(NAME, action)]});
+    const settings = {...defaults, ...(options.settings || {})};
+    const receiverMod = await import('./lib/receiver.js');
+    const mode = options.mode || (receiverMod.isManager() ? 'receiver' : 'sender');
+    const notify = typeof hooks.notify === 'function' ? (n) => { try { hooks.notify(n); } catch { /* a notice is a courtesy */ } } : () => {};
+    const mail = options.mail || await import('./lib/mail.js');
+    if (typeof hooks.registerNotificationSource === 'function') {
+        try {
+            if (mode === 'receiver') {
+                hooks.registerNotificationSource({id: 'new-request', label: 'A site asked for support',
+                    description: 'A customer opened a support request or wrote again.', severity: 'info', audience: 'admins'});
+            } else {
+                hooks.registerNotificationSource({id: 'reply', label: 'Domma Support replied',
+                    description: 'Domma answered one of this site\'s support requests.', severity: 'info', audience: 'admins'});
+            }
+        } catch (err) { fastify.log.warn(`[support] notification source: ${err.message}`); }
+    }
+
+    // On the manager the inbox needs it, so `manage` is enough there.
+    fastify.get('/meta', can(mode === 'receiver' ? 'manage' : 'send'), async () => ({categories: CATEGORIES, priorities: PRIORITIES, statuses: STATUSES}));
+
+    if (mode === 'receiver') await receiverRoutes(fastify, {can, notify, mail, receiverMod, settings, options});
+    else await senderRoutes(fastify, {can, notify, settings, options});
+}
+
+// ---------------------------------------------------------------------------------
+// Site
+// ---------------------------------------------------------------------------------
+
+async function senderRoutes(fastify, {can, notify, settings, options}) {
+    const env = options.env || process.env;
+    const manager = managerOf(env);
+    const outbox = createOutbox(options.dataDir || path.join(HERE, 'data'));
+    const api = manager ? managerApi(manager, options.fetch) : null;
+    // The manager's card wins once heard; until then (and standalone) this site's settings.
+    const contact = () => outbox.contact() || contactCard(settings);
+
+    let lastSync = 0;
+    /** Send what waits, then read the manager's view; tell admins about replies they have not heard of. */
+    async function sync() {
+        lastSync = Date.now();
+        const seen = outbox.seen();
+        if (!api) return {tickets: mergeTickets(outbox.all(), [], seen), reachable: false, error: ''};
+        const pushed = await flush(outbox, api);
+        const mine = await api.mine();
+        const remote = mine.ok ? (mine.body?.tickets || []) : null;
+        if (remote) {
+            const before = new Map(outbox.tickets().map(t => [t.ref, t.dommaAt]));
+            for (const t of remote) {
+                const at = lastDommaAt(t);
+                // A reply this site had not heard of before this sync: one notice each.
+                if (at && before.get(t.ref) !== at && seen[t.ref] !== at) {
+                    const last = [...t.messages].reverse().find(m => m.from === 'domma');
+                    notify({title: `Domma Support replied: ${t.subject}`, body: String(last?.body || '').slice(0, 300), severity: 'info',
+                        source: 'reply', link: `#/plugins/support/${t.ref}`, dedupeKey: `support-reply:${t.ref}:${at}`});
+                }
+            }
+            const card = mine.body?.contact ? contactCard(mine.body.contact) : null;
+            outbox.remember(remote, card);
+        }
+        const tickets = mergeTickets(outbox.all(), remote, seen, outbox.tickets());
+        return {tickets, reachable: Boolean(remote), error: mine.ok ? pushed.error : mine.error};
+    }
+
+    // Every few minutes: waiting messages go, new replies are noticed. Off in tests.
+    if (api && options.timer !== false) {
+        const t = setInterval(() => { sync().catch(() => {}); }, Math.max(1, Number(settings.syncMinutes) || 5) * 60_000);
+        t.unref?.();
+        const first = setTimeout(() => { sync().catch(() => {}); }, 30_000);
+        first.unref?.();
+        fastify.addHook('onClose', async () => { clearInterval(t); clearTimeout(first); });
+    }
+
+    fastify.get('/mode', can('send'), async () => ({mode: 'sender', connected: Boolean(manager), site: manager?.slug || '', contact: contact()}));
+
+    fastify.get('/count', can('send'), async () => {
+        // The badge reads the last sync's copy and never waits on the manager - but it is
+        // asked every minute, so it also nudges a sync in the background when the copy is
+        // over a minute old. A reply then shows within about a minute, not syncMinutes.
+        if (api && Date.now() - lastSync > 60_000) sync().catch(() => {});
+        const seen = outbox.seen();
+        // From the last sync's copy: the badge must not call the manager every minute.
+        const unread = outbox.tickets().filter(t => t.dommaAt && seen[t.ref] !== t.dommaAt);
+        const openCount = outbox.tickets().filter(t => t.status !== 'closed').length;
+        const waiting = outbox.all().filter(i => i.state === 'waiting').length;
+        const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+        if (unread.length) {
+            return {count: unread.length, label: `${unread.length} new ${unread.length === 1 ? 'reply' : 'replies'} from Domma Support`, tone: 'info',
+                details: {title: 'Support', items: unread.slice(0, 5).map(t => ({text: t.subject, meta: 'New reply'})), empty: ''}};
+        }
+        return {count: openCount, inventory: true, tone: 'info',
+            label: openCount ? `${plural(openCount, 'open request')}${waiting ? `, ${waiting} waiting to send` : ''}` : 'Nothing open - Domma is a message away',
+            details: {title: 'Support', rows: [{label: 'Open requests', value: String(openCount)}, {label: 'Waiting to send', value: String(waiting)}],
+                empty: 'Nothing open.'}};
+    });
+
+    // A screen load waits for the manager at most this long; past it, the last view is shown and
+    // the sync carries on in the background (each call has its own 10 s timeout, and items go one by one).
+    const SCREEN_WAIT_MS = options.screenWaitMs ?? 6000;
+    const withDeadline = (p, fallback) => new Promise((resolve) => {
+        const t = setTimeout(() => resolve(fallback()), SCREEN_WAIT_MS);
+        p.then((v) => { clearTimeout(t); resolve(v); }, () => { clearTimeout(t); resolve(fallback()); });
+    });
+    const offlineView = (error) => ({tickets: mergeTickets(outbox.all(), null, outbox.seen(), outbox.tickets()), reachable: false, error});
+
+    fastify.get('/tickets', can('send'), async () => {
+        const r = await withDeadline(sync(), () => offlineView('Domma is slow to answer - showing what we last heard.'));
+        return {connected: Boolean(manager), reachable: r.reachable, error: r.error, contact: contact(), tickets: r.tickets};
+    });
+
+    const notConnected = (reply) => reply.code(409).send({error: 'This site is not connected to Domma, so a request cannot be sent from here. Email us instead.'});
+
+    fastify.post('/tickets', can('send'), async (request, reply) => {
+        if (!manager) return notConnected(reply);
+        const {request: req, error} = cleanRequest(request.body || {});
+        if (error) return reply.code(400).send({error});
+        const payload = buildTicketPayload({request: req, user: request.user, cmsVersion: cmsVersion(), site: manager.slug, ref: newRef()});
+        outbox.add('ticket', payload);
+        const r = await withDeadline(flush(outbox, api), () => ({error: 'Domma is slow to answer'}));
+        const item = outbox.all().find(i => i.ref === payload.ref);
+        return reply.code(201).send({ref: payload.ref, state: item?.state || 'waiting',
+            message: item?.state === 'sent' ? 'Sent to Domma Support. We will reply here, and by email.'
+                : `Kept here and sent as soon as Domma answers. (${r.error || 'not sent yet'})`});
+    });
+
+    const turn = (close) => async (request, reply) => {
+        if (!manager) return notConnected(reply);
+        const ticketRef = String(request.params.ref);
+        const known = outbox.tickets().some(t => t.ref === ticketRef) || outbox.all().some(i => i.kind === 'ticket' && i.ref === ticketRef);
+        if (!known) return reply.code(404).send({error: 'No such request on this site.'});
+        let body = '';
+        if (!close) {
+            const {message, error} = cleanMessage(request.body || {});
+            if (error) return reply.code(400).send({error});
+            body = message.body;
+        }
+        const payload = buildMessagePayload({ticketRef, ref: newRef(), body, close, user: request.user});
+        outbox.add('message', payload, ticketRef);
+        await withDeadline(flush(outbox, api), () => ({}));
+        const item = outbox.all().find(i => i.ref === payload.ref);
+        return reply.code(201).send({ref: payload.ref, state: item?.state || 'waiting',
+            message: item?.state === 'sent' ? (close ? 'Marked as resolved. Thank you.' : 'Sent.') : 'Kept here and sent as soon as Domma answers.'});
+    };
+    fastify.post('/tickets/:ref/messages', {...can('send'), bodyLimit: 32 * 1024}, turn(false));
+    fastify.post('/tickets/:ref/close', can('send'), turn(true));
+
+    fastify.put('/tickets/:ref/seen', can('send'), async (request) => {
+        outbox.markSeen(String(request.params.ref), String(request.body?.at || ''));
+        return {ok: true};
+    });
+}
+
+// ---------------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------------
+
+async function receiverRoutes(fastify, {can, notify, mail, receiverMod, settings, options}) {
+    const rx = receiverMod;
+    const slugOf = options.slugFromToken || rx.slugFromToken;
+    const directory = options.siteDirectory || rx.siteDirectory;
+    const allowed = createThrottle({max: Number(settings.perSiteMax) || 20, windowMs: (Number(settings.perSiteMinutes) || 10) * 60_000});
+    const log = fastify.log;
+    if (options.dataDir) rx.setDataDir(options.dataDir);
+    try { await rx.ensureCollection(); } catch (err) { log.error(`[support] collection: ${err.message}`); }
+
+    const siteOf = (slug) => directory()[slug] || {name: slug, host: ''};
+    const inboxLink = (id) => `${mail.siteUrl()}/admin/#/plugins/support/${encodeURIComponent(id)}`;
+    const siteLink = (slug, ref) => {
+        const host = siteOf(slug).host;
+        return host ? `https://${host}/admin/#/plugins/support/${encodeURIComponent(ref)}` : '';
+    };
+
+    /** Tell Domma: a notice in the admin, and an email to the support mailbox. Never awaited. */
+    function toDomma(entry, body, isNew) {
+        const d = entry.data;
+        const name = siteOf(d.site).name;
+        notify({title: `${d.priority === 'urgent' ? 'URGENT - ' : ''}${isNew ? 'Support request' : 'Reply'} from ${name}: ${d.subject}`,
+            body: body.slice(0, 300), severity: d.priority === 'urgent' ? 'warning' : 'info', source: 'new-request',
+            link: `#/plugins/support/${entry.id}`, dedupeKey: `support:${entry.id}:${d.lastAt}`});
+        if (settings.notifyEmail) {
+            mail.send({to: settings.notifyEmail, ...toDommaEmail({ticket: d, siteName: name, link: inboxLink(entry.id), body, isNew})}, {log});
+        }
+    }
+
+    // ---- From the sites (no session: the fleet token IS the identity) ----
+
+    const fleet = async (request, reply) => {
+        const slug = await slugOf(request.headers.authorization);
+        if (!slug) { reply.code(401).send({error: 'Unknown site.'}); return null; }
+        return slug;
+    };
+
+    fastify.post('/fleet/tickets', {bodyLimit: 32 * 1024}, async (request, reply) => {
+        const slug = await fleet(request, reply);
+        if (!slug) return reply;
+        if (!allowed(slug)) return reply.code(429).send({error: 'That is a lot of requests at once - try again in a few minutes, or email us.'});
+        const r = await rx.open(slug, request.body || {}, undefined, siteOf(slug));
+        if (r.missing) return reply.code(404).send({error: r.error});
+        if (r.error) return reply.code(400).send({error: r.error});
+        if (r.created) toDomma(r.entry, r.entry.data.messages[0]?.body || '', true);
+        return reply.code(r.created ? 201 : 200).send({id: r.entry.id, ref: r.entry.data.ref, status: r.entry.data.status});
+    });
+
+    fastify.post('/fleet/messages', {bodyLimit: 32 * 1024}, async (request, reply) => {
+        const slug = await fleet(request, reply);
+        if (!slug) return reply;
+        if (!allowed(slug)) return reply.code(429).send({error: 'That is a lot of messages at once - try again in a few minutes.'});
+        const r = await rx.customerTurn(slug, request.body || {});
+        if (r.missing) return reply.code(404).send({error: r.error});
+        if (r.error) return reply.code(400).send({error: r.error});
+        const body = String(request.body?.body || '').trim();
+        if (r.added && body) toDomma(r.entry, body, false);
+        return {id: r.entry.id, status: r.entry.data.status};
+    });
+
+    fastify.get('/fleet/mine', async (request, reply) => {
+        const slug = await fleet(request, reply);
+        if (!slug) return reply;
+        return {tickets: (await rx.ticketsOf(slug)).map(senderView), contact: contactCard(settings)};
+    });
+
+    // ---- The inbox ----
+
+    const row = (e, dir = directory()) => ({id: e.id, ...e.data, siteName: dir[e.data.site]?.name || e.data.site,
+        siteHost: dir[e.data.site]?.host || '', createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt});
+
+    fastify.get('/mode', can('manage'), async () => ({mode: 'receiver', connected: true, contact: contactCard(settings),
+        notifyEmail: settings.notifyEmail || ''}));
+
+    fastify.get('/count', can('manage'), async () => {
+        const all = await rx.allTickets();
+        const waiting = all.filter(e => e.data?.status === 'open');
+        const urgent = waiting.filter(e => e.data?.priority === 'urgent');
+        const dir = directory();
+        if (!waiting.length) {
+            return {count: all.length, inventory: true, tone: 'info', label: `${all.length} request${all.length === 1 ? '' : 's'} - none waiting`,
+                details: {title: 'Support', empty: 'Nothing waiting on Domma.'}};
+        }
+        return {
+            count: waiting.length,
+            tone: urgent.length ? 'danger' : 'attention',
+            label: `${waiting.length} waiting on Domma${urgent.length ? `, ${urgent.length} urgent` : ''}`,
+            details: {title: 'Waiting on Domma', rows: [{label: 'Waiting', value: String(waiting.length)}, {label: 'Urgent', value: String(urgent.length), ...(urgent.length && {tone: 'danger'})}],
+                items: [...urgent, ...waiting.filter(e => e.data.priority !== 'urgent')].slice(0, 6)
+                    .map(e => ({text: e.data.subject, meta: dir[e.data.site]?.name || e.data.site, ...(e.data.priority === 'urgent' && {tone: 'danger'})})),
+                empty: ''}
+        };
+    });
+
+    fastify.get('/tickets', can('manage'), async () => {
+        const dir = directory();
+        return {tickets: (await rx.allTickets()).map(e => row(e, dir))};
+    });
+
+    fastify.get('/tickets/:id', can('manage'), async (request, reply) => {
+        const e = await rx.getTicket(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such request.'});
+        return row(e);
+    });
+
+    fastify.post('/tickets/:id/reply', {...can('manage'), bodyLimit: 32 * 1024}, async (request, reply) => {
+        const e = await rx.getTicket(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such request.'});
+        const body = String(request.body?.body ?? '').replace(/\r\n?/g, '\n').trim().slice(0, 8000);
+        const status = request.body?.status;
+        if (status !== undefined && !STATUSES.some(s => s.key === status)) return reply.code(400).send({error: 'That is not a status.'});
+        if (!body && !status) return reply.code(400).send({error: 'Write a reply first.'});
+        const by = String(request.user?.name || 'Domma Support');
+        const next = await rx.dommaTurn(e.id, {body, status, by, msgId: randomUUID()});
+        const d = next.data;
+        // The customer hears of a reply, and of their request being resolved - not of a quiet status change back to open.
+        if (d.userEmail && (body || (d.status === 'closed' && e.data.status !== 'closed'))) {
+            mail.send({to: d.userEmail, ...toCustomerEmail({ticket: d, siteName: siteOf(d.site).name, link: siteLink(d.site, d.ref), body,
+                resolved: d.status === 'closed'})}, {log});
+        }
+        return row(next);
+    });
+
+    fastify.put('/tickets/:id', can('manage'), async (request, reply) => {
+        const e = await rx.getTicket(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such request.'});
+        const {patch, error} = cleanUpdate(request.body || {});
+        if (error) return reply.code(400).send({error});
+        return row(await rx.patch(e.id, patch, String(request.user?.name || 'Domma Support')));
+    });
+
+    fastify.delete('/tickets/:id', can('manage'), async (request, reply) => {
+        const e = await rx.getTicket(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such request.'});
+        await rx.removeTicket(e.id);
+        return {ok: true};
+    });
+}

package/plugins/support/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "support",
+  "displayName": "Support",
+  "version": "1.0.0",
+  "tier": "free",
+  "description": "Get help from Domma straight from your admin: our email, phone and hours always to hand, and a conversation with the Domma team for anything you need - urgent requests first.",
+  "author": "Domma CMS",
+  "date": "2026-10-04",
+  "icon": "headphones",
+  "permissions": [
+    {
+      "key": "support",
+      "label": "Support",
+      "group": "Plugins",
+      "icon": "headphones",
+      "description": "Ask Domma for help and follow the conversation (send). On the Domma server itself: the inbox of every site's requests (manage).",
+      "actions": [
+        {"key": "send", "label": "Send", "description": "Ask Domma for help and read this site's requests and replies"},
+        {"key": "manage", "label": "Manage", "description": "On the Domma server: read and answer every site's requests"}
+      ],
+      "grant": ["admin"]
+    }
+  ],
+  "admin": {
+    "css": ["admin/css/index.css"],
+    "sidebar": [
+      {
+        "id": "support",
+        "text": "Support",
+        "icon": "headphones",
+        "url": "#/plugins/support",
+        "section": "#/plugins/support",
+        "permission": "support",
+        "countUrl": "/api/plugins/support/count"
+      }
+    ],
+    "routes": [
+      {"path": "/plugins/support", "view": "plugin-support", "title": "Support - Domma CMS"},
+      {"path": "/plugins/support/:id", "view": "plugin-support", "title": "Support - Domma CMS"}
+    ],
+    "views": {
+      "plugin-support": {
+        "entry": "support/admin/views/support.js",
+        "exportName": "supportView"
+      }
+    }
+  }
+}