@wtfalch/reporting 0.1.2 → 0.3.0

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/migrations/0003_errors.sql

@@ -0,0 +1,118 @@
+-- @wtfalch/reporting 0.3.0: the error group table. Mirrors src/tables.ts.
+--
+-- One row per fingerprint (docs/plans/errors.md): an uncaught exception's
+-- stack groups repeats into a count and a last-seen time instead of a
+-- firehose of identical reporting_events rows. Every statement is
+-- idempotent. Applied by the host's own migrate script after the host
+-- copies this file into its drizzle/ directory as the next number
+-- (reporting-migrations); never edited there.
+--
+-- Estate-shaped: the DO block at the end assumes the runtime-role convention
+-- (a role named <database>_rt that owns nothing and serves the app). A host
+-- without that role gets the table and no revokes take effect, which the
+-- package README says plainly.
+
+create table if not exists reporting_errors (
+  fingerprint     text primary key,
+  site            text not null,
+  kind            text not null,
+  message         text not null,
+  stack           text,
+  runtime         text not null,
+  release         text,
+  first_seen_at   timestamptz not null,
+  last_seen_at    timestamptz not null,
+  occurrences     bigint not null default 1,
+  state           text not null default 'open',
+  resolved_at     timestamptz,
+  resolved_by     text,
+  tenant_id       uuid,
+  request_id      text,
+  -- The digest that groups occurrences (docs/plans/errors.md: sha256 of the
+  -- kind and the top normalised frames, truncated to 32 hex). Lower case
+  -- only: two casings of the same digest must not become two groups.
+  constraint reporting_errors_fingerprint_check check (fingerprint ~ '^[0-9a-f]{32}$'),
+  constraint reporting_errors_site_check check (site ~ '^[a-z][a-z0-9-]{0,63}$'),
+  constraint reporting_errors_message_check check (length(message) between 1 and 512),
+  -- Redacted before it is queued (src/schema.ts); this bound is a second net
+  -- against a pathological stack, not the redaction itself.
+  constraint reporting_errors_stack_check check (stack is null or length(stack) <= 16384),
+  constraint reporting_errors_runtime_check check (runtime in ('server', 'edge', 'browser')),
+  constraint reporting_errors_state_check check (state in ('open', 'resolved', 'ignored')),
+  -- The row exists because one occurrence created it; it can never describe
+  -- zero.
+  constraint reporting_errors_occurrences_check check (occurrences > 0),
+  -- The upsert only ever moves this forward. If it moved backward, the count
+  -- and the window it claims to describe would disagree.
+  constraint reporting_errors_seen_check check (last_seen_at >= first_seen_at),
+  -- Same pairing as reporting_events_actor_pair_check: who resolved it is
+  -- meaningless without when, and vice versa.
+  constraint reporting_errors_resolved_pair_check check ((resolved_at is null) = (resolved_by is null))
+);
+
+comment on column reporting_errors.tenant_id is
+  'From the most recent sample. No foreign key and no cascade, same as reporting_events.actor_id: the group outlives the request, and erasure must not delete the count.';
+comment on column reporting_errors.request_id is
+  'From the most recent sample; overwritten on every occurrence, not a history.';
+
+-- The default operator view: this site, still open, newest first. A partial
+-- index because most errors end up resolved and should not cost this one.
+create index if not exists reporting_errors_site_open_idx
+  on reporting_errors (site, last_seen_at desc) where state = 'open';
+-- The same page's state filter, switched to resolved or ignored.
+create index if not exists reporting_errors_state_idx
+  on reporting_errors (state, last_seen_at desc);
+
+-- The one way rows leave reporting_errors on a timer. Unlike
+-- reporting_prune_events, eligibility is state AND age, not age alone: only
+-- 'resolved' or 'ignored' rows past the window are candidates. A row still
+-- 'open' is NEVER a candidate here, no matter how old — an unresolved error
+-- vanishing on a timer is the failure mode that makes an error tracker
+-- untrustworthy, so the only way one leaves this table is an operator
+-- resolving or ignoring it first, and it ageing out after. Same clamp and
+-- batching shape as reporting_prune_events: the window is clamped to between
+-- seven and four hundred days inside the function, and the batch is capped
+-- at 5,000 so no statement holds a lock for long.
+create or replace function reporting_prune_errors(retention interval, batch integer)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  w interval := greatest(interval '7 days', least(coalesce(retention, interval '30 days'), interval '400 days'));
+  b integer := greatest(1, least(coalesce(batch, 5000), 5000));
+  n integer;
+begin
+  with victims as (
+    select fingerprint from reporting_errors
+     where state in ('resolved', 'ignored')
+       and last_seen_at < now() - w
+     order by last_seen_at, fingerprint
+     limit b
+  )
+  delete from reporting_errors e using victims v where e.fingerprint = v.fingerprint;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_errors(interval, integer) from public;
+
+comment on function reporting_prune_errors(interval, integer) is
+  'Deletes only resolved or ignored rows past the retention window. An open row is never a candidate, regardless of age: an unresolved error disappearing on a timer is the one failure mode that makes an error tracker untrustworthy. It leaves this table only after an operator resolves or ignores it, and then ages out.';
+
+-- The runtime role keeps SELECT, INSERT and UPDATE: the capture path upserts
+-- on repeat occurrences and an operator moves state through this table.
+-- Nothing that deletes, the same as reporting_tasks and reporting_settings;
+-- reporting_prune_errors runs as the function owner, not the runtime role,
+-- so the grant below is execute only, same shape as reporting_prune_events.
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke delete, truncate on reporting_errors from %I', rt);
+    execute format('grant execute on function reporting_prune_errors(interval, integer) to %I', rt);
+  end if;
+end
+$$;

