@wtfalch/reporting 0.1.2 → 0.3.0

package/dist/next/index.d.ts

@@ -1,4 +1,7 @@
+import { type CollectorOptions } from '../analytics/collector.js';
+import { deviceOf } from '../analytics/schema.js';
 import type { Reporting } from '../types.js';
+import { type ClientErrorCollectorOptions } from './client-errors.js';
 /**
  * The Next bindings: everything in the package that knows what a request is.
  * Peer on `next`; a host without Next never imports this entry.
@@ -38,3 +41,55 @@ export declare const deferWithAfter: (fn: () => Promise<void>) => void;
 export declare function registerShutdownFlush(reporting: Reporting, opts?: {
     deadlineMs?: number;
 }): void;
+/**
+ * The collector as a route handler: mount as `POST` and `OPTIONS` of a public
+ * route (`// authz: public`). Always 204. `getUserId` reads the host's
+ * session for same-origin beacons; a beacon from an allowed foreign origin
+ * never reaches it.
+ */
+export declare function collectHandler(options: Omit<CollectorOptions, 'log' | 'site'> & {
+    readonly reporting: Reporting;
+}): (request: Request) => Promise<Response>;
+/**
+ * `onRequestError` from Next's instrumentation hook
+ * (`next/dist/server/instrumentation/types.d.ts`, `InstrumentationOnRequestError`).
+ * Declared locally: no public `next` subpath exports the type, and this is
+ * the exact shape the compiled server calls it with
+ * (`base-server.js`'s `instrumentationOnRequestError`).
+ */
+export type NextOnRequestError = (error: unknown, request: Readonly<{
+    path: string;
+    method: string;
+    headers: NodeJS.Dict<string | string[]>;
+}>, context: Readonly<{
+    routerKind: string;
+    routePath: string;
+    routeType: string;
+}>) => void | Promise<void>;
+/**
+ * Binds `reporting.captureError` to Next's `onRequestError`
+ * (docs/plans/errors.md, "Surface"). `runtime` is `edge` exactly when
+ * `NEXT_RUNTIME` says so — the same signal Next's own compiled server
+ * branches on (e.g. `dist/server/app-render/action-handler.js`), because
+ * the error context Next hands this hook carries no runtime field of its
+ * own. `requestId` is derived the same way `requestContext()` derives one:
+ * Cloudflare's `cf-ray`, else a fresh uuid.
+ *
+ * Never throws: Next calls this while already handling an error, and a
+ * reporter that throws back is the one failure worse than not reporting —
+ * the same rule `captureError` itself already keeps (errors/capture.ts).
+ * This catch is defence in depth for a `reporting` that violates it.
+ */
+export declare function errorHandler(reporting: Reporting): NextOnRequestError;
+/**
+ * The public ingest route for browser-reported errors: mount as `POST`
+ * (docs/plans/errors.md, "Surface"; `// authz: public`). See
+ * `createClientErrorCollector` (./client-errors.js) for the caps, the
+ * origin allowance and why identity is never the body's.
+ */
+export declare function clientErrorHandler(options: ClientErrorCollectorOptions): (request: Request) => Promise<Response>;
+/** Device and country for a server-side `track`, from the request's headers; nothing else is kept. */
+export declare function trackContext(): Promise<{
+    device: ReturnType<typeof deviceOf>;
+    country: string | null;
+}>;

package/dist/next/index.js

@@ -2,6 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { headers } from 'next/headers';
 import { unstable_rethrow } from 'next/navigation';
 import { after, connection } from 'next/server';
