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

package/dist/collections/experiments/lockHook.js

@@ -0,0 +1,134 @@
+import { XpLockedFieldError } from '../../errors.js';
+import { xpOptionsFromReq } from '../../options/fromReq.js';
+import { EDITABLE_BY_STATUS } from './editability.js';
+import { defaultArms } from './armInvariants.js';
+const isObject = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date);
+const relationships = new Set([
+    'layer',
+    'metrics.primary',
+    'metrics.secondary',
+    'metrics.guardrails',
+    'decision.decidedBy',
+    'decision.snapshotId'
+]);
+const dates = new Set([
+    'startedAt',
+    'stoppedAt',
+    'decidedAt',
+    'archivedAt',
+    'decision.discardedAt',
+    'decision.holdoutReleasedAt'
+]);
+/** Schema-aware: JSON retains its own ids and date-like strings. */ function normalize(value, path, json = false) {
+    json ||= [
+        'arms.params',
+        'targeting.value',
+        'decision.contentReport'
+    ].includes(path);
+    if (value === undefined || value === null && !json) return undefined;
+    if (value === null) return null;
+    if (!json && relationships.has(path)) {
+        if (Array.isArray(value)) return value.length ? value.map((item)=>normalize(item, path)) : undefined;
+        if (isObject(value) && 'id' in value) return value.id == null ? undefined : String(value.id);
+        if (typeof value === 'string' || typeof value === 'number') return String(value);
+    }
+    if (!json && (value instanceof Date || dates.has(path))) {
+        const date = new Date(value);
+        if (!Number.isNaN(date.valueOf())) return date.toISOString();
+    }
+    if (Array.isArray(value)) return value.map((item)=>{
+        if (!json && [
+            'arms',
+            'targeting'
+        ].includes(path) && isObject(item)) {
+            const { id: _rowId, ...row } = item;
+            return normalize(row, path);
+        }
+        return normalize(item, path, json);
+    });
+    if (isObject(value)) return Object.fromEntries(Object.keys(value).sort().flatMap((key)=>{
+        const nested = normalize(value[key], `${path}.${key}`, json);
+        return nested === undefined ? [] : [
+            [
+                key,
+                nested
+            ]
+        ];
+    }));
+    return value;
+}
+const same = (a, b, path)=>JSON.stringify(normalize(a, path)) === JSON.stringify(normalize(b, path));
+export const lockHook = async ({ data, originalDoc, operation, req })=>{
+    if (req.context.xpTransition === true) return data;
+    const admin = async ()=>{
+        const options = xpOptionsFromReq(req);
+        return await (options.access.admin ?? options.access.manage)({
+            req
+        }) === true;
+    };
+    if (operation === 'create') {
+        const result = {
+            ...data,
+            status: 'draft',
+            phase: 0
+        };
+        // Timestamps are Payload's: a client-sent value is never stored.
+        delete result.createdAt;
+        delete result.updatedAt;
+        for (const field of [
+            'seed',
+            'layerSlices',
+            'startedAt',
+            'stoppedAt',
+            'decidedAt',
+            'archivedAt',
+            'decision'
+        ])result[field] = undefined;
+        if (!data.arms || Array.isArray(data.arms) && data.arms.length === 0) {
+            result.arms = defaultArms(data.kind);
+        }
+        if (data.kind === 'code' && !await admin()) throw new XpLockedFieldError('kind', 'draft');
+        if (data.analysis?.method != null && data.analysis.method !== 'sequential' && !await admin()) throw new XpLockedFieldError('analysis.method', 'draft');
+        return result;
+    }
+    const status = originalDoc.status;
+    const editable = EDITABLE_BY_STATUS[status] ?? [];
+    const check = async (field, value, before)=>{
+        if (same(value, before, field)) return;
+        if (!editable.includes(field.split('.')[0])) throw new XpLockedFieldError(field, status);
+        if (field === 'analysis.method' && !await admin()) throw new XpLockedFieldError(field, status);
+        if (field === 'arms' && status !== 'draft') {
+            if (Array.isArray(value) && Array.isArray(before)) {
+                const byId = new Map(before.filter((arm)=>arm.id != null).map((arm)=>[
+                        String(arm.id),
+                        arm
+                    ]));
+                const changedKey = value.some((arm, index)=>{
+                    // An unmatched id is a new row; without ids, position identifies an existing row.
+                    const previous = arm.id != null && byId.size > 0 ? byId.get(String(arm.id)) : before[index];
+                    return previous !== undefined && arm.key !== previous.key;
+                });
+                if (changedKey) throw new XpLockedFieldError('arms.key', status);
+            }
+        }
+    };
+    // Payload owns the timestamps. It rewrites `updatedAt` on every save, but stores a
+    // client-sent `createdAt` as given, so pin it to the stored value (a Restore's
+    // version carries the same value, so Restores are unaffected).
+    if ('createdAt' in data) data.createdAt = originalDoc.createdAt;
+    for (const [field, value] of Object.entries(data)){
+        if (field === 'updatedAt' || field === 'createdAt') continue;
+        if ([
+            'analysis',
+            'metrics',
+            'decision'
+        ].includes(field) && isObject(value)) {
+            for (const [key, nested] of Object.entries(value))await check(`${field}.${key}`, nested, originalDoc[field]?.[key]);
+        } else {
+            await check(field, value, originalDoc[field]);
+            // Replacing the group also changes its method, including clearing it.
+            if (field === 'analysis' && !same(value, originalDoc.analysis, field) && originalDoc.analysis?.method != null && !await admin()) throw new XpLockedFieldError('analysis.method', status);
+        }
+    }
+    return data;
+};

