@evinvest/kitstart 0.11.0 → 0.12.0

package/README.md

@@ -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.11.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 {
@@ -678,6 +678,13 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   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
@@ -715,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,12 @@ 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.
@@ -73,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,12 @@ 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.
@@ -161,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

@@ -36,6 +36,12 @@ export type LeadStep = "need" | "contact";
  * 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", "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. */
@@ -62,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

@@ -58,6 +58,12 @@ export const ALLOWED_PROPS = [
     // 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. */
@@ -75,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/index.d.ts

@@ -13,10 +13,10 @@ export { flowTextOf, LEAD_CAPTURE_TEXT, type LeadCaptureFlowText, type LeadCaptu
 export { fillText, formatCents, openingText } from "./core/lead-capture-format.js";
 export { channelHref, resolveChannels, smsHref, type CaptureChannel, type ChannelFacts, type ChannelOptions, type ResolvedChannels, } from "./core/channels.js";
 export { checkTiming, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELDS, MIN_FILL_MS, RATE_LIMIT_MAX_KEYS, RateLimiter, RENDERED_AT_FIELD, screen, type Screening, } from "./core/antispam.js";
-export { createAcceptLead, EXPERIMENT_FIELD, FORM_ID_FIELD, leadRef, LOCALE_FIELD, LOCATION_FIELD, PRICE_CHANGED, SHOWN_CENTS_FIELD, VARIANT_FIELD, type AcceptDeps, type Outcome, type SubmitTags, } from "./core/accept.js";
+export { createAcceptLead, ANALYTICS_ID_FIELD, EXPERIMENT_FIELD, FORM_ID_FIELD, leadRef, LOCALE_FIELD, LOCATION_FIELD, PRICE_CHANGED, SHOWN_CENTS_FIELD, VARIANT_FIELD, type AcceptDeps, type Outcome, type SubmitTags, } from "./core/accept.js";
 export { areaServedNodes, breadcrumbNode, businessId, businessNode, faqPageNode, offerNodes, organizationId, organizationNode, placeGraph, websiteId, type OfferInput, type PageGraphCopy, type QuestionAnswer, } from "./core/seo/ld.js";
 export { AI_CRAWLERS, ogImageUrl, robotsFor, sitemapFor, type RobotsFile, type RobotsRule, type SitemapEntry, } from "./core/seo/sitemap.js";
-export { ALLOWED_PROPS, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, type AnalyticsTarget, type IntentChannel, type LeadField, type LeadStep, } from "./core/analytics.js";
+export { ALLOWED_PROPS, ANALYTICS_ID, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, type AnalyticsTarget, type IntentChannel, type LeadField, type LeadStep, } from "./core/analytics.js";
 export type { CallBarText, CopySlice, CoreText, PageMetaCopy, QuoteFormCopy, Said, StatusAction, StatusCopy, StatusScreenText, } from "./core/content.js";
 export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BookingConfigError, bookingConfigProblems, BOOKING_EXPERIMENT, bookingHref, bookingOf, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, parseBookingConfig, parseBookingRequest, PREFERRED_PARTS, type BookingChoice, type BookingConfig, type BookingPrefill, type BookingProvider, type BookingRequest, type BookingRequestedProperties, type BookingRules, type BookingStatus, type OpenBookingConfig, type PageProvider, type PreferredPart, } from "./core/booking/index.js";
 export { brandStatusTarget, statusTarget, thanksChannel, thanksSuffix, type StatusTarget } from "./core/status.js";

package/dist/index.js

@@ -13,10 +13,10 @@ export { flowTextOf, LEAD_CAPTURE_TEXT } from "./core/lead-capture-text.js";
 export { fillText, formatCents, openingText } from "./core/lead-capture-format.js";
 export { channelHref, resolveChannels, smsHref, } from "./core/channels.js";
 export { checkTiming, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELDS, MIN_FILL_MS, RATE_LIMIT_MAX_KEYS, RateLimiter, RENDERED_AT_FIELD, screen, } from "./core/antispam.js";
-export { createAcceptLead, EXPERIMENT_FIELD, FORM_ID_FIELD, leadRef, LOCALE_FIELD, LOCATION_FIELD, PRICE_CHANGED, SHOWN_CENTS_FIELD, VARIANT_FIELD, } from "./core/accept.js";
+export { createAcceptLead, ANALYTICS_ID_FIELD, EXPERIMENT_FIELD, FORM_ID_FIELD, leadRef, LOCALE_FIELD, LOCATION_FIELD, PRICE_CHANGED, SHOWN_CENTS_FIELD, VARIANT_FIELD, } from "./core/accept.js";
 export { areaServedNodes, breadcrumbNode, businessId, businessNode, faqPageNode, offerNodes, organizationId, organizationNode, placeGraph, websiteId, } from "./core/seo/ld.js";
 export { AI_CRAWLERS, ogImageUrl, robotsFor, sitemapFor, } from "./core/seo/sitemap.js";
-export { ALLOWED_PROPS, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, } from "./core/analytics.js";
+export { ALLOWED_PROPS, ANALYTICS_ID, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, } from "./core/analytics.js";
 export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BookingConfigError, bookingConfigProblems, BOOKING_EXPERIMENT, bookingHref, bookingOf, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, parseBookingConfig, parseBookingRequest, PREFERRED_PARTS, } from "./core/booking/index.js";
 export { brandStatusTarget, statusTarget, thanksChannel, thanksSuffix } from "./core/status.js";
 // A landing needs these beside the machinery; re-exported by name so a brand

package/dist/react/AnalyticsBoundary.js

@@ -2,9 +2,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ContactLinkTracker } from "@evinvest/marketing/tracker";
 import { usePathname } from "next/navigation.js";
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { analyticsSink, countsAsPageView, EVENTS, experimentProps } from "../core/analytics.js";
-import { AnalyticsSinkContext, experimentOf } from "./analytics-context.js";
+import { AnalyticsIdContext, AnalyticsSinkContext, experimentOf } from "./analytics-context.js";
+import { newSubmissionId } from "./use-lead-submit.js";
 /**
  * `data-intent` on a link or button marks a conversion intent that is not a
  * contact link — or one the tracker cannot classify (`sms:`).
@@ -35,7 +36,10 @@ function source() {
 export function AnalyticsBoundary({ target, placeSlug, children }) {
     // On the target's values: a server layout hands a fresh object every render.
     const { key, host, brandId } = target;
-    const sink = useMemo(() => analyticsSink({ key, host, brandId }, placeSlug), [key, host, brandId, placeSlug]);
+    // One visitor for the boundary's life, in memory only: a sink rebuilt for
+    // another place keeps it, and a lead posted from the page can name it.
+    const [distinctId] = useState(newSubmissionId);
+    const sink = useMemo(() => analyticsSink({ key, host, brandId }, placeSlug, distinctId), [key, host, brandId, placeSlug, distinctId]);
     const pathname = usePathname();
     useEffect(() => {
         if (!countsAsPageView(pathname))
@@ -57,5 +61,5 @@ export function AnalyticsBoundary({ target, placeSlug, children }) {
     }, [sink]);
     // A link inside an experiment's island (`LeadCapture`) carries the
     // assignment on itself, which is what the tracker reads.
-    return (_jsx(AnalyticsSinkContext.Provider, { value: sink, children: _jsx(ContactLinkTracker, { channels: ["phone", "whatsapp"], onContact: ({ channel, data }) => sink.capture(EVENTS.intent, { channel, ...experimentProps(data["experiment"], data["variant"]) }, { transport: "beacon" }), children: children }) }));
+    return (_jsx(AnalyticsIdContext.Provider, { value: key ? distinctId : null, children: _jsx(AnalyticsSinkContext.Provider, { value: sink, children: _jsx(ContactLinkTracker, { channels: ["phone", "whatsapp"], onContact: ({ channel, data }) => sink.capture(EVENTS.intent, { channel, ...experimentProps(data["experiment"], data["variant"]) }, { transport: "beacon" }), children: children }) }) }));
 }

package/dist/react/analytics-context.d.ts

@@ -7,5 +7,12 @@ import { experimentProps } from "../core/analytics.js";
  */
 export declare const AnalyticsSinkContext: import("react").Context<AnalyticsSink | null>;
 export declare const useAnalyticsSink: () => AnalyticsSink | null;
