@harshankur/viewcounter 3.1.0 → 3.2.0

package/routes/analytics.js

@@ -1,4 +1,6 @@
 const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
 const express = require('express');
 const rateLimit = require('express-rate-limit');
 const geoip = require('geoip-country');
@@ -7,6 +9,9 @@ const {
     EVENT_TYPE,
     HTTP_STATUS,
     QUERY_LIMITS,
+    REJECTION_REASON,
+    SOURCE_TYPE,
+    TRACKING,
     TREND_PERIOD,
     VIEW_LOG_SOURCE,
 } = require('../constants');
@@ -16,19 +21,66 @@ const PrivacyUtils = require('../utils/privacyUtils');
 const logger = require('../utils/logger');
 const { getClientIp, isValidIP, normalizeIp } = require('../utils/ipUtils');
 const { requireReadApiKey, requireAppScope, requireAdminApiKey, appsInScope } = require('../middleware/auth');
-const { requireRegisteredOrigin, noStore } = require('../middleware/security');
+const { requireRegisteredOrigin, requestOrigin, noStore } = require('../middleware/security');
+const { createRejectionCounter } = require('../db/rejectionCounter');
+const { hostnameOf, primaryLanguage, utmTags } = require('../utils/visitorContext');
 const {
     validateAppRegistration,
     validateRegisterView,
     validateEvent,
+    validateEngage,
     validateStatsRequest,
     validateTrendsRequest,
     validateListRequest,
     validateViewsRequest,
     validateSessionRequest,
     handleValidationErrors,
+    handleTrackingValidation,
 } = require('../middleware/validation');
 
+/**
+ * The tracker script sites include with <script src=".../tracker.js">. Read
+ * once; it is part of the package, not configuration.
+ */
+const TRACKER_SOURCE = fs.readFileSync(path.join(__dirname, '..', 'tracker', 'tracker.js'), 'utf8');
+/** Cached briefly, so a fix reaches every site within the hour. */
+const TRACKER_MAX_AGE_SECONDS = 60 * 60;
+
+/** The tracking endpoints, by path, and the source the tracking log files them under. */
+const TRACKING_PATHS = {
+    '/registerView': VIEW_LOG_SOURCE.REGISTER_VIEW,
+    '/event': VIEW_LOG_SOURCE.EVENT,
+    '/engage': VIEW_LOG_SOURCE.ENGAGE,
+};
+
+/**
+ * @param {string} path a request path, relative to where the router is mounted
+ * @returns {string|null} the tracking source, or null for any other endpoint
+ */
+function trackingSourceFor(path) {
+    return Object.hasOwn(TRACKING_PATHS, path) ? TRACKING_PATHS[path] : null;
+}
+
+/**
+ * sendBeacon posts text/plain, which needs no CORS preflight; a fetch may
+ * send JSON. Either way the handler sees an object, or an empty one for a
+ * body that is not JSON, which validation then refuses.
+ * @type {import('express').RequestHandler}
+ */
+function parseBeaconBody(req, res, next) {
+    if (typeof req.body === 'string') {
+        try {
+            const parsed = JSON.parse(req.body);
+            req.body = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+        } catch {
+            req.body = {};
+        }
+    } else if (!req.body || typeof req.body !== 'object') {
+        req.body = {};
+    }
+    next();
+}
+
 /**
  * Analytics routes.
  *
@@ -73,13 +125,13 @@ function intQuery(req, name, fallback) {
  * other tenant on the instance depends on, which is the failure mode that
  * matters once the apps belong to different people.
  *
- * Keyed on appId only — never on IP — so it is unaffected by how the client's
+ * Keyed on appId only, never on IP, so it is unaffected by how the client's
  * address is derived, and cannot be rotated away by a caller changing address.
  *
  * @param {{ perAppMax: number, windowMs: number }} rateLimitConfig
  * @returns {import('express').RequestHandler}
  */
