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

package/dist/admin/actions/actions.model.js

@@ -0,0 +1,71 @@
+import { armLabel } from '../labels.js';
+import { ACTIONS_COPY as C, hardCodedLabel, makeContentCopy, releaseCopy } from '../copy/actions.js';
+import { REVIEW_COPY } from '../copy/review.js';
+export function actionGroupLabel(key, storedLabel) {
+    return storedLabel?.trim() || armLabel(key);
+}
+export function availableActions({ status, kind, arms, decision, canManage }) {
+    if (!canManage) return [];
+    const action = (id, label, body, tone = 'secondary', archive, phrase)=>({
+            id,
+            label,
+            tone,
+            confirm: {
+                title: label,
+                body,
+                ...phrase ? {
+                    phrase: {
+                        action: phrase
+                    }
+                } : {}
+            },
+            ...archive ? {
+                archive
+            } : {}
+        });
+    const start = action('start', status === 'stopped' ? C.restart : C.start, status === 'stopped' ? C.restartBody : C.startBody, 'primary');
+    const decide = action('decide', C.decide, '', 'primary');
+    if (status === 'draft') return [
+        start
+    ];
+    if (status === 'running') return [
+        action('stop', C.stop, C.stopBody, 'danger'),
+        decide,
+        action('allocate', REVIEW_COPY.raise, REVIEW_COPY.allocationBody),
+        action('add-metric', REVIEW_COPY.addMetric, '')
+    ];
+    if (status === 'stopped') return [
+        start,
+        decide,
+        action('archive', C.archive, C.archiveBody, 'secondary', {
+            mode: 'stopped'
+        })
+    ];
+    if (status !== 'decided') return [];
+    const winner = arms.find((group)=>group.key === decision?.winnerArm);
+    const label = actionGroupLabel(decision?.winnerArm ?? 'control', winner?.label);
+    const rolloutOpen = arms.some((group)=>group.key === 'holdout') && Boolean(decision?.winnerArm) && decision?.winnerArm !== 'control' && !decision?.holdoutReleasedAt;
+    const report = decision?.contentReport;
+    const docs = Array.isArray(report) ? report : report?.docs;
+    return [
+        ...rolloutOpen ? [
+            action('release-holdout', C.release, releaseCopy(label))
+        ] : [],
+        ...kind !== 'code' ? [
+            action('make-content', C.makeContent, makeContentCopy(label, kind), 'primary')
+        ] : [],
+        ...docs?.length && docs.every((doc)=>doc.ok) ? [
+            action('after-content', C.finish, C.finishBody, 'secondary', {
+                mode: 'after-content'
+            })
+        ] : [],
+        action('discard', C.discard, C.discardBody, 'danger', {
+            mode: 'discard'
+        }, 'discard'),
+        ...kind === 'code' ? [
+            action('hard-coded', hardCodedLabel(label), hardCodedLabel(label), 'primary', {
+                mode: 'hard-coded'
+            }, 'hard-coded')
+        ] : []
+    ];
+}

package/dist/admin/actions/decide.model.d.ts

@@ -0,0 +1,21 @@
+import type { Snapshot } from '../../types/snapshot.js';
+import type { DecideBody } from '../../types/endpoints.js';
+import { type ActionGroup } from './actions.model.js';
+export declare function decideState({ snapshot, arms, chosenArm, note, typed }: {
+    snapshot: Snapshot | null;
+    arms: readonly ActionGroup[];
+    chosenArm: string | null;
+    note: string;
+    typed: string;
+}): {
+    options: {
+        value: string;
+        label: string;
+    }[];
+    prefill: string | null;
+    guarded: boolean;
+    reason: string | null;
+    phrase: string;
+    canSubmit: boolean;
+    body: DecideBody;
+};

package/dist/admin/actions/decide.model.js