+/**
+ * The `distinct_id` the boundary's sink sends, for a lead to carry to the
+ * panel. `null` outside a boundary or with no key: no event names it, so a
+ * lead has nothing to join.
+ */
+export declare const AnalyticsIdContext: import("react").Context<string | null>;
+export declare const useAnalyticsId: () => string | null;
 /** `data-experiment` / `data-variant` on an element or its ancestors, for an intent's event. */
 export declare function experimentOf(el: Element | null): ReturnType<typeof experimentProps>;

package/dist/react/analytics-context.js

@@ -8,6 +8,13 @@ import { experimentProps } from "../core/analytics.js";
  */
 export const AnalyticsSinkContext = createContext(null);
 export const useAnalyticsSink = () => useContext(AnalyticsSinkContext);
+/**
+ * The `distinct_id` the boundary's sink sends, for a lead to carry to the
+ * panel. `null` outside a boundary or with no key: no event names it, so a
+ * lead has nothing to join.
+ */
+export const AnalyticsIdContext = createContext(null);
+export const useAnalyticsId = () => useContext(AnalyticsIdContext);
 /** `data-experiment` / `data-variant` on an element or its ancestors, for an intent's event. */
 export function experimentOf(el) {
     const host = el?.closest("[data-experiment]");

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) };
 /**
@@ -98,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)
@@ -111,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() : "";

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;
+}

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

@@ -0,0 +1,49 @@
+import "server-only";
+/**
+ * An operator's override of one experiment, as the panel serves it — the
+ * shape `applyOverrides` of `@evinvest/experiments` takes. Only the types are
+ * checked here; whether a field fits the experiment in code (weights of the
+ * right length, a holdout in `[0, 1)`) is `applyOverrides`' call, because only
+ * it knows the code's variants.
+ */
+export interface ExperimentOverride {
+    readonly enabled?: boolean;
+    readonly weights?: readonly number[];
+    readonly holdout?: number;
+}
+export type ExperimentOverrides = Readonly<Record<string, ExperimentOverride>>;
+/**
+ * The operator's overrides of the brand's experiments: `GET
+ * <base>/experiments`, the panel's `{ "experiments": { "<key>": {…} } }`.
+ *
+ * Read by the proxy on every request, so the answer comes from memory: the
+ * first call waits for the panel (bounded by `timeoutMs`), every later one is
+ * served from the cache — past the TTL too, while one refresh runs behind it
+ * (stale-while-revalidate). The source never throws and never makes a page
+ * wait on the panel twice. A failed refresh — an unreachable panel, a
+ * non-200, a body that is not the panel's shape — keeps the last good answer:
+ * a kill switch must not turn itself back on because the panel blinked. With
+ * no good answer yet (or no base URL) it is `{}`, the config in code.
+ */
+export interface ExperimentsSourceOptions {
+    /** The brand's base on the panel (`LOCATIONS_API_URL`), read when asked; `null` → no overrides. */
+    baseUrl: () => string | null;
+    /** How long an answer is fresh; 30 s. */
+    ttlMs?: number;
+    /** How long the panel is given; 1.5 s. The proxy is waiting on the first call. */
+    timeoutMs?: number;
+    now?: () => number;
+    log?: Pick<Console, "error">;
+}
+export interface ExperimentsSource {
+    /** The overrides to apply now; `{}` when there are none or the panel cannot say. Never throws. */
+    overrides(): Promise<ExperimentOverrides>;
+}
+export declare const EXPERIMENTS_TTL_MS = 30000;
+/**
+ * The panel's answer as overrides, or `null` when it is not the panel's shape.
+ * A field of the wrong type is dropped, an entry that is not an object is
+ * skipped; the rest stands.
+ */
+export declare function parseExperimentOverrides(body: unknown): ExperimentOverrides | null;
+export declare function createExperimentsSource(options: ExperimentsSourceOptions): ExperimentsSource;

