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

package/dist/puck/editor/createTest.js

@@ -0,0 +1,50 @@
+import { editorCopy } from './copy.js';
+import { isSlugCollision, newTestBody, slugify, uniqueSlug } from './editor.model.js';
+/** Only a server refusal may supply editor-facing error text. */ export class CreateRefused extends Error {
+}
+function refusalMessage(body) {
+    const error = body;
+    const message = error?.errors?.[0]?.data?.errors?.[0]?.message;
+    return typeof message === 'string' && message.trim() ? message : editorCopy.createError;
+}
+/** Shared lookup, complete draft creation and one retry for a racing slug collision. */ export async function createTest(apiRoute, input) {
+    const api = apiRoute.replace(/\/$/, '');
+    const base = slugify(input.name) || 'test';
+    for(let attempt = 0;; attempt++){
+        // Suffixes shorten a 64-character base; include those neighbouring slugs in the lookup.
+        const lookup = await fetch(`${api}/xp-experiments?where[slug][like]=${encodeURIComponent(base.slice(0, 60))}&depth=0&limit=200&select[slug]=true`, {
+            credentials: 'include'
+        });
+        const found = await lookup.json();
+        if (!lookup.ok) throw new CreateRefused(refusalMessage(found));
+        if (!Array.isArray(found?.docs)) throw new Error(editorCopy.createError);
+        const taken = found.docs.flatMap((doc)=>typeof doc.slug === 'string' ? [
+                doc.slug
+            ] : []);
+        const response = await fetch(`${api}/xp-experiments`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(newTestBody({
+                ...input,
+                slug: uniqueSlug(base, taken)
+            }))
+        });
+        const body = await response.json();
+        if (!response.ok) {
+            if (isSlugCollision(response.status, body)) {
+                if (attempt === 0) continue;
+                throw new CreateRefused(editorCopy.nameExists);
+            }
+            throw new CreateRefused(refusalMessage(body));
+        }
+        const doc = body?.doc;
+        if (typeof doc?.id !== 'string' && typeof doc?.id !== 'number' || typeof doc?.slug !== 'string') throw new Error(editorCopy.createError);
+        return {
+            id: doc.id,
+            slug: doc.slug
+        };
+    }
+}

package/dist/puck/editor/editor.model.d.ts

