@evinvest/kitstart 0.8.0 → 0.10.0

package/dist/server/env.js

@@ -56,6 +56,17 @@ function leadWebhook(source) {
     }
     return { url, keyId, secret };
 }
+function rateLimit(source, production) {
+    const raw = opt(source, "LEAD_RATE_LIMIT");
+    if (raw === null)
+        return { limit: production ? 5 : 100, windowMs: 600_000 };
+    const parsed = /^(\d+)\/(\d+)$/.exec(raw);
+    const limit = Number(parsed?.[1]);
+    const seconds = Number(parsed?.[2]);
+    if (!parsed || limit < 1 || seconds < 1)
+        throw new Error("LEAD_RATE_LIMIT: <count>/<seconds>, both at least 1, e.g. 5/600");
+    return { limit, windowMs: seconds * 1000 };
+}
 export function parseServerEnv(site, source) {
     const production = source["NODE_ENV"] === "production";
     const trust = opt(source, "TRUSTED_PROXY");
@@ -76,6 +87,7 @@ export function parseServerEnv(site, source) {
         // Explicit because PostHog rejects a project's events at the other
         // region's host; the audience is European, so EU unless told otherwise.
         posthogHost: url(source, "POSTHOG_HOST") ?? "https://eu.i.posthog.com",
+        leadRateLimit: rateLimit(source, production),
     };
 }
 /** Lazy and cached: `next build` imports the brand's env module and must not need prod secrets. */

package/dist/server/index.d.ts

@@ -6,6 +6,7 @@
 import "server-only";
 export { createServerEnv, parseServerEnv, type EnvSource, type ServerEnv } from "./env.js";
 export { createPlaceSource, PLACE_REVALIDATE_SECONDS, PlaceSourceError, type PlaceSource, type PlaceSourceOptions } from "./place-source.js";
+export { createPricingSource, type PricingSource, type PricingSourceOptions } from "./pricing-source.js";
 export { describeLeadDb, openLeadStore, parseLeadDb, type LeadDb } from "./lead-store.js";
 export { openSqliteLeadStore, type SqliteLeadStore } from "./lead-store-sqlite.js";
 export { LeadStoreNotImplemented, openPostgresLeadStore } from "./lead-store-postgres.js";
@@ -13,6 +14,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 { leadWebhook, panelChannel, panelFlowOf, panelFlowProperties, type BuildWebhookBody, type LeadWebhook, type LeadWebhookContext, type LeadWebhookOptions, type PanelFlow, type PanelFlowProperties, } from "./lead-webhook.js";
+export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_HORIZON_MS, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_MAX_DELAY_MS, WEBHOOK_TICK_MS, type DeadRow, 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

@@ -6,6 +6,7 @@
 import "server-only";
 export { createServerEnv, parseServerEnv } from "./env.js";
 export { createPlaceSource, PLACE_REVALIDATE_SECONDS, PlaceSourceError } from "./place-source.js";
+export { createPricingSource } from "./pricing-source.js";
 export { describeLeadDb, openLeadStore, parseLeadDb } from "./lead-store.js";
 export { openSqliteLeadStore } from "./lead-store-sqlite.js";
 export { LeadStoreNotImplemented, openPostgresLeadStore } from "./lead-store-postgres.js";
@@ -13,6 +14,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 { leadWebhook, panelChannel, panelFlowOf, panelFlowProperties, } from "./lead-webhook.js";
+export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_HORIZON_MS, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_MAX_DELAY_MS, WEBHOOK_TICK_MS, } from "./webhook-outbox.js";
 export { signatureHeaders, signWebhook } from "./webhook-signature.js";

package/dist/server/lead-store-sqlite.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-import { type LeadStore } from "../core/lead.js";
+import { type Lead, type LeadStore } from "../core/lead.js";
 /**
  * The SQLite adapter of the `LeadStore` port: one file on the pod's volume.
  *
@@ -9,6 +9,10 @@ import { type LeadStore } from "../core/lead.js";
  * nothing — and map to the lead's `subject`, `locality` and `mobile`.
  */
 export interface SqliteLeadStore extends LeadStore {
+    findSubmission(submissionId: string): Promise<{
+        id: number;
+        lead: Lead;
+    } | null>;
     /** The schema version the file is at after opening. */
     version(): number;
 }

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

