domma-cms 0.55.1 → 0.69.3

package/{plugins/analytics/plugin.js → server/routes/api/analytics.js}

@@ -1,35 +1,60 @@
 /**
- * Analytics Plugin - Server
- * Tracks page hits with per-day buckets so we can chart trends and
- * filter by time range.
+ * Analytics - page-hit counters, trends and journeys.
  *
- * Storage:
- *   lifetime.json  { "/url": totalHits }
- *   daily.json     { "YYYY-MM-DD": { "/url": hits } }
+ * Was the `analytics` plugin until 0.67.0, where it was a CORE_PLUGINS member:
+ * always loaded, never switchable off. A feature nobody may turn off has no
+ * business being listed as an add-on, so it is simply part of the CMS now.
  *
- * Endpoints (mounted at /api/plugins/analytics):
- *   POST   /hit            public  record a hit { url, dnt }
+ * **Counters live in `content/analytics/`, not under plugins/.** They are real
+ * traffic history that cannot be regenerated, and the retirement migration
+ * deletes the plugin directory - so the data had to move out from under it. The
+ * migration copies and verifies before anything is removed.
+ *
+ * This is the CLIENT-SIDE beacon's store: a browser posts to /api/analytics/hit,
+ * which means bots, blocked scripts and Do-Not-Track visitors are absent by
+ * design. `analytics-pro` counts the same site server-side from an onRequest
+ * hook and will always report more. They are different instruments, not two
+ * versions of one, which is why neither supersedes the other.
+ *
+ * Endpoints (mounted at /api/analytics):
+ *   POST   /hit            public  record a hit { url, sid, ref }
  *   GET    /stats          admin   summary + top pages (?range=today|7d|30d|90d|all|custom&from=&to=)
  *   GET    /series         admin   per-day totals series (?days=N or ?from=&to=)
+ *   GET    /journeys       admin   entry/exit/path aggregates
+ *   GET    /realtime       admin   sessions active in the last 5 minutes
+ *   GET    /spikes         admin   days that stand out from the trend
  *   GET    /export.csv     admin   CSV export of top pages for the active range
- *   DELETE /stats          admin   reset all stats
+ *   DELETE /stats          admin   reset all counters
  */
+import {clip, plural} from '../../services/sidebarBadges.js';
 import fs from 'fs/promises';
 import path from 'path';
-import {fileURLToPath} from 'url';
+import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin} from '../../middleware/auth.js';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Where the counters live. Resolved per call rather than frozen at import so a
+ * test can run against a temporary install, the way the migrations do.
+ */
+export function analyticsDir() {
+    return path.resolve('content', 'analytics');
+}
 
-// Runtime counters live under data/ - the carve-out that BOTH update paths
-// preserve (siteCmsUpdater's copyPlugin backs up data/; `domma-cms update`
-// keeps 'data' in its preserve set). Pre-2.1 they sat in the plugin root and
-// were overwritten by the manager's copy on every plugin push. On first boot
-// migrateToDataDir() moves any pre-2.1 root files across.
-const DATA_DIR = path.join(__dirname, 'data');
+const DATA_DIR = analyticsDir();
 const LIFETIME_FILE = path.join(DATA_DIR, 'lifetime.json');
 const DAILY_FILE = path.join(DATA_DIR, 'daily.json');
 const LEGACY_FILE = path.join(DATA_DIR, 'stats.json');
 const JOURNEYS_FILE = path.join(DATA_DIR, 'journeys.json');
+
+/**
+ * What never gets counted, server side.
+ *
+ * These were the plugin's `config.js` defaults and no install ever changed one,
+ * so they are constants rather than a config block nobody would open. The other
+ * two defaults it carried - honourDnt and sessionDedup - were always decided in
+ * the browser, where the facts are, and still are: see public/js/analytics.js.
+ */
+const EXCLUDE_ADMIN = true;
+const EXCLUDE_PATHS = ['/api'];
 const JOURNEY_DAILY_CAP = 5000;
 const REALTIME_WINDOW_MS = 5 * 60 * 1000;
 
@@ -48,23 +73,6 @@ async function writeJson(file, data) {
     await fs.rename(tmp, file);
 }
 
-/**
- * One-shot relocation of pre-2.1 counters from the plugin root into data/.
- * Runs before migrateLegacy() so the rest of the plugin only ever sees data/.
- */
-async function migrateToDataDir() {
-    await fs.mkdir(DATA_DIR, { recursive: true });
-    for (const name of ['lifetime.json', 'daily.json', 'journeys.json', 'stats.json']) {
-        const dest = path.join(DATA_DIR, name);
-        try { await fs.access(dest); continue; } catch { /* dest absent - maybe move */ }
-        const oldPath = path.join(__dirname, name);
-        try {
-            await fs.access(oldPath);
-            await fs.rename(oldPath, dest);
-        } catch { /* no pre-2.1 file to move */ }
-    }
-}
-
 /**
  * One-shot migration from the legacy flat stats.json.
  * Preserves existing totals as lifetime numbers; daily history starts empty.
@@ -274,11 +282,17 @@ 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 || {};
+/**
+ * Auth is injectable, the shape dashboard.js and plugins.js use, so a test can
+ * drive these routes without registering @fastify/jwt.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} [opts]
+ */
+export async function analyticsRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requireAdmin = opts.requireAdmin || defaultRequireAdmin;
 