@@ -0,0 +1,38 @@
+import { decideGuard } from '../../results/decideGuard.js';
+import { expectedConfirm, matchesConfirm } from '../../transitions/confirmPhrases.js';
+import { ACTIONS_COPY as C } from '../copy/actions.js';
+import { actionGroupLabel } from './actions.model.js';
+export function decideState({ snapshot, arms, chosenArm, note, typed }) {
+    const options = arms.filter((group)=>group.key !== 'holdout' && group.kind !== 'holdout').map((group)=>({
+            value: group.key,
+            label: actionGroupLabel(group.key, group.label)
+        }));
+    const chosen = options.find((option)=>option.value === chosenArm);
+    const guarded = decideGuard(snapshot, chosenArm ?? '');
+    const phrase = expectedConfirm('decide', chosen?.label ?? '');
+    const reason = !chosen || !guarded ? null : snapshot && typeof snapshot.verdict.row === 'number' && [
+        1,
+        2,
+        3,
+        4
+    ].includes(snapshot.verdict.row) ? snapshot.verdict.headline : !snapshot ? C.noResults : snapshot.verdict.recommendedArm === null ? C.noRecommendation : chosenArm !== snapshot.verdict.recommendedArm ? C.different : null;
+    const canSubmit = Boolean(chosen) && (!guarded || note.trim() !== '' && matchesConfirm(phrase, typed));
+    const body = {
+        winnerArm: chosenArm ?? '',
+        ...note.trim() ? {
+            note: note.trim()
+        } : {},
+        ...guarded ? {
+            confirmation: typed.trim()
+        } : {}
+    };
+    return {
+        options,
+        prefill: snapshot?.verdict.recommendedArm ?? null,
+        guarded,
+        reason,
+        phrase,
+        canSubmit,
+        body
+    };
+}

package/dist/admin/allocation.model.d.ts

@@ -0,0 +1,20 @@
+import type { Arm, Status, UnitType } from '../types/contracts.js';
+export type AllocationGroup = Pick<Arm, 'key' | 'weight' | 'kind'> & {
+    label?: string;
+};
+export type AllocationLayer = {
+    name: string;
+    used: number;
+    free: number;
+};
+export declare function allocationSentence({ allocation, unitType, arms, layer, status }: {
+    allocation: number;
+    unitType: UnitType;
+    arms: readonly AllocationGroup[];
+    layer?: AllocationLayer;
+    status: Status;
+}): string;
+export declare function allocationGroups(fields: Record<string, {
+    value?: unknown;
+}>, path?: string): AllocationGroup[];
+export declare function allocationLayer(value: unknown): AllocationLayer | undefined;

package/dist/admin/allocation.model.js

