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

package/dist/events/rows.js

@@ -0,0 +1,65 @@
+import { exposureDimensions } from './dimensions.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Only declared primitive attributes can enter telemetry; never accept arbitrary browser objects. */ function attributes(value, keys) {
+    if (!record(value)) return undefined;
+    return Object.fromEntries(Object.entries(value).filter(([key, item])=>{
+        const definition = keys && Object.hasOwn(keys, key) ? keys[key] : undefined;
+        return definition && typeof item === definition.type && (typeof item !== 'number' || Number.isFinite(item)) && (!definition.values || typeof item === 'string' && definition.values.includes(item));
+    }));
+}
+export function eventRows(events, manifest, assignments, options, visitorId, userId, ts, requestAttributes = {}) {
+    const rows = new Map();
+    for (const event of events){
+        if (!record(event)) continue;
+        let row;
+        if (event.type === 'exposure') {
+            if (typeof event.experiment !== 'string' || typeof event.arm !== 'string' || ![
+                'manual',
+                'viewport',
+                'pageview'
+            ].includes(String(event.policy))) continue;
+            const experiment = manifest.experiments.find((exp)=>exp.slug === event.experiment);
+            const assigned = assignments.bySlug[event.experiment];
+            if (!experiment || !assigned?.exposable || event.phase !== experiment.phase || event.policy !== experiment.exposurePolicy) continue;
+            const unitId = experiment.unitType === 'visitor' ? visitorId : userId;
+            if (!unitId) continue;
+            const mismatch = event.arm !== assigned.arm;
+            row = {
+                type: mismatch ? 'arm-mismatch' : 'exposure',
+                experimentId: experiment.id,
+                phase: experiment.phase,
+                arm: event.arm,
+                unitId,
+                unitType: experiment.unitType,
+                userId,
+                ts,
+                dimensions: mismatch ? null : exposureDimensions(requestAttributes, options.events?.dimensions),
+                // §5.5 / §11: diagnostics are separate rows, never exposure denominators or multi-arm counts.
+                dedupeKey: mismatch ? `mismatch:${experiment.id}:${experiment.phase}:${unitId}:${ts.slice(0, 10)}` : `exposure:${experiment.id}:${experiment.phase}:${event.arm}:${unitId}:${ts.slice(0, 10)}`
+            };
+        } else if (event.type === 'conversion') {
+            if (typeof event.eventName !== 'string' || typeof event.idempotencyKey !== 'string' || !event.idempotencyKey.trim() || event.value !== undefined && (typeof event.value !== 'number' || !Number.isFinite(event.value))) continue;
+            const source = options.metricSources?.find((source)=>source.id === event.eventName);
+            if (source ? source.clientWritable !== true || source.kind === 'revenue' : !options.eventSources?.includes(event.eventName)) continue;
+            row = {
+                type: 'conversion',
+                eventName: event.eventName,
+                value: 1,
+                unitId: visitorId,
+                unitType: 'visitor',
+                userId,
+                ts,
+                dimensions: null,
+                attributes: attributes(event.attributes, options.attributeKeys),
+                // §5.5: scoped by unit and event so one client can never pre-claim another's key.
+                dedupeKey: `conversion:c:${visitorId}:${event.eventName}:${event.idempotencyKey}`
+            };
+        } else continue;
+        rows.set(row.dedupeKey, row);
+    }
+    return [
+        ...rows.values()
+    ];
+}

package/dist/exports/adminClient.d.ts

@@ -0,0 +1,16 @@
+export { AllocationField } from '../admin/AllocationField.js';
+export { FlagPointSelect } from '../admin/FlagPointSelect.js';
+export { LayerUsage } from '../admin/LayerUsage.js';
+export { LockedFieldNotice } from '../admin/LockedFieldNotice.js';
+export { MetricSourceSelect } from '../admin/MetricSourceSelect.js';
+export { PhaseHistory } from '../admin/PhaseHistory.js';
+export { StatusCell } from '../admin/StatusCell.js';
+export { SummaryCell } from '../admin/SummaryCell.js';
+export { ExperimentActions } from '../admin/actions/ExperimentActions.js';
+export { ArmSelectField } from '../admin/armSelect/ArmSelectField.js';
+export { ArmsField } from '../admin/arms/ArmsField.js';
+export { ResultsView } from '../admin/results/ResultsView.js';
+export { ReviewPanel } from '../admin/review/ReviewPanel.js';
+export { TargetingAttributeField } from '../admin/targeting/TargetingAttributeField.js';
+export { TargetingOpField } from '../admin/targeting/TargetingOpField.js';
+export { TargetingValueField } from '../admin/targeting/TargetingValueField.js';

