@evinvest/kitstart 0.9.0 → 0.11.0

package/README.md

@@ -13,12 +13,12 @@ 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` | Next server (routes, RSC) | `quoteRoute`, `bookingRoute`, `confirmRoute`, `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 |
-| `@evinvest/kitstart/react` | either side | `LangSwitch`, `CallBar`, `StatusScreen`, `PlaceDirectory`, `AreaChips`, `Coverage`, `MapFacade` (client), `QuoteFormShell`, `FormSelect` (client), `LeadCapture` (client), `Faq`, `AnalyticsBoundary` (client), plus the kit and marketing pieces a landing composes with |
+| `@evinvest/kitstart/react` | either side | `LangSwitch`, `CallBar`, `StatusScreen`, `PlaceDirectory`, `AreaChips`, `Coverage`, `MapFacade` (client), `QuoteFormShell`, `FormSelect` (client), `LeadCapture` (client), `LeadBooking` (client) and its adapters, `Faq`, `AnalyticsBoundary` (client), plus the kit and marketing pieces a landing composes with |
 | `@evinvest/kitstart/testing` | a brand's vitest | `describeLandingContract(site, { globalsCss, proxySource, text })`, `describeLeadStoreContract(name, harness)`, `storefrontPlace`, `serviceAreaPlace`, `testLead` |
 | `@evinvest/kitstart/testing/e2e` | a brand's Playwright | `defineSectionSuite(sections)`, `settle(page, selector)`, `BREAKPOINTS` |
 | bin `kitstart-size` | plain node | `kitstart-size [<build root>] [--route …] [--budget …]`: first-load JS of a place page against the target in `tests/bundle_budget.txt` (passes with a warning up to its tolerance, 20 % by default — see [The bundle budget](#the-bundle-budget)); fails closed |
@@ -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.9.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.11.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -231,8 +231,12 @@ it is the plain POST to `/quote` it always was.
 | `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 }`), 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) |
-| `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`, `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` |
+| `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 the place's booking (`LeadBooking`, from `place.booking`): a node or `(sent) => node` |
+| `bookingVariant` · `bookingEmbed` · `bookingAdapters` | the `booking_provider` variant that picks the place's provider · the providers' embeds (after cookie consent) rather than a new tab · the brand's adapters over the built-ins (from a client component) — see [Booking](#booking-manual-link-google_calendar-cal_com) |
+| `initialError` | `leadErrorOf(searchParams)` on a page that reads its query: the refusal a 303 brought back, drawn on the server by the card it names (`lead_card`) so the card says why without a script (see *Refusals*) |
+| `head`, `trust` | the brand's heading instead of the title; a slot beside the submit. Like `extras`, `done` and `booking`, any node, built on the server or not, and never asked for a `key`: each slot sits alone in a keyed fragment |
+| `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`, and for the booking `booking`, `bookingCta`, `bookingNote`, `prefer`, `preferOption`, `preferSubmit` |
 
 - **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`
@@ -271,21 +275,37 @@ it is the plain POST to `/quote` it always was.
   brand's type size cannot leave it on a half pixel.
 - **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
+  `0[1-9]` (or `+33` and nine), any other a `+` and 8 to 15 digits — and for
+  the plans visitors most often dial from, that plan's national length after
+  the code: `+1` ten, `+44` nine or ten, `+34` and `+41` nine, `+32` eight or
+  nine, `+49` 7 to 13, `+39` 6 to 11 (so `+12345678` is no number); 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
+  a hint when the field is left (`aria-live`, read out; when a tap left it,
+  only once the tap is over, so nothing moves under the finger) 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.
+- **Field messages.** Under each field, a live region (`aria-live`) always
+  in the DOM, so a message appearing in it is read out. Empty, it is out of
+  the field's flex flow (`empty:absolute`, never `hidden`): it takes no gap,
+  so a brand's `classNames.field` may set any gap with no override for it.
 - **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,