package/dist/server/experiments-source.js

@@ -0,0 +1,88 @@
+import "server-only";
+export const EXPERIMENTS_TTL_MS = 30_000;
+const TIMEOUT_MS = 1_500;
+const NONE = Object.freeze({});
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The panel's answer as overrides, or `null` when it is not the panel's shape.
+ * A field of the wrong type is dropped, an entry that is not an object is
+ * skipped; the rest stands.
+ */
+export function parseExperimentOverrides(body) {
+    if (!isRecord(body) || !isRecord(body["experiments"]))
+        return null;
+    const out = {};
+    for (const [key, entry] of Object.entries(body["experiments"])) {
+        if (!isRecord(entry))
+            continue;
+        const { enabled, weights, holdout } = entry;
+        out[key] = {
+            ...(typeof enabled === "boolean" ? { enabled } : {}),
+            ...(Array.isArray(weights) && weights.every((w) => typeof w === "number") ? { weights } : {}),
+            ...(typeof holdout === "number" ? { holdout } : {}),
+        };
+    }
+    return out;
+}
+export function createExperimentsSource(options) {
+    const ttl = options.ttlMs ?? EXPERIMENTS_TTL_MS;
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const log = options.log ?? console;
+    let cached = null;
+    let inflight = null;
+    /** The panel's overrides, or `null` when it could not say. */
+    async function load(base) {
+        let response;
+        try {
+            // `no-store`: the cache is this module's; Next's data cache would add a second TTL.
+            response = await fetch(`${base}/experiments`, { cache: "no-store", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch (cause) {
+            log.error("experiments: the panel is unreachable, keeping the last good overrides", cause);
+            return null;
+        }
+        if (response.status !== 200) {
+            log.error(`experiments: the panel answered ${response.status}, keeping the last good overrides`);
+            return null;
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (cause) {
+            log.error("experiments: the panel's body is not JSON, keeping the last good overrides", cause);
+            return null;
+        }
+        const parsed = parseExperimentOverrides(body);
+        if (parsed === null)
+            log.error("experiments: the panel's body is not { experiments: {…} }, keeping the last good overrides");
+        return parsed;
+    }
+    // One request at a time, however many visitors arrive while it runs.
+    function refresh(base) {
+        inflight ??= load(base)
+            .then(loaded => {
+            // A failure still restarts the clock, so a down panel is asked once per TTL.
+            const value = loaded ?? (cached?.base === base ? cached.value : NONE);
+            cached = { base, at: now(), value };
+            return value;
+        })
+            .finally(() => {
+            inflight = null;
+        });
+        return inflight;
+    }
+    return {
+        async overrides() {
+            const base = options.baseUrl();
+            if (!base)
+                return NONE;
+            if (cached?.base !== base)
+                return refresh(base);
+            if (now() - cached.at >= ttl)
+                void refresh(base);
+            return cached.value;
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -6,6 +6,8 @@
 import "server-only";
 export { createServerEnv, parseServerEnv, type EnvSource, type ServerEnv } from "./env.js";
 export { createPlaceSource, PLACE_REVALIDATE_SECONDS, PlaceSourceError, type PlaceSource, type PlaceSourceOptions } from "./place-source.js";
+export { createExperimentsSource, EXPERIMENTS_TTL_MS, parseExperimentOverrides, type ExperimentOverride, type ExperimentOverrides, type ExperimentsSource, type ExperimentsSourceOptions, } from "./experiments-source.js";
+export { declarationProblem, declareExperiments, experimentsDeclaredBody, type DeclarationContext, type DeclaredExperiment, type DeclareOptions, type DeclareOutcome, type ExperimentDeclarationV1, type ExperimentsDeclaration, type ExperimentsDeclaredEvent, } from "./experiments-declared.js";
 export { createPricingSource, type PricingSource, type PricingSourceOptions } from "./pricing-source.js";
 export { describeLeadDb, openLeadStore, parseLeadDb, type LeadDb } from "./lead-store.js";
 export { openSqliteLeadStore, type SqliteLeadStore } from "./lead-store-sqlite.js";

package/dist/server/index.js

@@ -6,6 +6,8 @@
 import "server-only";
 export { createServerEnv, parseServerEnv } from "./env.js";
 export { createPlaceSource, PLACE_REVALIDATE_SECONDS, PlaceSourceError } from "./place-source.js";
+export { createExperimentsSource, EXPERIMENTS_TTL_MS, parseExperimentOverrides, } from "./experiments-source.js";
+export { declarationProblem, declareExperiments, experimentsDeclaredBody, } from "./experiments-declared.js";
 export { createPricingSource } from "./pricing-source.js";
 export { describeLeadDb, openLeadStore, parseLeadDb } from "./lead-store.js";
 export { openSqliteLeadStore } from "./lead-store-sqlite.js";

package/dist/server/lead-webhook.d.ts

@@ -3,6 +3,7 @@ import type { BookingRequest } from "../core/booking/model.js";
 import { type Lead, type LeadChannel, type LeadSuspect } from "../core/lead.js";
 import type { LeadFlow } from "../core/pricing/flow.js";
 import type { ServerEnv } from "./env.js";
+import { type DeclareOutcome, type ExperimentsDeclaration } from "./experiments-declared.js";
 import { type TickReport, type WebhookOutbox, type WebhookOutboxOptions } from "./webhook-outbox.js";
 import type { WebhookSigning } from "./webhook-signature.js";
 /** What the brand's body builder is told besides the lead. */
@@ -34,6 +35,14 @@ export interface LeadWebhookContext {
      * the properties. `panelFlowProperties` writes them as the panel reads them.
      */
     flow?: PanelFlow;
+    /**
+     * The visitor's analytics id as the page posted it (`ANALYTICS_ID_FIELD`),
+     * for `lead.created`'s `analytics_id` — so PostHog joins the lead to the
+     * visit. Absent from a page without the script, an older page, or one
+     * without analytics. Write it only once the panel's contract has the
+     * property: it refuses an unknown one, and the outbox would park the lead.
+     */
+    analyticsId?: string;
 }
 /** A lead's sale as the panel's `lead.created` may carry it. */
 export interface PanelFlow {
@@ -108,6 +117,7 @@ export interface LeadWebhook {
         locale: string;
         formId: string;
         leadRef?: string;
+        analyticsId?: string;
     }): number;
     tick(): Promise<TickReport>;
     start(intervalMs?: number): void;
@@ -129,6 +139,13 @@ export interface LeadWebhook {
      * suspect held back); `off` without `panelBooking` or a `buildBookingBody`.
      */
     requestBooking?(request: BookingRequest): BookingQueued;
+    /**
+     * Queues `experiments.declared@1` — the experiments this build runs — in
+     * the same outbox, signed as a lead is. Experiments the panel would refuse
+     * are left out and listed in `skipped`. `declareExperiments` is the safe
+     * wrapper for a start.
+     */
+    declareExperiments?(experiments: ExperimentsDeclaration, summaries?: Readonly<Record<string, string>>): DeclareOutcome;
     readonly outbox: WebhookOutbox;
 }
 export interface LeadWebhookOptions extends WebhookOutboxOptions {

package/dist/server/lead-webhook.js

@@ -1,6 +1,7 @@
 import "server-only";
 import { randomUUID } from "node:crypto";
 import { suspectOf } from "../core/lead.js";
+import { experimentsDeclaredBody } from "./experiments-declared.js";
 import { openWebhookOutbox } from "./webhook-outbox.js";
 /** The sale `ctx.flow` describes, or nothing for a lead without a flow. */
 export function panelFlowOf(lead) {
@@ -45,6 +46,7 @@ export function leadWebhook(site, env, options) {
         throw new Error("LEAD_WEBHOOK_URL: the webhook outbox needs the sqlite lead store");
     const outbox = openWebhookOutbox(env.leadsDb.path, { ...env.leadWebhook, signing }, outboxOptions);
     const now = options.now ?? Date.now;
+    const sourceId = env.leadWebhook.keyId;
     return {
         outbox,
         panelSuspect,
@@ -65,6 +67,11 @@ export function leadWebhook(site, env, options) {
             const row = outbox.enqueueOnce(body, `booking:${request.leadRef}`, lead);
             return row === null ? { kind: "duplicate" } : { kind: "queued", row };
         },
+        declareExperiments(experiments, summaries) {
+            const { body, skipped } = experimentsDeclaredBody(experiments, { brandId: site.brand.id, sourceId, at: new Date(now()), ...(summaries ? { summaries } : {}) });
+            const row = outbox.enqueue(JSON.stringify(body), `experiments:${body.events[0].id}`);
+            return { kind: "queued", row, skipped };
+        },
         enqueue(lead, id, meta) {
             const suspect = panelSuspect ? suspectOf(lead) : undefined;
             const flow = panelFlow ? panelFlowOf(lead) : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evinvest/kitstart",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Landing-site machinery for local-service brands: a site composition root, the Place/Presence/ServiceArea model with a publication gate, host/locale routing, schema.org and SEO builders, the lead funnel with its antispam, and analytics events. Pure core at '.', more subpaths per runtime.",
   "license": "BlueOak-1.0.0",
   "publishConfig": {

package/template/flake.nix

@@ -3,7 +3,7 @@
     v_flakes.url = "github:valeratrades/v_flakes?ref=v1.6";
     # The lib flake at the tag of the @evinvest/kitstart version in
     # package-lock.json — mkLanding refuses a mismatch.
-    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.11.0";
+    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.12.0";
     ev.inputs.v_flakes.follows = "v_flakes";
   };
 

package/template/package.json

@@ -20,7 +20,7 @@
   "dependencies": {
     "@evinvest/analytics": "^0.3.0",
     "@evinvest/i18n": "^0.9.0",
-    "@evinvest/kitstart": "^0.11.0",
+    "@evinvest/kitstart": "^0.12.0",
     "@evinvest/marketing": "^0.3.0",
     "@evinvest/uikit": "^0.26.0",
     "next": "16.3.6",