package/dist/collections/identities.d.ts

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

package/dist/collections/identities.js

@@ -0,0 +1,30 @@
+import { readOnlyAccess } from './access.js';
+export function identitiesCollection(options) {
+    return {
+        slug: 'xp-identities',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            hidden: true
+        },
+        access: readOnlyAccess(options.access.readIdentities ?? options.access.admin ?? options.access.manage),
+        fields: [
+            {
+                name: 'anonymousId',
+                type: 'text',
+                unique: true,
+                required: true
+            },
+            {
+                name: 'userId',
+                type: 'text',
+                required: true
+            },
+            {
+                name: 'linkedAt',
+                type: 'date',
+                required: true
+            }
+        ]
+    };
+}

package/dist/collections/index.d.ts

@@ -0,0 +1,6 @@
+import type { CollectionConfig, GlobalConfig } from 'payload';
+import type { ResolvedOptions } from '../types/contracts.js';
+export declare function buildCollections(options: ResolvedOptions): {
+    collections: CollectionConfig[];
+    globals: GlobalConfig[];
+};

package/dist/collections/index.js

@@ -0,0 +1,24 @@
+import { experimentsCollection } from './experiments/config.js';
+import { phasesCollection } from './phases.js';
+import { layersCollection } from './layers.js';
+import { metricsCollection } from './metrics.js';
+import { eventsCollection } from './events.js';
+import { identitiesCollection } from './identities.js';
+import { snapshotsCollection } from './snapshots.js';
+import { stateGlobal } from '../globals/state.js';
+export function buildCollections(options) {
+    return {
+        collections: [
+            experimentsCollection(options),
+            phasesCollection(options),
+            layersCollection(options),
+            metricsCollection(options),
+            eventsCollection(options),
+            identitiesCollection(options),
+            snapshotsCollection(options)
+        ],
+        globals: [
+            stateGlobal(options)
+        ]
+    };
+}

package/dist/collections/layers.d.ts

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

package/dist/collections/layers.js

