@evinvest/kitstart 0.4.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ stays in the brand.
 | Import | Runtime | What |
 |---|---|---|
 | `@evinvest/kitstart` | anywhere (edge, client, server) | `defineSite`, places, routing (`createRouting`), the lead schema and funnel (`createAcceptLead`), antispam, JSON-LD / sitemap / robots builders, analytics events, the copy contract |
-| `@evinvest/kitstart/server` | Node, `server-only` | `createServerEnv`, `createPlaceSource`, the lead store (`openLeadStore` by `LEADS_DB_URL`: `sqlite:` today, `postgres://` a stub that refuses at boot), `checkLeadStore`, `leadNotifier`, `sendMail`, `clientKey` |
+| `@evinvest/kitstart/server` | Node, `server-only` | `createServerEnv`, `createPlaceSource`, the lead store (`openLeadStore` by `LEADS_DB_URL`: `sqlite:` today, `postgres://` a stub that refuses at boot), `checkLeadStore`, `leadNotifier`, `leadWebhook` (signed, outboxed), `sendMail`, `clientKey` |
 | `@evinvest/kitstart/proxy` | edge | `createProxy(site)`, `PROXY_MATCHER` |
 | `@evinvest/kitstart/next` | Next server (routes, RSC) | `quoteRoute`, `sitemapRoute`, `robotsRoute`, `ogRoute`, `healthRoute`, `createPlaceLoader`, `loadLocale`, `placeMetadata` / `brandMetadata` / `statusMetadata`, `metadataBase` |
 | `@evinvest/kitstart/next/config` | `next.config.ts`, `vitest.config.ts` | `withLanding`, `buildEnv` and the `assets/` readers |
@@ -45,7 +45,7 @@ brand's `flake.nix` is its own config plus one call — `template/flake.nix` is
 the whole of one:
 
 ```nix
-inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.3.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.5.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -251,6 +251,60 @@ chooses per visitor answer `Cache-Control: private, no-store`.
   network filesystem is not a place for it — that is what the Postgres port
   is for.
 
+## Lead webhook
+
+A signed POST of each lead to a receiver the brand names, delivered through an
+outbox in the leads file. The kit knows no receiver: the brand builds the body
+and passes the signing scheme; the kit serialises, signs, stores and retries.
+
+```ts
+// shared/config/env.ts
+import { createServerEnv, leadWebhook, type LeadWebhook } from "@evinvest/kitstart/server";
+
+export const serverEnv = createServerEnv(site);
+let hook: LeadWebhook | null | undefined;
+export const webhook = (): LeadWebhook | null =>
+  (hook ??= leadWebhook(site, serverEnv(), {
+    // The receiver's scheme, all of it: the kit has no defaults.
+    signing: {
+      prefix: "sa-ingest/v1.",
+      headers: { keyId: "x-sa-key-id", timestamp: "x-sa-timestamp", signature: "x-sa-signature" },
+    },
+    buildBody: (lead, ctx) => ({ events: [/* the receiver's shape, from lead + ctx */] }),
+  }));
+
+// instrumentation.ts, in register(): resume the queue after a restart
+webhook()?.start();
+
+// app/quote/route.ts
+export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavailable });
+```
+
+- **Off unless both halves are there.** No `LEAD_WEBHOOK_URL`, or no
+  `buildBody` → `leadWebhook` returns `null`. With the URL,
+  `LEAD_WEBHOOK_KEY_ID` and `LEAD_WEBHOOK_SECRET` are required, and the URL
+  must be `https:`, or `http:` to a `*.svc` / `*.svc.cluster.local` host or
+  loopback — the body carries PII. All checked at boot.
+- **Queued before the 303, sent after it.** The body is built once, from the
+  lead and `ctx` (`leadId`, `brandId`, `locale`, `formId`, `at`, and a fresh
+  `idempotencyKey` for the receiver to deduplicate by), and written to the
+  `webhook_outbox` table before the visitor is thanked; the send runs in
+  `after`. A lead the notifier skips (honeypot, rate limit) is not queued.
+- **Signature.** Three headers named by `signing.headers`: the key id, the
+  timestamp (unix seconds) and `hex(HMAC-SHA256(secret, prefix + timestamp +
+  "." + body))`, signed afresh on each attempt. Prefix and names are required.
+- **At-least-once.** 2xx is delivered. A `207` is delivered too, and an item
+  it marks `rejected` is final — logged by index, not retried. 5xx, 408, 429
+  and network errors retry, doubling from 5 s up to an hour (with jitter, and
+  at least `Retry-After`), `WEBHOOK_MAX_ATTEMPTS` (12) times; any other status,
+  3xx included, is final. A final row stays as `dead` with its `last_error`.
+- **PII stays in the body.** Logs name the row, the attempt and the status;
+  the receiver's own words (which may echo a field) go to the row's
+  `last_error`, never to the log.
+- **Restarts.** Rows are in the leads file; `start()` ticks every
+  `WEBHOOK_TICK_MS` and a new process picks up what is due. Rows queued for a
+  previous URL stay in place and are counted at open.
+
 ## The site
 
 ```ts
