@evinvest/kitstart 0.8.0 → 0.10.0

package/README.md

@@ -13,8 +13,8 @@ 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`, `leadWebhook` (signed, outboxed), `sendMail`, `clientKey` |
+| `@evinvest/kitstart` | anywhere (edge, client, server) | `defineSite`, places, routing (`createRouting`), the lead schema and funnel (`createAcceptLead`), the price list (`PricingModel`, `priceOf`, `flowOf`), antispam, JSON-LD / sitemap / robots builders, analytics events, the copy contract |
+| `@evinvest/kitstart/server` | Node, `server-only` | `createServerEnv`, `createPlaceSource`, `createPricingSource`, 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.8.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.10.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -226,20 +226,23 @@ it is the plain POST to `/quote` it always was.
 | `prefer` | a channel moved first when available (a `default_channel` arm) |
 | `experiment` | `{ name, variant }`, slugs: on every event and posted with the form |
 | `timeZone` | `Europe/Paris` by default |
-| `formId`, `id` | `quote` · `quote`: the id is the card's (root), so `#quote` scrolls to the whole card, head included; the form is `<id>-form`, the callback `<id>-callback` (its form `<id>-callback-form`) |
-| `text` | `LeadCaptureText`: `LEAD_CAPTURE_TEXT.fr` / `.en`, plain strings (`{need}`, `{day}`, `{time}` filled in); optional `localityPlaceholder`, `phonePlaceholder`, `namePlaceholder` (none by default) |
+| `formId`, `id` | `quote` · `quote`: the id is the card's (root), so `#quote` scrolls to the whole card, head included; the form is `<id>-form`, the callback `<id>-callback` (its form `<id>-callback-form`). Both forms post it as `card`, so a refused lead comes back to `#<id>` |
+| `text` | `LeadCaptureText`: `LEAD_CAPTURE_TEXT.fr` / `.en`, plain strings (`{need}`, `{day}`, `{time}` filled in); optional `localityPlaceholder`, `phonePlaceholder`, `namePlaceholder` (none by default). The errors are words of the page too: `phoneInvalid`, `required`, `needRequired`, `consentRequired`, `fieldInvalid`, `formInvalid`, and the post's `sending`, `networkError`, `timeoutError`, `retry` — a brand spreading `LEAD_CAPTURE_TEXT` has them |
 | `labels` | `visible` (default) · `hidden`: every field's label `sr-only` — still the field's accessible name — for a design that draws placeholders |
 | `callbackOpen` | whether the callback starts open; by default only when it leads (the place is closed). `#<id>-callback` opens it either way |
-| `done` | the card after a lead is taken — a node, or `(sent: LeadSent) => node` (`{ channel, phone, name }`). With it a script posts the form itself and shows this in place on the thanks page's 303; any other answer, or no network, submits the form for real; without a script nothing changes (303 → `/thanks`). Without it, every submit goes to `/thanks` |
+| `done` | the card after a lead is taken — a node, or `(sent: LeadSent) => node` (`{ channel, phone, name }`), shown in place. Without it, a lead taken goes to the thanks page the route names. Either way a script posts the form itself (asking `/quote` for JSON), so a refusal keeps what was typed; an answer that is not the route's, or no network, submits the form for real; without a script nothing changes (303) |
+| `flows`, `pricing`, `photos` | how each need is sold (`site.lead.flows`), the page's price list (`createPricingSource(site).model()`), and the `quote` needs priced from photos — see [Form variants](#form-variants-quote-estimate-fixed) |
+| `booking` | after a priced lead, in place of "we call you to set the slot": a node or `(sent) => node` — a booking provider's widget, when the brand has one (none ships with the kit) |
 | `head`, `trust` | the brand's heading instead of the title; a slot beside the submit |
-| `className` · `classNames` | the root · its parts: `root`, `head`, `title`, `lede`, `form`, `contact`, `field`, `label`, `control` (every input, the need's select in both states, the callback's phone), `hint`, `chips`, `chip`, `needs`, `need`, `summary`, `submit`, `trust`, `privacy`, `opening`, `others`, `channel`, `primary`, `callback`, `callbackSummary`, `callbackForm`, `callbackLede`, `callbackSubmit`, `consent`, `done` |
+| `className` · `classNames` | the root · its parts: `root`, `head`, `title`, `lede`, `form`, `contact`, `field`, `label`, `control` (every input, the need's select in both states, the callback's phone), `hint`, `error` (a refusal: under the field, or above the submit), `chips`, `chip`, `needs`, `need`, `summary`, `submit`, `trust`, `privacy`, `opening`, `others`, `channel`, `primary`, `callback`, `callbackSummary`, `callbackForm`, `callbackLede`, `callbackSubmit`, `consent`, `done`, and for the flows `estimate`, `estimateInput`, `estimateLegend`, `estimateOption`, `price`, `priceTotal`, `breakdown`, `priceNote`, `photos`, `priced`, `pricedPrice`, `pricedNote` |
 
 - **Taps.** A need the page knows is not asked again, and a place serving one
   commune fills it: focus the phone, type, send — two taps. `qualify-first`
   with no need: the tile, which moves the focus to the first empty field (the
   phone when the commune is filled), then send.
   `single` with no need takes the first one unless changed (two more taps).