@@ -0,0 +1,77 @@
+import { XpRefusal } from '../errors.js';
+import { XP_LAYER_USAGE } from '../admin/paths.js';
+import { managedAccess } from './access.js';
+export function layersCollection(options) {
+    return {
+        slug: 'xp-layers',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            useAsTitle: 'name'
+        },
+        access: managedAccess(options),
+        fields: [
+            {
+                name: 'name',
+                type: 'text',
+                required: true
+            },
+            {
+                name: 'slug',
+                type: 'text',
+                unique: true,
+                required: true,
+                validate: (value, { operation, previousValue })=>{
+                    if (operation === 'update' && value === undefined) return true;
+                    if (typeof value !== 'string' || !value.length) return 'Enter a slug.';
+                    return operation !== 'update' || value === previousValue || 'slug is set when the layer is created.';
+                }
+            },
+            {
+                name: 'unitType',
+                type: 'select',
+                required: true,
+                options: [
+                    'visitor',
+                    'user'
+                ],
+                validate: (value, { operation, previousValue })=>{
+                    if (operation === 'update' && value === undefined) return true;
+                    if (value !== 'visitor' && value !== 'user') return 'Choose visitors or signed-in users.';
+                    return operation !== 'update' || value === previousValue || 'unitType is set when the layer is created.';
+                }
+            },
+            {
+                name: 'description',
+                type: 'textarea'
+            },
+            {
+                name: 'usage',
+                type: 'ui',
+                admin: {
+                    components: {
+                        Field: XP_LAYER_USAGE
+                    }
+                }
+            }
+        ],
+        hooks: {
+            beforeDelete: [
+                async ({ id, req })=>{
+                    const references = await req.payload.find({
+                        collection: 'xp-experiments',
+                        where: {
+                            layer: {
+                                equals: id
+                            }
+                        },
+                        limit: 1,
+                        overrideAccess: false,
+                        req
+                    });
+                    if (references.docs.length) throw new XpRefusal('invalid-status', 'This layer is still referenced by an experiment.', undefined, 409);
+                }
+            ]
+        }
+    };
+}

package/dist/collections/metrics.d.ts

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

package/dist/collections/metrics.js

@@ -0,0 +1,115 @@
+import { XP_METRIC_SOURCE_SELECT } from '../admin/paths.js';
+import { managedAccess } from './access.js';
+import { serializeMetricSources } from './serialize.js';
+export function metricsCollection(options) {
+    const sources = serializeMetricSources(options);
+    return {
+        slug: 'xp-metrics',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            useAsTitle: 'name'
+        },
+        access: managedAccess(options),
+        hooks: {
+            beforeValidate: [
+                ({ data, originalDoc })=>{
+                    if (!data) return data;
+                    const source = sources.find((source)=>source.id === (data.source ?? originalDoc?.source));
+                    const capping = data.capping === undefined ? originalDoc?.capping : data.capping;
+                    // Payload may submit an empty optional group as { type: null, value: null }.
+                    const hasCapping = capping != null && (capping.type != null || capping.value != null);
+                    if (source?.kind === 'revenue' && !hasCapping) data.capping = {
+                        type: 'percentile',
+                        value: 0.99
+                    };
+                    return data;
+                }
+            ]
+        },
+        fields: [
+            {
+                name: 'name',
+                type: 'text',
+                required: true
+            },
+            {
+                name: 'slug',
+                type: 'text',
+                required: true,
+                unique: true
+            },
+            {
+                name: 'source',
+                type: 'text',
+                required: true,
+                validate: (value)=>sources.some((source)=>source.id === value) || 'Choose a registered metric source.',
+                admin: {
+                    components: {
+                        Field: XP_METRIC_SOURCE_SELECT
+                    },
+                    custom: {
+                        sources
+                    }
+                }
+            },
+            {
+                name: 'direction',
+                type: 'select',
+                required: true,
+                defaultValue: 'increase',
+                options: [
+                    'increase',
+                    'decrease'
+                ]
+            },
+            {
+                name: 'attributionWindowHours',
+                type: 'number',
+                defaultValue: 168,
+                min: 1
+            },
+            {
+                name: 'capping',
+                type: 'group',
+                fields: [
+                    {
+                        name: 'type',
+                        type: 'select',
+                        options: [
+                            'percentile',
+                            'absolute'
+                        ],
+                        validate: (value, { data, siblingData })=>{
+                            const hasCapping = value != null || siblingData?.value != null;
+                            const source = sources.find((source)=>source.id === data?.source);
+                            if (hasCapping && source && source.kind !== 'revenue') return 'Count and conversion metrics cannot be capped.';
+                            return !hasCapping || value === 'percentile' || value === 'absolute' || 'Choose a capping type.';
+                        }
+                    },
+                    {
+                        name: 'value',
+                        type: 'number',
+                        min: 0,
+                        validate: (value, { siblingData })=>{
+                            if (value == null && !siblingData?.type) return true;
+                            return typeof value === 'number' && Number.isFinite(value) && value >= 0 && (siblingData?.type === 'absolute' || siblingData?.type === 'percentile' && value > 0 && value <= 1) || 'Enter a valid cap (percentiles must be greater than 0 and at most 1).';
+                        }
+                    }
+                ]
+            },
+            {
+                name: 'minSampleSize',
+                type: 'number',
+                defaultValue: 150,
+                min: 1
+            },
+            {
+                name: 'guardrailThreshold',
+                type: 'number',
+                defaultValue: 0.05,
+                min: 0
+            }
+        ]
+    };
+}