-    await migrateToDataDir();
     await migrateLegacy();
 
     fastify.decorate('analytics', {
@@ -333,11 +347,11 @@ export default async function analyticsPlugin(fastify, options) {
         }
 
         const normalised = url.split('?')[0].split('#')[0].replace(/\/+$/, '') || '/';
-        if (settings.excludeAdmin && normalised.startsWith('/admin')) {
+        if (EXCLUDE_ADMIN && normalised.startsWith('/admin')) {
             return { ok: true, ignored: 'admin' };
         }
-        if (Array.isArray(settings.excludePaths)) {
-            for (const prefix of settings.excludePaths) {
+        if (Array.isArray(EXCLUDE_PATHS)) {
+            for (const prefix of EXCLUDE_PATHS) {
                 if (typeof prefix === 'string' && prefix && normalised.startsWith(prefix)) {
                     return { ok: true, ignored: 'excluded' };
                 }
@@ -441,6 +455,40 @@ export default async function analyticsPlugin(fastify, options) {
         return { activeSessions: sids.size, windowMinutes: REALTIME_WINDOW_MS / 60000 };
     });
 
+    /** GET /api/analytics/active-count - the sidebar badge: visitors on the site right now. */
+    fastify.get('/active-count', { preHandler: [authenticate, requireAdmin] }, async () => {
+        const [journeys, daily] = await Promise.all([readJson(JOURNEYS_FILE, {}), readJson(DAILY_FILE, {})]);
+        const today = todayKey();
+        const cutoff = Date.now() - REALTIME_WINDOW_MS;
+        const recent = (journeys[today] || []).filter(ev => ev.t >= cutoff);
+        const n = new Set(recent.map(ev => ev.sid)).size;
+        const mins = REALTIME_WINDOW_MS / 60000;
+
+        // What each active visitor is on now: their latest page.
+        const latest = new Map();
+        for (const ev of recent) if (!latest.has(ev.sid) || latest.get(ev.sid).t < ev.t) latest.set(ev.sid, ev);
+        const onPage = {};
+        for (const ev of latest.values()) onPage[ev.url] = (onPage[ev.url] || 0) + 1;
+        const viewsToday = Object.values(daily[today] || {}).reduce((a, b) => a + b, 0);
+        const sessionsToday = new Set((journeys[today] || []).map(ev => ev.sid)).size;
+
+        return {
+            count: n, label: `${plural(n, 'visitor')} on the site in the last ${mins} minutes`, tone: 'live',
+            details: {
+                title: 'Analytics',
+                rows: [
+                    {label: 'Active now', value: String(n)},
+                    {label: 'Views today', value: viewsToday.toLocaleString('en-GB')},
+                    {label: 'Sessions today', value: sessionsToday.toLocaleString('en-GB')}
+                ],
+                // URLs come from the PUBLIC hit counter - plain text only, set with textContent.
+                items: Object.entries(onPage).sort((a, b) => b[1] - a[1]).slice(0, 5)
+                    .map(([url, c]) => ({text: clip(url, 48), meta: `${plural(c, 'visitor')} here now`})),
+                empty: `Nobody on the site in the last ${mins} minutes.`
+            }
+        };
+    });
+
     fastify.get('/spikes', { preHandler: [authenticate, requireAdmin] }, async () => {
         const daily = await readJson(DAILY_FILE, {});
         return { items: detectSpikes(daily) };

package/server/routes/api/collections.js

@@ -359,6 +359,40 @@ export async function collectionsRoutes(fastify) {
         }
     });
 
+    /*
+     * Flag one entry as spam without disturbing the rest of it.
+     *
+     * `updateEntry` REPLACES `data` wholesale, so the obvious client-side PUT
+     * of {spam: true} would wipe every other field on the record. The merge
+     * has to happen server-side, which is the whole reason this endpoint
+     * exists rather than the context menu calling the generic update route.
+     *
+     * The field defaults to `spam` and need not be declared in the schema -
+     * validateEntryData only checks required fields, so an undeclared key is
+     * carried through untouched. Guarded by the same collections.update
+     * permission as any other write, so a public visitor cannot reach it.
+     */
+    fastify.post('/collections/:slug/entries/:id/spam', canUpdate, async (request, reply) => {
+        const {slug, id} = request.params;
+        const field = typeof request.body?.field === 'string' && request.body.field.trim()
+            ? request.body.field.trim()
+            : 'spam';
+        const value = request.body?.spam === false ? false : true;
+        try {
+            const existing = await getEntry(slug, id);
+            if (!existing) return reply.code(404).send({error: 'Entry not found'});
+
+            const entry = await updateEntry(slug, id, {...(existing.data || {}), [field]: value});
+            hooks.emit('collection:entryUpdated', {
+                slug, entryId: entry.id, data: entry.data, userId: request.user?.id || null
+            });
+            return {entry, field, spam: value};
+        } catch (err) {
+            const code = /not found/i.test(err.message) ? 404 : 400;
+            return reply.code(code).send({error: err.message});
+        }
+    });
+
     fastify.put('/collections/:slug/entries/:id', canUpdate, async (request, reply) => {
         try {
             const entry = await updateEntry(request.params.slug, request.params.id, request.body?.data || {});