@delmaredigital/payload-experiments 0.0.0-stage → 0.1.0-rc.6

package/dist/client/ExperimentsProvider.js

@@ -0,0 +1,22 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from 'react';
+import { registerApiRoute, unregisterApiRoute } from './beacon.js';
+import { ExperimentsContext } from './context.js';
+export function ExperimentsProvider(props) {
+    const token = useRef(Symbol()).current;
+    // Register committed providers before descendants can send from passive effects.
+    useLayoutEffect(()=>{
+        registerApiRoute(token, props.value.apiRoute);
+    }, [
+        token,
+        props.value.apiRoute
+    ]);
+    useLayoutEffect(()=>()=>unregisterApiRoute(token), [
+        token
+    ]);
+    return /*#__PURE__*/ _jsx(ExperimentsContext.Provider, {
+        value: props.value,
+        children: props.children
+    });
+}

package/dist/client/ViewportExposure.d.ts

@@ -0,0 +1,9 @@
+import type * as React from 'react';
+export declare function ViewportExposure({ expose, children }: {
+    expose?: {
+        slug: string;
+        arm: string;
+        phase: number;
+    };
+    children: React.ReactNode;
+}): React.JSX.Element;

package/dist/client/ViewportExposure.js

@@ -0,0 +1,69 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useContext, useEffect, useRef } from 'react';
+import { sendExposure, warnOnce } from './beacon.js';
+import { ExperimentsContext } from './context.js';
+export function ViewportExposure({ expose, children }) {
+    const value = useContext(ExperimentsContext);
+    const sentinel = useRef(null);
+    const apiRoute = value?.apiRoute;
+    const slug = expose?.slug, arm = expose?.arm, phase = expose?.phase;
+    useEffect(()=>{
+        if (slug === undefined || arm === undefined || phase === undefined) return;
+        if (apiRoute === undefined) {
+            warnOnce('viewport:no-provider', 'ViewportExposure requires ExperimentsProvider to send an exposure.');
+            return;
+        }
+        const target = sentinel.current;
+        if (!target || typeof IntersectionObserver === 'undefined') return;
+        const observer = new IntersectionObserver((entries)=>{
+            if (!entries.some((entry)=>entry.target === target && entry.intersectionRatio >= 0.5)) return;
+            sendExposure(apiRoute, {
+                type: 'exposure',
+                experiment: slug,
+                phase,
+                arm,
+                policy: 'viewport'
+            });
+            observer.disconnect();
+        }, {
+            threshold: 0.5
+        });
+        observer.observe(target);
+        return ()=>observer.disconnect();
+    }, [
+        slug,
+        arm,
+        phase,
+        apiRoute
+    ]);
+    // Nothing to expose (no running experiment, or a render-policy slot): render exactly
+    // what experiments-off renders — no wrapper, no sentinel (owner rule O9). Hooks stay above.
+    if (expose === undefined) return /*#__PURE__*/ _jsx(_Fragment, {
+        children: children
+    });
+    return /*#__PURE__*/ _jsxs("div", {
+        "data-xp-viewport": true,
+        style: {
+            position: 'relative',
+            display: 'block'
+        },
+        children: [
+            /*#__PURE__*/ _jsx("div", {
+                ref: sentinel,
+                "data-xp-sentinel": true,
+                "aria-hidden": true,
+                style: {
+                    position: 'absolute',
+                    top: 0,
+                    left: 0,
+                    width: '100%',
+                    height: '100px',
+                    pointerEvents: 'none',
+                    visibility: 'hidden'
+                }
+            }),
+            children
+        ]
+    });
+}

package/dist/client/beacon.d.ts

@@ -0,0 +1,17 @@
+import type { EventBody } from '../types/endpoints.js';
+type Event = EventBody['events'][number];
+type Exposure = Extract<Event, {
+    type: 'exposure';
+}>;
+/** Register only committed providers; the latest mounted provider supplies conversion routing. */
+export declare function registerApiRoute(token: symbol, apiRoute: string): void;
+export declare function unregisterApiRoute(token: symbol): void;
+/** No mounted provider means experiments are not wired on this page: conversions are not sent (spec §13). */
+export declare function conversionApiRoute(): string | undefined;
+export declare function warnOnce(key: string, message: string): void;
+/** Telemetry must never interrupt rendering or a host interaction. */
+export declare function sendEvent(apiRoute: string, event: Event): void;
+export declare function sendExposure(apiRoute: string, event: Exposure, pathname?: string): void;
+/** Internal test seam; deliberately not exported by /client. */
+export declare function __resetBeaconsForTests(): void;
+export {};

