@wtfalch/reporting 0.1.2 → 0.3.0

package/dist/analytics/tasks.js

@@ -0,0 +1,199 @@
+import { sql } from 'drizzle-orm';
+import { rowsOf } from '../housekeeping/tasks.js';
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+/** Completed days rolled up per run, so a long outage catches up in bounded steps under a renewed lease. */
+const CATCH_UP_DAYS = 14;
+/** The weekly rollup's raw lookback: returning means seen in one of the four weeks before. */
+export const WEEKLY_LOOKBACK_DAYS = 28;
+const iso = (d) => d.toISOString().slice(0, 10);
+const utcDay = (d) => new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+const addDays = (d, n) => new Date(d.getTime() + n * DAY);
+/** The Monday of the ISO week holding `d`, at UTC midnight. */
+export const mondayOf = (d) => {
+    const day = utcDay(d);
+    const dow = (day.getUTCDay() + 6) % 7;
+    return addDays(day, -dow);
+};
+async function rollupDay(db, day) {
+    const result = await db.execute(sql `select reporting_rollup_day(${day}::date) as n`);
+    return Number(rowsOf(result)[0]?.n ?? 0);
+}
+async function rollupWeek(db, monday) {
+    const result = await db.execute(sql `select reporting_rollup_week(${monday}::date) as n`);
+    return Number(rowsOf(result)[0]?.n ?? 0);
+}
+/** The first day worth rolling up when there is no watermark yet: the oldest raw row's day, or nothing. */
+async function firstRawDay(db) {
+    const result = await db.execute(sql `select min((occurred_at at time zone 'UTC')::date)::text as d from reporting_analytics`);
+    const d = rowsOf(result)[0]?.d;
+    return typeof d === 'string' && d.length === 10 ? d : null;
+}
+/**
+ * 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 const rollupAnalytics = {
+    name: 'reporting.rollup_analytics',
+    every: HOUR,
+    lease: 10 * 60 * 1000,
+    retry: 15 * 60 * 1000,
+    async run(ctx) {
+        const today = utcDay(ctx.now());
+        const yesterday = addDays(today, -1);
+        let cursor = ctx.watermark ? addDays(new Date(`${ctx.watermark}T00:00:00Z`), 1) : null;
+        if (!cursor) {
+            const first = await firstRawDay(ctx.db);
+            cursor = first ? new Date(`${first}T00:00:00Z`) : null;
+        }
+        let completed = 0;
+        while (cursor && cursor.getTime() <= yesterday.getTime() && completed < CATCH_UP_DAYS) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 60_000)
+                break;
+            const day = iso(cursor);
+            const moved = await ctx.db.transaction(async (tx) => {
+                await rollupDay(tx, day);
+                return ctx.commitWatermark(day, tx);
+            });
+            if (!moved) {
+                // The lease went to another process; its run owns the watermark now.
+                ctx.reporting.event({
+                    kind: 'reporting.rollup_yielded',
+                    level: 'warn',
+                    message: `rollup of ${day} yielded: the lease was lost before the watermark moved`,
+                    data: { day },
+                });
+                return;
+            }
+            completed += 1;
+            cursor = addDays(cursor, 1);
+            if (!(await ctx.renew()))
+                return;
+        }
+        // The open day, and yesterday if the catch-up has not reached it yet:
+        // recomputed for the dashboard, never vouched for.
+        const openFrom = cursor && cursor.getTime() < today.getTime() ? cursor : today;
+        for (let d = openFrom; d.getTime() <= today.getTime(); d = addDays(d, 1)) {
+            await rollupDay(ctx.db, iso(d));
+        }
+        if (completed > 0) {
+            ctx.reporting.event({
+                kind: 'reporting.rolled_up',
+                message: `rolled up ${completed} completed day(s), watermark ${iso(addDays(cursor ?? today, -1))}`,
+                data: { days: completed, watermark: iso(addDays(cursor ?? today, -1)) },
+            });
+        }
+    },
+};
+/**
+ * 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 const rollupAnalyticsWeekly = {
+    name: 'reporting.rollup_analytics_weekly',
+    every: DAY,
+    lease: 10 * 60 * 1000,
+    retry: HOUR,
+    async run(ctx) {
+        const today = utcDay(ctx.now());
+        const thisMonday = mondayOf(today);
+        let cursor = ctx.watermark
+            ? addDays(new Date(`${ctx.watermark}T00:00:00Z`), 7)
+            : null;
+        if (!cursor) {
+            const first = await firstRawDay(ctx.db);
+            cursor = first ? mondayOf(new Date(`${first}T00:00:00Z`)) : null;
+        }
+        let completed = 0;
+        while (cursor && cursor.getTime() < thisMonday.getTime() && completed < 26) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 60_000)
+                break;
+            const monday = iso(cursor);
+            const moved = await ctx.db.transaction(async (tx) => {
+                await rollupWeek(tx, monday);
+                return ctx.commitWatermark(monday, tx);
+            });
+            if (!moved)
+                return;
+            completed += 1;
+            cursor = addDays(cursor, 7);
+            if (!(await ctx.renew()))
+                return;
+        }
+        await rollupWeek(ctx.db, iso(thisMonday));
+    },
+};
+/**
+ * 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 const pruneAnalytics = {
+    name: 'reporting.prune_analytics',
+    every: HOUR,
+    lease: 10 * 60 * 1000,
+    retry: 15 * 60 * 1000,
+    async run(ctx) {
+        const days = ctx.settings['analytics.retention_days'];
+        const safeBefore = await safePruneBoundary(ctx.db);
+        if (!safeBefore)
+            return;
+        // The window's cutoff must fall before what the rollups still need. A
+        // window shorter than that (an operator's edit against a stalled
+        // rollup, or one shorter than the weekly lookback) defers pruning with
+        // a warning rather than failing every hour; the function refuses too.
+        const cutoffDay = iso(addDays(utcDay(ctx.now()), -days));
+        if (cutoffDay >= safeBefore) {
+            ctx.reporting.event({
+                kind: 'reporting.prune_deferred',
+                level: 'warn',
+                message: `analytics pruning deferred: a ${days}-day window would cut at ${cutoffDay}, but the rollups still need raw rows from ${safeBefore}`,
+                data: { days, cutoffDay, safeBefore },
+            });
+            return;
+        }
+        let total = 0;
+        for (let i = 0; i < 20; i += 1) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 30_000)
+                break;
+            const n = await pruneAnalyticsBatch(ctx.db, days, 5000, safeBefore);
+            total += n;
+            if (n < 5000)
+                break;
+            if (!(await ctx.renew()))
+                break;
+        }
+        if (total > 0) {
+            ctx.reporting.event({
+                kind: 'reporting.pruned_analytics',
+                message: `pruned ${total} analytics row(s) older than ${days} days`,
+                data: { rows: total, days, safeBefore },
+            });
+        }
+    },
+};
+/** The earliest day the rollups still need, as an ISO date, or null when a rollup has not completed anything yet. */
+export async function safePruneBoundary(db) {
+    const result = await db.execute(sql `select task, watermark from reporting_tasks where task in ('reporting.rollup_analytics', 'reporting.rollup_analytics_weekly')`);
+    const marks = new Map(rowsOf(result).map((r) => [String(r.task), r.watermark]));
+    const daily = marks.get('reporting.rollup_analytics');
+    const weekly = marks.get('reporting.rollup_analytics_weekly');
+    if (typeof daily !== 'string' || typeof weekly !== 'string')
+        return null;
+    const weeklyNeeds = addDays(new Date(`${weekly}T00:00:00Z`), -WEEKLY_LOOKBACK_DAYS);
+    const dailyDate = new Date(`${daily}T00:00:00Z`);
+    return iso(weeklyNeeds.getTime() < dailyDate.getTime() ? weeklyNeeds : dailyDate);
+}
+export async function pruneAnalyticsBatch(db, days, batch, safeBefore) {
+    return db.transaction(async (tx) => {
+        await tx.execute(sql `set local statement_timeout = '30s'`);
+        const result = await tx.execute(sql `select reporting_prune_analytics(make_interval(days => ${days}::int), ${batch}::int, ${safeBefore}::date) as n`);
+        return Number(rowsOf(result)[0]?.n ?? 0);
+    });
+}