@@ -0,0 +1,38 @@
+import { armLabel } from './labels.js';
+import { LOCKED_MESSAGES } from './copy/common.js';
+import { eachVersion, groupShare, holdoutClause, layerSentence, participation, peopleLabel, uncounted } from './copy/who.js';
+const percent = (value)=>String(Math.round(value * 10) / 10);
+export function allocationSentence({ allocation, unitType, arms, layer, status }) {
+    const groups = arms.filter((group)=>group.kind !== 'holdout');
+    if (!groups.length || !Number.isFinite(allocation)) return '';
+    const equal = groups.every((group)=>group.weight === groups[0].weight);
+    const shares = equal ? eachVersion(percent(allocation * groups[0].weight / 100)) : groups.map((group)=>groupShare(percent(allocation * group.weight / 100), armLabel(group.key, group.label))).join(', ');
+    const holdout = arms.find((group)=>group.kind === 'holdout');
+    let sentence = participation(percent(allocation), peopleLabel[unitType], shares) + (holdout ? holdoutClause(percent(holdout.weight)) : uncounted);
+    if ((layer || status === 'running') && !sentence.endsWith('.')) sentence += '.';
+    if (layer) sentence += layerSentence(layer.name, layer.used, layer.free);
+    if (status === 'running') sentence += ` ${LOCKED_MESSAGES.runningAllocation}`;
+    return sentence;
+}
+// Payload arrays are flattened into row fields; their parent value is a row count.
+export function allocationGroups(fields, path = 'arms') {
+    const direct = fields[path]?.value;
+    if (Array.isArray(direct)) return direct;
+    const rows = new Map();
+    for (const [key, field] of Object.entries(fields)){
+        if (!key.startsWith(`${path}.`)) continue;
+        const [index, property, ...rest] = key.slice(path.length + 1).split('.');
+        if (!index || !/^\d+$/.test(index) || !property || rest.length) continue;
+        const row = rows.get(Number(index)) ?? {};
+        row[property] = field.value;
+        rows.set(Number(index), row);
+    }
+    return [
+        ...rows.entries()
+    ].sort(([a], [b])=>a - b).map(([, row])=>row).filter((row)=>typeof row.key === 'string' && typeof row.weight === 'number' && typeof row.kind === 'string');
+}
+export function allocationLayer(value) {
+    if (!value || typeof value !== 'object') return undefined;
+    const layer = value;
+    return typeof layer.name === 'string' && typeof layer.used === 'number' && Number.isFinite(layer.used) && typeof layer.free === 'number' && Number.isFinite(layer.free) ? layer : undefined;
+}

package/dist/admin/api.d.ts

@@ -0,0 +1,32 @@
+import type { DocId } from '../types/contracts.js';
+import type { AddMetricBody, AllocateBody, ArchiveBody, DecideBody, MakeContentResult, PreflightResult, PreviewTokenResult, RefusalCode, ResultsResponse, SummaryResponse, TransitionSuccess } from '../types/endpoints.js';
+export type ApiResult<T> = {
+    ok: true;
+    data: T | undefined;
+} | {
+    ok: false;
+    status: number;
+    code?: RefusalCode;
+    message: string;
+    retryable: boolean;
+};
+export declare function createApi(apiBase: string): {
+    start: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
+    allocate: (id: DocId, body: AllocateBody) => Promise<ApiResult<TransitionSuccess>>;
+    addMetric: (id: DocId, body: AddMetricBody) => Promise<ApiResult<TransitionSuccess>>;
+    stop: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
+    decide: (id: DocId, body: DecideBody) => Promise<ApiResult<TransitionSuccess>>;
+    releaseHoldout: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
+    makeContent: (id: DocId) => Promise<ApiResult<MakeContentResult>>;
+    archive: (id: DocId, body: ArchiveBody) => Promise<ApiResult<TransitionSuccess>>;
+    preflight: (id: DocId) => Promise<ApiResult<PreflightResult>>;
+    previewToken: (id: DocId, arm: string) => Promise<ApiResult<PreviewTokenResult>>;
+    results: (id: DocId, options?: {
+        phase?: number;
+        series?: boolean;
+    }) => Promise<ApiResult<ResultsResponse>>;
+    recompute: (id: DocId) => Promise<ApiResult<{
+        snapshotId: string;
+    }>>;
+    summary: (ids: readonly DocId[]) => Promise<ApiResult<SummaryResponse>>;
+};

package/dist/admin/api.js

