@evinvest/kitstart 0.10.0 → 0.12.0

package/dist/react/booking-adapters.js

@@ -0,0 +1,104 @@
+import { isPageProvider } from "../core/booking/model.js";
+import { bookingHref } from "../core/booking/url.js";
+/** The built-in choice a context carries, or `null` when it is not one. */
+function choiceOf(config) {
+    if (config.provider === "manual")
+        return { provider: "manual" };
+    return isPageProvider(config.provider) && config.url ? { provider: config.provider, url: config.url } : null;
+}
+const hrefOf = (ctx) => {
+    const choice = choiceOf(ctx.config);
+    return choice && bookingHref(choice, { leadRef: ctx.leadRef, name: ctx.name, phone: ctx.phone });
+};
+/** `manual`: no page to open — the card promises the call and offers a preference. */
+export const manualAdapter = { provider: "manual" };
+/** `link`: the page with `ref=<leadRef>`. */
+export const linkAdapter = { provider: "link", href: hrefOf };
+/** `google_calendar`: the schedule as is — it takes no parameter, so the visitor types the same number there. */
+export const googleCalendarAdapter = { provider: "google_calendar", href: hrefOf };
+/** `cal_com`: the event with the name, the phone and `metadata[ref]`. */
+export const calComAdapter = { provider: "cal_com", href: hrefOf, prefillsPhone: () => true };
+const isObject = (v) => typeof v === "object" && v !== null;
+function addScript(src) {
+    const el = document.createElement("script");
+    el.src = src;
+    el.async = true;
+    document.head.appendChild(el);
+}
+/** Cal.com's own queue stub, as its embed snippet installs it; the script is added on the first call. */
+function calQueue(w, script) {
+    if (w.Cal)
+        return w.Cal;
+    const cal = (...args) => {
+        if (!cal.loaded) {
+            cal.ns = {};
+            addScript(script);
+            cal.loaded = true;
+        }
+        (cal.q ??= []).push(args);
+    };
+    w.Cal = cal;
+    return cal;
+}
+/** The hosted cloud serves its embed from `app.cal.com`; a self-hosted Cal.com from its own host. */
+export function calComEmbedOrigin(url) {
+    const u = new URL(url);
+    return u.hostname === "cal.com" ? "https://app.cal.com" : u.origin;
+}
+/** Per `Cal` instance — one per page — so the listeners are registered once however often the modal opens. */
+const calPages = new WeakMap();
+function calPage(cal, origin) {
+    const known = calPages.get(cal);
+    if (known)
+        return known;
+    const page = { current: null, booked: new Set() };
+    calPages.set(cal, page);
+    const booked = (e) => {
+        const ctx = page.current;
+        // Cal.com may fire both versions of the event for one booking.
+        if (!ctx || page.booked.has(ctx.leadRef))
+            return;
+        page.booked.add(ctx.leadRef);
+        const detail = isObject(e) ? e.detail : undefined;
+        const data = isObject(detail) && isObject(detail.data) ? detail.data : undefined;
+        const startAt = data?.startTime ?? data?.date;
+        const endAt = data?.endTime;
+        ctx.onBooked?.({ ...(typeof startAt === "string" ? { startAt } : {}), ...(typeof endAt === "string" ? { endAt } : {}) });
+    };
+    cal("init", { origin });
+    cal("on", { action: "bookingSuccessful", callback: booked });
+    cal("on", { action: "bookingSuccessfulV2", callback: booked });
+    return page;
+}
+/**
+ * `cal_com` as Cal.com's modal on the page: its script loads only on the
+ * click, and its `bookingSuccessful` is `onBooked` — once per lead, however
+ * often the modal is opened and closed. Opt-in (`bookingEmbed`), and only
+ * once the visitor accepted the provider's cookies.
+ */
+export const calComEmbedAdapter = {
+    provider: "cal_com",
+    prefillsPhone: () => true,
+    open: ctx => {
+        const href = hrefOf(ctx);
+        if (href === null)
+            return;
+        const u = new URL(href);
+        const origin = calComEmbedOrigin(href);
+        const cal = calQueue(window, `${origin}/embed/embed.js`);
+        calPage(cal, origin).current = ctx;
+        cal("modal", { calLink: u.pathname.slice(1), config: Object.fromEntries(u.searchParams) });
+    },
+};
+export const BOOKING_ADAPTERS = {
+    manual: manualAdapter,
+    link: linkAdapter,
+    google_calendar: googleCalendarAdapter,
+    cal_com: calComAdapter,
+};
+/** The embeds `bookingEmbed` turns on. */
+export const BOOKING_EMBEDS = { cal_com: calComEmbedAdapter };
+/** The built-ins with a brand's own over them, by provider. */
+export function bookingAdapters(over = {}) {
+    return { ...BOOKING_ADAPTERS, ...over };
+}

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect` and `LeadCapture` are client modules, each its own file
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
  * with its own `"use client"`, so a page pays for what it renders.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
@@ -18,6 +18,10 @@ export { Faq, type FaqPart, type FaqProps } from "./Faq.js";
 export { FormSelect, type FormSelectOption, type FormSelectPart, type FormSelectProps } from "./FormSelect.js";
 export { LangSwitch, withLang, type LangSwitchProps } from "./LangSwitch.js";
 export { LeadCapture, type LeadCapturePart, type LeadCaptureProps } from "./LeadCapture.js";
+export { LeadBooking, type LeadBookingProps } from "./LeadBooking.js";
+export type { BookingPart } from "./LeadBookingManual.js";
+export { BOOKING_ADAPTERS, BOOKING_EMBEDS, bookingAdapters, calComAdapter, calComEmbedAdapter, calComEmbedOrigin, googleCalendarAdapter, linkAdapter, manualAdapter, type BookedSlot, type BookingAdapter, type BookingAdapters, type BookingContext, } from "./booking-adapters.js";
+export { BOOKING_ACTION } from "./use-booking.js";
 export type { LeadSent } from "./use-lead-submit.js";
 export type { LeadCaptureLayout } from "./LeadCaptureNeed.js";
 export { MapFacade, type MapFacadePart, type MapFacadeProps } from "./MapFacade.js";

package/dist/react/index.js

@@ -1,7 +1,7 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect` and `LeadCapture` are client modules, each its own file
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
  * with its own `"use client"`, so a page pays for what it renders.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
