domma-cms 0.79.1 → 0.80.0

package/server/services/notify.js

@@ -0,0 +1,420 @@
+/**
+ * Notifications the site raises itself - core and plugins alike.
+ *
+ * Until 0.80 the only way in was the manager's push. Now:
+ *
+ *   notify({title, body, severity, link, source, dedupeKey, audience, expiresAt})
+ *       Something happened. Goes to the Super Admins unless the source's
+ *       setting (or `audience: {userIds}`, for a personal one) says otherwise.
+ *   resolveNotification(dedupeKey)
+ *       The cause went away (the plugin loads again, the invoice is paid).
+ *   registerNotificationSource({id, owner, label, description, severity,
+ *                               defaultOn, every, atBoot, check})
+ *       Names a source so Notifications' settings can list it, switch it off
+ *       or send it to other people - and, with `every` + `check`, runs it on a
+ *       timer: 'boot', '15m', 'hourly' or 'daily' (08:00 site time).
+ *
+ * Plugins get these through `options.hooks` (notify, resolveNotification,
+ * registerNotificationSource), stamped with their name, so a plugin's source
+ * ids are `<plugin>:<id>`. Core's are `core:<id>`.
+ *
+ * A failure in here is logged and swallowed: raising a notification never
+ * breaks the thing that raised it.
+ *
+ * @module services/notify
+ */
+import fs from 'fs';
+import path from 'path';
+import {randomUUID} from 'crypto';
+import {config, getConfig, saveConfig} from '../config.js';
+import {getAdapter} from './adapterRegistry.js';
+import {getEffectiveRoles} from './userRoles.js';
+
+const SLUG = 'notifications';
+export const SEVERITIES = ['info', 'success', 'warning', 'critical'];
+const RANK = {info: 0, success: 0, warning: 1, critical: 2};
+
+/** Who a source's notifications go to, as a setting. */
+export const AUDIENCES = {
+    'super-admin': {roles: ['super-admin']},
+    admins: {roles: ['super-admin', 'admin']},
+    everyone: null
+};
+export const SCHEDULES = ['boot', '15m', 'hourly', 'daily'];
+const INTERVAL_MS = {'15m': 15 * 60_000, hourly: 60 * 60_000};
+const DAILY_HOUR = 8;
+/** At most this many new notifications per source per hour - a loop cannot bury the inbox. */
+const RATE_CAP = 30;
+const CHECK_TIMEOUT_MS = 10_000;
+
+let log = console;
+
+// ---------------------------------------------------------------------------
+// Pure rules (exported for the tests)
+// ---------------------------------------------------------------------------
+
+/** A link a notification may carry: an http(s) address or an admin route (`#/…`), else null. */
+export function cleanLink(link) {
+    if (typeof link !== 'string') return null;
+    const s = link.trim();
+    if (/^https?:\/\/\S+$/i.test(s)) return s;
+    if (/^#\/[^\s]*$/.test(s)) return s;
+    return null;
+}
+
+/**
+ * May this user see a notification with this audience. None (manager pushes,
+ * everything before 0.80) is everyone who can read notifications, as before.
+ *
+ * @param {object|null|undefined} audience - {roles: string[]} | {userIds: string[]}
+ * @param {object} user - request.user: {id, role, additionalRoles}
+ */
+export function inAudience(audience, user) {
+    if (!audience || typeof audience !== 'object') return true;
+    if (Array.isArray(audience.userIds)) return audience.userIds.includes(user?.id);
+    if (Array.isArray(audience.roles)) {
+        const held = getEffectiveRoles(user || {});
+        return audience.roles.some(r => held.includes(r));
+    }
+    return true;
+}
+
+/** Is this notification live for this user now: in its audience, not expired, not dismissed. */
+export function isActiveFor(data, user, now = new Date().toISOString()) {
+    if (data.expiresAt && data.expiresAt < now) return false;
+    if (!inAudience(data.audience, user)) return false;
+    return !(Array.isArray(data.dismissedBy) && data.dismissedBy.includes(user?.id));
+}
+
+/**
+ * When a scheduled source is next due, given when it last ran.
+ *
+ * @param {string} every - '15m' | 'hourly' | 'daily' ('boot' is never "due")
+ * @param {number|null} lastRun - ms
+ * @param {Date} now
+ */
+export function isDue(every, lastRun, now = new Date()) {
+    if (every === 'boot') return false;
+    if (INTERVAL_MS[every]) return !lastRun || now.getTime() - lastRun >= INTERVAL_MS[every];
+    if (every === 'daily') {
+        const today = new Date(now);
+        today.setHours(DAILY_HOUR, 0, 0, 0);
+        // The most recent 08:00 that has passed.
+        const mark = now >= today ? today.getTime() : today.getTime() - 86_400_000;
+        return !lastRun || lastRun < mark;
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Sources and their settings
+// ---------------------------------------------------------------------------
+
+const sources = new Map();   // id -> definition
+const runs = new Map();      // id -> {lastRun, lastError, lastCount}
+
+/**
+ * Name a source (and optionally schedule it). Registering the same id again
+ * replaces it - a plugin reloaded in place does not end up with two.
+ *
+ * @param {object} def
+ * @param {string} def.id          - 'core:plugin-load', 'invoice:overdue'
+ * @param {string} [def.owner]     - 'core' or the plugin's name
+ * @param {string} [def.ownerLabel]
+ * @param {string} def.label
+ * @param {string} [def.description]
+ * @param {string} [def.severity]  - what it usually sends, for the settings list
+ * @param {boolean} [def.defaultOn=true]
+ * @param {string} [def.audience='super-admin']
+ * @param {string} [def.every]     - one of SCHEDULES; needs `check`
+ * @param {boolean} [def.atBoot]   - also run once at start-up
+ * @param {Function} [def.check]   - async ({now, notify, resolve}) => void
+ */
+export function registerNotificationSource(def) {
+    if (!def || typeof def.id !== 'string' || !def.id) throw new Error('A notification source needs an id.');
+    if (def.every && !SCHEDULES.includes(def.every)) throw new Error(`every must be one of ${SCHEDULES.join(', ')}.`);
+    if (def.every && typeof def.check !== 'function') throw new Error('A scheduled notification source needs a check function.');
+    const owner = def.owner || def.id.split(':')[0];
+    sources.set(def.id, {
+        ...def,
+        owner, ownerLabel: def.ownerLabel || (owner === 'core' ? 'System' : owner),
+        label: String(def.label || def.id), description: String(def.description || ''),
+        severity: SEVERITIES.includes(def.severity) ? def.severity : 'info',
+        defaultOn: def.defaultOn !== false,
+        audience: AUDIENCES[def.audience] !== undefined ? def.audience : 'super-admin'
+    });
+}
+
+function readSettings() {
+    try {
+        const s = getConfig('notifications');
+        return s && typeof s === 'object' && s.sources && typeof s.sources === 'object' ? s : {sources: {}};
+    } catch {
+        return {sources: {}};
+    }
+}
+
+/** A source's effective setting: {enabled, audience}. An unregistered source is on, for the Super Admins. */
+export function sourceSetting(id) {
+    const def = sources.get(id);
+    const saved = readSettings().sources[id] || {};
+    return {
+        enabled: typeof saved.enabled === 'boolean' ? saved.enabled : (def ? def.defaultOn : true),
+        audience: AUDIENCES[saved.audience] !== undefined ? saved.audience : (def?.audience || 'super-admin')
+    };
+}
+
+/** Change one source's setting (Notifications' settings, Super Admins only). */
+export function saveSourceSetting(id, {enabled, audience} = {}) {
+    const all = readSettings();
+    const current = sourceSetting(id);
+    all.sources[id] = {
+        enabled: typeof enabled === 'boolean' ? enabled : current.enabled,
+        audience: AUDIENCES[audience] !== undefined ? audience : current.audience
+    };
+    saveConfig('notifications', all);
+    return sourceSetting(id);
+}
+
+/** Every registered source with its setting and last run, for the settings screen. */
+export function listNotificationSources() {
+    return [...sources.values()]
+        .map(d => ({
+            id: d.id, owner: d.owner, ownerLabel: d.ownerLabel, label: d.label, description: d.description,
+            severity: d.severity, every: d.every || null, atBoot: Boolean(d.atBoot), defaultOn: d.defaultOn,
+            ...sourceSetting(d.id),
+            lastRun: runs.get(d.id)?.lastRun ? new Date(runs.get(d.id).lastRun).toISOString() : null,
+            lastError: runs.get(d.id)?.lastError || null
+        }))
+        // System first, then each plugin by name; within one owner, by label.
+        .sort((a, b) => (Number(b.owner === 'core') - Number(a.owner === 'core'))
+            || a.ownerLabel.localeCompare(b.ownerLabel) || a.label.localeCompare(b.label));
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+// One write at a time: on file storage each insert is a read-modify-write of
+// the whole collection, and two at once lose one.
+let chain = Promise.resolve();
+const serial = (fn) => { const next = chain.then(fn, fn); chain = next.catch(() => {}); return next; };
+
+// Before the server is ready (collections seeded, plugins loaded) notify() queues.
+let ready = false;
+const early = [];
+
+const sent = new Map();      // source -> timestamps in the last hour
+
+function underCap(source, now = Date.now()) {
+    const recent = (sent.get(source) || []).filter(t => now - t < 3_600_000);
+    if (recent.length >= RATE_CAP) { sent.set(source, recent); return false; }
+    recent.push(now);
+    sent.set(source, recent);
+    return true;
+}
+
+/** The payload as stored, or null (with the reason) when it is not a notification. */
+export function normalisePayload(p, setting = {audience: 'super-admin'}) {
+    if (!p || typeof p !== 'object') return {error: 'no payload'};
+    const title = typeof p.title === 'string' ? p.title.trim().slice(0, 200) : '';
+    if (!title) return {error: 'title is required'};
+    const expiresAt = p.expiresAt && !Number.isNaN(Date.parse(p.expiresAt)) ? new Date(p.expiresAt).toISOString() : null;
+    const audience = p.audience && Array.isArray(p.audience.userIds)
+        ? {userIds: p.audience.userIds.map(String)}
+        : AUDIENCES[setting.audience] ?? null;
+    return {
+        data: {
+            title,
+            body: typeof p.body === 'string' ? p.body.trim().slice(0, 4000) : '',
+            severity: SEVERITIES.includes(p.severity) ? p.severity : 'info',
+            source: String(p.source || 'core:general'),
+            sourceLabel: typeof p.sourceLabel === 'string' ? p.sourceLabel : undefined,
+            link: cleanLink(p.link),
+            dedupeKey: typeof p.dedupeKey === 'string' && p.dedupeKey ? p.dedupeKey.slice(0, 200) : null,
+            audience,
+            expiresAt
+        }
+    };
+}
+
+async function write(p) {
+    const setting = sourceSetting(String(p.source || 'core:general'));
+    if (!setting.enabled) return null;
+    const {data, error} = normalisePayload(p, setting);
+    if (error) { log.warn?.(`[notify] Not raised (${error}) from ${p?.source || 'unknown'}.`); return null; }
+    if (data.sourceLabel === undefined) data.sourceLabel = sources.get(data.source)?.ownerLabel || (data.source.startsWith('core:') ? 'System' : data.source.split(':')[0]);
+
+    const adapter = await getAdapter(SLUG);
+    const now = new Date().toISOString();
+
+    if (data.dedupeKey) {
+        const existing = (await adapter.all(SLUG)).find(e => e?.data?.dedupeKey === data.dedupeKey
+            && e.data.source === data.source && !(e.data.expiresAt && e.data.expiresAt <= now));
+        if (existing) {
+            // Still going on: say it again in place. Worse than before, it is news again.
+            const worse = RANK[data.severity] > RANK[existing.data.severity];
+            const merged = {...existing.data, ...data, createdAt: worse ? now : existing.data.createdAt,
+                readBy: worse ? [] : existing.data.readBy || [], dismissedBy: worse ? [] : existing.data.dismissedBy || []};
+            return adapter.update(SLUG, existing.id, {...existing, data: merged, meta: {...(existing.meta || {}), updatedAt: now}});
+        }
+    }
+
+    if (!underCap(data.source)) {
+        log.warn?.(`[notify] ${data.source} has sent ${RATE_CAP} in the last hour - holding the rest.`);
+        return null;
+    }
+    return adapter.insert(SLUG, {
+        id: randomUUID(),
+        data: {...data, createdAt: now, readBy: [], dismissedBy: []},
+        meta: {createdAt: now, updatedAt: now, source: data.source}
+    });
+}
+
+/**
+ * Raise a notification. Never throws; resolves to the stored entry, or null
+ * when the source is switched off, capped, or the payload is not usable.
+ *
+ * @param {object} payload
+ * @returns {Promise<object|null>}
+ */
+export function notify(payload) {
+    if (!ready) { early.push(payload); return Promise.resolve(null); }
+    return serial(() => write(payload)).catch(err => {
+        log.warn?.(`[notify] Could not raise "${payload?.title}": ${err.message}`);
+        return null;
+    });
+}
+
+/**
+ * The cause is gone: end every live notification with this key (from this
+ * source, when one is given). Never throws.
+ *
+ * @param {string} dedupeKey
+ * @param {string} [source]
+ * @returns {Promise<number>} how many were ended
+ */
+export function resolveNotification(dedupeKey, source) {
+    if (!ready || !dedupeKey) return Promise.resolve(0);
+    return serial(async () => {
+        const adapter = await getAdapter(SLUG);
+        const now = new Date().toISOString();
+        let n = 0;
+        for (const e of await adapter.all(SLUG)) {
+            const d = e?.data;
+            if (!d || d.dedupeKey !== dedupeKey || (source && d.source !== source)) continue;
+            if (d.expiresAt && d.expiresAt <= now) continue;
+            await adapter.update(SLUG, e.id, {...e, data: {...d, expiresAt: now}, meta: {...(e.meta || {}), updatedAt: now}});
+            n++;
+        }
+        return n;
+    }).catch(err => { log.warn?.(`[notify] Could not resolve "${dedupeKey}": ${err.message}`); return 0; });
+}
+
+/**
+ * The same three, bound to one owner - what a plugin is handed. Its ids are
+ * `<owner>:<id>`, and it can only resolve its own.
+ *
+ * @param {string} owner
+ * @param {string} [ownerLabel]
+ */
+export function notifierFor(owner, ownerLabel = owner) {
+    const id = (s) => `${owner}:${String(s || 'general').replace(/^[^:]*:/, '')}`;
+    return {
+        notify: (p = {}) => notify({...p, source: id(p.source), sourceLabel: ownerLabel}),
+        resolveNotification: (key, source) => resolveNotification(key, source ? id(source) : undefined),
+        registerNotificationSource: (def = {}) => registerNotificationSource({...def, id: id(def.id), owner, ownerLabel})
+    };
+}
+
+// ---------------------------------------------------------------------------
+// The ticker
+// ---------------------------------------------------------------------------
+
+function stateFile() {
+    return path.join(path.dirname(path.resolve(config.content.collectionsDir)), '.notification-sources.json');
+}
+function readState() {
+    try { return JSON.parse(fs.readFileSync(stateFile(), 'utf8')) || {}; } catch { return {}; }
+}
+function writeState(state) {
+    try { fs.writeFileSync(stateFile(), JSON.stringify(state, null, 2) + '\n'); } catch { /* next start runs it again */ }
+}
+
+/**
+ * Run one source's check now (the ticker, or "Run now" in settings).
+ *
+ * @param {string} id
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function runSource(id) {
+    const def = sources.get(id);
+    if (!def?.check) return {ok: false, error: 'not a scheduled source'};
+    const run = runs.get(id) || {};
+    run.lastRun = Date.now();
+    runs.set(id, run);
+    if (def.every === 'daily') writeState({...readState(), [id]: run.lastRun});
+    if (!sourceSetting(id).enabled) { run.lastError = null; return {ok: true, skipped: true}; }
+    const ctx = {
+        now: new Date(),
+        notify: (p = {}) => notify({...p, source: id, sourceLabel: def.ownerLabel}),
+        resolve: (key) => resolveNotification(key, id)
+    };
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(() => def.check(ctx)),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`took over ${CHECK_TIMEOUT_MS / 1000}s`)), CHECK_TIMEOUT_MS); })
+        ]);
+        run.lastError = null;
+        return {ok: true};
+    } catch (err) {
+        run.lastError = String(err?.message || err);
+        log.warn?.(`[notify] Source ${id} failed: ${run.lastError}`);
+        return {ok: false, error: run.lastError};
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+let ticker = null;
+
+/**
+ * Start raising: flush what was raised during start-up, run the boot checks,
+ * then look for due sources every minute. Called once the server is up.
+ *
+ * @param {{log?: object}} [opts]
+ * @returns {Function} stop
+ */
+export function startNotifications({log: logger} = {}) {
+    if (logger) log = logger;
+    ready = true;
+    for (const p of early.splice(0)) notify(p);
+    const saved = readState();
+    for (const [id, at] of Object.entries(saved)) runs.set(id, {...(runs.get(id) || {}), lastRun: at});
+
+    const tick = async (boot = false) => {
+        const now = new Date();
+        for (const def of [...sources.values()]) {
+            if (!def.check) continue;
+            const due = boot ? (def.every === 'boot' || def.atBoot || isDue(def.every, runs.get(def.id)?.lastRun, now))
+                : isDue(def.every, runs.get(def.id)?.lastRun, now);
+            if (due) await runSource(def.id);
+        }
+    };
+    // Boot checks a little after start, when the first requests are served.
+    const first = setTimeout(() => tick(true), 15_000);
+    ticker = setInterval(() => tick(false), 60_000);
+    first.unref?.();
+    ticker.unref?.();
+    return () => { clearTimeout(first); clearInterval(ticker); ticker = null; };
+}
+
+/** Test-only: forget everything. */
+export function _reset() {
+    sources.clear(); runs.clear(); sent.clear(); early.length = 0; ready = false;
+    if (ticker) clearInterval(ticker);
+    ticker = null;
+}
+/** Test-only: be ready without the ticker. */
+export function _ready() { ready = true; }

package/server/services/plugins.js

@@ -30,6 +30,7 @@ import {
 import {registerPluginResource, unregisterPluginResourcesByPlugin} from './permissionRegistry.js';
 import {registerThemeProvider} from './themeSettings.js';
 import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
+import {notifierFor} from './notify.js';
 import {createCollection, getCollection} from './collections.js';
 import * as defaultRolesService from './roles.js';
 import {normaliseAdminScope} from './roles.js';
@@ -482,7 +483,10 @@ export async function registerPlugins(fastify) {
                   registerCalendarSource: (source) => registerCalendarSource({...source, owner: manifest.name}),
                   getCalendarSources,
                   registerRelatedItems: (kind, provider) => registerRelatedItems(kind, {...provider, owner: manifest.name}),
-                  on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name)},
+                  on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name),
+                  // Notifications (0.80) - notify, resolveNotification, registerNotificationSource,
+                  // stamped with the plugin's name (its source ids are `<plugin>:<id>`).
+                  ...notifierFor(manifest.name, manifest.displayName || manifest.name)},
               settings,
               config: {}
           });