@@ -0,0 +1,95 @@
+import { API_MESSAGES, refusalMessage } from './copy/common.js';
+export function createApi(apiBase) {
+    const base = `${apiBase.replace(/\/$/, '')}/xp/experiments`;
+    const route = (id, action)=>`${base}/${encodeURIComponent(id)}/${action}`;
+    async function request(path, method, body) {
+        try {
+            const response = await fetch(path(), {
+                method,
+                credentials: 'include',
+                ...body === undefined ? {} : {
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify(body)
+                }
+            });
+            let data;
+            try {
+                data = await response.json();
+            } catch  {
+                if (response.ok) return {
+                    ok: true,
+                    data: undefined
+                };
+                return {
+                    ok: false,
+                    status: response.status,
+                    ...response.status === 501 ? {
+                        code: 'not-implemented'
+                    } : {},
+                    message: refusalMessage(undefined, response.status),
+                    retryable: response.status >= 500 && response.status !== 501
+                };
+            }
+            if (response.ok) return {
+                ok: true,
+                data: data
+            };
+            // Payload's own errors may omit code; future server codes retain their message.
+            const envelope = data;
+            const error = Array.isArray(envelope?.errors) ? envelope.errors[0] : undefined;
+            const code = response.status === 501 ? 'not-implemented' : typeof error?.code === 'string' ? error.code : undefined;
+            return {
+                ok: false,
+                status: response.status,
+                ...code ? {
+                    code
+                } : {},
+                message: refusalMessage(code, response.status, typeof error?.message === 'string' ? error.message : undefined),
+                retryable: code === 'commit-unverified' || response.status >= 500 && response.status !== 501
+            };
+        } catch  {
+            return {
+                ok: false,
+                status: 0,
+                message: API_MESSAGES.network,
+                retryable: true
+            };
+        }
+    }
+    const post = (id, action, body)=>request(()=>route(id, action), 'POST', body);
+    return {
+        start: (id)=>post(id, 'start'),
+        allocate: (id, body)=>post(id, 'allocate', body),
+        addMetric: (id, body)=>post(id, 'add-metric', body),
+        stop: (id)=>post(id, 'stop'),
+        decide: (id, body)=>post(id, 'decide', body),
+        releaseHoldout: (id)=>post(id, 'release-holdout'),
+        makeContent: (id)=>post(id, 'make-content'),
+        archive: (id, body)=>post(id, 'archive', body),
+        preflight: (id)=>request(()=>route(id, 'preflight'), 'GET'),
+        previewToken: (id, arm)=>request(()=>`${route(id, 'preview-token')}?arm=${encodeURIComponent(arm)}`, 'GET'),
+        results: (id, options = {})=>request(()=>{
+                const query = new URLSearchParams();
+                if (options.phase !== undefined) query.set('phase', String(options.phase));
+                if (options.series) query.set('series', '1');
+                const qs = query.toString();
+                return `${route(id, 'results')}${qs ? `?${qs}` : ''}`;
+            }, 'GET'),
+        recompute: (id)=>post(id, 'recompute'),
+        summary: async (ids)=>{
+            const data = {};
+            // Wire format: comma-separated ids, each URI-encoded; at most 100 per request.
+            for(let offset = 0; offset < ids.length; offset += 100){
+                const result = await request(()=>`${base}/summary?ids=${ids.slice(offset, offset + 100).map((id)=>encodeURIComponent(id)).join(',')}`, 'GET');
+                if (!result.ok) return result;
+                Object.assign(data, result.data);
+            }
+            return {
+                ok: true,
+                data
+            };
+        }
+    };
+}

package/dist/admin/armSelect/ArmSelectField.d.ts

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

package/dist/admin/armSelect/ArmSelectField.js

