@webiny/website-builder-sdk 6.4.11 → 6.6.0-alpha.1

package/experiments/bucketing.test.js

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { assignVariant, forcedAssignment, hashToUnit, matchesTargeting } from "./bucketing.js";
+import { CONTROL_VARIANT_ID } from "./types.js";
+const experiment = (overrides = {})=>({
+        experimentId: "exp-1",
+        revisionId: "page-1#0001",
+        pageEntryId: "page-1",
+        path: "/pricing",
+        status: "running",
+        tenantId: "root",
+        controlVariantId: CONTROL_VARIANT_ID,
+        trafficSplit: {
+            control: 50,
+            variants: {
+                "variant-a": 50
+            }
+        },
+        targeting: {
+            trafficPercentage: 100
+        },
+        analytics: {
+            provider: "posthog"
+        },
+        variants: [
+            {
+                variantId: "variant-a",
+                name: "Variant A"
+            }
+        ],
+        ...overrides
+    });
+const visitor = (overrides = {})=>({
+        visitorId: "visitor-1",
+        ...overrides
+    });
+describe("hashToUnit", ()=>{
+    it("is deterministic and within [0, 1)", ()=>{
+        const a = hashToUnit("visitor-1:exp-1");
+        const b = hashToUnit("visitor-1:exp-1");
+        expect(a).toBe(b);
+        expect(a).toBeGreaterThanOrEqual(0);
+        expect(a).toBeLessThan(1);
+    });
+    it("differs across seeds", ()=>{
+        expect(hashToUnit("visitor-1:exp-1")).not.toBe(hashToUnit("visitor-2:exp-1"));
+    });
+});
+describe("assignVariant", ()=>{
+    it("assigns the same visitor to the same bucket every time", ()=>{
+        const first = assignVariant(experiment(), visitor());
+        const second = assignVariant(experiment(), visitor());
+        expect(second).toEqual(first);
+    });
+    it("buckets the same visitor differently across experiments", ()=>{
+        const a = assignVariant(experiment({
+            experimentId: "exp-1"
+        }), visitor());
+        const b = assignVariant(experiment({
+            experimentId: "exp-2"
+        }), visitor());
+        expect(hashToUnit("visitor-1:exp-1")).not.toBe(hashToUnit("visitor-1:exp-2"));
+        expect([
+            a.variantId,
+            b.variantId
+        ].every(Boolean)).toBe(true);
+    });
+    it("respects the traffic split distribution", ()=>{
+        const exp = experiment({
+            trafficSplit: {
+                control: 80,
+                variants: {
+                    "variant-a": 20
+                }
+            }
+        });
+        let control = 0;
+        let variant = 0;
+        for(let i = 0; i < 5000; i++){
+            const assignment = assignVariant(exp, visitor({
+                visitorId: `v-${i}`
+            }));
+            if (assignment.isControl) control++;
+            else variant++;
+        }
+        const variantShare = variant / (control + variant);
+        expect(variantShare).toBeGreaterThan(0.15);
+        expect(variantShare).toBeLessThan(0.25);
+    });
+    it("excludes visitors outside the traffic percentage and serves control", ()=>{
+        const exp = experiment({
+            targeting: {
+                trafficPercentage: 0
+            }
+        });
+        const assignment = assignVariant(exp, visitor());
+        expect(assignment.isControl).toBe(true);
+        expect(assignment.excluded).toBe(true);
+    });
+    it("excludes visitors who do not match geo targeting", ()=>{
+        const exp = experiment({
+            targeting: {
+                trafficPercentage: 100,
+                geo: [
+                    "GB"
+                ]
+            }
+        });
+        const assignment = assignVariant(exp, visitor({
+            country: "US"
+        }));
+        expect(assignment.excluded).toBe(true);
+        expect(assignment.isControl).toBe(true);
+    });
+    it("ignores variants that are not ready", ()=>{
+        const exp = experiment({
+            trafficSplit: {
+                control: 0,
+                variants: {
+                    "variant-a": 50,
+                    "variant-ghost": 50
+                }
+            },
+            variants: [
+                {
+                    variantId: "variant-a",
+                    name: "Variant A"
+                }
+            ]
+        });
+        for(let i = 0; i < 200; i++){
+            const assignment = assignVariant(exp, visitor({
+                visitorId: `v-${i}`
+            }));
+            expect(assignment.variantId).not.toBe("variant-ghost");
+        }
+    });
+});
+describe("matchesTargeting", ()=>{
+    it("matches when no geo/device restriction is set", ()=>{
+        expect(matchesTargeting({
+            trafficPercentage: 100
+        }, visitor())).toBe(true);
+    });
+    it("matches device targeting", ()=>{
+        expect(matchesTargeting({
+            trafficPercentage: 100,
+            device: [
+                "mobile"
+            ]
+        }, visitor({
+            device: "mobile"
+        }))).toBe(true);
+        expect(matchesTargeting({
+            trafficPercentage: 100,
+            device: [
+                "mobile"
+            ]
+        }, visitor({
+            device: "desktop"
+        }))).toBe(false);
+    });
+});
+describe("forcedAssignment", ()=>{
+    it("forces a ready variant and marks it as not counted", ()=>{
+        const assignment = forcedAssignment(experiment(), "variant-a");
+        expect(assignment).toEqual({
+            variantId: "variant-a",
+            isControl: false,
+            excluded: false,
+            forced: true
+        });
+    });
+    it("forces the control bucket", ()=>{
+        const assignment = forcedAssignment(experiment(), CONTROL_VARIANT_ID);
+        expect(assignment?.isControl).toBe(true);
+        expect(assignment?.forced).toBe(true);
+    });
+    it("returns null for an unknown variant", ()=>{
+        expect(forcedAssignment(experiment(), "nope")).toBeNull();
+    });
+});
+
+//# sourceMappingURL=bucketing.test.js.map