-  Enter sends.
+  Enter sends. From the keyboard the tiles are a radio group: the arrows move
+  the choice and stay in it; Enter or Space answers and moves on.
 - **Channels** (`resolveChannels`, shared with `CallBar`): call (`tel:`),
   WhatsApp and SMS (the need in the message; SMS only to a mobile), "call me
   back" and the form. Open, the call leads; closed, the callback (open) and
@@ -252,11 +255,12 @@ it is the plain POST to `/quote` it always was.
 - **Callback.** A `<details>` with its own small form: the phone and a native,
   required consent, posted to `/quote` with `channel=callback`. The consent's
   value is the sentence it shows (`text.callbackConsent`, in the page's
-  language); the server refuses a callback without it — back to the form, as
-  any invalid lead, whatever the brand's rule — and stores it with the lead:
+  language); the server refuses a callback without it — back to the callback,
+  open, naming the consent, whatever the brand's rule — and stores it with the lead:
   `consent_text` word for word, `consent_at` when the server accepted it
-  (`Lead.consent`). Then the lead is held to `lead.validateCallback` (a
-  readable number, by default), not to the form's rule. The consent goes into
+  (`Lead.consent`). Then the lead is held to `lead.validateCallback` (the
+  phone rule, by default), not to the form's rule. Its phone is the form's
+  field: the same hint, the same block. The consent goes into
   no event; a webhook body built by the brand should leave `lead.consent` out.
 - **Locality.** A postcode field (`autoComplete="postal-code"`). A storefront
   with no named zone fills in its own postcode; a named zone fills in its one
@@ -267,22 +271,122 @@ it is the plain POST to `/quote` it always was.
   `inline-flex`) with `leading-6` after the brand's `channel` /
   `callbackSummary` classes unless they set a line height of their own, so a
   brand's type size cannot leave it on a half pixel.
-- **Phone.** `type="tel"`, required, never masked. A number that does not read
-  as one gets a hint when the field is left; the server keeps it. With
+- **Phone.** `type="tel"`, required, never masked, held to one rule on both
+  sides (`phoneProblem`, `validateLead`): a French number is ten digits from
+  `0[1-9]` (or `+33` and nine), any other a `+` and 8 to 15 digits; full-width
+  digits read as digits; a run of one digit is no number. One that fails gets
+  a hint when the field is left (`aria-live`, read out) and blocks the submit
+  in the page's words — the browser's bubble would speak its own language. With
   `lead.mobileFormat: "e164"` a number it can read is stored as
   `+33612345678` (`normalizePhone`); the default keeps it as typed, which is
   what a brand's tests and tooling look rows up by.
