@wtfalch/reporting 0.1.2 → 0.2.1

package/README.md

@@ -134,6 +134,62 @@ registerShutdownFlush(reporting);   // one bounded flush on SIGTERM
 Best effort. The queue is per process and bounded at 1,000; the logger has
 every row regardless.
 
+## Analytics (0.2.0)
+
+Three tables and two writers. `reporting_analytics` holds raw rows for a
+window (`analytics.retention_days`, default 90); `reporting_analytics_daily`
+and `reporting_analytics_weekly` hold counts with no identifier in any column
+and are kept indefinitely. The rollups store distinct visitor and people
+counts at every grain a reader asks for (site, tenant, name, path, device,
+country, referrer) rather than summing finer groups, keep a contiguous
+completed-day watermark in `reporting_tasks`, and pruning never passes what
+they still need.
+
+```ts
+// The collector, a public route: POST and OPTIONS, always 204.
+import { collectHandler } from '@wtfalch/reporting/next';
+const handle = collectHandler({
+  reporting, db,
+  sites: JSON.parse(process.env.REPORTING_SITES ?? '{}'),
+  getUserId: async () => (await getSession())?.user.id ?? null,
+  tenantFor: async (userId, pathname) => tenantIfMember(userId, pathname),
+  normalisePath: routePattern,
+});
+export const POST = handle;
+export const OPTIONS = handle;
+
+// The beacon, in the root layout.
+import { ReportingProvider, ConsentControl } from '@wtfalch/reporting/react';
+<ReportingProvider collector="/api/reporting/collect" site="app" consent="consented">
+  {children}
+  <ConsentControl>We count visits. Allow a cookie so we can tell returning visitors apart?</ConsentControl>
+</ReportingProvider>
+
+// Server-side truth, from a Server Action.
+await reporting.analytics.track({ name: 'invoice.approved', userId: access.actor.id, tenantId, path });
+
+// Housekeeping.
+housekeeping.register(rollupAnalytics);
+housekeeping.register(rollupAnalyticsWeekly);
+housekeeping.register(pruneAnalytics);
+```
+
+What the beacon never sends: a user id. Identity is joined server-side from
+the session, for same-origin beacons only; a beacon from an allowed foreign
+origin (`sites`) is recorded with no user and no tenant, whatever cookies it
+carries. Paths are normalised to route patterns before storage
+(`normalisePath`: uuids, numbers, tokens and addresses become placeholders),
+the query string never arrives, the user agent becomes a device class and is
+discarded, and `cf-ipcountry` becomes two letters or nothing.
+
+Consent: `none` stores nothing about the browser; `consented` (the default)
+sets the first-party cookie `_rp` only after `accept()`; `always` sets it
+without asking. `analytics.identify_signed_in` is the one line that turns
+server-side identification off.
+
+Erasure: `reporting_erase_person(subject)` deletes the subject's raw rows;
+the rollups hold nothing to erase. Call it in the host's erasure transaction.
+
 ## Tests
 
 ```ts

package/dist/analytics/collector.d.ts

@@ -0,0 +1,40 @@
+import type { Db, Logger } from '../types.js';
+/** Which origins may post beacons for which site (D17). The collector's own site is implied by same-origin. */
+export type Sites = Readonly<Record<string, {
+    readonly origins: readonly string[];
+}>>;
+export interface CollectorOptions {
+    readonly db: Db;
+    readonly log: Logger;
+    /** The collector's own site: same-origin beacons claiming it are this app's. */
+    readonly site: string;
+    /** Other sites and the origins allowed to post for them. A same-origin beacon for another site is dropped. */
+    readonly sites?: Sites;
+    /**
+     * The signed-in person, from the host's session, for same-origin beacons
+     * only (addendum A5): a beacon from an allowed foreign origin never reads
+     * the session, whatever cookies arrive. Return null for nobody.
+     */
+    readonly getUserId?: (request: Request) => Promise<string | null>;
+    /**
+     * The organisation a row belongs to, from the resolved person and the
+     * pathname as the browser sent it (the query string already gone); attach
+     * one only when that person is a member of it. Anonymous or refused claims
+     * store null. The normalised route is the third argument, for a host that
+     * decides by route rather than by id.
+     */
+    readonly tenantFor?: (userId: string, pathname: string, route: string) => Promise<string | null>;
+    /** The host's route normalisation; the package's default handles what it does not. */
+    readonly normalisePath?: (pathname: string) => string;
+    readonly identifySignedIn?: () => Promise<boolean>;
+    readonly now?: () => Date;
+    /** Events per minute per visitor and per client ip. Default 600. */
+    readonly ratePerMinute?: number;
+}
+/**
+ * The collector: a public route handler over the Web `Request`. Always 204,
+ * so a bad beacon is never a probe; every refusal is a drop and a log line.
+ */
+export declare function createCollector(options: CollectorOptions): {
+    handle(request: Request): Promise<Response>;
+};

package/dist/analytics/collector.js

@@ -0,0 +1,170 @@
+import { ANALYTICS_LIMITS, beaconBatchSchema, clampOccurredAt, countryOf, deviceOf, normalisePath, referrerHostOf, } from './schema.js';
+import { insertAnalytics } from './write.js';
+/** A per-process token bucket, enough to bound abuse, never to meter. */
+class Buckets {
+    perMinute;
+    now;
+    buckets = new Map();
+    constructor(perMinute, now) {
+        this.perMinute = perMinute;
+        this.now = now;
+    }
+    take(key, n) {
+        const t = this.now().getTime();
+        const b = this.buckets.get(key) ?? { tokens: this.perMinute, at: t };
+        b.tokens = Math.min(this.perMinute, b.tokens + ((t - b.at) / 60_000) * this.perMinute);
+        b.at = t;
+        if (b.tokens < n) {
+            this.buckets.set(key, b);
+            return false;
+        }
+        b.tokens -= n;
+        this.buckets.set(key, b);
+        if (this.buckets.size > 10_000)
+            this.buckets.clear();
+        return true;
+    }
+}
+const NO_CONTENT = () => new Response(null, { status: 204 });
+/**
+ * The collector: a public route handler over the Web `Request`. Always 204,
+ * so a bad beacon is never a probe; every refusal is a drop and a log line.
+ */
+export function createCollector(options) {
+    const now = options.now ?? (() => new Date());
+    const buckets = new Buckets(options.ratePerMinute ?? 600, now);
+    const normalise = options.normalisePath ?? normalisePath;
+    function originFor(request) {
+        const origin = request.headers.get('origin');
+        const host = request.headers.get('x-forwarded-host') ?? request.headers.get('host');
+        if (!origin)
+            return host ? { kind: 'same', origin: `https://${host}` } : null;
+        let originHost;
+        try {
+            originHost = new URL(origin).host;
+        }
+        catch {
+            return null;
+        }
+        return { kind: originHost === host ? 'same' : 'foreign', origin };
+    }
+    function corsFor(response, origin) {
+        response.headers.set('access-control-allow-origin', origin);
+        response.headers.set('vary', 'origin');
+        return response;
+    }
+    async function handle(request) {
+        const where = originFor(request);
+        if (request.method === 'OPTIONS') {
+            // Preflight for an allowed foreign origin; anything else gets nothing.
+            const allowed = where?.kind === 'foreign' &&
+                Object.values(options.sites ?? {}).some((s) => s.origins.includes(where.origin));
+            if (!allowed)
+                return NO_CONTENT();
+            const r = corsFor(NO_CONTENT(), where.origin);
+            r.headers.set('access-control-allow-methods', 'POST');
+            r.headers.set('access-control-allow-headers', 'content-type');
+            r.headers.set('access-control-max-age', '600');
+            return r;
+        }
+        if (request.method !== 'POST' || !where)
+            return NO_CONTENT();
+        const length = Number(request.headers.get('content-length') ?? '0');
+        if (length > ANALYTICS_LIMITS.bodyBytes)
+            return NO_CONTENT();
+        let text;
+        try {
+            text = await request.text();
+        }
+        catch {
+            return NO_CONTENT();
+        }
+        if (text.length > ANALYTICS_LIMITS.bodyBytes)
+            return NO_CONTENT();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            return NO_CONTENT();
+        }
+        const parsed = beaconBatchSchema.safeParse(json);
+        if (!parsed.success) {
+            options.log.info({ issues: parsed.error.issues.length }, 'reporting: beacon refused');
+            return NO_CONTENT();
+        }
+        const batch = parsed.data;
+        // Which site, and may this origin speak for it.
+        let foreign = false;
+        if (where.kind === 'same') {
+            if (batch.site !== options.site)
+                return NO_CONTENT();
+        }
+        else {
+            const allowed = options.sites?.[batch.site]?.origins.includes(where.origin) ?? false;
+            if (!allowed || batch.site === options.site)
+                return NO_CONTENT();
+            foreign = true;
+        }
+        const ip = request.headers.get('cf-connecting-ip') ?? request.headers.get('x-forwarded-for');
+        const n = batch.events.length;
+        if (!buckets.take(`ip:${ip ?? 'none'}`, n))
+            return NO_CONTENT();
+        if (batch.visitorId && !buckets.take(`v:${batch.visitorId}`, n))
+            return NO_CONTENT();
+        // Identity is the session's, same-origin only, and never the body's.
+        let userId = null;
+        if (!foreign && options.getUserId && ((await options.identifySignedIn?.()) ?? true)) {
+            try {
+                userId = await options.getUserId(request);
+            }
+            catch (error) {
+                options.log.warn({ err: error instanceof Error ? error.message : String(error) }, 'reporting: getUserId failed; recording anonymously');
+            }
+        }
+        const receivedAt = now();
+        const device = deviceOf(request.headers.get('user-agent'));
+        const country = countryOf(request.headers.get('cf-ipcountry'));
+        const rows = [];
+        for (const event of batch.events) {
+            const pathname = event.path.split(/[?#]/)[0] ?? '/';
+            const path = normalise(pathname);
+            let tenantId = null;
+            if (userId && options.tenantFor) {
+                try {
+                    tenantId = await options.tenantFor(userId, pathname, path);
+                }
+                catch {
+                    tenantId = null;
+                }
+            }
+            const props = { ...event.props };
+            if (event.duration !== undefined)
+                props.duration = event.duration;
+            rows.push({
+                occurredAt: clampOccurredAt(event.at, receivedAt),
+                receivedAt,
+                site: batch.site,
+                tenantId,
+                visitorId: batch.visitorId ?? null,
+                sessionId: batch.sessionId ?? null,
+                userId,
+                name: event.name,
+                path,
+                referrerHost: referrerHostOf(event.referrer),
+                device,
+                country,
+                props,
+            });
+        }
+        try {
+            await insertAnalytics(options.db, rows);
+        }
+        catch (error) {
+            options.log.error({ err: error instanceof Error ? error.message : String(error), rows: rows.length }, 'reporting: analytics insert failed');
+        }
+        const response = NO_CONTENT();
+        return foreign ? corsFor(response, where.origin) : response;
+    }
+    return { handle };
+}