package/experiments/bucketing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/bucketing.test.js","sources":["../../src/experiments/bucketing.test.ts"],"sourcesContent":["import { describe, it, expect } from \"vitest\";\nimport { assignVariant, forcedAssignment, hashToUnit, matchesTargeting } from \"./bucketing.js\";\nimport { CONTROL_VARIANT_ID, type ActiveExperiment, type VisitorContext } from \"./types.js\";\n\nconst experiment = (overrides: Partial<ActiveExperiment> = {}): ActiveExperiment => ({\n    experimentId: \"exp-1\",\n    revisionId: \"page-1#0001\",\n    pageEntryId: \"page-1\",\n    path: \"/pricing\",\n    status: \"running\",\n    tenantId: \"root\",\n    controlVariantId: CONTROL_VARIANT_ID,\n    trafficSplit: { control: 50, variants: { \"variant-a\": 50 } },\n    targeting: { trafficPercentage: 100 },\n    analytics: { provider: \"posthog\" },\n    variants: [{ variantId: \"variant-a\", name: \"Variant A\" }],\n    ...overrides\n});\n\nconst visitor = (overrides: Partial<VisitorContext> = {}): VisitorContext => ({\n    visitorId: \"visitor-1\",\n    ...overrides\n});\n\ndescribe(\"hashToUnit\", () => {\n    it(\"is deterministic and within [0, 1)\", () => {\n        const a = hashToUnit(\"visitor-1:exp-1\");\n        const b = hashToUnit(\"visitor-1:exp-1\");\n        expect(a).toBe(b);\n        expect(a).toBeGreaterThanOrEqual(0);\n        expect(a).toBeLessThan(1);\n    });\n\n    it(\"differs across seeds\", () => {\n        expect(hashToUnit(\"visitor-1:exp-1\")).not.toBe(hashToUnit(\"visitor-2:exp-1\"));\n    });\n});\n\ndescribe(\"assignVariant\", () => {\n    it(\"assigns the same visitor to the same bucket every time\", () => {\n        const first = assignVariant(experiment(), visitor());\n        const second = assignVariant(experiment(), visitor());\n        expect(second).toEqual(first);\n    });\n\n    it(\"buckets the same visitor differently across experiments\", () => {\n        const a = assignVariant(experiment({ experimentId: \"exp-1\" }), visitor());\n        const b = assignVariant(experiment({ experimentId: \"exp-2\" }), visitor());\n        // Not guaranteed to differ, but the seed differs; assert the seeds are independent.\n        expect(hashToUnit(\"visitor-1:exp-1\")).not.toBe(hashToUnit(\"visitor-1:exp-2\"));\n        expect([a.variantId, b.variantId].every(Boolean)).toBe(true);\n    });\n\n    it(\"respects the traffic split distribution\", () => {\n        const exp = experiment({\n            trafficSplit: { control: 80, variants: { \"variant-a\": 20 } }\n        });\n        let control = 0;\n        let variant = 0;\n        for (let i = 0; i < 5000; i++) {\n            const assignment = assignVariant(exp, visitor({ visitorId: `v-${i}` }));\n            if (assignment.isControl) {\n                control++;\n            } else {\n                variant++;\n            }\n        }\n        const variantShare = variant / (control + variant);\n        // Expect ~20% in the variant, allow a generous tolerance.\n        expect(variantShare).toBeGreaterThan(0.15);\n        expect(variantShare).toBeLessThan(0.25);\n    });\n\n    it(\"excludes visitors outside the traffic percentage and serves control\", () => {\n        const exp = experiment({ targeting: { trafficPercentage: 0 } });\n        const assignment = assignVariant(exp, visitor());\n        expect(assignment.isControl).toBe(true);\n        expect(assignment.excluded).toBe(true);\n    });\n\n    it(\"excludes visitors who do not match geo targeting\", () => {\n        const exp = experiment({ targeting: { trafficPercentage: 100, geo: [\"GB\"] } });\n        const assignment = assignVariant(exp, visitor({ country: \"US\" }));\n        expect(assignment.excluded).toBe(true);\n        expect(assignment.isControl).toBe(true);\n    });\n\n    it(\"ignores variants that are not ready\", () => {\n        const exp = experiment({\n            trafficSplit: { control: 0, variants: { \"variant-a\": 50, \"variant-ghost\": 50 } },\n            variants: [{ variantId: \"variant-a\", name: \"Variant A\" }]\n        });\n        for (let i = 0; i < 200; i++) {\n            const assignment = assignVariant(exp, visitor({ visitorId: `v-${i}` }));\n            expect(assignment.variantId).not.toBe(\"variant-ghost\");\n        }\n    });\n});\n\ndescribe(\"matchesTargeting\", () => {\n    it(\"matches when no geo/device restriction is set\", () => {\n        expect(matchesTargeting({ trafficPercentage: 100 }, visitor())).toBe(true);\n    });\n\n    it(\"matches device targeting\", () => {\n        expect(\n            matchesTargeting(\n                { trafficPercentage: 100, device: [\"mobile\"] },\n                visitor({ device: \"mobile\" })\n            )\n        ).toBe(true);\n        expect(\n            matchesTargeting(\n                { trafficPercentage: 100, device: [\"mobile\"] },\n                visitor({ device: \"desktop\" })\n            )\n        ).toBe(false);\n    });\n});\n\ndescribe(\"forcedAssignment\", () => {\n    it(\"forces a ready variant and marks it as not counted\", () => {\n        const assignment = forcedAssignment(experiment(), \"variant-a\");\n        expect(assignment).toEqual({\n            variantId: \"variant-a\",\n            isControl: false,\n            excluded: false,\n            forced: true\n        });\n    });\n\n    it(\"forces the control bucket\", () => {\n        const assignment = forcedAssignment(experiment(), CONTROL_VARIANT_ID);\n        expect(assignment?.isControl).toBe(true);\n        expect(assignment?.forced).toBe(true);\n    });\n\n    it(\"returns null for an unknown variant\", () => {\n        expect(forcedAssignment(experiment(), \"nope\")).toBeNull();\n    });\n});\n"],"names":["experiment","overrides","CONTROL_VARIANT_ID","visitor","describe","it","a","hashToUnit","b","expect","first","assignVariant","second","Boolean","exp","control","variant","i","assignment","variantShare","matchesTargeting","forcedAssignment"],"mappings":"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"}