+  `?lead_error=<field>&need=<need>&lead_card=<id>#<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
+  URL. Only slugs ride in that URL — never a phone or a name. Without a
+  script that text is the page's to draw: a page that reads its query passes
+  `initialError={leadErrorOf(await searchParams)}` and the server renders it
+  in the card the 303 named (`lead_card=<id>` or `<id>-callback`, beside the
+  fragment the server never sees): only that card draws it, at its form or
+  its callback (opened). A URL from before `lead_card` is drawn by every card
+  as it reads — the consent at the callback, anything else at the form. A page built for ISR
+  reads no query, so without a script it lands on the card with the field
+  marked by nothing — the limit of a cached page. 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
@@ -312,6 +332,169 @@ it is the plain POST to `/quote` it always was.
   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.
+- **The price shown is the price recorded.** The form also posts the price
+  it showed, `shown_cents` (`SHOWN_CENTS_FIELD`) — compared, never stored.
+  When the server's price differs (the panel changed the list under an open
+  page), the lead is not taken: a script gets `422 { ok: false, field:
+  "price_changed", reason: "price_changed", cents }`, and the card shows the
+  fresh price in place of the old one with `priceChanged` ("Le prix a
+  changé : 86 € au lieu de 77 €"); the next submit posts it and is taken. A
+  plain post goes to `/quote/confirm` (`confirmRoute`) — never back to its
+  card, whose page may be a cached render still showing the old price, so
+  every resubmit would be refused again. The confirmation is never cached:
+  it prices the answers afresh, says the price changed, and asks again for
+  the phone and the postcode — the URL carries only the need, the answers,
+  the page's ids and the price seen, nothing typed (a brand's extra fields
+  are not carried). Its form posts the fresh `shown_cents` and is taken. A
+  page cached before the field posts none and is taken as before; so does an
+  estimate posted without a script, whose page could not show a price. Counted as `lead_form_reject
+  {reason: "price_changed"}`.
+- **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
+  offers the place's booking (below) — or shows the brand's own `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`, `priceChanged*`, `slotCallback`, `book*` (`bookPhoneHint` too), `booked`,
+  `prefer*`, `part*`, `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;
+  `lead_booking_open {provider}` and `lead_booking_done {provider}` (below).
+- **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).
+
+### Booking: `manual`, `link`, `google_calendar`, `cal_com`
+
+How a priced lead's slot is set, per place, provider-agnostic. The default is
+`manual` — a call. A place may also have pages on `link`, `google_calendar`
+and `cal_com`, and the `booking_provider` experiment picks among them; the
+first A/B is `google_calendar` against `manual`. `calendly` is the next
+adapter, on the same seams.
+
+```ts
+// shared/config/places.ts — baked, optional; the panel's place settings override it (`PlaceLive.booking`)
+{ slug: "paris", …, booking: { default: "manual", providers: { google_calendar: { url: "https://calendar.app.google/…" } } } }
+// shared/config/site.ts — the Cal.com hosts a place may book on (default ["cal.evinvest.ltd", "cal.com"])
+export const site = defineSite({ …, booking: { calComHosts: ["cal.com", "cal.brand.fr"] } });
+// the page: the experiment's variant picks the provider among the place's
+<LeadCapture … bookingVariant={assignment(BOOKING_EXPERIMENT)} />
+// app/quote/booking/route.ts
+export const dynamic = "force-dynamic";
+export const POST = bookingRoute({ env: serverEnv, webhook });
+```
+
+- **The config** (`BookingConfig`): `{ default, providers: { <provider>: { url } } }`.
+  `manual` has no page and is always available: the card promises a call and
+  offers an optional preference — a day of the coming week and a part of the
+  day (`morning | afternoon | evening`), no free text. `link` — any booking
+  page, opened with `ref=<leadRef>`. `google_calendar` — a schedule on
+  `calendar.app.google` or `calendar.google.com/calendar/appointments/…`,
+  opened as is: it takes no parameter, so the card asks the visitor to type
+  the same phone there (`bookPhoneHint`) and the panel matches by contact and
+  time. `cal_com` — `https://<allowed host>/<user>/<event>`, opened with
+  `name`, `attendeePhoneNumber` (E.164) and `metadata[ref]=<leadRef>`.
+  `default` is `manual` or one of `providers`; a place with no booking is
+  `manual` (`DEFAULT_BOOKING`). A ref always rides in the query, never the
+  fragment. `bookingConfigProblems` holds the strict URL rules; the panel
+  mirrors them from [`test/fixtures/booking/`](./test/fixtures/booking/README.md).
+  `defineSite` refuses a baked booking or host list that does not validate;
+  a live one that does not is dropped and the baked one kept.
+- **The choice: one entry point.** `bookingOf(place, variant)` answers the
+  provider the `booking_provider` variant (`BOOKING_EXPERIMENT`, the same key
+  on every brand) names, when the place has it (`manual` always), else the
+  place's `default`. `LeadCapture` calls it with `bookingVariant`. The chosen
+  provider is what `booking.requested@1` and `lead_booking_open` /
+  `lead_booking_done {provider}` carry, so the arms compare.
+- **Nothing third-party before the click.** Every provider with a page is a
+  plain link the browser opens in a new tab. `bookingEmbed` on `LeadCapture`
+  (`BOOKING_EMBEDS`: Cal.com's modal, `calComEmbedAdapter`) opens it on the
+  page instead — only once the visitor accepted the provider's cookies: its
+  script loads on the click, and its `bookingSuccessful` is `onBooked` (once
+  per lead, however often the modal opens), the one way the page learns a
+  slot was taken (`lead_booking_done`). In an A/B
+  test both arms must open the same way, or it measures the opening.
+- **Adapters** (`BookingAdapter = { provider, href?, open?, prefillsPhone? }`),
+  picked by the chosen provider: `manualAdapter`, `linkAdapter`,
+  `googleCalendarAdapter`, `calComAdapter`; `bookingAdapters` on
+  `LeadCapture` registers a brand's own by provider name (from a client
+  component — a server one cannot pass functions). A provider no adapter
+  knows promises the call.
+- **`booking.requested@1`.** Opening a provider's page, or sending a
+  `manual` preference, posts `{ submission, lead_ref, provider,
+  preferred_date?, preferred_part? }` to `/quote/booking` (`bookingRoute`).
+  The submission id proves the lead is this page's (a `lead_ref` alone books
+  nothing); only a priced lead (`estimate`, `fixed`) books; one request per
+  lead. It is queued on the lead webhook's outbox behind `panelBooking` (off)
+  — see the lead webhook.
+- **`ctx.leadRef` is the panel's lead id.** A booking comes back to the panel
+  carrying `leadRef` (`metadata[ref]`, `ref`, `lead_ref`), so a brand's
+  `lead.created` must send `ctx.leadRef` as its lead id — not an id of its own.
+- **Weight.** The booking and the price confirmation add about 3.1 KB gz of
+  first-load JS to the template's place page (170,853 → 173,979 B against
+  its 158,000 B target: +10.1 %, within the 20 % tolerance).
+
 Tailwind v4 does not scan `node_modules`; the brand's `globals.css` names the
 package:
 
