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

package/dist/server/getFlagPoint.js

@@ -0,0 +1,36 @@
+import { getAssignments } from './getAssignments.js';
+import { recordExposures } from './recordExposures.js';
+import { suppressExposure } from './context.js';
+export async function getFlagPoint(serverRuntime, id, opts) {
+    const assignments = await getAssignments(serverRuntime, opts);
+    const point = Object.hasOwn(assignments.flagPoints, id) ? assignments.flagPoints[id] : {
+        arm: 'control',
+        params: {},
+        source: 'default',
+        exposable: false
+    };
+    const result = {
+        ...point,
+        params: {
+            ...point.params
+        },
+        exposable: point.exposable && !suppressExposure(assignments)
+    };
+    return {
+        ...result,
+        async expose (renderedArm) {
+            if (result.policy !== 'manual' || !result.exposable || !result.experiment || result.phase === undefined) return;
+            try {
+                await recordExposures(serverRuntime, [
+                    {
+                        slug: result.experiment,
+                        arm: renderedArm,
+                        phase: result.phase
+                    }
+                ], assignments);
+            } catch  {
+                console.error('[payload-experiments] flag point exposure failed');
+            }
+        }
+    };
+}

package/dist/server/headerRevision.d.ts

@@ -0,0 +1,6 @@
+/** Authenticate before a revision can trigger I/O. Entry/phase validation stays in the shared decoder. */
+export declare function verifiedHeaderRevision(value: string | null, opts: {
+    secrets: readonly string[];
+    visitorId?: string;
+    userId?: string;
+}): number | null;

package/dist/server/headerRevision.js

@@ -0,0 +1,10 @@
+import { verify } from '../runtime/signing.js';
+/** Authenticate before a revision can trigger I/O. Entry/phase validation stays in the shared decoder. */ export function verifiedHeaderRevision(value, opts) {
+    if (!value || Buffer.byteLength(value) > 1024) return null;
+    const parts = value.split('.');
+    if (parts.length !== 5) return null;
+    const [version, revision, flags, entries, mac] = parts;
+    if (version !== 'v1' || !/^(0|[1-9]\d*)$/.test(revision) || !Number.isSafeInteger(Number(revision))) return null;
+    if (!/^[sbpu]*$/.test(flags) || new Set(flags).size !== flags.length) return null;
+    return verify(`xp:assign:${opts.visitorId ?? ''}|${opts.userId ?? ''}|${flags}|${entries}|${revision}`, mac, opts.secrets) ? Number(revision) : null;
+}

package/dist/server/linkIdentity.d.ts

@@ -0,0 +1,9 @@
+import type { ExperimentsServerRuntime } from '../types/runtime.js';
+export declare function linkIdentity<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(serverRuntime: ExperimentsServerRuntime<TUser>, opts: {
+    headers: Headers;
+    userId: string;
+}): Promise<void>;

package/dist/server/linkIdentity.js

@@ -0,0 +1,34 @@
+import { NextRequest } from 'next/server.js';
+import { insertIdentityOnOwnConnection } from '../db/identities.js';
+import { readUnitCookie } from '../runtime/cookie.js';
+export async function linkIdentity(serverRuntime, opts) {
+    let payload;
+    try {
+        const runtime = serverRuntime.proxyRuntime;
+        // Consent sees cookies and headers only; the URL is a placeholder.
+        let consent = true;
+        try {
+            consent = runtime.cookie.consent?.(new NextRequest('http://consent.invalid/', {
+                headers: opts.headers
+            })) !== false;
+        } catch  {
+            console.error('[payload-experiments] consent failed; treating consent as false');
+            consent = false;
+        }
+        if (!consent) return;
+        const anonymousId = readUnitCookie(opts.headers, runtime);
+        if (!anonymousId) return;
+        payload = await serverRuntime.getPayload();
+        await insertIdentityOnOwnConnection(payload, {
+            anonymousId,
+            userId: opts.userId
+        });
+    } catch (error) {
+        try {
+            payload?.logger.error({
+                err: error,
+                msg: 'Experiments: linkIdentity failed'
+            });
+        } catch  {}
+    }
+}