package/dist/client/beacon.js

@@ -0,0 +1,71 @@
+'use client';
+const exposures = new Set();
+const pageviews = new Set();
+const warnings = new Set();
+const providers = new Map();
+/** Register only committed providers; the latest mounted provider supplies conversion routing. */ export function registerApiRoute(token, apiRoute) {
+    // Updating an existing token preserves its original mount order.
+    providers.set(token, apiRoute);
+}
+export function unregisterApiRoute(token) {
+    providers.delete(token);
+}
+/** No mounted provider means experiments are not wired on this page: conversions are not sent (spec §13). */ export function conversionApiRoute() {
+    return [
+        ...providers.values()
+    ].at(-1);
+}
+export function warnOnce(key, message) {
+    if (warnings.has(key)) return;
+    warnings.add(key);
+    console.error(message);
+}
+/** Telemetry must never interrupt rendering or a host interaction. */ export function sendEvent(apiRoute, event) {
+    try {
+        const body = {
+            events: [
+                event
+            ]
+        };
+        const json = JSON.stringify(body);
+        const url = `${apiRoute}/xp/events`;
+        try {
+            if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function' && navigator.sendBeacon(url, new Blob([
+                json
+            ], {
+                type: 'text/plain;charset=UTF-8'
+            }))) return;
+        } catch  {}
+        try {
+            void fetch(url, {
+                method: 'POST',
+                keepalive: true,
+                credentials: 'same-origin',
+                headers: {
+                    'content-type': 'text/plain;charset=UTF-8'
+                },
+                body: json
+            }).catch(()=>{});
+        } catch  {}
+    } catch  {}
+}
+export function sendExposure(apiRoute, event, pathname) {
+    const seen = pathname === undefined ? exposures : pageviews;
+    const key = JSON.stringify([
+        event.experiment,
+        event.phase,
+        event.arm,
+        ...pathname === undefined ? [] : [
+            pathname
+        ]
+    ]);
+    if (seen.has(key)) return;
+    seen.add(key);
+    sendEvent(apiRoute, event);
+}
+/** Internal test seam; deliberately not exported by /client. */ export function __resetBeaconsForTests() {
+    exposures.clear();
+    pageviews.clear();
+    warnings.clear();
+    providers.clear();
+}

package/dist/client/context.d.ts

@@ -0,0 +1,2 @@
+import type { ClientAssignments } from '../types/assignments.js';
+export declare const ExperimentsContext: import("react").Context<ClientAssignments | null>;

package/dist/client/context.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const ExperimentsContext = createContext(null);

package/dist/client/idempotency.d.ts

@@ -0,0 +1,2 @@
+/** Prefer a caller's stable key; restricted browser crypto must not break the caller. */
+export declare function idempotencyKey(provided?: string): string;

package/dist/client/idempotency.js

@@ -0,0 +1,13 @@
+'use client';
+/** Prefer a caller's stable key; restricted browser crypto must not break the caller. */ export function idempotencyKey(provided) {
+    // An empty key would collapse every conversion of this event for the unit into one dedupe row.
+    if (provided) return provided;
+    try {
+        if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+    } catch  {}
+    try {
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        return Array.from(bytes, (byte)=>byte.toString(16).padStart(2, '0')).join('');
+    } catch  {}
+    return Date.now().toString(36) + Math.random().toString(36).slice(2);
+}

package/dist/client/trackConversionBeacon.d.ts

@@ -0,0 +1,3 @@
+export declare function trackConversionBeacon(eventName: string, opts?: {
+    idempotencyKey?: string;
+}): void;

package/dist/client/trackConversionBeacon.js

@@ -0,0 +1,16 @@
+'use client';
+import { conversionApiRoute, sendEvent, warnOnce } from './beacon.js';
+import { idempotencyKey } from './idempotency.js';
+export function trackConversionBeacon(eventName, opts) {
+    const apiRoute = conversionApiRoute();
+    if (apiRoute === undefined) {
+        // Without an ExperimentsProvider the host has experiments disabled here; never send to a guessed route.
+        if (process.env.NODE_ENV !== 'production') warnOnce('conversion:no-provider', `trackConversionBeacon('${eventName}') was called without an ExperimentsProvider; nothing was sent.`);
+        return;
+    }
+    sendEvent(apiRoute, {
+        type: 'conversion',
+        eventName,
+        idempotencyKey: idempotencyKey(opts?.idempotencyKey)
+    });
+}

