@evinvest/kitstart 0.10.0 → 0.12.0

package/README.md

@@ -16,9 +16,9 @@ stays in the brand.
 | `@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.10.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.12.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -232,9 +232,11 @@ it is the plain POST to `/quote` it always was.
 | `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) |
 | `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`, `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` |
+| `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`
@@ -273,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
@@ -368,26 +386,115 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, pricing, unavai
   `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
-  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.
+  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`, `slotCallback`, `photos*`); optional in `LeadCaptureText`, so
+  `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.
+  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:
 
@@ -419,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);
@@ -484,6 +599,13 @@ chooses per visitor answer `Cache-Control: private, no-store`.
   (`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.
@@ -550,8 +672,31 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   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.
+  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.
+- **`ctx.analyticsId` — the visit, for PostHog.** The `distinct_id` of the
+  page's beacons (`AnalyticsBoundary` holds one per page, in memory), posted
+  by `LeadCapture`'s script as `analytics_id` and checked against
+  `[A-Za-z0-9._:-]{1,128}`. Write it as `lead.created`'s `analytics_id`
+  property so the panel's PostHog events of the lead join the visit — once
+  the panel accepts the property. Absent for a plain post, a page with no
+  analytics key, or an older page; never stored with the lead.
+- **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
@@ -577,6 +722,54 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   `WEBHOOK_TICK_MS` and a new process picks up what is due. Rows queued for a
   previous URL stay in place and are counted at open.
 