package/dist/analytics/reader.d.ts

@@ -0,0 +1,63 @@
+import type { Db } from '../types.js';
+export type Grain = 'site' | 'tenant' | 'name' | 'path' | 'device' | 'country' | 'referrer';
+export interface SeriesOptions {
+    readonly site: string;
+    /** A customer organisation's view: its own rows only, and small groups hidden. */
+    readonly tenantId?: string;
+    readonly from: string;
+    readonly to: string;
+    /** Which dimension to break down by. `site` (the default) is the total. */
+    readonly grain?: Exclude<Grain, 'tenant'>;
+    /** Below this many distinct visitors a bucket is shown as `(few)` when `tenantId` is set. Default 5. */
+    readonly floor?: number;
+}
+export interface SeriesPoint {
+    readonly day: string;
+    readonly key: string;
+    readonly views: number;
+    readonly visitors: number;
+    readonly people: number;
+}
+/**
+ * Daily counts from the rollup (addendum A4: every level is stored, none is
+ * summed from another). Only rows without a tenant carry dimensions, so a
+ * customer organisation's view is the site total for its tenant and nothing
+ * finer; the operator's view has every grain. Small groups (addendum A7)
+ * render as `(few)` for a tenant, so a bucket cannot single a person out.
+ */
+export declare function analyticsSeries(db: Db, opts: SeriesOptions): Promise<readonly SeriesPoint[]>;
+export interface WeeklyPoint {
+    readonly week: string;
+    readonly visitors: number;
+    readonly returningVisitors: number;
+    readonly people: number;
+    readonly returningPeople: number;
+}
+export declare function analyticsWeekly(db: Db, opts: {
+    site: string;
+    tenantId?: string;
+    from: string;
+    to: string;
+}): Promise<readonly WeeklyPoint[]>;
+export interface RecentOptions {
+    readonly site: string;
+    readonly tenantId?: string;
+    readonly name?: string;
+    readonly limit?: number;
+}
+export interface RecentEvent {
+    readonly occurredAt: Date;
+    readonly name: string;
+    readonly path: string;
+    readonly device: string;
+    readonly country: string | null;
+    readonly referrerHost: string | null;
+    readonly signedIn: boolean;
+}
+/** The latest raw rows as the operator sees them: what happened, never who. Ids are projected out. */
+export declare function analyticsRecent(db: Db, opts: RecentOptions): Promise<readonly RecentEvent[]>;
+/** `(few)` for a customer's bucket under the floor; the operator sees the number. */
+export declare function hideSmallGroups<T extends {
+    visitors: number;
+    key: string;
+}>(points: readonly T[], floor?: number): readonly T[];