package/dist/collections/phases.d.ts

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

package/dist/collections/phases.js

@@ -0,0 +1,59 @@
+import { readOnlyAccess } from './access.js';
+export function phasesCollection(options) {
+    return {
+        slug: 'xp-phases',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            hidden: true
+        },
+        access: readOnlyAccess(options.access.readResults ?? options.access.manage),
+        fields: [
+            {
+                name: 'experiment',
+                type: 'relationship',
+                relationTo: 'xp-experiments'
+            },
+            {
+                name: 'phase',
+                type: 'number',
+                required: true
+            },
+            {
+                name: 'phaseKind',
+                type: 'select',
+                required: true,
+                options: [
+                    'test',
+                    'rollout'
+                ]
+            },
+            {
+                name: 'startedAt',
+                type: 'date',
+                required: true
+            },
+            {
+                name: 'endedAt',
+                type: 'date'
+            },
+            {
+                name: 'seed',
+                type: 'text',
+                required: true
+            },
+            ...[
+                'arms',
+                'allocation',
+                'allocationChanges',
+                'targeting',
+                'metricDefinitions',
+                'analysis',
+                'contentChanges'
+            ].map((name)=>({
+                    name,
+                    type: 'json'
+                }))
+        ]
+    };
+}

package/dist/collections/serialize.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedOptions } from '../types/contracts.js';
+import type { SerializedAttributeKeys, SerializedFlagPoint, SerializedMetricSource } from '../types/admin.js';
+export declare function serializeFlagPoints(options: ResolvedOptions): SerializedFlagPoint[];
+export declare function serializeMetricSources(options: ResolvedOptions): SerializedMetricSource[];
+export declare function serializeAttributeKeys(options: ResolvedOptions): SerializedAttributeKeys;

package/dist/collections/serialize.js

@@ -0,0 +1,40 @@
+export function serializeFlagPoints(options) {
+    return (options.flagPoints ?? []).map(({ id, label, params, defaultParams })=>({
+            id,
+            label,
+            params,
+            defaultParams,
+            effectiveDefaults: defaultParams
+        }));
+}
+export function serializeMetricSources(options) {
+    return [
+        ...(options.metricSources ?? []).map(({ id, label, kind, keyedBy, clientWritable })=>({
+                id,
+                label,
+                kind,
+                keyedBy,
+                clientWritable: clientWritable === true
+            })),
+        ...(options.eventSources ?? []).map(({ name, clientWritable })=>({
+                id: `events:${name}`,
+                label: name,
+                kind: 'binomial',
+                keyedBy: 'visitor',
+                clientWritable
+            }))
+    ];
+}
+export function serializeAttributeKeys(options) {
+    return Object.fromEntries(Object.entries(options.attributeKeys ?? {}).map(([key, { type, values }])=>[
+            key,
+            {
+                type,
+                ...values ? {
+                    values: [
+                        ...values
+                    ]
+                } : {}
+            }
+        ]));
+}

package/dist/collections/snapshots.d.ts

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

package/dist/collections/snapshots.js

