@evinvest/kitstart 0.8.0 → 0.9.0

package/dist/react/QuoteFormShell.d.ts

@@ -20,6 +20,8 @@ export interface QuoteFormShellProps {
     /** The honeypot's label — read only by a bot filling every field. */
     honeypotLabel: string;
     formId?: string;
+    /** The card's anchor, posted so a refusal lands back on it (`quoteRoute`). */
+    card?: string | undefined;
     action?: string;
     id?: string;
     className?: string;

package/dist/react/QuoteFormShell.js

@@ -2,9 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "@evinvest/uikit";
 import { FORM_ID_FIELD, LOCALE_FIELD, LOCATION_FIELD } from "../core/accept.js";
 import { HONEYPOT_FIELD, RENDERED_AT_FIELD } from "../core/antispam.js";
+import { CARD_FIELD, SUBMISSION_FIELD } from "../core/lead.js";
 /** The mobile field's attributes: the numeric keypad and the phone's autofill. */
 export const PHONE_INPUT_PROPS = { type: "tel", inputMode: "tel", autoComplete: "tel" };
 export function QuoteFormShell(props) {
-    const { placeSlug, locale, renderedAt, honeypotLabel, formId = "quote", action = "/quote", id = "quote", className, onSubmit, children } = props;
-    return (_jsxs("form", { id: id, method: "post", action: action, onSubmit: onSubmit, className: cn("relative flex w-full flex-col gap-5", className), children: [placeSlug && _jsx("input", { type: "hidden", name: LOCATION_FIELD, value: placeSlug }), _jsx("input", { type: "hidden", name: LOCALE_FIELD, value: locale }), _jsx("input", { type: "hidden", name: FORM_ID_FIELD, value: formId }), _jsx("input", { type: "hidden", name: RENDERED_AT_FIELD, value: String(renderedAt) }), children, _jsx("div", { "aria-hidden": "true", style: { position: "absolute", left: "-10000px", width: 1, height: 1, overflow: "hidden" }, children: _jsxs("label", { children: [honeypotLabel, _jsx("input", { type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", defaultValue: "" })] }) })] }));
+    const { placeSlug, locale, renderedAt, honeypotLabel, formId = "quote", card, action = "/quote", id = "quote", className, onSubmit, children } = props;
+    return (_jsxs("form", { id: id, method: "post", action: action, onSubmit: onSubmit, className: cn("relative flex w-full flex-col gap-5", className), children: [placeSlug && _jsx("input", { type: "hidden", name: LOCATION_FIELD, value: placeSlug }), _jsx("input", { type: "hidden", name: LOCALE_FIELD, value: locale }), _jsx("input", { type: "hidden", name: FORM_ID_FIELD, value: formId }), _jsx("input", { type: "hidden", name: RENDERED_AT_FIELD, value: String(renderedAt) }), card && _jsx("input", { type: "hidden", name: CARD_FIELD, value: card }), _jsx("input", { type: "hidden", name: SUBMISSION_FIELD }), children, _jsx("div", { "aria-hidden": "true", style: { position: "absolute", left: "-10000px", width: 1, height: 1, overflow: "hidden" }, children: _jsxs("label", { children: [honeypotLabel, _jsx("input", { type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", defaultValue: "" })] }) })] }));
 }

package/dist/react/use-lead-error.d.ts

@@ -0,0 +1,24 @@
+import { type RefObject } from "react";
+import { type LeadChannel } from "../core/lead.js";
+import type { LeadCaptureText } from "../core/lead-capture-text.js";
+/** A refusal the server sent back: which of the card's forms, and the field it is about. */
+export interface LeadError {
+    channel: LeadChannel;
+    field: string;
+}
+/** The fields `LeadCapture` draws itself, which show a refusal under themselves. */
+export declare const OWN_FIELDS: Readonly<Record<LeadChannel, readonly string[]>>;
+/** The id of the message a refusal of a field the card does not draw is shown in, above the submit. */
+export declare const formMessageId: (id: string, channel: LeadChannel) => string;
+/** The words for a refused field: the field's own rule where the form has one. */
+export declare function errorText(field: string, text: LeadCaptureText): string;
+/**
+ * The server's refusal, for the card `id`: read once from the page's query
+ * when the 303 brought the visitor back (`?lead_error=phone#<id>`, or
+ * `#<id>-callback`) — then taken out of the URL, so a reload does not show it
+ * again — or set by the script's own post. The refused control takes the
+ * focus; a control the card does not draw (a brand's extra) is marked
+ * `aria-invalid` and pointed at the message above the submit. Fixing that
+ * control clears it.
+ */
+export declare function useLeadError(root: RefObject<HTMLElement | null>, id: string): [LeadError | null, (error: LeadError | null) => void];

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

@@ -0,0 +1,73 @@
+"use client";
+import { useEffect, useState } from "react";
+import { LEAD_ERROR_PARAM } from "../core/lead.js";
+const FIELD = /^[a-z][a-z0-9_]{0,31}$/;
+/** The fields `LeadCapture` draws itself, which show a refusal under themselves. */
+export const OWN_FIELDS = { form: ["phone", "locality", "name"], callback: ["phone", "consent"] };
+/** The id of the message a refusal of a field the card does not draw is shown in, above the submit. */
+export const formMessageId = (id, channel) => (channel === "callback" ? `${id}-callback-error` : `${id}-error`);
+/** The words for a refused field: the field's own rule where the form has one. */
+export function errorText(field, text) {
+    if (field === "phone")
+        return text.phoneInvalid;
+    if (field === "consent")
+        return text.consentRequired;
+    if (field === "need")
+        return text.needRequired;
+    if (field === "form")
+        return text.formInvalid;
+    return text.fieldInvalid;
+}
+/** The control a refusal is about: by its role, then by its posted name. */
+function controlOf(form, field) {
+    return form.querySelector(`[data-lead-field="${field}"]`) ?? form.querySelector(`[name="${CSS.escape(field)}"]`);
+}
+/**
+ * The server's refusal, for the card `id`: read once from the page's query
+ * when the 303 brought the visitor back (`?lead_error=phone#<id>`, or
+ * `#<id>-callback`) — then taken out of the URL, so a reload does not show it
+ * again — or set by the script's own post. The refused control takes the
+ * focus; a control the card does not draw (a brand's extra) is marked
+ * `aria-invalid` and pointed at the message above the submit. Fixing that
+ * control clears it.
+ */
+export function useLeadError(root, id) {
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        const url = new URL(window.location.href);
+        const field = url.searchParams.get(LEAD_ERROR_PARAM);
+        const channel = url.hash === `#${id}` ? "form" : url.hash === `#${id}-callback` ? "callback" : null;
+        if (field === null || channel === null)
+            return;
+        url.searchParams.delete(LEAD_ERROR_PARAM);
+        window.history.replaceState(window.history.state, "", url);
+        if (FIELD.test(field))
+            setError({ channel, field });
+    }, [id]);
+    useEffect(() => {
+        const form = error && root.current?.querySelector(`#${CSS.escape(error.channel === "callback" ? `${id}-callback-form` : `${id}-form`)}`);
+        if (!error || !form)
+            return;
+        const details = form.closest("details");
+        if (details)
+            details.open = true;
+        const control = controlOf(form, error.field);
+        const foreign = control && !OWN_FIELDS[error.channel].includes(error.field) ? control : null;
+        foreign?.setAttribute("aria-invalid", "true");
+        foreign?.setAttribute("aria-describedby", formMessageId(id, error.channel));
+        (control ?? document.getElementById(formMessageId(id, error.channel)))?.focus();
+        const fixed = (event) => {
+            if (error.field === "form" || (event.target instanceof Element && control?.contains(event.target)))
+                setError(null);
+        };
+        form.addEventListener("input", fixed);
+        form.addEventListener("change", fixed);
+        return () => {
+            form.removeEventListener("input", fixed);
+            form.removeEventListener("change", fixed);
+            foreign?.removeAttribute("aria-invalid");
+            foreign?.removeAttribute("aria-describedby");
+        };
+    }, [error, id, root]);
+    return [error, setError];
+}

package/dist/react/use-lead-events.d.ts

@@ -4,7 +4,10 @@ import { type LeadField, type LeadStep } from "../core/analytics.js";
 export declare const FIELD_ATTR = "data-lead-field";
 export interface LeadEvents {
     step(step: LeadStep): void;
+    /** A hint under a field (`blocking: false`); the browser's refusal is counted by itself (`blocking: true`). */
     fieldError(field: LeadField): void;
+    /** The script's post got no answer: `network` or `timeout`, and which form. */
+    submitError(reason: "network" | "timeout", channel: "form" | "callback"): void;
 }
 /**
  * The lead form's own funnel, reported through the boundary's sink: seen

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

@@ -45,7 +45,7 @@ export function useLeadEvents(root, tags) {
         const invalid = (event) => {
             const field = event.target instanceof Element ? event.target.getAttribute(FIELD_ATTR) : null;
             if (field)
-                sink.capture(EVENTS.fieldError, { ...props, field });
+                sink.capture(EVENTS.fieldError, { ...props, field, blocking: true });
         };
         el.addEventListener("focusin", focus);
         el.addEventListener("invalid", invalid, true);
@@ -57,6 +57,7 @@ export function useLeadEvents(root, tags) {
     }, [sink, root, props]);
     return useMemo(() => ({
         step: step => sink?.capture(EVENTS.formStep, { ...props, step }),
-        fieldError: field => sink?.capture(EVENTS.fieldError, { ...props, field }),
+        fieldError: field => sink?.capture(EVENTS.fieldError, { ...props, field, blocking: false }),
+        submitError: (reason, channel) => sink?.capture(EVENTS.submitError, { ...props, reason, channel }),
     }), [sink, props]);
 }

package/dist/react/use-lead-submit.d.ts

@@ -1,21 +1,56 @@
 import { type FormEventHandler } from "react";
+import { type LeadChannel } from "../core/lead.js";
 /** What the visitor just sent, for a brand's in-card success ("we call 06 … back"). */
 export interface LeadSent {
-    channel: "form" | "callback";
+    channel: LeadChannel;
     /** As typed. */
     phone: string;
     /** The name field's value, when the form has one and it was filled. */
     name: string | null;
 }
+/** Leaving the page, behind a seam a test can stand in for (jsdom cannot navigate). */
+export declare const navigation: {
+    assign: (url: string) => void;
+};
 /**
- * The lead posted by a script, so the card can say "done" in place. The body
- * and the endpoint are the form's own, and the server answers it as it answers
- * the plain post: a 303 to the thanks page means the lead was taken. Anything
- * else — a refusal, the store's 500, no network — submits the form for real,
- * so the server's own page says what went wrong. Off (`undefined` handler)
- * when the brand gave no in-card success: the 303 to `/thanks` stays the path.
+ * A v4 UUID. `randomUUID` exists only in a secure context; a LAN dev server
+ * over plain http is not one, but `getRandomValues` works everywhere.
  */
-export declare function useLeadSubmit(enabled: boolean, fields: {
+export declare function newSubmissionId(): string;
+/** Why the script's post got no answer: none came back (`network`), or none in time (`timeout`). */
+export type SendFailure = "network" | "timeout";
+/** How long the script waits for `/quote` before it says so; the lead is a few short fields. */
+export declare const SUBMIT_TIMEOUT_MS = 15000;
+export interface LeadSubmitHandlers {
+    /** The route refused the lead: the field to fix. */
+    onRefused: (channel: LeadChannel, field: string) => void;
+    /** No answer: the form stays as typed, with a retry. */
+    onFailed: (channel: LeadChannel, failure: SendFailure) => void;
+}
+export interface LeadSubmit {
+    sent: LeadSent | null;
+    onSubmit: FormEventHandler<HTMLFormElement>;
+    /** The form being posted, while it is. */
+    busy: LeadChannel | null;
+    /** The last post that got no answer, until the next one. */
+    failure: {
+        channel: LeadChannel;
+        failure: SendFailure;
+    } | null;
+    /** Posts that form again — the same submission id, so never a second lead. */
+    retry: () => void;
+}
+/**
+ * The lead posted by a script, so a refusal keeps what was typed: the body
+ * and the endpoint are the form's own, asked for JSON. Taken → the brand's
+ * in-card success when it has one (`done`), else the thanks page the route
+ * names. Refused → `onRefused` with the field, the form as it was. No answer
+ * — no network, or nothing in `SUBMIT_TIMEOUT_MS` — is said in place with a
+ * retry, never by leaving the page: the browser's error page would lose the
+ * form. Any other answer (the store's 500) submits the form for real, so the
+ * server's own page says what went wrong; the submission id makes that safe.
+ */
+export declare function useLeadSubmit(done: boolean, fields: {
     mobile: string;
     name: string | undefined;
-}): [LeadSent | null, FormEventHandler<HTMLFormElement> | undefined];
+}, on: LeadSubmitHandlers): LeadSubmit;

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

@@ -1,26 +1,103 @@
 "use client";
 import { useRef, useState } from "react";
-import { CHANNEL_FIELD } from "../core/lead.js";
+import { CHANNEL_FIELD, SUBMISSION_FIELD } from "../core/lead.js";
 import { THANKS } from "../core/routing.js";
+/** Leaving the page, behind a seam a test can stand in for (jsdom cannot navigate). */
+export const navigation = { assign: (url) => window.location.assign(url) };
 /**
- * The lead posted by a script, so the card can say "done" in place. The body
- * and the endpoint are the form's own, and the server answers it as it answers
- * the plain post: a 303 to the thanks page means the lead was taken. Anything
- * else — a refusal, the store's 500, no network — submits the form for real,
- * so the server's own page says what went wrong. Off (`undefined` handler)
- * when the brand gave no in-card success: the 303 to `/thanks` stays the path.
+ * A v4 UUID. `randomUUID` exists only in a secure context; a LAN dev server
+ * over plain http is not one, but `getRandomValues` works everywhere.
  */
-export function useLeadSubmit(enabled, fields) {
+export function newSubmissionId() {
+    if (typeof crypto.randomUUID === "function")
+        return crypto.randomUUID();
+    const b = crypto.getRandomValues(new Uint8Array(16));
+    b[6] = ((b[6] ?? 0) & 0x0f) | 0x40;
+    b[8] = ((b[8] ?? 0) & 0x3f) | 0x80;
+    const hex = [...b].map(x => x.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * The ids this page minted, by form, with what each was minted for. Kept in
+ * memory, not read back from the field: a browser restores a hidden field's
+ * value on Back, and a new lead would go out under an old one's id.
+ */
+const minted = new WeakMap();
+/**
+ * The form's submission id, written into its field: the same for a resend of
+ * the same lead, a new one as soon as anything posted differs — a number
+ * fixed after a timeout is another lead, which must not be answered with the
+ * first one's row.
+ */
+function stamp(form) {
+    const field = form.elements.namedItem(SUBMISSION_FIELD);
+    if (!(field instanceof HTMLInputElement))
+        return;
+    const posted = new FormData(form);
+    posted.delete(SUBMISSION_FIELD);
+    const lead = new URLSearchParams([...posted].filter((e) => typeof e[1] === "string")).toString();
+    const known = minted.get(form);
+    const id = known && known.lead === lead ? known.id : newSubmissionId();
+    minted.set(form, { id, lead });
+    field.value = id;
+}
+/** A root-relative path on this origin — never `//elsewhere`. */
+const OWN_PATH = /^\/(?!\/)/;
+/**
+ * The route's answer to a script (`quoteRoute`): JSON when it asked for it,
+ * or — through a proxy that rewrote nothing but followed the 303 — the
+ * thanks page itself. Anything else is not an answer: `null`.
+ */
+async function readAnswer(res) {
+    if ((res.ok || res.status === 422) && (res.headers.get("content-type") ?? "").includes("application/json")) {
+        // Not JSON is no answer; a body cut off (the network, the timeout) is no answer either — thrown on.
+        const body = await res.json().catch((error) => {
+            if (error instanceof SyntaxError)
+                return null;
+            throw error;
+        });
+        if (typeof body !== "object" || body === null)
+            return null;
+        const { ok, location, field } = body;
+        if (ok === true && typeof location === "string" && OWN_PATH.test(location))
+            return { ok, location };
+        if (ok === false && typeof field === "string")
+            return { ok, field };
+        return null;
+    }
+    if (res.ok && res.redirected) {
+        const url = new URL(res.url);
+        if (url.pathname.endsWith(THANKS))
+            return { ok: true, location: `${url.pathname}${url.search}` };
+    }
+    return null;
+}
+/** How long the script waits for `/quote` before it says so; the lead is a few short fields. */
+export const SUBMIT_TIMEOUT_MS = 15_000;
+/**
+ * The lead posted by a script, so a refusal keeps what was typed: the body
+ * and the endpoint are the form's own, asked for JSON. Taken → the brand's
+ * in-card success when it has one (`done`), else the thanks page the route
+ * names. Refused → `onRefused` with the field, the form as it was. No answer
+ * — no network, or nothing in `SUBMIT_TIMEOUT_MS` — is said in place with a
+ * retry, never by leaving the page: the browser's error page would lose the
+ * form. Any other answer (the store's 500) submits the form for real, so the
+ * server's own page says what went wrong; the submission id makes that safe.
+ */
+export function useLeadSubmit(done, fields, on) {
     const [sent, setSent] = useState(null);
+    const [busy, setBusy] = useState(null);
+    const [failure, setFailure] = useState(null);
     const pending = useRef(false);
-    if (!enabled)
-        return [sent, undefined];
+    const last = useRef(null);
     const submit = (event) => {
         event.preventDefault();
         if (pending.current)
             return;
         pending.current = true;
         const form = event.currentTarget;
+        last.current = form;
+        stamp(form);
         const data = new FormData(form);
         const body = new URLSearchParams();
         for (const [key, value] of data)
@@ -31,12 +108,44 @@ export function useLeadSubmit(enabled, fields) {
             return typeof value === "string" ? value.trim() : "";
         };
         const lead = { channel: read(CHANNEL_FIELD) === "callback" ? "callback" : "form", phone: read(fields.mobile), name: read(fields.name) || null };
+        setBusy(lead.channel);
+        setFailure(null);
+        const settle = () => {
+            pending.current = false;
+            setBusy(null);
+        };
         // `form.submit()` neither validates again nor comes back here.
         const fallBack = () => {
-            pending.current = false;
+            settle();
             form.submit();
         };
-        fetch(form.action, { method: "POST", body }).then(res => (res.ok && res.redirected && new URL(res.url).pathname.endsWith(THANKS) ? setSent(lead) : fallBack()), fallBack);
+        // A controller and a timer rather than `AbortSignal.timeout`: one clock the page (and a test) controls.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException("no answer in time", "TimeoutError")), SUBMIT_TIMEOUT_MS);
+        fetch(form.action, { method: "POST", body, headers: { Accept: "application/json" }, signal: controller.signal })
+            .then(readAnswer)
+            .then(answer => {
+            if (answer === null)
+                return fallBack();
+            if (!answer.ok) {
+                settle();
+                return on.onRefused(lead.channel, answer.field);
+            }
+            // Still pending: the page is leaving, or the form is gone. The next
+            // lead from this form (Back, another need) gets an id of its own.
+            minted.delete(form);
+            if (done)
+                setSent(lead);
+            else
+                navigation.assign(answer.location);
+        }, () => {
+            settle();
+            const kind = controller.signal.aborted ? "timeout" : "network";
+            setFailure({ channel: lead.channel, failure: kind });
+            on.onFailed(lead.channel, kind);
+        })
+            .finally(() => clearTimeout(timer));
     };
-    return [sent, submit];
+    const retry = () => last.current?.requestSubmit();
+    return { sent, onSubmit: submit, busy, failure, retry };
 }

package/dist/react/use-validity.d.ts

@@ -0,0 +1,17 @@
+import { type ChangeEvent, type FormEvent } from "react";
+/**
+ * A control's validity in the page's words. `message(el)` is what is wrong
+ * now, `""` when nothing is; it is the control's custom validity from the
+ * first render on, so the browser blocks the submit and its bubble speaks the
+ * page's language, not the browser's. `shown` is the message once the browser
+ * refused the control (`invalid`), until the visitor fixes it — for the
+ * field to show under itself and mark `aria-invalid`.
+ */
+export declare function useValidity<E extends HTMLInputElement>(message: (el: E) => string): {
+    ref: import("react").RefObject<E | null>;
+    shown: string | null;
+    onInvalid: (event: FormEvent<E>) => void;
+    onChange: (event: ChangeEvent<E>) => void;
+    /** After a value set by script, which fires no input event. */
+    recheck: (el: E) => void;
+};

package/dist/react/use-validity.js

@@ -0,0 +1,38 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A control's validity in the page's words. `message(el)` is what is wrong
+ * now, `""` when nothing is; it is the control's custom validity from the
+ * first render on, so the browser blocks the submit and its bubble speaks the
+ * page's language, not the browser's. `shown` is the message once the browser
+ * refused the control (`invalid`), until the visitor fixes it — for the
+ * field to show under itself and mark `aria-invalid`.
+ */
+export function useValidity(message) {
+    const ref = useRef(null);
+    const [shown, setShown] = useState(null);
+    const latest = useRef(message);
+    latest.current = message;
+    // Every render: the words arrive as props and may change with the locale.
+    useEffect(() => {
+        const el = ref.current;
+        if (el)
+            el.setCustomValidity(latest.current(el));
+    });
+    const recheck = (el) => {
+        const now = latest.current(el);
+        el.setCustomValidity(now);
+        if (now === "")
+            setShown(null);
+        else
+            setShown(was => (was === null ? null : now));
+    };
+    return {
+        ref,
+        shown,
+        onInvalid: (event) => setShown(latest.current(event.currentTarget) || event.currentTarget.validationMessage),
+        onChange: (event) => recheck(event.currentTarget),
+        /** After a value set by script, which fires no input event. */
+        recheck,
+    };
+}

package/dist/server/env.d.ts

@@ -35,6 +35,15 @@ export interface ServerEnv {
     } | null;
     posthogKey: string | null;
     posthogHost: string;
+    /**
+     * Leads one client address may send per window before the rest are kept
+     * as `rate-limited` (`LEAD_RATE_LIMIT`, `<count>/<seconds>`): 5 per 10 min
+     * in production; 100 outside it, where every request shares one address.
+     */
+    leadRateLimit: {
+        limit: number;
+        windowMs: number;
+    };
 }
 export type EnvSource = Readonly<Record<string, string | undefined>>;
 export declare function parseServerEnv(site: {

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

@@ -14,5 +14,5 @@ export { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE, type LeadMail, type Lea
 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 { 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

@@ -14,5 +14,5 @@ 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 { 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

@@ -50,6 +50,13 @@ 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");
+    },
 ];
 if (STEPS.length !== LEAD_SCHEMA_VERSION) {
     // The version belongs to the port, shared by every adapter; this table of
@@ -57,6 +64,29 @@ 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 stored row read back as the lead it was written from. */
+function leadOf(row) {
+    const verdict = str(row, "spam_verdict");
+    const extras = JSON.parse(str(row, "extras") ?? "{}");
+    const consentAt = str(row, "consent_at");
+    const submissionId = str(row, "submission_id");
+    return {
+        subject: str(row, "job") ?? "",
+        locality: str(row, "zip") ?? "",
+        mobile: str(row, "mobile") ?? "",
+        extras: Object.fromEntries(Object.entries(typeof extras === "object" && extras !== null ? extras : {}).filter((e) => typeof e[1] === "string")),
+        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 } : {}),
+    };
+}
 function userVersion(db) {
     return integer(db.prepare("PRAGMA user_version").get(), "user_version");
 }
@@ -138,12 +168,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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id");
+    const bySubmission = db.prepare("SELECT id, job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text, submission_id 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), "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,5 @@
 import "server-only";
-import type { Lead, LeadChannel } from "../core/lead.js";
+import { type Lead, type LeadChannel, type LeadSuspect } 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";
@@ -14,6 +14,12 @@ 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;
 }
 /**
  * What the Service-Arb panel's `lead.created` calls a callback request. Its
@@ -41,12 +47,25 @@ export interface LeadWebhook {
     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;
     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 lead webhook, or `null` when it is off: no `LEAD_WEBHOOK_URL`, or no