package/dist/server/metadata.d.ts

@@ -0,0 +1,7 @@
+import type { Metadata } from 'next';
+import type { ExperimentsServerRuntime } from '../types/runtime.js';
+export declare function experimentMetadata<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(serverRuntime: ExperimentsServerRuntime<TUser>, path: string): Promise<Pick<Metadata, 'robots' | 'alternates'>>;

package/dist/server/metadata.js

@@ -0,0 +1,24 @@
+import { findNormalisedPathKey, normalisePath } from '../runtime/normalisePath.js';
+import { serverManifest } from './context.js';
+export async function experimentMetadata(serverRuntime, path) {
+    const manifest = await serverManifest(serverRuntime.proxyRuntime);
+    const live = manifest?.experiments.find((e)=>e.kind === 'page' && e.arms.some((a)=>a.pageTarget !== undefined && normalisePath(a.pageTarget) === normalisePath(path)));
+    if (live) {
+        const controlPath = live.arms.find((a)=>a.kind === 'control')?.pageTarget;
+        return controlPath && normalisePath(path) !== normalisePath(controlPath) ? {
+            robots: {
+                index: false
+            },
+            alternates: {
+                canonical: controlPath
+            }
+        } : {};
+    }
+    const archivedPath = manifest ? findNormalisedPathKey(manifest.archivedPages, path) : undefined;
+    const archived = archivedPath === undefined ? undefined : manifest?.archivedPages[archivedPath];
+    return archived ? {
+        alternates: {
+            canonical: archived.winnerPath
+        }
+    } : {};
+}

package/dist/server/previewDraft.d.ts

@@ -0,0 +1,7 @@
+import type { Payload } from 'payload';
+import type { PreviewToken } from '../runtime/previewToken.js';
+import type { Assignments } from '../types/assignments.js';
+/** Draft previews use the authenticated manager's normal collection access. */
+export declare function previewDraft(payload: Payload, user: {
+    id: string | number;
+} | null, token: PreviewToken, assignments: Assignments, headers: Headers): Promise<void>;

package/dist/server/previewDraft.js

@@ -0,0 +1,51 @@
+/** Draft previews use the authenticated manager's normal collection access. */ export async function previewDraft(payload, user, token, assignments, headers) {
+    if (!user) return;
+    try {
+        const doc = await payload.findByID({
+            collection: 'xp-experiments',
+            id: token.e,
+            depth: 0,
+            overrideAccess: false,
+            user,
+            req: {
+                user: user,
+                headers
+            }
+        });
+        if (doc.status !== 'draft' && doc.status !== 'stopped' || doc.phase !== token.p || typeof doc.slug !== 'string' || !Array.isArray(doc.arms)) return;
+        const arm = doc.arms.find((a)=>a.key === token.a);
+        if (!arm || ![
+            'render',
+            'viewport',
+            'pageview',
+            'manual'
+        ].includes(doc.exposurePolicy)) return;
+        assignments.preview = true;
+        assignments.bySlug[doc.slug] = {
+            slug: doc.slug,
+            experimentId: doc.id,
+            arm: token.a,
+            phase: token.p,
+            exposable: false,
+            policy: doc.exposurePolicy,
+            source: 'preview'
+        };
+        if (typeof doc.flagPoint === 'string') {
+            const content = arm.kind === 'holdout' ? doc.arms.find((a)=>a.kind === 'control') : arm;
+            assignments.flagPoints[doc.flagPoint] = {
+                arm: token.a,
+                params: {
+                    ...content?.params
+                },
+                source: 'experiment',
+                experiment: doc.slug,
+                experimentId: doc.id,
+                phase: token.p,
+                policy: doc.exposurePolicy,
+                exposable: false
+            };
+        }
+    } catch  {
+        console.error('[payload-experiments] draft preview unavailable');
+    }
+}