@@ -286,9 +340,18 @@ page how to write its links through the route it rewrites to:
 
 ## Publishing
 
-`package.json` says `0.0.0` on purpose: `nix run .#publish -- minor` bumps it
-to `0.1.0`, the version `template/` asks for (`^0.1.0`). kitstart's peers
-must be on the registry first, so a release is two runs:
+`template/` follows the release on its own: `nix run .#publish` rewrites a
+template range that no longer admits a version it just published to
+`^<version>`, and on a kitstart release moves the `@evinvest/kitstart-v…` pin in
+`template/flake.nix` and this README — all in the release commit, so the tag
+lands on a template that already points at it. kitstart publishes last in a
+run, so its tarball carries the new ranges. A run without kitstart still
+moves the template, but the kitstart tarball already on npm ships the old one,
+so that run ends by printing the `--only @evinvest/kitstart` command that
+releases it. A range the script cannot read, or a branch behind its upstream,
+stops the run before anything is published. `npm test` fails whenever the
+template stops admitting the workspace versions. kitstart's peers must be on
+the registry first, so a release is two runs:
 
 1. `nix run .#publish -- minor --npm-only --only @evinvest/uikit --only @evinvest/marketing`,
    then wait until `npm view @evinvest/uikit version` answers the new one;

package/dist/core/accept.d.ts