-function buildPerAppLimiter(rateLimitConfig) {
+function buildPerAppLimiter(rateLimitConfig, onLimit = () => {}) {
     const { perAppMax, windowMs } = rateLimitConfig || {};
     // Zero disables it, for single-tenant deployments where the per-IP limit
     // is the only bound that means anything.
@@ -96,6 +148,10 @@ function buildPerAppLimiter(rateLimitConfig) {
         // bypass this limiter exists to be immune to.
         keyGenerator: (req) => String(req.query?.appId || req.body?.appId || '__unattributed__'),
         validate: { keyGeneratorIpFallback: false },
+        handler: (req, res, next, options) => {
+            onLimit(req);
+            res.status(options.statusCode).json(options.message);
+        },
     });
 }
 
@@ -113,7 +169,7 @@ function withRequestId(req, res, next) {
  * Build the correlation context for a log line.
  *
  * Logs the MASKED address, never the raw one. `logRequest` previously wrote
- * the unmasked IP on every view, event, and error — and on any normal
+ * the unmasked IP on every view, event, and error, and on any normal
  * deployment stdout is persisted to disk, so the raw addresses the privacy
  * design goes to lengths to keep out of the database were being written beside
  * it anyway.
@@ -128,7 +184,7 @@ function logContext(req) {
  *
  * The client gets a stable message plus the request id; the detail goes to the
  * server log only. Previously the raw database error text was returned to the
- * caller whenever NODE_ENV was not exactly "development" — which was the
+ * caller whenever NODE_ENV was not exactly "development", which was the
  * default, and which the setup wizard wrote into .env.
  */
 function handleRouteError(req, res, error, operation) {
@@ -140,10 +196,12 @@ function handleRouteError(req, res, error, operation) {
 }
 
 /**
- * @param {{ config: object, dbManager: object, isReady: () => boolean }} deps
+ * @param {{ config: object, dbManager: object, isReady: () => boolean,
+ *   geo?: { city: { lookup: (ip: string) => { region: string|null, city: string|null } }|null } }} deps
+ *   `geo.city` is read on every view, so it can be opened after the router is built
  * @returns {import('express').Router}
  */
-function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
+function createAnalyticsRouter({ config, dbManager, isReady = () => true, geo = { city: null } }) {
     const router = express.Router();
     // Authentication and authorization are separate steps: `requireKey` proves
     // the caller holds a key we issued, `requireScope` proves that key is
@@ -151,8 +209,38 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
     const requireKey = requireReadApiKey(config.auth);
     const requireScope = requireAppScope();
     const requireAdmin = requireAdminApiKey(config.auth);
-    const requireOrigin = requireRegisteredOrigin(config.allowed);
-    const limitPerApp = buildPerAppLimiter(config.server?.rateLimit);
+
+    // Tracking requests that are not stored are counted for the tracking log,
+    // so an operator can see why a site's views are not arriving.
+    const rejections = createRejectionCounter({
+        write: (rows) => (dbManager.logs?.recordRejections ? dbManager.logs.recordRejections(rows) : Promise.resolve(true)),
+    });
+    const reject = (req, reason, { appId, detail } = {}) => {
+        const source = trackingSourceFor(req.path);
+        if (!source) return;
+        rejections.count({
+            source,
+            reason,
+            appId: appId ?? req.query?.appId ?? req.body?.appId,
+            detail,
+            hostname: hostnameOf(requestOrigin(req)),
+        });
+    };
+
+    const requireOrigin = requireRegisteredOrigin(config.allowed, {
+        onReject: (req, appId) => reject(req, REJECTION_REASON.ORIGIN_NOT_ALLOWED, { appId }),
+    });
+    const limitPerApp = buildPerAppLimiter(config.server?.rateLimit,
+        (req) => reject(req, REJECTION_REASON.RATE_LIMITED, { detail: 'app' }));
+    const trackingValidation = handleTrackingValidation(reject);
+
+    /** Views from these are counted in the tracking log and never stored. */
+    const refuseBot = (req) => {
+        const userAgent = req.get('user-agent') || '';
+        if (!UserAgentParser.isBot(userAgent)) return false;
+        reject(req, REJECTION_REASON.BOT, { detail: UserAgentParser.botName(userAgent) });
+        return true;
+    };
 
     router.use(withRequestId);
 
@@ -169,6 +257,16 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
         return res.json({ status: 'healthy', uptime: process.uptime() });
     });
 
+    /**
+     * The tracker script. Loaded by other sites, so it opts out of the
+     * same-origin resource policy helmet applies to everything else.
+     */
+    router.get('/tracker.js', (req, res) => {
+        res.set('Cache-Control', `public, max-age=${TRACKER_MAX_AGE_SECONDS}`);
+        res.set('Cross-Origin-Resource-Policy', 'cross-origin');
+        res.type('application/javascript').send(TRACKER_SOURCE);
+    });
+
     /**
      * Register a page view.
      */
@@ -176,18 +274,23 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
         limitPerApp,
         requireOrigin,
         validateRegisterView(config.allowed),
-        handleValidationErrors,
+        trackingValidation,
         async (req, res) => {
             try {
                 const { appId, deviceSize, page, title, referrer, sessionId } = req.query;
-                const ip = normalizeIp(getClientIp(req));
+                if (refuseBot(req)) {
+                    return res.json({ message: 'Automated clients are not counted', recorded: false, duplicate: false });
+                }
 
+                const ip = normalizeIp(getClientIp(req));
                 if (!isValidIP(ip)) {
+                    reject(req, REJECTION_REASON.INVALID_IP);
                     logger.warn(`Rejected request with unparseable client IP`, logContext(req));
                     return res.status(HTTP_STATUS.BAD_REQUEST).json({ message: 'Invalid IP address format' });
                 }
 
                 const ipInfo = geoip.lookup(ip);
+                const place = geo.city ? geo.city.lookup(ip) : { region: null, city: null };
                 const userAgent = req.get('user-agent') || '';
                 const uaData = UserAgentParser.parse(userAgent);
 
@@ -198,7 +301,9 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
                 // page itself, not where the visitor came from, so reading it
                 // recorded every direct visit as a referral from the site's own
                 // domain. A server relaying views passes the real referrer here.
-                const referrerData = ReferrerParser.parse(referrer);
+                const hostname = hostnameOf(requestOrigin(req));
+                const referrerData = ReferrerParser.parse(referrer, hostname);
+                const utm = utmTags(req.query);
 
                 const result = await dbManager.registerEvent(appId, {
                     ip,
@@ -208,7 +313,13 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
                     pageTitle: title,
                     referrer: referrerData.referrer,
                     referrerDomain: referrerData.referrerDomain,
-                    sourceType: referrerData.sourceType,
+                    // A tagged link is a campaign, whichever site it was clicked on.
+                    sourceType: utm.utmSource || utm.utmMedium ? SOURCE_TYPE.CAMPAIGN : referrerData.sourceType,
+                    hostname,
+                    language: primaryLanguage(req.get('accept-language')),
+                    ...utm,
+                    region: place.region,
+                    city: place.city,
                     browser: uaData.browser,
                     browserVersion: uaData.browserVersion,
                     os: uaData.os,
@@ -224,15 +335,21 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
 
                 logger.audit('registerView', { ...logContext(req), appId, duplicate: result.duplicate });
 
+                // `id` lets the page report engagement for this view later.
                 if (result.duplicate) {
                     return res.status(HTTP_STATUS.OK).json({
                         message: 'View already registered recently',
                         duplicate: true,
+                        recorded: true,
+                        id: result.publicId,
                     });
                 }
 
-                return res.status(HTTP_STATUS.OK).json({ message: 'Success!', duplicate: false });
+                return res.status(HTTP_STATUS.OK).json({
+                    message: 'Success!', duplicate: false, recorded: true, id: result.publicId,
+                });
             } catch (error) {
+                reject(req, REJECTION_REASON.SERVER_ERROR);
                 return handleRouteError(req, res, error, 'register view');
             }
         }
@@ -245,17 +362,22 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
         limitPerApp,
         requireOrigin,
         validateEvent(config.allowed),
-        handleValidationErrors,
+        trackingValidation,
         async (req, res) => {
             try {
                 const { appId, eventType, eventData, sessionId, page, title } = req.body;
-                const ip = normalizeIp(getClientIp(req));
+                if (refuseBot(req)) {
+                    return res.json({ message: 'Automated clients are not counted', recorded: false });
+                }
 
+                const ip = normalizeIp(getClientIp(req));
                 if (!isValidIP(ip)) {
+                    reject(req, REJECTION_REASON.INVALID_IP);
                     return res.status(HTTP_STATUS.BAD_REQUEST).json({ message: 'Invalid IP address format' });
                 }
 
                 const ipInfo = geoip.lookup(ip);
+                const place = geo.city ? geo.city.lookup(ip) : { region: null, city: null };
                 const userAgent = req.get('user-agent') || '';
                 const uaData = UserAgentParser.parse(userAgent);
 
@@ -273,6 +395,10 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
                     sessionId,
                     eventType,
                     eventData,
+                    hostname: hostnameOf(requestOrigin(req)),
+                    language: primaryLanguage(req.get('accept-language')),
+                    region: place.region,
+                    city: place.city,
                     userAgent,
                     visitorSecret: config.privacy.visitorSecret,
                     // Custom events are never deduplicated.
@@ -284,14 +410,48 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
 
                 return res.status(HTTP_STATUS.OK).json({
                     message: 'Event tracked successfully',
+                    recorded: true,
+                    id: result.publicId,
+                    // Deprecated: the internal row number. Kept for 3.x clients; use `id`.
                     insertId: result.insertId,
                 });
             } catch (error) {
+                reject(req, REJECTION_REASON.SERVER_ERROR);
                 return handleRouteError(req, res, error, 'track event');
             }
         }
     );
 
+    /**
+     * Engagement for a recorded view: how long its page was visible and how
+     * far it was scrolled, sent by the tracker when the page is hidden or left.
+     */
+    router.post('/engage',
+        express.text({ type: () => true, limit: TRACKING.ENGAGE_BODY_BYTES }),
+        parseBeaconBody,
+        limitPerApp,
+        requireOrigin,
+        validateEngage(config.allowed),
+        trackingValidation,
+        async (req, res) => {
+            try {
+                if (refuseBot(req)) return res.status(HTTP_STATUS.NO_CONTENT).end();
+
+                const { appId, id, ms, scroll } = req.body;
+                const updated = await dbManager.addEngagement(appId, {
+                    viewId: id,
+                    engagedMs: Number(ms),
+                    scrollDepth: Number(scroll),
+                });
+                if (!updated) reject(req, REJECTION_REASON.UNKNOWN_VIEW);
+                return res.status(HTTP_STATUS.NO_CONTENT).end();
+            } catch (error) {
+                reject(req, REJECTION_REASON.SERVER_ERROR);
+                return handleRouteError(req, res, error, 'record engagement');
+            }
+        }
+    );
+
     // ---- Read API. Everything below requires a valid key. -------------------
 
     router.use(noStore);
@@ -424,7 +584,7 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
      * Provision a new app. Admin tier only.
      *
      * Creates the app's table and records it in the registry, then adds it to
-     * the live allowlist so it accepts traffic immediately — no restart. The
+     * the live allowlist so it accepts traffic immediately, with no restart. The
      * appId becomes a table identifier, so it is validated against a strict
      * pattern before it reaches any DDL.
      */
@@ -459,7 +619,26 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
         }
     );
 
+    /** For the host app's own limiter, which runs before this router, and for shutdown. */
+    router.countRejection = reject;
+    router.flushRejections = () => rejections.flush();
+
+    /**
+     * For the app that mounts this router, after its body parser: a body that
+     * is malformed JSON or over the size limit never reaches the router, so it
+     * is counted here, as an invalid request to the endpoint it was sent to.
+     * @type {import('express').ErrorRequestHandler}
+     */
+    // eslint-disable-next-line no-unused-vars
+    router.bodyErrorHandler = (err, req, res, next) => {
+        const status = err.status || err.statusCode || HTTP_STATUS.INTERNAL_SERVER_ERROR;
+        logger.warn(`Request rejected: ${err.message}`, { requestId: req.id });
+        reject(req, REJECTION_REASON.INVALID_REQUEST, { detail: 'body' });
+        res.status(status === HTTP_STATUS.INTERNAL_SERVER_ERROR ? HTTP_STATUS.BAD_REQUEST : status)
+            .json({ message: 'Malformed or oversized request' });
+    };
+
     return router;
 }
 