package/dist/server/recordContentChange.d.ts

@@ -0,0 +1,7 @@
+import type { CollectionAfterChangeHook, CollectionBeforeChangeHook } from 'payload';
+/** Paired beforeChange capture: previousDoc may be an autosaved draft. */
+export declare function capturePublishedContent({ req, collection, originalDoc, operation }: Parameters<CollectionBeforeChangeHook>[0]): Promise<void>;
+type ContentChangeArgs = Pick<Parameters<CollectionAfterChangeHook>[0], 'doc' | 'previousDoc' | 'req' | 'collection'>;
+/** Publish-only host helper. Audit failures are logged, never thrown into saves. */
+export declare function recordContentChange(args: ContentChangeArgs): Promise<void>;
+export {};

package/dist/server/recordContentChange.js

@@ -0,0 +1,150 @@
+import { isDeepStrictEqual } from 'node:util';
+import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment } from '../db/appends.js';
+import { txExecutor } from '../db/executor.js';
+import { puckCollections } from '../options.js';
+import { withTransition } from '../transitions/kernel.js';
+const slots = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC'
+];
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+function bindings(data, puck) {
+    const found = new Map();
+    function add(field, value, content) {
+        const key = field + ':' + value;
+        const binding = found.get(key) ?? {
+            field,
+            value,
+            contents: []
+        };
+        binding.contents.push(content);
+        found.set(key, binding);
+    }
+    function walk(value) {
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (!object(value)) return;
+        if (puck && value.type === 'ExperimentSlot' && object(value.props)) {
+            const props = value.props;
+            const slug = typeof props.experiment === 'string' ? props.experiment : object(props.experiment) ? props.experiment.slug : undefined;
+            if (typeof slug === 'string' && slug) add('slug', slug, {
+                id: props.id,
+                ...Object.fromEntries(slots.map((slot)=>[
+                        slot,
+                        props[slot] ?? []
+                    ]))
+            });
+        } else if (!puck) {
+            // Arm-select stores { experiment, arm }. The containing host row owns the
+            // content (e.g. vars[].experimentArm + vars[].blocks), not the tag alone.
+            for (const tag of Object.values(value)){
+                if (object(tag) && typeof tag.experiment === 'string' && tag.experiment && typeof tag.arm === 'string') {
+                    add('id', tag.experiment, value);
+                }
+            }
+        }
+        Object.values(value).forEach(walk);
+    }
+    walk(data);
+    return found;
+}
+const baselineKey = (collection, id)=>`${collection}:${id}`;
+/** Paired beforeChange capture: previousDoc may be an autosaved draft. */ export async function capturePublishedContent({ req, collection, originalDoc, operation }) {
+    if (!collection.versions || !collection.versions.drafts) return;
+    if (await req.transactionID == null) {
+        req.payload.logger?.debug('[payload-experiments] contentChanges baseline skipped without a transaction');
+        return;
+    }
+    const id = operation === 'create' ? '__create__' : originalDoc.id;
+    const baselines = req.context.xpPublishedContent ??= {};
+    const key = baselineKey(collection.slug, id);
+    delete baselines[key];
+    const audit = await contentChangeSavepoint(txExecutor(req), async ()=>operation === 'create' ? undefined : previousPublishedContent(req, collection.slug, id));
+    if (!audit.ok) throw audit.error;
+    baselines[key] = {
+        collection: collection.slug,
+        id,
+        doc: audit.result
+    };
+}
+/** Publish-only host helper. Audit failures are logged, never thrown into saves. */ export async function recordContentChange(args) {
+    try {
+        await auditContentChange(args);
+    } catch (error) {
+        console.error('[payload-experiments] contentChanges failed; the document was saved without it', error);
+    }
+}
+async function auditContentChange({ doc, previousDoc, req, collection }) {
+    const drafts = Boolean(collection.versions && collection.versions.drafts);
+    if (drafts && doc._status !== 'published') return;
+    if (await req.transactionID == null) {
+        req.payload.logger?.debug('[payload-experiments] contentChanges skipped without a transaction');
+        return;
+    }
+    const baselines = req.context.xpPublishedContent;
+    const key = baselineKey(collection.slug, previousDoc?.id == null ? '__create__' : doc.id);
+    const baseline = baselines?.[key];
+    if (baselines) delete baselines[key];
+    // Missing capture must never turn an unchanged publish into a false marker.
+    if (drafts && !baseline) {
+        req.payload.logger?.debug('[payload-experiments] contentChanges skipped without a captured published baseline');
+        return;
+    }
+    const options = req.payload.config.custom?.xp;
+    const registration = puckCollections(options ?? {}).find((entry)=>entry.slug === collection.slug);
+    const after = bindings(registration ? doc[registration.field] : doc, Boolean(registration));
+    const changes = (previous)=>{
+        const before = bindings(registration && object(previous) ? previous[registration.field] : previous, Boolean(registration));
+        return [
+            ...new Set([
+                ...before.keys(),
+                ...after.keys()
+            ])
+        ].filter((key)=>!isDeepStrictEqual(before.get(key)?.contents, after.get(key)?.contents)).map((key)=>after.get(key) ?? before.get(key));
+    };
+    if (!drafts && !changes(previousDoc).length) return;
+    // Include discovery reads in the savepoint: a SQL read error also aborts Postgres.
+    // An explicit host call must supply its afterChange request's transaction.
+    const executor = txExecutor(req);
+    const audit = await contentChangeSavepoint(executor, async ()=>{
+        const changed = changes(drafts ? baseline?.doc : previousDoc);
+        const experiments = new Map();
+        for (const binding of changed){
+            const experiment = await runningContentExperiment(executor, binding);
+            if (experiment) experiments.set(String(experiment.id), experiment.id);
+        }
+        // Successful audit locks persist until commit; acquire multiple E locks in order.
+        for (const [, experimentId] of [
+            ...experiments
+        ].sort(([a], [b])=>a.localeCompare(b))){
+            await withTransition(req, {
+                experimentId,
+                bump: false,
+                audit: true
+            }, async ({ exec })=>{
+                const experiment = await runningContentExperiment(exec, {
+                    field: 'id',
+                    value: experimentId
+                });
+                if (!experiment) return;
+                await appendContentChange(exec, {
+                    experimentId,
+                    phase: experiment.phase,
+                    entry: {
+                        at: new Date().toISOString(),
+                        doc: {
+                            collection: collection.slug,
+                            id: doc.id
+                        },
+                        by: req.user?.id ?? null
+                    }
+                });
+            });
+        }
+    });
+    if (!audit.ok) throw audit.error;
+}