package/experiments/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./bucketing.js";
+export * from "./analyticsProvider.js";
+export * from "./PostHogAnalyticsProvider.js";
+export * from "./render.js";

package/experiments/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./bucketing.js";
+export * from "./analyticsProvider.js";
+export * from "./PostHogAnalyticsProvider.js";
+export * from "./render.js";

package/experiments/render.d.ts

@@ -0,0 +1,79 @@
+import type { PublicPage } from "../types.js";
+import type { ActiveExperiment, DeviceType, VariantAssignment, VariantContent, VisitorContext } from "./types.js";
+/** The cookie that persists the stable visitor id used for deterministic bucketing. */
+export declare const DEFAULT_VISITOR_COOKIE = "wb_ab_vid";
+/** Default query parameter used to force a variant for QA/review. */
+export declare const FORCED_VARIANT_PARAM = "wb-variant";
+/** The minimal data surface the render helper needs. ContentSdk satisfies this. */
+export interface ExperimentSdk {
+    getPage(path: string): Promise<PublicPage | null>;
+    getPageExperiment(path: string): Promise<ActiveExperiment | null>;
+    getVariantContent(variantId: string): Promise<VariantContent | null>;
+    /** Runtime kill-switch check. When omitted, the pause state is not consulted. */
+    getExperimentPaused?(experimentId: string): Promise<boolean>;
+}
+export interface ExperimentCookie {
+    name: string;
+    value: string;
+    maxAge: number;
+}
+export interface GetPageWithExperimentOptions {
+    /** Forced variant id (from the `?wb-variant=` query parameter). Overrides bucketing, never counted. */
+    forcedVariantId?: string;
+    /**
+     * Request query parameters. When provided, the forced variant is read from
+     * `searchParams[FORCED_VARIANT_PARAM]` unless `forcedVariantId` is set explicitly. Convenient
+     * for framework handlers that already have the parsed query (e.g. Next.js `searchParams`).
+     */
+    searchParams?: Record<string, string | string[] | undefined>;
+    /** Explicit visitor id. When omitted, it is read from the cookie or generated. */
+    visitorId?: string;
+    /** Explicit ISO country code. When omitted, it is read from common CDN geo headers. */
+    country?: string;
+    /** Explicit device type. When omitted, it is derived from the user agent. */
+    device?: DeviceType;
+    /** Header names to read the visitor country from, in priority order. */
+    geoHeaders?: string[];
+    /** Bucketing cookie name. Defaults to `wb_ab_vid`. */
+    cookieName?: string;
+    /** Bucketing cookie max age in seconds. Defaults to one year. */
+    cookieMaxAge?: number;
+    /** Set false to skip exposure emission (e.g. when consent has not been granted). */
+    emitExposure?: boolean;
+    /** Visitor id generator. Defaults to nanoid. */
+    generateVisitorId?: () => string;
+}
+export interface ExperimentRenderResult {
+    /** The content to render server-side: the baseline (control) or a variant overlay. */
+    page: PublicPage | null;
+    /** The active experiment, or null when there is none for the path. */
+    experiment: ActiveExperiment | null;
+    /** The visitor's assignment, or null when no experiment applies. */
+    assignment: VariantAssignment | null;
+    /**
+     * Set when the caller should persist the bucketing cookie (i.e. a visitor id was generated
+     * this request). Persisting it in a Route Handler / middleware keeps bucketing stable.
+     */
+    cookie?: ExperimentCookie;
+}
+/**
+ * Resolve request-time visitor context from request headers/cookies. Never uses a logged-in
+ * identity. Returns whether a visitor id was generated, so the caller can persist the cookie.
+ */
+export declare const resolveVisitorContext: (options?: GetPageWithExperimentOptions) => Promise<{
+    context: VisitorContext;
+    generatedVisitorId: boolean;
+}>;
+/**
+ * Resolve and render the right page for a visitor, server-side, with no client-side content
+ * swap.
+ *
+ * Caching contract (important — handled here so projects do not reimplement it):
+ *  - The baseline (control) is fetched via `getPage(path)` and caches per path.
+ *  - The active experiment metadata is fetched via `getPageExperiment(path)` and caches per path.
+ *  - A variant's content is fetched via `getVariantContent(variantId)` and caches per variant id.
+ * Every request therefore resolves to one of a small, fixed set of cacheable objects keyed by
+ * (path) or (variant id) — NEVER by the raw visitor id. Each active variant adds exactly one
+ * cacheable object per URL.
+ */
+export declare const getPageWithExperiment: (sdk: ExperimentSdk, path: string, options?: GetPageWithExperimentOptions) => Promise<ExperimentRenderResult>;