-module.exports = { createAnalyticsRouter, handleRouteError, logContext, withRequestId };
+module.exports = { createAnalyticsRouter, handleRouteError, logContext, withRequestId, trackingSourceFor };

package/tracker/tracker.js

@@ -0,0 +1,191 @@
+/*!
+ * viewcounter tracker, https://viewcounter.harshankur.com
+ *
+ *   <script defer src="https://your-server/tracker.js" data-app="blog"></script>
+ *
+ * Records a view of each page (including page changes in single-page apps),
+ * how long it was visible and how far it was scrolled, clicks on links to
+ * other sites and on downloads, and the campaign tags of the landing URL.
+ * The page before is sent as its origin and path only.
+ *
+ * It stores nothing on the visitor's device (no cookie, no localStorage, no
+ * sessionStorage), so it needs no consent banner, and it sends no identifier:
+ * the server tells repeat visits apart with a hash it rotates every day.
+ *
+ * Options, as attributes on the script tag:
+ *   data-app="blog"                 required: the app ID the views belong to
+ *   data-hosts="example.com,www.example.com"
+ *                                   only track on these hostnames (keeps dev
+ *                                   servers and previews out of the data)
+ *   data-spa="false"                do not treat history changes as page views
+ *   data-outbound="false"           do not record clicks on links to other sites
+ *   data-downloads="false"          do not record clicks on downloads
+ *   data-respect-dnt="true"         send nothing when Do Not Track is on
+ *
+ * Custom events: window.viewcounter.track('signup', { plan: 'pro' }).
+ */
+(() => {
+    const script = document.currentScript;
+    const app = script && script.dataset.app;
+    if (!app) return;
+
+    const option = (name, fallback) => (script.dataset[name] === undefined ? fallback : script.dataset[name] !== 'false');
+    const hosts = (script.dataset.hosts || '').split(',').map((host) => host.trim().toLowerCase()).filter(Boolean);
+    if (hosts.length && !hosts.includes(location.hostname.toLowerCase())) return;
+    if (location.protocol !== 'http:' && location.protocol !== 'https:') return;
+    // Automated browsers are not visitors.
+    if (navigator.webdriver) return;
+    if (option('respectDnt', false) && (navigator.doNotTrack === '1' || window.doNotTrack === '1')) return;
+
+    const base = script.src.replace(/[^/]*$/, '');
+    const UTM = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+    const DOWNLOAD = /\.(pdf|zip|gz|tgz|rar|7z|dmg|exe|msi|pkg|deb|rpm|apk|iso|csv|xlsx?|docx?|pptx?|odt|ods|epub|mp3|mp4|mov|avi|wav)$/i;
+    const MAX_ENGAGED_MS = 6 * 60 * 60 * 1000;
+
+    const deviceSize = () => (innerWidth < 768 ? 'small' : innerWidth < 1200 ? 'medium' : 'large');
+    /** How much of the page has been on screen, from 0 to 100. */
+    const seen = () => {
+        const height = Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0);
+        return height <= 0 ? 100 : Math.min(100, Math.round(((scrollY + innerHeight) / height) * 100));
+    };
+
+    /** A URL's origin and path: its query and fragment can carry tokens or emails. */
+    const originAndPath = (url) => {
+        try {
+            const parsed = new URL(url);
+            return `${parsed.origin}${parsed.pathname}`;
+        } catch {
+            return '';
+        }
+    };
+
+    let view = null;
+    let referrer = document.referrer ? originAndPath(document.referrer) : '';
+    let path = location.pathname;
+
+    /** Tell the server how long the current page was visible and how far it was scrolled. */
+    function reportEngagement() {
+        if (!view || !view.id) return;
+        const ms = Math.min(MAX_ENGAGED_MS, Math.round(view.visibleMs + (view.visibleSince === null ? 0 : performance.now() - view.visibleSince)));
+        if (ms <= view.sentMs && view.scroll <= view.sentScroll) return;
+        view.sentMs = ms;
+        view.sentScroll = view.scroll;
+        const body = JSON.stringify({ appId: app, id: view.id, ms, scroll: view.scroll });
+        // text/plain needs no CORS preflight, so the beacon survives the page closing.
+        if (!(navigator.sendBeacon && navigator.sendBeacon(`${base}engage`, new Blob([body], { type: 'text/plain' })))) {
+            fetch(`${base}engage`, { method: 'POST', body, keepalive: true, credentials: 'omit', headers: { 'Content-Type': 'text/plain' } })
+                .catch(() => {});
+        }
+    }
+
+    function pageview() {
+        reportEngagement();
+        const params = new URLSearchParams({
+            appId: app,
+            deviceSize: deviceSize(),
+            page: location.pathname.slice(0, 500),
+            title: document.title.slice(0, 200),
+            referrer: referrer.slice(0, 500),
+        });
+        // Only the campaign tags: the rest of a query string can carry
+        // emails, tokens, or IDs, and never leaves the page.
+        const query = new URLSearchParams(location.search);
+        for (const key of UTM) {
+            const value = query.get(key);
+            if (value) params.set(key, value.slice(0, 100));
+        }
+
+        const current = {
+            id: null,
+            visibleMs: 0,
+            visibleSince: document.visibilityState === 'visible' ? performance.now() : null,
+            scroll: seen(),
+            sentMs: 0,
+            sentScroll: 0,
+        };
+        view = current;
+        fetch(`${base}registerView?${params}`, { keepalive: true, credentials: 'omit', referrerPolicy: 'no-referrer' })
+            .then((response) => (response.ok ? response.json() : null))
+            .then((result) => { if (result && result.id) current.id = result.id; })
+            .catch(() => {});
+    }
+
+    function track(eventType, eventData) {
+        if (typeof eventType !== 'string' || !eventType) return;
+        fetch(`${base}event`, {
+            method: 'POST',
+            keepalive: true,
+            credentials: 'omit',
+            referrerPolicy: 'no-referrer',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                appId: app,
+                eventType: eventType.slice(0, 50),
+                eventData: eventData && typeof eventData === 'object' ? eventData : undefined,
+                page: location.pathname.slice(0, 500),
+                title: document.title.slice(0, 200),
+            }),
+        }).catch(() => {});
+    }
+
+    // A page change in a single-page app is a new page view, with the page it
+    // came from as its referrer (which the server files as internal).
+    function navigated() {
+        if (location.pathname === path) return;
+        referrer = `${location.origin}${path}`;
+        path = location.pathname;
+        pageview();
+    }
+    if (option('spa', true)) {
+        for (const method of ['pushState', 'replaceState']) {
+            const original = history[method];
+            history[method] = function patched(...args) {
+                const result = original.apply(this, args);
+                navigated();
+                return result;
+            };
+        }
+        addEventListener('popstate', navigated);
+    }
+
+    let scrollQueued = false;
+    addEventListener('scroll', () => {
+        if (scrollQueued) return;
+        scrollQueued = true;
+        requestAnimationFrame(() => {
+            scrollQueued = false;
+            if (view) view.scroll = Math.max(view.scroll, seen());
+        });
+    }, { passive: true });
+
+    document.addEventListener('visibilitychange', () => {
+        if (!view) return;
+        if (document.visibilityState === 'hidden') {
+            if (view.visibleSince !== null) view.visibleMs += performance.now() - view.visibleSince;
+            view.visibleSince = null;
+            reportEngagement();
+        } else if (view.visibleSince === null) {
+            view.visibleSince = performance.now();
+        }
+    });
+    addEventListener('pagehide', reportEngagement);
+
+    // Links out and downloads. Only the other site's hostname, or the file's
+    // name, is recorded: never the whole URL, which can carry personal data.
+    document.addEventListener('click', (event) => {
+        const link = event.target && event.target.closest ? event.target.closest('a[href]') : null;
+        if (!link) return;
+        let url;
+        try { url = new URL(link.href, location.href); } catch { return; }
+        if (option('downloads', true) && DOWNLOAD.test(url.pathname)) {
+            let file = url.pathname.split('/').pop();
+            try { file = decodeURIComponent(file); } catch { /* keep it encoded */ }
+            track('download', { file: file.slice(0, 100) });
+        } else if (option('outbound', true) && /^https?:$/.test(url.protocol) && url.hostname !== location.hostname) {
+            track('outbound', { host: url.hostname });
+        }
+    }, { capture: true });
+
+    window.viewcounter = { track };
+    pageview();
+})();

