@evinvest/kitstart 0.10.0 → 0.12.0

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

@@ -0,0 +1,49 @@
+import "server-only";
+/**
+ * An operator's override of one experiment, as the panel serves it — the
+ * shape `applyOverrides` of `@evinvest/experiments` takes. Only the types are
+ * checked here; whether a field fits the experiment in code (weights of the
+ * right length, a holdout in `[0, 1)`) is `applyOverrides`' call, because only
+ * it knows the code's variants.
+ */
+export interface ExperimentOverride {
+    readonly enabled?: boolean;
+    readonly weights?: readonly number[];
+    readonly holdout?: number;
+}
+export type ExperimentOverrides = Readonly<Record<string, ExperimentOverride>>;
+/**
+ * The operator's overrides of the brand's experiments: `GET
+ * <base>/experiments`, the panel's `{ "experiments": { "<key>": {…} } }`.
+ *
+ * Read by the proxy on every request, so the answer comes from memory: the
+ * first call waits for the panel (bounded by `timeoutMs`), every later one is
+ * served from the cache — past the TTL too, while one refresh runs behind it
+ * (stale-while-revalidate). The source never throws and never makes a page
+ * wait on the panel twice. A failed refresh — an unreachable panel, a
+ * non-200, a body that is not the panel's shape — keeps the last good answer:
+ * a kill switch must not turn itself back on because the panel blinked. With
+ * no good answer yet (or no base URL) it is `{}`, the config in code.
+ */
+export interface ExperimentsSourceOptions {
+    /** The brand's base on the panel (`LOCATIONS_API_URL`), read when asked; `null` → no overrides. */
+    baseUrl: () => string | null;
+    /** How long an answer is fresh; 30 s. */
+    ttlMs?: number;
+    /** How long the panel is given; 1.5 s. The proxy is waiting on the first call. */
+    timeoutMs?: number;
+    now?: () => number;
+    log?: Pick<Console, "error">;
+}
+export interface ExperimentsSource {
+    /** The overrides to apply now; `{}` when there are none or the panel cannot say. Never throws. */
+    overrides(): Promise<ExperimentOverrides>;
+}
+export declare const EXPERIMENTS_TTL_MS = 30000;
+/**
+ * The panel's answer as overrides, or `null` when it is not the panel's shape.
+ * A field of the wrong type is dropped, an entry that is not an object is
+ * skipped; the rest stands.
+ */
+export declare function parseExperimentOverrides(body: unknown): ExperimentOverrides | null;
+export declare function createExperimentsSource(options: ExperimentsSourceOptions): ExperimentsSource;

package/dist/server/experiments-source.js