package/experiments/render.js

@@ -0,0 +1,149 @@
+import { nanoid } from "nanoid";
+import { getHeadersProvider } from "../headersProvider.js";
+import { assignVariant, forcedAssignment } from "./bucketing.js";
+import { getAnalyticsProvider } from "./analyticsProvider.js";
+const DEFAULT_VISITOR_COOKIE = "wb_ab_vid";
+const FORCED_VARIANT_PARAM = "wb-variant";
+const DEFAULT_GEO_HEADERS = [
+    "x-vercel-ip-country",
+    "cloudfront-viewer-country",
+    "cf-ipcountry",
+    "x-country-code"
+];
+const readCookie = (cookieHeader, name)=>{
+    if (!cookieHeader) return;
+    for (const part of cookieHeader.split(";")){
+        const index = part.indexOf("=");
+        if (-1 === index) continue;
+        const key = part.slice(0, index).trim();
+        if (key === name) return decodeURIComponent(part.slice(index + 1).trim());
+    }
+};
+const detectDevice = (userAgent)=>{
+    if (!userAgent) return;
+    if (/iPad|Tablet|PlayBook|Silk/i.test(userAgent)) return "tablet";
+    if (/Mobi|Android.+Mobile|iPhone|iPod|Windows Phone/i.test(userAgent)) return "mobile";
+    return "desktop";
+};
+const resolveVisitorContext = async (options = {})=>{
+    const cookieName = options.cookieName ?? DEFAULT_VISITOR_COOKIE;
+    const generate = options.generateVisitorId ?? (()=>nanoid());
+    let headers;
+    const provider = getHeadersProvider();
+    if (provider) try {
+        headers = await provider();
+    } catch  {
+        headers = void 0;
+    }
+    let visitorId = options.visitorId;
+    let generatedVisitorId = false;
+    if (!visitorId) visitorId = readCookie(headers?.get("cookie"), cookieName);
+    if (!visitorId) {
+        visitorId = generate();
+        generatedVisitorId = true;
+    }
+    let country = options.country;
+    if (!country && headers) for (const header of options.geoHeaders ?? DEFAULT_GEO_HEADERS){
+        const value = headers.get(header);
+        if (value) {
+            country = value.toUpperCase();
+            break;
+        }
+    }
+    const device = options.device ?? detectDevice(headers?.get("user-agent"));
+    return {
+        context: {
+            visitorId,
+            country,
+            device
+        },
+        generatedVisitorId
+    };
+};
+const resolveForcedVariantId = (options)=>{
+    if (options.forcedVariantId) return options.forcedVariantId;
+    const raw = options.searchParams?.[FORCED_VARIANT_PARAM];
+    return Array.isArray(raw) ? raw[0] : raw;
+};
+const overlayVariant = (baseline, variant)=>({
+        ...baseline,
+        properties: variant.properties,
+        bindings: variant.bindings,
+        elements: variant.elements,
+        extensions: variant.extensions,
+        metadata: variant.metadata
+    });
+const getPageWithExperiment = async (sdk, path, options = {})=>{
+    const [controlPage, experiment] = await Promise.all([
+        sdk.getPage(path),
+        sdk.getPageExperiment(path)
+    ]);
+    if (!experiment || !controlPage) return {
+        page: controlPage,
+        experiment: experiment ?? null,
+        assignment: null
+    };
+    if ("running" !== experiment.status) return {
+        page: controlPage,
+        experiment,
+        assignment: null
+    };
+    if (sdk.getExperimentPaused) {
+        const paused = await sdk.getExperimentPaused(experiment.experimentId).catch(()=>false);
+        if (paused) return {
+            page: controlPage,
+            experiment,
+            assignment: null
+        };
+    }
+    const forcedVariantId = resolveForcedVariantId(options);
+    const { context, generatedVisitorId } = await resolveVisitorContext(options);
+    let assignment = null;
+    if (forcedVariantId) assignment = forcedAssignment(experiment, forcedVariantId);
+    if (!assignment) assignment = assignVariant(experiment, context);
+    let page = controlPage;
+    if (!assignment.isControl) {
+        const variant = await sdk.getVariantContent(assignment.variantId);
+        if (variant) page = overlayVariant(controlPage, variant);
+        else assignment = {
+            variantId: experiment.controlVariantId,
+            isControl: true,
+            excluded: assignment.excluded,
+            forced: assignment.forced
+        };
+    }
+    const shouldEmit = (options.emitExposure ?? true) && !assignment.excluded && !assignment.forced;
+    if (shouldEmit) {
+        const provider = getAnalyticsProvider(experiment.analytics.provider);
+        if (provider) {
+            const experimentKey = "string" == typeof experiment.analytics.experimentKey ? experiment.analytics.experimentKey : void 0;
+            try {
+                await provider.emitExposure({
+                    experimentId: experiment.experimentId,
+                    experimentKey,
+                    variantId: assignment.variantId,
+                    revisionId: experiment.revisionId,
+                    tenantId: experiment.tenantId,
+                    visitorId: context.visitorId,
+                    pageId: experiment.pageEntryId,
+                    path: experiment.path,
+                    timestamp: new Date().toISOString()
+                });
+            } catch  {}
+        }
+    }
+    const result = {
+        page,
+        experiment,
+        assignment
+    };
+    if (generatedVisitorId) result.cookie = {
+        name: options.cookieName ?? DEFAULT_VISITOR_COOKIE,
+        value: context.visitorId,
+        maxAge: options.cookieMaxAge ?? 31536000
+    };
+    return result;
+};
+export { DEFAULT_VISITOR_COOKIE, FORCED_VARIANT_PARAM, getPageWithExperiment, resolveVisitorContext };
+
+//# sourceMappingURL=render.js.map