package/utils/appIdUtils.js

@@ -2,7 +2,7 @@
  * App ID validation.
  *
  * An app ID becomes a MySQL table name. Identifiers cannot be bound as query
- * parameters, so they are interpolated — which is safe only because the value
+ * parameters, so they are interpolated, which is safe only because the value
  * is checked here first. App IDs used to come exclusively from local config;
  * the admin API now accepts them over HTTP, so this is a live injection
  * boundary, not a formatting preference.

package/utils/durationUtils.js

@@ -0,0 +1,33 @@
+/**
+ * Human-readable durations for configuration: "30m", "12h", "7d".
+ *
+ * Deliberately small: whole numbers of minutes, hours, or days, nothing else,
+ * so a value like "30 min" or "1.5h" is refused rather than read as something
+ * the operator did not mean. For a session timeout that difference matters.
+ */
+
+const UNIT_MS = { m: 60 * 1000, h: 60 * 60 * 1000, d: 24 * 60 * 60 * 1000 };
+const DURATION = /^(\d{1,6})([mhd])$/;
+
+/**
+ * @param {string} raw e.g. "7d"
+ * @returns {number|null} milliseconds, or null when the value is not a duration
+ */
+function parseDuration(raw) {
+    const match = DURATION.exec(String(raw ?? '').trim().toLowerCase());
+    return match ? Number(match[1]) * UNIT_MS[match[2]] : null;
+}
+
+/**
+ * The largest whole unit that expresses `ms` exactly: 604800000 -> "7d".
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+    for (const unit of ['d', 'h', 'm']) {
+        if (ms % UNIT_MS[unit] === 0) return `${ms / UNIT_MS[unit]}${unit}`;
+    }
+    return `${ms}ms`;
+}
+
+module.exports = { parseDuration, formatDuration };

package/utils/errorUtils.js

@@ -6,7 +6,7 @@
  * identified by an enum member, its message text lives in exactly one table
  * here, and callers branch on `err.code` rather than parsing message strings.
  *
- * `getError` builds and reports but deliberately does NOT throw — the `throw`
+ * `getError` builds and reports but deliberately does NOT throw: the `throw`
  * stays visible at the call site and under the caller's control.
  */
 
