@wtfalch/reporting 0.3.1 → 0.4.0

package/dist/migrations/0006_tenant_settings.sql

@@ -0,0 +1,142 @@
+-- @wtfalch/reporting 0.4.0: per-tenant retention overrides. Mirrors src/tables.ts.
+--
+-- Retention is one setting per deployed app today (settings.ts:
+-- events.retention_days, analytics.retention_days), all-or-nothing. A
+-- multi-tenant company app the factory stamps may need a longer window for
+-- one customer's contract (gap issue #11) without moving the default for
+-- everyone else.
+--
+-- A separate table, not a row in reporting_settings: that table's key is
+-- its whole primary key, with no tenant dimension, and giving it one would
+-- change every existing key's shape. `reporting_tenant_settings` is the
+-- same idea -- one JSONB value per key, an operator's edit, a plain read on
+-- every housekeeping run -- keyed by (tenant_id, key) instead. Clearing an
+-- override never deletes the row (same "nothing that deletes" convention
+-- as reporting_settings): it sets the value to JSON null, and the prune
+-- functions below treat that exactly like no row at all. Every statement is
+-- idempotent.
+
+create table if not exists reporting_tenant_settings (
+  tenant_id   uuid not null,
+  key         text not null,
+  value       jsonb not null,
+  updated_at  timestamptz not null default now(),
+  updated_by  text,
+  constraint reporting_tenant_settings_pkey primary key (tenant_id, key),
+  -- Only the two retention keys this release supports; unlike
+  -- reporting_settings_key_check this is not a namespace pattern; there is
+  -- exactly one thing this table does.
+  constraint reporting_tenant_settings_key_check
+    check (key in ('events.retention_days', 'analytics.retention_days')),
+  -- JSON null (an explicit "no override") or a number in the same bounds
+  -- settings.ts's RETENTION_BOUNDS enforces in TypeScript.
+  constraint reporting_tenant_settings_value_check check (
+    jsonb_typeof(value) = 'null'
+    or (jsonb_typeof(value) = 'number' and (value #>> '{}')::numeric between 7 and 400)
+  )
+);
+
+-- ---------------------------------------------------- reporting_prune_events
+-- Same clamping and batching as before; the per-row window now checks this
+-- tenant's override first, falling back to the site-wide one. A row with no
+-- tenant_id (most of them) never joins, so it always uses the default --
+-- unaffected by this migration until an operator sets an override.
+create or replace function reporting_prune_events(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 e.id
+      from reporting_events e
+      left join reporting_tenant_settings ts
+        on ts.tenant_id = e.tenant_id and ts.key = 'events.retention_days'
+     where e.occurred_at < now() - (
+             case when jsonb_typeof(ts.value) = 'number'
+                  then greatest(interval '7 days', least((ts.value #>> '{}')::numeric * interval '1 day', interval '400 days'))
+                  else w
+             end
+           )
+     order by e.occurred_at, e.id
+     limit b
+  )
+  delete from reporting_events ev using victims v where ev.id = v.id;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_events(interval, integer) from public;
+
+-- -------------------------------------------------- reporting_prune_analytics
+-- Same shape: a tenant's own retention_days overrides the site-wide window,
+-- still bounded by safe_before so pruning never outruns the rollups
+-- (addendum A3) -- the per-tenant window is clamped the same 7-400 days
+-- before comparison, so an override cannot defeat that guarantee either.
+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 a.id
+      from reporting_analytics a
+      left join reporting_tenant_settings ts
+        on ts.tenant_id = a.tenant_id and ts.key = 'analytics.retention_days'
+     where a.occurred_at < least(
+             case when jsonb_typeof(ts.value) = 'number'
+                  then now() - greatest(interval '7 days', least((ts.value #>> '{}')::numeric * interval '1 day', interval '400 days'))
+                  else cutoff
+             end,
+             (safe_before::timestamp at time zone 'UTC')
+           )
+     order by a.occurred_at, a.id
+     limit b
+  )
+  delete from reporting_analytics an using victims v where an.id = v.id;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_analytics(interval, integer, date) from public;
+
+-- The runtime role reads and edits overrides (an operator's settings page),
+-- same shape as reporting_settings: select, insert, update, nothing that
+-- deletes -- clearing an override is a value update, not a row removal.
+--
+-- CREATE OR REPLACE FUNCTION keeps the two prune functions' existing grants
+-- (their signatures are unchanged from 0001/0002); the two re-grants below
+-- are a no-op on a host that already has them and a safety net on one
+-- whose grants somehow drifted, cheap either way.
+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_tenant_settings from %I', rt);
+    execute format('grant execute on function reporting_prune_events(interval, integer) to %I', rt);
+    execute format(
+      'grant execute on function reporting_prune_analytics(interval, integer, date) to %I',
+      rt
+    );
+  end if;
+end
+$$;

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

@@ -0,0 +1,50 @@
+import type { Reporting } from '../types.js';
+import type { NextOnRequestError } from './index.js';
+export interface EdgeErrorReport {
+    readonly kind: string;
+    readonly message: string;
+    readonly stack: string | null;
+    readonly release: string | null;
+    readonly requestId: string;
+}
+export interface EdgeCaptureOptions {
+    /** Where `edgeErrorIngestHandler` (./index.js) is mounted; same-origin path or an absolute URL. */
+    readonly endpoint: string;
+    /** Must match `EdgeErrorIngestOptions.secret` on the receiving end. */
+    readonly secret: string;
+    readonly release?: string | null;
+    /** Bounds how long a slow or hung node route can hold this up. Default 2000ms. */
+    readonly timeoutMs?: number;
+    /** For tests: replaces the global `fetch`. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Binds to Next's `onRequestError` for the edge runtime. Builds the report
+ * from the error alone -- no `db`, no `Reporting` instance needed -- and
+ * POSTs it to the node route.
+ *
+ * Awaited, not fire-and-forget: `NextOnRequestError` may return a promise
+ * exactly so a hook like this can be waited on, and an edge isolate is free
+ * to be torn down the instant this function returns -- a POST left running
+ * behind an unawaited call is a coin flip on whether it ever leaves the
+ * process. `timeoutMs` bounds the wait so a hung node route cannot hold
+ * Next's own error handling open indefinitely. Never throws back into Next,
+ * the same rule `errorHandler` (./index.js) already keeps.
+ */
+export declare function edgeErrorHandler(options: EdgeCaptureOptions): NextOnRequestError;
+export interface EdgeErrorIngestOptions {
+    readonly reporting: Reporting;
+    /** Must match `EdgeCaptureOptions.secret` on the sending end. */
+    readonly secret: string;
+}
+/**
+ * The node half of the pair: not a public ingest like `clientErrorHandler`'s
+ * (no origin allowance, no rate limiter, no batching) because it is not
+ * meant to be reachable except by this app's own edge runtime holding the
+ * shared secret. A request missing or failing that check is dropped the
+ * same silent way every ingest route in this package answers a bad one --
+ * always 204, so a prober learns nothing.
+ */
+export declare function createEdgeErrorIngestCollector(options: EdgeErrorIngestOptions): {
+    handle(request: Request): Promise<Response>;
+};

package/dist/next/edge-errors.js

@@ -0,0 +1,131 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * The edge runtime has no database connection (docs/plans/errors.md never
+ * covered it; `errorHandler`/`captureError` assume one). `errorHandler`
+ * (./index.js) still gets called there -- `NEXT_RUNTIME` says `edge` -- but
+ * a `Reporting` built over a driver that needs a TCP socket cannot even be
+ * constructed in that runtime, so the capture it tries to defer never runs.
+ *
+ * The fix is not to teach the edge runtime to write Postgres. It is to keep
+ * capture edge-safe: serialise the error and hand it to a node route
+ * handler over `fetch`, the one thing both runtimes share, and let that
+ * route -- which does have a `db` -- call `captureError` for real.
+ * `edgeErrorHandler` is the edge half; `createEdgeErrorIngestCollector`
+ * (wrapped as `edgeErrorIngestHandler` in ./index.js) is the node half.
+ *
+ * The shared `secret` is what stops a stranger from writing rows into
+ * `reporting_errors` through this route: unlike `clientErrorHandler`, whose
+ * public ingest is meant for any browser to call, this one exists only for
+ * this app's own edge runtime to call, and has no session or origin to
+ * check instead.
+ */
+const RAY_PATTERN = /^[0-9a-f]{16}-[A-Z0-9]{3,6}$/;
+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 to Next's `onRequestError` for the edge runtime. Builds the report
+ * from the error alone -- no `db`, no `Reporting` instance needed -- and
+ * POSTs it to the node route.
+ *
+ * Awaited, not fire-and-forget: `NextOnRequestError` may return a promise
+ * exactly so a hook like this can be waited on, and an edge isolate is free
+ * to be torn down the instant this function returns -- a POST left running
+ * behind an unawaited call is a coin flip on whether it ever leaves the
+ * process. `timeoutMs` bounds the wait so a hung node route cannot hold
+ * Next's own error handling open indefinitely. Never throws back into Next,
+ * the same rule `errorHandler` (./index.js) already keeps.
+ */
+export function edgeErrorHandler(options) {
+    const doFetch = options.fetch ?? fetch;
+    return async (error, request) => {
+        try {
+            const ray = headerValue(request.headers, 'cf-ray');
+            const requestId = ray && RAY_PATTERN.test(ray) ? ray : randomUUID();
+            const body = {
+                kind: error instanceof Error ? error.name || 'Error' : 'Error',
+                message: error instanceof Error
+                    ? error.message || error.name || 'Error'
+                    : typeof error === 'string'
+                        ? error
+                        : 'unknown edge error',
+                stack: error instanceof Error && typeof error.stack === 'string' ? error.stack : null,
+                release: options.release ?? null,
+                requestId,
+            };
+            await doFetch(options.endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-reporting-edge-secret': options.secret,
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 2000),
+            });
+        }
+        catch {
+            // Never throw back into Next: see errorHandler's own doc comment. A
+            // failed or timed-out forward just means this occurrence is lost.
+        }
+    };
+}
+const reportSchema = z.object({
+    kind: z.string().min(1),
+    message: z.string().min(1),
+    stack: z.string().nullish(),
+    release: z.string().nullish(),
+    requestId: z.string().min(1),
+});
+const NO_CONTENT = () => new Response(null, { status: 204 });
+/** Constant-time so a network trace of response latency cannot narrow the secret. */
+function secretMatches(provided, expected) {
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * The node half of the pair: not a public ingest like `clientErrorHandler`'s
+ * (no origin allowance, no rate limiter, no batching) because it is not
+ * meant to be reachable except by this app's own edge runtime holding the
+ * shared secret. A request missing or failing that check is dropped the
+ * same silent way every ingest route in this package answers a bad one --
+ * always 204, so a prober learns nothing.
+ */
+export function createEdgeErrorIngestCollector(options) {
+    async function handle(request) {
+        if (request.method !== 'POST')
+            return NO_CONTENT();
+        const provided = request.headers.get('x-reporting-edge-secret');
+        if (!provided || !secretMatches(provided, options.secret))
+            return NO_CONTENT();
+        let json;
+        try {
+            json = await request.json();
+        }
+        catch {
+            return NO_CONTENT();
+        }
+        const parsed = reportSchema.safeParse(json);
+        if (!parsed.success)
+            return NO_CONTENT();
+        const { kind, message, stack, release, requestId } = parsed.data;
+        const err = new Error(message);
+        err.stack = stack ?? undefined;
+        options.reporting.captureError(err, {
+            kind,
+            runtime: 'edge',
+            release: release ?? null,
+            requestId,
+        });
+        return NO_CONTENT();
+    }
+    return { handle };
+}

package/dist/next/index.d.ts

@@ -2,6 +2,8 @@ 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';
+import { type EdgeErrorIngestOptions } from './edge-errors.js';
+export { edgeErrorHandler, type EdgeCaptureOptions, type EdgeErrorReport } from './edge-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.
@@ -88,6 +90,14 @@ export declare function errorHandler(reporting: Reporting): NextOnRequestError;
  * origin allowance and why identity is never the body's.
  */
 export declare function clientErrorHandler(options: ClientErrorCollectorOptions): (request: Request) => Promise<Response>;
+/**
+ * The node half of `edgeErrorHandler` (./edge-errors.js): mount as `POST` of
+ * an internal route (docs/plans/errors.md has no "Surface" entry for this,
+ * because it is not a public one -- `// authz: public` would be wrong here;
+ * the shared `secret` is the gate). This is where `reporting`'s real `db`
+ * lives, so this is where the edge-forwarded report finally becomes a row.
+ */
+export declare function edgeErrorIngestHandler(options: EdgeErrorIngestOptions): (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>;

package/dist/next/index.js

@@ -5,6 +5,8 @@ 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';
+import { createEdgeErrorIngestCollector } from './edge-errors.js';
+export { edgeErrorHandler } from './edge-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.
@@ -132,6 +134,17 @@ export function clientErrorHandler(options) {
     const collector = createClientErrorCollector(options);
     return (request) => collector.handle(request);
 }
+/**
+ * The node half of `edgeErrorHandler` (./edge-errors.js): mount as `POST` of
+ * an internal route (docs/plans/errors.md has no "Surface" entry for this,
+ * because it is not a public one -- `// authz: public` would be wrong here;
+ * the shared `secret` is the gate). This is where `reporting`'s real `db`
+ * lives, so this is where the edge-forwarded report finally becomes a row.
+ */
+export function edgeErrorIngestHandler(options) {
+    const collector = createEdgeErrorIngestCollector(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 {

package/dist/reader.js

@@ -19,6 +19,8 @@ export async function eventsPage(db, opts = {}) {
         conditions.push(eq(reportingEvents.site, opts.site));
     if (opts.requestId)
         conditions.push(eq(reportingEvents.requestId, opts.requestId));
+    if (opts.environment)
+        conditions.push(eq(reportingEvents.environment, opts.environment));
     if (opts.after) {
         const { occurredAt, id } = opts.after;
         const keyset = or(lt(reportingEvents.occurredAt, occurredAt), and(eq(reportingEvents.occurredAt, occurredAt), lt(reportingEvents.id, id)));

package/dist/schema.d.ts

@@ -90,4 +90,14 @@ 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;
+/**
+ * Deploy target, not per-event: stamped once on `ReportingOptions.environment`,
+ * the same as `site`, because a preview or stage deploy is a whole process
+ * running with that value, not a claim an individual event makes (gap issue
+ * #6). Unlike `runtime` or `level`, the set of names is not fixed -- a host
+ * may run `production`/`stage`/`preview`, or its own scheme -- so this only
+ * keeps it slug-shaped.
+ */
+export declare const ENVIRONMENT_PATTERN: RegExp;
+export declare const environmentSchema: z.ZodString;
 export declare const fingerprintSchema: z.ZodString;

package/dist/schema.js

@@ -90,6 +90,18 @@ export const eventInputSchema = z.strictObject({
 export const siteSchema = z
     .string()
     .regex(SITE_PATTERN, 'a site id is lower case, digits and dashes');
+/**
+ * Deploy target, not per-event: stamped once on `ReportingOptions.environment`,
+ * the same as `site`, because a preview or stage deploy is a whole process
+ * running with that value, not a claim an individual event makes (gap issue
+ * #6). Unlike `runtime` or `level`, the set of names is not fixed -- a host
+ * may run `production`/`stage`/`preview`, or its own scheme -- so this only
+ * keeps it slug-shaped.
+ */
+export const ENVIRONMENT_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/;
+export const environmentSchema = z
+    .string()
+    .regex(ENVIRONMENT_PATTERN, 'an environment is lower case, digits, dashes and underscores');
 export const fingerprintSchema = z
     .string()
     .regex(FINGERPRINT_PATTERN, 'a fingerprint is 32 lower-case hex characters');

package/dist/settings.d.ts

@@ -14,3 +14,24 @@ 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. */
 export declare function setSettings(db: Db, patch: Partial<Settings>, by: Actor): Promise<SettingsChange>;
+/**
+ * A multi-tenant company app may need a longer or shorter retention window
+ * for one customer's contract without moving the site-wide default (gap
+ * issue #11): `reporting_tenant_settings`, keyed by (tenant_id, key), one
+ * JSONB value the same shape `getSettings`/`setSettings` already parse.
+ * `reporting_prune_events`/`reporting_prune_analytics` (0006_tenant_settings.sql)
+ * check this table for the row they are about to prune before falling back
+ * to the site-wide setting.
+ */
+export declare const TENANT_RETENTION_KEYS: readonly ["events.retention_days", "analytics.retention_days"];
+export type TenantRetentionKey = (typeof TENANT_RETENTION_KEYS)[number];
+/** Only the keys this tenant has overridden; a key absent here means "use the site-wide default". */
+export declare function getTenantRetention(db: Db, tenantId: string): Promise<Partial<Record<TenantRetentionKey, number>>>;
+/**
+ * Sets a tenant's override, or clears it back to the site-wide default when
+ * `days` is `null` -- clearing never deletes the row, same "nothing that
+ * deletes" convention as `reportingSettings`: it stores the JSON `null`
+ * `reporting_prune_events`/`reporting_prune_analytics` already treat as "no
+ * override". Throws on an out-of-bounds value: the caller is a form.
+ */
+export declare function setTenantRetention(db: Db, tenantId: string, key: TenantRetentionKey, days: number | null, by: Actor): Promise<void>;

package/dist/settings.js

@@ -1,6 +1,6 @@
-import { sql } from 'drizzle-orm';
+import { eq, sql } from 'drizzle-orm';
 import { z } from 'zod';
-import { reportingSettings } from './tables.js';
+import { reportingSettings, reportingTenantSettings } from './tables.js';
 /**
  * Operator-edited settings, one row per key, read by housekeeping on every
  * run. Bounds are enforced here and again inside `reporting_prune_events`,
@@ -75,3 +75,54 @@ export async function setSettings(db, patch, by) {
         return { before, after, by, changed };
     });
 }
+/**
+ * A multi-tenant company app may need a longer or shorter retention window
+ * for one customer's contract without moving the site-wide default (gap
+ * issue #11): `reporting_tenant_settings`, keyed by (tenant_id, key), one
+ * JSONB value the same shape `getSettings`/`setSettings` already parse.
+ * `reporting_prune_events`/`reporting_prune_analytics` (0006_tenant_settings.sql)
+ * check this table for the row they are about to prune before falling back
+ * to the site-wide setting.
+ */
+export const TENANT_RETENTION_KEYS = ['events.retention_days', 'analytics.retention_days'];
+/** Only the keys this tenant has overridden; a key absent here means "use the site-wide default". */
+export async function getTenantRetention(db, tenantId) {
+    const rows = await db
+        .select({ key: reportingTenantSettings.key, value: reportingTenantSettings.value })
+        .from(reportingTenantSettings)
+        .where(eq(reportingTenantSettings.tenantId, tenantId));
+    const out = {};
+    for (const row of rows) {
+        if (typeof row.value === 'number' && Number.isInteger(row.value)) {
+            out[row.key] = row.value;
+        }
+    }
+    return out;
+}
+/**
+ * Sets a tenant's override, or clears it back to the site-wide default when
+ * `days` is `null` -- clearing never deletes the row, same "nothing that
+ * deletes" convention as `reportingSettings`: it stores the JSON `null`
+ * `reporting_prune_events`/`reporting_prune_analytics` already treat as "no
+ * override". Throws on an out-of-bounds value: the caller is a form.
+ */
+export async function setTenantRetention(db, tenantId, key, days, by) {
+    if (days !== null) {
+        const parsed = retention.safeParse(days);
+        if (!parsed.success) {
+            throw new Error(`reporting.tenantSettings: ${key} must be an integer between ${RETENTION_BOUNDS.min} and ${RETENTION_BOUNDS.max}`);
+        }
+    }
+    // The column is `jsonb not null`, and a JS `null` value maps to a SQL
+    // NULL parameter, not the JSON literal `null` -- an explicit cast is the
+    // only way to store "no override" as the value the CHECK and the prune
+    // functions both expect, rather than violate the NOT NULL constraint.
+    const value = days === null ? sql `'null'::jsonb` : sql `to_jsonb(${days}::int)`;
+    await db
+        .insert(reportingTenantSettings)
+        .values({ tenantId, key, value, updatedBy: `${by.class}:${by.id}` })
+        .onConflictDoUpdate({
+        target: [reportingTenantSettings.tenantId, reportingTenantSettings.key],
+        set: { value, updatedAt: sql `now()`, updatedBy: `${by.class}:${by.id}` },
+    });
+}