package/dist/next/client-errors.d.ts

@@ -0,0 +1,46 @@
+import type { Reporting } from '../types.js';
+/**
+ * The public ingest route for browser-reported errors
+ * (docs/plans/errors.md, "Surface"): modelled exactly on the analytics
+ * collector (`../analytics/collector.js`) — always 204, the same origin
+ * allowance, the same body-size cap — because that ingest problem is
+ * already solved there and a second set of limits would be a second set to
+ * get wrong.
+ *
+ * Two things differ from the analytics collector, both because a
+ * `Reporting` instance is already bound to one site:
+ * 1. There is no `sites` map to route a foreign origin's claim to a
+ *    different site's table — `origins` below is a flat allow-list, and a
+ *    batch claiming any other site is dropped, same-origin or not.
+ * 2. A capture goes through `reporting.captureError`, not a direct insert,
+ *    so there is no `now`/`db` to take here: capture.ts already has its own.
+ */
+export interface ClientErrorCollectorOptions {
+    readonly reporting: Reporting;
+    /** Foreign origins allowed to post errors for this site, beside same-origin. */
+    readonly origins?: readonly string[];
+    /**
+     * The signed-in person, from the host's session, for a same-origin
+     * request only — a foreign origin never reads it (addendum A5's rule,
+     * same as the analytics collector's `getUserId`).
+     */
+    readonly getUserId?: (request: Request) => Promise<string | null>;
+    /**
+     * The host's tenant lookup for that person. Unlike the analytics
+     * collector's `tenantFor`, there is no pathname to hand over: an error
+     * batch names no single route the way a page view does.
+     */
+    readonly tenantFor?: (userId: string) => Promise<string | null>;
+    /**
+     * Captures allowed per minute per client address. An unauthenticated route
+     * that writes rows needs a ceiling that does not depend on the caller being
+     * our own beacon: the browser's 5-distinct/20-total cap is one line of
+     * client code away from being ignored, and `reporting_errors` never prunes
+     * an open row. Lower than the analytics default because an error is rarer
+     * than a page view by design; a client hitting this is already broken.
+     */
+    readonly ratePerMinute?: number;
+}
+export declare function createClientErrorCollector(options: ClientErrorCollectorOptions): {
+    handle(request: Request): Promise<Response>;
+};

package/dist/next/client-errors.js