+import { createCollector } from '../analytics/collector.js';
+import { countryOf, deviceOf } from '../analytics/schema.js';
+import { createClientErrorCollector } from './client-errors.js';
 /**
  * The Next bindings: everything in the package that knows what a request is.
  * Peer on `next`; a host without Next never imports this entry.
@@ -71,3 +74,72 @@ export function registerShutdownFlush(reporting, opts = {}) {
         void reporting.flush({ deadlineMs: opts.deadlineMs ?? 2000 });
     });
 }
+/**
+ * The collector as a route handler: mount as `POST` and `OPTIONS` of a public
+ * route (`// authz: public`). Always 204. `getUserId` reads the host's
+ * session for same-origin beacons; a beacon from an allowed foreign origin
+ * never reaches it.
+ */
+export function collectHandler(options) {
+    const { reporting, ...rest } = options;
+    const collector = createCollector({ ...rest, log: reporting.log, site: reporting.site });
+    return (request) => collector.handle(request);
+}
+function headerValue(dict, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(dict)) {
+        if (key.toLowerCase() !== lower)
+            continue;
+        const value = dict[key];
+        return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+    }
+    return null;
+}
+/**
+ * Binds `reporting.captureError` to Next's `onRequestError`
+ * (docs/plans/errors.md, "Surface"). `runtime` is `edge` exactly when
+ * `NEXT_RUNTIME` says so — the same signal Next's own compiled server
+ * branches on (e.g. `dist/server/app-render/action-handler.js`), because
+ * the error context Next hands this hook carries no runtime field of its
+ * own. `requestId` is derived the same way `requestContext()` derives one:
+ * Cloudflare's `cf-ray`, else a fresh uuid.
+ *
+ * Never throws: Next calls this while already handling an error, and a
+ * reporter that throws back is the one failure worse than not reporting —
+ * the same rule `captureError` itself already keeps (errors/capture.ts).
+ * This catch is defence in depth for a `reporting` that violates it.
+ */
+export function errorHandler(reporting) {
+    return (error, request) => {
+        try {
+            const runtime = process.env.NEXT_RUNTIME === 'edge' ? 'edge' : 'server';
+            const ray = headerValue(request.headers, 'cf-ray');
+            const requestId = ray && RAY_PATTERN.test(ray) ? ray : randomUUID();
+            reporting.captureError(error, { runtime, requestId });
+        }
+        catch {
+            // See the doc comment above: this must never throw back into Next.
+        }
+    };
+}
+/**
+ * The public ingest route for browser-reported errors: mount as `POST`
+ * (docs/plans/errors.md, "Surface"; `// authz: public`). See
+ * `createClientErrorCollector` (./client-errors.js) for the caps, the
+ * origin allowance and why identity is never the body's.
+ */
+export function clientErrorHandler(options) {
+    const collector = createClientErrorCollector(options);
+    return (request) => collector.handle(request);
+}
+/** Device and country for a server-side `track`, from the request's headers; nothing else is kept. */
+export async function trackContext() {
+    try {
+        const h = await headers();
+        return { device: deviceOf(h.get('user-agent')), country: countryOf(h.get('cf-ipcountry')) };
+    }
+    catch (error) {
+        unstable_rethrow(error);
+        return { device: 'unknown', country: null };
+    }
+}

package/dist/react/charts.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+/**
+ * Two server-renderable pictures for the readers' pages, inline SVG with no
+ * dependency: a sparkline over a series and a bar list over buckets. Colours
+ * come from `currentColor` and CSS variables the host sets, so the host's
+ * theme applies.
+ */
+export declare function Sparkline(props: {
+    readonly points: readonly {
+        readonly day: string;
+        readonly value: number;
+    }[];
+    readonly width?: number;
+    readonly height?: number;
+    readonly label?: string;
+}): import("react").JSX.Element;
+export declare function BarList(props: {
+    readonly items: readonly {
+        readonly key: string;
+        readonly value: number;
+        readonly hint?: ReactNode;
+    }[];
+    readonly label?: string;
+}): import("react").JSX.Element;

