domma-cms 0.91.1 → 0.92.0

package/plugins/feedback/lib/receiver.js

@@ -0,0 +1,121 @@
+/**
+ * Feedback - the RECEIVING side, on the manager (dcm).
+ *
+ * Reports live in the `feedback-reports` collection (NOT `feedback`: that slug
+ * is the starter preset every site has for visitor comments). Its API is off
+ * on all four verbs - a collection's default is a public read, and these carry
+ * admins' names and emails.
+ *
+ * A site is who its fleet token says it is (site-manager/services/fleetTokens.js,
+ * memory only, minted when the manager forked it). The module is imported at
+ * call time and only exists where Site Manager does, which is also how this
+ * plugin knows it is on the manager.
+ *
+ * @module feedback/lib/receiver
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createCollection, createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
+import {receivedReport, statusFromIssue, statusLabel} from './shape.js';
+
+export const COLLECTION = 'feedback-reports';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SITE_MANAGER = path.resolve(HERE, '..', '..', 'site-manager');
+const TOKENS = path.join(SITE_MANAGER, 'services', 'fleetTokens.js');
+
+/** Is Site Manager here - so this is the manager, and reports come TO it? */
+export const isManager = () => fs.existsSync(TOKENS);
+
+/** The site a bearer token speaks for, or null. */
+export async function slugFromToken(authorization) {
+    const token = String(authorization || '').replace(/^Bearer\s+/i, '').trim();
+    if (!token) return null;
+    try {
+        const tokens = await import(TOKENS);
+        return tokens.resolve(token) || null;
+    } catch { return null; }
+}
+
+/** slug -> display name, from Site Manager's registry. Empty when there is none. */
+export function siteNames() {
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(SITE_MANAGER, 'data', 'sites.json'), 'utf8'));
+        const list = Array.isArray(j) ? j : (j.sites || Object.values(j));
+        return Object.fromEntries(list.filter(s => s?.slug).map(s => [s.slug, s.displayName || s.name || s.slug]));
+    } catch { return {}; }
+}
+
+/** Make the collection when it is missing. Every boot: a plugin switched on by copy never runs onEnable. */
+export async function ensureCollection() {
+    if (await getCollection(COLLECTION)) return false;
+    const schema = JSON.parse(fs.readFileSync(path.join(HERE, '..', 'collections', `${COLLECTION}.json`), 'utf8'));
+    await createCollection(schema);
+    return true;
+}
+
+/** Every report, newest first. */
+export async function allReports() {
+    const {entries} = await listEntries(COLLECTION, {limit: 100000, sort: 'createdAt', order: 'desc'});
+    return entries || [];
+}
+
+export const getReport = (id) => getEntry(COLLECTION, id);
+export const removeReport = (id) => deleteEntry(COLLECTION, id);
+
+/**
+ * A site's report arrived. The same site sending the same `ref` again (a retry
+ * after a reply that never reached it) gets the report it already made.
+ *
+ * @returns {Promise<{entry?: object, created?: boolean, error?: string}>}
+ */
+export async function receive(slug, payload) {
+    const {data, error} = receivedReport(payload, slug);
+    if (error) return {error};
+    if (data.ref) {
+        const same = (await allReports()).find(e => e.data?.site === slug && e.data?.ref === data.ref);
+        if (same) return {entry: same, created: false};
+    }
+    data.history = [{at: new Date().toISOString(), by: data.userName, what: 'Sent'}];
+    const entry = await createEntry(COLLECTION, data, {source: 'fleet'});
+    return {entry, created: true};
+}
+
+/** One site's reports - never another's. */
+export async function reportsOf(slug) {
+    return (await allReports()).filter(e => e.data?.site === slug);
+}
+
+/**
+ * Change a report, keeping a line of history for each thing that moved.
+ *
+ * @param   {string} id
+ * @param   {object} patch - from cleanUpdate()
+ * @param   {string} by - who, for the history
+ * @returns {Promise<object|null>}
+ */
+export async function applyPatch(id, patch, by) {
+    const e = await getReport(id);
+    if (!e) return null;
+    const d = {...e.data};
+    const now = new Date().toISOString();
+    const history = Array.isArray(d.history) ? [...d.history] : [];
+    if (patch.status !== undefined && patch.status !== d.status) history.push({at: now, by, what: `Status: ${statusLabel(patch.status)}`});
+    if (patch.reply !== undefined) { d.replyAt = patch.reply ? now : ''; history.push({at: now, by, what: patch.reply ? 'Replied' : 'Reply removed'}); }
+    if (patch.issueKey !== undefined && patch.issueKey !== d.issueKey) history.push({at: now, by, what: `Waypoint ${patch.issueKey}`});
+    Object.assign(d, patch, {history: history.slice(-100)});
+    return updateEntry(COLLECTION, id, d);
+}
+
+/**
+ * Waypoint says an issue linked to a report moved. The report follows, unless
+ * it was set to "Not planned" by hand.
+ */
+export async function issueMoved(sourceId, issue = {}) {
+    const e = await getReport(sourceId).catch(() => null);
+    if (!e) return null;
+    const status = statusFromIssue(issue.statusCategory, e.data.status);
+    return applyPatch(sourceId, {status, issueStatus: String(issue.statusName || '').slice(0, 60),
+        ...(issue.key && {issueKey: String(issue.key)})}, 'Waypoint');
+}