@@ -0,0 +1,185 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Banner, Button, SelectInput, useConfig, useField } from '@payloadcms/ui';
+import { useEffect, useState } from 'react';
+import { bindArmSelect, experimentId } from './armSelect.model.js';
+import { ARM_SELECT_COPY } from '../copy/armSelect.js';
+export function ArmSelectField({ path, field, readOnly }) {
+    const { config } = useConfig();
+    const api = config.routes.api;
+    const point = String(field.admin?.custom?.flagPoint ?? '');
+    const key = `${api}:${point}`;
+    const experiment = useField({
+        path: `${path}.experiment`
+    });
+    const arm = useField({
+        path: `${path}.arm`
+    });
+    const storedId = experimentId(experiment.value);
+    const [loaded, setLoaded] = useState(null);
+    const [error, setError] = useState(null);
+    const [earlier, setEarlier] = useState(null);
+    const locked = Boolean(readOnly || field.admin?.readOnly);
+    useEffect(()=>{
+        setLoaded(null);
+        setError(null);
+        if (!point) return;
+        const controller = new AbortController();
+        async function list(statuses) {
+            const docs = [];
+            let page = 1;
+            while(!controller.signal.aborted){
+                const query = new URLSearchParams({
+                    depth: '0',
+                    limit: '100',
+                    page: String(page),
+                    'where[flagPoint][equals]': point,
+                    'where[status][in]': statuses
+                });
+                const response = await fetch(`${api}/xp-experiments?${query}`, {
+                    credentials: 'include',
+                    signal: controller.signal
+                });
+                if (!response.ok) throw new Error(response.status === 403 ? ARM_SELECT_COPY.forbidden : ARM_SELECT_COPY.unavailable);
+                const data = await response.json();
+                docs.push(...data.docs);
+                if (!data.hasNextPage) break;
+                page++;
+            }
+            return docs;
+        }
+        void Promise.all([
+            list('running,decided'),
+            list('draft,stopped')
+        ]).then(([live, candidates])=>{
+            if (!controller.signal.aborted) {
+                setError(null);
+                setLoaded({
+                    key,
+                    live: live[0] ?? null,
+                    candidates
+                });
+            }
+        }).catch((reason)=>{
+            if (!controller.signal.aborted) setError({
+                key,
+                message: reason instanceof Error ? reason.message : ARM_SELECT_COPY.unavailable
+            });
+        });
+        return ()=>controller.abort();
+    }, [
+        api,
+        point,
+        key
+    ]);
+    const data = loaded?.key === key && error?.key !== key ? loaded : null;
+    const known = data && storedId != null && [
+        data.live,
+        ...data.candidates
+    ].some((doc)=>doc && String(doc.id) === String(storedId));
+    useEffect(()=>{
+        if (!point || !data || storedId == null || known) return;
+        const controller = new AbortController();
+        void fetch(`${api}/xp-experiments/${encodeURIComponent(storedId)}?depth=0`, {
+            credentials: 'include',
+            signal: controller.signal
+        }).then(async (response)=>{
+            if (!response.ok) return;
+            const doc = await response.json();
+            if (!controller.signal.aborted) setEarlier({
+                key,
+                id: String(storedId),
+                name: doc.name
+            });
+        }).catch(()=>{});
+        return ()=>controller.abort();
+    }, [
+        api,
+        data,
+        key,
+        known,
+        point,
+        storedId
+    ]);
+    if (!point) return /*#__PURE__*/ _jsx("p", {
+        role: "status",
+        children: ARM_SELECT_COPY.noFlagPoint
+    });
+    if (error?.key === key) return /*#__PURE__*/ _jsx("p", {
+        role: "status",
+        children: error.message
+    });
+    if (!data) return /*#__PURE__*/ _jsx("p", {
+        role: "status",
+        children: ARM_SELECT_COPY.loading
+    });
+    const reference = earlier?.key === key && earlier.id === String(storedId) ? {
+        id: storedId,
+        name: earlier.name
+    } : experiment.value;
+    const binding = bindArmSelect({
+        ...data,
+        stored: {
+            experiment: reference,
+            arm: arm.value
+        }
+    });
+    const write = (id, value)=>{
+        if (!locked) {
+            experiment.setValue(id == null ? null : String(id));
+            arm.setValue(value);
+        }
+    };
+    return /*#__PURE__*/ _jsxs("div", {
+        className: "xp-arm-select",
+        children: [
+            binding.banner ? /*#__PURE__*/ _jsx(Banner, {
+                children: binding.banner
+            }) : null,
+            binding.stale ? /*#__PURE__*/ _jsxs("div", {
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        children: binding.stale
+                    }),
+                    /*#__PURE__*/ _jsx(Button, {
+                        disabled: locked,
+                        onClick: ()=>write(null, null),
+                        children: ARM_SELECT_COPY.clear
+                    })
+                ]
+            }) : null,
+            binding.pickable ? /*#__PURE__*/ _jsx(SelectInput, {
+                path: `${path}.experiment`,
+                name: `${path}.experiment`,
+                label: ARM_SELECT_COPY.experiment,
+                options: data.candidates.map((doc)=>({
+                        label: doc.name,
+                        value: String(doc.id)
+                    })),
+                value: binding.bound ? String(binding.bound.id) : '',
+                readOnly: locked,
+                onChange: (option)=>{
+                    if (Array.isArray(option)) return;
+                    const candidate = data.candidates.find((doc)=>String(doc.id) === option?.value);
+                    write(candidate?.id ?? null, null);
+                }
+            }) : null,
+            /*#__PURE__*/ _jsx(SelectInput, {
+                path: `${path}.arm`,
+                name: `${path}.arm`,
+                label: ARM_SELECT_COPY.group,
+                required: field.fields.some((child)=>'name' in child && child.name === 'arm' && 'required' in child && child.required),
+                options: binding.options,
+                readOnly: locked || !binding.bound,
+                value: !binding.stale && binding.options.some((option)=>option.value === arm.value) ? arm.value ?? '' : '',
+                onChange: (option)=>{
+                    if (binding.bound && !Array.isArray(option)) write(binding.bound.id, typeof option?.value === 'string' ? option.value : null);
+                }
+            }),
+            arm.showError ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: arm.errorMessage
+            }) : null
+        ]
+    });
+}