@@ -0,0 +1,165 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ANALYTICS_LIMITS } from '../analytics/schema.js';
+import { Buckets } from '../ingest-limit.js';
+import { SITE_PATTERN } from '../schema.js';
+/** At most this many entries of a batch are ever captured; the rest are dropped silently. */
+const BATCH_MAX = 10;
+/**
+ * Not `z.strictObject`, unlike the analytics beacon schema: a client that
+ * adds `tenantId`, `userId` or `requestId` here must have that field
+ * silently stripped, not the whole batch refused. `handle()` below never
+ * reads such a field either way — identity and the request id come only
+ * from this request itself (`getUserId`/`tenantFor`, and `cf-ray`/a fresh
+ * uuid), never from the body. The browser is not a trusted caller.
+ */
+const entrySchema = z.object({
+    kind: z.string().min(1),
+    message: z.string().min(1),
+    stack: z.string().nullish(),
+    release: z.string().nullish(),
+});
+const batchSchema = z.object({
+    site: z.string().regex(SITE_PATTERN),
+    errors: z.array(entrySchema).min(1),
+});
+const NO_CONTENT = () => new Response(null, { status: 204 });
+/**
+ * The client's address as the tunnel presents it. `cf-connecting-ip` first
+ * because every request to this estate arrives through Cloudflare, then the
+ * first hop of `x-forwarded-for`; a header a client sets itself is no worse
+ * here than no key at all, since the bucket only ever costs that same client.
+ */
+function clientAddress(request) {
+    const cf = request.headers.get('cf-connecting-ip');
+    if (cf)
+        return cf.trim();
+    const xff = request.headers.get('x-forwarded-for');
+    return xff ? (xff.split(',')[0] ?? '').trim() || null : null;
+}
+/** `<16 hex>-<colo>`, as Cloudflare emits it — the same pattern `./index.ts` uses; kept here too, rather than imported, to avoid a circular import between the two files. */
+const RAY_PATTERN = /^[0-9a-f]{16}-[A-Z0-9]{3,6}$/;
+function requestIdOf(request) {
+    const ray = request.headers.get('cf-ray');
+    return ray && RAY_PATTERN.test(ray) ? ray : randomUUID();
+}
+/**
+ * Same shape as the collector's own `originFor` (`../analytics/collector.js`,
+ * private there): duplicated rather than exported, per this task's scope —
+ * it is ~10 lines and the two callers now diverge (no `sites` map here).
+ */
+function originOf(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;
+}
+/**
+ * An `Error` carrying exactly the client's own message and stack, so
+ * `captureError`'s existing redaction and fingerprinting run unchanged on
+ * it (errors/capture.ts is not this task's to edit). The class name is
+ * never read from this: `context.kind` below overrides it with the
+ * client's own `kind`.
+ */
+function toCapturable(entry) {
+    const err = new Error(entry.message);
+    err.stack = entry.stack ?? undefined;
+    return err;
+}
+export function createClientErrorCollector(options) {
+    const { reporting } = options;
+    const buckets = new Buckets(options.ratePerMinute ?? 60, () => new Date());
+    async function handle(request) {
+        if (request.method !== 'POST')
+            return NO_CONTENT();
+        const where = originOf(request);
+        if (!where)
+            return NO_CONTENT();
+        if (where.kind === 'foreign' && !(options.origins ?? []).includes(where.origin)) {
+            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 = batchSchema.safeParse(json);
+        if (!parsed.success) {
+            reporting.log.info({ issues: parsed.error.issues.length }, 'reporting: client error batch refused');
+            return NO_CONTENT();
+        }
+        if (parsed.data.site !== reporting.site)
+            return NO_CONTENT();
+        // After parsing, so the cost of a refused body is not charged to the
+        // address, and before any capture, so the bucket bounds what is written
+        // rather than what was asked. Keyed on the address alone: a visitor id
+        // would be the client's own claim, and this is the route that exists
+        // because the client is not trusted.
+        const entries = parsed.data.errors.slice(0, BATCH_MAX);
+        if (!buckets.take(`ip:${clientAddress(request) ?? 'none'}`, entries.length)) {
+            return NO_CONTENT();
+        }
+        // Identity is the session's, same-origin only, and never the body's
+        // (the entry schema above has no tenantId/userId field to begin with).
+        let userId = null;
+        if (where.kind === 'same' && options.getUserId) {
+            try {
+                userId = await options.getUserId(request);
+            }
+            catch (error) {
+                reporting.log.warn({ err: error instanceof Error ? error.message : String(error) }, 'reporting: client error getUserId failed; capturing without a tenant');
+            }
+        }
+        let tenantId = null;
+        if (userId && options.tenantFor) {
+            try {
+                tenantId = await options.tenantFor(userId);
+            }
+            catch {
+                tenantId = null;
+            }
+        }
+        // This request's own id, cf-ray or a fresh uuid — never the body's;
+        // same rule `errorHandler` (./index.ts) follows for a server capture.
+        const requestId = requestIdOf(request);
+        for (const entry of entries) {
+            reporting.captureError(toCapturable(entry), {
+                kind: entry.kind,
+                runtime: 'browser',
+                release: entry.release ?? null,
+                tenantId,
+                requestId,
+            });
+        }
+        const response = NO_CONTENT();
+        return where.kind === 'foreign' ? corsFor(response, where.origin) : response;
+    }
+    return { handle };
+}