package/dist/client/useExperiment.d.ts

@@ -0,0 +1,5 @@
+export declare function useExperiment<P extends Record<string, unknown> = Record<string, unknown>>(slug: string): {
+    arm: string;
+    params: P;
+    expose(renderedArm: string): void;
+};

package/dist/client/useExperiment.js

@@ -0,0 +1,27 @@
+'use client';
+import { useContext } from 'react';
+import { sendExposure, warnOnce } from './beacon.js';
+import { ExperimentsContext } from './context.js';
+export function useExperiment(slug) {
+    const value = useContext(ExperimentsContext);
+    const entry = value && Object.hasOwn(value.experiments, slug) ? value.experiments[slug] : undefined;
+    if (!entry) {
+        const message = `Experiment "${slug}" must be allow-listed in toClientAssignments and rendered inside ExperimentsProvider.`;
+        if (process.env.NODE_ENV !== 'production') throw new Error(message);
+        warnOnce(`experiment:${slug}`, message);
+    }
+    return {
+        arm: entry?.arm ?? 'control',
+        params: entry?.params ?? {},
+        expose (renderedArm) {
+            if (!value || !entry?.exposable || entry.policy !== 'manual') return;
+            sendExposure(value.apiRoute, {
+                type: 'exposure',
+                experiment: slug,
+                phase: entry.phase,
+                arm: renderedArm,
+                policy: entry.policy
+            });
+        }
+    };
+}

package/dist/client/useFlagPoint.d.ts

@@ -0,0 +1,9 @@
+import type { DocId } from '../types/contracts.js';
+export declare function useFlagPoint<P extends Record<string, unknown> = Record<string, unknown>>(id: string): {
+    arm: string;
+    params: P;
+    source: 'experiment' | 'default';
+    experiment?: string;
+    experimentId?: DocId;
+    expose(renderedArm: string): void;
+};

package/dist/client/useFlagPoint.js

@@ -0,0 +1,32 @@
+'use client';
+import { useContext } from 'react';
+import { sendExposure, warnOnce } from './beacon.js';
+import { ExperimentsContext } from './context.js';
+export function useFlagPoint(id) {
+    const value = useContext(ExperimentsContext);
+    const entry = value && Object.hasOwn(value.flagPoints, id) ? value.flagPoints[id] : undefined;
+    if (!entry) {
+        const message = `Flag point "${id}" must be allow-listed in toClientAssignments and rendered inside ExperimentsProvider.`;
+        if (process.env.NODE_ENV !== 'production') throw new Error(message);
+        warnOnce(`flagPoint:${id}`, message);
+    }
+    return {
+        arm: entry?.arm ?? 'control',
+        params: entry?.params ?? {},
+        source: entry?.source ?? 'default',
+        ...entry?.source === 'experiment' ? {
+            experiment: entry.experiment,
+            experimentId: entry.experimentId
+        } : {},
+        expose (renderedArm) {
+            if (!value || !entry?.exposable || entry.source !== 'experiment' || entry.policy !== 'manual' || entry.experiment === undefined || entry.phase === undefined) return;
+            sendExposure(value.apiRoute, {
+                type: 'exposure',
+                experiment: entry.experiment,
+                phase: entry.phase,
+                arm: renderedArm,
+                policy: entry.policy
+            });
+        }
+    };
+}

package/dist/collections/access.d.ts

@@ -0,0 +1,21 @@
+import type { Access } from 'payload';
+import type { ExperimentsAccess, ResolvedOptions } from '../types/contracts.js';
+/** Host access callbacks must return the boolean true, never a truthy filter. */
+export declare const isTrue: (fn: ExperimentsAccess) => Access;
+export declare const deny: Access;
+export declare function managedAccess(options: ResolvedOptions): {
+    create: Access;
+    read: Access;
+    update: Access;
+    delete: Access;
+    readVersions: Access;
+    unlock: Access;
+};
+export declare function readOnlyAccess(read: ExperimentsAccess): {
+    create: Access;
+    read: Access;
+    update: Access;
+    delete: Access;
+    readVersions: Access;
+    unlock: Access;
+};