package/dist/analytics/write.d.ts

@@ -0,0 +1,19 @@
+import type { Db } from '../types.js';
+import type { Device } from './schema.js';
+/** One raw row as the collector or `track` writes it; every field already validated and normalised. */
+export interface AnalyticsRow {
+    readonly occurredAt: Date;
+    readonly receivedAt: Date;
+    readonly site: string;
+    readonly tenantId: string | null;
+    readonly visitorId: string | null;
+    readonly sessionId: string | null;
+    readonly userId: string | null;
+    readonly name: string;
+    readonly path: string;
+    readonly referrerHost: string | null;
+    readonly device: Device;
+    readonly country: string | null;
+    readonly props: Record<string, string | number | boolean | null>;
+}
+export declare function insertAnalytics(db: Db, rows: readonly AnalyticsRow[]): Promise<void>;

package/dist/analytics/write.js

@@ -0,0 +1,20 @@
+import { reportingAnalytics } from '../tables.js';
+export async function insertAnalytics(db, rows) {
+    if (rows.length === 0)
+        return;
+    await db.insert(reportingAnalytics).values(rows.map((r) => ({
+        occurredAt: r.occurredAt,
+        receivedAt: r.receivedAt,
+        site: r.site,
+        tenantId: r.tenantId,
+        visitorId: r.visitorId,
+        sessionId: r.sessionId,
+        userId: r.userId,
+        name: r.name,
+        path: r.path,
+        referrerHost: r.referrerHost,
+        device: r.device,
+        country: r.country,
+        props: r.props,
+    })));
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The beacon: `page.view` on load and on history changes, `page.leave` with
+ * the seconds on the page, and whatever the host `track`s, batched twenty at
+ * a time or every five seconds and posted with `sendBeacon` (falling back to
+ * `fetch` with `keepalive`). It sends the pathname, never the query string,
+ * and never a user id: the collector knows who is signed in from the session
+ * cookie, and a client-supplied id would be a claim (D14).
+ *
+ * Consent (D15): `none` keeps nothing; `consented` starts as `none` until
+ * `accept()`; `always` sets the first-party cookie without asking. The cookie
+ * `_rp` holds the visitor id and the answer, one year, SameSite=Lax, Secure;
+ * the session id lives in `sessionStorage` under `consented`/`always` and in
+ * memory under `none`. Nothing about the browser is stored beyond that.
+ *
+ * With `errors: true` (docs/plans/errors.md, "Surface"), the beacon also
+ * listens for `window.onerror` and `unhandledrejection` and posts them to
+ * `errorCollector` with the same transport and batching as everything
+ * above — capped at 5 distinct errors and 20 sends total per page load, so
+ * a render loop throwing every frame cannot become a request flood.
+ *
+ * No dependencies, no globals beyond `window`; under 3 KB gzipped.
+ */
+export type ConsentMode = 'none' | 'consented' | 'always';
+export type ConsentAnswer = 'accepted' | 'declined' | null;
+export interface BeaconOptions {
+    /** The collector URL, same-origin (`/api/reporting/collect`) or the hub's. */
+    readonly collector: string;
+    /** This app's site id. */
+    readonly site: string;
+    readonly consent?: ConsentMode;
+    /** Batch size and flush interval; the defaults are the collector's caps. */
+    readonly batch?: number;
+    readonly flushMs?: number;
+    /** For tests: the window to observe and the transport to post with. */
+    readonly window?: Window;
+    readonly send?: (url: string, body: string) => void;
+    /** `window.onerror` + `unhandledrejection`, capped and de-duplicated. Default false. */
+    readonly errors?: boolean;
+    /** The route `clientErrorHandler` (./next) is mounted at. Required when `errors` is true. */
+    readonly errorCollector?: string;
+}
+export interface Beacon {
+    track(name: string, props?: Record<string, string | number | boolean | null>): void;
+    pageView(): void;
+    /** The person's answer under `consented`; sets or clears the cookie and remembers it. */
+    accept(): void;
+    decline(): void;
+    answer(): ConsentAnswer;
+    visitorId(): string | null;
+    flush(): void;
+    destroy(): void;
+}
+export declare function createBeacon(options: BeaconOptions): Beacon;

package/dist/browser/index.js

@@ -0,0 +1,330 @@
+/**
+ * The beacon: `page.view` on load and on history changes, `page.leave` with
+ * the seconds on the page, and whatever the host `track`s, batched twenty at
+ * a time or every five seconds and posted with `sendBeacon` (falling back to
+ * `fetch` with `keepalive`). It sends the pathname, never the query string,
+ * and never a user id: the collector knows who is signed in from the session
+ * cookie, and a client-supplied id would be a claim (D14).
+ *
+ * Consent (D15): `none` keeps nothing; `consented` starts as `none` until
+ * `accept()`; `always` sets the first-party cookie without asking. The cookie
+ * `_rp` holds the visitor id and the answer, one year, SameSite=Lax, Secure;
+ * the session id lives in `sessionStorage` under `consented`/`always` and in
+ * memory under `none`. Nothing about the browser is stored beyond that.
+ *
+ * With `errors: true` (docs/plans/errors.md, "Surface"), the beacon also
+ * listens for `window.onerror` and `unhandledrejection` and posts them to
+ * `errorCollector` with the same transport and batching as everything
+ * above — capped at 5 distinct errors and 20 sends total per page load, so
+ * a render loop throwing every frame cannot become a request flood.
+ *
+ * No dependencies, no globals beyond `window`; under 3 KB gzipped.
+ */
+const COOKIE = '_rp';
+const YEAR = 365 * 24 * 60 * 60;
+const NAME = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+function randomId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let s = '';
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}
+function readCookie(doc) {
+    const m = doc.cookie.match(new RegExp(`(?:^|; )${COOKIE}=([^;]*)`));
+    if (!m?.[1])
+        return null;
+    const [id, answer] = decodeURIComponent(m[1]).split('.');
+    if (!id || !/^[a-f0-9]{32}$/.test(id))
+        return null;
+    return { id, answer: answer === 'a' ? 'accepted' : answer === 'd' ? 'declined' : null };
+}
+function writeCookie(doc, value) {
+    doc.cookie =
+        value === null
+            ? `${COOKIE}=; Max-Age=0; Path=/; SameSite=Lax; Secure`
+            : `${COOKIE}=${encodeURIComponent(value)}; Max-Age=${YEAR}; Path=/; SameSite=Lax; Secure`;
+}
+export function createBeacon(options) {
+    const win = options.window ?? window;
+    const doc = win.document;
+    const mode = options.consent ?? 'consented';
+    const batchSize = Math.min(20, options.batch ?? 20);
+    const flushMs = options.flushMs ?? 5000;
+    const send = options.send ??
+        ((url, body) => {
+            const blob = new Blob([body], { type: 'application/json' });
+            if (!win.navigator.sendBeacon?.(url, blob)) {
+                void win.fetch(url, { method: 'POST', body, keepalive: true, credentials: 'include' });
+            }
+        });
+    // Identity: a visitor id only with consent; a session id per tab.
+    let cookie = readCookie(doc);
+    let answer = cookie?.answer ?? null;
+    const declined = () => mode === 'none' || (mode === 'consented' && answer !== 'accepted');
+    if (mode === 'always' && !cookie) {
+        cookie = { id: randomId(), answer: 'accepted' };
+        writeCookie(doc, `${cookie.id}.a`);
+    }
+    if (declined()) {
+        if (cookie && answer !== 'declined')
+            cookie = null;
+    }
+    let sessionId = null;
+    function inMemorySession() {
+        if (!sessionId)
+            sessionId = randomId();
+        return sessionId;
+    }
+    function session() {
+        if (declined())
+            return inMemorySession();
+        try {
+            const stored = win.sessionStorage.getItem(`${COOKIE}s`);
+            if (stored && /^[a-f0-9]{32}$/.test(stored))
+                return stored;
+            const fresh = randomId();
+            win.sessionStorage.setItem(`${COOKIE}s`, fresh);
+            return fresh;
+        }
+        catch {
+            return inMemorySession();
+        }
+    }
+    const queue = [];
+    let timer = null;
+    function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (queue.length === 0)
+            return;
+        const events = queue.splice(0, batchSize);
+        const body = JSON.stringify({
+            site: options.site,
+            visitorId: declined() ? null : (cookie?.id ?? null),
+            sessionId: session(),
+            events,
+        });
+        try {
+            send(options.collector, body);
+        }
+        catch {
+            // A beacon that cannot leave is dropped; nothing here may throw into the page.
+        }
+        if (queue.length > 0)
+            flush();
+    }
+    function push(event) {
+        queue.push(event);
+        if (queue.length >= batchSize)
+            flush();
+        else if (!timer)
+            timer = setTimeout(flush, flushMs);
+    }
+    // Errors: window.onerror + unhandledrejection, capped and de-duplicated
+    // (docs/plans/errors.md, "Surface"). A render loop throwing every frame
+    // must not become a request flood: at most 5 distinct errors — by kind +
+    // message + first stack line — and 20 sends total are ever posted per
+    // page load; a repeat past the first occurrence only bumps a counter
+    // kept in memory, never resent. Same transport, same batching and the
+    // same destroy() teardown as the queue above.
+    const ERROR_DISTINCT_MAX = 5;
+    const ERROR_TOTAL_MAX = 20;
+    let errCleanup = null;
+    if (options.errors && options.errorCollector) {
+        const errorCollector = options.errorCollector;
+        const seen = new Map();
+        let total = 0;
+        const errQueue = [];
+        let errTimer = null;
+        function errFlush() {
+            if (errTimer) {
+                clearTimeout(errTimer);
+                errTimer = null;
+            }
+            if (errQueue.length === 0)
+                return;
+            const errors = errQueue.splice(0, batchSize);
+            const body = JSON.stringify({ site: options.site, errors });
+            try {
+                send(errorCollector, body);
+            }
+            catch {
+                // Same rule as the transport above: never throw into the page.
+            }
+            if (errQueue.length > 0)
+                errFlush();
+        }
+        function errPush(entry) {
+            errQueue.push(entry);
+            if (errQueue.length >= batchSize)
+                errFlush();
+            else if (!errTimer)
+                errTimer = setTimeout(errFlush, flushMs);
+        }
+        // A query string can carry a token; a stack's frame URLs are the only
+        // place one could hide here, stripped exactly as the collector strips
+        // one from a pathname (analytics/schema.ts's normalisePath).
+        function stripQuery(text) {
+            return text.replace(/\?[^\s:)]*/g, '');
+        }
+        // The literal first line of `.stack` is just `kind: message` again
+        // (V8) or, on Firefox, already a frame; either way the second line is
+        // the first real call frame when there is one — what actually tells
+        // two same-kind, same-message errors apart.
+        function firstStackLine(stack) {
+            if (!stack)
+                return '';
+            const lines = stack.split('\n');
+            return (lines[1] ?? lines[0] ?? '').trim();
+        }
+        function record(kind, message, stack) {
+            const cleanMessage = stripQuery(message);
+            const cleanStack = stack === null ? null : stripQuery(stack);
+            const key = `${kind}\u0000${cleanMessage}\u0000${firstStackLine(cleanStack)}`;
+            const count = seen.get(key);
+            if (count !== undefined) {
+                seen.set(key, count + 1);
+                return; // a repeat: counted, never resent.
+            }
+            if (seen.size >= ERROR_DISTINCT_MAX || total >= ERROR_TOTAL_MAX)
+                return;
+            seen.set(key, 1);
+            total += 1;
+            errPush({ kind, message: cleanMessage, stack: cleanStack });
+        }
+        function describeReason(reason, fallbackKind) {
+            if (reason instanceof Error) {
+                return {
+                    kind: reason.name || fallbackKind,
+                    message: reason.message || fallbackKind,
+                    stack: typeof reason.stack === 'string' ? reason.stack : null,
+                };
+            }
+            if (typeof reason === 'string')
+                return { kind: fallbackKind, message: reason, stack: null };
+            try {
+                return {
+                    kind: fallbackKind,
+                    message: JSON.stringify(reason) ?? String(reason),
+                    stack: null,
+                };
+            }
+            catch {
+                return { kind: fallbackKind, message: fallbackKind, stack: null };
+            }
+        }
+        const onError = (event) => {
+            // A cross-origin script with no CORS grant reports exactly this
+            // message, with no line, column or Error object: nothing here is
+            // useful, and every throw from a foreign <script> would otherwise
+            // repeat it.
+            if (event.message === 'Script error.')
+                return;
+            if (event.error instanceof Error || typeof event.error === 'string') {
+                const info = describeReason(event.error, 'Error');
+                record(info.kind, info.message, info.stack);
+            }
+            else {
+                record('Error', event.message || 'Error', null);
+            }
+        };
+        const onRejection = (event) => {
+            const info = describeReason(event.reason, 'UnhandledRejection');
+            record(info.kind, info.message, info.stack);
+        };
+        win.addEventListener('error', onError);
+        win.addEventListener('unhandledrejection', onRejection);
+        errCleanup = () => {
+            errFlush();
+            win.removeEventListener('error', onError);
+            win.removeEventListener('unhandledrejection', onRejection);
+        };
+    }
+    const pathOf = () => win.location.pathname || '/';
+    let currentPath = pathOf();
+    let enteredAt = Date.now();
+    let lastReferrer = doc.referrer || null;
+    function pageView() {
+        currentPath = pathOf();
+        enteredAt = Date.now();
+        push({
+            name: 'page.view',
+            at: Date.now(),
+            path: currentPath,
+            referrer: lastReferrer,
+            props: {},
+        });
+        lastReferrer = null;
+    }
+    function pageLeave() {
+        const duration = Math.max(0, Math.round((Date.now() - enteredAt) / 1000));
+        push({ name: 'page.leave', at: Date.now(), path: currentPath, props: {}, duration });
+        flush();
+    }
+    function track(name, props = {}) {
+        if (!NAME.test(name) || name.startsWith('page.'))
+            return;
+        push({ name, at: Date.now(), path: pathOf(), props });
+    }
+    // History: a SPA navigation is a page view too.
+    const history = win.history;
+    const pushState = history.pushState.bind(history);
+    const replaceState = history.replaceState.bind(history);
+    const onNavigate = () => {
+        if (pathOf() === currentPath)
+            return;
+        pageLeave();
+        pageView();
+    };
+    history.pushState = (...args) => {
+        pushState(...args);
+        onNavigate();
+    };
+    history.replaceState = (...args) => {
+        replaceState(...args);
+        onNavigate();
+    };
+    const onPop = () => onNavigate();
+    const onHide = () => {
+        if (doc.visibilityState === 'hidden')
+            pageLeave();
+    };
+    win.addEventListener('popstate', onPop);
+    doc.addEventListener('visibilitychange', onHide);
+    win.addEventListener('pagehide', pageLeave);
+    pageView();
+    return {
+        track,
+        pageView,
+        accept() {
+            if (mode !== 'consented')
+                return;
+            answer = 'accepted';
+            cookie = { id: cookie?.id ?? randomId(), answer };
+            writeCookie(doc, `${cookie.id}.a`);
+        },
+        decline() {
+            if (mode !== 'consented')
+                return;
+            answer = 'declined';
+            cookie = null;
+            writeCookie(doc, `${randomId()}.d`);
+        },
+        answer: () => answer,
+        visitorId: () => (declined() ? null : (cookie?.id ?? null)),
+        flush,
+        destroy() {
+            flush();
+            errCleanup?.();
+            history.pushState = pushState;
+            history.replaceState = replaceState;
+            win.removeEventListener('popstate', onPop);
+            doc.removeEventListener('visibilitychange', onHide);
+            win.removeEventListener('pagehide', pageLeave);
+        },
+    };
+}