package/dist/analytics/reader.js

@@ -0,0 +1,89 @@
+import { and, asc, desc, eq, gte, isNull, lte, sql } from 'drizzle-orm';
+import { reportingAnalytics, reportingAnalyticsDaily, reportingAnalyticsWeekly, } from '../tables.js';
+/**
+ * Daily counts from the rollup (addendum A4: every level is stored, none is
+ * summed from another). Only rows without a tenant carry dimensions, so a
+ * customer organisation's view is the site total for its tenant and nothing
+ * finer; the operator's view has every grain. Small groups (addendum A7)
+ * render as `(few)` for a tenant, so a bucket cannot single a person out.
+ */
+export async function analyticsSeries(db, opts) {
+    const t = reportingAnalyticsDaily;
+    if (opts.tenantId) {
+        const rows = await db
+            .select({ day: t.day, views: t.views, visitors: t.visitors, people: t.people })
+            .from(t)
+            .where(and(eq(t.site, opts.site), eq(t.grain, 'tenant'), eq(t.tenantId, opts.tenantId), gte(t.day, opts.from), lte(t.day, opts.to)))
+            .orderBy(asc(t.day));
+        return rows.map((r) => ({
+            day: String(r.day),
+            key: 'total',
+            views: r.views,
+            visitors: r.visitors,
+            people: r.people,
+        }));
+    }
+    const grain = opts.grain ?? 'site';
+    const keyColumn = grain === 'name'
+        ? t.name
+        : grain === 'path'
+            ? t.path
+            : grain === 'device'
+                ? t.device
+                : grain === 'country'
+                    ? t.country
+                    : grain === 'referrer'
+                        ? t.referrerHost
+                        : sql `'total'`;
+    const rows = await db
+        .select({ day: t.day, key: keyColumn, views: t.views, visitors: t.visitors, people: t.people })
+        .from(t)
+        .where(and(eq(t.site, opts.site), eq(t.grain, grain), isNull(t.tenantId), gte(t.day, opts.from), lte(t.day, opts.to)))
+        .orderBy(asc(t.day), desc(t.views));
+    return rows.map((r) => ({
+        day: String(r.day),
+        key: String(r.key ?? 'total'),
+        views: r.views,
+        visitors: r.visitors,
+        people: r.people,
+    }));
+}
+export async function analyticsWeekly(db, opts) {
+    const t = reportingAnalyticsWeekly;
+    const rows = await db
+        .select()
+        .from(t)
+        .where(and(eq(t.site, opts.site), opts.tenantId ? eq(t.tenantId, opts.tenantId) : isNull(t.tenantId), gte(t.week, opts.from), lte(t.week, opts.to)))
+        .orderBy(asc(t.week));
+    return rows.map((r) => ({
+        week: String(r.week),
+        visitors: r.visitors,
+        returningVisitors: r.returningVisitors,
+        people: r.people,
+        returningPeople: r.returningPeople,
+    }));
+}
+/** The latest raw rows as the operator sees them: what happened, never who. Ids are projected out. */
+export async function analyticsRecent(db, opts) {
+    const t = reportingAnalytics;
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 200));
+    const rows = await db
+        .select({
+        occurredAt: t.occurredAt,
+        name: t.name,
+        path: t.path,
+        device: t.device,
+        country: t.country,
+        referrerHost: t.referrerHost,
+        signedIn: sql `${t.userId} is not null`,
+    })
+        .from(t)
+        .where(and(eq(t.site, opts.site), opts.tenantId ? eq(t.tenantId, opts.tenantId) : undefined, opts.name ? eq(t.name, opts.name) : undefined))
+        .orderBy(desc(t.occurredAt), desc(t.id))
+        .limit(limit);
+    return rows.map((r) => ({ ...r, signedIn: Boolean(r.signedIn) }));
+}
+/** `(few)` for a customer's bucket under the floor; the operator sees the number. */
+export function hideSmallGroups(points, floor = 5) {
+    return points.map((p) => (p.visitors > 0 && p.visitors < floor ? { ...p, key: '(few)' } : p));
+}