package/plugins/feedback/lib/sender.js

@@ -0,0 +1,161 @@
+/**
+ * Feedback - the SENDING side, on every site the manager started.
+ *
+ * A report is written to this site's own outbox FIRST and only then sent. The
+ * manager's token for this site rotates whenever either end restarts, and for
+ * those seconds a send answers 401 or does not connect at all - so a report is
+ * never "sent or lost", it is "sent, or waiting". Waiting ones go again the
+ * next time anyone opens the screen, and on the hourly sync.
+ *
+ * The outbox also remembers which vendor replies this site has already seen,
+ * which is what the sidebar badge and the "new reply" notification count.
+ *
+ * @module feedback/lib/sender
+ */
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where this site's manager is, from the environment its manager set.
+ *
+ * @param   {object} [env]
+ * @returns {{url: string, token: string, slug: string}|null}
+ */
+export function managerOf(env = process.env) {
+    if (!env.MANAGER_URL || !env.FLEET_TOKEN) return null;
+    return {url: String(env.MANAGER_URL).replace(/\/+$/, ''), token: String(env.FLEET_TOKEN), slug: String(env.SITE_SLUG || '')};
+}
+
+/**
+ * The outbox: this site's copy of everything it sent, in data/outbox.json.
+ *
+ * @param   {string} dataDir
+ * @returns {object}
+ */
+export function createOutbox(dataDir) {
+    const file = path.join(dataDir, 'outbox.json');
+    const read = () => {
+        try {
+            const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+            return {items: Array.isArray(j.items) ? j.items : [], seen: j.seen && typeof j.seen === 'object' ? j.seen : {}};
+        } catch { return {items: [], seen: {}}; }
+    };
+    const write = (state) => {
+        fs.mkdirSync(dataDir, {recursive: true});
+        fs.writeFileSync(`${file}.tmp`, JSON.stringify(state, null, 2));
+        fs.renameSync(`${file}.tmp`, file);
+    };
+    return {
+        all: () => read().items,
+        seen: () => read().seen,
+        add(payload) {
+            const s = read();
+            const item = {ref: payload.ref, state: 'waiting', payload, createdAt: new Date().toISOString(), remoteId: '', lastError: ''};
+            s.items.push(item);
+            write(s);
+            return item;
+        },
+        mark(ref, patch) {
+            const s = read();
+            const item = s.items.find(i => i.ref === ref);
+            if (!item) return null;
+            Object.assign(item, patch);
+            write(s);
+            return item;
+        },
+        markSeen(id, replyAt) {
+            const s = read();
+            s.seen[id] = replyAt;
+            write(s);
+        }
+    };
+}
+
+export const newRef = () => randomUUID();
+
+/**
+ * Talk to the manager. `fetchImpl` is swapped in tests; nothing here throws -
+ * every call answers `{ok, status?, body?, error?}`.
+ *
+ * @param   {{url: string, token: string}} manager
+ * @param   {Function} [fetchImpl]
+ */
+export function managerApi(manager, fetchImpl = globalThis.fetch) {
+    const call = async (method, route, body) => {
+        try {
+            const res = await fetchImpl(`${manager.url}/api/plugins/feedback/fleet/${route}`, {
+                method,
+                headers: {authorization: `Bearer ${manager.token}`, ...(body && {'content-type': 'application/json'})},
+                ...(body && {body: JSON.stringify(body)}),
+                signal: AbortSignal.timeout(10_000)
+            });
+            let json = null;
+            try { json = await res.json(); } catch { /* not JSON */ }
+            if (res.status >= 200 && res.status < 300) return {ok: true, status: res.status, body: json};
+            return {ok: false, status: res.status, error: json?.error || `The Domma server answered ${res.status}.`};
+        } catch (err) {
+            return {ok: false, error: `Could not reach the Domma server: ${err.message}`};
+        }
+    };
+    return {
+        submit: (payload) => call('POST', 'submit', payload),
+        mine: () => call('GET', 'mine')
+    };
+}
+
+/**
+ * Send whatever is waiting. A report the manager already has (a retry after a
+ * timeout that did arrive) comes back with the same id, so this is safe to
+ * repeat.
+ *
+ * @returns {Promise<{sent: number, waiting: number, error: string}>}
+ */
+export async function flush(outbox, api) {
+    let sent = 0;
+    let error = '';
+    for (const item of outbox.all().filter(i => i.state === 'waiting')) {
+        const r = await api.submit(item.payload);
+        if (r.ok && r.body?.id) {
+            outbox.mark(item.ref, {state: 'sent', remoteId: r.body.id, lastError: '', sentAt: new Date().toISOString()});
+            sent++;
+        } else {
+            error = r.error || 'Not sent.';
+            outbox.mark(item.ref, {lastError: error, triedAt: new Date().toISOString()});
+            // 400 means the manager will never take it as it stands; stop retrying it.
+            if (r.status === 400) outbox.mark(item.ref, {state: 'refused'});
+        }
+    }
+    return {sent, waiting: outbox.all().filter(i => i.state === 'waiting').length, error};
+}
+
+/**
+ * The list the screen shows: the manager's view of every report this site
+ * sent, plus the ones still waiting to go (which the manager has never seen).
+ *
+ * @param   {object[]} outboxItems
+ * @param   {object[]|null} remote - the manager's /mine, or null when it could not be reached
+ * @param   {Object<string, string>} seen - report id -> the replyAt this site has read
+ * @returns {object[]}
+ */
+export function mergeReports(outboxItems, remote, seen = {}) {
+    const out = [];
+    const known = new Set();
+    for (const r of remote || []) {
+        known.add(r.ref);
+        out.push({...r, local: false, unread: Boolean(r.reply && r.replyAt && seen[r.id] !== r.replyAt)});
+    }
+    for (const i of outboxItems) {
+        if (known.has(i.ref)) continue;
+        if (i.state === 'sent' && remote) continue; // the manager dropped it; nothing to show but noise
+        const p = i.payload || {};
+        out.push({
+            id: '', ref: i.ref, type: p.type, title: p.title, description: p.description, where: p.where || '', severity: p.severity || '',
+            userName: p.user?.name || '', status: i.state === 'refused' ? 'refused' : 'waiting',
+            statusLabel: i.state === 'refused' ? 'Not accepted' : 'Waiting to send',
+            reply: '', replyAt: '', issueKey: '', issueStatus: '', createdAt: i.createdAt, updatedAt: i.createdAt,
+            local: true, unread: false, lastError: i.lastError || ''
+        });
+    }
+    return out.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}