package/dist/server/recordExposures.d.ts

@@ -0,0 +1,7 @@
+import type { ExperimentsServerRuntime } from '../types/runtime.js';
+import type { Assignments, RenderedExposure } from '../types/assignments.js';
+export declare function recordExposures<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(serverRuntime: ExperimentsServerRuntime<TUser>, rendered: RenderedExposure[], ctx: Assignments): Promise<void>;

package/dist/server/recordExposures.js

@@ -0,0 +1,56 @@
+import { pooledExecutor } from '../db/executor.js';
+import { insertEvents } from '../db/events.js';
+import { exposureDimensions } from '../events/dimensions.js';
+import { requestAttributesOf } from './context.js';
+import { readManifestRow } from '../db/manifest.js';
+export async function recordExposures(serverRuntime, rendered, ctx) {
+    let payload;
+    try {
+        if (ctx.bot || ctx.staff || ctx.preview || ctx.method === 'HEAD') return;
+        const candidates = rendered.flatMap((entry)=>{
+            const assignment = ctx.bySlug[entry.slug];
+            return assignment?.exposable && (assignment.policy === 'render' || assignment.policy === 'manual') && assignment.arm === entry.arm && assignment.phase === entry.phase ? [
+                {
+                    ...assignment
+                }
+            ] : [];
+        });
+        if (!candidates.length) return;
+        const { visitorId, userId } = ctx;
+        const ts = new Date().toISOString();
+        payload = await serverRuntime.getPayload();
+        const options = payload.config?.custom?.xp;
+        const dimensions = exposureDimensions(requestAttributesOf(ctx), options?.events?.dimensions);
+        const exec = pooledExecutor(payload);
+        // Assignments intentionally omit unitType; the immutable manifest field selects the unit.
+        const manifest = await readManifestRow(exec);
+        const rows = candidates.flatMap((assignment)=>{
+            const experiment = manifest?.manifest.experiments.find((exp)=>exp.id === assignment.experimentId && exp.slug === assignment.slug);
+            if (!experiment) return [];
+            const unitId = experiment.unitType === 'visitor' ? visitorId : userId;
+            if (!unitId) return [];
+            return [
+                {
+                    type: 'exposure',
+                    experimentId: assignment.experimentId,
+                    phase: assignment.phase,
+                    arm: assignment.arm,
+                    unitType: experiment.unitType,
+                    unitId,
+                    userId,
+                    ts,
+                    dimensions,
+                    dedupeKey: `exposure:${assignment.experimentId}:${assignment.phase}:${assignment.arm}:${unitId}:${ts.slice(0, 10)}`
+                }
+            ];
+        });
+        await insertEvents(exec, rows, (message)=>payload.logger.error(message));
+    } catch (error) {
+        try {
+            payload?.logger.error({
+                err: error,
+                msg: 'Experiments: recordExposures failed'
+            });
+        } catch  {}
+    }
+}

