@delmaredigital/payload-experiments 0.1.0-rc.7 → 0.2.0-rc.1

package/dist/transitions/preflightData.js

@@ -19,164 +19,216 @@ const failureDetail = (cause)=>cause instanceof Error ? cause.message : 'Placeme
     });
     if (!found.docs[0]) return null;
     const experiment = found.docs[0];
-    const ids = [
+    return (await loadStartInputsBatch(req, options, [
+        experiment
+    ])).get(String(experiment.id)) ?? null;
+}
+const metricIds = (experiment)=>[
         experiment.metrics?.primary,
         ...experiment.metrics?.secondary ?? [],
         ...experiment.metrics?.guardrails ?? []
     ].map(relationshipId).filter((id)=>id !== undefined);
-    const metrics = [];
-    if (ids.length) {
-        let page = 1;
-        while(true){
-            const result = await req.payload.find({
-                collection: 'xp-metrics',
-                req,
-                overrideAccess: false,
-                depth: 0,
-                limit: 100,
-                page,
-                where: {
-                    id: {
-                        in: ids
-                    }
-                }
-            });
-            metrics.push(...result.docs);
-            if (!result.hasNextPage) break;
-            page++;
-        }
-    }
-    const input = {
-        experiment,
-        metrics,
-        metricSources: options.metricSources,
-        flagPoints: options.flagPoints,
-        attributeKeys: options.attributeKeys
-    };
-    if (experiment.kind === 'block') {
-        try {
-            input.placements = await scanBlockPlacements(req, {
-                slug: experiment.slug,
-                puckCollections: options.puck?.collections ?? []
-            });
-        } catch (cause) {
-            input.placementError = failureDetail(cause);
-        }
-    }
-    if (experiment.kind === 'flag') {
-        const point = options.flagPoints?.find((point)=>point.id === experiment.flagPoint);
-        if (point) {
-            // Match the save hook: the control always uses effective point defaults.
-            let params = point.defaultParams;
-            try {
-                const state = await req.payload.findGlobal({
-                    slug: 'xp-state',
-                    req,
-                    overrideAccess: false,
-                    depth: 0
-                });
-                const defaults = state.flagDefaults;
-                params = defaults?.[point.id]?.params ?? params;
-            } catch (cause) {
-                const error = cause;
-                if (error?.status !== 403 && error?.name !== 'Forbidden') throw cause;
-            }
-            experiment.arms = experiment.arms.map((arm)=>arm.kind === 'control' ? {
-                    ...arm,
-                    params
-                } : arm);
-        }
-        if (point?.placements) {
-            try {
-                const placements = await flagPlacements(options, experiment, req);
-                if (Array.isArray(placements) && placements.every((p)=>p && typeof p === 'object' && typeof p.arm === 'string')) input.flagPlacements = placements;
-                else input.flagPlacementError = 'Placement lookup returned an invalid result.';
-            } catch (cause) {
-                input.flagPlacementError = failureDetail(cause);
-            }
-        }
-        if (experiment.flagPoint) {
-            // At most one row can be this experiment; two rows suffice to find a peer.
-            const busy = await req.payload.find({
-                collection: 'xp-experiments',
-                req,
-                overrideAccess: false,
-                depth: 0,
-                limit: 2,
-                where: {
-                    and: [
-                        {
-                            flagPoint: {
-                                equals: experiment.flagPoint
-                            }
-                        },
-                        {
-                            status: {
-                                in: [
-                                    'running',
-                                    'decided'
-                                ]
-                            }
-                        }
-                    ]
-                }
-            });
-            input.flagPointBusy = busy.docs.some((doc)=>String(doc.id) !== String(experiment.id));
-        }
-    }
-    const layerId = relationshipId(experiment.layer);
-    if (layerId !== undefined) {
-        const layers = await req.payload.find({
-            collection: 'xp-layers',
+/** Shared, request-scoped reads for summary; a failed row is null in tolerant mode.
+ * Preflight/Start use the same builder and retain their throwing read behaviour.
+ */ export async function loadStartInputsBatch(req, options, experiments, tolerateErrors = false) {
+    const ids = [
+        ...new Set(experiments.flatMap(metricIds))
+    ];
+    const metrics = (async ()=>{
+        if (!ids.length) return [];
+        const result = await req.payload.find({
+            collection: 'xp-metrics',
             req,
             overrideAccess: false,
             depth: 0,
-            limit: 1,
+            pagination: false,
+            limit: ids.length,
             where: {
                 id: {
-                    equals: layerId
+                    in: ids
                 }
             }
         });
-        const layer = layers.docs[0];
-        const usedSlices = [];
-        let page = 1;
-        while(true){
-            const result = await req.payload.find({
-                collection: 'xp-experiments',
-                req,
-                overrideAccess: false,
-                depth: 0,
-                limit: 100,
-                page,
-                where: {
-                    and: [
-                        {
-                            layer: {
+        return result.docs;
+    })();
+    const blockSlugs = new Set(experiments.filter((e)=>e.kind === 'block').map((e)=>e.slug));
+    // Lazy promises prevent unhandled rejections and share failed reads as well as successful ones.
+    let blocks;
+    let state;
+    const busyPoints = new Map();
+    const layers = new Map();
+    const inputs = new Map();
+    for (const experiment of experiments){
+        try {
+            const ownIds = new Set(metricIds(experiment).map(String));
+            const input = {
+                experiment,
+                metrics: (await metrics).filter((metric)=>ownIds.has(String(metric.id))),
+                metricSources: options.metricSources,
+                flagPoints: options.flagPoints,
+                attributeKeys: options.attributeKeys
+            };
+            if (experiment.kind === 'block') {
+                try {
+                    blocks ??= scanBlockPlacements(req, {
+                        slugs: blockSlugs,
+                        puckCollections: options.puck?.collections ?? []
+                    });
+                    input.placements = (await blocks).get(experiment.slug) ?? [];
+                } catch (cause) {
+                    input.placementError = failureDetail(cause);
+                }
+            }
+            if (experiment.kind === 'flag') {
+                const point = options.flagPoints?.find((point)=>point.id === experiment.flagPoint);
+                if (point) {
+                    state ??= (async ()=>{
+                        try {
+                            const doc = await req.payload.findGlobal({
+                                slug: 'xp-state',
+                                req,
+                                overrideAccess: false,
+                                depth: 0
+                            });
+                            return doc.flagDefaults;
+                        } catch (cause) {
+                            const error = cause;
+                            if (error?.status !== 403 && error?.name !== 'Forbidden') throw cause;
+                            // Match the existing preflight fallback when the global is access-filtered.
+                            return undefined;
+                        }
+                    })();
+                    const defaults = await state;
+                    experiment.arms = experiment.arms.map((arm)=>arm.kind === 'control' ? {
+                            ...arm,
+                            params: defaults?.[point.id]?.params ?? point.defaultParams
+                        } : arm);
+                }
+                if (point?.placements) {
+                    try {
+                        const placements = await flagPlacements(options, experiment, req);
+                        if (Array.isArray(placements) && placements.every((p)=>p && typeof p === 'object' && typeof p.arm === 'string')) input.flagPlacements = placements;
+                        else input.flagPlacementError = 'Placement lookup returned an invalid result.';
+                    } catch (cause) {
+                        input.flagPlacementError = failureDetail(cause);
+                    }
+                }
+                if (experiment.flagPoint) {
+                    const key = experiment.flagPoint;
+                    if (!busyPoints.has(key)) busyPoints.set(key, (async ()=>{
+                        // Two rows suffice to find a peer, including when the batch contains that peer.
+                        const busy = await req.payload.find({
+                            collection: 'xp-experiments',
+                            req,
+                            overrideAccess: false,
+                            depth: 0,
+                            limit: 2,
+                            where: {
+                                and: [
+                                    {
+                                        flagPoint: {
+                                            equals: key
+                                        }
+                                    },
+                                    {
+                                        status: {
+                                            in: [
+                                                'running',
+                                                'decided'
+                                            ]
+                                        }
+                                    }
+                                ]
+                            }
+                        });
+                        return busy.docs;
+                    })());
+                    input.flagPointBusy = (await busyPoints.get(key)).some((doc)=>String(doc.id) !== String(experiment.id));
+                }
+            }
+            const layerId = relationshipId(experiment.layer);
+            if (layerId !== undefined) {
+                const key = String(layerId);
+                if (!layers.has(key)) layers.set(key, (async ()=>{
+                    const result = await req.payload.find({
+                        collection: 'xp-layers',
+                        req,
+                        overrideAccess: false,
+                        depth: 0,
+                        limit: 1,
+                        where: {
+                            id: {
                                 equals: layerId
                             }
-                        },
-                        {
-                            status: {
-                                in: [
-                                    'running',
-                                    'decided'
+                        }
+                    });
+                    const layer = result.docs[0];
+                    const usedSlices = [];
+                    let page = 1;
+                    while(true){
+                        const usage = await req.payload.find({
+                            collection: 'xp-experiments',
+                            req,
+                            overrideAccess: false,
+                            depth: 0,
+                            limit: 100,
+                            page,
+                            where: {
+                                and: [
+                                    {
+                                        layer: {
+                                            equals: layerId
+                                        }
+                                    },
+                                    {
+                                        status: {
+                                            in: [
+                                                'running',
+                                                'decided'
+                                            ]
+                                        }
+                                    }
                                 ]
                             }
-                        }
-                    ]
-                }
-            });
-            for (const doc of result.docs)if (Array.isArray(doc.layerSlices)) usedSlices.push(...doc.layerSlices);
-            if (!result.hasNextPage) break;
-            page++;
+                        });
+                        for (const doc of usage.docs)if (Array.isArray(doc.layerSlices)) usedSlices.push(...doc.layerSlices);
+                        if (!usage.hasNextPage) break;
+                        page++;
+                    }
+                    return layer ? {
+                        unitType: layer.unitType,
+                        usedSlices
+                    } : null;
+                })());
+                input.layer = await layers.get(key);
+            }
+            inputs.set(String(experiment.id), input);
+        } catch (cause) {
+            if (!tolerateErrors) throw cause;
+            inputs.set(String(experiment.id), null);
         }
-        input.layer = layer ? {
-            unitType: layer.unitType,
-            usedSlices
-        } : null;
     }
-    return input;
+    return inputs;
+}
+function placementUrls(options, placement) {
+    const result = {};
+    const { collection, id, published } = placement;
+    try {
+        const url = options.admin?.previewUrl?.({
+            collection,
+            id
+        });
+        if (typeof url === 'string') result.url = url;
+    } catch  {}
+    try {
+        const url = options.admin?.editorUrl?.({
+            collection,
+            id,
+            draft: !published
+        });
+        if (typeof url === 'string') result.editorUrl = url;
+    } catch  {}
+    return result;
 }
 async function primaryHistory(source, now) {
     if (!source) return null;
@@ -230,8 +282,7 @@ export async function preflightData(req, { experimentId, options }, { now = new
         const compared = e.arms.filter((arm)=>arm.kind !== 'holdout');
         const control = compared.find((arm)=>arm.kind === 'control');
         const variant = compared.find((arm)=>arm.kind === 'variant');
-        const savedDuration = e.analysis?.plannedDurationDays && e.analysis.plannedDurationDays > 0 ? e.analysis.plannedDurationDays : undefined;
-        const planned = savedDuration ?? 14;
+        const planned = 14;
         const enrolled = trafficPerDay * e.allocation / 100;
         const pairShare = ((control?.weight ?? 0) + (variant?.weight ?? 0)) / 100;
         const tuning = enrolled * planned * pairShare;
@@ -274,13 +325,11 @@ export async function preflightData(req, { experimentId, options }, { now = new
                     });
                 let result = await estimateAt(tuning);
                 let weeks = result.sampleSizeAndRuntime.primary?.weeks ?? result.weekThreshold ?? 13;
-                const plannedDurationDays = savedDuration ?? Math.ceil(weeks * 7);
+                const plannedDurationDays = Math.ceil(weeks * 7);
                 const sequentialTuningParameter = enrolled * plannedDurationDays * pairShare;
-                if (savedDuration === undefined) {
-                    // Re-evaluate using exactly the duration and tuning Review will prefill.
-                    result = await estimateAt(sequentialTuningParameter);
-                    weeks = result.sampleSizeAndRuntime.primary?.weeks ?? result.weekThreshold ?? 13;
-                }
+                // Re-evaluate using exactly the power-derived duration and tuning Apply will save.
+                result = await estimateAt(sequentialTuningParameter);
+                weeks = result.sampleSizeAndRuntime.primary?.weeks ?? result.weekThreshold ?? 13;
                 power = {
                     weeks,
                     plannedDurationDays,
@@ -295,6 +344,8 @@ export async function preflightData(req, { experimentId, options }, { now = new
             collection: placement.collection,
             id: placement.id,
             title: placement.title,
+            slots: placement.slots,
+            ...placementUrls(options, placement),
             ok: requiredSlots.every((slot)=>slot && placement.slots[slot] > 0),
             detail: placement.published ? 'Published' : 'Draft'
         }));

package/dist/transitions/start.js

@@ -1,7 +1,7 @@
-import { randomBytes } from 'node:crypto';
 import { claimSlices } from '../db/slices.js';
 import { XpRefusal } from '../errors.js';
 import { isOpValid } from '../targeting/ops.js';
+import { newSeed } from '../runtime/seed.js';
 import { checkStart, relationshipId } from './checkStart.js';
 import { withTransition } from './kernel.js';
 import { writePhaseRecord } from './phaseRecord.js';
@@ -160,7 +160,7 @@ export async function start(req, { experimentId, options }) {
             count: current.allocation
         });
         const phase = (current.phase ?? 0) + 1;
-        const seed = `${randomBytes(16).toString('hex')}|`;
+        const seed = newSeed();
         const startedAt = at.toISOString();
         const definitions = caps.definitions.map((metric)=>({
                 ...metric,

package/dist/types/admin.d.ts

@@ -2,6 +2,7 @@ import type { MetricSource, ParamField } from './contracts.js';
 export type SerializedFlagPoint = {
     id: string;
     label: string;
+    description?: string;
     params: Record<string, ParamField>;
     defaultParams: Record<string, unknown>;
     effectiveDefaults: Record<string, unknown>;

package/dist/types/contracts.d.ts

@@ -64,6 +64,7 @@ export interface MetricSource {
 export interface FlagPoint {
     id: string;
     label: string;
+    description?: string;
     params: Record<string, ParamField>;
     defaultParams: Record<string, unknown>;
     placements?(args: {
@@ -104,6 +105,22 @@ export interface ExperimentsPluginOptions<TUser extends {
         readResults?: ExperimentsAccess;
         readIdentities?: ExperimentsAccess;
     };
+    admin?: {
+        editorUrl?: (args: {
+            collection: string;
+            id: DocId;
+            draft?: boolean;
+        }) => string;
+        previewUrl?: (args: {
+            collection: string;
+            id: DocId;
+        }) => string;
+        descriptions?: {
+            block?: string;
+            document?: string;
+            setting?: string;
+        };
+    };
     metricSources?: MetricSource[];
     eventSources?: Array<string | {
         name: string;

package/dist/types/endpoints.d.ts

@@ -1,4 +1,7 @@
 import type { ArmKind, DocId, ExposurePolicy, MetricSource, ResolvedOptions } from './contracts.js';
+import type { ArmSlot } from './puck.js';
+import type { ReadinessCode } from '../transitions/checkStart.js';
+export type { ReadinessCode } from '../transitions/checkStart.js';
 import type { Snapshot, VerdictCode } from './snapshot.js';
 export type ArmIssueCode = 'weights-total' | 'control-count' | 'control-first' | 'holdout-last' | 'holdout-count' | 'variant-count' | 'duplicate-key' | 'duplicate-slot' | 'slot-required' | 'invalid-key';
 export type RefusalCode = ArmIssueCode | 'not-found' | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-no-targets' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'layer-full' | 'layer-unit-mismatch' | 'unknown-metric-source' | 'unit-source-mismatch' | 'no-reach-per-day' | 'invalid-status' | 'stale-draft' | 'commit-unverified' | 'allocation-lower' | 'confirmation-required' | 'invalid-winner' | 'slices-taken' | 'locked-placement' | 'not-implemented' | 'forbidden' | 'unauthenticated' | 'body-too-large' | 'invalid-body' | 'too-many-ids' | 'invalid-phase' | 'invalid-ids' | 'recompute-failed' | 'undeclared-targeting-key' | 'invalid-targeting-rule' | 'duplicate-metric';
@@ -39,7 +42,7 @@ export type MakeContentResult = TransitionSuccess & {
 };
 export type PreflightResult = {
     checks: Array<{
-        code: RefusalCode;
+        code: ReadinessCode;
         ok: boolean;
         detail?: unknown;
     }>;
@@ -48,6 +51,8 @@ export type PreflightResult = {
         id: DocId;
         title: string;
         url?: string;
+        editorUrl?: string;
+        slots?: Record<ArmSlot, number>;
         ok: boolean;
         detail?: string;
     }>;
@@ -91,6 +96,10 @@ export type ResultsResponse = {
     phases: PhaseSummary[];
     snapshot: Snapshot | null;
     decisionSnapshot?: Snapshot;
+    decision?: {
+        phase: number;
+        winnerArm: string;
+    };
     series?: Array<{
         computedAt: string;
         metricId: DocId;
@@ -100,6 +109,7 @@ export type ResultsResponse = {
     }>;
 };
 export type SummaryResponse = Record<DocId, {
+    ready?: boolean;
     exposures: number;
     days: number;
     verdict: {

package/dist/types/snapshot.d.ts

@@ -105,6 +105,7 @@ export interface Snapshot {
         detail: string;
         recommendedArm: string | null;
         guardrailLine?: string;
+        worstArm?: string;
     };
     contentChanges: Array<{
         at: string;

package/dist/types/surface.d.ts

@@ -0,0 +1,29 @@
+import type { DocId } from './contracts.js';
+import type { SerializedAttributeKeys, SerializedFlagPoint, SerializedMetricSource } from './admin.js';
+export type TestsRoute = 'home' | 'new' | 'test' | 'results';
+export interface TestsSurfaceProps {
+    route: TestsRoute;
+    id?: string;
+    adminRoute: string;
+    apiRoute: string;
+    isAdmin: boolean;
+    pages?: Array<{
+        collection: string;
+        collectionLabel: string;
+        id: DocId;
+        title: string;
+        editorUrl: string;
+    }>;
+    canManage: boolean;
+    canReadResults: boolean;
+    flagPoints: SerializedFlagPoint[];
+    attributeKeys: SerializedAttributeKeys;
+    metricSources: SerializedMetricSource[];
+    admin?: {
+        descriptions?: {
+            block?: string;
+            document?: string;
+            setting?: string;
+        };
+    };
+}

package/dist/types/surface.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-experiments",
-  "version": "0.1.0-rc.7",
+  "version": "0.2.0-rc.1",
   "description": "No-code A/B testing for Payload CMS and Next.js: block, page and flag experiments with holdouts, layers, exposure logging and honest statistics inside the admin — no vendor",
   "type": "module",
   "license": "MIT",

package/dist/access.d.ts

@@ -1 +0,0 @@
-export { deny, isTrue, managedAccess, readOnlyAccess } from './collections/access.js';

package/dist/access.js

@@ -1,2 +0,0 @@
-// Keep CORE-02a's helpers canonical without changing its collection files.
-export { deny, isTrue, managedAccess, readOnlyAccess } from './collections/access.js';

package/dist/admin/AllocationField.d.ts

@@ -1,2 +0,0 @@
-import type { NumberFieldClientProps } from 'payload';
-export declare function AllocationField({ path, field, readOnly }: NumberFieldClientProps): import("react").JSX.Element;

package/dist/admin/AllocationField.js

@@ -1,80 +0,0 @@
-'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { FieldError, useField, useFormFields } from '@payloadcms/ui';
-import { EDITABLE_BY_STATUS, isEditable } from '../collections/experiments/editability.js';
-import { lockedReason } from './lockedNotice.model.js';
-import { allocationGroups, allocationLayer, allocationSentence } from './allocation.model.js';
-import { WHO_COPY } from './copy/who.js';
-import { useLayerUsage } from './useLayerUsage.js';
-export function AllocationField({ path, field, readOnly }) {
-    const { value, setValue } = useField({
-        path
-    });
-    const form = useFormFields(([fields])=>({
-            status: fields.status?.value ?? 'draft',
-            unitType: fields.unitType?.value ?? 'visitor',
-            arms: allocationGroups(fields),
-            layerId: fields.layer?.value,
-            layer: allocationLayer(fields.layer?.value) ?? allocationLayer({
-                name: fields['layer.name']?.value,
-                used: fields['layer.used']?.value,
-                free: fields['layer.free']?.value
-            })
-        }));
-    const locked = Boolean(readOnly || field.admin?.readOnly || !isEditable(form.status, 'allocation'));
-    const reason = lockedReason(form.status, 'allocation', EDITABLE_BY_STATUS);
-    const layerId = typeof form.layerId === 'object' && form.layerId !== null ? 'id' in form.layerId ? form.layerId.id : null : form.layerId;
-    const layer = useLayerUsage(typeof layerId === 'string' || typeof layerId === 'number' ? layerId : null);
-    const sentence = allocationSentence({
-        ...form,
-        allocation: value ?? NaN,
-        layer: layer ?? form.layer
-    });
-    // position: relative anchors Payload's absolutely positioned FieldError tooltip to this field.
-    return /*#__PURE__*/ _jsxs("div", {
-        className: "xp-allocation-field",
-        style: {
-            position: 'relative'
-        },
-        children: [
-            /*#__PURE__*/ _jsx("label", {
-                htmlFor: path,
-                children: WHO_COPY.allocation
-            }),
-            /*#__PURE__*/ _jsx("input", {
-                id: path,
-                name: path,
-                type: "number",
-                min: 1,
-                max: 100,
-                step: 1,
-                required: field.required,
-                value: value ?? '',
-                readOnly: locked,
-                "aria-describedby": `${path}-description`,
-                style: {
-                    display: 'block',
-                    color: 'var(--theme-text)',
-                    background: 'var(--theme-input-bg)',
-                    border: '1px solid var(--theme-elevation-200)',
-                    borderRadius: 'var(--style-radius-s)',
-                    padding: '0.5rem'
-                },
-                onChange: (event)=>{
-                    if (!locked) setValue(event.target.value === '' ? null : event.target.valueAsNumber);
-                }
-            }),
-            /*#__PURE__*/ _jsx(FieldError, {
-                path: path
-            }),
-            /*#__PURE__*/ _jsx("p", {
-                id: `${path}-description`,
-                children: sentence
-            }),
-            reason && (form.status !== 'running' || !sentence) ? /*#__PURE__*/ _jsx("p", {
-                className: "xp-locked-notice",
-                children: reason
-            }) : null
-        ]
-    });
-}

package/dist/admin/FlagPointSelect.d.ts

@@ -1,2 +0,0 @@
-import type { TextFieldClientProps } from 'payload';
-export declare function FlagPointSelect({ field, path, readOnly }: TextFieldClientProps): import("react").JSX.Element;