package/plugins/feedback/lib/shape.js

@@ -0,0 +1,211 @@
+/**
+ * Feedback - the pure half: what a report is, what each side may say about it,
+ * and how a Waypoint issue's progress becomes a report's status.
+ *
+ * Nothing here touches the disk, the network or the clock (the throttle takes
+ * `now`), so all of it is tested on its own (tests/shape.test.js).
+ *
+ * @module feedback/lib/shape
+ */
+
+/** What a report can be. The icon is a Domma icon name (checked against the registry). */
+export const TYPES = [
+    {key: 'bug', label: 'Something is broken', short: 'Bug', icon: 'alert-circle'},
+    {key: 'feature', label: 'An idea or request', short: 'Request', icon: 'sparkles'},
+    {key: 'question', label: 'A question', short: 'Question', icon: 'help-circle'},
+    {key: 'praise', label: 'Something we got right', short: 'Praise', icon: 'heart'},
+    {key: 'other', label: 'Something else', short: 'Other', icon: 'message-square'}
+];
+
+/** How bad a bug is. Only asked for bugs. */
+export const SEVERITIES = [
+    {key: 'minor', label: 'Minor - a nuisance'},
+    {key: 'major', label: 'Major - gets in the way'},
+    {key: 'blocker', label: 'Blocker - cannot carry on'}
+];
+
+/** Where a report is. The order is the order the inbox offers them in. */
+export const STATUSES = [
+    {key: 'new', label: 'New', tone: 'info'},
+    {key: 'acknowledged', label: 'Seen', tone: 'muted'},
+    {key: 'planned', label: 'Planned', tone: 'info'},
+    {key: 'in-progress', label: 'In progress', tone: 'warning'},
+    {key: 'done', label: 'Done', tone: 'success'},
+    {key: 'declined', label: 'Not planned', tone: 'muted'}
+];
+
+export const TYPE_KEYS = TYPES.map(t => t.key);
+export const STATUS_KEYS = STATUSES.map(s => s.key);
+export const SEVERITY_KEYS = SEVERITIES.map(s => s.key);
+export const statusLabel = (key) => STATUSES.find(s => s.key === key)?.label ?? key;
+export const typeLabel = (key) => TYPES.find(t => t.key === key)?.short ?? key;
+
+/** Longest a field may be. The route's bodyLimit (32 KB) is the outer wall. */
+export const LIMITS = {title: 140, description: 8000, where: 300, reply: 8000, notes: 8000};
+
+const text = (v, max) => String(v ?? '').replace(/\u0000/g, '').replace(/\r\n?/g, '\n').trim().slice(0, max);
+
+/**
+ * What a site admin typed, cleaned. Never carries who sent it - that comes
+ * from the signed-in user on the server, not from the form.
+ *
+ * @param   {object} body
+ * @returns {{report?: object, error?: string}}
+ */
+export function cleanSubmission(body = {}) {
+    const type = TYPE_KEYS.includes(body.type) ? body.type : 'other';
+    const title = text(body.title, LIMITS.title);
+    const description = text(body.description, LIMITS.description);
+    if (!title) return {error: 'Give it a short title.'};
+    if (!description) return {error: 'Say a little more in the description.'};
+    const severity = type === 'bug' && SEVERITY_KEYS.includes(body.severity) ? body.severity : '';
+    return {report: {type, title, description, where: text(body.where, LIMITS.where), severity}};
+}
+
+/**
+ * The payload a site sends the manager: the cleaned report, who sent it (from
+ * the session), and which CMS it runs. `site` is informational only - the
+ * manager attributes a report to the site its token names, never to this.
+ *
+ * @param   {{report: object, user: object, cmsVersion?: string, site?: string, ref: string}} p
+ * @returns {object}
+ */
+export function buildPayload({report, user = {}, cmsVersion = '', site = '', ref}) {
+    return {
+        ref: text(ref, 64),
+        ...report,
+        cmsVersion: text(cmsVersion, 20),
+        site: text(site, 64),
+        user: {id: text(user.id, 64), name: text(user.name, 120), email: text(user.email, 200)}
+    };
+}
+
+/**
+ * A report as the MANAGER stores it, from a site's payload. The slug is the
+ * one the token resolved to; anything the body claims about the site is
+ * ignored.
+ *
+ * @param   {object} payload
+ * @param   {string} slug
+ * @returns {{data?: object, error?: string}}
+ */
+export function receivedReport(payload = {}, slug) {
+    const {report, error} = cleanSubmission(payload);
+    if (error) return {error};
+    const u = payload.user && typeof payload.user === 'object' ? payload.user : {};
+    return {
+        data: {
+            ...report,
+            site: slug,
+            ref: text(payload.ref, 64),
+            cmsVersion: text(payload.cmsVersion, 20),
+            userId: text(u.id, 64),
+            userName: text(u.name, 120) || 'An admin',
+            userEmail: text(u.email, 200),
+            status: 'new',
+            reply: '',
+            replyAt: '',
+            notes: '',
+            issueId: '',
+            issueKey: '',
+            issueStatus: '',
+            history: []
+        }
+    };
+}
+
+/**
+ * What a site may read of one of its own reports. A whitelist: internal notes,
+ * other sites and anything added to the record later stay on the manager.
+ *
+ * @param   {{id: string, data: object, meta?: object}} entry
+ * @returns {object}
+ */
+export function senderView(entry) {
+    const d = entry?.data || {};
+    return {
+        id: entry.id,
+        ref: d.ref || '',
+        type: d.type,
+        title: d.title,
+        description: d.description,
+        where: d.where || '',
+        severity: d.severity || '',
+        userName: d.userName || '',
+        status: d.status,
+        statusLabel: statusLabel(d.status),
+        reply: d.reply || '',
+        replyAt: d.replyAt || '',
+        issueKey: d.issueKey || '',
+        issueStatus: d.issueStatus || '',
+        createdAt: entry.meta?.createdAt || '',
+        updatedAt: entry.meta?.updatedAt || ''
+    };
+}
+
+/**
+ * The status a report takes when its Waypoint issue moves. A report the vendor
+ * marked "Not planned" by hand keeps that, whatever the issue does.
+ *
+ * @param   {string} category - 'todo' | 'doing' | 'done'
+ * @param   {string} current
+ * @returns {string}
+ */
+export function statusFromIssue(category, current) {
+    if (current === 'declined') return current;
+    return {todo: 'planned', doing: 'in-progress', done: 'done'}[category] || current;
+}
+
+/**
+ * What the vendor may change on a report from the inbox.
+ *
+ * @param   {object} body
+ * @param   {object} current - the stored data
+ * @returns {{patch?: object, error?: string}}
+ */
+export function cleanUpdate(body = {}, current = {}) {
+    const patch = {};
+    if (body.status !== undefined) {
+        if (!STATUS_KEYS.includes(body.status)) return {error: 'That is not a status.'};
+        patch.status = body.status;
+    }
+    if (body.reply !== undefined) patch.reply = text(body.reply, LIMITS.reply);
+    if (body.notes !== undefined) patch.notes = text(body.notes, LIMITS.notes);
+    if (!Object.keys(patch).length) return {error: 'Nothing to change.'};
+    if (patch.reply !== undefined && patch.reply === (current.reply || '')) delete patch.reply;
+    return {patch};
+}
+
+/**
+ * How many a site may send: `max` in any `windowMs`. The manager's global
+ * limiter exempts loopback, which is where every site calls from, so this is
+ * the only brake.
+ *
+ * @param   {{max?: number, windowMs?: number}} [opts]
+ * @returns {(key: string, now?: number) => boolean} true when allowed
+ */
+export function createThrottle({max = 10, windowMs = 10 * 60_000} = {}) {
+    const seen = new Map();
+    return (key, now = Date.now()) => {
+        const recent = (seen.get(key) || []).filter(t => now - t < windowMs);
+        if (recent.length >= max) { seen.set(key, recent); return false; }
+        recent.push(now);
+        seen.set(key, recent);
+        return true;
+    };
+}
+
+/**
+ * The description a Waypoint issue gets from a report: the words, then where
+ * they came from.
+ *
+ * @param   {object} d - report data
+ * @returns {string}
+ */
+export function issueDescription(d = {}) {
+    const lines = [d.description || '', '', '---', `From ${d.userName || 'an admin'} on ${d.site || 'a site'}`];
+    if (d.cmsVersion) lines.push(`Domma CMS ${d.cmsVersion}`);
+    if (d.where) lines.push(`Where: ${d.where}`);
+    if (d.severity) lines.push(`Severity: ${d.severity}`);
+    return lines.join('\n');
+}