package/dist/server/request.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest } from 'next/server.js';
+/** Only proxy-signed context can supply a URL, method or consent decision. */
+export declare function serverRequest(headers: Headers, secrets: readonly string[]): {
+    request: NextRequest;
+    hasContext: boolean;
+    consent?: boolean;
+};

package/dist/server/request.js

@@ -0,0 +1,39 @@
+import { NextRequest } from 'next/server.js';
+import { XP_REQUEST_HEADER } from '../constants.js';
+import { verify } from '../runtime/signing.js';
+/** Only proxy-signed context can supply a URL, method or consent decision. */ export function serverRequest(headers, secrets) {
+    const fallback = ()=>({
+            request: new NextRequest('https://xp.invalid/', {
+                headers,
+                method: 'UNKNOWN'
+            }),
+            hasContext: false
+        });
+    const value = headers.get(XP_REQUEST_HEADER);
+    if (!value || Buffer.byteLength(value) > 2048) return fallback();
+    const parts = /^([^|]*)\|(.+)\|(c[01])\|([A-Za-z0-9_-]{43})$/.exec(value);
+    if (!parts) return fallback();
+    const verb = parts[1], path = parts[2], consent = parts[3], mac = parts[4];
+    if (!verify(`xp:request:${verb}|${path}|${consent}`, mac, secrets) || !path.startsWith('/') || /[\\\r\n#]/.test(path)) return fallback();
+    const method = [
+        'GET',
+        'HEAD',
+        'POST',
+        'PUT',
+        'PATCH',
+        'DELETE',
+        'OPTIONS'
+    ].includes(verb) ? verb : 'UNKNOWN';
+    try {
+        return {
+            request: new NextRequest(`https://xp.invalid${path}`, {
+                headers,
+                method
+            }),
+            hasContext: true,
+            consent: consent === 'c1'
+        };
+    } catch  {
+        return fallback();
+    }
+}

package/dist/server/resolveExperimentData.d.ts

@@ -0,0 +1,6 @@
+import type { Data } from '@puckeditor/core';
+import type { Assignments, RenderedExposure } from '../types/assignments.js';
+export declare function resolveExperimentData<TData extends Data>(puckData: TData, assignments: Assignments): {
+    data: TData;
+    rendered: RenderedExposure[];
+};

package/dist/server/resolveExperimentData.js

@@ -0,0 +1,64 @@
+import { manifestOf, suppressExposure } from './context.js';
+export function resolveExperimentData(puckData, assignments) {
+    const rendered = new Map();
+    const slots = [
+        'control',
+        'variantA',
+        'variantB',
+        'variantC'
+    ];
+    const manifest = manifestOf(assignments);
+    function walk(value) {
+        if (Array.isArray(value)) return value.map(walk);
+        if (!value || typeof value !== 'object') return value;
+        const node = value;
+        if (node.type !== 'ExperimentSlot') return Object.fromEntries(Object.entries(node).map(([key, item])=>[
+                key,
+                walk(item)
+            ]));
+        const props = node.props && typeof node.props === 'object' ? node.props : {};
+        // Stored Puck JSON is untrusted, including unbound and unknown experiments.
+        const clean = {
+            ...props
+        };
+        delete clean.xpSlot;
+        delete clean.xpArm;
+        delete clean.xpExpose;
+        const ref = props.experiment;
+        const slug = typeof ref?.slug === 'string' ? ref.slug : undefined;
+        const assignment = slug && Object.hasOwn(assignments.bySlug, slug) ? assignments.bySlug[slug] : undefined;
+        const experiment = manifest?.experiments.find((e)=>e.slug === slug);
+        const arm = experiment?.arms.find((a)=>a.key === assignment?.arm);
+        const archived = slug && Object.hasOwn(assignments.archivedWinners, slug) ? assignments.archivedWinners[slug] : undefined;
+        const selected = assignment ? assignment.arm === 'holdout' ? 'control' : arm?.slot ?? assignment.arm : archived ?? 'control';
+        const slot = slots.includes(selected) ? selected : 'control';
+        clean.xpSlot = slot;
+        if (assignment) {
+            clean.xpArm = assignment.arm;
+            if (assignment.exposable && !suppressExposure(assignments)) {
+                const exposure = {
+                    slug: assignment.slug,
+                    arm: assignment.arm,
+                    phase: assignment.phase
+                };
+                // A missing slot has rendered no experimental content.
+                if (Array.isArray(props[slot])) {
+                    if (assignment.policy === 'render') rendered.set(`${assignment.slug}|${assignment.phase}|${assignment.arm}`, exposure);
+                    if (assignment.policy === 'viewport') clean.xpExpose = exposure;
+                }
+            }
+        }
+        for (const name of slots)clean[name] = name === slot ? walk(props[name] ?? []) : [];
+        for (const [key, item] of Object.entries(clean))if (!slots.includes(key)) clean[key] = walk(item);
+        return Object.fromEntries(Object.entries(node).map(([key, item])=>[
+                key,
+                key === 'props' ? clean : walk(item)
+            ]));
+    }
+    return {
+        data: walk(puckData),
+        rendered: [
+            ...rendered.values()
+        ]
+    };
+}

package/dist/server/runResults.d.ts

@@ -0,0 +1,22 @@
+import type { Payload } from 'payload';
+import type { DocId } from '../types/contracts.js';
+type UnavailableMetric = {
+    experimentId: DocId;
+    phase: number;
+    metricId: DocId;
+    reason: string;
+};
+export declare function runResults(payload: Payload, { budgetMs, experimentId, sweep }?: {
+    budgetMs?: number;
+    experimentId?: DocId;
+    sweep?: boolean;
+}): Promise<{
+    ran: number;
+    skipped: number;
+    swept: number;
+    processedIds: DocId[];
+    budgetExhausted: boolean;
+    unavailableMetrics?: UnavailableMetric[];
+    sweepAttempted?: boolean;
+}>;
+export {};