domma-cms 0.55.1 → 0.66.0

package/plugins/mail-reader/plugin.js

@@ -0,0 +1,48 @@
+/**
+ * Mail Reader plugin - read-only IMAP mailbox reader.
+ *
+ * Almost nothing lives here. The routes are `registerReadRoutes()` from
+ * `plugins/_lib/mail/`, shared with `email-pro`, which registers the same
+ * surface and adds writing, sending and a synchronised store on top. This file
+ * is the free edition's wiring: its defaults, its connection pool, and the
+ * decision to register the read surface and nothing else.
+ *
+ * Routes mount at /api/plugins/mail-reader. See
+ * `plugins/_lib/mail/readRoutes.js` for what they do and why they are
+ * read-only at the protocol level rather than merely by omission.
+ *
+ * @module mail-reader/plugin
+ */
+import {createPool} from '../_lib/mail/imapPool.js';
+import {registerReadRoutes} from '../_lib/mail/readRoutes.js';
+import defaultConfig from './config.js';
+
+export default async function mailReaderPlugin(fastify, options) {
+    const config = {...defaultConfig, ...(options.settings || {})};
+    const pool = createPool(config);
+
+    // Connections are process state; a reload or shutdown should close them
+    // rather than leave the mail server holding dead sessions.
+    fastify.addHook('onClose', async () => pool.closeAll());
+
+    registerReadRoutes(fastify, {
+        auth: options.auth,
+        hooks: options.hooks,
+        config,
+        pool,
+        pluginName: 'mail-reader'
+    });
+}
+
+/**
+ * Nothing to provision - the plugin's only state is the shared mail store,
+ * which is created on first save.
+ *
+ * @returns {Promise<void>}
+ */
+export async function onEnable() {}
+
+/**
+ * @returns {Promise<void>}
+ */
+export async function onDisable() {}

package/plugins/mail-reader/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "mail-reader",
+  "displayName": "Mail Reader",
+  "version": "1.0.0",
+  "description": "Read-only IMAP mailbox reader. Connects to a standard IMAP server and reads mail without ever writing to it.",
+  "author": "Darryl Waterhouse",
+  "date": "2026-09-19",
+  "icon": "mail",
+  "admin": {
+    "sidebar": [
+      {
+        "id": "mail-reader",
+        "text": "Mail Reader",
+        "icon": "mail",
+        "url": "#/plugins/mail-reader",
+        "section": "#/plugins/mail-reader"
+      }
+    ],
+    "routes": [
+      {
+        "path": "/plugins/mail-reader",
+        "view": "plugin-mail-reader",
+        "title": "Mail Reader - Domma CMS"
+      }
+    ],
+    "views": {
+      "plugin-mail-reader": {
+        "entry": "mail-reader/admin/views/mail.js?v=c5c6483f",
+        "exportName": "mailView"
+      }
+    }
+  }
+}

package/plugins/notes/admin/views/notes.js