package/dist/collections/access.js

@@ -0,0 +1,25 @@
+/** Host access callbacks must return the boolean true, never a truthy filter. */ export const isTrue = (fn)=>async ({ req })=>await fn({
+            req
+        }) === true;
+export const deny = ()=>false;
+export function managedAccess(options) {
+    const manage = isTrue(options.access.manage);
+    return {
+        create: manage,
+        read: manage,
+        update: manage,
+        delete: manage,
+        readVersions: manage,
+        unlock: manage
+    };
+}
+export function readOnlyAccess(read) {
+    return {
+        create: deny,
+        read: isTrue(read),
+        update: deny,
+        delete: deny,
+        readVersions: deny,
+        unlock: deny
+    };
+}

package/dist/collections/events.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig } from 'payload';
+import type { ResolvedOptions } from '../types/contracts.js';
+export declare function eventsCollection(options: ResolvedOptions): CollectionConfig;

package/dist/collections/events.js

@@ -0,0 +1,117 @@
+import { readOnlyAccess } from './access.js';
+export function eventsCollection(options) {
+    return {
+        slug: 'xp-events',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            hidden: true
+        },
+        access: readOnlyAccess(options.access.readIdentities ?? options.access.admin ?? options.access.manage),
+        indexes: [
+            {
+                fields: [
+                    'experiment',
+                    'phase',
+                    'type',
+                    'ts'
+                ]
+            },
+            {
+                fields: [
+                    'unitId',
+                    'experiment'
+                ]
+            },
+            {
+                fields: [
+                    'type',
+                    'eventName',
+                    'ts'
+                ]
+            },
+            {
+                fields: [
+                    'experiment',
+                    'type',
+                    'ts'
+                ]
+            }
+        ],
+        fields: [
+            {
+                name: 'type',
+                type: 'select',
+                required: true,
+                options: [
+                    'exposure',
+                    'conversion',
+                    'arm-mismatch'
+                ]
+            },
+            {
+                name: 'experiment',
+                type: 'relationship',
+                relationTo: 'xp-experiments'
+            },
+            {
+                name: 'phase',
+                type: 'number'
+            },
+            {
+                name: 'arm',
+                type: 'text'
+            },
+            {
+                name: 'unitId',
+                type: 'text',
+                required: true
+            },
+            {
+                name: 'unitType',
+                type: 'select',
+                required: true,
+                options: [
+                    'visitor',
+                    'user'
+                ]
+            },
+            {
+                name: 'userId',
+                type: 'text'
+            },
+            {
+                name: 'eventName',
+                type: 'text'
+            },
+            {
+                name: 'value',
+                type: 'number'
+            },
+            {
+                name: 'ts',
+                type: 'date',
+                required: true
+            },
+            {
+                name: 'dimensions',
+                type: 'json',
+                admin: {
+                    hidden: true,
+                    readOnly: true
+                }
+            },
+            {
+                name: 'attributes',
+                type: 'json'
+            },
+            {
+                name: 'dedupeKey',
+                type: 'text',
+                unique: true,
+                index: true,
+                required: true
+            }
+        ]
+    };
+}

package/dist/collections/experiments/armInvariants.d.ts

@@ -0,0 +1,12 @@
+import type { Arm, ExperimentKind } from '../../types/contracts.js';
+import type { ArmIssueCode } from '../../types/endpoints.js';
+export interface ArmIssue {
+    code: ArmIssueCode;
+    armIndex?: number;
+    armKey?: string;
+    message: string;
+}
+/** The groups a new experiment starts with: Original 50 / Variant A 50, no holdout (spec §5.1, O4). Block slots equal the key. */
+export declare function defaultArms(kind: ExperimentKind | undefined): Arm[];
+export declare function checkArms(arms: Arm[], kind: ExperimentKind): ArmIssue[];
+export declare function addHoldout(arms: Arm[]): Arm[];

package/dist/collections/experiments/armInvariants.js