package/dist/react/charts.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Two server-renderable pictures for the readers' pages, inline SVG with no
+ * dependency: a sparkline over a series and a bar list over buckets. Colours
+ * come from `currentColor` and CSS variables the host sets, so the host's
+ * theme applies.
+ */
+export function Sparkline(props) {
+    const w = props.width ?? 320;
+    const h = props.height ?? 64;
+    const values = props.points.map((p) => p.value);
+    const max = Math.max(1, ...values);
+    const n = Math.max(1, values.length - 1);
+    const coords = values.map((v, i) => [(i / n) * (w - 2) + 1, h - 1 - (v / max) * (h - 2)]);
+    const line = coords
+        .map(([x, y], i) => `${i === 0 ? 'M' : 'L'}${x.toFixed(1)} ${y.toFixed(1)}`)
+        .join(' ');
+    const area = coords.length > 0 ? `${line} L${(w - 1).toFixed(1)} ${h - 1} L1 ${h - 1} Z` : '';
+    const last = coords.at(-1);
+    return (_jsxs("svg", { viewBox: `0 0 ${w} ${h}`, width: "100%", height: h, role: "img", "aria-label": props.label ?? `${values.length} days, up to ${max}`, preserveAspectRatio: "none", style: { display: 'block', maxWidth: '100%' }, children: [_jsx("title", { children: props.label ?? `${values.length} days, up to ${max}` }), area ? _jsx("path", { d: area, fill: "currentColor", opacity: "0.12" }) : null, line ? _jsx("path", { d: line, fill: "none", stroke: "currentColor", strokeWidth: "1.5" }) : null, last ? _jsx("circle", { cx: last[0], cy: last[1], r: "2.5", fill: "currentColor" }) : null] }));
+}
+export function BarList(props) {
+    const max = Math.max(1, ...props.items.map((i) => i.value));
+    return (_jsx("ol", { "data-reporting-bars": "", "aria-label": props.label, style: { listStyle: 'none', margin: 0, padding: 0 }, children: props.items.map((item) => (_jsxs("li", { style: {
+                display: 'grid',
+                gridTemplateColumns: '1fr auto',
+                gap: '0.5rem',
+                alignItems: 'center',
+                padding: '0.25rem 0',
+            }, children: [_jsxs("div", { style: { position: 'relative', minWidth: 0 }, children: [_jsx("div", { "aria-hidden": "true", style: {
+                                position: 'absolute',
+                                inset: 0,
+                                width: `${(item.value / max) * 100}%`,
+                                background: 'currentColor',
+                                opacity: 0.1,
+                                borderRadius: 2,
+                            } }), _jsxs("span", { style: {
+                                position: 'relative',
+                                overflow: 'hidden',
+                                textOverflow: 'ellipsis',
+                                whiteSpace: 'nowrap',
+                                display: 'block',
+                                padding: '0 0.375rem',
+                            }, children: [item.key, item.hint ? (_jsx("span", { style: { opacity: 0.6, marginLeft: '0.5rem' }, children: item.hint })) : null] })] }), _jsx("span", { style: { fontVariantNumeric: 'tabular-nums' }, children: item.value.toLocaleString() })] }, item.key))) }));
+}

package/dist/react/errors.d.ts

@@ -0,0 +1,12 @@
+import type { ReportingErrorRow } from '../tables.js';
+/**
+ * The operator's error list: a plain table over the rows `errorsPage()`
+ * already returned, newest last-seen first — the same props-in split as
+ * `charts.tsx`, no fetching and no client state. The stack and the rest of
+ * one group's detail belong in a detail view, not here; this table only ever
+ * renders the group's summary columns.
+ */
+export declare function ErrorsTable(props: {
+    readonly rows: readonly ReportingErrorRow[];
+    readonly label?: string;
+}): import("react").JSX.Element;