@@ -343,6 +526,14 @@ export const config = { matcher: ["/((?!_next/).*)"] };
 export const dynamic = "force-dynamic";
 export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable, anchor: "devis" });
 
+// app/quote/confirm/route.ts — a plain post whose price changed confirms here, uncached
+export const dynamic = "force-dynamic";
+export const GET = confirmRoute(site, { pricing, text: locale => TEXT[locale].leadCapture });
+
+// app/quote/booking/route.ts — a priced lead's booking request (`booking.requested@1`)
+export const dynamic = "force-dynamic";
+export const POST = bookingRoute({ env: serverEnv, webhook });
+
 // app/sitemap.ts — reads the Host header, so it is dynamic; pages are not
 export const dynamic = "force-dynamic";
 export default sitemapRoute(site, places);
@@ -399,13 +590,22 @@ chooses per visitor answer `Cache-Control: private, no-store`.
   `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`.
+  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
   (`LEAD_NOTIFY_TO`, or the brand's email). Both are bare addresses
   (`leads@brand.fr`), not `Name <…>`. Off loopback, a server without TLS gets
   nothing; past `MAIL_PER_MINUTE` a minute the lead is stored and only logged.
+- **The mail names the need.** `lead.subject` is the id the form posted
+  (`hot_water`); `leadNotifier(site, env, { needLabel })` names it instead —
+  `needLabel(need)` answers the label in the mail's language (the business's,
+  not the visitor's), `undefined` for a need it does not know, which the mail
+  prints as the id. The default mail uses it, `defaultLeadMail(brand, lead, id,
+  { needLabel })` too, and a brand's `format` gets it as its third argument:
+  `(lead, id, { need }) => LeadMail`.
 - **The rate limit knows whose address it counts.** `TRUSTED_PROXY` is
   `cloudflare` (only `CF-Connecting-IP`) or `xff:<n>` (the n-th
   `X-Forwarded-For` hop from the right); production refuses to boot without it.
@@ -465,6 +665,31 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   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` — send it as the panel's lead id.** The lead's reference
+  the page was answered with (`lead-<row>-<8 hex>`), whatever the switch.
+  Every booking joins its lead by it (Cal.com's `metadata[ref]`, a link's
+  `ref`, `booking.requested`'s `lead_ref`): **a brand must send this as the
+  panel lead id** in `lead.created`, not an id it computes itself.
+- **Booking requests: `panelBooking`, off.** With `leadWebhook(…, {
+  panelBooking: true, buildBookingBody })`, `bookingRoute` queues
+  `booking.requested@1` through the same outbox, after the lead's
+  `lead.created`, once per lead (`requestBooking`; the row's ref is
+  `booking:<leadRef>`), held until the lead's own row (`lead:<row>`) is
+  delivered — a `409` or `425` for it is retried, the panel not having the
+  lead yet — and never queued for a lead whose `lead.created` was not
+  (a suspect held back). `buildBookingBody(request, ctx)` builds the event —
+  `bookingRequestedProperties(request)` writes `{ lead_ref, provider,
+  preferred_date?, preferred_part? }`, `ctx` has `brandId`, `at`,
+  `idempotencyKey`. Off by default, and to stay off until the panel accepts
+  the event type: off, a request is answered and dropped.
 - **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

package/dist/core/accept.d.ts

@@ -1,5 +1,6 @@
 import { type RateLimiter } from "./antispam.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";
@@ -8,22 +9,36 @@ export declare const FORM_ID_FIELD = "form_id";
 /** The site's experiment assignment, posted so the submit counts in the right arm. */
 export declare const EXPERIMENT_FIELD = "experiment";
 export declare const VARIANT_FIELD = "variant";
+/**
+ * The price the form showed, in cents — compared with the server's, never
+ * stored as the price: a lead is taken only at the price the visitor saw.
+ */
+export declare const SHOWN_CENTS_FIELD = "shown_cents";
+/** The refusal of a lead shown at a price that has since changed (`lead_error=price_changed`). */
+export declare const PRICE_CHANGED = "price_changed";
 /** What the submit event carries besides the form id: slugs only, never what was typed. */
 export interface SubmitTags {
     experiment?: string;
     variant?: string;
 }
 export type Outcome<L extends string> = 
-/** `duplicate`: a resend of a submission already stored — answered as the first was, nothing sent again. */
+/**
+ * `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. */
+/**
+ * `field` names what to fix (`phone`, `consent`, … or `form`); `why` is for
+ * the log. `cents`: with `price_changed`, the price the lead would be taken at now.
+ */
  | {
     kind: "invalid";
     why: string;
@@ -32,6 +47,7 @@ export type Outcome<L extends string> =
     formId: string;
     locale: L;
     slug: string | null;
+    cents?: number;
 } | {
     kind: "failed";
     locale: L;
@@ -56,7 +72,14 @@ 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.
@@ -68,6 +91,16 @@ export interface AcceptDeps {
     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 { 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";
@@ -8,11 +10,67 @@ export const FORM_ID_FIELD = "form_id";
 /** The site's experiment assignment, posted so the submit counts in the right arm. */
 export const EXPERIMENT_FIELD = "experiment";
 export const VARIANT_FIELD = "variant";
+/**
+ * The price the form showed, in cents — compared with the server's, never
+ * stored as the price: a lead is taken only at the price the visitor saw.
+ */
+export const SHOWN_CENTS_FIELD = "shown_cents";
+/** The refusal of a lead shown at a price that has since changed (`lead_error=price_changed`). */
+export const PRICE_CHANGED = "price_changed";
 const FORM_ID = /^[a-z0-9_-]{1,32}$/;
 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.
@@ -60,7 +118,16 @@ async function accept(site, form, clientKey, deps) {
     // 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, lead: prior.lead, locale, formId, duplicate: true };
+        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);
+    // The price shown is the price recorded: a form priced from an older list
+    // is refused with the fresh price, for the visitor to confirm. A page from
+    // before the field posts none, and is taken as before.
+    const shown = field(form, SHOWN_CENTS_FIELD);
+    if (sale.price && shown !== null && /^\d{1,12}$/.test(shown) && Number(shown) !== sale.price.cents) {
+        deps.log.warn(`quote: a ${sale.flow} for ${candidate.subject} was shown at ${shown} and is now ${sale.price.cents}; sent back to confirm`);
+        return { kind: "invalid", why: "price changed", field: PRICE_CHANGED, channel: channelOf(candidate), formId, locale, slug, cents: sale.price.cents };
+    }
     // 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,
@@ -72,6 +139,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() } } : {}),
@@ -84,10 +152,11 @@ async function accept(site, form, clientKey, deps) {
         // 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, lead: winner.lead, locale, formId, duplicate: true };
+            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 };
     }
