@wtfalch/reporting 0.1.2 → 0.2.1

package/dist/index.js

@@ -1,4 +1,7 @@
 import { alertRow } from './alerts.js';
+import { analyticsRecent, analyticsSeries, analyticsWeekly } from './analytics/reader.js';
+import { ANALYTICS_NAME_PATTERN, normalisePath, propsSchema } from './analytics/schema.js';
+import { insertAnalytics } from './analytics/write.js';
 import { eventsPage } from './reader.js';
 import { siteSchema } from './schema.js';
 import { getSettings, setSettings } from './settings.js';
@@ -8,7 +11,10 @@ export * from './schema.js';
 export * from './tables.js';
 export * from './types.js';
 export { alertKind, projectDetail } from './alerts.js';
-export { DEFAULT_SETTINGS, RETENTION_BOUNDS } from './settings.js';
+export { CONSENT_MODES, DEFAULT_SETTINGS, RETENTION_BOUNDS } from './settings.js';
+export * from './analytics/schema.js';
+export { createCollector } from './analytics/collector.js';
+export { analyticsRecent, analyticsSeries, analyticsWeekly, hideSmallGroups, } from './analytics/reader.js';
 function modeFromEnv() {
     const env = process.env.NODE_ENV;
     return env === 'development' || env === 'test' ? env : 'production';
@@ -75,6 +81,42 @@ export function createReporting(options) {
                 return change;
             },
         },
+        analytics: {
+            async track(input) {
+                try {
+                    if (!ANALYTICS_NAME_PATTERN.test(input.name)) {
+                        throw new Error(`analytics.track: "${input.name}" is not a name`);
+                    }
+                    const props = propsSchema.parse(input.props ?? {});
+                    const at = input.occurredAt ?? now();
+                    await insertAnalytics(options.db, [
+                        {
+                            occurredAt: at,
+                            receivedAt: now(),
+                            site,
+                            tenantId: input.tenantId ?? null,
+                            visitorId: input.visitorId ?? null,
+                            sessionId: input.sessionId ?? null,
+                            userId: input.userId ?? null,
+                            name: input.name,
+                            path: (options.normalisePath ?? normalisePath)(input.path ?? '/'),
+                            referrerHost: null,
+                            device: input.device ?? 'unknown',
+                            country: input.country ?? null,
+                            props,
+                        },
+                    ]);
+                }
+                catch (error) {
+                    if (mode !== 'production')
+                        throw error;
+                    options.log.error({ err: describe(error), name: input.name }, 'reporting: track failed');
+                }
+            },
+            series: (opts) => analyticsSeries(options.db, opts),
+            weekly: (opts) => analyticsWeekly(options.db, opts),
+            recent: (opts) => analyticsRecent(options.db, opts),
+        },
         stats: () => writer.stats(),
     };
     return reporting;

package/dist/migrations/0002_analytics.sql