@@ -18,6 +18,9 @@ export { Faq } from "./Faq.js";
 export { FormSelect } from "./FormSelect.js";
 export { LangSwitch, withLang } from "./LangSwitch.js";
 export { LeadCapture } from "./LeadCapture.js";
+export { LeadBooking } from "./LeadBooking.js";
+export { BOOKING_ADAPTERS, BOOKING_EMBEDS, bookingAdapters, calComAdapter, calComEmbedAdapter, calComEmbedOrigin, googleCalendarAdapter, linkAdapter, manualAdapter, } from "./booking-adapters.js";
+export { BOOKING_ACTION } from "./use-booking.js";
 export { MapFacade } from "./MapFacade.js";
 export { PlaceDirectory } from "./PlaceDirectory.js";
 export { PHONE_INPUT_PROPS, QuoteFormShell } from "./QuoteFormShell.js";

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

@@ -0,0 +1,20 @@
+import type { BookingRequestedProperties } from "../core/booking/model.js";
+/** A request as the page posts it; a provider outside the closed set is the server's to refuse. */
+export type PostedBooking = Omit<BookingRequestedProperties, "provider"> & {
+    provider: string;
+};
+/** Where `LeadCapture` posts a booking request: `bookingRoute`, beside the quote route. */
+export declare const BOOKING_ACTION = "/quote/booking";
+export interface BookingReport {
+    /** The visitor opened the booking (or sent a `manual` preference): the event, and `booking.requested@1` to the site. */
+    requested(properties: PostedBooking): Promise<boolean>;
+    /** The provider said the slot is booked. */
+    booked(): void;
+}
+/**
+ * The page's side of a booking: `lead_booking_open` / `lead_booking_done`
+ * (the provider only, never the URL), and the request to the site's
+ * `bookingRoute`, which the panel hears as `booking.requested@1`. The post is
+ * first-party, and the page stays: a provider's page opens in a new tab.
+ */
+export declare function useBooking(provider: string, submission: string, formId: string, action?: string): BookingReport;