package/experiments/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/render.js","sources":["../../src/experiments/render.ts"],"sourcesContent":["import { nanoid } from \"nanoid\";\nimport type { PublicPage } from \"~/types.js\";\nimport { getHeadersProvider } from \"~/headersProvider.js\";\nimport { assignVariant, forcedAssignment } from \"./bucketing.js\";\nimport { getAnalyticsProvider } from \"./analyticsProvider.js\";\nimport type {\n    ActiveExperiment,\n    DeviceType,\n    VariantAssignment,\n    VariantContent,\n    VisitorContext\n} from \"./types.js\";\n\n/** The cookie that persists the stable visitor id used for deterministic bucketing. */\nexport const DEFAULT_VISITOR_COOKIE = \"wb_ab_vid\";\n\n/** Default query parameter used to force a variant for QA/review. */\nexport const FORCED_VARIANT_PARAM = \"wb-variant\";\n\nconst DEFAULT_GEO_HEADERS = [\n    \"x-vercel-ip-country\",\n    \"cloudfront-viewer-country\",\n    \"cf-ipcountry\",\n    \"x-country-code\"\n];\n\n/** The minimal data surface the render helper needs. ContentSdk satisfies this. */\nexport interface ExperimentSdk {\n    getPage(path: string): Promise<PublicPage | null>;\n    getPageExperiment(path: string): Promise<ActiveExperiment | null>;\n    getVariantContent(variantId: string): Promise<VariantContent | null>;\n    /** Runtime kill-switch check. When omitted, the pause state is not consulted. */\n    getExperimentPaused?(experimentId: string): Promise<boolean>;\n}\n\nexport interface ExperimentCookie {\n    name: string;\n    value: string;\n    maxAge: number;\n}\n\nexport interface GetPageWithExperimentOptions {\n    /** Forced variant id (from the `?wb-variant=` query parameter). Overrides bucketing, never counted. */\n    forcedVariantId?: string;\n    /**\n     * Request query parameters. When provided, the forced variant is read from\n     * `searchParams[FORCED_VARIANT_PARAM]` unless `forcedVariantId` is set explicitly. Convenient\n     * for framework handlers that already have the parsed query (e.g. Next.js `searchParams`).\n     */\n    searchParams?: Record<string, string | string[] | undefined>;\n    /** Explicit visitor id. When omitted, it is read from the cookie or generated. */\n    visitorId?: string;\n    /** Explicit ISO country code. When omitted, it is read from common CDN geo headers. */\n    country?: string;\n    /** Explicit device type. When omitted, it is derived from the user agent. */\n    device?: DeviceType;\n    /** Header names to read the visitor country from, in priority order. */\n    geoHeaders?: string[];\n    /** Bucketing cookie name. Defaults to `wb_ab_vid`. */\n    cookieName?: string;\n    /** Bucketing cookie max age in seconds. Defaults to one year. */\n    cookieMaxAge?: number;\n    /** Set false to skip exposure emission (e.g. when consent has not been granted). */\n    emitExposure?: boolean;\n    /** Visitor id generator. Defaults to nanoid. */\n    generateVisitorId?: () => string;\n}\n\nexport interface ExperimentRenderResult {\n    /** The content to render server-side: the baseline (control) or a variant overlay. */\n    page: PublicPage | null;\n    /** The active experiment, or null when there is none for the path. */\n    experiment: ActiveExperiment | null;\n    /** The visitor's assignment, or null when no experiment applies. */\n    assignment: VariantAssignment | null;\n    /**\n     * Set when the caller should persist the bucketing cookie (i.e. a visitor id was generated\n     * this request). Persisting it in a Route Handler / middleware keeps bucketing stable.\n     */\n    cookie?: ExperimentCookie;\n}\n\nconst readCookie = (cookieHeader: string | null | undefined, name: string): string | undefined => {\n    if (!cookieHeader) {\n        return undefined;\n    }\n    for (const part of cookieHeader.split(\";\")) {\n        const index = part.indexOf(\"=\");\n        if (index === -1) {\n            continue;\n        }\n        const key = part.slice(0, index).trim();\n        if (key === name) {\n            return decodeURIComponent(part.slice(index + 1).trim());\n        }\n    }\n    return undefined;\n};\n\nconst detectDevice = (userAgent: string | null | undefined): DeviceType | undefined => {\n    if (!userAgent) {\n        return undefined;\n    }\n    if (/iPad|Tablet|PlayBook|Silk/i.test(userAgent)) {\n        return \"tablet\";\n    }\n    if (/Mobi|Android.+Mobile|iPhone|iPod|Windows Phone/i.test(userAgent)) {\n        return \"mobile\";\n    }\n    return \"desktop\";\n};\n\n/**\n * Resolve request-time visitor context from request headers/cookies. Never uses a logged-in\n * identity. Returns whether a visitor id was generated, so the caller can persist the cookie.\n */\nexport const resolveVisitorContext = async (\n    options: GetPageWithExperimentOptions = {}\n): Promise<{ context: VisitorContext; generatedVisitorId: boolean }> => {\n    const cookieName = options.cookieName ?? DEFAULT_VISITOR_COOKIE;\n    const generate = options.generateVisitorId ?? (() => nanoid());\n\n    let headers: Headers | undefined;\n    const provider = getHeadersProvider();\n    if (provider) {\n        try {\n            headers = await provider();\n        } catch {\n            headers = undefined;\n        }\n    }\n\n    let visitorId = options.visitorId;\n    let generatedVisitorId = false;\n    if (!visitorId) {\n        visitorId = readCookie(headers?.get(\"cookie\"), cookieName);\n    }\n    if (!visitorId) {\n        visitorId = generate();\n        generatedVisitorId = true;\n    }\n\n    let country = options.country;\n    if (!country && headers) {\n        for (const header of options.geoHeaders ?? DEFAULT_GEO_HEADERS) {\n            const value = headers.get(header);\n            if (value) {\n                country = value.toUpperCase();\n                break;\n            }\n        }\n    }\n\n    const device = options.device ?? detectDevice(headers?.get(\"user-agent\"));\n\n    return { context: { visitorId, country, device }, generatedVisitorId };\n};\n\n/** Forced variant id from an explicit option, falling back to the query parameter. */\nconst resolveForcedVariantId = (options: GetPageWithExperimentOptions): string | undefined => {\n    if (options.forcedVariantId) {\n        return options.forcedVariantId;\n    }\n    const raw = options.searchParams?.[FORCED_VARIANT_PARAM];\n    return Array.isArray(raw) ? raw[0] : raw;\n};\n\nconst overlayVariant = (baseline: PublicPage, variant: VariantContent): PublicPage => {\n    return {\n        ...baseline,\n        properties: variant.properties as PublicPage[\"properties\"],\n        bindings: variant.bindings as PublicPage[\"bindings\"],\n        elements: variant.elements as PublicPage[\"elements\"],\n        extensions: variant.extensions,\n        metadata: variant.metadata\n    };\n};\n\n/**\n * Resolve and render the right page for a visitor, server-side, with no client-side content\n * swap.\n *\n * Caching contract (important — handled here so projects do not reimplement it):\n *  - The baseline (control) is fetched via `getPage(path)` and caches per path.\n *  - The active experiment metadata is fetched via `getPageExperiment(path)` and caches per path.\n *  - A variant's content is fetched via `getVariantContent(variantId)` and caches per variant id.\n * Every request therefore resolves to one of a small, fixed set of cacheable objects keyed by\n * (path) or (variant id) — NEVER by the raw visitor id. Each active variant adds exactly one\n * cacheable object per URL.\n */\nexport const getPageWithExperiment = async (\n    sdk: ExperimentSdk,\n    path: string,\n    options: GetPageWithExperimentOptions = {}\n): Promise<ExperimentRenderResult> => {\n    // Baseline content + active experiment. Both cache per path.\n    const [controlPage, experiment] = await Promise.all([\n        sdk.getPage(path),\n        sdk.getPageExperiment(path)\n    ]);\n\n    if (!experiment || !controlPage) {\n        return { page: controlPage, experiment: experiment ?? null, assignment: null };\n    }\n\n    // Only a running experiment serves variants. `getPageExperiment` already returns the active\n    // one, but guard defensively.\n    if (experiment.status !== \"running\") {\n        return { page: controlPage, experiment, assignment: null };\n    }\n\n    // Kill-switch: a paused experiment instantly reverts to the control. Consulted uncached by the\n    // data provider so it takes effect immediately while page/variant content stays cached.\n    if (sdk.getExperimentPaused) {\n        const paused = await sdk.getExperimentPaused(experiment.experimentId).catch(() => false);\n        if (paused) {\n            return { page: controlPage, experiment, assignment: null };\n        }\n    }\n\n    const forcedVariantId = resolveForcedVariantId(options);\n\n    const { context, generatedVisitorId } = await resolveVisitorContext(options);\n\n    let assignment: VariantAssignment | null = null;\n    if (forcedVariantId) {\n        assignment = forcedAssignment(experiment, forcedVariantId);\n    }\n    if (!assignment) {\n        assignment = assignVariant(experiment, context);\n    }\n\n    let page = controlPage;\n    if (!assignment.isControl) {\n        const variant = await sdk.getVariantContent(assignment.variantId);\n        if (variant) {\n            page = overlayVariant(controlPage, variant);\n        } else {\n            // The variant disappeared (e.g. deleted) — fall back to the control safely.\n            assignment = {\n                variantId: experiment.controlVariantId,\n                isControl: true,\n                excluded: assignment.excluded,\n                forced: assignment.forced\n            };\n        }\n    }\n\n    // Emit a single canonical exposure event through the provider seam. Forced and excluded\n    // assignments are never reported. Analytics failures must never break rendering.\n    const shouldEmit = (options.emitExposure ?? true) && !assignment.excluded && !assignment.forced;\n    if (shouldEmit) {\n        const provider = getAnalyticsProvider(experiment.analytics.provider);\n        if (provider) {\n            const experimentKey =\n                typeof experiment.analytics.experimentKey === \"string\"\n                    ? experiment.analytics.experimentKey\n                    : undefined;\n            try {\n                await provider.emitExposure({\n                    experimentId: experiment.experimentId,\n                    experimentKey,\n                    variantId: assignment.variantId,\n                    revisionId: experiment.revisionId,\n                    tenantId: experiment.tenantId,\n                    visitorId: context.visitorId,\n                    pageId: experiment.pageEntryId,\n                    path: experiment.path,\n                    timestamp: new Date().toISOString()\n                });\n            } catch {\n                // Swallow — exposure measurement must never affect the rendered response.\n            }\n        }\n    }\n\n    const result: ExperimentRenderResult = { page, experiment, assignment };\n\n    if (generatedVisitorId) {\n        result.cookie = {\n            name: options.cookieName ?? DEFAULT_VISITOR_COOKIE,\n            value: context.visitorId,\n            maxAge: options.cookieMaxAge ?? 60 * 60 * 24 * 365\n        };\n    }\n\n    return result;\n};\n"],"names":["DEFAULT_VISITOR_COOKIE","FORCED_VARIANT_PARAM","DEFAULT_GEO_HEADERS","readCookie","cookieHeader","name","part","index","key","decodeURIComponent","detectDevice","userAgent","resolveVisitorContext","options","cookieName","generate","nanoid","headers","provider","getHeadersProvider","undefined","visitorId","generatedVisitorId","country","header","value","device","resolveForcedVariantId","raw","Array","overlayVariant","baseline","variant","getPageWithExperiment","sdk","path","controlPage","experiment","Promise","paused","forcedVariantId","context","assignment","forcedAssignment","assignVariant","page","shouldEmit","getAnalyticsProvider","experimentKey","Date","result"],"mappings":"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"}