package/dist/admin/armSelect/armSelect.model.d.ts

@@ -0,0 +1,30 @@
+import type { Arm, DocId, Status } from '../../types/contracts.js';
+export type ArmSelectExperiment = {
+    id: DocId;
+    name: string;
+    status: Status;
+    arms: Pick<Arm, 'key' | 'kind' | 'label'>[];
+};
+export type ExperimentReference = DocId | {
+    id: DocId;
+    name?: string;
+};
+export type StoredArmSelect = {
+    experiment?: ExperimentReference | null;
+    arm?: string | null;
+};
+export declare function experimentId(reference: ExperimentReference | null | undefined): DocId | null;
+export declare function bindArmSelect({ live, candidates, stored }: {
+    live?: ArmSelectExperiment | null;
+    candidates: readonly ArmSelectExperiment[];
+    stored: StoredArmSelect;
+}): {
+    bound: ArmSelectExperiment | null;
+    pickable: boolean;
+    options: {
+        label: string;
+        value: import("../../types/contracts.js").ArmKey;
+    }[];
+    stale: string | null;
+    banner: string | null;
+};

package/dist/admin/armSelect/armSelect.model.js

@@ -0,0 +1,20 @@
+import { ARM_SELECT_COPY, staleExperiment } from '../copy/armSelect.js';
+export function experimentId(reference) {
+    return reference == null ? null : typeof reference === 'object' ? reference.id : reference;
+}
+export function bindArmSelect({ live, candidates, stored }) {
+    const id = experimentId(stored.experiment);
+    const previous = candidates.find((candidate)=>id != null && String(candidate.id) === String(id));
+    const bound = live ?? previous ?? null;
+    const oldName = typeof stored.experiment === 'object' ? stored.experiment?.name : undefined;
+    return {
+        bound,
+        pickable: !live,
+        options: (bound?.arms ?? []).filter((arm)=>arm.kind !== 'holdout').map((arm)=>({
+                label: arm.label,
+                value: arm.key
+            })),
+        stale: id != null && (bound == null || String(id) !== String(bound.id)) ? staleExperiment(previous?.name ?? oldName) : null,
+        banner: bound?.status === 'running' ? ARM_SELECT_COPY.running : null
+    };
+}

package/dist/admin/arms/ArmsField.d.ts

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