+    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
@@ -96,7 +165,7 @@ async function accept(site, form, clientKey, deps) {
         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);
@@ -107,7 +176,7 @@ async function accept(site, form, clientKey, deps) {
         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, lead, locale, formId };
+        return { kind: "stored", id, ref, lead, locale, formId };
     }
     queue();
     deps.defer(async () => {
@@ -120,5 +189,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 };
 }

package/dist/core/analytics.d.ts

@@ -16,6 +16,9 @@ export declare const EVENTS: {
     readonly formStep: "lead_form_step";
     readonly submitError: "lead_form_submit_error";
     readonly formReject: "lead_form_reject";
+    readonly estimateShown: "lead_estimate_shown";
+    readonly bookingOpen: "lead_booking_open";
+    readonly bookingDone: "lead_booking_done";
 };
 export type IntentChannel = "form_open" | "whatsapp" | "phone" | "sms" | "callback" | "booking";
 /**
@@ -32,7 +35,7 @@ export type LeadStep = "need" | "contact";
  * throws, prod drops) rather than by review. `experiment` and `variant` are
  * the site's assignment, passed in; `field` is a field's role, never its value.
  */
-export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source", "device", "channel", "form_id", "experiment", "variant", "field", "step", "layout", "reason", "blocking"];
+export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source", "device", "channel", "form_id", "experiment", "variant", "field", "step", "layout", "reason", "blocking", "need", "cents_bucket", "provider"];
 /** What an experiment's assignment looks like on the wire: short slugs, nothing a person typed. */
 export declare const EXPERIMENT_SLUG: RegExp;
 /** An experiment's assignment as event properties, or nothing when it is not a pair of slugs. */