@@ -1079,7 +1083,7 @@ export async function runLifecycleHook(name, hook, fastify) {
         }
 
         if (typeof mod[hook] === 'function') {
-            await mod[hook]({ fastify, services, hooks: pluginRoleHooks(name) });
+            await mod[hook]({ fastify, services, hooks: {...pluginRoleHooks(name), ...notifierFor(name)} });
         }
     } catch (err) {
         fastify.log.error(`Plugin "${name}" lifecycle hook "${hook}" failed: ${err.message}`);

package/server/services/sidebarBadges.js

@@ -35,3 +35,36 @@ export function clip(text, max = 60) {
     const cut = s.slice(0, max - 1);
     return `${cut.slice(0, cut.lastIndexOf(' ') > max * 0.6 ? cut.lastIndexOf(' ') : cut.length)}…`;
 }
+
+/**
+ * My Profile's sidebar badge: the details of yours still empty - your name, and
+ * each extra profile field an administrator added (the user-profiles
+ * collection). None missing is no badge. Plain text throughout.
+ *
+ * @param {object} user
+ * @param {object} profile - this user's profile data
+ * @param {object[]} fields - the user-profiles collection's fields
+ */
+export function profileBadge(user = {}, profile = {}, fields = []) {
+    const empty = (v) => v === undefined || v === null || (typeof v === 'string' && !v.trim()) || (Array.isArray(v) && !v.length);
+    const missing = [
+        ...(empty(user.name) ? ['Name'] : []),
+        ...fields.filter(f => f && f.name && f.type !== 'hidden' && empty(profile[f.name])).map(f => String(f.label || f.name))
+    ];
+    const n = missing.length;
+    const shown = fields.filter(f => f && f.name && f.type !== 'hidden').length + 1;
+    return {
+        count: n,
+        label: n ? `${n} profile detail${n === 1 ? '' : 's'} not filled in` : 'Your profile is complete',
+        tone: 'info',
+        details: {
+            title: 'My Profile',
+            rows: [
+                {label: 'Filled in', value: `${shown - n} of ${shown}`},
+                {label: 'Role', value: String(user.role || '')}
+            ],
+            items: missing.slice(0, 8).map(text => ({text, meta: 'empty'})),
+            empty: 'Every detail is filled in.'
+        }
+    };
+}