@@ -27,6 +27,15 @@ export interface AcceptDeps {
     /** Runs after the response is sent; see the route handler. */
     defer: (task: () => Promise<void> | void) => void;
     notify: (lead: Lead, id: number) => Promise<void>;
+    /**
+     * Queues the lead for a durable delivery (the webhook outbox) before the
+     * answer, where a crash cannot drop it; a lead the notifier skips is skipped
+     * here too. A failure logs and changes nothing — the lead is stored.
+     */
+    enqueue?: (lead: Lead, id: number, meta: {
+        locale: string;
+        formId: string;
+    }) => void;
     capture: (lead: Lead, formId: string) => void;
     limiter: RateLimiter;
     now: number;

package/dist/core/accept.js

@@ -65,6 +65,14 @@ async function accept(site, form, clientKey, deps) {
         deps.log.warn(`quote: lead ${id} stored as suspected spam (${lead.spamVerdict}); not notified`);
         return { kind: "stored", id, lead, locale, formId };
     }
+    if (deps.enqueue) {
+        try {
+            deps.enqueue(lead, id, { locale, formId });
+        }
+        catch (error) {
+            deps.log.error(`quote: lead ${id} is stored but could not be queued for its webhook`, error);
+        }
+    }
     deps.defer(async () => {
         try {
             await deps.notify(lead, id);

package/dist/next/quote-route.d.ts

@@ -3,6 +3,7 @@ import type { LeadStore } from "../core/lead.js";
 import type { Place } from "../core/place/types.js";
 import { type Site } from "../core/site.js";
 import type { ServerEnv } from "../server/env.js";
+import type { LeadWebhook } from "../server/lead-webhook.js";
 import type { LeadNotifier } from "../server/notify.js";
 /**
  * `app/quote/route.ts` — the no-JS path, and the one that has to keep working:
@@ -10,7 +11,7 @@ import type { LeadNotifier } from "../server/notify.js";
  *
  * ```ts
  * export const dynamic = "force-dynamic";
- * export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable });
+ * export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavailable });
  * ```
  */
 export interface UnavailableCopy {
@@ -23,6 +24,13 @@ export interface QuoteRouteDeps<L extends string> {
     env: () => Pick<ServerEnv, "leadsDb" | "posthogKey" | "posthogHost" | "trustedProxy">;
     /** Built once (and at boot, by the brand) so a missing sender fails startup, not a lead. */
     notifier: () => LeadNotifier;
+    /**
+     * The signed lead webhook, or `null` when it is off (`leadWebhook`). A lead
+     * is queued before the 303 and sent after it; the brand's
+     * `instrumentation.ts` should `start()` it so a restart resumes the queue
+     * without waiting for the next lead.
+     */
+    webhook?: () => LeadWebhook | null;
     /** The self-contained 500's words, when the store refused the lead. */
     unavailable: (locale: L, place: Place<L> | null) => UnavailableCopy;
     /** Opened on first use (`next build` imports the route); defaults to `LEADS_DB_URL`'s. */

package/dist/next/quote-route.js

@@ -56,6 +56,15 @@ export function quoteRoute(site, deps) {
     const log = deps.log ?? console;
     let store;
     let notifier;
+    let webhook;
+    const leadWebhook = () => {
+        if (webhook === undefined) {
+            webhook = deps.webhook?.() ?? null;
+            // Idempotent: a brand that started it at boot keeps its timer.
+            webhook?.start();
+        }
+        return webhook;
+    };
     const leadStore = () => {
         store ??= deps.store ? deps.store() : openLeadStore(deps.env().leadsDb);
         return store;
@@ -104,6 +113,13 @@ export function quoteRoute(site, deps) {
                 notifier ??= deps.notifier();
                 return notifier.notify(lead, id);
             },
+            enqueue: (lead, id, meta) => {
+                const hook = leadWebhook();
+                if (!hook)
+                    return;
+                hook.enqueue(lead, id, meta);
+                defer(() => hook.tick().then(() => undefined, error => log.error("quote: the webhook delivery after a lead failed", error)));
+            },
             capture: (lead, formId) => analyticsSink({ key: env.posthogKey, host: env.posthogHost, brandId: site.brand.id }, lead.placeSlug).capture(EVENTS.leadSubmit, {
                 form_id: formId,
             }),

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, 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 } 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-webhook.d.ts

@@ -0,0 +1,50 @@
+import "server-only";
+import type { Lead } 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;
+}
+/**
+ * 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;

package/dist/server/lead-webhook.js

@@ -0,0 +1,31 @@
+import "server-only";
+import { randomUUID } from "node:crypto";
+import { openWebhookOutbox } from "./webhook-outbox.js";
+/**
+ * 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/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();
+        },
+    };
+}

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

@@ -0,0 +1,32 @@
+import "server-only";
+/**
+ * How a signed webhook proves who sent it and when:
+ *
+ * ```text
+ * <keyId header>:     the sender's key id
+ * <timestamp header>: unix seconds at send time
+ * <signature header>: hex(HMAC-SHA256(secret, prefix + timestamp + "." + body))
+ * ```
+ *
+ * The timestamp is inside the MAC, so a captured request cannot be re-stamped
+ * past the receiver's replay window. The prefix names what is signed, so a MAC
+ * made with the same secret for anything else never passes for this. Prefix
+ * and header names are the receiver's, and a brand passes them — the kit
+ * knows no receiver, so it has no defaults to guess one by.
+ */
+export interface WebhookSigning {
+    prefix: string;
+    headers: WebhookSignatureHeaders;
+}
+export interface WebhookSignatureHeaders {
+    keyId: string;
+    timestamp: string;
+    signature: string;
+}
+/** Lowercase hex, as the receiver compares it. */
+export declare function signWebhook(secret: string, prefix: string, timestamp: string, body: string): string;
+/** The three headers for one send; signed afresh each attempt, since the timestamp is. */
+export declare function signatureHeaders(signing: WebhookSigning, key: {
+    keyId: string;
+    secret: string;
+}, body: string, nowMs: number): Record<string, string>;

package/dist/server/webhook-signature.js

@@ -0,0 +1,16 @@
+import "server-only";
+import { createHmac } from "node:crypto";
+/** Lowercase hex, as the receiver compares it. */
+export function signWebhook(secret, prefix, timestamp, body) {
+    return createHmac("sha256", secret).update(prefix).update(timestamp).update(".").update(body).digest("hex");
+}
+/** The three headers for one send; signed afresh each attempt, since the timestamp is. */
+export function signatureHeaders(signing, key, body, nowMs) {
+    const names = signing.headers;
+    const timestamp = String(Math.floor(nowMs / 1000));
+    return {
+        [names.keyId]: key.keyId,
+        [names.timestamp]: timestamp,
+        [names.signature]: signWebhook(key.secret, signing.prefix, timestamp, body),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evinvest/kitstart",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Landing-site machinery for local-service brands: a site composition root, the Place/Presence/ServiceArea model with a publication gate, host/locale routing, schema.org and SEO builders, the lead funnel with its antispam, and analytics events. Pure core at '.', more subpaths per runtime.",
   "license": "BlueOak-1.0.0",
   "publishConfig": {

package/template/flake.nix

@@ -3,7 +3,7 @@
     v_flakes.url = "github:valeratrades/v_flakes?ref=v1.6";
     # The lib flake at the tag of the @evinvest/kitstart version in
     # package-lock.json — mkLanding refuses a mismatch.
-    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.3.0";
+    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.5.0";
     ev.inputs.v_flakes.follows = "v_flakes";
   };
 

package/template/package.json

@@ -20,9 +20,9 @@
   "dependencies": {
     "@evinvest/analytics": "^0.3.0",
     "@evinvest/i18n": "^0.9.0",
-    "@evinvest/kitstart": "^0.3.0",
+    "@evinvest/kitstart": "^0.5.0",
     "@evinvest/marketing": "^0.3.0",
-    "@evinvest/uikit": "^0.22.0",
+    "@evinvest/uikit": "^0.24.0",
     "next": "16.3.6",
     "react": "19.3.0",
     "react-dom": "19.3.0",

package/template/tests/e2e/quote-form.spec.ts

@@ -1,4 +1,4 @@
-import { expect, test, type Page } from "@playwright/test";
+import { expect, test, type Locator, type Page } from "@playwright/test";
 
 // The quote form's contract with the visitor: it posts before any script
 // (the one standing in water may be on a bad connection), and once the script
@@ -51,6 +51,9 @@ test.describe("with JavaScript", () => {
   test("works from the keyboard", async ({ page }) => {
     await page.goto("/fr#quote");
     const trigger = page.getByRole("combobox", { name: SUBJECT });
+    // Before hydration the role finds the server's select, and the focus
+    // would go to it, not the kit's list; wait for the select to be replaced.
+    await expect(page.locator("#quote select")).toHaveCount(0);
     await trigger.focus();
     await page.keyboard.press("ArrowDown");
     await expect(page.getByRole("option", { name: "Ménage courant" })).toBeFocused();
@@ -65,18 +68,34 @@ test.describe("with JavaScript", () => {
 });
 
 test("the field is the same box before and after hydration", async ({ browser }) => {
-  const box = async (javaScriptEnabled: boolean) => {
+  const open = async (javaScriptEnabled: boolean) => {
     const context = await browser.newContext({ javaScriptEnabled });
     const page = await context.newPage();
     await page.goto("/fr#quote");
-    const control = javaScriptEnabled ? page.getByRole("combobox", { name: SUBJECT }) : page.locator("#quote select[name=subject]");
-    await expect(control).toBeVisible();
-    const rect = await control.evaluate(el => {
+    return page;
+  };
+  const measure = (control: Locator) =>
+    control.evaluate(el => {
       const r = el.getBoundingClientRect();
       return { width: r.width, height: r.height, x: r.x, border: getComputedStyle(el).borderTopWidth, radius: getComputedStyle(el).borderTopLeftRadius };
     });
-    await context.close();
-    return rect;
-  };
-  expect(await box(true)).toEqual(await box(false));
+
+  // The server's select is a combobox of the same name, so until the page
+  // hydrates the role finds it — and hydration detaches it, leaving a
+  // measurement of zeros. Measure only once the kit's button has replaced it.
+  const scripted = await open(true);
+  await expect(scripted.locator("#quote select")).toHaveCount(0);
+  const kit = scripted.getByRole("combobox", { name: SUBJECT });
+  await expect(kit).toHaveJSProperty("tagName", "BUTTON");
+  await expect(kit).toBeVisible();
+  const hydrated = await measure(kit);
+  await scripted.context().close();
+
+  const bare = await open(false);
+  const native = bare.locator("#quote select[name=subject]");
+  await expect(native).toBeVisible();
+  const server = await measure(native);
+  await bare.context().close();
+
+  expect(hydrated).toEqual(server);
 });