@@ -1,4 +1,4 @@
-import type { Arm, Status } from '../../types/contracts.js';
+import type { Arm, DocId, Status, UnitType } from '../../types/contracts.js';
 import type { ArmSlot } from '../../types/puck.js';
 export type EditorExperiment = {
     name: string;
@@ -14,3 +14,30 @@ export declare function tabsFor(experiment?: Pick<EditorExperiment, 'arms'> | nu
 }>;
 export declare function bannerFor(status?: Status | null, winner?: string): string;
 export declare function slugify(name: string): string;
+/** Complete draft defaults, shared by the page hand-off and setting creation. */
+export declare function newTestBody(input: {
+    kind: 'block' | 'flag';
+    name: string;
+    slug: string;
+    unitType: UnitType;
+    flagPoint?: string;
+    layer?: DocId;
+    hypothesis?: string;
+}): {
+    hypothesis?: string | undefined;
+    layer?: DocId | undefined;
+    flagPoint?: string | undefined;
+    name: string;
+    slug: string;
+    kind: "block" | "flag";
+    unitType: UnitType;
+    exposurePolicy: string;
+    arms: Arm[];
+    allocation: number;
+    analysis: {
+        plannedDurationDays: number;
+    };
+};
+export declare function uniqueSlug(base: string, taken: readonly string[]): string;
+/** Payload nests field validation errors under data.errors. Only a unique slug refusal is retryable. */
+export declare function isSlugCollision(status: number, body: unknown): boolean;

package/dist/puck/editor/editor.model.js

@@ -31,3 +31,64 @@ export function bannerFor(status, winner = editorCopy.labels.control) {
 export function slugify(name) {
     return name.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64).replace(/-+$/g, '');
 }
+/** Complete draft defaults, shared by the page hand-off and setting creation. */ export function newTestBody(input) {
+    const { kind, name, slug, unitType, flagPoint, layer, hypothesis } = input;
+    const arms = [
+        {
+            key: 'control',
+            kind: 'control',
+            label: 'Original',
+            weight: 50,
+            ...kind === 'block' ? {
+                slot: 'control'
+            } : {}
+        },
+        {
+            key: 'variantA',
+            kind: 'variant',
+            label: 'Variant A',
+            weight: 50,
+            ...kind === 'block' ? {
+                slot: 'variantA'
+            } : {}
+        }
+    ];
+    return {
+        name,
+        slug,
+        kind,
+        unitType,
+        exposurePolicy: kind === 'block' ? 'render' : 'manual',
+        arms,
+        allocation: 100,
+        analysis: {
+            plannedDurationDays: 28
+        },
+        ...flagPoint === undefined ? {} : {
+            flagPoint
+        },
+        ...layer === undefined ? {} : {
+            layer
+        },
+        ...hypothesis === undefined ? {} : {
+            hypothesis
+        }
+    };
+}
+export function uniqueSlug(base, taken) {
+    const root = base.slice(0, 64).replace(/-+$/g, '') || 'test';
+    const used = new Set(taken);
+    if (!used.has(root)) return root;
+    for(let index = 2;; index++){
+        const suffix = `-${index}`;
+        const candidate = root.slice(0, 64 - suffix.length).replace(/-+$/g, '') + suffix;
+        if (!used.has(candidate)) return candidate;
+    }
+}
+/** Payload nests field validation errors under data.errors. Only a unique slug refusal is retryable. */ export function isSlugCollision(status, body) {
+    if (status !== 400 || !body || typeof body !== 'object') return false;
+    const error = body;
+    const message = typeof error.message === 'string' ? error.message : '';
+    if ((error.path === 'slug' || error.field === 'slug' || /\bslug\b/i.test(message)) && /unique|already.*(?:use|exist)|duplicate/i.test(message)) return true;
+    return Array.isArray(error.errors) && error.errors.some((item)=>isSlugCollision(status, item)) || isSlugCollision(status, error.data);
+}

package/dist/results/analyse.js

@@ -114,6 +114,7 @@ const severity = {
         };
         let worst = 'ok';
         let worstArmLabel = compared[0]?.label ?? '';
+        let worstArm = compared[0]?.key ?? '';
         try {
             if (!data || data.unavailable !== undefined) throw new Error(data?.unavailable ?? 'Metric data was not supplied');
             const stats = new Map();
@@ -248,6 +249,7 @@ const severity = {
                 if (severity[status] > severity[worst]) {
                     worst = status;
                     worstArmLabel = arm.label;
+                    worstArm = arm.key;
                 }
             }
         } catch (error) {
@@ -267,7 +269,8 @@ const severity = {
             verdictGuardrails.push(worst === 'failing' ? {
                 name: definition.name,
                 status: worst,
-                worstArmLabel
+                worstArmLabel,
+                worstArm
             } : {
                 name: definition.name,
                 status: worst

package/dist/results/verdict.d.ts

@@ -61,6 +61,7 @@ interface VerdictInputFields {
     } & ({
         status: 'failing';
         worstArmLabel: string;
+        worstArm: string;
     } | {
         status: 'ok' | 'warning' | 'insufficient';
         worstArmLabel?: string;

package/dist/results/verdict.js

@@ -21,7 +21,7 @@ function chance(value) {
 }
 /** Apply spec §8.5 in order to already-computed results; no inference is performed here. */ export function computeVerdict(input) {
     const rollout = input.phaseKind === 'rollout';
-    const make = (row, code, finding, action, detail, recommendedArm, line)=>({
+    const make = (row, code, finding, action, detail, recommendedArm, line, worstArm)=>({
             row,
             code,
             finding,
@@ -31,6 +31,9 @@ function chance(value) {
             recommendedArm,
             ...line === undefined ? {} : {
                 guardrailLine: line
+            },
+            ...worstArm === undefined ? {} : {
+                worstArm
             }
         });
     if (input.primary.unavailable !== undefined) {
@@ -56,7 +59,7 @@ function chance(value) {
         return make('R3', 'rollout-readout', `Since shipping ${winner}: ${percent(lift)} vs the holdout (CI ${percent(ci[0])} to ${percent(ci[1])}).`, null, 'This describes the shipped version compared with people still seeing the Original.', null, guardrailLine(input));
     }
     const failing = input.guardrails.find((item)=>item.status === 'failing');
-    if (failing) return make(3, 'guardrail-failing', `Stop: ${failing.worstArmLabel} harms ${failing.name}.`, null, 'An outcome that must stay safe has become worse.', input.controlArm);
+    if (failing) return make(3, 'guardrail-failing', `Stop: ${failing.worstArmLabel} harms ${failing.name}.`, null, 'An outcome that must stay safe has become worse.', input.controlArm, undefined, failing.worstArm);
     if (collecting) return make(4, 'collecting', input.status === 'stopped' ? 'Stopped before enough data was collected.' : `Collecting data: ${minimum} of ${input.exposures.minExposuresPerArm} people, ${minimumConverters} of ${input.primary.minSampleSize} conversions.`, null, 'More people or conversions are needed before drawing a conclusion.', null);
     const variantKeys = new Set(compared.filter((item)=>item.kind === 'variant').map((item)=>item.arm));
     const variants = input.primary.comparisons.filter((item)=>variantKeys.has(item.arm));
@@ -68,12 +71,12 @@ function chance(value) {
     ].sort((a, b)=>direction * (b.lift - a.lift))[0];
     const worst = worse[0];
     if (variants.length > 0 && worse.length === variants.length) return make(5, 'original-better', 'The Original is better.', 'Decide for the Original.', 'Every tested alternative performed worse.', input.controlArm);
-    if (worst && !best) return make(6, 'worse-none-better', `${labels(worse)} ${worse.length === 1 ? 'is' : 'are'} worse; no variant is better.`, `Decide for the Original or restart without ${worse.length === 1 ? 'it' : 'them'}.`, 'At least one alternative performed worse and none improved the main outcome.', input.controlArm);
+    if (worst && !best) return make(6, 'worse-none-better', `${labels(worse)} ${worse.length === 1 ? 'is' : 'are'} worse; no variant is better.`, `Decide for the Original or restart without ${worse.length === 1 ? 'it' : 'them'}.`, 'At least one alternative performed worse and none improved the main outcome.', input.controlArm, undefined, worst.arm);
     if (best && !worst) {
         const finding = better.length >= 2 ? `${better.length === 2 ? 'Both' : `All ${better.length} variants`} beat the Original; not tested against each other — ${best.label} has the larger improvement.` : input.method === 'bayesian' ? `${best.label} is very likely better${chance(best.chanceToWin)}.` : `${best.label} is statistically better: ${percent(best.lift)} (CI ${percent(best.ci[0])} to ${percent(best.ci[1])}).`;
         return make(7, 'winner', finding, null, 'The main outcome improved compared with the Original.', best.arm, guardrailLine(input));
     }
-    if (best && worst) return make(8, 'mixed', `Mixed: ${labels(better)} better, ${labels(worse)} worse.`, 'Review before deciding.', 'The tested alternatives moved the main outcome in different directions.', best.arm);
+    if (best && worst) return make(8, 'mixed', `Mixed: ${labels(better)} better, ${labels(worse)} worse.`, 'Review before deciding.', 'The tested alternatives moved the main outcome in different directions.', best.arm, undefined, worst.arm);
     if (input.status === 'running' && !input.plannedDurationPassed) {
         if (input.power.feasible === false || input.power.daysRemaining !== null && input.power.daysRemaining > 90) {
             return make(9, 'keep-running', 'A clear answer would take more than 90 days at this traffic.', 'Consider a bigger change or a different metric.', 'Current traffic is too low for a timely answer.', null);

package/dist/transitions/checkStart.d.ts

@@ -1,6 +1,7 @@
 import type { Arm, DocId, ExperimentKind, ExposurePolicy, FlagPoint, MetricSource, ResolvedOptions, Status, TargetingRule, UnitType } from '../types/contracts.js';
 import type { ArmIssueCode, PreflightResult } from '../types/endpoints.js';
 import type { BlockPlacement, FlagPlacement } from './placements.js';
+export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
 export interface StartExperiment {
     id: DocId;
     slug: string;

package/dist/transitions/placements.d.ts

@@ -13,10 +13,14 @@ export type FlagPlacement = Awaited<ReturnType<NonNullable<FlagPoint['placements
 /** Each matching ExperimentSlot is checked separately, including multiple slots
  * in one document: content elsewhere in the document cannot hide an empty slot.
  */
-export declare function scanBlockPlacements(req: PayloadRequest, { slug, puckCollections }: {
+export declare function scanBlockPlacements(req: PayloadRequest, args: {
     slug: string;
     puckCollections: NonNullable<ResolvedOptions['puck']>['collections'];
 }): Promise<BlockPlacement[]>;
+export declare function scanBlockPlacements(req: PayloadRequest, args: {
+    slugs: ReadonlySet<string>;
+    puckCollections: NonNullable<ResolvedOptions['puck']>['collections'];
+}): Promise<Map<string, BlockPlacement[]>>;
 export declare function flagPlacements<TUser extends {
     id: DocId;
 }>(options: ResolvedOptions<TUser>, experiment: {

package/dist/transitions/placements.js

@@ -5,10 +5,17 @@ const slots = [
     'variantB',
     'variantC'
 ];
-/** Each matching ExperimentSlot is checked separately, including multiple slots
- * in one document: content elsewhere in the document cannot hide an empty slot.
- */ export async function scanBlockPlacements(req, { slug, puckCollections }) {
-    const placements = [];
+export async function scanBlockPlacements(req, args) {
+    const { puckCollections } = args;
+    const slugs = args.slugs ?? new Set([
+        args.slug
+    ]);
+    const placements = new Map([
+        ...slugs
+    ].map((slug)=>[
+            slug,
+            []
+        ]));
     for (const { slug: collection, field } of normalisePuckCollections({
         puck: {
             enabled: true,
@@ -54,8 +61,8 @@ const slots = [
                         const props = node.props;
                         const ref = props?.experiment;
                         const experiment = typeof ref === 'string' ? ref : ref && typeof ref === 'object' && 'slug' in ref ? ref.slug : null;
-                        if (node.type === 'ExperimentSlot' && props && experiment === slug) {
-                            placements.push({
+                        if (node.type === 'ExperimentSlot' && props && typeof experiment === 'string' && slugs.has(experiment)) {
+                            placements.get(experiment).push({
                                 collection,
                                 id: doc.id,
                                 title: String(doc.title ?? doc.name ?? doc.id),
@@ -76,7 +83,7 @@ const slots = [
             }
         }
     }
-    return placements;
+    return args.slugs ? placements : placements.get(args.slug);
 }
 export async function flagPlacements(options, experiment, req) {
     const point = options.flagPoints?.find((point)=>point.id === experiment.flagPoint);

package/dist/transitions/preflightData.d.ts

@@ -2,7 +2,7 @@ import type { PayloadRequest } from 'payload';
 import type { PowerWeeksInput, PowerWeeksResult } from '@delmaredigital/experiments-stats';
 import type { DocId, ResolvedOptions } from '../types/contracts.js';
 import type { PreflightResult } from '../types/endpoints.js';
-import type { CheckStartInput } from './checkStart.js';
+import type { CheckStartInput, StartExperiment } from './checkStart.js';
 export interface PreflightDependencies {
     now?: Date;
     estimate?: (input: PowerWeeksInput) => PowerWeeksResult | Promise<PowerWeeksResult>;
@@ -13,6 +13,12 @@ export interface PreflightDependencies {
 export declare function loadStartInputs<TUser extends {
     id: DocId;
 }>(req: PayloadRequest, options: ResolvedOptions<TUser>, experimentId: DocId): Promise<CheckStartInput | null>;
+/** 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 declare function loadStartInputsBatch<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, options: ResolvedOptions<TUser>, experiments: StartExperiment[], tolerateErrors?: boolean): Promise<Map<string, CheckStartInput | null>>;
 export declare function preflightData<TUser extends {
     id: DocId;
 }>(req: PayloadRequest, { experimentId, options }: {