@@ -0,0 +1,47 @@
+import { readOnlyAccess } from './access.js';
+export function snapshotsCollection(options) {
+    return {
+        slug: 'xp-results-snapshots',
+        graphQL: false,
+        disableDuplicate: true,
+        admin: {
+            hidden: true
+        },
+        access: readOnlyAccess(options.access.readResults ?? options.access.manage),
+        indexes: [
+            {
+                fields: [
+                    'experiment',
+                    'computedAt'
+                ]
+            }
+        ],
+        fields: [
+            {
+                name: 'experiment',
+                type: 'relationship',
+                relationTo: 'xp-experiments'
+            },
+            {
+                name: 'phase',
+                type: 'number',
+                required: true
+            },
+            {
+                name: 'computedAt',
+                type: 'date',
+                required: true
+            },
+            {
+                name: 'window',
+                type: 'json',
+                required: true
+            },
+            {
+                name: 'snapshot',
+                type: 'json',
+                required: true
+            }
+        ]
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_EVENTS_PER_BODY = 20;
+export declare const DEFAULT_MAX_BODY_BYTES = 8192;
+export declare const XP_COOKIE = "xp_id";
+export declare const XP_HEADER = "x-xp-assignments";
+export declare const XP_PREVIEW_PARAM = "xp_preview";
+export declare const XP_MANIFEST_KEY_HEADER = "x-xp-manifest-key";
+export declare const XP_REQUEST_HEADER = "x-xp-request";

package/dist/constants.js

@@ -0,0 +1,7 @@
+export const MAX_EVENTS_PER_BODY = 20;
+export const DEFAULT_MAX_BODY_BYTES = 8192;
+export const XP_COOKIE = 'xp_id';
+export const XP_HEADER = 'x-xp-assignments';
+export const XP_PREVIEW_PARAM = 'xp_preview';
+export const XP_MANIFEST_KEY_HEADER = 'x-xp-manifest-key';
+export const XP_REQUEST_HEADER = 'x-xp-request';

package/dist/db/adapter.d.ts

@@ -0,0 +1,3 @@
+import type { Payload } from 'payload';
+export declare function assertPostgresAdapter(payload: Payload): void;
+export declare function probeTransactions(payload: Payload): Promise<void>;

package/dist/db/adapter.js

@@ -0,0 +1,9 @@
+export function assertPostgresAdapter(payload) {
+    // @payloadcms/db-postgres/dist/index.js:133 declares this package marker.
+    if (payload.db.packageName !== '@payloadcms/db-postgres') throw new Error('Experiments requires @payloadcms/db-postgres');
+}
+export async function probeTransactions(payload) {
+    const id = await payload.db.beginTransaction();
+    if (id == null) throw new Error('Experiments transactions are disabled');
+    await payload.db.rollbackTransaction(id);
+}

package/dist/db/appends.d.ts

@@ -0,0 +1,58 @@
+import type { Executor } from './executor.js';
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+export interface AllocationChange {
+    at: string;
+    from: number;
+    to: number;
+}
+export interface ContentChange {
+    at: string;
+    doc: {
+        collection: string;
+        id: DocId;
+    };
+    by: DocId | null;
+}
+type AppendArgs<T> = {
+    experimentId: DocId;
+    phase: number;
+    entry: T;
+};
+/** Read the main collection row BEFORE the host write. Draft version retention
+ * and unpublishing cannot remove this baseline. Adapter reads avoid Local API
+ * error handling killing the host transaction before savepoint recovery.
+ */
+export declare function previousPublishedContent(req: PayloadRequest, collection: string, id: DocId): Promise<Record<string, unknown> | undefined>;
+/** Serialize flagDefaults read/modify/write before the manifest builder bumps. */
+export declare function lockContentDefaults(exec: Executor): Promise<void>;
+/** §7.8 contentChanges exception: internal lookup on the host transaction.
+ * Use the executor directly: Payload Local API read errors kill the caller's
+ * transaction before a never-throw hook can recover its audit savepoint.
+ */
+export declare function runningContentExperiment(exec: Executor, binding: {
+    field: 'id' | 'slug';
+    value: DocId;
+}): Promise<{
+    id: DocId;
+    phase: number;
+} | undefined>;
+/** Requires the experiment lock on the transaction executor (withTransition).
+ * The generated schema stores allocationChanges as one JSONB column, not rows.
+ */
+export declare function appendAllocationChange(exec: Executor, args: AppendArgs<AllocationChange>): Promise<void>;
+/** Requires the experiment lock on the transaction executor (withTransition).
+ * The generated schema stores contentChanges as one JSONB column, not rows.
+ */
+export declare function appendContentChange(exec: Executor, args: AppendArgs<ContentChange>): Promise<void>;
+/** A best-effort audit must not abort the host write sharing its transaction.
+ * Recover SQL errors before returning them: catching alone leaves Postgres aborted.
+ */
+export declare function contentChangeSavepoint<T>(exec: Executor, fn: () => Promise<T>): Promise<{
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: unknown;
+}>;
+export {};