@@ -2,6 +2,7 @@ import "server-only";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { channelOf, LEAD_SCHEMA_VERSION } from "../core/lead.js";
+import { LEAD_FLOWS } from "../core/pricing/flow.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.
@@ -50,6 +51,22 @@ const STEPS = [
         db.exec("ALTER TABLE leads ADD COLUMN consent_at TEXT");
         db.exec("ALTER TABLE leads ADD COLUMN consent_text TEXT");
     },
+    // 6 — the script's id for a submission, so a resend after a lost answer is
+    // the same row. Unique where present; a plain post has none, and NULLs
+    // never collide.
+    db => {
+        db.exec("ALTER TABLE leads ADD COLUMN submission_id TEXT");
+        db.exec("CREATE UNIQUE INDEX leads_submission_id ON leads (submission_id) WHERE submission_id IS NOT NULL");
+    },
+    // 7 — how the need was sold (`quote`, `estimate`, `fixed`), and for the two
+    // priced flows the server's price, the model's date and an estimate's
+    // answers (JSON). Nullable: a row from before, a callback, a quote.
+    db => {
+        db.exec("ALTER TABLE leads ADD COLUMN flow TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN quoted_cents INTEGER");
+        db.exec("ALTER TABLE leads ADD COLUMN pricing_valid_from TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN estimate_inputs TEXT");
+    },
 ];
 if (STEPS.length !== LEAD_SCHEMA_VERSION) {
     // The version belongs to the port, shared by every adapter; this table of
@@ -57,6 +74,45 @@ if (STEPS.length !== LEAD_SCHEMA_VERSION) {
     throw new Error(`leads: ${STEPS.length} sqlite steps for schema version ${LEAD_SCHEMA_VERSION}`);
 }
 const RUST_COLUMNS = ["id", "job", "zip", "mobile", "at"];
+function str(row, key) {
+    const value = column(row, key);
+    return typeof value === "string" ? value : null;
+}
+const VERDICTS = ["honeypot", "too-fast", "rate-limited"];
+/** A JSON object of strings, or `{}`: what `extras` and `estimate_inputs` hold. */
+function strings(text) {
+    const value = JSON.parse(text ?? "{}");
+    return Object.fromEntries(Object.entries(typeof value === "object" && value !== null ? value : {}).filter((e) => typeof e[1] === "string"));
+}
+function priceOf(row) {
+    const cents = column(row, "quoted_cents");
+    const validFrom = str(row, "pricing_valid_from");
+    if ((typeof cents !== "number" && typeof cents !== "bigint") || validFrom === null)
+        return null;
+    const inputs = str(row, "estimate_inputs");
+    return { cents: Number(cents), validFrom, ...(inputs !== null ? { inputs: strings(inputs) } : {}) };
+}
+/** A stored row read back as the lead it was written from. */
+function leadOf(row) {
+    const verdict = str(row, "spam_verdict");
+    const consentAt = str(row, "consent_at");
+    const submissionId = str(row, "submission_id");
+    const flow = LEAD_FLOWS.find(f => f === str(row, "flow"));
+    const price = priceOf(row);
+    return {
+        subject: str(row, "job") ?? "",
+        locality: str(row, "zip") ?? "",
+        mobile: str(row, "mobile") ?? "",
+        extras: strings(str(row, "extras")),
+        placeSlug: str(row, "location_id"),
+        spamVerdict: verdict !== null && VERDICTS.includes(verdict) ? verdict : null,
+        channel: str(row, "channel") === "callback" ? "callback" : "form",
+        ...(consentAt !== null ? { consent: { at: consentAt, text: str(row, "consent_text") ?? "" } } : {}),
+        ...(submissionId !== null ? { submissionId } : {}),
+        ...(flow !== undefined ? { flow } : {}),
+        ...(price !== null ? { price } : {}),
+    };
+}
 function userVersion(db) {
     return integer(db.prepare("PRAGMA user_version").get(), "user_version");
 }
@@ -138,12 +194,17 @@ export function openSqliteLeadStore(path) {
         db.close();
         throw error;
     }
-    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id");
+    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text, submission_id, flow, quoted_cents, pricing_valid_from, estimate_inputs) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id");
+    const bySubmission = db.prepare("SELECT id, job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text, submission_id, flow, quoted_cents, pricing_valid_from, estimate_inputs FROM leads WHERE submission_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, channelOf(lead), lead.consent?.at ?? null, lead.consent?.text ?? null), "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, lead.submissionId ?? null, lead.flow ?? null, lead.price?.cents ?? null, lead.price?.validFrom ?? null, lead.price?.inputs ? JSON.stringify(lead.price.inputs) : null), "id");
+        },
+        async findSubmission(submissionId) {
+            const row = bySubmission.get(submissionId);
+            return row === undefined ? null : { id: integer(row, "id"), lead: leadOf(row) };
         },
         async count() {
             return integer(count.get(), "n");

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

@@ -1,5 +1,6 @@
 import "server-only";
-import type { Lead, LeadChannel } from "../core/lead.js";
+import { type Lead, type LeadChannel, type LeadSuspect } from "../core/lead.js";
+import type { LeadFlow } from "../core/pricing/flow.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";
@@ -14,7 +15,50 @@ export interface LeadWebhookContext {
     at: Date;
     /** Fresh per lead and stored with the body, so every retry carries the same one. */
     idempotencyKey: string;
+    /**
+     * Why the lead is suspect (`suspectOf`), for the panel's `suspect`
+     * property — only under `panelSuspect`; otherwise always absent, and the
+     * body must not carry the property at all.
+     */
+    suspect?: LeadSuspect;
+    /**
+     * The lead's public reference (`leadRef`, `lead-<row>-<8 hex>`): the one
+     * the page was answered with (`LeadSent.lead`), so a later step on the page
+     * can name the lead the panel knows. Absent only on a context built by hand.
+     */
+    leadRef?: string;
+    /**
+     * How the need was sold and at what price — only under `panelFlow`, and
+     * only on a lead with a flow; otherwise absent, and the body must not carry
+     * the properties. `panelFlowProperties` writes them as the panel reads them.
+     */
+    flow?: PanelFlow;
 }
+/** A lead's sale as the panel's `lead.created` may carry it. */
+export interface PanelFlow {
+    flow: LeadFlow;
+    /** With `estimate` and `fixed` only, always with `pricingValidFrom`. */
+    quotedCents?: number;
+    /** The price list's date, `YYYY-MM-DD`. */
+    pricingValidFrom?: string;
+    /** With `estimate` only, and only when it asked anything: input id → option id, slugs. */
+    estimateInputs?: Readonly<Record<string, string>>;
+}
+/** The sale `ctx.flow` describes, or nothing for a lead without a flow. */
+export declare function panelFlowOf(lead: Pick<Lead, "flow" | "price">): PanelFlow | undefined;
+/**
+ * `ctx.flow` as `lead.created`'s properties: `flow`, then `quoted_cents` and
+ * `pricing_valid_from` together (estimate and fixed), then `estimate_inputs`
+ * (estimate) — the panel's closed vocabulary. Spread into the body's
+ * `properties`; `{}` without a flow.
+ */
+export interface PanelFlowProperties {
+    flow: LeadFlow;
+    quoted_cents?: number;
+    pricing_valid_from?: string;
+    estimate_inputs?: Readonly<Record<string, string>>;
+}
+export declare function panelFlowProperties(flow: PanelFlow | undefined): PanelFlowProperties | Record<string, never>;
 /**
  * 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
@@ -36,17 +80,40 @@ export interface LeadWebhook {
     enqueue(lead: Lead, id: number, meta: {
         locale: string;
         formId: string;
+        leadRef?: string;
     }): number;
     tick(): Promise<TickReport>;
     start(intervalMs?: number): void;
     stop(): void;
     close(): void;
+    /** The outbox's `requeueDead`: this target's dead rows back in the queue. */
+    requeueDead(): number;
+    /** Whether a suspect lead is queued, marked (`LeadWebhookOptions.panelSuspect`). */
+    readonly panelSuspect: boolean;
+    /** Whether `ctx.flow` is filled in (`LeadWebhookOptions.panelFlow`). */
+    readonly panelFlow: boolean;
     readonly outbox: WebhookOutbox;
 }
 export interface LeadWebhookOptions extends WebhookOutboxOptions {
     /** Absent → the webhook is off, whatever the environment says. */
     buildBody?: BuildWebhookBody | undefined;
     signing: WebhookSigning;
+    /**
+     * The one switch for the panel's `suspect` marker. Off (the default) until
+     * the panel's `lead.created` accepts the property — it refuses an unknown
+     * one, and the outbox would park the lead: a rate-limited lead stays in the
+     * table and `ctx.suspect` stays absent, as before. On: a rate-limited lead
+     * is queued too, and every queued lead's `ctx.suspect` says why it is
+     * suspect, for the brand's body to carry.
+     */
+    panelSuspect?: boolean;
+    /**
+     * The switch for the sale's properties (`ctx.flow`: `flow`, `quoted_cents`,
+     * `pricing_valid_from`, `estimate_inputs`). Off (the default) until the
+     * panel's `lead.created` accepts them — it refuses an unknown property, and
+     * the outbox would park the lead. The leads table keeps them either way.
+     */
+    panelFlow?: boolean;
 }
 /**
  * The lead webhook, or `null` when it is off: no `LEAD_WEBHOOK_URL`, or no

package/dist/server/lead-webhook.js

@@ -1,6 +1,25 @@
 import "server-only";
 import { randomUUID } from "node:crypto";
+import { suspectOf } from "../core/lead.js";
 import { openWebhookOutbox } from "./webhook-outbox.js";
+/** The sale `ctx.flow` describes, or nothing for a lead without a flow. */
+export function panelFlowOf(lead) {
+    if (!lead.flow)
+        return undefined;
+    if (lead.flow === "quote" || !lead.price)
+        return { flow: "quote" };
+    const inputs = lead.flow === "estimate" && lead.price.inputs && Object.keys(lead.price.inputs).length > 0 ? { estimateInputs: lead.price.inputs } : {};
+    return { flow: lead.flow, quotedCents: lead.price.cents, pricingValidFrom: lead.price.validFrom, ...inputs };
+}
+export function panelFlowProperties(flow) {
+    if (!flow)
+        return {};
+    return {
+        flow: flow.flow,
+        ...(flow.quotedCents !== undefined && flow.pricingValidFrom !== undefined ? { quoted_cents: flow.quotedCents, pricing_valid_from: flow.pricingValidFrom } : {}),
+        ...(flow.estimateInputs ? { estimate_inputs: flow.estimateInputs } : {}),
+    };
+}
 /**
  * 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
@@ -19,7 +38,7 @@ export function panelChannel(channel) {
  * so a broken setting fails startup rather than a lead.
  */
 export function leadWebhook(site, env, options) {
-    const { buildBody, signing, ...outboxOptions } = options;
+    const { buildBody, signing, panelSuspect = false, panelFlow = false, ...outboxOptions } = options;
     if (!env.leadWebhook || !buildBody)
         return null;
     if (env.leadsDb.kind !== "sqlite")
@@ -28,8 +47,20 @@ export function leadWebhook(site, env, options) {
     const now = options.now ?? Date.now;
     return {
         outbox,
+        panelSuspect,
+        panelFlow,
         enqueue(lead, id, meta) {
-            const ctx = { leadId: id, brandId: site.brand.id, ...meta, at: new Date(now()), idempotencyKey: randomUUID() };
+            const suspect = panelSuspect ? suspectOf(lead) : undefined;
+            const flow = panelFlow ? panelFlowOf(lead) : undefined;
+            const ctx = {
+                leadId: id,
+                brandId: site.brand.id,
+                ...meta,
+                at: new Date(now()),
+                idempotencyKey: randomUUID(),
+                ...(suspect ? { suspect } : {}),
+                ...(flow ? { flow } : {}),
+            };
             const body = JSON.stringify(buildBody(lead, ctx));
             if (typeof body !== "string")
                 throw new Error("buildWebhookBody returned nothing JSON can carry");
@@ -39,5 +70,6 @@ export function leadWebhook(site, env, options) {
         start: intervalMs => outbox.start(intervalMs),
         stop: () => outbox.stop(),
         close: () => outbox.close(),
+        requeueDead: () => outbox.requeueDead(),
     };
 }

package/dist/server/pricing-source.d.ts

@@ -0,0 +1,25 @@
+import "server-only";
+import type { PricingModel } from "../core/pricing/model.js";
+import type { Site } from "../core/site.js";
+/**
+ * The brand's live price list: `GET <base>/pricing`, the whole model with a
+ * label in every locale, over the baked one (`site.pricing`). The same
+ * failure semantics as the place source, for the same reason — a page that
+ * throws under ISR is a bare 500 with no phone: an unreachable source, a
+ * non-200, a body that is not JSON, and a model that does not validate all
+ * serve the baked model. Taken whole or not at all: a page never prices from
+ * half a model. `{}` is the source's "nothing set": the baked model, quietly.
+ */
+export interface PricingSourceOptions {
+    /** The source's base URL, read when asked; `null` → the baked model only. */
+    baseUrl: () => string | null;
+    /** TTL on the fetch itself (see `PlaceSourceOptions`); 600 s. */
+    revalidateSeconds?: number;
+    timeoutMs?: number;
+    log?: Pick<Console, "error">;
+}
+export interface PricingSource {
+    /** The model to price with now: live, else baked, else `null` (every need is a `quote`). Never throws. */
+    model(): Promise<PricingModel | null>;
+}
+export declare function createPricingSource<L extends string, P extends string>(site: Site<L, P>, options: PricingSourceOptions): PricingSource;

package/dist/server/pricing-source.js

@@ -0,0 +1,48 @@
+import "server-only";
+import { parsePricingModel, pricingProblemsFor } from "../core/pricing/validate.js";
+import { PLACE_REVALIDATE_SECONDS } from "./place-source.js";
+const TIMEOUT_MS = 3_000;
+const isEmptyObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).length === 0;
+export function createPricingSource(site, options) {
+    const revalidate = options.revalidateSeconds ?? PLACE_REVALIDATE_SECONDS;
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const log = options.log ?? console;
+    const baked = site.pricing ?? null;
+    async function live(base) {
+        const init = { cache: "force-cache", next: { revalidate }, signal: AbortSignal.timeout(timeoutMs) };
+        let response;
+        try {
+            response = await fetch(`${base}/pricing`, init);
+        }
+        catch (cause) {
+            log.error("pricing: source unreachable, pricing from the baked model", cause);
+            return baked;
+        }
+        if (!response.ok) {
+            log.error(`pricing: source answered ${response.status}, pricing from the baked model`);
+            return baked;
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (cause) {
+            log.error("pricing: the source's body is not JSON, pricing from the baked model", cause);
+            return baked;
+        }
+        if (isEmptyObject(body))
+            return baked;
+        const problems = pricingProblemsFor(body, site.i18n.locales);
+        if (problems.length > 0) {
+            log.error(`pricing: the source's model is refused whole (${problems.slice(0, 5).join("; ")}), pricing from the baked model`);
+            return baked;
+        }
+        return parsePricingModel(body);
+    }
+    return {
+        async model() {
+            const base = options.baseUrl();
+            return base ? live(base) : baked;
+        },
+    };
+}

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

@@ -18,12 +18,28 @@ export interface WebhookTarget {
     secret: string;
     signing: WebhookSigning;
 }
+/** What `onDead` is told of a row given up on: its error as tagged (`HTTP 503`), never the receiver's words. */
+export interface DeadRow {
+    id: number;
+    ref: string | null;
+    attempts: number;
+    error: string;
+}
 export interface WebhookOutboxOptions {
-    /** Tries per row, the first included; past it the row is `dead`. */
+    /**
+     * How long a row is retried, from when it was queued (or requeued); past it
+     * a failure makes it `dead`. 48 hours by default: a receiver down over a
+     * night and a day still gets its leads.
+     */
+    horizonMs?: number;
+    /** A cap on tries per row besides the horizon, the first included; none by default. */
     maxAttempts?: number;
     /** The wait after the first failure; doubled after each next one. */
     baseDelayMs?: number;
+    /** The longest wait between two tries: an hour by default. */
     maxDelayMs?: number;
+    /** Told of every row given up on, after the error log — the alert hook. */
+    onDead?: (row: DeadRow) => void;
     /** Per request, so a hung receiver does not hold the tick. */
     timeoutMs?: number;
     /** Rows sent per tick. */
@@ -57,9 +73,19 @@ export interface WebhookOutbox {
     start(intervalMs?: number): void;
     stop(): void;
     rows(): OutboxRow[];
+    /**
+     * Puts this target's `dead` rows back in the queue, due now, with their
+     * tries and horizon fresh — after a key rotation or an outage longer than
+     * the horizon. Answers how many. `kitstart-outbox requeue` does the same
+     * from a shell.
+     */
+    requeueDead(): number;
     close(): void;
 }
+/** The old default cap on tries; kept for a brand that passes it as `maxAttempts`. The horizon decides now. */
 export declare const WEBHOOK_MAX_ATTEMPTS = 12;
+export declare const WEBHOOK_HORIZON_MS: number;
+export declare const WEBHOOK_MAX_DELAY_MS: number;
 export declare const WEBHOOK_TICK_MS = 10000;
 /**
  * `https:` anywhere; `http:` only where nothing but the cluster sees the

package/dist/server/webhook-outbox.js

@@ -2,7 +2,10 @@ import "server-only";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { signatureHeaders } from "./webhook-signature.js";
+/** The old default cap on tries; kept for a brand that passes it as `maxAttempts`. The horizon decides now. */
 export const WEBHOOK_MAX_ATTEMPTS = 12;
+export const WEBHOOK_HORIZON_MS = 48 * 60 * 60_000;
+export const WEBHOOK_MAX_DELAY_MS = 60 * 60_000;
 export const WEBHOOK_TICK_MS = 10_000;
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS webhook_outbox (
@@ -113,6 +116,12 @@ async function judge(response, rowId, log) {
     const why = said ? `${tag}: ${said}` : tag;
     if (status === 408 || status === 429 || status >= 500)
         return { kind: "retry", tag, why, afterMs: retryAfter(response) };
+    // A rotated key (401, 403) or a receiver moved or not yet deployed (404):
+    // fixed by a person, after which the lead must still arrive.
+    if (status === 401 || status === 403)
+        return { kind: "retry", tag, why, afterMs: null, alarm: "check LEAD_WEBHOOK_KEY_ID / LEAD_WEBHOOK_SECRET against the receiver's key" };
+    if (status === 404)
+        return { kind: "retry", tag, why, afterMs: null, alarm: "check LEAD_WEBHOOK_URL" };
     // 3xx included: redirects are not followed, since the target was vetted and its Location was not.
     return { kind: "dead", tag, why };
 }
@@ -124,9 +133,10 @@ async function judge(response, rowId, log) {
  * agreed to take them.
  */
 export function openWebhookOutbox(path, target, options = {}) {
-    const maxAttempts = options.maxAttempts ?? WEBHOOK_MAX_ATTEMPTS;
+    const horizon = options.horizonMs ?? WEBHOOK_HORIZON_MS;
+    const maxAttempts = options.maxAttempts ?? Number.POSITIVE_INFINITY;
     const baseDelay = options.baseDelayMs ?? 5_000;
-    const maxDelay = options.maxDelayMs ?? 60 * 60_000;
+    const maxDelay = options.maxDelayMs ?? WEBHOOK_MAX_DELAY_MS;
     const timeoutMs = options.timeoutMs ?? 10_000;
     const batch = options.batch ?? 20;
     const send = options.fetch ?? fetch;
@@ -146,13 +156,15 @@ export function openWebhookOutbox(path, target, options = {}) {
         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 ?");
+    const due = db.prepare("SELECT id, ref, body, attempts, created_at 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 <> ?");
+    // `created_at` restarts the horizon: a requeued row is queued anew.
+    const requeue = db.prepare("UPDATE webhook_outbox SET state = 'pending', attempts = 0, created_at = ?, next_attempt_at = ?, done_at = NULL WHERE state = 'dead' 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`);
@@ -187,6 +199,7 @@ export function openWebhookOutbox(path, target, options = {}) {
             const id = int(row, "id");
             const body = text(row, "body") ?? "";
             const attempts = int(row, "attempts") + 1;
+            const queuedAt = int(row, "created_at");
             if (Number(claim.run(t + timeoutMs + 5_000, id, t).changes) === 0)
                 continue;
             const verdict = await deliver(id, body);
@@ -194,15 +207,25 @@ export function openWebhookOutbox(path, target, options = {}) {
                 finish.run("delivered", attempts, verdict.note?.slice(0, ERROR_CAP) ?? null, now(), id);
                 report.delivered += 1;
             }
-            else if (verdict.kind === "dead" || attempts >= maxAttempts) {
+            else if (verdict.kind === "dead" || attempts >= maxAttempts || now() - queuedAt >= horizon) {
                 finish.run("dead", attempts, verdict.why, now(), id);
-                log.error(`webhook: outbox #${id} dead after ${attempts} attempt(s): ${verdict.tag}`);
+                log.error(`webhook: outbox #${id} dead after ${attempts} attempt(s): ${verdict.tag}; requeue with requeueDead() or \`kitstart-outbox requeue\``);
                 report.dead += 1;
+                try {
+                    options.onDead?.({ id, ref: text(row, "ref"), attempts, error: verdict.tag });
+                }
+                catch (error) {
+                    log.error("webhook: the onDead hook failed", error);
+                }
             }
             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`);
+                const line = `webhook: outbox #${id} attempt ${attempts} failed (${verdict.tag}); next in ${Math.round(wait / 1000)} s`;
+                if (verdict.alarm)
+                    log.error(`${line} — ${verdict.alarm}`);
+                else
+                    log.warn(line);
                 report.retried += 1;
             }
         }
@@ -249,6 +272,10 @@ export function openWebhookOutbox(path, target, options = {}) {
                 lastError: text(row, "last_error"),
             }));
         },
+        requeueDead() {
+            const t = now();
+            return Number(requeue.run(t, t, target.url).changes);
+        },
         close() {
             stop();
             db.close();

package/dist/testing/index.d.ts

@@ -9,4 +9,5 @@
 export { describeLandingContract, type LandingContractOptions } from "./landing-contract.js";
 export { servedPaths } from "./served-files.js";
 export { describeLeadStoreContract, type LeadStoreHarness } from "./lead-store-contract.js";
+export { leadRuleDisagreements, PHONE_MATRIX } from "./lead-rules.js";
 export { serviceAreaPlace, storefrontPlace, testLead } from "./fixtures.js";

package/dist/testing/index.js

@@ -9,4 +9,5 @@
 export { describeLandingContract } from "./landing-contract.js";
 export { servedPaths } from "./served-files.js";
 export { describeLeadStoreContract } from "./lead-store-contract.js";
+export { leadRuleDisagreements, PHONE_MATRIX } from "./lead-rules.js";
 export { serviceAreaPlace, storefrontPlace, testLead } from "./fixtures.js";

package/dist/testing/landing-contract.js

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import { isPublished, publicationGaps } from "../core/place/publication.js";
 import { createRouting, NON_PAGE_ROUTES, pointSuffixes, THANKS } from "../core/routing.js";
 import { openLaunchBlockers } from "../core/site.js";
+import { leadRuleDisagreements } from "./lead-rules.js";
 import { servedPaths } from "./served-files.js";
 const SOURCE_LINE = /@source\s+["'][^"']*node_modules\/@evinvest\/kitstart\/dist["']/;
 const MATCHER = "/((?!_next/).*)";
@@ -42,6 +43,11 @@ export function describeLandingContract(site, options = {}) {
                 expect(moves && suffixes.includes(redirect.from), redirect.from).toBe(false);
             }
         });
+        // A number the form lets through and the server refuses sends the visitor
+        // back for nothing they can see; `validateLead` is the shared rule.
+        it("refuses exactly the phone numbers the form blocks", () => {
+            expect(leadRuleDisagreements(site.lead)).toEqual([]);
+        });
         it("publishes nothing without a domain", () => {
             if (site.brand.domain !== null)
                 return;

package/dist/testing/lead-rules.d.ts

@@ -0,0 +1,18 @@
+import { type LeadSchema } from "../core/lead.js";
+/**
+ * Numbers people type, and whether each is a way to reach them — the
+ * review's matrix (LEAD-FORMS-REVIEW-2026-10-03) and the spellings that must
+ * keep working.
+ */
+export declare const PHONE_MATRIX: readonly {
+    mobile: string;
+    valid: boolean;
+}[];
+/**
+ * Where a brand's form rule disagrees with the form's own phone check: a
+ * number the form lets through that the server refuses (the visitor is sent
+ * back for nothing they can see), or one the form blocks that the rule would
+ * take. Every other field is filled as the form fills it — the first subject,
+ * a postcode — so only the phone is judged. Empty is agreement.
+ */
+export declare function leadRuleDisagreements(schema: LeadSchema<string>): string[];