@@ -45,6 +45,7 @@ const WarningType = {
     VIEW_LOG_PRUNE_FAILED: 'VIEW_LOG_PRUNE_FAILED',
     MIGRATION_TABLE_MISSING: 'MIGRATION_TABLE_MISSING',
     VIEW_LOG_WRITE_FAILED: 'VIEW_LOG_WRITE_FAILED',
+    TRACKING_LOG_WRITE_FAILED: 'TRACKING_LOG_WRITE_FAILED',
     ADMIN_LOG_WRITE_FAILED: 'ADMIN_LOG_WRITE_FAILED',
     TRASH_PURGE_FAILED: 'TRASH_PURGE_FAILED',
 };
@@ -113,6 +114,8 @@ const WARNING_MESSAGES = {
         'Behind a TLS-terminating proxy, set TRUST_PROXY and have the proxy pass X-Forwarded-Proto and the original Host.',
     [WarningType.MIGRATION_TABLE_MISSING]: (info) =>
         `Table '${info?.table}' does not exist; skipping its schema migration.`,
+    [WarningType.TRACKING_LOG_WRITE_FAILED]: (info) =>
+        `Could not write counted tracking rejections: ${info?.cause}`,
     [WarningType.VIEW_LOG_WRITE_FAILED]: (info) =>
         `Could not write the view register log entry for '${info?.appId}': ${info?.cause}`,
     [WarningType.ADMIN_LOG_WRITE_FAILED]: (info) =>