+- **Refusals are never silent.** Every required field blocks with the page's
+  words and is marked `aria-invalid` once refused. What the server still
+  refuses (a brand's own rule, a stale page) comes back to the card: the
+  script's post gets a `422 { field }` and the form, as typed, shows the error
+  at that field (`role="alert"`, focused); the plain post gets a 303 to
+  `?lead_error=<field>&need=<need>#<id>` (`#<id>-callback` for a callback,
+  opened), which the card reads once the script runs and then drops from the
+  URL. Only slugs ride in that URL — never a phone or a name. A field the card
+  does not draw (a brand's `extras`) shows its error above the submit and is
+  marked itself.
+- **Sending.** The script's post (asking `/quote` for JSON) carries a
+  `submission_id` it mints once per lead — a new one as soon as anything
+  posted changes, and never one the browser restored; the store keeps one row
+  per id, so a resend after a lost answer is answered as the first was and
+  never makes a second lead. While it runs the form's submit is disabled, `aria-busy` and
+  says `sending`. No answer — no network, or none in 15 s
+  (`SUBMIT_TIMEOUT_MS`) — is said in place with a retry that sends the same
+  lead; the page is never left for the browser's error page.
 - **Events** (through `AnalyticsBoundary`'s sink; none outside one):
   `lead_form_view` (half in view, once), `lead_form_start` (first focus),
-  `lead_form_field_error {field}` (the browser refused it, or the phone hint
-  showed — the field's role, never its value), `lead_form_step {step}`
+  `lead_form_field_error {field, blocking}` (`blocking: true` the browser
+  refused it, `false` the phone hint showed — the field's role, never its
+  value), `lead_form_submit_error {reason, channel}` (`network` /
+  `timeout`), `lead_form_step {step}`
   (`contact` / `need`), each with `form_id`, `layout`, `experiment`,
   `variant`; `contact_intent_click {channel}` for `phone`, `whatsapp`, `sms`,
   `callback`, with the experiment; and on the server `lead_form_submit
-  {form_id, channel}` with the posted experiment.
-- **Weight.** 5.6 KB gz of first-load JS on the template's place page
-  (157,287 → 162,985 B against its 158,000 B target: +3.2 %, a warning
-  within the 20 % tolerance).
+  {form_id, channel}` and `lead_form_reject {form_id, channel, field,
+  reason}` with the posted experiment.
+- **Weight.** 8.9 KB gz of first-load JS on the template's place page
+  (157,287 → 166,361 B against its 158,000 B target: +5.3 %, a warning
+  within the 20 % tolerance); the refusals and the shared phone rule are
+  2.0 KB of it, sending (the id, the busy state, the retry) 0.6 KB.
+
+### Form variants: quote, estimate, fixed
+
+A need is sold one of three ways, chosen per need — one brand can mix them:
+
+- `quote` — the price is uncertain; the lead asks for one. The form as it was.
+- `estimate` — the price follows from a few enum answers (zone, bedrooms,
+  surface band, frequency), shown live as the visitor taps; then the slot.
+- `fixed` — one price for a well-defined job, shown as is; then the slot.
+
+```ts
+// shared/config/lead.ts — the form and the route read the same map
+export const LEAD: LeadSchema<Subject> = { …, flows: { standard: "estimate", deep: "quote" } };
+// shared/config/site.ts — the baked price list
+export const site = defineSite({ …, lead: LEAD, pricing: PRICING });
+// shared/config/env.ts — the live one, from the place source's base URL
+export const pricing = createPricingSource(site, { baseUrl: () => serverEnv().locationsApiUrl });
+// app/quote/route.ts
+export const POST = quoteRoute(site, { env: serverEnv, notifier, pricing, unavailable });
+// the page: <LeadCapture … flows={LEAD.flows} pricing={await pricing.model()} photos={["deep"]} />
+```
+
+- **The price list** (`PricingModel`) is JSON: `format` 1, `currency` `EUR`
+  (TTC), `validFrom`, `roundToCents`, `minimumCents`, `inputs` (`add` in
+  cents, `multiply` and `discount` in basis points, labels per locale) and
+  `needs` (`{ kind: "estimate", baseCents, inputs }` or `{ kind: "fixed",
+  cents }`). `priceOf(model, need, answers) → { cents, breakdown } | null`
+  is integer cents throughout, rounding half up at every product, then to
+  `roundToCents`, then the minimum. The rules and the shared fixtures the
+  panel holds its own port to are in
+  [`test/fixtures/pricing/`](./test/fixtures/pricing/README.md).
+  `defineSite` refuses a baked model that does not validate or lacks a label
+  in one of the site's locales.
+- **The live list** (`createPricingSource`): `GET <base>/pricing`, TTL
+  600 s, 3 s timeout; an unreachable source, a non-200, a body that is not
+  JSON or a model that does not validate (for every locale of the site) all
+  serve the baked model, logged — whole or not at all, never half a model.
+  `{}` is "nothing set": the baked model, quietly.
+- **A need runs its flow only when the list prices it so** (`flowOf`): an
+  `estimate` the model cannot price — no model, a remote model without the
+  need — is a `quote`. So a flow the brand has not switched on is never run
+  by a posted field.
+- **The form.** An estimate's questions are a tile per answer (touch-sized
+  radios posted as `estimate_<input>`), required once the script runs; the
+  price box (`aria-live`) shows the total and the lines that made it, or
+  what is missing — never "from". A fixed need shows its price. Either
+  submits as `bookSubmit` ("Réserver"). Without a script the answers still
+  post and the server prices them; the live price needs the script.
+- **The server prices the lead itself.** `/quote` reads the posted answers
+  for the need's inputs only and runs the same `priceOf`; a posted amount is
+  never read. The lead is stored with `flow`, `price.cents`,
+  `price.validFrom` and an estimate's `price.inputs` (schema 7: `flow`,
+  `quoted_cents`, `pricing_valid_from`, `estimate_inputs`). An estimate
+  whose answers do not price (a stale page, a forged answer) is kept as a
+  `quote` — never refused. A callback has no flow.
+- **After a priced lead** the card stays: the script's answer carries the
+  server's `cents` and the lead's reference (`lead`, `leadRef`:
+  `lead-<row>-<8 hex>`), and the card confirms the price (`sentPrice`) and
+  promises a call to set the slot (`slotCallback`) — or shows the brand's
+  `booking`. The lead is stored first, so an abandoned booking is still a
+  lead to call. A `quote` need, and any callback, behave as before.
+- **Photos.** A `quote` need listed in `photos` offers "Envoyez des photos"
+  — a WhatsApp link with the need in the message — when the place has
+  WhatsApp; the callback stays where it is.
+- **Words.** `LEAD_CAPTURE_TEXT` carries them (`priceTitle`, `pricePending`,
+  `priceNote`, `priceBase`, `priceRounding`, `priceMinimum`, `bookSubmit`,
+  `sentPrice`, `slotCallback`, `photos*`); optional in `LeadCaptureText`, so
+  a brand's own text from before them falls back to the kit's in the page's
+  language (`flowTextOf`).
+- **Events.** `lead_estimate_shown {need, cents_bucket}` once per need and
+  price band (`centsBucket`: `"7500-10000"`), never the price.
+- **Weight.** About 3.9 KB gz of first-load JS on the template's place page
+  (166,459 → 170,375 B against its 158,000 B target: +7.8 %, within the 20 %
+  tolerance).
 
 Tailwind v4 does not scan `node_modules`; the brand's `globals.css` names the
 package:
@@ -311,9 +415,9 @@ export const proxy = createProxy(site);
 // included — let past, it would be a cached bare 404 without the phone.
 export const config = { matcher: ["/((?!_next/).*)"] };
 
-// app/quote/route.ts
+// app/quote/route.ts — `anchor`: the card's id, when it is not `quote`
 export const dynamic = "force-dynamic";
-export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable });
+export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable, anchor: "devis" });
 
 // app/sitemap.ts — reads the Host header, so it is dynamic; pages are not
 export const dynamic = "force-dynamic";
@@ -324,6 +428,24 @@ export function generateStaticParams() { return []; }
 export const revalidate = 600;
 ```
 
+**The lead rule.** `site.lead.validate` defaults to `validateLead`: the
+number the form itself blocks on. A brand's own rule composes with it and
+names the field it refuses, which the form shows the error at:
+
+```ts
+validate: lead => validateLead(lead) ?? (lead.locality === "" ? { field: "locality", why: "a postcode" } : null),
+```
+
+A bare string still works — a refusal of the whole `form`. The landing
+contract (`describeLandingContract`) holds the rule to the form's phone check
+over `PHONE_MATRIX` (`leadRuleDisagreements`), so the server never refuses a
+number the form let through.
+
+**The thanks page.** A callback lands on `/thanks?channel=callback`; read it
+with `thanksChannel(searchParams)` to promise a call instead of a quote, and
+pass `{ thanks: true, channel }` to `statusTarget` so the language switch
+keeps it.
+
 `createPlaceLoader(site, places)(params)` returns the `PlaceView` for a page,
 reading the link mode from the `location` param (`_royat` = host mode).
 
@@ -352,6 +474,10 @@ chooses per visitor answer `Cache-Control: private, no-store`.
   adapter passes `describeLeadStoreContract` and migrates itself to
   `LEAD_SCHEMA_VERSION` on open. SQLite keeps the Rust server's columns
   (`job`, `zip`, `mobile`) and recognises every earlier table in place.
+  Schema 6 adds `submission_id` under a unique index (where present): one
+  row per script submission, read back by `findSubmission`. Schema 7 adds
+  the flow and the price a lead was taken at (`flow`, `quoted_cents`,
+  `pricing_valid_from`, `estimate_inputs`), all nullable.
 - **Mail is checked at boot.** With `SMTP_URL` set, `leadNotifier` throws when
   it is built if the URL is malformed (the error never repeats it), there is
   no sender (`LEAD_NOTIFY_FROM`, or `leads@<domain>`) or no recipient
@@ -408,15 +534,42 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   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.
+  `after`. A lead the notifier skips (honeypot, rate limit) is not queued —
+  unless `panelSuspect` (below) queues the rate-limited one.
+- **Suspect leads: `panelSuspect`, off.** `suspectOf(lead)` is
+  `rate_limited`, `too_fast` or nothing — never `honeypot`, whose lead goes
+  nowhere. With `leadWebhook(…, { panelSuspect: true })` a rate-limited lead
+  is queued too (still never mailed) and `ctx.suspect` names why a lead is
+  suspect, for the body's `suspect` property. Off by default, and to stay off
+  until the panel's `lead.created` accepts the property: it refuses an
+  unknown one, and the outbox would park the lead. Off, nothing changes.
+- **The sale: `panelFlow`, off.** With `leadWebhook(…, { panelFlow: true })`
+  `ctx.flow` says how the need was sold (`panelFlowOf(lead)`), and
+  `panelFlowProperties(ctx.flow)` writes it as `lead.created`'s properties:
+  `flow`; `quoted_cents` and `pricing_valid_from` together, for `estimate`
+  and `fixed` only; `estimate_inputs` (input → answer, slugs, at most 12)
+  for an `estimate` that asked anything. Off by default, and to stay off
+  until the panel accepts them — it refuses unknown properties, and the
+  outbox would park the lead. `ctx.leadRef` is the lead's reference the page
+  was answered with, whatever the switch.
+- **The rate limit** is `LEAD_RATE_LIMIT` (`<count>/<seconds>`): 5 per 10
+  minutes per address in production, 100 outside it, where every request of
+  a local stack shares one address. Outside production a lead held back as
+  rate-limited or honeypot is logged loudly.
 - **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`.
+  at least `Retry-After`), for 48 hours from queueing (`horizonMs`;
+  `maxAttempts` is an optional cap). 401, 403 and 404 retry too, logged as
+  errors naming the setting to check — a rotated key, a moved receiver. Any
+  other status, 3xx included, is final. A final row stays as `dead` with its
+  `last_error`, `onDead({ id, ref, attempts, error })` is told (an alert), and
+  `requeueDead()` — or `kitstart-outbox requeue` on the leads file (the rows
+  of `--target`, else `LEAD_WEBHOOK_URL`), with `kitstart-outbox status` to
+  count rows — puts the dead rows back, due now, their horizon fresh.
 - **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.

package/dist/cli/kitstart-outbox.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/kitstart-outbox.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// kitstart-outbox <status | requeue> [--db <leads.db>] — see `outbox.ts`.
+import { runOutboxCli } from "./outbox.js";
+try {
+    process.exitCode = runOutboxCli(process.argv.slice(2), process.env, line => console.log(line));
+}
+catch (error) {
+    console.error(`✘ ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/cli/outbox.d.ts

@@ -0,0 +1,5 @@
+export declare const USAGE = "kitstart-outbox <status | requeue> [--db <leads.db>]\n\n  status    rows of webhook_outbox by state and target\n  requeue   dead rows back to pending, due now, their tries and horizon fresh \u2014\n            only the receiver's of --target, else LEAD_WEBHOOK_URL; all\n            without either (a running site sends only its own target's)\n\nThe file is --db, else LEADS_DB_URL (sqlite:///<path>), else LEADS_DB_PATH.";
+type Env = Readonly<Record<string, string | undefined>>;
+/** Runs the command; answers the exit code. `print` takes each line of output. */
+export declare function runOutboxCli(args: readonly string[], env: Env, print: (line: string) => void, now?: number): number;
+export {};

package/dist/cli/outbox.js

@@ -0,0 +1,77 @@
+// kitstart-outbox — the webhook outbox from a shell, on the leads file itself.
+// Plain node and its builtins only, like every bin here: the server layer
+// imports `server-only`, which throws outside Next, so the two statements
+// below repeat what `requeueDead()` and `rows()` do in
+// `server/webhook-outbox.ts`; a test runs both on one file.
+import { existsSync } from "node:fs";
+export const USAGE = `kitstart-outbox <status | requeue> [--db <leads.db>]
+
+  status    rows of webhook_outbox by state and target
+  requeue   dead rows back to pending, due now, their tries and horizon fresh —
+            only the receiver's of --target, else LEAD_WEBHOOK_URL; all
+            without either (a running site sends only its own target's)
+
+The file is --db, else LEADS_DB_URL (sqlite:///<path>), else LEADS_DB_PATH.`;
+function leadsFile(args, env) {
+    const at = args.indexOf("--db");
+    if (at !== -1)
+        return args[at + 1] ?? null;
+    const url = env["LEADS_DB_URL"]?.trim();
+    if (url) {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "sqlite:" || parsed.host !== "")
+            throw new Error("LEADS_DB_URL is not sqlite:///<absolute path>");
+        return decodeURIComponent(parsed.pathname);
+    }
+    return env["LEADS_DB_PATH"]?.trim() || null;
+}
+function open(path) {
+    const sqlite = process.getBuiltinModule("node:sqlite");
+    if (!sqlite)
+        throw new Error("node:sqlite is unavailable — Node ≥ 22.13 is required");
+    const db = new sqlite.DatabaseSync(path);
+    db.exec("PRAGMA busy_timeout = 5000");
+    return db;
+}
+/** Runs the command; answers the exit code. `print` takes each line of output. */
+export function runOutboxCli(args, env, print, now = Date.now()) {
+    const [command] = args;
+    if (command !== "status" && command !== "requeue") {
+        print(USAGE);
+        return 2;
+    }
+    const path = leadsFile(args, env);
+    if (!path) {
+        print(`no leads file: pass --db, or set LEADS_DB_URL or LEADS_DB_PATH\n\n${USAGE}`);
+        return 2;
+    }
+    // Opening a path that is not there would create an empty file there.
+    if (!existsSync(path)) {
+        print(`no leads file at ${path}`);
+        return 2;
+    }
+    const db = open(path);
+    try {
+        if (command === "requeue") {
+            const at = args.indexOf("--target");
+            const raw = at !== -1 ? args[at + 1] : env["LEAD_WEBHOOK_URL"]?.trim();
+            // Spelt as the server stores it (`checkWebhookUrl`), or nothing would match.
+            const target = raw ? new URL(raw).toString() : null;
+            const sql = "UPDATE webhook_outbox SET state = 'pending', attempts = 0, created_at = ?, next_attempt_at = ?, done_at = NULL WHERE state = 'dead'";
+            const done = target === null ? db.prepare(sql).run(now, now) : db.prepare(`${sql} AND target = ?`).run(now, now, target);
+            print(target === null
+                ? `requeued ${Number(done.changes)} dead row(s) of every target; a running site sends those of its own LEAD_WEBHOOK_URL on its next tick`
+                : `requeued ${Number(done.changes)} dead row(s) for ${target}; the running site sends them on its next tick`);
+            return 0;
+        }
+        const rows = db.prepare("SELECT state, target, COUNT(*) AS n FROM webhook_outbox GROUP BY state, target ORDER BY state, target").all();
+        if (rows.length === 0)
+            print("the outbox is empty");
+        for (const row of rows)
+            print(`${String(Reflect.get(row, "state")).padEnd(10)}${String(Reflect.get(row, "n")).padStart(6)}  ${String(Reflect.get(row, "target"))}`);
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/core/accept.d.ts

@@ -1,5 +1,6 @@
 import { type RateLimiter } from "./antispam.js";
-import { type Lead } from "./lead.js";
+import { type Lead, type LeadChannel } from "./lead.js";
+import type { PricingModel } from "./pricing/model.js";
 import type { Site } from "./site.js";
 /** Hidden fields the form carries besides what the visitor types. */
 export declare const LOCATION_FIELD = "location";
@@ -13,15 +14,27 @@ export interface SubmitTags {
     experiment?: string;
     variant?: string;
 }
-export type Outcome<L extends string> = {
+export type Outcome<L extends string> = 
+/**
+ * `ref`: the lead's public reference (`leadRef`). `duplicate`: a resend of
+ * a submission already stored — answered as the first was, nothing sent again.
+ */
+{
     kind: "stored";
     id: number;
+    ref: string;
     lead: Lead;
     locale: L;
     formId: string;
-} | {
+    duplicate?: true;
+}
+/** `field` names what to fix (`phone`, `consent`, … or `form`); `why` is for the log. */
+ | {
     kind: "invalid";
     why: string;
+    field: string;
+    channel: LeadChannel;
+    formId: string;
     locale: L;
     slug: string | null;
 } | {
@@ -32,6 +45,11 @@ export type Outcome<L extends string> = {
 export interface AcceptDeps {
     /** The commit point: resolves once the lead is durable. */
     insert: (lead: Lead) => Promise<number>;
+    /** The lead a submission id was stored as (`LeadStore.findSubmission`); absent → no deduplication. */
+    findSubmission?: (submissionId: string) => Promise<{
+        id: number;
+        lead: Lead;
+    } | null>;
     /** Runs after the response is sent; see the route handler. */
     defer: (task: () => Promise<void> | void) => void;
     notify: (lead: Lead, id: number) => Promise<void>;
@@ -43,12 +61,35 @@ export interface AcceptDeps {
     enqueue?: (lead: Lead, id: number, meta: {
         locale: string;
         formId: string;
+        leadRef: string;
     }) => void;
+    /**
+     * The price list to price an `estimate` or `fixed` lead with
+     * (`createPricingSource(…).model`); absent → `site.pricing`. A failure is
+     * no model: the lead is kept as a `quote`, never refused.
+     */
+    pricing?: () => Promise<PricingModel | null>;
+    /**
+     * Queue a rate-limited lead too, for the panel to show as suspect
+     * (`LeadWebhookOptions.panelSuspect`). Off: it waits in the table, as before.
+     * It is never mailed; a honeypot lead is never sent anywhere.
+     */
+    sendSuspect?: boolean;
     capture: (lead: Lead, formId: string, tags: SubmitTags) => void;
     limiter: RateLimiter;
     now: number;
     log: Pick<Console, "warn" | "error">;
 }
+/**
+ * The lead's public reference, `lead-<row>-<8 hex>`: the one the script's
+ * answer gives the page (`LeadSent.lead`) and the webhook offers the panel
+ * (`LeadWebhookContext.leadRef`), so whatever the page does next — a booking,
+ * once there is a provider — can name its lead. The
+ * row id for a person matching it to the mail; the tag because row ids start
+ * over if the leads file is ever recreated. Seeded by the submission id when
+ * there is one, so a resend is answered with the same reference.
+ */
+export declare function leadRef(id: number, seed: string): string;
 /**
  * The funnel's commit point, independent of HTTP. Order is the invariant:
  * validate → screen → **insert** → (deferred) notify and capture.

package/dist/core/accept.js

@@ -1,6 +1,8 @@
 import { experimentProps } from "./analytics.js";
 import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELDS, RENDERED_AT_FIELD, screen } from "./antispam.js";
-import { MAX_FIELD, readCandidate, validateCandidate } from "./lead.js";
+import { channelOf, MAX_FIELD, readCandidate, validateCandidate } from "./lead.js";
+import { flowOf, readEstimateInputs } from "./pricing/flow.js";
+import { priceOf } from "./pricing/price.js";
 /** Hidden fields the form carries besides what the visitor types. */
 export const LOCATION_FIELD = "location";
 export const LOCALE_FIELD = "locale";
@@ -13,6 +15,55 @@ function field(form, name) {
     const value = form.get(name);
     return typeof value === "string" ? value.trim().slice(0, MAX_FIELD) : null;
 }
+/** FNV-1a, 32 bits, as 8 hex: a tag, not a secret — the core has no `node:crypto`. */
+function tag(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++)
+        h = Math.imul(h ^ seed.charCodeAt(i), 0x01000193);
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * The lead's public reference, `lead-<row>-<8 hex>`: the one the script's
+ * answer gives the page (`LeadSent.lead`) and the webhook offers the panel
+ * (`LeadWebhookContext.leadRef`), so whatever the page does next — a booking,
+ * once there is a provider — can name its lead. The
+ * row id for a person matching it to the mail; the tag because row ids start
+ * over if the leads file is ever recreated. Seeded by the submission id when
+ * there is one, so a resend is answered with the same reference.
+ */
+export function leadRef(id, seed) {
+    return `lead-${id}-${tag(seed)}`;
+}
+/**
+ * How the lead's need is sold and at what price — the server's own number,
+ * from the posted answers through the same `priceOf` the form showed; a
+ * posted amount is never read. A callback asks for a call, not a price: no
+ * flow. An estimate whose answers do not price (a stale form, a tampered
+ * field) is kept as a `quote`: the customer is still a customer.
+ */
+async function priced(site, form, lead, deps) {
+    const flows = site.lead.flows;
+    if (!flows || channelOf(lead) === "callback")
+        return {};
+    let model;
+    try {
+        model = deps.pricing ? await deps.pricing() : (site.pricing ?? null);
+    }
+    catch (error) {
+        deps.log.error("quote: the price list could not be read; the lead is kept as a quote", error);
+        model = null;
+    }
+    const flow = flowOf(flows, model, lead.subject);
+    if (flow === "quote" || !model)
+        return { flow: "quote" };
+    const inputs = flow === "estimate" ? readEstimateInputs(model, lead.subject, name => field(form, name)) : {};
+    const price = priceOf(model, lead.subject, inputs);
+    if (!price) {
+        deps.log.warn(`quote: an ${flow} for ${lead.subject} did not price from what was posted; kept as a quote`);
+        return { flow: "quote" };
+    }
+    return { flow, price: { cents: price.cents, validFrom: model.validFrom, ...(flow === "estimate" ? { inputs } : {}) } };
+}
 /**
  * The funnel's commit point, independent of HTTP. Order is the invariant:
  * validate → screen → **insert** → (deferred) notify and capture.
@@ -30,17 +81,38 @@ function field(form, name) {
 export function createAcceptLead(site) {
     return (form, clientKey, deps) => accept(site, form, clientKey, deps);
 }
+/** The stored lead for a submission id; a failed lookup is no lookup — the insert's index still holds. */
+async function stored(submissionId, deps) {
+    if (!submissionId || !deps.findSubmission)
+        return null;
+    try {
+        return await deps.findSubmission(submissionId);
+    }
+    catch (error) {
+        deps.log.error("quote: the lookup of a resent submission failed", error);
+        return null;
+    }
+}
 async function accept(site, form, clientKey, deps) {
     const rawSlug = field(form, LOCATION_FIELD);
     const slug = rawSlug && site.placeSlugs.includes(rawSlug) ? rawSlug : null;
     const rawLocale = field(form, LOCALE_FIELD);
     const locale = site.i18n.isLocale(rawLocale) ? rawLocale : site.i18n.defaultLocale;
+    // It reaches analytics as a property; anything but a short slug is dropped.
+    const posted = field(form, FORM_ID_FIELD);
+    const formId = posted !== null && FORM_ID.test(posted) ? posted : "quote";
     const candidate = readCandidate(site.lead, form, slug);
-    const why = validateCandidate(site.lead, candidate);
-    if (why) {
-        deps.log.warn(`quote: rejected a submission for ${slug ?? "no point"}: missing ${why}`);
-        return { kind: "invalid", why, locale, slug };
+    const rejection = validateCandidate(site.lead, candidate);
+    if (rejection) {
+        deps.log.warn(`quote: rejected a submission for ${slug ?? "no point"} at ${rejection.field}: missing ${rejection.why}`);
+        return { kind: "invalid", why: rejection.why, field: rejection.field, channel: channelOf(candidate), formId, locale, slug };
     }
+    // A resend of a stored submission (its answer was lost) is that lead: no
+    // second row, no second mail, the limit not spent again.
+    const prior = await stored(candidate.submissionId, deps);
+    if (prior)
+        return { kind: "stored", id: prior.id, ref: leadRef(prior.id, candidate.submissionId ?? ""), lead: prior.lead, locale, formId, duplicate: true };
+    const sale = await priced(site, form, candidate, deps);
     // After validation, so a typo corrected and resent does not spend the limit.
     const verdict = screen({
         honeypot: [HONEYPOT_FIELD, ...LEGACY_HONEYPOT_FIELDS].map(name => field(form, name)).find(v => v) ?? null,
@@ -52,6 +124,7 @@ async function accept(site, form, clientKey, deps) {
     const { consentText, ...rest } = candidate;
     const lead = {
         ...rest,
+        ...sale,
         spamVerdict: verdict === "ok" ? null : verdict,
         // Stamped by the server: the moment it accepted the consent with the lead.
         ...(consentText ? { consent: { text: consentText, at: new Date(deps.now).toISOString() } } : {}),
@@ -61,28 +134,36 @@ async function accept(site, form, clientKey, deps) {
         id = await deps.insert(lead);
     }
     catch (error) {
+        // Two posts of one submission raced past the lookup; the unique index let one in.
+        const winner = await stored(candidate.submissionId, deps);
+        if (winner)
+            return { kind: "stored", id: winner.id, ref: leadRef(winner.id, candidate.submissionId ?? ""), lead: winner.lead, locale, formId, duplicate: true };
         deps.log.error(`quote: the lead store rejected a submission for ${slug ?? "no point"}`, error);
         return { kind: "failed", locale, slug };
     }
-    // It reaches analytics as a property; anything but a short slug is dropped.
-    const posted = field(form, FORM_ID_FIELD);
-    const formId = posted !== null && FORM_ID.test(posted) ? posted : "quote";
+    const ref = leadRef(id, candidate.submissionId ?? `${id}:${deps.now}`);
     // The render stamp comes from the client, so it only marks: a `too-fast`
     // lead (or one from a page cached before the stamp existed) is still sent
     // on, flagged. The honeypot and the rate limit are the server's own
     // evidence, and those leads wait in the table for a reviewer.
-    if (lead.spamVerdict && lead.spamVerdict !== "too-fast") {
-        deps.log.warn(`quote: lead ${id} stored as suspected spam (${lead.spamVerdict}); not notified`);
-        return { kind: "stored", id, lead, locale, formId };
-    }
-    if (deps.enqueue) {
+    const queue = () => {
+        if (!deps.enqueue)
+            return;
         try {
-            deps.enqueue(lead, id, { locale, formId });
+            deps.enqueue(lead, id, { locale, formId, leadRef: ref });
         }
         catch (error) {
             deps.log.error(`quote: lead ${id} is stored but could not be queued for its webhook`, error);
         }
+    };
+    if (lead.spamVerdict && lead.spamVerdict !== "too-fast") {
+        const marked = lead.spamVerdict === "rate-limited" && deps.sendSuspect === true;
+        deps.log.warn(`quote: lead ${id} stored as suspected spam (${lead.spamVerdict}); not notified${marked ? ", queued marked suspect" : ""}`);
+        if (marked)
+            queue();
+        return { kind: "stored", id, ref, lead, locale, formId };
     }
+    queue();
     deps.defer(async () => {
         try {
             await deps.notify(lead, id);
@@ -93,5 +174,5 @@ async function accept(site, form, clientKey, deps) {
     });
     const tags = experimentProps(field(form, EXPERIMENT_FIELD), field(form, VARIANT_FIELD));
     deps.defer(() => deps.capture(lead, formId, tags));
-    return { kind: "stored", id, lead, locale, formId };
+    return { kind: "stored", id, ref, lead, locale, formId };
 }