package/dist/exports/adminClient.js

@@ -0,0 +1,17 @@
+'use client';
+export { AllocationField } from '../admin/AllocationField.js';
+export { FlagPointSelect } from '../admin/FlagPointSelect.js';
+export { LayerUsage } from '../admin/LayerUsage.js';
+export { LockedFieldNotice } from '../admin/LockedFieldNotice.js';
+export { MetricSourceSelect } from '../admin/MetricSourceSelect.js';
+export { PhaseHistory } from '../admin/PhaseHistory.js';
+export { StatusCell } from '../admin/StatusCell.js';
+export { SummaryCell } from '../admin/SummaryCell.js';
+export { ExperimentActions } from '../admin/actions/ExperimentActions.js';
+export { ArmSelectField } from '../admin/armSelect/ArmSelectField.js';
+export { ArmsField } from '../admin/arms/ArmsField.js';
+export { ResultsView } from '../admin/results/ResultsView.js';
+export { ReviewPanel } from '../admin/review/ReviewPanel.js';
+export { TargetingAttributeField } from '../admin/targeting/TargetingAttributeField.js';
+export { TargetingOpField } from '../admin/targeting/TargetingOpField.js';
+export { TargetingValueField } from '../admin/targeting/TargetingValueField.js';

package/dist/exports/client.d.ts

@@ -0,0 +1,7 @@
+export { ExperimentsProvider } from '../client/ExperimentsProvider.js';
+export { useFlagPoint } from '../client/useFlagPoint.js';
+export { useExperiment } from '../client/useExperiment.js';
+export { ExperimentPageview } from '../client/ExperimentPageview.js';
+export { trackConversionBeacon } from '../client/trackConversionBeacon.js';
+export { MAX_EVENTS_PER_BODY, DEFAULT_MAX_BODY_BYTES } from '../constants.js';
+export type { ClientAssignments } from '../types/assignments.js';

package/dist/exports/client.js

@@ -0,0 +1,7 @@
+'use client';
+export { ExperimentsProvider } from '../client/ExperimentsProvider.js';
+export { useFlagPoint } from '../client/useFlagPoint.js';
+export { useExperiment } from '../client/useExperiment.js';
+export { ExperimentPageview } from '../client/ExperimentPageview.js';
+export { trackConversionBeacon } from '../client/trackConversionBeacon.js';
+export { MAX_EVENTS_PER_BODY, DEFAULT_MAX_BODY_BYTES } from '../constants.js';

package/dist/exports/index.d.ts

@@ -0,0 +1,4 @@
+export { createExperimentsPlugin } from '../plugin.js';
+export { defineFlagPoint, defineMetricSource } from '../define.js';
+export { createArmSelectField } from '../fields/armSelect.js';
+export type { SerializedFlagPoint, SerializedMetricSource, SerializedAttributeKeys, EditableField, Assignment, Assignments, FlagPointResult, ClientAssignments, RenderedExposure, DocId, Attributes, ExposurePolicy, ExperimentKind, Status, UnitType, ArmKey, ArmKind, TargetingRule, Arm, ParamField, MetricSource, FlagPoint, RateLimiter, ExperimentsAccess, ExperimentsPluginOptions, ArmIssueCode, RefusalCode, ErrorEnvelope, TransitionSuccess, AllocateBody, AddMetricBody, DecideBody, ArchiveBody, MakeContentResult, PreflightResult, PreviewTokenResult, PhaseSummary, ResultsResponse, SummaryResponse, EventBody, FlagDefault, Manifest, ManifestExperiment, ArmSlot, ExperimentRef, ExperimentSlotProps, ExperimentsProxyRuntimeOptions, ExperimentsProxyRuntime, ExperimentsServerRuntimeOptions, ExperimentsServerRuntime, VerdictCode, Snapshot, } from '../types/index.js';

package/dist/exports/index.js

@@ -0,0 +1,3 @@
+export { createExperimentsPlugin } from '../plugin.js';
+export { defineFlagPoint, defineMetricSource } from '../define.js';
+export { createArmSelectField } from '../fields/armSelect.js';

package/dist/exports/proxy.d.ts

@@ -0,0 +1,4 @@
+export { resolveExperiments } from '../proxy/resolve.js';
+export { applyExperiments } from '../proxy/apply.js';
+export { createExperimentProxy } from '../proxy/createProxy.js';
+export type { ExperimentsProxyResult } from '../proxy/resolve.js';