package/dist/react/errors.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The operator's error list: a plain table over the rows `errorsPage()`
+ * already returned, newest last-seen first — the same props-in split as
+ * `charts.tsx`, no fetching and no client state. The stack and the rest of
+ * one group's detail belong in a detail view, not here; this table only ever
+ * renders the group's summary columns.
+ */
+export function ErrorsTable(props) {
+    if (props.rows.length === 0) {
+        return _jsx("p", { "data-reporting-errors-empty": "", children: "No errors captured. All clear." });
+    }
+    return (_jsxs("table", { "data-reporting-errors": "", "aria-label": props.label ?? 'Errors, newest last seen first', children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Kind" }), _jsx("th", { scope: "col", children: "Message" }), _jsx("th", { scope: "col", children: "Occurrences" }), _jsx("th", { scope: "col", children: "First seen" }), _jsx("th", { scope: "col", children: "Last seen" }), _jsx("th", { scope: "col", children: "Runtime" }), _jsx("th", { scope: "col", children: "Release" }), _jsx("th", { scope: "col", children: "State" })] }) }), _jsx("tbody", { children: props.rows.map((row) => (_jsxs("tr", { children: [_jsx("td", { children: row.kind }), _jsx("td", { style: { maxWidth: '32rem', overflowWrap: 'anywhere', wordBreak: 'break-word' }, title: row.message, children: row.message }), _jsx("td", { style: { fontVariantNumeric: 'tabular-nums' }, children: String(row.occurrences) }), _jsx("td", { children: formatTimestamp(row.firstSeenAt) }), _jsx("td", { children: formatTimestamp(row.lastSeenAt) }), _jsx("td", { children: row.runtime }), _jsx("td", { children: row.release ?? '—' }), _jsx("td", { children: row.state })] }, row.fingerprint))) })] }));
+}
+function formatTimestamp(value) {
+    return `${value.toISOString().slice(0, 19).replace('T', ' ')} UTC`;
+}

package/dist/react/index.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+import { type ConsentMode } from '../browser/index.js';
+export declare function ReportingProvider(props: {
+    readonly collector: string;
+    readonly site: string;
+    readonly consent?: ConsentMode;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** `track(name, props)` from a client component; a no-op before the beacon mounts. */
+export declare function useTrack(): (name: string, props?: Record<string, string | number | boolean | null>) => void;
+/**
+ * The consent question, shown only under `consented` and only until it is
+ * answered. The host supplies the words; the control supplies the two
+ * buttons and remembers the answer through the beacon's cookie.
+ */
+export declare function ConsentControl(props: {
+    readonly children: ReactNode;
+    readonly acceptLabel?: string;
+    readonly declineLabel?: string;
+    readonly className?: string;
+}): import("react").JSX.Element | null;

package/dist/react/index.js

@@ -0,0 +1,52 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { createBeacon, } from '../browser/index.js';
+const ReportingContext = createContext({
+    beacon: null,
+    answer: null,
+    mode: 'none',
+    accept: () => undefined,
+    decline: () => undefined,
+});
+export function ReportingProvider(props) {
+    const [beacon, setBeacon] = useState(null);
+    const [answer, setAnswer] = useState(null);
+    const mode = props.consent ?? 'consented';
+    useEffect(() => {
+        const b = createBeacon({ collector: props.collector, site: props.site, consent: mode });
+        setBeacon(b);
+        setAnswer(b.answer());
+        return () => b.destroy();
+    }, [props.collector, props.site, mode]);
+    const value = useMemo(() => ({
+        beacon,
+        answer,
+        mode,
+        accept() {
+            beacon?.accept();
+            setAnswer(beacon?.answer() ?? null);
+        },
+        decline() {
+            beacon?.decline();
+            setAnswer(beacon?.answer() ?? null);
+        },
+    }), [beacon, answer, mode]);
+    return _jsx(ReportingContext.Provider, { value: value, children: props.children });
+}
+/** `track(name, props)` from a client component; a no-op before the beacon mounts. */
+export function useTrack() {
+    const { beacon } = useContext(ReportingContext);
+    return (name, props) => beacon?.track(name, props);
+}
+/**
+ * The consent question, shown only under `consented` and only until it is
+ * answered. The host supplies the words; the control supplies the two
+ * buttons and remembers the answer through the beacon's cookie.
+ */
+export function ConsentControl(props) {
+    const { answer, mode, accept, decline, beacon } = useContext(ReportingContext);
+    if (mode !== 'consented' || answer !== null || !beacon)
+        return null;
+    return (_jsxs("section", { "data-reporting-consent": "", className: props.className, "aria-label": "Analytics consent", children: [props.children, _jsxs("div", { "data-reporting-consent-actions": "", children: [_jsx("button", { type: "button", "data-reporting-consent-decline": "", onClick: decline, children: props.declineLabel ?? 'No thanks' }), _jsx("button", { type: "button", "data-reporting-consent-accept": "", onClick: accept, children: props.acceptLabel ?? 'Allow' })] })] }));
+}

package/dist/schema.d.ts

@@ -9,9 +9,15 @@ export declare const LEVELS: readonly ["info", "warn", "error", "alert"];
 export type Level = (typeof LEVELS)[number];
 export declare const ACTOR_CLASSES: readonly ["human", "api_key", "agent", "service"];
 export type ActorClass = (typeof ACTOR_CLASSES)[number];
+export declare const ERROR_STATES: readonly ["open", "resolved", "ignored"];
+export type ErrorState = (typeof ERROR_STATES)[number];
+export declare const ERROR_RUNTIMES: readonly ["server", "edge", "browser"];
+export type ErrorRuntime = (typeof ERROR_RUNTIMES)[number];
 /** `namespace.name`: one dot, lower case, digits and underscores. */
 export declare const KIND_PATTERN: RegExp;
 export declare const SITE_PATTERN: RegExp;
+/** sha256 of the kind and the top normalised frames, truncated to 32 hex, lower case. */
+export declare const FINGERPRINT_PATTERN: RegExp;
 /**
  * Keys a `data` object may not carry, because each names a person or a
  * secret. A guardrail against the accidental case, not proof of absence: a
@@ -27,6 +33,7 @@ export declare const LIMITS: {
     readonly targetId: 256;
     readonly dataBytes: 16384;
     readonly site: 64;
+    readonly stack: 16384;
 };
 /** Flat, bounded, banned keys refused, numbers finite. */
 export declare const flatDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
@@ -83,3 +90,4 @@ export declare const eventInputSchema: z.ZodObject<{
 export type EventInput = z.input<typeof eventInputSchema>;
 export type ValidEvent = z.output<typeof eventInputSchema>;
 export declare const siteSchema: z.ZodString;
+export declare const fingerprintSchema: z.ZodString;

package/dist/schema.js

@@ -7,9 +7,13 @@ import { z } from 'zod';
  */
 export const LEVELS = ['info', 'warn', 'error', 'alert'];
 export const ACTOR_CLASSES = ['human', 'api_key', 'agent', 'service'];
+export const ERROR_STATES = ['open', 'resolved', 'ignored'];
+export const ERROR_RUNTIMES = ['server', 'edge', 'browser'];
 /** `namespace.name`: one dot, lower case, digits and underscores. */
 export const KIND_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
 export const SITE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/** sha256 of the kind and the top normalised frames, truncated to 32 hex, lower case. */
+export const FINGERPRINT_PATTERN = /^[0-9a-f]{32}$/;
 /**
  * Keys a `data` object may not carry, because each names a person or a
  * secret. A guardrail against the accidental case, not proof of absence: a
@@ -34,6 +38,7 @@ export const LIMITS = {
     targetId: 256,
     dataBytes: 16384,
     site: 64,
+    stack: 16384,
 };
 const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 /** Flat, bounded, banned keys refused, numbers finite. */
@@ -85,3 +90,6 @@ export const eventInputSchema = z.strictObject({
 export const siteSchema = z
     .string()
     .regex(SITE_PATTERN, 'a site id is lower case, digits and dashes');
+export const fingerprintSchema = z
+    .string()
+    .regex(FINGERPRINT_PATTERN, 'a fingerprint is 32 lower-case hex characters');

package/dist/settings.d.ts

@@ -9,6 +9,7 @@ export declare const RETENTION_BOUNDS: {
     readonly min: 7;
     readonly max: 400;
 };
+export declare const CONSENT_MODES: readonly ["none", "consented", "always"];
 export declare const DEFAULT_SETTINGS: Settings;
 export declare function getSettings(db: Db): Promise<Settings>;
 /** Validates every key, writes the changed ones in one transaction, returns before and after. Throws on an out-of-bounds value: the caller is a form. */

package/dist/settings.js

@@ -8,15 +8,20 @@ import { reportingSettings } from './tables.js';
  * do is shorten history to a week.
  */
 export const RETENTION_BOUNDS = { min: 7, max: 400 };
+export const CONSENT_MODES = ['none', 'consented', 'always'];
+const retention = z.number().int().min(RETENTION_BOUNDS.min).max(RETENTION_BOUNDS.max);
 const DEFS = {
-    'events.retention_days': {
-        schema: z.number().int().min(RETENTION_BOUNDS.min).max(RETENTION_BOUNDS.max),
-        default: 30,
-    },
+    'events.retention_days': { schema: retention, default: 30 },
+    // Ninety, not thirty: behaviour is watched over years through the rollups,
+    // and a dimension they lack is a recompute over this window (D13).
+    'analytics.retention_days': { schema: retention, default: 90 },
+    // Cookieless until the person says otherwise (D15).
+    'analytics.consent': { schema: z.enum(CONSENT_MODES), default: 'consented' },
+    // A signed-in person's rows carry their id, as the product's own record of
+    // serving them; one line to change if advice changes (D15).
+    'analytics.identify_signed_in': { schema: z.boolean(), default: true },
 };
-export const DEFAULT_SETTINGS = Object.freeze({
-    'events.retention_days': DEFS['events.retention_days'].default,
-});
+export const DEFAULT_SETTINGS = Object.freeze(Object.fromEntries(Object.entries(DEFS).map(([k, d]) => [k, d.default])));
 function fromRows(rows) {
     const out = { ...DEFAULT_SETTINGS };
     for (const row of rows) {
@@ -44,7 +49,9 @@ export async function setSettings(db, patch, by) {
             throw new Error(`reporting.settings: unknown key "${key}"`);
         const parsed = def.schema.safeParse(value);
         if (!parsed.success) {
-            throw new Error(`reporting.settings: ${key} must be an integer between ${RETENTION_BOUNDS.min} and ${RETENTION_BOUNDS.max}`);
+            throw new Error(key.endsWith('retention_days')
+                ? `reporting.settings: ${key} must be an integer between ${RETENTION_BOUNDS.min} and ${RETENTION_BOUNDS.max}`
+                : `reporting.settings: ${key} is not a valid value`);
         }
     }
     return db.transaction(async (tx) => {