package/dist/react/use-booking.js

@@ -0,0 +1,32 @@
+"use client";
+import { useCallback, useMemo } from "react";
+import { EVENTS } from "../core/analytics.js";
+import { useAnalyticsSink } from "./analytics-context.js";
+/** Where `LeadCapture` posts a booking request: `bookingRoute`, beside the quote route. */
+export const BOOKING_ACTION = "/quote/booking";
+/**
+ * The page's side of a booking: `lead_booking_open` / `lead_booking_done`
+ * (the provider only, never the URL), and the request to the site's
+ * `bookingRoute`, which the panel hears as `booking.requested@1`. The post is
+ * first-party, and the page stays: a provider's page opens in a new tab.
+ */
+export function useBooking(provider, submission, formId, action = BOOKING_ACTION) {
+    const sink = useAnalyticsSink();
+    const props = useMemo(() => ({ provider, form_id: formId }), [provider, formId]);
+    const requested = useCallback(async (properties) => {
+        sink?.capture(EVENTS.bookingOpen, props);
+        try {
+            const res = await fetch(action, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ submission, ...properties }),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }, [sink, props, action, submission]);
+    const booked = useCallback(() => sink?.capture(EVENTS.bookingDone, props), [sink, props]);
+    return { requested, booked };
+}

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

@@ -1,11 +1,7 @@
 import { type RefObject } from "react";
-import { type LeadChannel } from "../core/lead.js";
+import { type LeadChannel, type LeadError } from "../core/lead.js";
 import type { LeadCaptureText } from "../core/lead-capture-text.js";
-/** A refusal the server sent back: which of the card's forms, and the field it is about. */
-export interface LeadError {
-    channel: LeadChannel;
-    field: string;
-}
+export type { LeadError };
 /** The fields `LeadCapture` draws itself, which show a refusal under themselves. */
 export declare const OWN_FIELDS: Readonly<Record<LeadChannel, readonly string[]>>;
 /** The id of the message a refusal of a field the card does not draw is shown in, above the submit. */
@@ -21,4 +17,4 @@ export declare function errorText(field: string, text: LeadCaptureText): string;
  * `aria-invalid` and pointed at the message above the submit. Fixing that
  * control clears it.
  */
-export declare function useLeadError(root: RefObject<HTMLElement | null>, id: string): [LeadError | null, (error: LeadError | null) => void];
+export declare function useLeadError(root: RefObject<HTMLElement | null>, id: string, initial?: LeadError | null): [LeadError | null, (error: LeadError | null) => void];

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

@@ -1,7 +1,7 @@
 "use client";
 import { useEffect, useState } from "react";
-import { LEAD_ERROR_PARAM } from "../core/lead.js";
-const FIELD = /^[a-z][a-z0-9_]{0,31}$/;
+import { PRICE_CHANGED } from "../core/accept.js";
+import { LEAD_CARD_PARAM, LEAD_ERROR_FIELD, LEAD_ERROR_PARAM } from "../core/lead.js";
 /** The fields `LeadCapture` draws itself, which show a refusal under themselves. */
 export const OWN_FIELDS = { form: ["phone", "locality", "name"], callback: ["phone", "consent"] };
 /** The id of the message a refusal of a field the card does not draw is shown in, above the submit. */