@@ -0,0 +1,350 @@
+-- @wtfalch/reporting 0.2.0: the analytics record. Mirrors src/tables.ts.
+--
+-- Three tables (docs/plans/reporting.md D13). `reporting_analytics` holds
+-- raw rows for a window; the two rollups hold counts and nothing that
+-- identifies anybody, which is what lets them outlive the raw rows and be
+-- shown to a customer organisation. Every statement is idempotent; the file
+-- is applied by the host's own migrate script after `reporting-migrations`
+-- copies it in as the next number.
+
+-- -------------------------------------------------------------- raw rows
+-- No ip, no user agent, no email, no name, no free text longer than a path.
+-- `user_id` is set only server-side from the session, never from the beacon;
+-- `visitor_id` is the first-party cookie's value when consent gave one.
+-- `path` is the pathname only, normalised to a route pattern before it gets
+-- here (addendum A7), so no identifier or token survives into storage.
+create table if not exists reporting_analytics (
+  id              bigint generated always as identity primary key,
+  occurred_at     timestamptz not null,
+  received_at     timestamptz not null default now(),
+  site            text not null,
+  tenant_id       uuid,
+  visitor_id      text,
+  session_id      text,
+  user_id         text,
+  name            text not null,
+  path            text not null,
+  referrer_host   text,
+  device          text not null,
+  country         text,
+  props           jsonb not null default '{}'::jsonb,
+  schema_version  smallint not null default 1,
+  constraint reporting_analytics_site_check check (site ~ '^[a-z][a-z0-9-]{0,63}$'),
+  constraint reporting_analytics_name_check check (name ~ '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$'),
+  constraint reporting_analytics_path_check check (length(path) between 1 and 512 and position('?' in path) = 0),
+  constraint reporting_analytics_referrer_check check (referrer_host is null or length(referrer_host) <= 253),
+  constraint reporting_analytics_device_check check (device in ('desktop', 'mobile', 'tablet', 'bot', 'unknown')),
+  constraint reporting_analytics_country_check check (country is null or country ~ '^[A-Z]{2}$'),
+  constraint reporting_analytics_ids_check check (
+    (visitor_id is null or length(visitor_id) between 8 and 64)
+    and (session_id is null or length(session_id) between 8 and 64)
+    and (user_id is null or length(user_id) between 1 and 256)
+  ),
+  -- The beacon's clock is a claim; ten minutes either side of arrival is
+  -- the most it may say.
+  constraint reporting_analytics_clock_check check (abs(extract(epoch from (occurred_at - received_at))) <= 600),
+  constraint reporting_analytics_props_object_check check (jsonb_typeof(props) = 'object'),
+  constraint reporting_analytics_props_size_check check (octet_length(props::text) <= 4096),
+  constraint reporting_analytics_props_flat_check check (not jsonb_path_exists(props, 'strict $.* ? (@.type() == "object" || @.type() == "array")', '{}', true)),
+  constraint reporting_analytics_props_keys_check check (
+    not (props ?| array['email', 'name', 'display_name', 'displayName', 'password', 'secret', 'token', 'authorization'])
+  )
+);
+create index if not exists reporting_analytics_site_time_idx
+  on reporting_analytics (site, occurred_at desc, id desc);
+create index if not exists reporting_analytics_tenant_time_idx
+  on reporting_analytics (tenant_id, occurred_at desc, id desc) where tenant_id is not null;
+create index if not exists reporting_analytics_user_idx
+  on reporting_analytics (user_id) where user_id is not null;
+create index if not exists reporting_analytics_site_name_time_idx
+  on reporting_analytics (site, name, occurred_at desc);
+-- The rollups read one UTC day at a time.
+create index if not exists reporting_analytics_day_idx
+  on reporting_analytics (((occurred_at at time zone 'UTC')::date), site);
+alter table reporting_analytics set (autovacuum_vacuum_scale_factor = 0.02);
+
+-- ------------------------------------------------------------ daily rollup
+-- One row per day, site, grain and dimension value. `grain` names which
+-- dimension the row is grouped by (addendum A4: distinct counts are stored
+-- at every level a reader promises, never summed from finer groups):
+--   site      the whole site (every dimension null)
+--   tenant    per organisation
+--   name      per event name
+--   path      page views per normalised route, top 200 a day plus '(other)'
+--   device, country, referrer   per dimension, referrers top 50 plus '(other)'
+-- A day's whole set is replaced atomically by reporting_rollup_day, so a
+-- bucket that leaves the top list does not linger. The generated key
+-- columns make the nullable dimensions part of the primary key.
+create table if not exists reporting_analytics_daily (
+  day             date not null,
+  site            text not null,
+  grain           text not null,
+  tenant_id       uuid,
+  name            text,
+  path            text,
+  device          text,
+  country         text,
+  referrer_host   text,
+  views           integer not null,
+  visitors        integer not null,
+  people          integer not null,
+  tenant_key      text generated always as (coalesce(tenant_id::text, '')) stored,
+  name_key        text generated always as (coalesce(name, '')) stored,
+  path_key        text generated always as (coalesce(path, '')) stored,
+  device_key      text generated always as (coalesce(device, '')) stored,
+  country_key     text generated always as (coalesce(country, '')) stored,
+  referrer_key    text generated always as (coalesce(referrer_host, '')) stored,
+  constraint reporting_analytics_daily_grain_check check (grain in ('site', 'tenant', 'name', 'path', 'device', 'country', 'referrer')),
+  constraint reporting_analytics_daily_pkey primary key (day, site, grain, tenant_key, name_key, path_key, device_key, country_key, referrer_key)
+);
+create index if not exists reporting_analytics_daily_site_grain_idx
+  on reporting_analytics_daily (site, grain, day desc);
+
+-- ----------------------------------------------------------- weekly rollup
+-- Visitors and people per ISO week (the Monday), and how many of them were
+-- seen in one of the four weeks before, inside the raw window: the one
+-- question the daily table cannot answer.
+create table if not exists reporting_analytics_weekly (
+  week                date not null,
+  site                text not null,
+  tenant_id           uuid,
+  visitors            integer not null,
+  returning_visitors  integer not null,
+  people              integer not null,
+  returning_people    integer not null,
+  tenant_key          text generated always as (coalesce(tenant_id::text, '')) stored,
+  constraint reporting_analytics_weekly_pkey primary key (week, site, tenant_key)
+);
+
+-- The rollups' completed-history watermark (addendum A3), one text value
+-- per task, moved in the same transaction as the aggregate set it vouches
+-- for and fenced by the claim token.
+alter table reporting_tasks add column if not exists watermark text;
+
+-- Settings the next release reserved: the raw window, the consent mode and
+-- the signed-in switch, per site through the key's suffix.
+alter table reporting_settings drop constraint if exists reporting_settings_key_check;
+alter table reporting_settings add constraint reporting_settings_key_check
+  check (key ~ '^(events|analytics)\.[a-z][a-z0-9_]*$');
+
+-- --------------------------------------------------------- reporting_rollup_day
+-- Replaces one UTC day's aggregate set. Definer, because the runtime role
+-- may not write the rollups directly: their contents are derived, and only
+-- this function derives them. Returns the number of rows written.
+create or replace function reporting_rollup_day(d date)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  n integer;
+  lo timestamptz := (d::timestamp at time zone 'UTC');
+  hi timestamptz := ((d + 1)::timestamp at time zone 'UTC');
+begin
+  if d is null then
+    raise exception 'reporting_rollup_day: a day is required';
+  end if;
+  delete from reporting_analytics_daily where day = d;
+  with raw as (
+    select site, tenant_id, visitor_id, user_id, name, path, device, country, referrer_host
+      from reporting_analytics
+     where occurred_at >= lo and occurred_at < hi
+  ),
+  top_paths as (
+    select site, path from (
+      select site, path, count(*) as c,
+             row_number() over (partition by site order by count(*) desc, path) as rn
+        from raw where name = 'page.view' group by site, path
+    ) t where rn <= 200
+  ),
+  top_refs as (
+    select site, referrer_host from (
+      select site, referrer_host, count(*) as c,
+             row_number() over (partition by site order by count(*) desc, referrer_host) as rn
+        from raw where referrer_host is not null group by site, referrer_host
+    ) t where rn <= 50
+  ),
+  rows_out as (
+    -- site
+    select site, 'site' as grain, null::uuid as tenant_id, null::text as name, null::text as path,
+           null::text as device, null::text as country, null::text as referrer_host,
+           count(*) as views, count(distinct visitor_id) as visitors, count(distinct user_id) as people
+      from raw group by site
+    union all
+    -- tenant
+    select site, 'tenant', tenant_id, null, null, null, null, null,
+           count(*), count(distinct visitor_id), count(distinct user_id)
+      from raw where tenant_id is not null group by site, tenant_id
+    union all
+    -- name
+    select site, 'name', null, name, null, null, null, null,
+           count(*), count(distinct visitor_id), count(distinct user_id)
+      from raw group by site, name
+    union all
+    -- path: page views only, top 200 plus (other)
+    select r.site, 'path', null, null,
+           case when tp.path is null then '(other)' else r.path end,
+           null, null, null,
+           count(*), count(distinct r.visitor_id), count(distinct r.user_id)
+      from raw r left join top_paths tp on tp.site = r.site and tp.path = r.path
+     where r.name = 'page.view'
+     group by r.site, case when tp.path is null then '(other)' else r.path end
+    union all
+    -- device
+    select site, 'device', null, null, null, device, null, null,
+           count(*), count(distinct visitor_id), count(distinct user_id)
+      from raw group by site, device
+    union all
+    -- country
+    select site, 'country', null, null, null, null, coalesce(country, 'ZZ'), null,
+           count(*), count(distinct visitor_id), count(distinct user_id)
+      from raw group by site, coalesce(country, 'ZZ')
+    union all
+    -- referrer: top 50 plus (other); rows with no referrer are '(direct)'
+    select r.site, 'referrer', null, null, null, null, null,
+           case when r.referrer_host is null then '(direct)'
+                when tr.referrer_host is null then '(other)'
+                else r.referrer_host end,
+           count(*), count(distinct r.visitor_id), count(distinct r.user_id)
+      from raw r left join top_refs tr on tr.site = r.site and tr.referrer_host = r.referrer_host
+     group by r.site, case when r.referrer_host is null then '(direct)'
+                           when tr.referrer_host is null then '(other)'
+                           else r.referrer_host end
+  )
+  insert into reporting_analytics_daily
+    (day, site, grain, tenant_id, name, path, device, country, referrer_host, views, visitors, people)
+  select d, site, grain, tenant_id, name, path, device, country, referrer_host,
+         views::integer, visitors::integer, people::integer
+    from rows_out;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_rollup_day(date) from public;
+
+-- -------------------------------------------------------- reporting_rollup_week
+-- Replaces one ISO week's rows (w is the Monday). Returning means seen in
+-- any of the four weeks before, which is the raw lookback this rollup
+-- declares; reporting_prune_analytics is told about it.
+create or replace function reporting_rollup_week(w date)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  n integer;
+  lo timestamptz := (w::timestamp at time zone 'UTC');
+  hi timestamptz := ((w + 7)::timestamp at time zone 'UTC');
+  back timestamptz := ((w - 28)::timestamp at time zone 'UTC');
+begin
+  if w is null or extract(isodow from w) <> 1 then
+    raise exception 'reporting_rollup_week: a Monday is required';
+  end if;
+  delete from reporting_analytics_weekly where week = w;
+  with this_week as (
+    select site, tenant_id, visitor_id, user_id
+      from reporting_analytics where occurred_at >= lo and occurred_at < hi
+  ),
+  earlier as (
+    select distinct site, visitor_id, user_id
+      from reporting_analytics where occurred_at >= back and occurred_at < lo
+  ),
+  scopes as (
+    select site, null::uuid as tenant_id, visitor_id, user_id from this_week
+    union all
+    select site, tenant_id, visitor_id, user_id from this_week where tenant_id is not null
+  )
+  insert into reporting_analytics_weekly
+    (week, site, tenant_id, visitors, returning_visitors, people, returning_people)
+  select w, s.site, s.tenant_id,
+         count(distinct s.visitor_id),
+         count(distinct s.visitor_id) filter (where exists (
+           select 1 from earlier e where e.site = s.site and e.visitor_id = s.visitor_id)),
+         count(distinct s.user_id),
+         count(distinct s.user_id) filter (where exists (
+           select 1 from earlier e where e.site = s.site and e.user_id = s.user_id))
+    from scopes s
+   group by s.site, s.tenant_id;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_rollup_week(date) from public;
+
+-- ------------------------------------------------------ reporting_prune_analytics
+-- The one way raw rows leave by age. `safe_before` is the earliest day the
+-- rollups still need (the daily watermark, and the weekly watermark less
+-- its four-week lookback, whichever is earlier): a cutoff at or past it is
+-- refused, so pruning never outruns aggregation (addendum A3).
+create or replace function reporting_prune_analytics(retention interval, batch integer, safe_before date)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  w interval := greatest(interval '7 days', least(coalesce(retention, interval '90 days'), interval '400 days'));
+  b integer := greatest(1, least(coalesce(batch, 5000), 5000));
+  cutoff timestamptz := now() - w;
+  n integer;
+begin
+  if safe_before is null then
+    raise exception 'reporting_prune_analytics: the rollups have not completed a day yet; nothing is safe to prune';
+  end if;
+  if cutoff >= (safe_before::timestamp at time zone 'UTC') then
+    raise exception 'reporting_prune_analytics: cutoff % is not before the rollups'' watermark %', cutoff, safe_before;
+  end if;
+  with victims as (
+    select id from reporting_analytics
+     where occurred_at < cutoff
+     order by occurred_at, id
+     limit b
+  )
+  delete from reporting_analytics a using victims v where a.id = v.id;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_analytics(interval, integer, date) from public;
+
+-- -------------------------------------------------------- reporting_erase_person
+-- The subject's raw rows go; the rollups hold no identifier and stay. Called
+-- by the host inside its erasure transaction. Returns the rows deleted.
+create or replace function reporting_erase_person(subject text)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  n integer;
+begin
+  if subject is null or length(subject) = 0 then
+    raise exception 'reporting_erase_person: a subject id is required';
+  end if;
+  delete from reporting_analytics where user_id = subject;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_erase_person(text) from public;
+
+-- The runtime role inserts and reads raw rows, reads the rollups, and
+-- changes either only through the functions above.
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on reporting_analytics from %I', rt);
+    execute format('revoke insert, update, delete, truncate on reporting_analytics_daily from %I', rt);
+    execute format('revoke insert, update, delete, truncate on reporting_analytics_weekly from %I', rt);
+    execute format('grant execute on function reporting_rollup_day(date) to %I', rt);
+    execute format('grant execute on function reporting_rollup_week(date) to %I', rt);
+    execute format('grant execute on function reporting_prune_analytics(interval, integer, date) to %I', rt);
+    execute format('grant execute on function reporting_erase_person(text) to %I', rt);
+  end if;
+end
+$$;

package/dist/next/index.d.ts

@@ -1,3 +1,5 @@
+import { type CollectorOptions } from '../analytics/collector.js';
+import { deviceOf } from '../analytics/schema.js';
 import type { Reporting } from '../types.js';
 /**
  * The Next bindings: everything in the package that knows what a request is.
@@ -38,3 +40,17 @@ 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>;
+/** 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,8 @@ 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';
 /**
  * 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 +73,25 @@ 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);
+}
+/** 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/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/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) => {