@evinvest/kitstart 0.4.0 → 0.6.0

package/dist/react/use-lead-events.js

@@ -0,0 +1,62 @@
+"use client";
+import { useEffect, useMemo, useRef } from "react";
+import { EVENTS, experimentProps } from "../core/analytics.js";
+import { useAnalyticsSink } from "./analytics-context.js";
+/** The attribute a lead form's control names its role in, for `lead_form_field_error`. */
+export const FIELD_ATTR = "data-lead-field";
+/**
+ * The lead form's own funnel, reported through the boundary's sink: seen
+ * (half of it in view, once), started (the first focus inside, once), a
+ * field the browser refused (`invalid`, by role — never the value), and the
+ * step `qualify-first` moved to. Every event carries the form, the layout and
+ * the site's experiment, so the arms of a test compare on one schema.
+ */
+export function useLeadEvents(root, tags) {
+    const sink = useAnalyticsSink();
+    const { formId, layout } = tags;
+    const name = tags.experiment?.name;
+    const variant = tags.experiment?.variant;
+    const props = useMemo(() => ({ form_id: formId, layout, ...experimentProps(name, variant) }), [formId, layout, name, variant]);
+    const started = useRef(false);
+    useEffect(() => {
+        const el = root.current;
+        if (!sink || !el)
+            return;
+        let seen = false;
+        const view = () => {
+            if (seen)
+                return;
+            seen = true;
+            sink.capture(EVENTS.formView, props);
+        };
+        // Without an observer (an old browser, a test DOM) rendering is seeing.
+        const observer = typeof IntersectionObserver === "function" ? new IntersectionObserver(es => es.some(e => e.isIntersecting) && view(), { threshold: 0.5 }) : null;
+        if (observer)
+            observer.observe(el);
+        else
+            view();
+        const focus = () => {
+            if (started.current)
+                return;
+            started.current = true;
+            sink.capture(EVENTS.formStart, props);
+        };
+        // `invalid` does not bubble: listened to on the way down.
+        const invalid = (event) => {
+            const field = event.target instanceof Element ? event.target.getAttribute(FIELD_ATTR) : null;
+            if (field)
+                sink.capture(EVENTS.fieldError, { ...props, field });
+        };
+        el.addEventListener("focusin", focus);
+        el.addEventListener("invalid", invalid, true);
+        return () => {
+            observer?.disconnect();
+            el.removeEventListener("focusin", focus);
+            el.removeEventListener("invalid", invalid, true);
+        };
+    }, [sink, root, props]);
+    return useMemo(() => ({
+        step: step => sink?.capture(EVENTS.formStep, { ...props, step }),
+        fieldError: field => sink?.capture(EVENTS.fieldError, { ...props, field }),
+    }), [sink, props]);
+}

package/dist/server/env.d.ts

@@ -3,7 +3,7 @@ import { type ProxyTrust } from "./client-key.js";
 import { type LeadDb } from "./lead-store.js";
 /**
  * The server's runtime configuration, parsed once. Secrets (`SMTP_URL`,
- * `SMS_TOKEN`, `POSTHOG_KEY`) arrive from the container environment, never
+ * `SMS_TOKEN`, `POSTHOG_KEY`, `LEAD_WEBHOOK_SECRET`) arrive from the container environment, never
  * from the image.
  *
  * Production has no default for where state lives: a missing lead store
@@ -27,6 +27,12 @@ export interface ServerEnv {
     /** Whose word the rate limit takes for the client's address; see `ProxyTrust`. */
     trustedProxy: ProxyTrust | null;
     smsToken: string | null;
+    /** Where queued leads are POSTed, signed; `null` → the webhook is off. */
+    leadWebhook: {
+        url: string;
+        keyId: string;
+        secret: string;
+    } | null;
     posthogKey: string | null;
     posthogHost: string;
 }

package/dist/server/env.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseProxyTrust } from "./client-key.js";
 import { parseLeadDb } from "./lead-store.js";
+import { checkWebhookUrl } from "./webhook-outbox.js";
 function opt(source, name) {
     const value = source[name]?.trim();
     return value ? value : null;
@@ -42,6 +43,19 @@ function leadsDb(source, production, brandId) {
     }
     return { leadsDb: { kind: "sqlite", path: join(homedir(), ".local/share", brandId, "leads.db") }, leadsDbFrom: "default" };
 }