@@ -0,0 +1,88 @@
+import "server-only";
+export const EXPERIMENTS_TTL_MS = 30_000;
+const TIMEOUT_MS = 1_500;
+const NONE = Object.freeze({});
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The panel's answer as overrides, or `null` when it is not the panel's shape.
+ * A field of the wrong type is dropped, an entry that is not an object is
+ * skipped; the rest stands.
+ */
+export function parseExperimentOverrides(body) {
+    if (!isRecord(body) || !isRecord(body["experiments"]))
+        return null;
+    const out = {};
+    for (const [key, entry] of Object.entries(body["experiments"])) {
+        if (!isRecord(entry))
+            continue;
+        const { enabled, weights, holdout } = entry;
+        out[key] = {
+            ...(typeof enabled === "boolean" ? { enabled } : {}),
+            ...(Array.isArray(weights) && weights.every((w) => typeof w === "number") ? { weights } : {}),
+            ...(typeof holdout === "number" ? { holdout } : {}),
+        };
+    }
+    return out;
+}
+export function createExperimentsSource(options) {
+    const ttl = options.ttlMs ?? EXPERIMENTS_TTL_MS;
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const log = options.log ?? console;
+    let cached = null;
+    let inflight = null;
+    /** The panel's overrides, or `null` when it could not say. */
+    async function load(base) {
+        let response;
+        try {
+            // `no-store`: the cache is this module's; Next's data cache would add a second TTL.
+            response = await fetch(`${base}/experiments`, { cache: "no-store", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch (cause) {
+            log.error("experiments: the panel is unreachable, keeping the last good overrides", cause);
+            return null;
+        }
+        if (response.status !== 200) {
+            log.error(`experiments: the panel answered ${response.status}, keeping the last good overrides`);
+            return null;
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (cause) {
+            log.error("experiments: the panel's body is not JSON, keeping the last good overrides", cause);
+            return null;
+        }
+        const parsed = parseExperimentOverrides(body);
+        if (parsed === null)
+            log.error("experiments: the panel's body is not { experiments: {…} }, keeping the last good overrides");
+        return parsed;
+    }
+    // One request at a time, however many visitors arrive while it runs.
+    function refresh(base) {
+        inflight ??= load(base)
+            .then(loaded => {
+            // A failure still restarts the clock, so a down panel is asked once per TTL.
+            const value = loaded ?? (cached?.base === base ? cached.value : NONE);
+            cached = { base, at: now(), value };
+            return value;
+        })
+            .finally(() => {
+            inflight = null;
+        });
+        return inflight;
+    }
+    return {
+        async overrides() {
+            const base = options.baseUrl();
+            if (!base)
+                return NONE;
+            if (cached?.base !== base)
+                return refresh(base);
+            if (now() - cached.at >= ttl)
+                void refresh(base);
+            return cached.value;
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -6,14 +6,16 @@
 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 { createExperimentsSource, EXPERIMENTS_TTL_MS, parseExperimentOverrides, type ExperimentOverride, type ExperimentOverrides, type ExperimentsSource, type ExperimentsSourceOptions, } from "./experiments-source.js";
+export { declarationProblem, declareExperiments, experimentsDeclaredBody, type DeclarationContext, type DeclaredExperiment, type DeclareOptions, type DeclareOutcome, type ExperimentDeclarationV1, type ExperimentsDeclaration, type ExperimentsDeclaredEvent, } from "./experiments-declared.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";
 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 { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE, type LeadMail, type LeadMailShown, type LeadNotifier, type NeedLabel, 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, panelFlowOf, panelFlowProperties, type BuildWebhookBody, type LeadWebhook, type LeadWebhookContext, type LeadWebhookOptions, type PanelFlow, type PanelFlowProperties, } from "./lead-webhook.js";
+export { leadWebhook, panelChannel, panelFlowOf, panelFlowProperties, type BookingQueued, type BookingWebhookContext, type BuildBookingBody, 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,8 @@
 import "server-only";
 export { createServerEnv, parseServerEnv } from "./env.js";
 export { createPlaceSource, PLACE_REVALIDATE_SECONDS, PlaceSourceError } from "./place-source.js";
+export { createExperimentsSource, EXPERIMENTS_TTL_MS, parseExperimentOverrides, } from "./experiments-source.js";
+export { declarationProblem, declareExperiments, experimentsDeclaredBody, } from "./experiments-declared.js";
 export { createPricingSource } from "./pricing-source.js";
 export { describeLeadDb, openLeadStore, parseLeadDb } from "./lead-store.js";
 export { openSqliteLeadStore } from "./lead-store-sqlite.js";

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

@@ -1,7 +1,9 @@
 import "server-only";
+import type { BookingRequest } from "../core/booking/model.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 DeclareOutcome, type ExperimentsDeclaration } from "./experiments-declared.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. */
@@ -33,6 +35,14 @@ export interface LeadWebhookContext {
      * the properties. `panelFlowProperties` writes them as the panel reads them.
      */
     flow?: PanelFlow;
+    /**
+     * The visitor's analytics id as the page posted it (`ANALYTICS_ID_FIELD`),
+     * for `lead.created`'s `analytics_id` — so PostHog joins the lead to the
+     * visit. Absent from a page without the script, an older page, or one
+     * without analytics. Write it only once the panel's contract has the
+     * property: it refuses an unknown one, and the outbox would park the lead.
+     */
+    analyticsId?: string;
 }
 /** A lead's sale as the panel's `lead.created` may carry it. */
 export interface PanelFlow {
@@ -75,12 +85,39 @@ export declare function panelChannel(channel: LeadChannel): "form" | typeof PANE
  * lead is queued — the stored body is what every attempt sends.
  */
 export type BuildWebhookBody = (lead: Lead, ctx: LeadWebhookContext) => unknown;
+/** What the brand's booking body builder is told besides the request. */
+export interface BookingWebhookContext {
+    brandId: string;
+    /** When the site took the request. */
+    at: Date;
+    /** Fresh per request and stored with the body, like a lead's. */
+    idempotencyKey: string;
+}
+/**
+ * `booking.requested@1`'s body, built by the brand like `BuildWebhookBody`:
+ * `bookingRequestedProperties(request)` writes the properties as the panel
+ * reads them, and `request.leadRef` is the lead id the brand's
+ * `lead.created` must have carried for the two to join.
+ */
+export type BuildBookingBody = (request: BookingRequest, ctx: BookingWebhookContext) => unknown;
+/** Why `requestBooking` queued nothing. */
+export type BookingQueued = {
+    kind: "queued";
+    row: number;
+} | {
+    kind: "off";
+} | {
+    kind: "duplicate";
+} | {
+    kind: "unqueued";
+};
 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;
         leadRef?: string;
+        analyticsId?: string;
     }): number;
     tick(): Promise<TickReport>;
     start(intervalMs?: number): void;
@@ -92,6 +129,23 @@ export interface LeadWebhook {
     readonly panelSuspect: boolean;
     /** Whether `ctx.flow` is filled in (`LeadWebhookOptions.panelFlow`). */
     readonly panelFlow: boolean;
+    /** Whether `requestBooking` queues anything (`LeadWebhookOptions.panelBooking`). */
+    readonly panelBooking?: boolean;
+    /**
+     * Queues `booking.requested@1` behind the lead's `lead.created`, through
+     * the same outbox: not sent until that row is delivered, and a `409` / `425`
+     * for it retried. Once per lead: a second request is a `duplicate`,
+     * whatever it asks. `unqueued` when the lead's own row was never queued (a
+     * suspect held back); `off` without `panelBooking` or a `buildBookingBody`.
+     */
+    requestBooking?(request: BookingRequest): BookingQueued;
+    /**
+     * Queues `experiments.declared@1` — the experiments this build runs — in
+     * the same outbox, signed as a lead is. Experiments the panel would refuse
+     * are left out and listed in `skipped`. `declareExperiments` is the safe
+     * wrapper for a start.
+     */
+    declareExperiments?(experiments: ExperimentsDeclaration, summaries?: Readonly<Record<string, string>>): DeclareOutcome;
     readonly outbox: WebhookOutbox;
 }
 export interface LeadWebhookOptions extends WebhookOutboxOptions {
@@ -114,6 +168,15 @@ export interface LeadWebhookOptions extends WebhookOutboxOptions {
      * the outbox would park the lead. The leads table keeps them either way.
      */
     panelFlow?: boolean;
+    /**
+     * The switch for `booking.requested@1` (`requestBooking`). Off (the
+     * default) until the panel accepts the event type — it refuses an unknown
+     * one, and the outbox would park it. Off, a booking request is answered
+     * and dropped; the lead is untouched either way.
+     */
+    panelBooking?: boolean;
+    /** The body of `booking.requested@1`; absent → booking requests are dropped whatever `panelBooking` says. */
+    buildBookingBody?: BuildBookingBody | undefined;
 }
 /**
  * The lead webhook, or `null` when it is off: no `LEAD_WEBHOOK_URL`, or no

package/dist/server/lead-webhook.js

@@ -1,6 +1,7 @@
 import "server-only";
 import { randomUUID } from "node:crypto";
 import { suspectOf } from "../core/lead.js";
+import { experimentsDeclaredBody } from "./experiments-declared.js";
 import { openWebhookOutbox } from "./webhook-outbox.js";
 /** The sale `ctx.flow` describes, or nothing for a lead without a flow. */
 export function panelFlowOf(lead) {
@@ -38,17 +39,39 @@ export function panelChannel(channel) {
  * so a broken setting fails startup rather than a lead.
  */
 export function leadWebhook(site, env, options) {
-    const { buildBody, signing, panelSuspect = false, panelFlow = false, ...outboxOptions } = options;
+    const { buildBody, buildBookingBody, signing, panelSuspect = false, panelFlow = false, panelBooking = false, ...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;
+    const sourceId = env.leadWebhook.keyId;
     return {
         outbox,
         panelSuspect,
         panelFlow,
+        panelBooking,
+        requestBooking(request) {
+            if (!panelBooking || !buildBookingBody)
+                return { kind: "off" };
+            // The lead's own row, as `enqueue` refs it: the booking follows it, and
+            // a lead never queued (held back as suspect) is never booked to the panel.
+            const lead = `lead:${/^lead-(\d+)-/.exec(request.leadRef)?.[1] ?? ""}`;
+            if (!outbox.hasRef(lead))
+                return { kind: "unqueued" };
+            const ctx = { brandId: site.brand.id, at: new Date(now()), idempotencyKey: randomUUID() };
+            const body = JSON.stringify(buildBookingBody(request, ctx));
+            if (typeof body !== "string")
+                throw new Error("buildBookingBody returned nothing JSON can carry");
+            const row = outbox.enqueueOnce(body, `booking:${request.leadRef}`, lead);
+            return row === null ? { kind: "duplicate" } : { kind: "queued", row };
+        },
+        declareExperiments(experiments, summaries) {
+            const { body, skipped } = experimentsDeclaredBody(experiments, { brandId: site.brand.id, sourceId, at: new Date(now()), ...(summaries ? { summaries } : {}) });
+            const row = outbox.enqueue(JSON.stringify(body), `experiments:${body.events[0].id}`);
+            return { kind: "queued", row, skipped };
+        },
         enqueue(lead, id, meta) {
             const suspect = panelSuspect ? suspectOf(lead) : undefined;
             const flow = panelFlow ? panelFlowOf(lead) : undefined;

package/dist/server/notify.d.ts

@@ -15,8 +15,19 @@ export interface LeadMail {
     text: string;
 }
 export type NotifyEnv = Pick<ServerEnv, "smtpUrl" | "notifyTo" | "notifyFrom" | "smsToken">;
+/**
+ * The need's label in the mail's language — the business's, whatever the
+ * visitor's — or `undefined` for one it does not know (a stale form's).
+ */
+export type NeedLabel = (need: string) => string | undefined;
+/** What a mail shows in place of the raw lead: the need as `needLabel` names it, else its id. */
+export interface LeadMailShown {
+    need: string;
+}
 /** A plain default; a brand passes `format` to write it in its own language. */
-export declare function defaultLeadMail(brand: Pick<BrandFacts, "name">, lead: Lead, id: number): LeadMail;
+export declare function defaultLeadMail(brand: Pick<BrandFacts, "name">, lead: Lead, id: number, options?: {
+    needLabel?: NeedLabel | undefined;
+}): LeadMail;
 /**
  * Checked when it is built — at boot, when a brand builds it there — not on
  * the first lead: with SMTP configured, a sender needs a domain to be `leads@`
@@ -29,7 +40,14 @@ export declare const MAIL_PER_MINUTE = 20;
 export declare function leadNotifier(site: {
     brand: BrandFacts;
 }, env: NotifyEnv, options?: {
-    format?: (lead: Lead, id: number) => LeadMail;
+    /** The brand's mail; `shown.need` is the need's label (`needLabel`), else its id. */
+    format?: (lead: Lead, id: number, shown: LeadMailShown) => LeadMail;
+    /**
+     * Names the need in the mail — `lead.subject` is the id the form posted
+     * (`hot_water`), which the business should not have to decode. The labels
+     * the brand hands `LeadCapture` as `needs`, in the mail's language.
+     */
+    needLabel?: NeedLabel;
     log?: Pick<Console, "warn">;
     /** `MAIL_PER_MINUTE` by default: a flood that passes the antispam must not become a mail flood. */
     mailPerMinute?: number;

package/dist/server/notify.js

@@ -1,8 +1,9 @@
 import "server-only";
 import { channelOf } from "../core/lead.js";
 import { parseSmtpUrl, sendMail } from "./smtp.js";
+const shownOf = (lead, needLabel) => ({ need: needLabel?.(lead.subject) ?? lead.subject });
 /** A plain default; a brand passes `format` to write it in its own language. */
-export function defaultLeadMail(brand, lead, id) {
+export function defaultLeadMail(brand, lead, id, options = {}) {
     const place = lead.placeSlug ?? "unknown";
     // A callback request is a promise to ring the customer: it says so first.
     const callback = channelOf(lead) === "callback";
@@ -11,7 +12,7 @@ export function defaultLeadMail(brand, lead, id) {
         text: [
             `Lead #${id} — place ${place}${callback ? " — CALL BACK" : ""}${lead.spamVerdict ? ` — suspect (${lead.spamVerdict})` : ""}`,
             "",
-            `Subject  : ${lead.subject}`,
+            `Subject  : ${shownOf(lead, options.needLabel).need}`,
             `Locality : ${lead.locality}`,
             `Mobile   : ${lead.mobile}`,
             ...Object.entries(lead.extras).map(([name, value]) => `${name} : ${value}`),
@@ -32,7 +33,8 @@ export function leadNotifier(site, env, options = {}) {
     const log = options.log ?? console;
     const now = options.now ?? Date.now;
     const cap = options.mailPerMinute ?? MAIL_PER_MINUTE;
-    const format = options.format ?? ((lead, id) => defaultLeadMail(brand, lead, id));
+    const { needLabel } = options;
+    const format = options.format ?? ((lead, id) => defaultLeadMail(brand, lead, id, { needLabel }));
     let window = { start: Number.NEGATIVE_INFINITY, sent: 0 };
     const spend = () => {
         const t = now();
@@ -59,7 +61,7 @@ export function leadNotifier(site, env, options = {}) {
                 log.warn(`lead ${id}: over ${cap} notification mails a minute; stored, not mailed`);
             }
             else if (mail) {
-                const { subject, text } = format(lead, id);
+                const { subject, text } = format(lead, id, shownOf(lead, needLabel));
                 channels.push(sendMail(mail.url, { from: mail.from, to: mail.to, subject, text }, { helo: mail.helo }));
             }
             if (env.smsToken) {

package/dist/server/place-source.js

@@ -29,7 +29,7 @@ export function createPlaceSource(site, options) {
         if (!response.ok)
             return { kind: "failed", status: response.status };
         try {
-            return { kind: "live", place: mergeLive(baked, parsePlaceLive(await response.json(), site.i18n.locales)) };
+            return { kind: "live", place: mergeLive(baked, parsePlaceLive(await response.json(), site.i18n.locales, site.booking ?? {})) };
         }
         catch (cause) {
             // A body that is not the source's shape is the source failing, not the place.

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

@@ -67,6 +67,16 @@ export interface TickReport {
 export interface WebhookOutbox {
     /** Queues a body; synchronous and local, so it can sit before the response. */
     enqueue(body: string, ref?: string | null): number;
+    /**
+     * Queues a body unless a row with the same `ref` was ever queued, in one
+     * statement — two pods racing on one ref queue it once. Answers the new
+     * row, or `null` when the ref was there. With `after`, the row is not sent
+     * until the row of that ref is delivered, and a `409` or `425` for it is
+     * retried: the receiver has not seen what it depends on yet.
+     */
+    enqueueOnce?(body: string, ref: string, after?: string): number | null;
+    /** Whether a row with this `ref` was ever queued, whatever its state. */
+    hasRef?(ref: string): boolean;
     /** 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. */
@@ -100,4 +110,4 @@ export declare function checkWebhookUrl(value: string, name?: string): string;
  * 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;
+export declare function openWebhookOutbox(path: string, target: WebhookTarget, options?: WebhookOutboxOptions): WebhookOutbox & Required<Pick<WebhookOutbox, "enqueueOnce" | "hasRef">>;

package/dist/server/webhook-outbox.js

@@ -21,7 +21,17 @@ CREATE TABLE IF NOT EXISTS webhook_outbox (
   done_at         INTEGER
 );
 CREATE INDEX IF NOT EXISTS webhook_outbox_due ON webhook_outbox (state, target, next_attempt_at);
+CREATE INDEX IF NOT EXISTS webhook_outbox_ref ON webhook_outbox (ref);
 `;
+/**
+ * Added after the table shipped: a file from before gets it on open. A row's
+ * `after_ref` holds it until the row of that ref is delivered.
+ */
+function addAfterRef(db) {
+    const columns = db.prepare("PRAGMA table_info(webhook_outbox)").all();
+    if (!columns.some(c => column(c, "name") === "after_ref"))
+        db.exec("ALTER TABLE webhook_outbox ADD COLUMN after_ref TEXT");
+}
 /** How much of a receiver's answer a row keeps. */
 const ERROR_CAP = 500;
 const IN_CLUSTER = /(^|\.)svc(\.cluster\.local)?$/;
@@ -103,7 +113,7 @@ async function multiStatus(response, rowId, log) {
     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) {
+async function judge(response, rowId, log, dependent) {
     const status = response.status;
     if (status === 207)
         return multiStatus(response, rowId, log);
@@ -116,6 +126,9 @@ 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 row that follows another: the receiver may not have taken that one yet.
+    if (dependent && (status === 409 || status === 425))
+        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)
@@ -150,13 +163,19 @@ export function openWebhookOutbox(path, target, options = {}) {
         db.exec("PRAGMA busy_timeout = 5000");
         db.exec("PRAGMA journal_mode = WAL");
         db.exec(SCHEMA);
+        addAfterRef(db);
     }
     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, ref, body, attempts, created_at FROM webhook_outbox WHERE state = 'pending' AND target = ? AND next_attempt_at <= ? ORDER BY next_attempt_at, id LIMIT ?");
+    const insertOnce = db.prepare("INSERT INTO webhook_outbox (target, ref, body, created_at, next_attempt_at, after_ref) SELECT ?, ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM webhook_outbox WHERE ref = ?) RETURNING id");
+    const byRef = db.prepare("SELECT 1 FROM webhook_outbox WHERE ref = ? LIMIT 1");
+    // A row waits for the row it follows to be delivered; held, it is not due.
+    const due = db.prepare(`SELECT id, ref, body, attempts, created_at, after_ref FROM webhook_outbox AS o WHERE state = 'pending' AND target = ? AND next_attempt_at <= ?
+       AND (after_ref IS NULL OR EXISTS (SELECT 1 FROM webhook_outbox AS d WHERE d.ref = o.after_ref AND d.state = 'delivered'))
+     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 = ?");
@@ -173,7 +192,7 @@ export function openWebhookOutbox(path, target, options = {}) {
         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) {
+    async function deliver(id, body, dependent) {
         try {
             const response = await send(target.url, {
                 method: "POST",
@@ -182,7 +201,7 @@ export function openWebhookOutbox(path, target, options = {}) {
                 redirect: "manual",
                 signal: AbortSignal.timeout(timeoutMs),
             });
-            return await judge(response, id, log);
+            return await judge(response, id, log, dependent);
         }
         catch (error) {
             // The name and code only: a fetch error's message is safe, but its cause chain is the runtime's to word.
@@ -202,7 +221,7 @@ export function openWebhookOutbox(path, target, options = {}) {
             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);
+            const verdict = await deliver(id, body, text(row, "after_ref") !== null);
             if (verdict.kind === "delivered") {
                 finish.run("delivered", attempts, verdict.note?.slice(0, ERROR_CAP) ?? null, now(), id);
                 report.delivered += 1;
@@ -249,6 +268,14 @@ export function openWebhookOutbox(path, target, options = {}) {
             const t = now();
             return int(insert.get(target.url, ref, body, t, t), "id");
         },
+        enqueueOnce(body, ref, after) {
+            const t = now();
+            const row = insertOnce.get(target.url, ref, body, t, t, after ?? null, ref);
+            return row === undefined ? null : int(row, "id");
+        },
+        hasRef(ref) {
+            return byRef.get(ref) !== undefined;
+        },
         tick,
         start(intervalMs = WEBHOOK_TICK_MS) {
             if (timer)

package/dist/testing/lead-rules.js

@@ -16,7 +16,13 @@ export const PHONE_MATRIX = [
     { mobile: "01 23 45 67 89", valid: true },
     { mobile: "+1 415 555 0123", valid: true },
     { mobile: "+44 7911 123456", valid: true },
-    { mobile: "+12345678", valid: true },
+    { mobile: "+32 470 12 34 56", valid: true },
+    { mobile: "+41 44 668 18 00", valid: true },
+    { mobile: "+49 30 1234567", valid: true },
+    { mobile: "+34 612 345 678", valid: true },
+    { mobile: "+39 06 1234 5678", valid: true },
+    { mobile: "+44 20 7946 0958", valid: true },
+    { mobile: "+352 621 123 456", valid: true },
     { mobile: "０６１２３４５６７８", valid: true },
     { mobile: "(415) 555-0123", valid: false },
     { mobile: "+3361234567", valid: false },
@@ -25,6 +31,14 @@ export const PHONE_MATRIX = [
     { mobile: "06 12 34 56 7", valid: false },
     { mobile: "12 34 56 7", valid: false },
     { mobile: "+1234567", valid: false },
+    // A known plan's number short of its national length (LEAD-FORMS-RETEST-2026-10-03).
+    { mobile: "+12345678", valid: false },
+    { mobile: "+1 415 555 012", valid: false },
+    { mobile: "+44 7911 1234", valid: false },
+    { mobile: "+34 612 345 67", valid: false },
+    { mobile: "+41 44 668 18 0", valid: false },
+    { mobile: "+32 470 123", valid: false },
+    { mobile: "+49 30 1234", valid: false },
     { mobile: "06 12", valid: false },
 ];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evinvest/kitstart",
-  "version": "0.10.0",
+  "version": "0.12.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/app/quote/booking/route.ts

@@ -0,0 +1,11 @@
+import { bookingRoute } from "@evinvest/kitstart/next";
+import { serverEnv } from "@/shared/config/env";
+
+/**
+ * A priced lead asking for a slot: `booking.requested@1` to the panel through
+ * the lead webhook's outbox, once its `panelBooking` is on. This template has
+ * no webhook, so the request is answered and dropped.
+ */
+export const dynamic = "force-dynamic";
+
+export const POST = bookingRoute({ env: serverEnv });

package/template/app/quote/confirm/route.ts

@@ -0,0 +1,12 @@
+import { confirmRoute } from "@evinvest/kitstart/next";
+import { TEXT } from "@/entities/content";
+import { pricing } from "@/shared/config/env";
+import { site } from "@/shared/config/site";
+
+/**
+ * A form posted without a script whose price changed lands here: a page that
+ * is never cached, with the fresh price to confirm.
+ */
+export const dynamic = "force-dynamic";
+
+export const GET = confirmRoute(site, { pricing, text: locale => TEXT[locale].leadCapture });

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.10.0";
+    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.12.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.10.0",
+    "@evinvest/kitstart": "^0.12.0",
     "@evinvest/marketing": "^0.3.0",
-    "@evinvest/uikit": "^0.25.0",
+    "@evinvest/uikit": "^0.26.0",
     "next": "16.3.6",
     "react": "19.3.0",
     "react-dom": "19.3.0",

package/template/src/shared/config/places.ts

@@ -16,5 +16,9 @@ export const PLACES: readonly Place<Locale>[] = [
     channels: { phone: null, whatsapp: null },
     hours: [{ days: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], opens: "08:00", closes: "19:00" }],
     rating: null,
+    // How a priced lead's slot is set. Left out, the card promises a call
+    // (`manual`); the panel's place settings set it live (`PlaceLive.booking`),
+    // e.g. `{ default: "manual", providers: { google_calendar: { url: "https://calendar.app.google/…" } } }`,
+    // and the `booking_provider` experiment picks among them (`bookingOf`).
   },
 ];

package/template/src/shared/config/site.ts

@@ -31,6 +31,9 @@ export const site = defineSite({
   publication: SERVICE_AREA_GATE,
   lead: LEAD,
   pricing: PRICING,
+  // The Cal.com hosts a place's `cal_com` booking may be on. A brand on its
+  // own Cal.com adds its domain: ["cal.com", "cal.brand.fr"].
+  booking: { calComHosts: ["cal.com"] },
 });
 
 export type PageKey = (typeof site.pageKeys)[number];