@@ -0,0 +1,89 @@
+/** The groups a new experiment starts with: Original 50 / Variant A 50, no holdout (spec §5.1, O4). Block slots equal the key. */ export function defaultArms(kind) {
+    const slot = (key)=>kind === 'block' ? {
+            slot: key
+        } : {};
+    return [
+        {
+            key: 'control',
+            kind: 'control',
+            label: 'Original',
+            weight: 50,
+            ...slot('control')
+        },
+        {
+            key: 'variantA',
+            kind: 'variant',
+            label: 'Variant A',
+            weight: 50,
+            ...slot('variantA')
+        }
+    ];
+}
+export function checkArms(arms, kind) {
+    const issues = [];
+    const issue = (code, message, armIndex)=>{
+        issues.push({
+            code,
+            message,
+            ...armIndex === undefined ? {} : {
+                armIndex,
+                armKey: arms[armIndex].key
+            }
+        });
+    };
+    if (arms.some((arm)=>!Number.isInteger(arm.weight) || arm.weight < 0) || arms.reduce((total, arm)=>total + arm.weight, 0) !== 100) {
+        issue('weights-total', 'Group shares must be whole numbers that add up to exactly 100.');
+    }
+    if (arms.filter((arm)=>arm.kind === 'control').length !== 1) issue('control-count', 'Exactly one Original is required.');
+    if (arms.some((arm, index)=>arm.kind === 'control' && index !== 0)) issue('control-first', 'The Original must be first.');
+    if (arms.filter((arm)=>arm.kind === 'holdout').length > 1) issue('holdout-count', 'Only one Holdout is allowed.');
+    if (arms.some((arm, index)=>arm.kind === 'holdout' && index !== arms.length - 1)) issue('holdout-last', 'The Holdout must be the last group.');
+    if (arms.filter((arm)=>arm.kind === 'variant').length > 3) issue('variant-count', 'At most three variants are allowed.');
+    const keys = new Set(), slots = new Set();
+    const kinds = {
+        control: 'control',
+        variantA: 'variant',
+        variantB: 'variant',
+        variantC: 'variant',
+        holdout: 'holdout'
+    };
+    arms.forEach((arm, index)=>{
+        if (!Object.hasOwn(kinds, arm.key) || kinds[arm.key] !== arm.kind) issue('invalid-key', 'Each group must be the Original, Variant A, B or C, or the Holdout.', index);
+        if (keys.has(arm.key)) issue('duplicate-key', 'Each group can appear only once.', index);
+        keys.add(arm.key);
+        if (kind === 'block') {
+            if (arm.kind === 'holdout') {
+                if (arm.slot != null) issue('invalid-key', 'The Holdout has no content of its own; it sees the Original.', index);
+            } else {
+                if (!arm.slot || arm.slot !== arm.key) issue('slot-required', 'Each Original and Variant needs its own content area.', index);
+                if (arm.slot && slots.has(arm.slot)) issue('duplicate-slot', 'Two groups cannot share the same content area.', index);
+                if (arm.slot) slots.add(arm.slot);
+            }
+        }
+    });
+    return issues;
+}
+export function addHoldout(arms) {
+    if (arms.some((arm)=>arm.kind === 'holdout' || arm.key === 'holdout')) return arms;
+    const total = arms.reduce((sum, arm)=>sum + arm.weight, 0);
+    const denominator = total > 0 ? total : arms.length;
+    const numerators = arms.map((arm)=>(total > 0 ? arm.weight : 1) * 90);
+    const weights = numerators.map((numerator)=>Math.floor(numerator / denominator));
+    const remainders = numerators.map((numerator)=>numerator % denominator);
+    const order = arms.map((_, index)=>index).sort((a, b)=>remainders[b] - remainders[a] || Number(arms[b].kind === 'control') - Number(arms[a].kind === 'control') || a - b);
+    const remainder = 90 - weights.reduce((sum, weight)=>sum + weight, 0);
+    for(let i = 0; i < remainder && order.length; i++)weights[order[i % order.length]]++;
+    const holdout = {
+        key: 'holdout',
+        kind: 'holdout',
+        label: 'Holdout',
+        weight: 10
+    };
+    return [
+        ...arms.map((arm, index)=>({
+                ...arm,
+                weight: weights[index]
+            })),
+        holdout
+    ];
+}

package/dist/collections/experiments/config.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig } from 'payload';
+import type { ResolvedOptions } from '../../types/contracts.js';
+export declare function experimentsCollection(options: ResolvedOptions): CollectionConfig;