domma-cms 0.16.0 → 0.17.0

package/plugins/analytics/plugin.js

@@ -22,6 +22,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LIFETIME_FILE = path.join(__dirname, 'lifetime.json');
 const DAILY_FILE = path.join(__dirname, 'daily.json');
 const LEGACY_FILE = path.join(__dirname, 'stats.json');
+const JOURNEYS_FILE = path.join(__dirname, 'journeys.json');
+const JOURNEY_DAILY_CAP = 5000;
+const REALTIME_WINDOW_MS = 5 * 60 * 1000;
 
 async function readJson(file, fallback) {
     try {
@@ -40,23 +43,30 @@ async function writeJson(file, data) {
 /**
  * One-shot migration from the legacy flat stats.json.
  * Preserves existing totals as lifetime numbers; daily history starts empty.
+ * Also seeds journeys.json if missing.
  */
 async function migrateLegacy() {
+    let lifetimeExists = false;
     try {
         await fs.access(LIFETIME_FILE);
-        return; // already migrated
-    } catch {
-        // fall through
-    }
-    const legacy = await readJson(LEGACY_FILE, null);
-    if (legacy && typeof legacy === 'object') {
-        await writeJson(LIFETIME_FILE, legacy);
-        await writeJson(DAILY_FILE, {});
-        // keep stats.json on disk as a backup; the next reset will wipe it
-    } else {
-        await writeJson(LIFETIME_FILE, {});
+        lifetimeExists = true;
+    } catch { /* not migrated */ }
+
+    if (!lifetimeExists) {
+        const legacy = await readJson(LEGACY_FILE, null);
+        if (legacy && typeof legacy === 'object') {
+            await writeJson(LIFETIME_FILE, legacy);
+        } else {
+            await writeJson(LIFETIME_FILE, {});
+        }
         await writeJson(DAILY_FILE, {});
     }
+
+    try {
+        await fs.access(JOURNEYS_FILE);
+    } catch {
+        await writeJson(JOURNEYS_FILE, {});
+    }
 }
 
 function todayKey(date = new Date()) {
@@ -131,14 +141,164 @@ function escapeCsvCell(value) {
     return str;
 }
 
+function eventsInRange(journeys, start, end) {
+    const startMs = start.getTime();
+    const endMs = end.getTime();
+    const out = [];
+    for (const [day, events] of Object.entries(journeys)) {
+        const dayMs = new Date(day + 'T00:00:00Z').getTime();
+        if (dayMs < startMs || dayMs > endMs) continue;
+        for (const ev of events) out.push(ev);
+    }
+    return out;
+}
+
+function groupBySession(events) {
+    const sessions = new Map();
+    for (const ev of events) {
+        if (!sessions.has(ev.sid)) sessions.set(ev.sid, []);
+        sessions.get(ev.sid).push(ev);
+    }
+    for (const arr of sessions.values()) arr.sort((a, b) => a.t - b.t);
+    return sessions;
+}
+
+function aggregateJourneys(events) {
+    const sessions = groupBySession(events);
+    const entry = new Map();
+    const exit = new Map();
+    const paths = new Map(); // key: '\x00'-joined, value: { from, to, count }
+    let bouncedSessions = 0;
+
+    for (const arr of sessions.values()) {
+        if (arr.length === 0) continue;
+        entry.set(arr[0].url, (entry.get(arr[0].url) || 0) + 1);
+        exit.set(arr[arr.length - 1].url, (exit.get(arr[arr.length - 1].url) || 0) + 1);
+        if (arr.length === 1) bouncedSessions += 1;
+        for (let i = 0; i < arr.length - 1; i += 1) {
+            const from = arr[i].url;
+            const to = arr[i + 1].url;
+            const key = from + '\x00' + to; // NUL is invalid in URL pathnames, so unambiguous
+            const existing = paths.get(key);
+            if (existing) {
+                existing.count += 1;
+            } else {
+                paths.set(key, { from, to, count: 1 });
+            }
+        }
+    }
+
+    const toSorted = (m) => Array.from(m.entries())
+        .map(([url, count]) => ({ url, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+
+    const pathsSorted = Array.from(paths.values())
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+
+    const totalSessions = sessions.size;
+    return {
+        entry: toSorted(entry),
+        exit: toSorted(exit),
+        paths: pathsSorted,
+        bounceRate: totalSessions === 0 ? 0 : +(bouncedSessions / totalSessions).toFixed(3),
+        totalSessions
+    };
+}
+
+function detectSpikes(daily, now = new Date()) {
+    const todayStr = todayKey(now);
+    const currentHour = now.getUTCHours();
+
+    // Approximation: distribute today's hits evenly across elapsed hours.
+    const todayUrls = daily[todayStr] || {};
+    const elapsedHours = Math.max(1, currentHour + 1);
+
+    const flagged = [];
+    for (const [url, totalToday] of Object.entries(todayUrls)) {
+        const currentHits = totalToday / elapsedHours;
+
+        // Baseline: previous 7 days' same-hour share (assume 24-hour spread)
+        const samples = [];
+        for (let i = 1; i <= 7; i += 1) {
+            const prev = new Date(now);
+            prev.setUTCDate(prev.getUTCDate() - i);
+            const key = todayKey(prev);
+            const sample = (daily[key] && daily[key][url]) ? daily[key][url] / 24 : 0;
+            samples.push(sample);
+        }
+        const mean = samples.reduce((a, b) => a + b, 0) / samples.length;
+        const variance = samples.reduce((acc, x) => acc + (x - mean) * (x - mean), 0) / samples.length;
+        const stddev = Math.sqrt(variance);
+
+        if (currentHits >= 5 && currentHits > mean + 2 * stddev && mean > 0) {
+            flagged.push({
+                url,
+                hits: Math.round(currentHits),
+                baseline: Math.round(mean),
+                ratio: +(currentHits / Math.max(mean, 0.5)).toFixed(2)
+            });
+        }
+    }
+
+    return flagged.sort((a, b) => b.ratio - a.ratio).slice(0, 5);
+}
+
+function shouldRecordJourney(dayEntries, cap = JOURNEY_DAILY_CAP) {
+    return Array.isArray(dayEntries) && dayEntries.length < cap;
+}
+
 export default async function analyticsPlugin(fastify, options) {
     const { authenticate, requireAdmin } = options.auth;
     const settings = options.settings || {};
 
     await migrateLegacy();
 
+    fastify.decorate('analytics', {
+        async getStats({ range = '7d', from, to } = {}) {
+            const dates = rangeToDates(range, from, to);
+            const [lifetime, daily] = await Promise.all([
+                readJson(LIFETIME_FILE, {}),
+                readJson(DAILY_FILE, {})
+            ]);
+            let totals; let total;
+            if (!dates) {
+                totals = lifetime;
+                total = Object.values(lifetime).reduce((a, n) => a + n, 0);
+            } else {
+                const agg = aggregateDaily(daily, dates.start, dates.end);
+                totals = agg.totals;
+                total = agg.total;
+            }
+            const top = Object.entries(totals)
+                .map(([url, hits]) => ({ url, hits }))
+                .sort((a, b) => b.hits - a.hits);
+            return { total, top, lifetimeTotal: Object.values(lifetime).reduce((a, n) => a + n, 0) };
+        },
+        async getDaily() { return readJson(DAILY_FILE, {}); },
+        async getJourneys({ range = '7d', from, to } = {}) {
+            const dates = rangeToDates(range === 'all' ? '30d' : range, from, to);
+            const journeys = await readJson(JOURNEYS_FILE, {});
+            return aggregateJourneys(eventsInRange(journeys, dates.start, dates.end));
+        },
+        async getRealtime() {
+            const journeys = await readJson(JOURNEYS_FILE, {});
+            const today = todayKey();
+            const events = journeys[today] || [];
+            const cutoff = Date.now() - REALTIME_WINDOW_MS;
+            const sids = new Set();
+            for (const ev of events) if (ev.t >= cutoff) sids.add(ev.sid);
+            return { activeSessions: sids.size, windowMinutes: REALTIME_WINDOW_MS / 60000 };
+        },
+        async getSpikes() {
+            const daily = await readJson(DAILY_FILE, {});
+            return { items: detectSpikes(daily) };
+        }
+    });
+
     fastify.post('/hit', async (request, reply) => {
-        const { url, dnt } = request.body || {};
+        const { url, dnt, sid, ref } = request.body || {};
         if (!url || typeof url !== 'string') {
             return reply.status(400).send({ error: 'url is required' });
         }
@@ -159,14 +319,31 @@ export default async function analyticsPlugin(fastify, options) {
         }
 
         const today = todayKey();
-        const [lifetime, daily] = await Promise.all([
+        const [lifetime, daily, journeys] = await Promise.all([
             readJson(LIFETIME_FILE, {}),
-            readJson(DAILY_FILE, {})
+            readJson(DAILY_FILE, {}),
+            readJson(JOURNEYS_FILE, {})
         ]);
+
         lifetime[normalised] = (lifetime[normalised] || 0) + 1;
         if (!daily[today]) daily[today] = {};
         daily[today][normalised] = (daily[today][normalised] || 0) + 1;
-        await Promise.all([writeJson(LIFETIME_FILE, lifetime), writeJson(DAILY_FILE, daily)]);
+
+        // Journey event — only if sid is a string of reasonable shape, and under cap
+        const safeSid = typeof sid === 'string' && sid.length > 0 && sid.length <= 64 ? sid : null;
+        const safeRef = typeof ref === 'string' && ref.length <= 512 ? ref : '';
+        if (safeSid) {
+            if (!journeys[today]) journeys[today] = [];
+            if (shouldRecordJourney(journeys[today])) {
+                journeys[today].push({ sid: safeSid, t: Date.now(), url: normalised, ref: safeRef });
+            }
+        }
+
+        await Promise.all([
+            writeJson(LIFETIME_FILE, lifetime),
+            writeJson(DAILY_FILE, daily),
+            writeJson(JOURNEYS_FILE, journeys)
+        ]);
         return { ok: true };
     });
 
@@ -212,6 +389,37 @@ export default async function analyticsPlugin(fastify, options) {
         return { series: buildSeries(daily, dates.start, dates.end) };
     });
 
+    fastify.get('/journeys', { preHandler: [authenticate, requireAdmin] }, async (request) => {
+        const { range = '7d', from, to } = request.query || {};
+        const dates = rangeToDates(range === 'all' ? '30d' : range, from, to);
+        const journeys = await readJson(JOURNEYS_FILE, {});
+        const events = eventsInRange(journeys, dates.start, dates.end);
+        const agg = aggregateJourneys(events);
+        return {
+            range,
+            from: todayKey(dates.start),
+            to: todayKey(dates.end),
+            ...agg
+        };
+    });
+
+    fastify.get('/realtime', { preHandler: [authenticate, requireAdmin] }, async () => {
+        const journeys = await readJson(JOURNEYS_FILE, {});
+        const today = todayKey();
+        const events = journeys[today] || [];
+        const cutoff = Date.now() - REALTIME_WINDOW_MS;
+        const sids = new Set();
+        for (const ev of events) {
+            if (ev.t >= cutoff) sids.add(ev.sid);
+        }
+        return { activeSessions: sids.size, windowMinutes: REALTIME_WINDOW_MS / 60000 };
+    });
+
+    fastify.get('/spikes', { preHandler: [authenticate, requireAdmin] }, async () => {
+        const daily = await readJson(DAILY_FILE, {});
+        return { items: detectSpikes(daily) };
+    });
+
     fastify.get('/export.csv', { preHandler: [authenticate, requireAdmin] }, async (request, reply) => {
         const { range = '30d', from, to } = request.query || {};
         const dates = rangeToDates(range, from, to);
@@ -236,7 +444,11 @@ export default async function analyticsPlugin(fastify, options) {
     });
 
     fastify.delete('/stats', { preHandler: [authenticate, requireAdmin] }, async () => {
-        await Promise.all([writeJson(LIFETIME_FILE, {}), writeJson(DAILY_FILE, {})]);
+        await Promise.all([
+            writeJson(LIFETIME_FILE, {}),
+            writeJson(DAILY_FILE, {}),
+            writeJson(JOURNEYS_FILE, {})
+        ]);
         try {
             await fs.unlink(LEGACY_FILE);
         } catch {
@@ -245,3 +457,6 @@ export default async function analyticsPlugin(fastify, options) {
         return { ok: true };
     });
 }
+
+export { aggregateJourneys, detectSpikes, shouldRecordJourney };
+

package/plugins/analytics/public/inject-body.html

@@ -10,6 +10,21 @@
 
     var url = window.location.pathname;
 
+    // Session-scoped anonymous ID — clears with the tab. Cookie-less.
+    var sid = '';
+    try {
+        sid = sessionStorage.getItem('dm_sid') || '';
+        if (!sid) {
+            sid = (crypto && crypto.randomUUID)
+                ? crypto.randomUUID()
+                : (Date.now().toString(36) + Math.random().toString(36).slice(2, 10));
+            sessionStorage.setItem('dm_sid', sid);
+        }
+    } catch (e) {
+        // sessionStorage unavailable — proceed without sid
+    }
+
+    // Session dedup (one hit per URL per session)
     try {
         var key = 'dm_analytics_seen';
         var seen = sessionStorage.getItem(key);
@@ -18,14 +33,23 @@
         list.push(url);
         sessionStorage.setItem(key, list.join('|'));
     } catch (e) {
-        // sessionStorage unavailable (e.g. private mode) — record anyway
+        // proceed anyway
     }
 
+    // Strip query/fragment from referrer; only keep same-origin or external origin+path
+    var ref = '';
+    try {
+        if (document.referrer) {
+            var r = new URL(document.referrer);
+            ref = r.origin === window.location.origin ? r.pathname : (r.origin + r.pathname);
+        }
+    } catch (e) { /* ignore */ }
+
     fetch('/api/plugins/analytics/hit', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         keepalive: true,
-        body: JSON.stringify({ url: url })
+        body: JSON.stringify({ url: url, sid: sid, ref: ref })
     }).catch(function () { /* silent */ });
 })();
 </script>

package/server/routes/api/dashboard.js

@@ -0,0 +1,239 @@
+/**
+ * Dashboard API
+ * Aggregates traffic, journeys, spikes, health, and activity for the admin dashboard.
+ *
+ * GET /api/dashboard/summary           full payload
+ * GET /api/dashboard/summary?lite=1    KPI strip + spikes + health.status only
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin} from '../../middleware/auth.js';
+import {getHealth} from '../../services/health.js';
+import {listVersions} from '../../services/versions.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+
+const ACTIVITY_LIMIT         = 10;
+const VERSIONS_PER_PAGE      = 3;
+const ENTRIES_PER_COLLECTION = 3;
+
+/**
+ * @param {Date} [d]
+ * @returns {string}
+ */
+function todayKey(d = new Date()) {
+    return d.toISOString().slice(0, 10);
+}
+
+/**
+ * @param {number} n
+ * @returns {string}
+ */
+function isoDaysAgo(n) {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    d.setUTCDate(d.getUTCDate() - n);
+    return todayKey(d);
+}
+
+/**
+ * @param {object} daily
+ * @param {string} key
+ * @returns {number}
+ */
+function sumDay(daily, key) {
+    return Object.values(daily[key] || {}).reduce((a, n) => a + n, 0);
+}
+
+/**
+ * @param {object} daily
+ * @param {string} fromKey
+ * @param {string} toKey
+ * @returns {number}
+ */
+function sumRange(daily, fromKey, toKey) {
+    let total = 0;
+    for (const [day, urls] of Object.entries(daily)) {
+        if (day < fromKey || day > toKey) continue;
+        for (const n of Object.values(urls)) total += n;
+    }
+    return total;
+}
+
+/**
+ * Build the top-pages widget data, including a per-day sparkline and a
+ * percentage delta versus the previous comparable window.
+ *
+ * @param {object} daily
+ * @param {number} [days]
+ * @returns {Array<{url: string, hits: number, deltaPct: number|null, spark: number[]}>}
+ */
+function buildTopPages(daily, days = 7) {
+    const totals = {};
+    const perDay = {};
+    for (let i = days - 1; i >= 0; i -= 1) {
+        const k = isoDaysAgo(i);
+        for (const [url, n] of Object.entries(daily[k] || {})) {
+            totals[url] = (totals[url] || 0) + n;
+            if (!perDay[url]) perDay[url] = new Array(days).fill(0);
+            perDay[url][days - 1 - i] = n;
+        }
+    }
+    const prevTotals = {};
+    for (let i = 2 * days - 1; i >= days; i -= 1) {
+        const k = isoDaysAgo(i);
+        for (const [url, n] of Object.entries(daily[k] || {})) {
+            prevTotals[url] = (prevTotals[url] || 0) + n;
+        }
+    }
+    return Object.entries(totals)
+        .map(([url, hits]) => {
+            const prev = prevTotals[url] || 0;
+            const deltaPct = prev === 0 ? null : +(((hits - prev) / prev) * 100).toFixed(1);
+            return { url, hits, deltaPct, spark: perDay[url] };
+        })
+        .sort((a, b) => b.hits - a.hits)
+        .slice(0, 5);
+}
+
+/**
+ * Recent activity feed — combines page version events with recent collection
+ * entries (form submissions). Returns at most 10 items, newest first.
+ *
+ * @returns {Promise<Array<object>>}
+ */
+async function buildActivity() {
+    const items = [];
+
+    // Versions — read each page's _meta.json via the service so the schema
+    // stays in one place. listVersions returns newest-first.
+    const versionsDir = path.join(ROOT, 'content', 'versions');
+    try {
+        const dirs = await fs.readdir(versionsDir, { withFileTypes: true });
+        for (const d of dirs) {
+            if (!d.isDirectory()) continue;
+            const urlPath = '/' + (d.name === '_index' ? '' : d.name);
+            let versions = [];
+            try { versions = await listVersions(urlPath); }
+            catch { continue; }
+            for (const v of versions.slice(0, VERSIONS_PER_PAGE)) {
+                items.push({
+                    type: v.type === 'manual' ? 'publish' : 'edit',
+                    at: v.createdAt,
+                    actor: v.author || 'unknown',
+                    target: urlPath
+                });
+            }
+        }
+    } catch { /* no versions dir */ }
+
+    // Collection entries — each slug has a single data.json with an array of
+    // entries. Take the newest ENTRIES_PER_COLLECTION by meta.createdAt.
+    const collectionsDir = path.join(ROOT, 'content', 'collections');
+    try {
+        const slugs = await fs.readdir(collectionsDir, { withFileTypes: true });
+        for (const slug of slugs) {
+            if (!slug.isDirectory()) continue;
+            const dataFile = path.join(collectionsDir, slug.name, 'data.json');
+            let entries = [];
+            try { entries = JSON.parse(await fs.readFile(dataFile, 'utf8')); }
+            catch { continue; }
+            if (!Array.isArray(entries)) continue;
+
+            const sorted = entries
+                .filter(e => e && e.meta && e.meta.createdAt)
+                .sort((a, b) => (b.meta.createdAt || '').localeCompare(a.meta.createdAt || ''))
+                .slice(0, ENTRIES_PER_COLLECTION);
+
+            for (const e of sorted) {
+                items.push({
+                    type: 'form',
+                    at: e.meta.createdAt,
+                    form: slug.name
+                });
+            }
+        }
+    } catch { /* no collections dir */ }
+
+    return items
+        .filter(i => i.at)
+        .sort((a, b) => (b.at || '').localeCompare(a.at || ''))
+        .slice(0, ACTIVITY_LIMIT);
+}
+
+/**
+ * Register the dashboard routes.
+ *
+ * Auth middlewares are accepted as options so tests can supply no-ops without
+ * needing to register `@fastify/jwt` on the test instance. In production the
+ * defaults are the real `authenticate` / `requireAdmin` from middleware/auth.js.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requireAdmin?: Function}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function dashboardRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requireAdmin = opts.requireAdmin || defaultRequireAdmin;
+    const guard = { preHandler: [authenticate, requireAdmin] };
+
+    fastify.get('/dashboard/summary', guard, async (request) => {
+        const lite = request.query.lite === '1' || request.query.lite === 'true';
+        const warnings = [];
+        const safe = async (label, fn) => {
+            try { return await fn(); }
+            catch (e) {
+                // Strip absolute paths from error messages so we don't disclose deployment layout.
+                const msg = String(e.message || e).replace(/(\/|[A-Za-z]:\\)[^\s'"]+/g, '<path>');
+                warnings.push(`${label}: ${msg}`);
+                return null;
+            }
+        };
+
+        const analytics = fastify.analytics;
+        const daily = analytics ? (await safe('analytics.daily', () => analytics.getDaily())) || {} : {};
+
+        const today = todayKey();
+        const yesterday = isoDaysAgo(1);
+        const todayHits = sumDay(daily, today);
+        const yesterdayHits = sumDay(daily, yesterday);
+        const deltaPct = yesterdayHits === 0
+            ? null
+            : +(((todayHits - yesterdayHits) / yesterdayHits) * 100).toFixed(1);
+        const traffic = {
+            today: todayHits,
+            yesterday: yesterdayHits,
+            deltaPct,
+            weekToDate: sumRange(daily, isoDaysAgo(6), today),
+            previousWeek: sumRange(daily, isoDaysAgo(13), isoDaysAgo(7))
+        };
+
+        const realtime = analytics
+            ? (await safe('analytics.realtime', () => analytics.getRealtime())) || { activeSessions: 0 }
+            : { activeSessions: 0 };
+        const spikes = analytics
+            ? ((await safe('analytics.spikes', () => analytics.getSpikes())) || { items: [] }).items
+            : [];
+        const health = await safe('health', () => getHealth()) || { status: 'ok', checks: [] };
+
+        if (lite) {
+            return {
+                traffic: { today: traffic.today, yesterday: traffic.yesterday, deltaPct: traffic.deltaPct },
+                realtime,
+                spikes,
+                health: { status: health.status },
+                warnings
+            };
+        }
+
+        const topPages = buildTopPages(daily);
+        const journeys = analytics
+            ? (await safe('analytics.journeys', () => analytics.getJourneys({ range: '7d' }))) || null
+            : null;
+        const activity = (await safe('activity', () => buildActivity())) || [];
+
+        return { traffic, topPages, journeys, spikes, realtime, health, activity, warnings };
+    });
+}

package/server/server.js

@@ -249,6 +249,7 @@ const {componentsRoutes} = await import('./routes/api/components.js');
 const {versionsRoutes} = await import('./routes/api/versions.js');
 const {effectsRoutes} = await import('./routes/api/effects.js');
 const {notificationsRoutes} = await import('./routes/api/notifications.js');
+const {dashboardRoutes} = await import('./routes/api/dashboard.js');
 
 await app.register(pagesRoutes,       { prefix: '/api' });
 await app.register(settingsRoutes,    { prefix: '/api' });
@@ -267,6 +268,7 @@ await app.register(componentsRoutes, {prefix: '/api'});
 await app.register(versionsRoutes, {prefix: '/api'});
 await app.register(effectsRoutes, {prefix: '/api'});
 await app.register(notificationsRoutes, {prefix: '/api'});
+await app.register(dashboardRoutes, {prefix: '/api'});
 
 // ---------------------------------------------------------------------------
 // CMS Plugins (server-side Fastify plugins from plugins/ directory)