@@ -31,8 +31,9 @@ function controlOf(form, field) {
  * `aria-invalid` and pointed at the message above the submit. Fixing that
  * control clears it.
  */
-export function useLeadError(root, id) {
-    const [error, setError] = useState(null);
+export function useLeadError(root, id, initial = null) {
+    // Drawn on the server too when the page read it from its query (`leadErrorOf`).
+    const [error, setError] = useState(initial);
     useEffect(() => {
         const url = new URL(window.location.href);
         const field = url.searchParams.get(LEAD_ERROR_PARAM);
@@ -40,8 +41,9 @@ export function useLeadError(root, id) {
         if (field === null || channel === null)
             return;
         url.searchParams.delete(LEAD_ERROR_PARAM);
+        url.searchParams.delete(LEAD_CARD_PARAM);
         window.history.replaceState(window.history.state, "", url);
-        if (FIELD.test(field))
+        if (LEAD_ERROR_FIELD.test(field))
             setError({ channel, field });
     }, [id]);
     useEffect(() => {
@@ -57,7 +59,8 @@ export function useLeadError(root, id) {
         foreign?.setAttribute("aria-describedby", formMessageId(id, error.channel));
         (control ?? document.getElementById(formMessageId(id, error.channel)))?.focus();
         const fixed = (event) => {
-            if (error.field === "form" || (event.target instanceof Element && control?.contains(event.target)))
+            // A refusal of the whole form, or of its price, is about every answer: any change answers it.
+            if (error.field === "form" || error.field === PRICE_CHANGED || (event.target instanceof Element && control?.contains(event.target)))
                 setError(null);
         };
         form.addEventListener("input", fixed);

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

@@ -11,6 +11,11 @@ export interface LeadSent {
     lead?: string;
     /** The price the server took the lead at, for an `estimate` or `fixed` need. */
     cents?: number;
+    /**
+     * The form's submission id, with `lead` only: the secret a booking request
+     * (`bookingRoute`) proves the lead is this page's with.
+     */
+    submission?: string;
 }
 /** Leaving the page, behind a seam a test can stand in for (jsdom cannot navigate). */
 export declare const navigation: {
@@ -27,7 +32,8 @@ export type SendFailure = "network" | "timeout";
 export declare const SUBMIT_TIMEOUT_MS = 15000;
 export interface LeadSubmitHandlers {
     /** The route refused the lead: the field to fix. */
-    onRefused: (channel: LeadChannel, field: string) => void;
+    /** `cents`: with `price_changed`, the server's fresh price. */
+    onRefused: (channel: LeadChannel, field: string, cents?: number) => void;
     /** No answer: the form stays as typed, with a retry. */
     onFailed: (channel: LeadChannel, failure: SendFailure) => void;
 }

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

@@ -1,7 +1,9 @@
 "use client";
 import { useRef, useState } from "react";
+import { ANALYTICS_ID_FIELD } from "../core/accept.js";
 import { CHANNEL_FIELD, SUBMISSION_FIELD } from "../core/lead.js";
 import { THANKS } from "../core/routing.js";
+import { useAnalyticsId } from "./analytics-context.js";
 /** Leaving the page, behind a seam a test can stand in for (jsdom cannot navigate). */
 export const navigation = { assign: (url) => window.location.assign(url) };
 /**
@@ -68,8 +70,9 @@ async function readAnswer(res) {
                 ...(typeof cents === "number" && Number.isSafeInteger(cents) && cents >= 0 ? { cents } : {}),
             };
         }
+        // `cents`: with `price_changed`, the price the lead would be taken at now.
         if (ok === false && typeof field === "string")
-            return { ok, field };
+            return { ok, field, ...(typeof cents === "number" && Number.isSafeInteger(cents) && cents >= 0 ? { cents } : {}) };
         return null;
     }
     if (res.ok && res.redirected) {
@@ -97,6 +100,7 @@ export function useLeadSubmit(done, fields, on) {
     const [failure, setFailure] = useState(null);
     const pending = useRef(false);
     const last = useRef(null);
+    const analyticsId = useAnalyticsId();
     const submit = (event) => {
         event.preventDefault();
         if (pending.current)
@@ -110,6 +114,10 @@ export function useLeadSubmit(done, fields, on) {
         for (const [key, value] of data)
             if (typeof value === "string")
                 body.append(key, value);
+        // Not a field of the form: the submission id stamps what the visitor
+        // posted, and a plain post (no script) has no analytics to name anyway.
+        if (analyticsId)
+            body.set(ANALYTICS_ID_FIELD, analyticsId);
         const read = (field) => {
             const value = field === undefined ? null : data.get(field);
             return typeof value === "string" ? value.trim() : "";
@@ -136,13 +144,15 @@ export function useLeadSubmit(done, fields, on) {
                 return fallBack();
             if (!answer.ok) {
                 settle();
-                return on.onRefused(lead.channel, answer.field);
+                return on.onRefused(lead.channel, answer.field, answer.cents);
             }
             // Still pending: the page is leaving, or the form is gone. The next
             // lead from this form (Back, another need) gets an id of its own.
             minted.delete(form);
+            const submission = data.get(SUBMISSION_FIELD);
+            const ref = answer.lead && typeof submission === "string" && submission !== "" ? { lead: answer.lead, submission } : answer.lead ? { lead: answer.lead } : {};
             if (typeof done === "function" ? done(lead.channel) : done)
-                setSent({ ...lead, ...(answer.lead ? { lead: answer.lead } : {}), ...(answer.cents !== undefined ? { cents: answer.cents } : {}) });
+                setSent({ ...lead, ...ref, ...(answer.cents !== undefined ? { cents: answer.cents } : {}) });
             else
                 navigation.assign(answer.location);
         }, () => {

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

@@ -0,0 +1,18 @@
+import type { LeadCaptureFlowText } from "../core/lead-capture-text.js";
+import type { Price } from "../core/pricing/model.js";
+/**
+ * The price the server answered when the one on screen was stale
+ * (`price_changed`): shown in its place, and posted back as `shown_cents` —
+ * a resubmit is the visitor confirming it. Only while the answers are the
+ * ones it was refused for; a change and the page prices on its own again.
+ */
+export declare function useRepriced(price: Price | null, need: string | undefined, text: LeadCaptureFlowText, locale: string): {
+    /** The price to show: the server's fresh one, else the page's own. */
+    price: Price | null;
+    /** What the form posts as `shown_cents`. */
+    shownCents: number | undefined;
+    /** The words for a `price_changed` refusal, with both prices when the page has them. */
+    message: () => string;
+    /** A refusal: remembers the fresh price when it is `price_changed`. */
+    refused(field: string, cents: number | undefined): void;
+};

package/dist/react/use-repriced.js

@@ -0,0 +1,27 @@
+"use client";
+import { useState } from "react";
+import { PRICE_CHANGED } from "../core/accept.js";
+import { fillText, formatCents } from "../core/lead-capture-format.js";
+/**
+ * The price the server answered when the one on screen was stale
+ * (`price_changed`): shown in its place, and posted back as `shown_cents` —
+ * a resubmit is the visitor confirming it. Only while the answers are the
+ * ones it was refused for; a change and the page prices on its own again.
+ */
+export function useRepriced(price, need, text, locale) {
+    const [repriced, setRepriced] = useState(null);
+    const current = repriced && price && repriced.shown === price.cents && repriced.need === need ? repriced : null;
+    return {
+        /** The price to show: the server's fresh one, else the page's own. */
+        price: current ? { cents: current.cents, breakdown: [] } : price,
+        /** What the form posts as `shown_cents`. */
+        shownCents: current?.cents ?? price?.cents,
+        /** The words for a `price_changed` refusal, with both prices when the page has them. */
+        message: () => current ? fillText(text.priceChanged, { price: formatCents(current.cents, locale), shown: formatCents(current.shown, locale) }) : text.priceChangedGeneric,
+        /** A refusal: remembers the fresh price when it is `price_changed`. */
+        refused(field, cents) {
+            if (field === PRICE_CHANGED && cents !== undefined && price)
+                setRepriced({ cents, shown: price.cents, need });
+        },
+    };
+}

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

@@ -0,0 +1,106 @@
+import "server-only";
+import type { LeadWebhook } from "./lead-webhook.js";
+/**
+ * One experiment as the code declares it — the shape of an
+ * `@evinvest/experiments` spec, so the brand's `as const` config is passed
+ * as is. `variants[0]` is the control.
+ */
+export interface DeclaredExperiment {
+    readonly variants: readonly string[];
+    readonly weights: readonly number[];
+    readonly enabled?: boolean;
+    readonly holdout?: number;
+}
+export type ExperimentsDeclaration = Readonly<Record<string, DeclaredExperiment>>;
+/** `ExperimentDeclaration` of the panel's `experiments.declared@1`. */
+export interface ExperimentDeclarationV1 {
+    key: string;
+    variants: string[];
+    weights: number[];
+    enabled: boolean;
+    holdout?: number;
+    summary?: string;
+}
+/** `experiments.declared@1` as protojson: `sa.v1.Event` with `ExperimentsDeclaredV1` for properties. */
+export interface ExperimentsDeclaredEvent {
+    id: string;
+    schema: "sa.funnel.v1";
+    type: "experiments.declared";
+    typeVersion: 1;
+    occurredAt: string;
+    source: {
+        kind: "site";
+        id: string;
+    };
+    subject: {
+        brandId: string;
+    };
+    properties: {
+        experiments: ExperimentDeclarationV1[];
+    };
+}
+/**
+ * Why the panel would refuse this experiment, or `null`. The panel judges the
+ * event whole, so one bad experiment would lose the brand's declaration:
+ * it is left out instead, and said so at start.
+ */
+export declare function declarationProblem(key: string, spec: DeclaredExperiment, summary: string | undefined): string | null;
+/** RFC 9562 UUIDv7: the panel refuses any other version for an event id. */
+export declare function uuidV7(nowMs: number): string;
+export interface DeclarationContext {
+    brandId: string;
+    /** The key id the batch is signed with: the panel refuses any other `source.id`. */
+    sourceId: string;
+    at: Date;
+    /** One line of hypothesis per key, at most 200 characters. */
+    summaries?: Readonly<Record<string, string>>;
+}
+/**
+ * The ingest body declaring the brand's experiments, and what was left out of
+ * it with why. A fresh UUIDv7 each call: every start is a declaration of its
+ * own, and the panel keeps the latest by `occurredAt`.
+ */
+export declare function experimentsDeclaredBody(experiments: ExperimentsDeclaration, ctx: DeclarationContext): {
+    body: {
+        events: [ExperimentsDeclaredEvent];
+    };
+    skipped: {
+        key: string;
+        why: string;
+    }[];
+};
+/** What `declareExperiments` did: queued (`row`), or why not. */
+export type DeclareOutcome = {
+    kind: "queued";
+    row: number;
+    skipped: {
+        key: string;
+        why: string;
+    }[];
+} | {
+    kind: "off";
+} | {
+    kind: "failed";
+};
+export interface DeclareOptions {
+    summaries?: Readonly<Record<string, string>>;
+    log?: Pick<Console, "warn" | "error">;
+}
+/**
+ * Tells the panel which experiments this build runs — for `instrumentation.ts`
+ * `register()`, once per start:
+ *
+ * ```ts
+ * export async function register() {
+ *   if (process.env.NEXT_RUNTIME !== "nodejs") return;
+ *   declareExperiments(webhook, experiments, { summaries: { hero: "A shorter form converts better" } });
+ * }
+ * ```
+ *
+ * Queued in the lead webhook's outbox, signed and retried like a lead, and
+ * sent at once. It never throws and never holds the start: a webhook that is
+ * off (no `LEAD_WEBHOOK_URL`) or cannot be built is logged and skipped — the
+ * panel keeps the brand's last declaration. An experiment the panel would
+ * refuse is left out, logged.
+ */
+export declare function declareExperiments(webhook: () => LeadWebhook | null, experiments: ExperimentsDeclaration, options?: DeclareOptions): DeclareOutcome;

package/dist/server/experiments-declared.js

@@ -0,0 +1,124 @@
+import "server-only";
+import { randomBytes } from "node:crypto";
+import { EXPERIMENT_SLUG } from "../core/analytics.js";
+const KEY = /^[a-z0-9_]{1,64}$/;
+const MAX_SUMMARY = 200;
+/**
+ * Why the panel would refuse this experiment, or `null`. The panel judges the
+ * event whole, so one bad experiment would lose the brand's declaration:
+ * it is left out instead, and said so at start.
+ */
+export function declarationProblem(key, spec, summary) {
+    if (!KEY.test(key))
+        return "the key is not [a-z0-9_]{1,64}";
+    if (spec.variants.length < 2)
+        return "fewer than two variants";
+    if (new Set(spec.variants).size !== spec.variants.length)
+        return "a variant is declared twice";
+    if (!spec.variants.every(v => EXPERIMENT_SLUG.test(v)))
+        return "a variant is not a slug ([a-z0-9_-]{1,32})";
+    if (spec.weights.length !== spec.variants.length)
+        return "not one weight per variant";
+    if (!spec.weights.every(w => Number.isFinite(w) && w >= 0))
+        return "a weight is negative or not a number";
+    if (spec.weights.reduce((sum, w) => sum + w, 0) <= 0)
+        return "the weights sum to zero";
+    if (spec.holdout !== undefined && !(Number.isFinite(spec.holdout) && spec.holdout >= 0 && spec.holdout < 1))
+        return "the holdout is not in [0, 1)";
+    if (summary !== undefined && summary.length > MAX_SUMMARY)
+        return `the summary is over ${MAX_SUMMARY} characters`;
+    return null;
+}
+/** RFC 9562 UUIDv7: the panel refuses any other version for an event id. */
+export function uuidV7(nowMs) {
+    const bytes = randomBytes(16);
+    let ms = nowMs;
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = ms % 256;
+        ms = Math.floor(ms / 256);
+    }
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * The ingest body declaring the brand's experiments, and what was left out of
+ * it with why. A fresh UUIDv7 each call: every start is a declaration of its
+ * own, and the panel keeps the latest by `occurredAt`.
+ */
+export function experimentsDeclaredBody(experiments, ctx) {
+    const declared = [];
+    const skipped = [];
+    for (const [key, spec] of Object.entries(experiments)) {
+        const summary = ctx.summaries && Object.hasOwn(ctx.summaries, key) ? ctx.summaries[key] : undefined;
+        const why = declarationProblem(key, spec, summary);
+        if (why !== null) {
+            skipped.push({ key, why });
+            continue;
+        }
+        declared.push({
+            key,
+            variants: [...spec.variants],
+            weights: [...spec.weights],
+            enabled: spec.enabled ?? true,
+            ...(spec.holdout !== undefined ? { holdout: spec.holdout } : {}),
+            ...(summary !== undefined && summary !== "" ? { summary } : {}),
+        });
+    }
+    const event = {
+        id: uuidV7(ctx.at.getTime()),
+        schema: "sa.funnel.v1",
+        type: "experiments.declared",
+        typeVersion: 1,
+        occurredAt: ctx.at.toISOString(),
+        source: { kind: "site", id: ctx.sourceId },
+        subject: { brandId: ctx.brandId },
+        properties: { experiments: declared },
+    };
+    return { body: { events: [event] }, skipped };
+}
+/**
+ * Tells the panel which experiments this build runs — for `instrumentation.ts`
+ * `register()`, once per start:
+ *
+ * ```ts
+ * export async function register() {
+ *   if (process.env.NEXT_RUNTIME !== "nodejs") return;
+ *   declareExperiments(webhook, experiments, { summaries: { hero: "A shorter form converts better" } });
+ * }
+ * ```
+ *
+ * Queued in the lead webhook's outbox, signed and retried like a lead, and
+ * sent at once. It never throws and never holds the start: a webhook that is
+ * off (no `LEAD_WEBHOOK_URL`) or cannot be built is logged and skipped — the
+ * panel keeps the brand's last declaration. An experiment the panel would
+ * refuse is left out, logged.
+ */
+export function declareExperiments(webhook, experiments, options = {}) {
+    const log = options.log ?? console;
+    let hook;
+    try {
+        hook = webhook();
+    }
+    catch (error) {
+        log.error("experiments: the lead webhook could not be built, nothing declared to the panel", error);
+        return { kind: "failed" };
+    }
+    if (!hook?.declareExperiments)
+        return { kind: "off" };
+    let outcome;
+    try {
+        outcome = hook.declareExperiments(experiments, options.summaries ?? {});
+    }
+    catch (error) {
+        log.error("experiments: the declaration could not be queued", error);
+        return { kind: "failed" };
+    }
+    if (outcome.kind === "queued") {
+        for (const { key, why } of outcome.skipped)
+            log.error(`experiments: ${key} is not declared to the panel: ${why}`);
+        hook.tick().catch((error) => log.error("experiments: sending the declaration failed; the outbox retries it", error));
+    }
+    return outcome;
+}