+/** All three or none: a URL without its key would sign nothing a receiver accepts. */
+function leadWebhook(source) {
+    const raw = opt(source, "LEAD_WEBHOOK_URL");
+    if (raw === null)
+        return null;
+    const url = checkWebhookUrl(raw);
+    const keyId = opt(source, "LEAD_WEBHOOK_KEY_ID");
+    const secret = opt(source, "LEAD_WEBHOOK_SECRET");
+    if (keyId === null || secret === null) {
+        throw new Error("LEAD_WEBHOOK_URL is set: LEAD_WEBHOOK_KEY_ID and LEAD_WEBHOOK_SECRET are required too");
+    }
+    return { url, keyId, secret };
+}
 export function parseServerEnv(site, source) {
     const production = source["NODE_ENV"] === "production";
     const trust = opt(source, "TRUSTED_PROXY");
@@ -57,6 +71,7 @@ export function parseServerEnv(site, source) {
         notifyTo: opt(source, "LEAD_NOTIFY_TO"),
         notifyFrom: opt(source, "LEAD_NOTIFY_FROM"),
         smsToken: opt(source, "SMS_TOKEN"),
+        leadWebhook: leadWebhook(source),
         posthogKey: opt(source, "POSTHOG_KEY"),
         // Explicit because PostHog rejects a project's events at the other
         // region's host; the audience is European, so EU unless told otherwise.

package/dist/server/index.d.ts

@@ -13,3 +13,6 @@ export { parseSmtpUrl, sendMail, type Mail, type SendOptions } from "./smtp.js";
 export { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE, type LeadMail, type LeadNotifier, type NotifyEnv } from "./notify.js";
 export { clientKey, NO_CLIENT_ADDRESS, parseProxyTrust, type ProxyTrust } from "./client-key.js";
 export { checkLeadStore } from "./boot.js";
+export { leadWebhook, panelChannel, type BuildWebhookBody, type LeadWebhook, type LeadWebhookContext, type LeadWebhookOptions } from "./lead-webhook.js";
+export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TICK_MS, type OutboxRow, type OutboxState, type TickReport, type WebhookOutbox, type WebhookOutboxOptions, type WebhookTarget, } from "./webhook-outbox.js";
+export { signatureHeaders, signWebhook, type WebhookSignatureHeaders, type WebhookSigning } from "./webhook-signature.js";

package/dist/server/index.js

@@ -13,3 +13,6 @@ export { parseSmtpUrl, sendMail } from "./smtp.js";
 export { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE } from "./notify.js";
 export { clientKey, NO_CLIENT_ADDRESS, parseProxyTrust } from "./client-key.js";
 export { checkLeadStore } from "./boot.js";
+export { leadWebhook, panelChannel } from "./lead-webhook.js";
+export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TICK_MS, } from "./webhook-outbox.js";
+export { signatureHeaders, signWebhook } from "./webhook-signature.js";

package/dist/server/lead-store-sqlite.js

@@ -1,7 +1,7 @@
 import "server-only";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { LEAD_SCHEMA_VERSION } from "../core/lead.js";
+import { channelOf, LEAD_SCHEMA_VERSION } from "../core/lead.js";
 // `node:sqlite` is reached through `getBuiltinModule` rather than an import so
 // the bundler never has to resolve a builtin it may not know yet; the type is
 // the module's own.