package/experiments/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The reserved variant id for the control bucket. The control bucket renders the baseline
+ * revision content; it has no Variant object of its own.
+ */
+export declare const CONTROL_VARIANT_ID = "control";
+export type DeviceType = "desktop" | "mobile" | "tablet";
+export interface ExperimentTrafficSplit {
+    control: number;
+    variants: Record<string, number>;
+}
+export interface ExperimentTargeting {
+    trafficPercentage: number;
+    geo?: string[];
+    device?: DeviceType[];
+}
+/**
+ * Provider-agnostic analytics configuration carried by an experiment. Adapters read this and
+ * map it to their own shape. No provider-specific field name appears here.
+ */
+export interface ExperimentAnalyticsConfig {
+    provider: string;
+    [key: string]: unknown;
+}
+export interface ActiveExperimentVariant {
+    variantId: string;
+    name: string;
+}
+/**
+ * A variant's full content snapshot, shaped for rendering. Overlaid onto the baseline page so
+ * the result is a complete, renderable page.
+ */
+export interface VariantContent {
+    id: string;
+    properties: Record<string, any>;
+    bindings: Record<string, any>;
+    elements: Record<string, any>;
+    extensions: Record<string, any>;
+    metadata: Record<string, any>;
+}
+/**
+ * The active experiment for a path as returned by the Website Builder API. This is the only
+ * experiment shape the render path deals with — it is provider-agnostic.
+ */
+export interface ActiveExperiment {
+    experimentId: string;
+    revisionId: string;
+    pageEntryId: string;
+    path: string;
+    status: string;
+    tenantId: string;
+    controlVariantId: string;
+    trafficSplit: ExperimentTrafficSplit;
+    targeting: ExperimentTargeting;
+    analytics: ExperimentAnalyticsConfig;
+    variants: ActiveExperimentVariant[];
+}
+/**
+ * Request-time context used to bucket a visitor. Derived server-side from request headers /
+ * cookies — never from a logged-in identity.
+ */
+export interface VisitorContext {
+    /** A stable visitor id (from the bucketing cookie, or a generated id). */
+    visitorId: string;
+    /** ISO country code, if the CDN/edge provided one. */
+    country?: string;
+    /** Device type, derived from the user agent. */
+    device?: DeviceType;
+}
+export interface VariantAssignment {
+    /** The assigned variant id, or the control variant id. */
+    variantId: string;
+    /** True when the control bucket (baseline revision) was assigned. */
+    isControl: boolean;
+    /**
+     * True when the visitor was not entered into the experiment (targeting or traffic
+     * percentage). The control is served and no exposure is emitted.
+     */
+    excluded: boolean;
+    /** True when a forced-variant query parameter overrode bucketing (QA). Never reported. */
+    forced: boolean;
+}
+/**
+ * The single canonical exposure event. Each analytics provider adapter maps from this into its
+ * own event shape. No PostHog (or other provider) field names may appear here.
+ */
+export interface ExposureEvent {
+    experimentId: string;
+    /** Optional human-readable experiment key for provider mapping (from analytics config). */
+    experimentKey?: string;
+    /** The assigned variant id (the control variant id for the control bucket). */
+    variantId: string;
+    revisionId: string;
+    tenantId: string;
+    /** Stable distinct visitor id. */
+    visitorId: string;
+    pageId: string;
+    path: string;
+    timestamp: string;
+}
+/**
+ * The provider seam. A v2 GA4 adapter is a drop-in implementation of this interface — the data
+ * model, assignment logic, and render path never change.
+ */
+export interface AnalyticsProvider {
+    /** Provider id, matched against an experiment's analytics.provider. */
+    readonly name: string;
+    emitExposure(event: ExposureEvent): Promise<void>;
+}