package/dist/errors/capture.d.ts

@@ -0,0 +1,52 @@
+import type { CaptureContext, Db, EventInput, Logger } from '../types.js';
+/**
+ * The one path an uncaught exception takes into the estate
+ * (docs/plans/errors.md, "Surface" and "Why a second table, not just an
+ * event row"): one `reporting_events` row for the timeline, through the
+ * writer's own `event()` so it shares its queue, batching and logger line,
+ * and one upsert into the fingerprint's group — first seen, last seen, how
+ * many, and whether an operator has already dealt with it.
+ *
+ * Two contracts this must never break, both sharpened from the writer's own
+ * (writer.ts's header comment) for an error reporter specifically:
+ *
+ * 1. A capture must never carry a secret. Redaction runs on `message` and
+ *    `stack` before anything else touches them — a stack is the likeliest
+ *    way a wrapping key leaves the process (redact.ts) — and the
+ *    fingerprint is computed on that same redacted text, so a secret can
+ *    never reach the digest basis either.
+ * 2. A capture must never throw back into the code that threw the original
+ *    error. The whole body of `captureError` is one try/catch, and the
+ *    group upsert — the one part of this that touches a database that can
+ *    be down — is scheduled through the host's `defer` and wrapped in its
+ *    own catch, exactly as the writer's flush protects the request from a
+ *    failed insert. An error reporter that itself throws while reporting an
+ *    error is the one failure mode worse than not reporting it.
+ */
+export interface CaptureOptions {
+    readonly db: Db;
+    readonly log: Logger;
+    readonly site: string;
+    readonly now: () => Date;
+    /** Runs the group upsert after the current unit of work, same as the writer's flush (writer.ts). */
+    readonly defer: (fn: () => Promise<void>) => void;
+    /** The Writer's own `event()`, so the timeline row shares its queue, batching and logger line. */
+    readonly event: (input: EventInput) => void;
+    /** Stamped on a fresh group when a capture's own context supplies none. */
+    readonly release?: string | null;
+}
+/**
+ * `captureError(error, context?)`: the class from `errorKind` (or the
+ * context's own, when the caller already knows it), the message and stack
+ * from the value itself — never assuming it is an `Error` — redacted before
+ * anything else touches them, bounded to what the table accepts, then
+ * fingerprinted on that same redacted, bounded text so a secret can never
+ * reach the digest either.
+ *
+ * Writes the timeline row synchronously through `o.event()` (the writer
+ * queues and logs it), then schedules the group upsert through `o.defer` —
+ * no timer of its own, same as the writer's flush. The whole body is one
+ * try/catch: nothing here may throw back into the code that threw the
+ * original error.
+ */
+export declare function createCapture(o: CaptureOptions): (error: unknown, context?: CaptureContext) => void;