@@ -42,6 +42,14 @@ const STEPS = [
     db => db.exec("ALTER TABLE leads ADD COLUMN spam_verdict TEXT"),
     // 4 — the brand's extra fields, as a JSON object; `NULL` when there are none.
     db => db.exec("ALTER TABLE leads ADD COLUMN extras TEXT"),
+    // 5 — how the lead was asked for (`form`, `callback`), and a callback's
+    // consent: when the server accepted it and the sentence shown. Nullable: a
+    // row from before is a form lead, and a form lead has no consent to keep.
+    db => {
+        db.exec("ALTER TABLE leads ADD COLUMN channel TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN consent_at TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN consent_text TEXT");
+    },
 ];
 if (STEPS.length !== LEAD_SCHEMA_VERSION) {
     // The version belongs to the port, shared by every adapter; this table of
@@ -66,7 +74,7 @@ function recognise(db) {
         throw new Error(`leads: an unrecognised table (${columns.join(", ")}); refusing to migrate it`);
     }
     let at = 1;
-    for (const [step, added] of [[2, "location_id"], [3, "spam_verdict"], [4, "extras"]]) {
+    for (const [step, added] of [[2, "location_id"], [3, "spam_verdict"], [4, "extras"], [5, "consent_text"]]) {
         if (!columns.includes(added))
             break;
         at = step;
@@ -130,12 +138,12 @@ export function openSqliteLeadStore(path) {
         db.close();
         throw error;
     }
-    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras) VALUES (?, ?, ?, ?, ?, ?) RETURNING id");
+    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id");
     const count = db.prepare("SELECT COUNT(*) AS n FROM leads");
     return {
         async insert(lead) {
             const extras = Object.keys(lead.extras).length > 0 ? JSON.stringify(lead.extras) : null;
-            return integer(insert.get(lead.subject, lead.locality, lead.mobile, lead.placeSlug, lead.spamVerdict, extras), "id");
+            return integer(insert.get(lead.subject, lead.locality, lead.mobile, lead.placeSlug, lead.spamVerdict, extras, channelOf(lead), lead.consent?.at ?? null, lead.consent?.text ?? null), "id");
         },
         async count() {
             return integer(count.get(), "n");

package/dist/server/lead-webhook.d.ts

@@ -0,0 +1,61 @@
+import "server-only";
+import type { Lead, LeadChannel } from "../core/lead.js";
+import type { ServerEnv } from "./env.js";
+import { type TickReport, type WebhookOutbox, type WebhookOutboxOptions } from "./webhook-outbox.js";
+import type { WebhookSigning } from "./webhook-signature.js";
+/** What the brand's body builder is told besides the lead. */
+export interface LeadWebhookContext {
+    /** The row id in the leads table. */
+    leadId: number;
+    brandId: string;
+    locale: string;
+    formId: string;
+    /** When the lead was accepted. */
+    at: Date;
+    /** Fresh per lead and stored with the body, so every retry carries the same one. */
+    idempotencyKey: string;
+}
+/**
+ * What the Service-Arb panel's `lead.created` calls a callback request. Its
+ * `properties.channel` is a closed set (`form` | `phone_inbound`) and an event
+ * outside it is refused whole — the outbox would park the lead — so until the
+ * panel's `sa.funnel.v1` accepts `callback`, a callback travels as `form`.
+ * TODO(panel): set to "callback" once the panel accepts it; nothing else changes.
+ */
+declare const PANEL_CALLBACK = "form";
+/** A lead's channel as the panel's `properties.channel` may carry it: `panelChannel(channelOf(lead))`. */
+export declare function panelChannel(channel: LeadChannel): "form" | typeof PANEL_CALLBACK;
+/**
+ * The receiver's body, built by the brand: the kit serialises and signs
+ * whatever this returns and knows nothing of its shape. Called once, when the
+ * lead is queued — the stored body is what every attempt sends.
+ */
+export type BuildWebhookBody = (lead: Lead, ctx: LeadWebhookContext) => unknown;
+export interface LeadWebhook {
+    /** Builds, serialises and queues the lead's body; returns the outbox row. */
+    enqueue(lead: Lead, id: number, meta: {
+        locale: string;
+        formId: string;
+    }): number;
+    tick(): Promise<TickReport>;
+    start(intervalMs?: number): void;
+    stop(): void;
+    close(): void;
+    readonly outbox: WebhookOutbox;
+}
+export interface LeadWebhookOptions extends WebhookOutboxOptions {
+    /** Absent → the webhook is off, whatever the environment says. */
+    buildBody?: BuildWebhookBody | undefined;
+    signing: WebhookSigning;
+}
+/**
+ * The lead webhook, or `null` when it is off: no `LEAD_WEBHOOK_URL`, or no
+ * body builder from the brand. Built at boot by the brand, like the notifier,
+ * so a broken setting fails startup rather than a lead.
+ */
+export declare function leadWebhook(site: {
+    brand: {
+        id: string;
+    };
+}, env: Pick<ServerEnv, "leadsDb" | "leadWebhook">, options: LeadWebhookOptions): LeadWebhook | null;
+export {};

package/dist/server/lead-webhook.js

@@ -0,0 +1,43 @@
+import "server-only";
+import { randomUUID } from "node:crypto";
+import { openWebhookOutbox } from "./webhook-outbox.js";
+/**
+ * What the Service-Arb panel's `lead.created` calls a callback request. Its
+ * `properties.channel` is a closed set (`form` | `phone_inbound`) and an event
+ * outside it is refused whole — the outbox would park the lead — so until the
+ * panel's `sa.funnel.v1` accepts `callback`, a callback travels as `form`.
+ * TODO(panel): set to "callback" once the panel accepts it; nothing else changes.
+ */
+const PANEL_CALLBACK = "form";
+/** A lead's channel as the panel's `properties.channel` may carry it: `panelChannel(channelOf(lead))`. */
+export function panelChannel(channel) {
+    return channel === "callback" ? PANEL_CALLBACK : "form";
+}
+/**
+ * The lead webhook, or `null` when it is off: no `LEAD_WEBHOOK_URL`, or no
+ * body builder from the brand. Built at boot by the brand, like the notifier,
+ * so a broken setting fails startup rather than a lead.
+ */
+export function leadWebhook(site, env, options) {
+    const { buildBody, signing, ...outboxOptions } = options;
+    if (!env.leadWebhook || !buildBody)
+        return null;
+    if (env.leadsDb.kind !== "sqlite")
+        throw new Error("LEAD_WEBHOOK_URL: the webhook outbox needs the sqlite lead store");
+    const outbox = openWebhookOutbox(env.leadsDb.path, { ...env.leadWebhook, signing }, outboxOptions);
+    const now = options.now ?? Date.now;
+    return {
+        outbox,
+        enqueue(lead, id, meta) {
+            const ctx = { leadId: id, brandId: site.brand.id, ...meta, at: new Date(now()), idempotencyKey: randomUUID() };
+            const body = JSON.stringify(buildBody(lead, ctx));
+            if (typeof body !== "string")
+                throw new Error("buildWebhookBody returned nothing JSON can carry");
+            return outbox.enqueue(body, `lead:${id}`);
+        },
+        tick: () => outbox.tick(),
+        start: intervalMs => outbox.start(intervalMs),
+        stop: () => outbox.stop(),
+        close: () => outbox.close(),
+    };
+}

package/dist/server/notify.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-import type { Lead } from "../core/lead.js";
+import { type Lead } from "../core/lead.js";
 import type { BrandFacts } from "../core/site.js";
 import type { ServerEnv } from "./env.js";
 /**

package/dist/server/notify.js

@@ -1,12 +1,15 @@
 import "server-only";
+import { channelOf } from "../core/lead.js";
 import { parseSmtpUrl, sendMail } from "./smtp.js";
 /** A plain default; a brand passes `format` to write it in its own language. */
 export function defaultLeadMail(brand, lead, id) {
     const place = lead.placeSlug ?? "unknown";
+    // A callback request is a promise to ring the customer: it says so first.
+    const callback = channelOf(lead) === "callback";
     return {
-        subject: `${brand.name} — new lead (${place})`,
+        subject: `${brand.name} — ${callback ? "call back" : "new lead"} (${place})`,
         text: [
-            `Lead #${id} — place ${place}${lead.spamVerdict ? ` — suspect (${lead.spamVerdict})` : ""}`,
+            `Lead #${id} — place ${place}${callback ? " — CALL BACK" : ""}${lead.spamVerdict ? ` — suspect (${lead.spamVerdict})` : ""}`,
             "",
             `Subject  : ${lead.subject}`,
             `Locality : ${lead.locality}`,

package/dist/server/webhook-outbox.d.ts

@@ -0,0 +1,77 @@
+import "server-only";
+import { type WebhookSigning } from "./webhook-signature.js";
+/**
+ * A durable queue of signed POSTs, kept in the leads file so a body is on disk
+ * before the visitor is thanked and survives a restart of the pod. Delivery is
+ * at-least-once: a row leaves `pending` only on the receiver's answer, and a
+ * crash between the answer and the update sends it again — the receiver
+ * deduplicates by whatever id the body carries.
+ *
+ * Bodies hold PII; they go out in the request and nowhere else. Logs name the
+ * row, the attempt and the status — never the body, and never the receiver's
+ * words, which may echo it: those stay in the row's `last_error`, beside the
+ * body they describe.
+ */
+export interface WebhookTarget {
+    url: string;
+    keyId: string;
+    secret: string;
+    signing: WebhookSigning;
+}
+export interface WebhookOutboxOptions {
+    /** Tries per row, the first included; past it the row is `dead`. */
+    maxAttempts?: number;
+    /** The wait after the first failure; doubled after each next one. */
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Per request, so a hung receiver does not hold the tick. */
+    timeoutMs?: number;
+    /** Rows sent per tick. */
+    batch?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** In `[0, 1)`; spreads retries so a receiver back from an outage is not hit at once. */
+    random?: () => number;
+    log?: Pick<Console, "info" | "warn" | "error">;
+}
+export type OutboxState = "pending" | "delivered" | "dead";
+export interface OutboxRow {
+    id: number;
+    ref: string | null;
+    state: OutboxState;
+    attempts: number;
+    nextAttemptAt: number;
+    lastError: string | null;
+}
+export interface TickReport {
+    delivered: number;
+    retried: number;
+    dead: number;
+}
+export interface WebhookOutbox {
+    /** Queues a body; synchronous and local, so it can sit before the response. */
+    enqueue(body: string, ref?: string | null): number;
+    /** One pass over the rows that are due; concurrent calls share the running one. */
+    tick(): Promise<TickReport>;
+    /** Ticks every `intervalMs` until `stop`; a second call is a no-op. */
+    start(intervalMs?: number): void;
+    stop(): void;
+    rows(): OutboxRow[];
+    close(): void;
+}
+export declare const WEBHOOK_MAX_ATTEMPTS = 12;
+export declare const WEBHOOK_TICK_MS = 10000;
+/**
+ * `https:` anywhere; `http:` only where nothing but the cluster sees the
+ * bytes — a Service's DNS name or loopback — since the body carries PII.
+ * Throws without the value: a URL setting may carry credentials.
+ */
+export declare function checkWebhookUrl(value: string, name?: string): string;
+/**
+ * Opens (and creates) the outbox table in the SQLite file at `path` — the
+ * leads file, through a connection of its own. Every row is bound to the
+ * target URL it was queued for: after a change of `LEAD_WEBHOOK_URL` the old
+ * rows stay, are counted at open, and are not sent to a receiver that never
+ * agreed to take them.
+ */
+export declare function openWebhookOutbox(path: string, target: WebhookTarget, options?: WebhookOutboxOptions): WebhookOutbox;

package/dist/server/webhook-outbox.js

@@ -0,0 +1,257 @@
+import "server-only";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { signatureHeaders } from "./webhook-signature.js";
+export const WEBHOOK_MAX_ATTEMPTS = 12;
+export const WEBHOOK_TICK_MS = 10_000;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS webhook_outbox (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  target          TEXT    NOT NULL,
+  ref             TEXT,
+  body            TEXT    NOT NULL,
+  created_at      INTEGER NOT NULL,
+  attempts        INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER NOT NULL,
+  state           TEXT    NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'delivered', 'dead')),
+  last_error      TEXT,
+  done_at         INTEGER
+);
+CREATE INDEX IF NOT EXISTS webhook_outbox_due ON webhook_outbox (state, target, next_attempt_at);
+`;
+/** How much of a receiver's answer a row keeps. */
+const ERROR_CAP = 500;
+const IN_CLUSTER = /(^|\.)svc(\.cluster\.local)?$/;
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * `https:` anywhere; `http:` only where nothing but the cluster sees the
+ * bytes — a Service's DNS name or loopback — since the body carries PII.
+ * Throws without the value: a URL setting may carry credentials.
+ */
+export function checkWebhookUrl(value, name = "LEAD_WEBHOOK_URL") {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${name} is not a URL`);
+    }
+    if (url.protocol === "https:")
+        return url.toString();
+    if (url.protocol === "http:" && (IN_CLUSTER.test(url.hostname) || LOOPBACK.has(url.hostname)))
+        return url.toString();
+    throw new Error(`${name}: https, or http to a *.svc / *.svc.cluster.local host or localhost`);
+}
+function sqlite() {
+    const mod = process.getBuiltinModule("node:sqlite");
+    if (!mod)
+        throw new Error("node:sqlite is unavailable — Node ≥ 22.13 is required");
+    return mod;
+}
+function column(row, key) {
+    return typeof row === "object" && row !== null ? Reflect.get(row, key) : undefined;
+}
+function int(row, key) {
+    const value = column(row, key);
+    if (typeof value === "number" || typeof value === "bigint")
+        return Number(value);
+    throw new Error(`webhook_outbox: expected an integer \`${key}\`, got ${typeof value}`);
+}
+function text(row, key) {
+    const value = column(row, key);
+    return typeof value === "string" ? value : null;
+}
+function state(row) {
+    const value = column(row, "state");
+    if (value === "pending" || value === "delivered" || value === "dead")
+        return value;
+    throw new Error(`webhook_outbox: unknown state ${String(value)}`);
+}
+/** `Retry-After` in seconds; the HTTP-date form is rare enough to ignore. */
+function retryAfter(response) {
+    const value = Number(response.headers.get("retry-after"));
+    return Number.isFinite(value) && value > 0 ? value * 1000 : null;
+}
+/**
+ * A `207` names a verdict per item of the batch. `rejected` is final — the
+ * receiver refused the item for what it is, and sending it again changes
+ * nothing — so the row is delivered, with the refusals noted; the other
+ * statuses (`accepted`, `duplicate`) need no word.
+ */
+async function multiStatus(response, rowId, log) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        log.warn(`webhook: outbox #${rowId}: a 207 with an unreadable body; taken as delivered`);
+        return { kind: "delivered", note: "207 with an unreadable body" };
+    }
+    const results = column(parsed, "results");
+    if (!Array.isArray(results))
+        return { kind: "delivered", note: null };
+    const rejected = results.filter(r => column(r, "status") === "rejected");
+    if (rejected.length === 0)
+        return { kind: "delivered", note: null };
+    for (const r of rejected) {
+        const index = column(r, "index");
+        log.warn(`webhook: outbox #${rowId}: item ${typeof index === "number" ? index : "?"} rejected by the receiver; not retried (reason in the row)`);
+    }
+    const reasons = rejected.map(r => `#${String(column(r, "index"))}: ${String(column(r, "reason") ?? "rejected")}`);
+    return { kind: "delivered", note: `rejected ${reasons.join("; ")}` };
+}
+async function judge(response, rowId, log) {
+    const status = response.status;
+    if (status === 207)
+        return multiStatus(response, rowId, log);
+    if (status >= 200 && status < 300) {
+        await response.body?.cancel();
+        return { kind: "delivered", note: null };
+    }
+    const said = (await response.text().catch(() => "")).slice(0, ERROR_CAP);
+    const tag = `HTTP ${status}`;
+    const why = said ? `${tag}: ${said}` : tag;
+    if (status === 408 || status === 429 || status >= 500)
+        return { kind: "retry", tag, why, afterMs: retryAfter(response) };
+    // 3xx included: redirects are not followed, since the target was vetted and its Location was not.
+    return { kind: "dead", tag, why };
+}
+/**
+ * Opens (and creates) the outbox table in the SQLite file at `path` — the
+ * leads file, through a connection of its own. Every row is bound to the
+ * target URL it was queued for: after a change of `LEAD_WEBHOOK_URL` the old
+ * rows stay, are counted at open, and are not sent to a receiver that never
+ * agreed to take them.
+ */
+export function openWebhookOutbox(path, target, options = {}) {
+    const maxAttempts = options.maxAttempts ?? WEBHOOK_MAX_ATTEMPTS;
+    const baseDelay = options.baseDelayMs ?? 5_000;
+    const maxDelay = options.maxDelayMs ?? 60 * 60_000;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const batch = options.batch ?? 20;
+    const send = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const random = options.random ?? Math.random;
+    const log = options.log ?? console;
+    if (path !== ":memory:")
+        mkdirSync(dirname(path), { recursive: true });
+    const db = new (sqlite().DatabaseSync)(path);
+    try {
+        db.exec("PRAGMA busy_timeout = 5000");
+        db.exec("PRAGMA journal_mode = WAL");
+        db.exec(SCHEMA);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    const insert = db.prepare("INSERT INTO webhook_outbox (target, ref, body, created_at, next_attempt_at) VALUES (?, ?, ?, ?, ?) RETURNING id");
+    const due = db.prepare("SELECT id, body, attempts FROM webhook_outbox WHERE state = 'pending' AND target = ? AND next_attempt_at <= ? ORDER BY next_attempt_at, id LIMIT ?");
+    // A lease: another process ticking the same file skips a row while it is in flight.
+    const claim = db.prepare("UPDATE webhook_outbox SET next_attempt_at = ? WHERE id = ? AND state = 'pending' AND next_attempt_at <= ?");
+    const finish = db.prepare("UPDATE webhook_outbox SET state = ?, attempts = ?, last_error = ?, done_at = ? WHERE id = ?");
+    const reschedule = db.prepare("UPDATE webhook_outbox SET attempts = ?, next_attempt_at = ?, last_error = ? WHERE id = ?");
+    const list = db.prepare("SELECT id, ref, state, attempts, next_attempt_at, last_error FROM webhook_outbox ORDER BY id");
+    const stranded = db.prepare("SELECT COUNT(*) AS n FROM webhook_outbox WHERE state = 'pending' AND target <> ?");
+    const left = int(stranded.get(target.url), "n");
+    if (left > 0)
+        log.warn(`webhook: ${left} pending row(s) queued for another target; left in place, not sent`);
+    /** Doubling from `baseDelay`, capped, plus up to a fifth more at random. */
+    function backoff(attempts, hinted) {
+        const plain = Math.min(maxDelay, baseDelay * 2 ** Math.max(0, attempts - 1));
+        return Math.min(maxDelay, Math.max(plain + Math.floor(plain * 0.2 * random()), hinted ?? 0));
+    }
+    async function deliver(id, body) {
+        try {
+            const response = await send(target.url, {
+                method: "POST",
+                headers: { "content-type": "application/json", ...signatureHeaders(target.signing, target, body, now()) },
+                body,
+                redirect: "manual",
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            return await judge(response, id, log);
+        }
+        catch (error) {
+            // The name and code only: a fetch error's message is safe, but its cause chain is the runtime's to word.
+            const name = error instanceof Error ? error.name : "error";
+            const code = column(error instanceof Error ? error.cause : undefined, "code");
+            const tag = `network ${name}${typeof code === "string" ? ` ${code}` : ""}`;
+            return { kind: "retry", tag, why: tag, afterMs: null };
+        }
+    }
+    async function pass() {
+        const report = { delivered: 0, retried: 0, dead: 0 };
+        const t = now();
+        for (const row of due.all(target.url, t, batch)) {
+            const id = int(row, "id");
+            const body = text(row, "body") ?? "";
+            const attempts = int(row, "attempts") + 1;
+            if (Number(claim.run(t + timeoutMs + 5_000, id, t).changes) === 0)
+                continue;
+            const verdict = await deliver(id, body);
+            if (verdict.kind === "delivered") {
+                finish.run("delivered", attempts, verdict.note?.slice(0, ERROR_CAP) ?? null, now(), id);
+                report.delivered += 1;
+            }
+            else if (verdict.kind === "dead" || attempts >= maxAttempts) {
+                finish.run("dead", attempts, verdict.why, now(), id);
+                log.error(`webhook: outbox #${id} dead after ${attempts} attempt(s): ${verdict.tag}`);
+                report.dead += 1;
+            }
+            else {
+                const wait = backoff(attempts, verdict.afterMs);
+                reschedule.run(attempts, now() + wait, verdict.why, id);
+                log.warn(`webhook: outbox #${id} attempt ${attempts} failed (${verdict.tag}); next in ${Math.round(wait / 1000)} s`);
+                report.retried += 1;
+            }
+        }
+        return report;
+    }
+    let running = null;
+    let timer = null;
+    const tick = () => {
+        running ??= pass().finally(() => {
+            running = null;
+        });
+        return running;
+    };
+    const stop = () => {
+        if (timer)
+            clearInterval(timer);
+        timer = null;
+    };
+    return {
+        enqueue(body, ref = null) {
+            const t = now();
+            return int(insert.get(target.url, ref, body, t, t), "id");
+        },
+        tick,
+        start(intervalMs = WEBHOOK_TICK_MS) {
+            if (timer)
+                return;
+            const run = () => {
+                tick().catch(error => log.error("webhook: an outbox tick failed", error));
+            };
+            timer = setInterval(run, intervalMs);
+            // The queue must not keep a process alive that is otherwise done.
+            timer.unref();
+            run();
+        },
+        stop,
+        rows() {
+            return list.all().map(row => ({
+                id: int(row, "id"),
+                ref: text(row, "ref"),
+                state: state(row),
+                attempts: int(row, "attempts"),
+                nextAttemptAt: int(row, "next_attempt_at"),
+                lastError: text(row, "last_error"),
+            }));
+        },
+        close() {
+            stop();
+            db.close();
+        },
+    };
+}