package/experiments/types.js

@@ -0,0 +1,4 @@
+const CONTROL_VARIANT_ID = "control";
+export { CONTROL_VARIANT_ID };
+
+//# sourceMappingURL=types.js.map

package/experiments/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/types.js","sources":["../../src/experiments/types.ts"],"sourcesContent":["/**\n * The reserved variant id for the control bucket. The control bucket renders the baseline\n * revision content; it has no Variant object of its own.\n */\nexport const CONTROL_VARIANT_ID = \"control\";\n\nexport type DeviceType = \"desktop\" | \"mobile\" | \"tablet\";\n\nexport interface ExperimentTrafficSplit {\n    control: number;\n    variants: Record<string, number>;\n}\n\nexport interface ExperimentTargeting {\n    trafficPercentage: number;\n    geo?: string[];\n    device?: DeviceType[];\n}\n\n/**\n * Provider-agnostic analytics configuration carried by an experiment. Adapters read this and\n * map it to their own shape. No provider-specific field name appears here.\n */\nexport interface ExperimentAnalyticsConfig {\n    provider: string;\n    [key: string]: unknown;\n}\n\nexport interface ActiveExperimentVariant {\n    variantId: string;\n    name: string;\n}\n\n/**\n * A variant's full content snapshot, shaped for rendering. Overlaid onto the baseline page so\n * the result is a complete, renderable page.\n */\nexport interface VariantContent {\n    id: string;\n    properties: Record<string, any>;\n    bindings: Record<string, any>;\n    elements: Record<string, any>;\n    extensions: Record<string, any>;\n    metadata: Record<string, any>;\n}\n\n/**\n * The active experiment for a path as returned by the Website Builder API. This is the only\n * experiment shape the render path deals with — it is provider-agnostic.\n */\nexport interface ActiveExperiment {\n    experimentId: string;\n    revisionId: string;\n    pageEntryId: string;\n    path: string;\n    status: string;\n    tenantId: string;\n    controlVariantId: string;\n    trafficSplit: ExperimentTrafficSplit;\n    targeting: ExperimentTargeting;\n    analytics: ExperimentAnalyticsConfig;\n    variants: ActiveExperimentVariant[];\n}\n\n/**\n * Request-time context used to bucket a visitor. Derived server-side from request headers /\n * cookies — never from a logged-in identity.\n */\nexport interface VisitorContext {\n    /** A stable visitor id (from the bucketing cookie, or a generated id). */\n    visitorId: string;\n    /** ISO country code, if the CDN/edge provided one. */\n    country?: string;\n    /** Device type, derived from the user agent. */\n    device?: DeviceType;\n}\n\nexport interface VariantAssignment {\n    /** The assigned variant id, or the control variant id. */\n    variantId: string;\n    /** True when the control bucket (baseline revision) was assigned. */\n    isControl: boolean;\n    /**\n     * True when the visitor was not entered into the experiment (targeting or traffic\n     * percentage). The control is served and no exposure is emitted.\n     */\n    excluded: boolean;\n    /** True when a forced-variant query parameter overrode bucketing (QA). Never reported. */\n    forced: boolean;\n}\n\n/**\n * The single canonical exposure event. Each analytics provider adapter maps from this into its\n * own event shape. No PostHog (or other provider) field names may appear here.\n */\nexport interface ExposureEvent {\n    experimentId: string;\n    /** Optional human-readable experiment key for provider mapping (from analytics config). */\n    experimentKey?: string;\n    /** The assigned variant id (the control variant id for the control bucket). */\n    variantId: string;\n    revisionId: string;\n    tenantId: string;\n    /** Stable distinct visitor id. */\n    visitorId: string;\n    pageId: string;\n    path: string;\n    timestamp: string;\n}\n\n/**\n * The provider seam. A v2 GA4 adapter is a drop-in implementation of this interface — the data\n * model, assignment logic, and render path never change.\n */\nexport interface AnalyticsProvider {\n    /** Provider id, matched against an experiment's analytics.provider. */\n    readonly name: string;\n    emitExposure(event: ExposureEvent): Promise<void>;\n}\n"],"names":["CONTROL_VARIANT_ID"],"mappings":"AAIO,MAAMA,qBAAqB"}