package/dist/exports/proxy.js

@@ -0,0 +1,3 @@
+export { resolveExperiments } from '../proxy/resolve.js';
+export { applyExperiments } from '../proxy/apply.js';
+export { createExperimentProxy } from '../proxy/createProxy.js';

package/dist/exports/puck.d.ts

@@ -0,0 +1,4 @@
+export { ExperimentSlot } from '../puck/ExperimentSlot.js';
+export { createExperimentSlotField } from '../puck/experimentSlotField.js';
+export { EXPERIMENT_SLOT_TYPE } from '../types/puck.js';
+export type { ArmSlot, ExperimentRef, ExperimentSlotProps } from '../types/puck.js';

package/dist/exports/puck.js

@@ -0,0 +1,3 @@
+export { ExperimentSlot } from '../puck/ExperimentSlot.js';
+export { createExperimentSlotField } from '../puck/experimentSlotField.js';
+export { EXPERIMENT_SLOT_TYPE } from '../types/puck.js';

package/dist/exports/puckEditor.d.ts

@@ -0,0 +1 @@
+export { ExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';

package/dist/exports/puckEditor.js

@@ -0,0 +1,2 @@
+'use client';
+export { ExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';

package/dist/exports/rsc.d.ts

@@ -0,0 +1,13 @@
+export { getAssignments } from '../server/getAssignments.js';
+export { resolveExperimentData } from '../server/resolveExperimentData.js';
+export { recordExposures } from '../server/recordExposures.js';
+export { getFlagPoint } from '../server/getFlagPoint.js';
+export { linkIdentity } from '../server/linkIdentity.js';
+export { trackConversion } from '../server/trackConversion.js';
+export { eraseUser } from '../server/eraseUser.js';
+export { runResults } from '../server/runResults.js';
+export { recordContentChange } from '../server/recordContentChange.js';
+export { experimentSitemapFilter } from '../server/sitemap.js';
+export { experimentMetadata } from '../server/metadata.js';
+export { toClientAssignments } from '../server/toClientAssignments.js';
+export { contentChangesBeforeHook as captureContentBaseline } from '../hooks/contentChanges.js';

package/dist/exports/rsc.js

@@ -0,0 +1,13 @@
+export { getAssignments } from '../server/getAssignments.js';
+export { resolveExperimentData } from '../server/resolveExperimentData.js';
+export { recordExposures } from '../server/recordExposures.js';
+export { getFlagPoint } from '../server/getFlagPoint.js';
+export { linkIdentity } from '../server/linkIdentity.js';
+export { trackConversion } from '../server/trackConversion.js';
+export { eraseUser } from '../server/eraseUser.js';
+export { runResults } from '../server/runResults.js';
+export { recordContentChange } from '../server/recordContentChange.js';
+export { experimentSitemapFilter } from '../server/sitemap.js';
+export { experimentMetadata } from '../server/metadata.js';
+export { toClientAssignments } from '../server/toClientAssignments.js';
+export { contentChangesBeforeHook as captureContentBaseline } from '../hooks/contentChanges.js';

package/dist/exports/runtimeProxy.d.ts

@@ -0,0 +1,4 @@
+export { defineExperimentsProxyRuntime } from '../runtime/proxyRuntime.js';
+export { createPostgresManifestLoader, createHttpManifestLoader } from '../runtime/loaders.js';
+export type { ExperimentsProxyRuntime, ExperimentsProxyRuntimeOptions, Manifest } from '../types/index.js';
+export type { PostgresManifestLoaderOptions, HttpManifestLoaderOptions, ManifestLoader } from '../runtime/loaders.js';

package/dist/exports/runtimeProxy.js

@@ -0,0 +1,2 @@
+export { defineExperimentsProxyRuntime } from '../runtime/proxyRuntime.js';
+export { createPostgresManifestLoader, createHttpManifestLoader } from '../runtime/loaders.js';

package/dist/exports/runtimeServer.d.ts

@@ -0,0 +1,2 @@
+export { defineExperimentsServerRuntime } from '../server/serverRuntime.js';
+export type { ExperimentsServerRuntime, ExperimentsServerRuntimeOptions } from '../types/runtime.js';

package/dist/exports/runtimeServer.js

@@ -0,0 +1 @@
+export { defineExperimentsServerRuntime } from '../server/serverRuntime.js';

package/dist/fields/armSelect.d.ts

@@ -0,0 +1,7 @@
+import type { Field } from 'payload';
+export declare function createArmSelectField({ name, flagPoint, label, required }: {
+    name?: string;
+    flagPoint: string;
+    label?: string;
+    required?: boolean;
+}): Field;

package/dist/fields/armSelect.js

@@ -0,0 +1,33 @@
+import { XP_ARM_SELECT } from '../admin/paths.js';
+export function createArmSelectField({ name = 'experimentArm', flagPoint, label, required }) {
+    return {
+        name,
+        type: 'group',
+        label: label ?? 'Experiment group',
+        admin: {
+            components: {
+                Field: XP_ARM_SELECT
+            },
+            custom: {
+                flagPoint
+            }
+        },
+        fields: [
+            {
+                name: 'experiment',
+                type: 'text',
+                admin: {
+                    hidden: true
+                }
+            },
+            {
+                name: 'arm',
+                type: 'text',
+                required,
+                admin: {
+                    hidden: true
+                }
+            }
+        ]
+    };
+}

package/dist/globals/state.d.ts

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

package/dist/globals/state.js

@@ -0,0 +1,31 @@
+import { deny, isTrue } from '../collections/access.js';
+export function stateGlobal(options) {
+    return {
+        slug: 'xp-state',
+        dbName: 'xp_state',
+        graphQL: false,
+        admin: {
+            hidden: true
+        },
+        access: {
+            read: isTrue(options.access.manage),
+            update: deny,
+            readVersions: deny
+        },
+        fields: [
+            {
+                name: 'revision',
+                type: 'number',
+                defaultValue: 0
+            },
+            {
+                name: 'manifest',
+                type: 'json'
+            },
+            {
+                name: 'flagDefaults',
+                type: 'json'
+            }
+        ]
+    };
+}

package/dist/hooks/contentChanges.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionAfterChangeHook, CollectionBeforeChangeHook } from 'payload';
+export declare const contentChangesHook: CollectionAfterChangeHook;
+export declare const contentChangesBeforeHook: CollectionBeforeChangeHook;

package/dist/hooks/contentChanges.js

@@ -0,0 +1,10 @@
+import { capturePublishedContent, recordContentChange } from '../server/recordContentChange.js';
+import { neverThrow, neverThrowBefore } from './hostHook.js';
+export const contentChangesHook = neverThrow('contentChanges', async (args)=>{
+    await recordContentChange(args);
+    return args.doc;
+});
+export const contentChangesBeforeHook = neverThrowBefore('contentChanges baseline', async (args)=>{
+    await capturePublishedContent(args);
+    return args.data;
+});

package/dist/hooks/hostHook.d.ts

@@ -0,0 +1,5 @@
+import type { CollectionAfterChangeHook, CollectionBeforeChangeHook } from 'payload';
+/** Host saves must survive synchronous and asynchronous plugin hook failures. */
+export declare function neverThrow(name: string, hook: CollectionAfterChangeHook): CollectionAfterChangeHook;
+/** The baseline capture is also best effort and must return incoming save data. */
+export declare function neverThrowBefore(name: string, hook: CollectionBeforeChangeHook): CollectionBeforeChangeHook;

package/dist/hooks/hostHook.js

@@ -0,0 +1,20 @@
+/** Host saves must survive synchronous and asynchronous plugin hook failures. */ export function neverThrow(name, hook) {
+    return async (args)=>{
+        try {
+            return await hook(args);
+        } catch (error) {
+            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, error);
+            return args.doc;
+        }
+    };
+}
+/** The baseline capture is also best effort and must return incoming save data. */ export function neverThrowBefore(name, hook) {
+    return async (args)=>{
+        try {
+            return await hook(args);
+        } catch (error) {
+            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, error);
+            return args.data;
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_NAME: "@delmaredigital/payload-experiments";

package/dist/index.js

@@ -0,0 +1,4 @@
+// @delmaredigital/payload-experiments
+// Public surface is defined in docs/plans/2026-10-30-payload-experiments-design.md §7.
+// Implementation lands by lane; this file only pins the package until then.
+export const PLUGIN_NAME = '@delmaredigital/payload-experiments';

package/dist/manifest/cache.d.ts

@@ -0,0 +1,10 @@
+import type { Manifest } from '../types/manifest.js';
+import type { ManifestLoader } from '../runtime/loaders.js';
+export declare function createManifestCache(load: ManifestLoader, { ttlMs, coldStartMs, refreshTimeoutMs, now }?: {
+    ttlMs?: number;
+    coldStartMs?: number;
+    refreshTimeoutMs?: number;
+    now?: () => number;
+}): {
+    get(): Promise<Manifest | null>;
+};

package/dist/manifest/cache.js

@@ -0,0 +1,51 @@
+export function createManifestCache(load, { ttlMs = 30_000, coldStartMs = 1_500, refreshTimeoutMs = 5_000, now = Date.now } = {}) {
+    let cached = null;
+    let checkedAt = -Infinity;
+    let inFlight;
+    function refresh() {
+        if (!inFlight) {
+            const expired = new Error('Manifest refresh timed out');
+            let timer;
+            const pending = Promise.resolve().then(()=>load(cached ? {
+                    ifRevision: cached.revision
+                } : {}));
+            inFlight = Promise.race([
+                pending,
+                new Promise((_resolve, reject)=>{
+                    timer = setTimeout(()=>reject(expired), refreshTimeoutMs);
+                })
+            ]).then((result)=>{
+                if (result !== 'not-modified') cached = result;
+                checkedAt = now();
+                return cached;
+            }, (error)=>{
+                // A timed-out attempt must not pin inFlight or delay the next retry.
+                // Its late result is ignored: only the race winner can mutate the cache.
+                checkedAt = error === expired ? -Infinity : now();
+                return cached;
+            }).finally(()=>{
+                clearTimeout(timer);
+                inFlight = undefined;
+            });
+        }
+        return inFlight;
+    }
+    return {
+        async get () {
+            if (now() - checkedAt < ttlMs) return cached;
+            const pending = refresh();
+            if (cached) return cached;
+            let timer;
+            try {
+                return await Promise.race([
+                    pending,
+                    new Promise((resolve)=>{
+                        timer = setTimeout(()=>resolve(null), coldStartMs);
+                    })
+                ]);
+            } finally{
+                if (timer !== undefined) clearTimeout(timer);
+            }
+        }
+    };
+}

package/dist/manifest/compile.d.ts

@@ -0,0 +1,63 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, DocId, ExperimentKind, ExposurePolicy, Status, TargetingRule, UnitType } from '../types/contracts.js';
+import type { Manifest, ManifestExperiment } from '../types/manifest.js';
+import type { AttributeKeys } from '../runtime/targeting.js';
+type TypedTargetingRule = ManifestExperiment['targeting'][number];
+export interface ManifestCompileOptions {
+    attributeKeys?: AttributeKeys;
+    onInvalid?(slug: string, reason: string): void;
+}
+export interface ManifestPhase {
+    phase: number;
+    phaseKind: 'test' | 'rollout';
+    seed: string;
+    arms: Arm[];
+    allocation: number;
+    targeting: Array<TargetingRule & {
+        type?: TypedTargetingRule['type'];
+    }>;
+    endedAt?: string | null;
+}
+export interface ManifestInputExperiment {
+    id: DocId;
+    slug: string;
+    kind: ExperimentKind;
+    status: Status;
+    unitType: UnitType;
+    exposurePolicy: ExposurePolicy;
+    flagPoint?: string | null;
+    arms: Arm[];
+    layer?: {
+        slug: string;
+    } | DocId | null;
+    layerSlices?: number[] | null;
+    decision?: {
+        winnerArm?: string | null;
+        discardedAt?: string | null;
+        holdoutReleasedAt?: string | null;
+    } | null;
+    currentPhase: ManifestPhase | null;
+    lastTestPhase?: ManifestPhase | null;
+}
+export interface ManifestInputs {
+    experiments: ManifestInputExperiment[];
+    flagDefaults: Manifest['flagDefaults'];
+    excludeIds?: DocId[];
+    pruneFlagDefaultIds?: DocId[];
+}
+export declare function loadManifestInputs(req: PayloadRequest, { excludeIds, pruneFlagDefaultIds }?: {
+    excludeIds?: DocId[];
+    pruneFlagDefaultIds?: DocId[];
+}): Promise<ManifestInputs>;
+/** Pure compiler. Assignment config comes exclusively from the frozen phase. */
+export declare function compileManifest(inputs: ManifestInputs, revision: number, { attributeKeys, onInvalid }?: ManifestCompileOptions): Manifest;
+/** Take the state lock before reading inputs. Under READ COMMITTED, a builder
+ * waiting for another transition then sees that transition's committed changes,
+ * so a later revision cannot overwrite the manifest with pre-lock input state.
+ * All reads and writes join the request's transaction.
+ */
+export declare function buildAndStoreManifest(req: PayloadRequest, options?: {
+    excludeIds?: DocId[];
+    pruneFlagDefaultIds?: DocId[];
+}): Promise<Manifest>;
+export {};