+## Experiments from the panel
+
+The experiments live in code (`@evinvest/experiments`, one `as const` config);
+the panel decides their weights and kill switch, and PostHog counts them.
+
+**Overrides** (`createExperimentsSource`): `GET <base>/experiments`, the same
+base as the place source, `{ "experiments": { "<key>": { enabled?, weights?,
+holdout? } } }`. The proxy reads it on every request, so it answers from memory:
+the first call waits for the panel (1.5 s timeout), later ones are served from
+the cache, and past the 30 s TTL the stale answer is served while one refresh
+runs behind it. An unreachable panel, a non-200 or a body of another shape is
+logged and keeps the last good answer — a kill switch must not come back on
+because the panel blinked — or `{}`, the config in code, when there was none
+yet; either way the panel is not asked again before the TTL.
+
+```ts
+// shared/config/env.ts
+export const experimentOverrides = createExperimentsSource({ baseUrl: () => serverEnv().locationsApiUrl });
+// proxy.ts — the same applied config wherever a variant is read
+const live = applyOverrides(experiments, await experimentOverrides.overrides());
+```
+
+Only types are checked here; whether a field fits the code (weights of the
+declared length, holdout in `[0, 1)`) is `applyOverrides`' call.
+
+**Declaration** (`declareExperiments`): at every start the landing tells the
+panel which experiments this build runs — `experiments.declared@1`, one event
+with every experiment's key, variants, weights, `enabled`, `holdout` and an
+optional one-line `summary`, under a fresh UUIDv7. It goes through the lead
+webhook's outbox, signed and retried like a lead (so it needs the same
+`LEAD_WEBHOOK_URL` and sqlite lead store), and the panel keeps the latest by
+`occurredAt`; an experiment missing from it is retired there.
+
+```ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  declareExperiments(webhook, experiments, { summaries: { lead_layout: "Two steps beat one long form" } });
+}
+```
+
+It never throws and never holds the start: no webhook, one that cannot be
+built, or a queue that refuses the row is logged and skipped — the panel keeps
+the last declaration. An experiment the panel would refuse (key not
+`[a-z0-9_]{1,64}`, fewer than two unique slug variants, weights not one per
+variant, negative or summing to zero, holdout outside `[0, 1)`, summary over
+200 characters) is left out and logged, since the panel judges the event whole.
+
 ## The site
 
 ```ts

package/dist/core/accept.d.ts

@@ -9,6 +9,19 @@ 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 page's analytics id (`ANALYTICS_ID`), posted by the script only: the
+ * webhook's `ctx.analyticsId`, for `lead.created`'s `analytics_id`. Never
+ * stored with the lead and never a reason to refuse one.
+ */
+export declare const ANALYTICS_ID_FIELD = "analytics_id";
+/**
+ * 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;
@@ -28,7 +41,10 @@ export type Outcome<L extends string> =
     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;
@@ -37,6 +53,7 @@ export type Outcome<L extends string> =
     formId: string;
     locale: L;
     slug: string | null;
+    cents?: number;
 } | {
     kind: "failed";
     locale: L;
@@ -62,6 +79,7 @@ export interface AcceptDeps {
         locale: string;
         formId: string;
         leadRef: string;
+        analyticsId?: string;
     }) => void;
     /**
      * The price list to price an `estimate` or `fixed` lead with

package/dist/core/accept.js

@@ -1,4 +1,4 @@
-import { experimentProps } from "./analytics.js";
+import { ANALYTICS_ID, 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";
@@ -10,6 +10,19 @@ 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 page's analytics id (`ANALYTICS_ID`), posted by the script only: the
+ * webhook's `ctx.analyticsId`, for `lead.created`'s `analytics_id`. Never
+ * stored with the lead and never a reason to refuse one.
+ */
+export const ANALYTICS_ID_FIELD = "analytics_id";
+/**
+ * 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);
@@ -113,6 +126,14 @@ async function accept(site, form, clientKey, 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);
+    // 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,
@@ -146,11 +167,13 @@ async function accept(site, form, clientKey, deps) {
     // 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.
+    const rawAnalyticsId = form.get(ANALYTICS_ID_FIELD);
+    const analyticsId = typeof rawAnalyticsId === "string" && ANALYTICS_ID.test(rawAnalyticsId) ? rawAnalyticsId : undefined;
     const queue = () => {
         if (!deps.enqueue)
             return;
         try {
-            deps.enqueue(lead, id, { locale, formId, leadRef: ref });
+            deps.enqueue(lead, id, { locale, formId, leadRef: ref, ...(analyticsId ? { analyticsId } : {}) });
         }
         catch (error) {
             deps.log.error(`quote: lead ${id} is stored but could not be queued for its webhook`, error);

package/dist/core/analytics.d.ts

@@ -17,6 +17,8 @@ export declare const EVENTS: {
     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";
 /**
@@ -33,7 +35,13 @@ 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", "need", "cents_bucket"];
+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"];
+/**
+ * The beacon's `distinct_id` as a lead may carry it to the panel
+ * (`lead.created`'s `analytics_id`), so PostHog can join the lead to the
+ * visit. The panel's own rule; anything else is dropped, never refused.
+ */
+export declare const ANALYTICS_ID: RegExp;
 /** 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. */
@@ -60,6 +68,8 @@ export interface AnalyticsTarget {
  * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
  * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
  * because the events that matter most — a tap on `tel:` or `wa.me` — are
- * followed by the page handing the visitor to another app.
+ * followed by the page handing the visitor to another app. `distinctId`:
+ * the visitor's id, held by the caller so a lead can name it; a random one
+ * per sink without it.
  */
-export declare function analyticsSink(target: AnalyticsTarget, locationId: string | null): AnalyticsSink;
+export declare function analyticsSink(target: AnalyticsTarget, locationId: string | null, distinctId?: string): AnalyticsSink;

package/dist/core/analytics.js

@@ -24,6 +24,10 @@ export const EVENTS = {
     // 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
@@ -51,7 +55,15 @@ export const ALLOWED_PROPS = [
     "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",
 ];
+/**
+ * The beacon's `distinct_id` as a lead may carry it to the panel
+ * (`lead.created`'s `analytics_id`), so PostHog can join the lead to the
+ * visit. The panel's own rule; anything else is dropped, never refused.
+ */
+export const ANALYTICS_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 /** 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}$/;
 /** An experiment's assignment as event properties, or nothing when it is not a pair of slugs. */
@@ -69,11 +81,14 @@ export function countsAsPageView(pathname) {
  * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
  * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
  * because the events that matter most — a tap on `tel:` or `wa.me` — are
- * followed by the page handing the visitor to another app.
+ * followed by the page handing the visitor to another app. `distinctId`:
+ * the visitor's id, held by the caller so a lead can name it; a random one
+ * per sink without it.
  */
-export function analyticsSink(target, locationId) {
+export function analyticsSink(target, locationId, distinctId) {
     return createBeaconSink({
         key: target.key ?? undefined,
+        ...(distinctId !== undefined ? { distinctId } : {}),
         host: target.host,
         allowedProps: ALLOWED_PROPS,
         globalProps: locationId ? { brand_id: target.brandId, location_id: locationId } : { brand_id: target.brandId },

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";

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

@@ -0,0 +1,106 @@
+/**
+ * Booking, provider-agnostic: how a place's slot is set once a priced lead is
+ * stored. The vocabulary is the panel's (snake_case, closed sets) and the
+ * fixtures in `test/fixtures/booking/` are the contract it mirrors: a new
+ * provider extends the closed set with its own URL rule, and nothing else on
+ * either side changes.
+ */
+/**
+ * - `manual`: no external page — the site promises a call to set the slot, and
+ *   the operator records it in the panel. Always available; carries no URL.
+ * - `link`: any external booking page (strict https), opened with
+ *   `ref=<leadRef>` in its query.
+ * - `google_calendar`: a Google appointment schedule, opened as is — it takes
+ *   no parameter, so the panel matches its bookings by contact and time.
+ * - `cal_com`: a Cal.com event, opened with the name, the phone and
+ *   `metadata[ref]=<leadRef>` prefilled.
+ */
+export declare const BOOKING_PROVIDERS: readonly ["manual", "link", "google_calendar", "cal_com"];
+export type BookingProvider = (typeof BOOKING_PROVIDERS)[number];
+/** The providers with a page to open — every one but `manual`. */
+export type PageProvider = Exclude<BookingProvider, "manual">;
+/**
+ * A place's booking, as `PlaceLive.booking` serves it and the panel's place
+ * settings edit it: the providers it has a page on, and the one it offers by
+ * default — `manual` or one of them. An experiment (`booking_provider`) may
+ * pick another of the place's providers (`bookingOf`).
+ */
+export interface BookingConfig {
+    default: BookingProvider;
+    providers: Readonly<Partial<Record<PageProvider, {
+        url: string;
+    }>>>;
+}
+/** The booking one page offers: the provider chosen for this visitor, and its page. */
+export type BookingChoice = {
+    provider: "manual";
+} | {
+    provider: PageProvider;
+    url: string;
+};
+/**
+ * A choice a brand's own adapter makes sense of — what `LeadBooking` takes.
+ * Every `BookingChoice` is one; the closed set is what the place settings
+ * and `booking.requested@1` accept.
+ */
+export interface OpenBookingConfig {
+    provider: string;
+    url?: string;
+}
+/** A place with no booking of its own — baked or live — promises a call. */
+export declare const DEFAULT_BOOKING: BookingConfig;
+/** The experiment whose variant names the provider a visitor is offered, the same key on every brand. */
+export declare const BOOKING_EXPERIMENT = "booking_provider";
+/** A lead's booking, as the panel's projection tracks it; the site only ever says `requested`. */
+export declare const BOOKING_STATUSES: readonly ["none", "requested", "booked", "canceled", "done", "no_show"];
+export type BookingStatus = (typeof BOOKING_STATUSES)[number];
+/** The part of the day a visitor may prefer for a `manual` slot. */
+export declare const PREFERRED_PARTS: readonly ["morning", "afternoon", "evening"];
+export type PreferredPart = (typeof PREFERRED_PARTS)[number];
+/**
+ * The site's `booking.requested@1`: a lead asked for a slot. A provider with
+ * a page sends it when the page is opened; `manual` when the visitor sends
+ * the (optional) preference — which only `manual` carries.
+ */
+export interface BookingRequest {
+    /** The lead's public reference (`leadRef`) — the panel's lead id. */
+    leadRef: string;
+    provider: BookingProvider;
+    /** `YYYY-MM-DD`; `manual` only. */
+    preferredDate?: string;
+    /** `manual` only. */
+    preferredPart?: PreferredPart;
+}
+/** `booking.requested@1`'s properties as the panel reads them. */
+export interface BookingRequestedProperties {
+    lead_ref: string;
+    provider: BookingProvider;
+    preferred_date?: string;
+    preferred_part?: PreferredPart;
+}
+/** The Cal.com hosts a `cal_com` URL may point at unless the site names its own: ours, and the hosted cloud. */
+export declare const DEFAULT_CAL_COM_HOSTS: readonly string[];
+/** What a validator is told besides the value: the site's (or brand's) Cal.com hosts. */
+export interface BookingRules {
+    /** Exact hostnames, lowercase; a subdomain is another host. Default `DEFAULT_CAL_COM_HOSTS`. */
+    calComHosts?: readonly string[];
+}
+export declare const BOOKING_LIMITS: {
+    readonly maxUrl: 2048;
+    /** A Cal.com username or event slug: one path segment, no dot segment. */
+    readonly calComSegment: RegExp;
+};
+export declare function isLeadRef(value: unknown): value is string;
+export declare function isBookingProvider(value: unknown): value is BookingProvider;
+export declare function isPageProvider(value: unknown): value is PageProvider;
+export declare function isPreferredPart(value: unknown): value is PreferredPart;
+/**
+ * The one entry point for which booking a visitor is offered: the provider
+ * the experiment's variant (`booking_provider`) names, when the place has it
+ * (`manual` it always has), else the place's default. The chosen provider is
+ * what `booking.requested@1` and `lead_booking_open/done` report, so the arms
+ * compare.
+ */
+export declare function bookingOf(place: {
+    booking?: BookingConfig | undefined;
+}, variant?: string | null): BookingChoice;