package/image/geometry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure geometry core for crop + focal point rendering.
+ *
+ * This module is the single source of truth shared by:
+ *  - the Admin editor previews (square / 4:3 / 16:9),
+ *  - the Next.js render helper (`getImageProps` / `<Image>`),
+ *  - and any future URL-transform loader (`?rect=…`).
+ *
+ * Keeping the math here guarantees that what an editor previews is exactly what
+ * a visitor sees. Everything is framework-agnostic and side-effect free.
+ */
+import type { AssetCrop, AssetImage } from "@webiny/sdk";
+import type { AspectRatioInput } from "./types.js";
+/** A rectangle in normalized (0..1) coordinates of the original image. */
+export interface NormalizedRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * CSS needed to render an image cropped to a target aspect ratio while honoring
+ * both the crop rectangle and the focal point — without any server-side processing.
+ *
+ * `objectPosition` is the simpler, focal-point-only path (apply to an `object-fit:
+ * cover` image). `container` + `image` is the accurate path that also honors the
+ * crop rectangle via an overflow-clipped wrapper.
+ */
+export interface ImageRenderData {
+    rect: NormalizedRect;
+    objectPosition: string;
+    container: {
+        position: "relative";
+        width: "100%";
+        aspectRatio: string;
+        overflow: "hidden";
+    };
+    image: {
+        position: "absolute";
+        width: string;
+        height: string;
+        left: string;
+        top: string;
+        maxWidth: "none";
+        objectFit: "cover";
+        objectPosition: string;
+    };
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+}
+export declare function resolveAssetImage(override?: AssetImage | null, assetDefault?: AssetImage | null): AssetImage;
+export declare function getCropRect(crop?: AssetCrop | null): NormalizedRect;
+export declare function getVisibleRect(image: AssetImage, aspectRatio?: AspectRatioInput): NormalizedRect;
+export declare function getImageRenderData(image: AssetImage, aspectRatio?: AspectRatioInput): ImageRenderData;