package/dist/analytics/schema.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export declare const ANALYTICS_NAME_PATTERN: RegExp;
+export declare const DEVICES: readonly ["desktop", "mobile", "tablet", "bot", "unknown"];
+export type Device = (typeof DEVICES)[number];
+export declare const ANALYTICS_LIMITS: {
+    readonly path: 512;
+    readonly referrerHost: 253;
+    readonly propsBytes: 4096;
+    readonly bodyBytes: 16384;
+    readonly batch: 20;
+    /** The beacon's clock may disagree with the server's by this much, either way. */
+    readonly clockSkewMs: number;
+};
+/** The package's own event names; everything else is the host's. */
+export declare const PAGE_VIEW = "page.view";
+export declare const PAGE_LEAVE = "page.leave";
+/** Flat, bounded, and never a key that names a person or a secret; the same rule the event log's `data` has, at a quarter of the size. */
+export declare const propsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+/** One event as the beacon sends it. Nothing here names a person: the collector joins identity from the session, never from the body. */
+export declare const beaconEventSchema: z.ZodObject<{
+    name: z.ZodString;
+    at: z.ZodNumber;
+    path: z.ZodString;
+    referrer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    props: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    duration: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const beaconBatchSchema: z.ZodObject<{
+    site: z.ZodString;
+    visitorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    events: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        at: z.ZodNumber;
+        path: z.ZodString;
+        referrer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        props: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type BeaconBatch = z.infer<typeof beaconBatchSchema>;
+export type BeaconEvent = z.infer<typeof beaconEventSchema>;
+/**
+ * The default route normalisation (addendum A7): a pathname with anything
+ * that looks like an identifier replaced by a placeholder, so no uuid,
+ * numeric id, token or address ever reaches the raw table or a rollup. A
+ * host with a route manifest supplies its own and this is the fallback for
+ * paths it does not know. The query string and fragment never arrive here;
+ * the beacon sends the pathname and the collector strips again anyway.
+ */
+export declare function normalisePath(pathname: string): string;
+/** The host only: `https://www.example.com/a?b` becomes `www.example.com`; junk becomes null. */
+export declare function referrerHostOf(referrer: string | null | undefined): string | null;
+/** A device class from the user agent, which is then discarded. Coarse on purpose. */
+export declare function deviceOf(userAgent: string | null | undefined): Device;
+/** Two upper-case letters or nothing; `cf-ipcountry` says `XX` and `T1` for unknown and Tor, which are not countries. */
+export declare function countryOf(header: string | null | undefined): string | null;
+/** The beacon's time, held to within the skew of arrival. */
+export declare function clampOccurredAt(at: number, receivedAt: Date): Date;

package/dist/analytics/schema.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import { BANNED_KEYS, SITE_PATTERN } from '../schema.js';
+export const ANALYTICS_NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+export const DEVICES = ['desktop', 'mobile', 'tablet', 'bot', 'unknown'];
+export const ANALYTICS_LIMITS = {
+    path: 512,
+    referrerHost: 253,
+    propsBytes: 4096,
+    bodyBytes: 16384,
+    batch: 20,
+    /** The beacon's clock may disagree with the server's by this much, either way. */
+    clockSkewMs: 10 * 60 * 1000,
+};
+/** The package's own event names; everything else is the host's. */
+export const PAGE_VIEW = 'page.view';
+export const PAGE_LEAVE = 'page.leave';
+const scalar = z.union([z.string().max(1024), z.number(), z.boolean(), z.null()]);
+/** Flat, bounded, and never a key that names a person or a secret; the same rule the event log's `data` has, at a quarter of the size. */
+export const propsSchema = z.record(z.string().max(64), scalar).superRefine((props, ctx) => {
+    for (const key of Object.keys(props)) {
+        if (BANNED_KEYS.includes(key)) {
+            ctx.addIssue({ code: 'custom', path: [key], message: `"${key}" may not be a props key` });
+        }
+        const value = props[key];
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            ctx.addIssue({ code: 'custom', path: [key], message: 'must be a finite number' });
+        }
+    }
+    if (JSON.stringify(props).length > ANALYTICS_LIMITS.propsBytes) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `must serialise to at most ${ANALYTICS_LIMITS.propsBytes} bytes`,
+        });
+    }
+});
+const opaqueId = z.string().regex(/^[A-Za-z0-9_-]{8,64}$/);
+/** One event as the beacon sends it. Nothing here names a person: the collector joins identity from the session, never from the body. */
+export const beaconEventSchema = z.strictObject({
+    name: z.string().regex(ANALYTICS_NAME_PATTERN),
+    /** Milliseconds since the epoch, by the browser's clock; clamped on arrival. */
+    at: z.number().int().nonnegative(),
+    path: z.string().min(1).max(2048),
+    referrer: z.string().max(2048).nullish(),
+    props: propsSchema.default({}),
+    /** Seconds on the page, for `page.leave`. */
+    duration: z.number().int().min(0).max(86_400).optional(),
+});
+export const beaconBatchSchema = z.strictObject({
+    site: z.string().regex(SITE_PATTERN),
+    visitorId: opaqueId.nullish(),
+    sessionId: opaqueId.nullish(),
+    events: z.array(beaconEventSchema).min(1).max(ANALYTICS_LIMITS.batch),
+});
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC = /^\d+$/;
+const OPAQUE = /^[A-Za-z0-9_-]{20,}$/;
+const HEXISH = /^[0-9a-f]{16,}$/i;
+/**
+ * The default route normalisation (addendum A7): a pathname with anything
+ * that looks like an identifier replaced by a placeholder, so no uuid,
+ * numeric id, token or address ever reaches the raw table or a rollup. A
+ * host with a route manifest supplies its own and this is the fallback for
+ * paths it does not know. The query string and fragment never arrive here;
+ * the beacon sends the pathname and the collector strips again anyway.
+ */
+export function normalisePath(pathname) {
+    const raw = pathname.split(/[?#]/)[0] ?? '/';
+    const segments = raw.split('/').filter((s) => s.length > 0);
+    const out = segments.map((segment) => {
+        let s = segment;
+        try {
+            s = decodeURIComponent(segment);
+        }
+        catch {
+            return ':x';
+        }
+        if (UUID.test(s))
+            return ':id';
+        if (NUMERIC.test(s))
+            return ':n';
+        if (s.includes('@') || s.includes('=') || s.includes(':'))
+            return ':x';
+        if (HEXISH.test(s) || OPAQUE.test(s) || s.length > 48)
+            return ':x';
+        return s.toLowerCase();
+    });
+    const joined = `/${out.join('/')}`;
+    return joined.length > ANALYTICS_LIMITS.path ? joined.slice(0, ANALYTICS_LIMITS.path) : joined;
+}
+/** The host only: `https://www.example.com/a?b` becomes `www.example.com`; junk becomes null. */
+export function referrerHostOf(referrer) {
+    if (!referrer)
+        return null;
+    try {
+        const host = new URL(referrer).hostname.toLowerCase();
+        if (!host || host.length > ANALYTICS_LIMITS.referrerHost)
+            return null;
+        return host;
+    }
+    catch {
+        return null;
+    }
+}
+/** A device class from the user agent, which is then discarded. Coarse on purpose. */
+export function deviceOf(userAgent) {
+    if (!userAgent)
+        return 'unknown';
+    const ua = userAgent;
+    if (/bot|crawl|spider|slurp|fetch|headless|lighthouse|preview|monitor|curl|wget|python-requests/i.test(ua))
+        return 'bot';
+    if (/iPad|Tablet|PlayBook|Silk|Kindle/i.test(ua) || (/Android/i.test(ua) && !/Mobile/i.test(ua)))
+        return 'tablet';
+    if (/Mobi|iPhone|iPod|Android|BlackBerry|IEMobile|Opera Mini/i.test(ua))
+        return 'mobile';
+    return 'desktop';
+}
+/** Two upper-case letters or nothing; `cf-ipcountry` says `XX` and `T1` for unknown and Tor, which are not countries. */
+export function countryOf(header) {
+    return header && /^[A-Z]{2}$/.test(header) && header !== 'XX' && header !== 'T1' ? header : null;
+}
+/** The beacon's time, held to within the skew of arrival. */
+export function clampOccurredAt(at, receivedAt) {
+    const lo = receivedAt.getTime() - ANALYTICS_LIMITS.clockSkewMs;
+    const hi = receivedAt.getTime() + ANALYTICS_LIMITS.clockSkewMs;
+    return new Date(Math.min(hi, Math.max(lo, at)));
+}

package/dist/analytics/tasks.d.ts

@@ -0,0 +1,32 @@
+import type { Task, TaskContext } from '../housekeeping/index.js';
+import type { Db } from '../types.js';
+/** The weekly rollup's raw lookback: returning means seen in one of the four weeks before. */
+export declare const WEEKLY_LOOKBACK_DAYS = 28;
+/** The Monday of the ISO week holding `d`, at UTC midnight. */
+export declare const mondayOf: (d: Date) => Date;
+/**
+ * The daily rollup (addendum A3). Completed days first: from the day after
+ * the watermark up to yesterday, each day's aggregate set and the watermark
+ * move committed together, fenced by the claim token, in bounded batches
+ * with the lease renewed between them. Then the open day (today) is
+ * recomputed without moving the watermark, so the dashboard is current and
+ * history stays contiguous.
+ */
+export declare const rollupAnalytics: Task;
+/**
+ * The weekly rollup: completed ISO weeks (Monday to Sunday, wholly before
+ * today) from the week after its own watermark, then the open week
+ * recomputed. Its watermark is the Monday of the last completed week.
+ */
+export declare const rollupAnalyticsWeekly: Task;
+/**
+ * Raw rows leave by age, and never past what the rollups still need: the
+ * daily watermark, and the weekly watermark less its lookback, whichever is
+ * earlier. Until both rollups have completed a day there is nothing safe to
+ * prune, and the function says so.
+ */
+export declare const pruneAnalytics: Task;
+/** The earliest day the rollups still need, as an ISO date, or null when a rollup has not completed anything yet. */
+export declare function safePruneBoundary(db: Db): Promise<string | null>;
+export declare function pruneAnalyticsBatch(db: Db, days: number, batch: number, safeBefore: string): Promise<number>;
+export type { TaskContext };