@@ -111,7 +111,7 @@ export const notesView = {
                         render: (v) => {
                             if (!Array.isArray(v) || v.length === 0) return '<span style="opacity:0.35;">-</span>';
                             return v.map((c) =>
-                                `<span class="badge badge-outline notes-cat-tag" data-cat="${esc(c)}" `
+                                `<span class="badge badge-secondary notes-cat-tag" data-cat="${esc(c)}" `
                                 + `style="font-size:0.7rem;margin-right:2px;cursor:pointer;">${esc(c)}</span>`
                             ).join('');
                         }

package/plugins/notes/plugin.json

@@ -5,7 +5,7 @@
   "description": "Rich note-taking with categories, search, and markdown content.",
   "author": "Darryl Waterhouse",
   "date": "2026-03-24",
-  "icon": "file-text",
+  "icon": "edit-3",
   "admin": {
     "sidebar": [
       {
@@ -25,7 +25,7 @@
     ],
     "views": {
       "plugin-notes": {
-        "entry": "notes/admin/views/notes.js?v=1010cfca",
+        "entry": "notes/admin/views/notes.js?v=ecd1b254",
         "exportName": "notesView"
       }
     }

package/plugins/surveys/lib/audience.js

@@ -0,0 +1,37 @@
+const C = 'surveys-contacts';
+
+function parseGroups(raw) {
+    if (Array.isArray(raw)) return raw;
+    if (typeof raw === 'string') { try { return JSON.parse(raw); } catch { return raw ? [raw] : []; } }
+    return [];
+}
+
+export function createAudience(col) {
+    async function listContacts() {
+        const {entries} = await col.listEntries(C, {limit: 100000});
+        return entries.map(e => ({id: e.id, name: e.data.name ?? '', email: e.data.email ?? '', groups: parseGroups(e.data.groups)}));
+    }
+
+    async function contactIdsForGroups(groupNames) {
+        const want = new Set(groupNames);
+        const contacts = await listContacts();
+        return contacts.filter(c => c.groups.some(g => want.has(g))).map(c => c.id);
+    }
+
+    async function importFromContacts(sourceContacts) {
+        let imported = 0;
+        for (const c of sourceContacts) {
+            const email = (c.email ?? '').trim();
+            if (!email) continue;
+            await col.createEntry(C, {
+                name: (c.name ?? '').trim(),
+                email,
+                groups: parseGroups(c.groups)
+            }, {source: 'import-contacts'});
+            imported++;
+        }
+        return {imported};
+    }
+
+    return {listContacts, contactIdsForGroups, importFromContacts};
+}

package/plugins/surveys/lib/campaigns.js

@@ -0,0 +1,43 @@
+const S = 'surveys-surveys';
+const MODES = new Set(['identified', 'anonymous']);
+const STATUSES = new Set(['draft', 'open', 'closed']);
+
+export function createCampaigns(col) {
+    async function all() { const {entries} = await col.listEntries(S, {limit: 100000}); return entries; }
+    async function getBySlug(slug) { return (await all()).find(e => e.data.slug === slug) ?? null; }
+
+    async function createSurvey(input) {
+        if (!input.slug || !input.title || !input.formSlug) throw new Error('slug, title and formSlug are required');
+        if (await getBySlug(input.slug)) throw new Error(`A survey with slug "${input.slug}" already exists`);
+        return col.createEntry(S, {
+            slug: input.slug,
+            title: input.title,
+            description: input.description ?? '',
+            formSlug: input.formSlug,
+            groupIds: Array.isArray(input.groupIds) ? input.groupIds : [],
+            mode: MODES.has(input.mode) ? input.mode : 'identified',
+            status: STATUSES.has(input.status) ? input.status : 'draft',
+            opensAt: input.opensAt ?? null,
+            closesAt: input.closesAt ?? null,
+            reminderAfterDays: Number(input.reminderAfterDays) || 7,
+            intro: input.intro ?? '',
+            footer: input.footer ?? '',
+            thankYou: input.thankYou ?? '',
+            inviteEmail: input.inviteEmail ?? {subject: '', body: ''}
+        }, {source: 'admin'});
+    }
+
+    async function updateSurvey(id, patch) {
+        const entry = await col.getEntry(S, id);
+        if (!entry) throw new Error('Survey not found');
+        const merged = {...entry.data};
+        for (const k of ['title', 'description', 'formSlug', 'groupIds', 'opensAt', 'closesAt', 'reminderAfterDays', 'intro', 'footer', 'thankYou', 'inviteEmail']) {
+            if (k in patch) merged[k] = patch[k];
+        }
+        if (patch.mode && MODES.has(patch.mode)) merged.mode = patch.mode;
+        if (patch.status && STATUSES.has(patch.status)) merged.status = patch.status;
+        return col.updateEntry(S, id, merged);
+    }
+
+    return {all, getBySlug, createSurvey, updateSurvey};
+}

package/plugins/surveys/lib/ledger.js

@@ -0,0 +1,110 @@
+import {generateToken, hashToken, normaliseCode} from './tokens.js';
+
+const SLUG = 'surveys-invites';
+
+/**
+ * Ledger over the surveys-invites collection.
+ * @param {{createEntry,listEntries,getEntry,updateEntry}} col collections service
+ */
+export function createLedger(col) {
+    async function invitesForSurvey(surveyId) {
+        const {entries} = await col.listEntries(SLUG, {limit: 100000});
+        return entries.filter(e => e.data.surveyId === surveyId);
+    }
+
+    /** Issue pending invites for contacts that don't already have one. Returns [{id, contactId, token}]. */
+    async function issueInvites(surveyId, contactIds) {
+        const existing = await invitesForSurvey(surveyId);
+        const seen = new Set(existing.map(e => e.data.contactId));
+        const out = [];
+        for (const contactId of contactIds) {
+            if (seen.has(contactId)) continue;
+            const token = generateToken();
+            const entry = await col.createEntry(SLUG, {
+                surveyId, contactId,
+                tokenHash: hashToken(normaliseCode(token)),
+                status: 'pending', sentAt: null, completedAt: null, responseId: null
+            }, {source: 'surveys'});
+            out.push({id: entry.id, contactId, token});
+            seen.add(contactId);
+        }
+        return out;
+    }
+
+    /**
+     * Ensure every listed contact has a FRESH token to email. New contacts get a
+     * created invite; existing non-completed invites are re-issued with a new
+     * token (so re-sends and reminders carry a working personalised link);
+     * contacts who already completed the survey are skipped. The previous token
+     * for a re-issued invite stops working - latest link wins.
+     *
+     * Returns [{id, contactId, token}] for the invites to email.
+     */
+    async function issueOrReissue(surveyId, contactIds) {
+        const existing = await invitesForSurvey(surveyId);
+        const byContact = new Map(existing.map(e => [e.data.contactId, e]));
+        const out = [];
+        for (const contactId of contactIds) {
+            const ex = byContact.get(contactId);
+            if (ex && ex.data.status === 'completed') continue;
+            const token = generateToken();
+            const tokenHash = hashToken(normaliseCode(token));
+            if (ex) {
+                await col.updateEntry(SLUG, ex.id, {...ex.data, tokenHash});
+                out.push({id: ex.id, contactId, token});
+            } else {
+                const entry = await col.createEntry(SLUG, {
+                    surveyId, contactId, tokenHash,
+                    status: 'pending', sentAt: null, completedAt: null, responseId: null
+                }, {source: 'surveys'});
+                out.push({id: entry.id, contactId, token});
+            }
+        }
+        return out;
+    }
+
+    /** Find an invite by submitted code (any format). Null if unknown. */
+    async function findByCode(surveyId, code) {
+        const hash = hashToken(normaliseCode(code));
+        const invites = await invitesForSurvey(surveyId);
+        return invites.find(e => e.data.tokenHash === hash) ?? null;
+    }
+
+    /** Mark sent / bounced. */
+    async function markSent(inviteId, ok, nowIso) {
+        const entry = await col.getEntry(SLUG, inviteId);
+        if (!entry) return null;
+        return col.updateEntry(SLUG, inviteId, {
+            ...entry.data,
+            status: ok ? 'sent' : 'bounced',
+            sentAt: ok ? nowIso : entry.data.sentAt
+        });
+    }
+
+    /** Mark completed with the stored response id. */
+    async function markCompleted(inviteId, responseId, nowIso) {
+        const entry = await col.getEntry(SLUG, inviteId);
+        if (!entry) return null;
+        return col.updateEntry(SLUG, inviteId, {
+            ...entry.data, status: 'completed', completedAt: nowIso, responseId: responseId ?? null
+        });
+    }
+
+    /** Invites that are neither completed nor bounced. */
+    async function outstanding(surveyId) {
+        const invites = await invitesForSurvey(surveyId);
+        return invites.filter(e => e.data.status !== 'completed' && e.data.status !== 'bounced');
+    }
+
+    /** Sent invites, not yet completed, whose sentAt is older than afterDays before now. */
+    async function dueForReminder(surveyId, afterDays, now) {
+        const cutoff = now.getTime() - Number(afterDays) * 86400000;
+        const invites = await invitesForSurvey(surveyId);
+        return invites.filter(e =>
+            e.data.status === 'sent' &&
+            e.data.sentAt && new Date(e.data.sentAt).getTime() <= cutoff
+        );
+    }
+
+    return {invitesForSurvey, issueInvites, issueOrReissue, findByCode, markSent, markCompleted, outstanding, dueForReminder};
+}

package/plugins/surveys/lib/sending.js

@@ -0,0 +1,106 @@
+import {formatCode} from './tokens.js';
+
+function escapeHtml(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Escape a value for use inside a double-quoted HTML attribute (e.g. href). */
+function escapeAttr(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+/**
+ * Render one invite's subject + plain-text + HTML from a template and a link.
+ *
+ * The HTML version turns each {{link}} into a clickable "Take the survey" button
+ * (the raw URL was previously emitted as inert escaped text - unclickable). All
+ * non-link copy is escaped so user-authored bodies can't inject markup. The
+ * plain-text version keeps the raw URL.
+ */
+export function renderInvite(template, contact, link) {
+    const name = contact.name || 'there';
+    const subjectTpl = (template.subject && template.subject.trim()) || 'You are invited to a survey';
+    const bodyTpl = (template.body && template.body.trim())
+        || "Hi {{name}},\n\nWe'd really value your feedback - it only takes a minute.\n\n{{link}}";
+
+    const subject = subjectTpl.replaceAll('{{name}}', name).replaceAll('{{link}}', link);
+    const text = bodyTpl.replaceAll('{{name}}', name).replaceAll('{{link}}', link);
+
+    const button = `<p style="margin:24px 0;"><a href="${escapeAttr(link)}" `
+        + `style="display:inline-block;background:#2563eb;color:#ffffff;text-decoration:none;`
+        + `padding:12px 24px;border-radius:6px;font-weight:600;font-size:15px;">Take the survey</a></p>`;
+
+    const bodyHtml = bodyTpl
+        .split('{{link}}')
+        .map((seg) => escapeHtml(seg.replaceAll('{{name}}', name)).replace(/\n/g, '<br>'))
+        .join(button);
+
+    const html = `<div style="font-family:-apple-system,Segoe UI,Roboto,Arial,sans-serif;`
+        + `max-width:560px;margin:0 auto;padding:24px;color:#1f2937;line-height:1.6;font-size:15px;">`
+        + bodyHtml
+        + `<hr style="border:none;border-top:1px solid #e5e7eb;margin:24px 0;">`
+        + `<p style="font-size:12px;color:#6b7280;">If the button doesn't work, paste this link into your browser:<br>`
+        + `<a href="${escapeAttr(link)}" style="color:#2563eb;">${escapeHtml(link)}</a></p>`
+        + `</div>`;
+
+    return {subject, text, html};
+}
+
+/**
+ * Send to each recipient; never fails wholesale. Returns [{inviteId, ok}].
+ * @param {Array<{invite,contact,token}>} recipients
+ * @param {{subject,body}} template
+ * @param {object} deps {sendEmail, transport, from, fromName, baseUrl, surveySlug}
+ */
+export async function sendBatch(recipients, template, deps) {
+    const {sendEmail, transport, from, fromName, baseUrl, surveySlug} = deps;
+    const results = [];
+    for (const r of recipients) {
+        const link = `${baseUrl}/survey/${surveySlug}?t=${formatCode(r.token)}`;
+        const msg = renderInvite(template, r.contact, link);
+        try {
+            await sendEmail(transport, {from, fromName, to: r.contact.email, subject: msg.subject, html: msg.html, text: msg.text});
+            results.push({inviteId: r.invite.id, ok: true});
+        } catch {
+            results.push({inviteId: r.invite.id, ok: false});
+        }
+    }
+    return results;
+}
+
+/**
+ * Resolve recipients for a survey and send them invites, flipping the ledger.
+ * Shared by the admin /send route and the scheduler /run route.
+ * @param {object} ctx {survey, mode, audience, ledger, transport, sendEmail, smtp, baseUrl, fromName, nowIso}
+ * @returns {Promise<{results: Array<{inviteId,ok}>}>}
+ */
+export async function runSend(ctx) {
+    const {survey, mode, audience, ledger, transport, sendEmail, smtp, baseUrl, fromName, nowIso} = ctx;
+    const groupNames = Array.isArray(survey.data.groupIds) ? survey.data.groupIds : [];
+    const contactIds = await audience.contactIdsForGroups(groupNames);
+    const contacts = (await audience.listContacts()).filter(c => contactIds.includes(c.id));
+
+    // Who to target: 'non-responders' narrows to contacts whose invite is still
+    // outstanding (invited, not completed/bounced); 'all' targets everyone.
+    let targetIds = contactIds;
+    if (mode === 'non-responders') {
+        const outstanding = new Set((await ledger.outstanding(survey.id)).map(e => e.data.contactId));
+        targetIds = contactIds.filter(id => outstanding.has(id));
+    }
+
+    // (Re)issue a fresh token for each target so re-sends and reminders carry a
+    // working personalised link; contacts who already completed are skipped.
+    const issued = await ledger.issueOrReissue(survey.id, targetIds);
+    const tokenByContact = new Map(issued.map(i => [i.contactId, i]));
+    const recipients = contacts
+        .filter(c => tokenByContact.has(c.id))
+        .map(c => {
+            const inv = tokenByContact.get(c.id);
+            return {invite: {id: inv.id}, contact: c, token: inv.token};
+        });
+    const results = await sendBatch(recipients, survey.data.inviteEmail || {}, {
+        sendEmail, transport, from: smtp.fromAddress, fromName: smtp.fromName || fromName, baseUrl, surveySlug: survey.data.slug
+    });
+    for (const r of results) await ledger.markSent(r.inviteId, r.ok, nowIso);
+    return {results};
+}

package/plugins/surveys/lib/stats.js

@@ -0,0 +1,62 @@
+const CHOICE = new Set(['select', 'radio', 'checkbox', 'dropdown']);
+const RATING = new Set(['rating', 'number', 'range']);
+
+/** Aggregate one field across response rows into a normalised distribution. */
+export function aggregateField(field, rows) {
+    const label = field.label || field.name;
+    if (RATING.has(field.type)) {
+        const nums = rows.map(r => Number(r[field.name])).filter(n => !Number.isNaN(n));
+        const average = nums.length ? Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 100) / 100 : 0;
+        const counts = tally(rows.map(r => String(r[field.name] ?? '')).filter(Boolean));
+        return {field: field.name, label, type: 'rating', average, items: toItems(counts)};
+    }
+    if (CHOICE.has(field.type)) {
+        const counts = tally(rows.flatMap(r => Array.isArray(r[field.name]) ? r[field.name] : [r[field.name]]).filter(Boolean));
+        return {field: field.name, label, type: 'choice', items: toItems(counts)};
+    }
+    return {field: field.name, label, type: 'text', responses: rows.map(r => r[field.name]).filter(Boolean)};
+}
+
+function tally(values) {
+    const m = new Map();
+    for (const v of values) m.set(v, (m.get(v) || 0) + 1);
+    return m;
+}
+
+function toItems(counts) {
+    const total = [...counts.values()].reduce((a, b) => a + b, 0) || 1;
+    return [...counts.entries()].map(([k, v]) => ({label: String(k), value: v, pct: Math.round((v / total) * 100)}));
+}
+
+/**
+ * THE CHARTS SEAM. Input shape [{label,value,pct}] is the exact contract a
+ * future framework charts() call will accept. Swap this body for that call
+ * when the component lands. See docs/superpowers/specs/2026-06-26-domma-charts-upstream-proposal.md.
+ */
+export function renderDistribution(items) {
+    return `<div class="survey-dist">` + items.map(i =>
+        `<div class="survey-dist-row"><span class="survey-dist-label">${escapeHtml(i.label)}</span>` +
+        `<span class="survey-dist-bar"><span class="survey-dist-fill" data-pct="${i.pct}" style="width:${i.pct}%"></span></span>` +
+        `<span class="survey-dist-val">${i.value} (${i.pct}%)</span></div>`
+    ).join('') + `</div>`;
+}
+
+export function campaignHealth(invites) {
+    const invited = invites.length;
+    const completed = invites.filter(i => i.data.status === 'completed').length;
+    return {invited, completed, responseRate: invited ? Math.round((completed / invited) * 100) : 0};
+}
+
+export function toCsv(rows, columns) {
+    const esc = (v) => {
+        const s = String(v ?? '');
+        return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+    };
+    const head = columns.join(',');
+    const body = rows.map(r => columns.map(c => esc(r[c])).join(',')).join('\n');
+    return `${head}\n${body}`;
+}
+
+function escapeHtml(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

package/plugins/surveys/lib/submit.js

@@ -0,0 +1,95 @@
+import {createRequire} from 'module';
+
+const require = createRequire(import.meta.url);
+const FormLogicEngine = require('../../../public/js/form-logic-engine.js');
+
+class SurveyError extends Error {
+    constructor(message, code = 400) { super(message); this.statusCode = code; }
+}
+
+function withinWindow(data, now) {
+    const t = new Date(now).getTime();
+    if (data.opensAt && t < new Date(data.opensAt).getTime()) return false;
+    if (data.closesAt && t > new Date(data.closesAt).getTime()) return false;
+    return true;
+}
+
+/** Validate visible fields with the same engine core uses. Throws SurveyError. */
+function validate(form, body) {
+    const values = {};
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        const v = body[f.name];
+        values[f.name] = typeof v === 'string' ? v.trim() : (v ?? '');
+    }
+    const missing = [];
+    const errors = [];
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        if (FormLogicEngine.evaluateFieldVisibility(f, values) === 'hidden') continue;
+        const val = values[f.name];
+        const empty = !val?.toString().trim();
+        if (FormLogicEngine.evaluateFieldRequirement(f, values) && empty) missing.push(f.label || f.name);
+        else if (!empty) {
+            const e = FormLogicEngine.validateField(f, val, values);
+            if (e.length) errors.push(e[0].message);
+        }
+    }
+    if (missing.length || errors.length) {
+        const parts = [];
+        if (missing.length) parts.push(`Required fields missing: ${missing.join(', ')}`);
+        if (errors.length) parts.push(errors.join('; '));
+        throw new SurveyError(`${parts.join('. ')}.`);
+    }
+    return values;
+}
+
+/**
+ * Process a tokenised survey submission.
+ * @param {string} surveySlug
+ * @param {string} code submitted invite code (any format)
+ * @param {object} body answer values keyed by field name
+ * @param {object} deps {col, ledger, getSurveyBySlug, readForm, getCollection, sendCompletionEmail, now}
+ * @returns {Promise<{ok:true, message:string}>}
+ */
+export async function processSurveySubmission(surveySlug, code, body, deps) {
+    const {col, ledger, getSurveyBySlug, readForm, getCollection, sendCompletionEmail, now} = deps;
+
+    const survey = await getSurveyBySlug(surveySlug);
+    if (!survey) throw new SurveyError('Survey not found.', 404);
+    const s = survey.data;
+    if (s.status !== 'open') throw new SurveyError('This survey has closed.', 410);
+    if (!withinWindow(s, now())) throw new SurveyError('This survey has closed.', 410);
+
+    const invite = await ledger.findByCode(survey.id, code);
+    if (!invite) throw new SurveyError('That code is invalid for this survey.', 403);
+    if (invite.data.status === 'completed') throw new SurveyError('This survey has already been completed for that code.', 409);
+
+    const form = await readForm(s.formSlug);
+    const values = validate(form, body);
+
+    const targetSlug = s.formSlug;
+    const targetCollection = await getCollection(targetSlug);
+    if (!targetCollection) throw new SurveyError('Survey form is not configured correctly.', 500);
+    const data = {};
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        if (values[f.name] !== undefined) data[f.name] = values[f.name];
+    }
+    // NOTE: contactId / token are deliberately NOT written here - anonymity is intrinsic.
+    const entry = await col.createEntry(targetSlug, data, {source: `survey:${surveySlug}`});
+
+    const responseId = s.mode === 'identified' ? entry.id : null;
+    await ledger.markCompleted(invite.id, responseId, now());
+
+    await sendCompletionEmail(form, data).catch((err) => console.warn('[surveys] completion email failed:', err.message));
+
+    // Prefer the survey's own thank-you message over the underlying form's
+    // successMessage, so respondents see a survey-specific confirmation rather
+    // than the generic form response.
+    const thankYou = (s.thankYou && String(s.thankYou).trim())
+        || 'Thank you - your survey response has been recorded.';
+    return {ok: true, message: thankYou};
+}
+
+export {SurveyError};

package/plugins/surveys/lib/tokens.js

@@ -0,0 +1,28 @@
+import crypto from 'crypto';
+
+const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'; // no O,0,I,1,L
+const LENGTH = 8;
+
+/** Generate an 8-char unambiguous uppercase token. */
+export function generateToken() {
+    const bytes = crypto.randomBytes(LENGTH);
+    let out = '';
+    for (let i = 0; i < LENGTH; i++) out += ALPHABET[bytes[i] % ALPHABET.length];
+    return out;
+}
+
+/** SHA-256 hex of a normalised code. The plaintext is never stored. */
+export function hashToken(code) {
+    return crypto.createHash('sha256').update(String(code)).digest('hex');
+}
+
+/** Display form: ABCD-EFGH. */
+export function formatCode(token) {
+    const t = String(token).toUpperCase();
+    return t.length === 8 ? `${t.slice(0, 4)}-${t.slice(4)}` : t;
+}
+
+/** Canonical form for hashing/lookup: strip non-alphanumerics, uppercase. */
+export function normaliseCode(input) {
+    return String(input ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+}