wiki-formant 0.27.1 → 0.28.0

package/README.md

@@ -551,27 +551,55 @@ export const GET = resolveMapHandler({ authorize: async () => !!(await currentUs
 
 ## Analytics
 
-Two lanes, one events helper. `mcpCallProps` reads a tool name out of a JSON-RPC
-envelope that is untrusted and may be a batch; `searchQueryProps` normalises a
-search box's free text so the same question aggregates as one row. Sending stays
-with the caller — `plausibleEvent` builds the request, and the framework's own
-deferral (`after()` in a route or server action, `event.waitUntil` in a proxy)
-decides when it goes, so this package keeps its zero-dependency guarantee.
+Page views and events, counted in the site's own Postgres instead of a hosted
+service. No cookie is set and no address is kept: a visitor is a hash of the
+address and browser under a salt that is replaced every UTC day, and the old
+salt is deleted, so a visitor is told apart within a day and never followed
+into the next. Rows are kept 400 days. The package owns the SQL and the app
+owns the connection: `Sql` is one function that runs a statement with `$1, $2…`
+placeholders, and the three tables it needs are stated as Prisma models at the
+top of `src/analytics.ts`.
+
+```ts
+// src/lib/track.ts
+export const sql: Sql = (query, ...values) => prisma.$queryRawUnsafe(query, ...values);
+
+// src/app/api/view/route.ts – the whole beacon route
+export const POST = (request: Request) => collect(request, { sql, defer: after });
+
+// the root layout, once
+<Beacon />
+```
+
+`<Beacon>` (`wiki-formant/react`) sends a view each time the path changes,
+client-side moves included, and a click on a link to another host as an
+"Outbound Link: Click" event; `track(name, props)` (`wiki-formant/dom`) sends
+any other browser event. Server code calls `recordEvent` and leaves the
+deferral to the framework, so this package keeps its zero-dependency
+guarantee:
 
 ```ts
 const props = searchQueryProps({ query, results: rows.length, surface: 'wiki' });
 // null for an empty field, so a blank search cannot fire an event
-if (props) after(() => plausibleEvent({ domain }, 'Search Query', url, props, headers, {
-  // a person triggered this, so it joins their session rather than landing
-  // as the fixed bot-tracker pseudo-visitor
-  userAgent: headers.get('user-agent') ?? undefined,
-}));
+if (props) after(() => recordEvent(sql, { name: 'Search Query', props, url, headers }));
 ```
 
+`mcpCallProps` reads a tool name out of a JSON-RPC envelope that is untrusted
+and may be a batch; `searchQueryProps` normalises a search box's free text so
+the same question aggregates as one row. Pass the request's headers and the
+event joins whoever sent it, person or agent.
+
+`digest(sql, { days })` reads a site back as one JSON object: visitors, page
+views, bounce rate, visit length, sources (a link's `utm_source`, else the
+referring host), top and entry pages, countries, devices, visitors by day, MCP
+tool calls, and the searches that found nothing. A visit is a run of one
+visitor's views with no gap over 30 minutes. A multi-tenant app passes a `site`
+key to every call and a `site` resolver to `collect`.
+
 Instrumenting the agent lane and not the human one is the easy mistake: it
 leaves a wiki able to say what every crawler asked for and nothing about what
-its readers asked for. The queries that return zero rows are the valuable ones —
-they name a gap in the corpus in the reader's own words.
+its readers asked for. The queries that return zero rows are the valuable ones
+– they name a gap in the corpus in the reader's own words.
 
 ## Base stylesheet
 
@@ -605,6 +633,14 @@ npx check-classes --warn         # report and exit 0
 npx check-classes --compositions # also fail on the inline compositions
 ```
 
+`analytics-digest` prints a site's `digest` as JSON for a script outside the app. Run it from the app's root, where `pg` is installed and `.env` holds `DATABASE_URL`:
+
+```sh
+npx analytics-digest --days 7
+npx analytics-digest --days 30 --handle radixwiki --siblings caper.network,acuiq.com
+npx analytics-digest --days 7 --gap "Symptom Miss:term"   # adds an event to the search gaps
+```
+
 ## Licence
 
 MIT.

package/bin/analytics-digest.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// bin/analytics-digest.mjs – print one site's `digest` (`wiki-formant/analytics`)
+// as JSON, for a script that reads traffic from outside the app.
+//
+// Run from the app's root, where `pg` is installed and `.env` holds
+// DATABASE_URL (read from the environment first). The SQL is the package's, so
+// a report reads the figures the app's own pages read.
+//
+//   npx analytics-digest --days 7
+//   npx analytics-digest --days 30 --handle radixwiki --siblings caper.network,acuiq.com
+//   npx analytics-digest --days 7 --site <id>             # a multi-tenant app's site
+//   npx analytics-digest --days 7 --gap "Symptom Miss:term"   # adds to the search gaps
+import pg from 'pg';
+import { digest, SEARCH_GAPS } from '../dist/analytics.js';
+
+const args = process.argv.slice(2);
+const arg = name => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const all = name => args.flatMap((a, i) => (a === name && args[i + 1] ? [args[i + 1]] : []));
+
+if (!process.env.DATABASE_URL) {
+  try {
+    process.loadEnvFile('.env');
+  } catch {
+    // reported below
+  }
+}
+if (!process.env.DATABASE_URL) {
+  console.log(JSON.stringify({ error: 'no DATABASE_URL in the environment or ./.env' }));
+  process.exit(0);
+}
+
+const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
+try {
+  await client.connect();
+  const sql = (query, ...values) => client.query(query, values).then(r => r.rows);
+  const result = await digest(sql, {
+    site: arg('--site') ?? '',
+    days: Number(arg('--days') ?? 7),
+    handle: arg('--handle'),
+    siblings: arg('--siblings')?.split(',').filter(Boolean) ?? [],
+    gaps: [
+      SEARCH_GAPS,
+      ...all('--gap').map(g => {
+        const [event, prop] = g.split(':');
+        return { event, prop };
+      }),
+    ],
+  });
+  console.log(JSON.stringify(result));
+} catch (e) {
+  console.log(JSON.stringify({ error: e.message }));
+} finally {
+  await client.end().catch(() => {});
+}

package/dist/analytics.d.ts

@@ -1,36 +1,127 @@
-import type { HeaderReader } from './rate-limit.js';
-export interface PlausibleConfig {
-    /** The hostname the Plausible property is registered under. */
-    domain: string;
-    /** Override for self-hosted Plausible. */
-    endpoint?: string;
+import { type HeaderReader, type RateLimitOptions } from './rate-limit.js';
+/**
+ * Runs one statement with `$1, $2…` placeholders and resolves to its rows.
+ * Prisma: `(query, ...values) => prisma.$queryRawUnsafe(query, ...values)`.
+ */
+export type Sql = (query: string, ...values: unknown[]) => Promise<unknown>;
+/** Long enough to compare a month with the same month a year before. */
+export declare const KEEP_DAYS = 400;
+/** iPadOS reports itself as a Mac, so its views count as a computer's. */
+export declare const deviceOf: (ua: string) => "phone" | "tablet" | "computer";
+/**
+ * Where a visit came from: its `utm_source` when the link carried one, else the
+ * referring host, and null for a referrer that is this site or none.
+ */
+export declare function sourceOf(referrer: unknown, utm: unknown, host: string): string | null;
+/** A browser path as stored: decoded, one leading slash, no trailing one. Null when it will not decode. */
+export declare function normalisePath(path: string): string | null;
+export interface ViewInput {
+    /** The beacon request's headers: the address, browser, host and country come from them. */
+    headers: HeaderReader;
+    path: string;
+    referrer?: unknown;
+    /** The page URL's `utm_source`. */
+    utm?: unknown;
+    site?: string;
+}
+/** Count one page view, unless a bot sent it. Never rejects. */
+export declare function recordView(sql: Sql, { headers, path, referrer, utm, site }: ViewInput): Promise<void>;
+export interface EventInput {
+    name: string;
+    props?: Record<string, string | number>;
+    /** The page it happened on, as a URL or a path. */
+    url?: string;
+    /** The request of whoever caused it, so the event joins their visitor. Omit for an event no visitor caused. */
+    headers?: HeaderReader;
+    site?: string;
+}
+/** Record one named event. Never rejects. */
+export declare function recordEvent(sql: Sql, { name, props, url, headers, site }: EventInput): Promise<void>;
+/** What a page sends: a view, or with `name` an event. */
+export interface Beacon {
+    path: string;
+    referrer?: string;
+    utm?: string;
+    name?: string;
+    props?: Record<string, string | number>;
 }
-export interface PlausibleExtra {
-    /** Revenue goal payload; accepted and ignored on plans without revenue goals. */
-    revenue?: {
-        currency: string;
-        amount: number;
-    };
+export interface CollectOptions {
+    sql: Sql;
+    /** `after` in a Next route: the write runs once the 204 has gone. */
+    defer: (task: () => Promise<unknown>) => void;
+    /** The site a beacon counts toward, or null to drop it. A single-site app omits it. */
+    site?: (request: Request, path: string) => string | null | Promise<string | null>;
+    rateLimit?: RateLimitOptions;
+}
+/**
+ * The whole beacon route: `export const POST = (r: Request) => collect(r, { sql, defer: after })`.
+ * Answers 204 whatever happens, before anything is written, so a reader never waits on it.
+ */
+export declare function collect(request: Request, { sql, defer, site, rateLimit: limit }: CollectOptions): Promise<Response>;
+export interface Gap {
+    event: string;
+    /** The prop holding the reader's words. */
+    prop: string;
+    /** Props the event must carry, e.g. `{ results: '0' }`. */
+    where?: Record<string, string>;
+}
+/** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
+export declare const SEARCH_GAPS: Gap;
+export interface DigestOptions {
+    site?: string;
+    /** How far back, in whole days from now. */
+    days: number;
+    /** The site's own X handle: `follow_clicks` counts clicks on links to it. */
+    handle?: string;
+    /** Hosts of sibling sites: `sibling_referrals` counts the visits they sent. */
+    siblings?: string[];
+    gaps?: Gap[];
     /**
-     * Send the visitor's own user agent so the event joins their session rather
-     * than landing as the fixed bot-tracker pseudo-visitor. Right for an event
-     * a person triggered; wrong for one a crawler did.
+     * MCP callers left out of `agent_tool_calls`, matched inside the user agent.
+     * The default is the conformance suites (`<repo>-mcp-test`) and the studio's own tools.
      */
-    userAgent?: string;
+    ownAgents?: string[];
+}
+type Ranked<K extends string, M extends string> = Array<Record<K, string> & Record<M, number>>;
+export interface Digest {
+    visitors: number;
+    pageviews: number;
+    /** Percent of visits that saw one page; null with no visits. */
+    bounce_rate: number | null;
+    /** Mean seconds from a visit's first view to its last; null with no visits. */
+    visit_duration: number | null;
+    /** Visitors plus every agent that sent an event, such as an MCP call. */
+    visitors_incl_agents: number;
+    /** Visitors in the same number of days before. */
+    previous_visitors: number;
+    top_sources: Ranked<'source', 'visitors'>;
+    top_pages: Ranked<'page', 'visitors'>;
+    entry_pages: Ranked<'page', 'visitors'>;
+    /** Entry pages of visits from links tagged `utm_source=x`. */
+    from_posts: Ranked<'page', 'visitors'>;
+    sibling_referrals: Ranked<'source', 'visitors'>;
+    countries: Ranked<'country', 'visitors'>;
+    devices: Ranked<'device', 'visitors'>;
+    by_day: Ranked<'date', 'visitors'>;
+    follow_clicks: {
+        events: number;
+        visitors: number;
+    } | null;
+    agent_tool_calls: Ranked<'tool', 'events'>;
+    gaps: Ranked<'query', 'events'>;
 }
 /**
- * The exact request shape Plausible's events API expects.
- *
- * Never rejects: analytics must not be able to fail a response the reader is
- * waiting on.
+ * Everything a report needs about one site's last `days` days, in one query.
+ * Visitor figures count distinct visitors, so a person who comes back on
+ * another day counts once for each day.
  */
-export declare function plausibleEvent(config: PlausibleConfig, name: string, url: string, props: Record<string, string>, headers: HeaderReader, extra?: PlausibleExtra): Promise<unknown>;
+export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents }: DigestOptions): Promise<Digest>;
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.
  *
  * The body is untrusted and may be a batch, a notification, or malformed
  * entirely, so every extraction is defensive and the result is always a
- * complete props object. A batch is attributed to its first member — the
+ * complete props object. A batch is attributed to its first member – the
  * alternative is one event per member, which would make a fan-out look like
  * traffic it is not.
  */
@@ -47,7 +138,7 @@ export interface SearchQueryInput {
     surface?: string;
 }
 /**
- * Props for a "Search Query" event — the human-side twin of `mcpCallProps`.
+ * Props for a "Search Query" event – the human-side twin of `mcpCallProps`.
  *
  * A wiki instruments its agent surface and then counts every question an agent
  * asks while recording none of the questions a person asks. The queries that
@@ -56,9 +147,8 @@ export interface SearchQueryInput {
  *
  * Returns `null` for a query with no content, so an empty field cannot fire an
  * event. The text is untrusted, so it is collapsed, lowercased for aggregation
- * and truncated — the same 64-character bound search itself applies, which
+ * and truncated – the same 64-character bound search itself applies, which
  * keeps the prop and the query that produced it the same string.
  */
 export declare function searchQueryProps({ query, results, surface, }: SearchQueryInput): Record<string, string> | null;
-/** The hostname of a site URL, for the `domain` a Plausible property is filed under. */
-export declare function plausibleDomain(siteUrl: string | undefined, fallback: string): string;
+export {};

package/dist/analytics.js

@@ -1,49 +1,235 @@
-// analytics.ts — server-side Plausible events for a wiki's agent and human lanes.
+// analytics.ts – page views and events, counted in the site's own Postgres.
 //
-// The proxy counts an "AI Bot Visit" by matching user agents, which cannot see
-// inside a JSON-RPC envelope. So an MCP call is only countable by tool name at
-// the route, and that extraction — from a body that is untrusted and may be a
-// batch — is the part worth sharing. Every wiki in the workspace had its own
-// copy of it, differing only in the default hostname.
+// It replaces a hosted analytics service. A page reports its own view to the
+// site's own address (`startBeacon` in `dom.ts`, `<Beacon>` in `react.tsx`), a
+// route hands the beacon to `collect`, and server code records events with
+// `recordEvent`. `digest` reads it all back as one JSON object, and the
+// `analytics-digest` bin prints that object for scripts outside the app.
 //
-// `searchQueryProps` is the human-side twin: the same shape problem, from the
-// other direction. A search box is untrusted free text on every wiki, and the
-// normalisation that makes it aggregatable — and keeps an empty field from
-// firing an event — is the part worth sharing rather than re-deriving.
+// No cookie is set and no address is kept. A visitor is a hash of the address
+// and the browser under a salt that changes every UTC day, and the old salt is
+// deleted when the new one is made, so a visitor can be told apart within a day
+// and never followed into the next. A visit is a run of one visitor's views
+// with no gap over 30 minutes.
 //
-// Deferral stays with the caller: `after()` in a route handler,
-// `event.waitUntil` in a proxy. Both are framework calls, and importing one
-// here would cost this package its zero-dependency guarantee.
-const DEFAULT_ENDPOINT = 'https://plausible.io/api/event';
+// The package owns the SQL; the app owns the connection. `Sql` is one function
+// that runs a parameterised statement, which Prisma, `pg` and postgres.js can
+// all supply in a line. The app declares the three tables in its own schema,
+// so `prisma db push` keeps them:
+//
+//   model View {
+//     id        BigInt   @id @default(autoincrement())
+//     siteId    String   @default("")
+//     path      String
+//     source    String?
+//     country   String?
+//     device    String
+//     visitor   String
+//     createdAt DateTime @default(now()) @db.Timestamptz(3)
+//     @@index([siteId, createdAt])
+//   }
+//
+//   model Event {
+//     id        BigInt   @id @default(autoincrement())
+//     siteId    String   @default("")
+//     name      String
+//     path      String?
+//     props     Json     @default("{}")
+//     visitor   String?
+//     createdAt DateTime @default(now()) @db.Timestamptz(3)
+//     @@index([siteId, name, createdAt])
+//   }
+//
+//   model Salt {
+//     day   String @id
+//     value String
+//   }
+//
+// `siteId` is "" in an app that serves one site. A multi-tenant app passes its
+// own site key to every call.
+//
+// Deferral stays with the caller: `after()` in a route, `event.waitUntil` in a
+// proxy. Both are framework calls, and importing one here would cost this
+// package its zero-dependency guarantee. Hashing is Web Crypto, so the module
+// runs anywhere Node 20, a browser or an edge runtime does.
+import { clientIp, clientKey, rateLimit } from './rate-limit.js';
+/** Long enough to compare a month with the same month a year before. */
+export const KEEP_DAYS = 400;
+const DAY_MS = 86_400_000;
+/** A script that runs a page's JavaScript and says what it is. */
+const BOT = /bot|crawl|spider|slurp|headless|lighthouse|prerender|preview/i;
+/** iPadOS reports itself as a Mac, so its views count as a computer's. */
+export const deviceOf = (ua) => /iPad|Tablet|Android(?!.*Mobile)/i.test(ua) ? 'tablet' : /Mobi|iPhone|Android/i.test(ua) ? 'phone' : 'computer';
+const bareHost = (host) => host.toLowerCase().replace(/:\d+$/, '').replace(/^www\./, '');
 /**
- * The exact request shape Plausible's events API expects.
- *
- * Never rejects: analytics must not be able to fail a response the reader is
- * waiting on.
+ * Where a visit came from: its `utm_source` when the link carried one, else the
+ * referring host, and null for a referrer that is this site or none.
  */
-export function plausibleEvent(config, name, url, props, headers, extra = {}) {
-    return fetch(config.endpoint ?? DEFAULT_ENDPOINT, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'User-Agent': extra.userAgent || 'Mozilla/5.0 (compatible; BotTracker/1.0)',
-            'X-Forwarded-For': headers.get('x-forwarded-for') || headers.get('x-real-ip') || '127.0.0.1',
-        },
-        body: JSON.stringify({
-            name,
-            url,
-            domain: config.domain,
-            props: JSON.stringify(props),
-            ...(extra.revenue ? { revenue: extra.revenue } : {}),
-        }),
-    }).catch(() => undefined);
+export function sourceOf(referrer, utm, host) {
+    if (typeof utm === 'string' && utm.trim())
+        return utm.trim().toLowerCase().slice(0, 100);
+    if (typeof referrer !== 'string' || !referrer)
+        return null;
+    try {
+        const from = bareHost(new URL(referrer).hostname);
+        return from && from !== bareHost(host) ? from.slice(0, 200) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A browser path as stored: decoded, one leading slash, no trailing one. Null when it will not decode. */
+export function normalisePath(path) {
+    try {
+        const p = decodeURIComponent(path.split(/[?#]/)[0].slice(0, 500));
+        return `/${p.replace(/^\/+|\/+$/g, '')}`;
+    }
+    catch {
+        return null;
+    }
+}
+const hex = (bytes) => Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+const salts = new WeakMap();
+/** Today's salt. Whoever makes it also deletes yesterday's, and rows past keeping. */
+async function todaysSalt(sql) {
+    const day = new Date().toISOString().slice(0, 10);
+    const cached = salts.get(sql);
+    if (cached?.day === day)
+        return cached.value;
+    const made = (await sql('INSERT INTO "Salt" (day, value) VALUES ($1, $2) ON CONFLICT (day) DO NOTHING RETURNING day', day, hex(crypto.getRandomValues(new Uint8Array(32)))));
+    if (made.length) {
+        const cutoff = new Date(Date.now() - KEEP_DAYS * DAY_MS);
+        await sql('DELETE FROM "Salt" WHERE day < $1', day);
+        await sql('DELETE FROM "View" WHERE "createdAt" < $1', cutoff);
+        await sql('DELETE FROM "Event" WHERE "createdAt" < $1', cutoff);
+    }
+    const [row] = (await sql('SELECT value FROM "Salt" WHERE day = $1', day));
+    salts.set(sql, { day, value: row.value });
+    return row.value;
+}
+async function visitorOf(sql, site, headers) {
+    const text = [await todaysSalt(sql), site, clientIp(headers), headers.get('user-agent') ?? ''].join('\n');
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hex(new Uint8Array(digest)).slice(0, 32);
+}
+/** Analytics must not be able to fail a response, so a failed write is logged and dropped. */
+const quietly = (task) => task().then(() => undefined, (e) => console.error(`analytics: ${e.message}`));
+/** Count one page view, unless a bot sent it. Never rejects. */
+export function recordView(sql, { headers, path, referrer, utm, site = '' }) {
+    const ua = headers.get('user-agent') ?? '';
+    const page = normalisePath(path);
+    if (!ua || BOT.test(ua) || page === null)
+        return Promise.resolve();
+    return quietly(async () => sql('INSERT INTO "View" ("siteId", path, source, country, device, visitor) VALUES ($1, $2, $3, $4, $5, $6)', site, page, sourceOf(referrer, utm, headers.get('host') ?? ''), headers.get('x-vercel-ip-country')?.slice(0, 2) || null, deviceOf(ua), await visitorOf(sql, site, headers)));
+}
+/** Record one named event. Never rejects. */
+export function recordEvent(sql, { name, props = {}, url, headers, site = '' }) {
+    return quietly(async () => {
+        let path = null;
+        if (url)
+            path = normalisePath(new URL(url, 'http://x').pathname);
+        return sql('INSERT INTO "Event" ("siteId", name, path, props, visitor) VALUES ($1, $2, $3, $4::jsonb, $5)', site, name.slice(0, 64), path, JSON.stringify(props), headers?.get('user-agent') ? await visitorOf(sql, site, headers) : null);
+    });
+}
+/** A browser-sent event's props: eight at most, each value a short string or a number. */
+function beaconProps(props) {
+    if (!props || typeof props !== 'object' || Array.isArray(props))
+        return {};
+    return Object.fromEntries(Object.entries(props)
+        .filter(([, v]) => typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v)))
+        .slice(0, 8)
+        .map(([k, v]) => [k.slice(0, 40), typeof v === 'string' ? v.slice(0, 300) : v]));
+}
+// A person reads a few pages a minute. This leaves room for a fast reader and
+// stops one address filling a site's figures.
+const BEACONS = { capacity: 30, refillPerSec: 0.5 };
+/**
+ * The whole beacon route: `export const POST = (r: Request) => collect(r, { sql, defer: after })`.
+ * Answers 204 whatever happens, before anything is written, so a reader never waits on it.
+ */
+export async function collect(request, { sql, defer, site, rateLimit: limit = BEACONS }) {
+    const done = new Response(null, { status: 204 });
+    const { headers } = request;
+    if (BOT.test(headers.get('user-agent') ?? '') || !rateLimit(clientKey('beacon', headers), limit).ok)
+        return done;
+    const body = (await request.json().catch(() => null));
+    const path = typeof body?.path === 'string' ? normalisePath(body.path) : null;
+    if (!body || !path)
+        return done;
+    const key = site ? await site(request, path) : '';
+    if (key === null)
+        return done;
+    defer(() => typeof body.name === 'string' && body.name
+        ? recordEvent(sql, { name: body.name, props: beaconProps(body.props), url: path, headers, site: key })
+        : recordView(sql, { headers, path, referrer: body.referrer, utm: body.utm, site: key }));
+    return done;
+}
+/** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
+export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results: '0', surface: 'wiki' } };
+/**
+ * Everything a report needs about one site's last `days` days, in one query.
+ * Visitor figures count distinct visitors, so a person who comes back on
+ * another day counts once for each day.
+ */
+export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'] }) {
+    // The window is the database's clock, which stamped the rows; the app's can run behind it.
+    const values = [site, Math.max(1, Math.round(days))];
+    const $ = (v) => `$${values.push(v)}`;
+    const list = (select, limit, order = '2 DESC, 1') => `(SELECT coalesce(json_agg(t), '[]') FROM (${select} ORDER BY ${order}${limit ? ` LIMIT ${limit}` : ''}) t)`;
+    const gapSelects = gaps.map(g => {
+        const prop = $(g.prop);
+        return `(SELECT props->>${prop} AS query, count(*) AS events FROM e
+      WHERE name = ${$(g.event)} AND props @> ${$(JSON.stringify(g.where ?? {}))}::jsonb AND props->>${prop} IS NOT NULL
+      GROUP BY 1 ORDER BY 2 DESC, 1 LIMIT 15)`;
+    });
+    const [row] = (await sql(`WITH v AS (
+      SELECT id, path, source, country, device, visitor, "createdAt" AS at FROM "View"
+      WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
+    ), marked AS (
+      SELECT *, CASE WHEN at - lag(at) OVER (PARTITION BY visitor ORDER BY at, id) <= interval '30 minutes' THEN 0 ELSE 1 END AS starts FROM v
+    ), numbered AS (
+      SELECT *, sum(starts) OVER (PARTITION BY visitor ORDER BY at, id) AS visit FROM marked
+    ), visits AS (
+      SELECT visitor, count(*) AS views, extract(epoch FROM max(at) - min(at)) AS seconds,
+        (array_agg(path ORDER BY at, id))[1] AS entry, (array_agg(source ORDER BY at, id))[1] AS source
+      FROM numbered GROUP BY visitor, visit
+    ), e AS (
+      SELECT name, props, visitor FROM "Event" WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
+    )
+    SELECT json_build_object(
+      'visitors', (SELECT count(DISTINCT visitor) FROM v),
+      'pageviews', (SELECT count(*) FROM v),
+      'bounce_rate', (SELECT round(100.0 * count(*) FILTER (WHERE views = 1) / nullif(count(*), 0)) FROM visits),
+      'visit_duration', (SELECT round(avg(seconds)) FROM visits),
+      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v UNION SELECT visitor FROM e) a),
+      'previous_visitors', (SELECT count(DISTINCT visitor) FROM "View"
+        WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => 2 * $2::int) AND "createdAt" < now() - make_interval(days => $2::int)),
+      'top_sources', ${list(`SELECT coalesce(source, '(none)') AS source, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1`, 6)},
+      'top_pages', ${list('SELECT path AS page, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1', 6)},
+      'entry_pages', ${list('SELECT entry AS page, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1', 6)},
+      'from_posts', ${list(`SELECT entry AS page, count(DISTINCT visitor) AS visitors FROM visits WHERE source = 'x' GROUP BY 1`, 15)},
+      'sibling_referrals', ${list(`SELECT source, count(DISTINCT visitor) AS visitors FROM visits WHERE source = ANY(${$(siblings)}::text[]) GROUP BY 1`, 6)},
+      'countries', ${list('SELECT country, count(DISTINCT visitor) AS visitors FROM v WHERE country IS NOT NULL GROUP BY 1', 10)},
+      'devices', ${list('SELECT device, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1')},
+      'by_day', ${list(`SELECT to_char(at AT TIME ZONE 'UTC', 'YYYY-MM-DD') AS date, count(DISTINCT visitor) AS visitors FROM v GROUP BY 1`, undefined, '1')},
+      'follow_clicks', ${handle
+        ? `(SELECT json_build_object('events', count(*), 'visitors', count(DISTINCT visitor)) FROM e
+              WHERE name = 'Outbound Link: Click' AND props->>'url' ILIKE ANY(${$([`%x.com/${handle}%`, `%twitter.com/${handle}%`])}::text[]))`
+        : 'NULL'},
+      'agent_tool_calls', ${list(`SELECT coalesce(props->>'tool', '(none)') AS tool, count(*) AS events FROM e
+         WHERE name = 'MCP Call' AND props->>'method' = 'tools/call'
+           AND NOT coalesce(props->>'ua', '') ILIKE ANY(${$(ownAgents.map(a => `%${a}%`))}::text[])
+         GROUP BY 1`, 10)},
+      'gaps', ${gapSelects.length ? `(SELECT coalesce(json_agg(t), '[]') FROM (${gapSelects.join(' UNION ALL ')}) t)` : `'[]'::json`}
+    ) AS digest`, ...values));
+    return row.digest;
 }
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.
  *
  * The body is untrusted and may be a batch, a notification, or malformed
  * entirely, so every extraction is defensive and the result is always a
- * complete props object. A batch is attributed to its first member — the
+ * complete props object. A batch is attributed to its first member – the
  * alternative is one event per member, which would make a fan-out look like
  * traffic it is not.
  */
@@ -55,7 +241,7 @@ export function mcpCallProps(request, body, server) {
     return { ...(server ? { server } : {}), method, ...(tool ? { tool } : {}), ua };
 }
 /**
- * Props for a "Search Query" event — the human-side twin of `mcpCallProps`.
+ * Props for a "Search Query" event – the human-side twin of `mcpCallProps`.
  *
  * A wiki instruments its agent surface and then counts every question an agent
  * asks while recording none of the questions a person asks. The queries that
@@ -64,7 +250,7 @@ export function mcpCallProps(request, body, server) {
  *
  * Returns `null` for a query with no content, so an empty field cannot fire an
  * event. The text is untrusted, so it is collapsed, lowercased for aggregation
- * and truncated — the same 64-character bound search itself applies, which
+ * and truncated – the same 64-character bound search itself applies, which
  * keeps the prop and the query that produced it the same string.
  */
 export function searchQueryProps({ query, results, surface, }) {
@@ -73,18 +259,8 @@ export function searchQueryProps({ query, results, surface, }) {
         return null;
     return {
         q,
-        // A string because Plausible props are strings; `results == "0"` is the
-        // filter that yields the gap list.
+        // A string, so `{ results: '0' }` is the filter that yields the gap list.
         results: String(Math.max(0, Math.trunc(results) || 0)),
         ...(surface ? { surface } : {}),
     };
 }
-/** The hostname of a site URL, for the `domain` a Plausible property is filed under. */
-export function plausibleDomain(siteUrl, fallback) {
-    try {
-        return new URL(siteUrl || fallback).hostname;
-    }
-    catch {
-        return fallback.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
-    }
-}

package/dist/dom.d.ts

@@ -103,3 +103,18 @@ export declare function sortTables(root: ParentNode, options?: SortTablesOptions
  * A table already in a box keeps it, so a second pass changes nothing.
  */
 export declare function scrollTables(html: string): string;
+/**
+ * Report each page view to the site's own `endpoint`, whose route hands it to
+ * `collect` (`wiki-formant/analytics`). Same-origin, so no third-party script
+ * runs and no blocklist names the request.
+ *
+ * A client-side router moves between pages with `history.pushState`, which no
+ * load event marks, so both history writes are wrapped and a view is sent
+ * whenever the path changes; a change to the query or hash alone is not a page.
+ * A click on a link to another host is sent as an "Outbound Link: Click" event
+ * carrying its `url`. Starts once per page load however often it is called, so
+ * React's doubled effects in development send one view, not two.
+ */
+export declare function startBeacon(endpoint?: string): void;
+/** Record a named event from the browser, on the endpoint `startBeacon` was given. */
+export declare function track(name: string, props?: Record<string, string | number>): void;

package/dist/dom.js

@@ -322,3 +322,60 @@ export function scrollTables(html) {
         return hadBox ? tag : SCROLL_BOX + tag;
     });
 }
+// ---- analytics beacon -------------------------------------------------------
+let beaconEndpoint = '/api/view';
+let beaconStarted = false;
+const sendBeacon = (body) => navigator.sendBeacon?.(beaconEndpoint, JSON.stringify(body));
+/**
+ * Report each page view to the site's own `endpoint`, whose route hands it to
+ * `collect` (`wiki-formant/analytics`). Same-origin, so no third-party script
+ * runs and no blocklist names the request.
+ *
+ * A client-side router moves between pages with `history.pushState`, which no
+ * load event marks, so both history writes are wrapped and a view is sent
+ * whenever the path changes; a change to the query or hash alone is not a page.
+ * A click on a link to another host is sent as an "Outbound Link: Click" event
+ * carrying its `url`. Starts once per page load however often it is called, so
+ * React's doubled effects in development send one view, not two.
+ */
+export function startBeacon(endpoint = '/api/view') {
+    if (beaconStarted || typeof window === 'undefined')
+        return;
+    beaconStarted = true;
+    beaconEndpoint = endpoint;
+    let last = '';
+    let first = true;
+    const view = () => {
+        if (location.pathname === last)
+            return;
+        last = location.pathname;
+        // document.referrer belongs to the page load, so only its first view carries it.
+        sendBeacon({
+            path: last,
+            referrer: first ? document.referrer : undefined,
+            utm: new URLSearchParams(location.search).get('utm_source') ?? undefined,
+        });
+        first = false;
+    };
+    for (const method of ['pushState', 'replaceState']) {
+        const write = history[method];
+        history[method] = function (...args) {
+            write.apply(this, args);
+            view();
+        };
+    }
+    addEventListener('popstate', view);
+    document.addEventListener('click', e => {
+        const a = e.target?.closest?.('a[href]');
+        if (a instanceof HTMLAnchorElement && /^https?:$/.test(a.protocol) && a.host !== location.host) {
+            track('Outbound Link: Click', { url: a.href });
+        }
+    }, { capture: true });
+    view();
+}
+/** Record a named event from the browser, on the endpoint `startBeacon` was given. */
+export function track(name, props) {
+    if (typeof window === 'undefined')
+        return;
+    sendBeacon({ name, path: location.pathname, props });
+}

package/dist/react.d.ts

@@ -444,3 +444,10 @@ export type { WikiLinkComponent, WikiLinkProps } from './react-server.js';
 export declare function useArticlePasses(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;
 /** Tweet placeholders hydrated, and their iframes kept sized to the posted height. */
 export declare function useTweetEmbeds(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;
+/**
+ * Counts the page views of the app it is mounted in: place it once, in the root
+ * layout. `endpoint` is the route that hands the beacon to `collect`.
+ */
+export declare function Beacon({ endpoint }: {
+    endpoint?: string;
+}): null;

package/dist/react.js

@@ -27,7 +27,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 //      state on <html> before first paint. The hook keeps that attribute in
 //      sync afterwards, so CSS has one source of truth either side of hydration.
 import { railBreakpointMismatch, readRailFloating, resolveSidebarOpen, SIDEBAR_ATTRIBUTE, } from './sidebar.js';
-import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbeds, sortTables } from './dom.js';
+import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbeds, sortTables, startBeacon } from './dom.js';
 import { comboboxAria } from './combobox.js';
 import { Component, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
 const readStored = (key) => {
@@ -820,3 +820,11 @@ export function useTweetEmbeds(ref, deps) {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 }
+/**
+ * Counts the page views of the app it is mounted in: place it once, in the root
+ * layout. `endpoint` is the route that hands the beacon to `collect`.
+ */
+export function Beacon({ endpoint = '/api/view' }) {
+    useEffect(() => startBeacon(endpoint), [endpoint]);
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -182,7 +182,8 @@
   },
   "bin": {
     "check-classes": "bin/check-classes.mjs",
-    "check-pages": "bin/check-pages.mjs"
+    "check-pages": "bin/check-pages.mjs",
+    "analytics-digest": "bin/analytics-digest.mjs"
   },
   "files": [
     "dist",
@@ -239,7 +240,8 @@
     "fast-diff": ">=1.3",
     "jose": ">=5",
     "react": ">=18",
-    "sanitize-html": ">=2"
+    "sanitize-html": ">=2",
+    "pg": ">=8"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -295,6 +297,9 @@
     },
     "fast-diff": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   }
 }