package/dist/core/analytics.js

@@ -21,6 +21,13 @@ export const EVENTS = {
     submitError: "lead_form_submit_error",
     // The server's refusal (`reason`, the `field`): the visitor was sent back.
     formReject: "lead_form_reject",
+    // An estimate's price, shown for a full set of answers: the need and the
+    // price's band (`centsBucket`), never the price — once per band and need.
+    estimateShown: "lead_estimate_shown",
+    // After a priced lead: the visitor opened the place's booking (`provider`),
+    // and — only where the provider says so on the page (Cal.com's embed) — booked.
+    bookingOpen: "lead_booking_open",
+    bookingDone: "lead_booking_done",
 };
 /**
  * Every property name an event may carry. A customer's phone or address comes
@@ -44,6 +51,12 @@ export const ALLOWED_PROPS = [
     "reason",
     // A field error that blocked the submit (`true`), or a hint (`false`).
     "blocking",
+    // The brand's subject slug.
+    "need",
+    // A price's band, `"5000-7500"` (`centsBucket`) — never the price.
+    "cents_bucket",
+    // The booking's provider, `manual` | `link` | `cal_com` — never its URL.
+    "provider",
 ];
 /** What an experiment's assignment looks like on the wire: short slugs, nothing a person typed. */
 export const EXPERIMENT_SLUG = /^[a-z0-9_-]{1,32}$/;

package/dist/core/booking/index.d.ts

@@ -0,0 +1,3 @@
+export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BOOKING_EXPERIMENT, bookingOf, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, PREFERRED_PARTS, type BookingChoice, type BookingConfig, type BookingProvider, type BookingRequest, type BookingRequestedProperties, type BookingRules, type BookingStatus, type OpenBookingConfig, type PageProvider, type PreferredPart, } from "./model.js";
+export { BookingConfigError, bookingConfigProblems, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, parseBookingConfig, parseBookingRequest, } from "./validate.js";
+export { bookingHref, type BookingPrefill } from "./url.js";

package/dist/core/booking/index.js

@@ -0,0 +1,3 @@
+export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BOOKING_EXPERIMENT, bookingOf, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, PREFERRED_PARTS, } from "./model.js";
+export { BookingConfigError, bookingConfigProblems, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, parseBookingConfig, parseBookingRequest, } from "./validate.js";
+export { bookingHref } from "./url.js";