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

package/dist/endpoints/results.d.ts

@@ -0,0 +1,24 @@
+import type { PayloadRequest } from 'payload';
+import type { EndpointContext, RefusalCode } from '../types/endpoints.js';
+import type { DocId } from '../types/contracts.js';
+import type { Snapshot } from '../types/snapshot.js';
+export declare function resultsError(status: number, code: RefusalCode, message: string): Response;
+export type SnapshotDocument = {
+    id: DocId;
+    experiment: DocId | {
+        id: DocId;
+    };
+    phase: number;
+    computedAt: string;
+    snapshot: Snapshot;
+};
+export declare function readSnapshots(req: PayloadRequest, ids: DocId[], { per, decisionId, seriesPhase }?: {
+    per?: 'phase' | 'experiment';
+    decisionId?: DocId | null;
+    seriesPhase?: number;
+}): Promise<SnapshotDocument[]>;
+export declare function handleResults<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;

package/dist/endpoints/results.js

@@ -0,0 +1,136 @@
+import { resultsMetadata, newestSnapshotIds } from '../db/snapshots.js';
+import { pooledExecutor } from '../db/executor.js';
+const headers = {
+    'Cache-Control': 'no-store'
+};
+export function resultsError(status, code, message) {
+    return Response.json({
+        errors: [
+            {
+                code,
+                message
+            }
+        ]
+    }, {
+        status,
+        headers
+    });
+}
+export async function readSnapshots(req, ids, { per = 'phase', decisionId, seriesPhase } = {}) {
+    const snapshotIds = seriesPhase === undefined ? await newestSnapshotIds(pooledExecutor(req.payload), ids, per) : [];
+    if (decisionId != null && !snapshotIds.some((id)=>String(id) === String(decisionId))) snapshotIds.push(decisionId);
+    if (seriesPhase === undefined && snapshotIds.length === 0) return [];
+    const { docs } = await req.payload.find({
+        collection: 'xp-results-snapshots',
+        req,
+        overrideAccess: false,
+        depth: 0,
+        pagination: false,
+        limit: seriesPhase === undefined ? snapshotIds.length : 0,
+        sort: '-computedAt',
+        where: seriesPhase === undefined ? {
+            id: {
+                in: snapshotIds
+            }
+        } : {
+            and: [
+                {
+                    experiment: {
+                        in: ids
+                    }
+                },
+                {
+                    phase: {
+                        equals: seriesPhase
+                    }
+                }
+            ]
+        }
+    });
+    return docs.sort((a, b)=>Date.parse(b.computedAt) - Date.parse(a.computedAt) || String(b.id).localeCompare(String(a.id), undefined, {
+            numeric: true
+        }));
+}
+export async function handleResults(req, _ctx) {
+    const id = req.routeParams?.id;
+    if (typeof id !== 'string' && typeof id !== 'number') return resultsError(404, 'not-found', 'Experiment not found');
+    const params = new URL(req.url ?? 'http://localhost').searchParams;
+    const selected = params.get('phase');
+    if (selected !== null && (!/^\d+$/.test(selected) || !Number.isSafeInteger(Number(selected)) || Number(selected) < 1)) return resultsError(400, 'invalid-body', 'Choose a valid round');
+    const metadata = await resultsMetadata(pooledExecutor(req.payload), id);
+    if (!metadata) return resultsError(404, 'not-found', 'Experiment not found');
+    const { docs } = await req.payload.find({
+        collection: 'xp-phases',
+        req,
+        overrideAccess: false,
+        depth: 0,
+        pagination: false,
+        limit: 0,
+        where: {
+            experiment: {
+                equals: id
+            }
+        },
+        sort: 'phase'
+    });
+    const records = docs.sort((a, b)=>a.phase - b.phase);
+    const phases = records.map((record)=>({
+            phase: record.phase,
+            phaseKind: record.phaseKind,
+            startedAt: String(record.startedAt),
+            endedAt: record.endedAt == null ? null : String(record.endedAt),
+            arms: record.arms.map(({ key, label, kind })=>({
+                    key,
+                    label,
+                    kind
+                })),
+            metrics: record.metricDefinitions.map(({ metricId, name, kind, role, resolvedCap, historyUnits, capNotice })=>({
+                    metricId,
+                    name,
+                    kind,
+                    role,
+                    ...resolvedCap === undefined ? {} : {
+                        resolvedCap
+                    },
+                    ...historyUnits === undefined ? {} : {
+                        historyUnits
+                    },
+                    ...capNotice ? {
+                        capNotice
+                    } : {}
+                }))
+        }));
+    const snapshots = await readSnapshots(req, [
+        id
+    ], {
+        decisionId: metadata.snapshotId
+    });
+    const decision = metadata.snapshotId == null ? undefined : snapshots.find((snapshot)=>String(snapshot.id) === String(metadata.snapshotId))?.snapshot;
+    const phase = selected === null ? decision?.phase ?? (metadata.status === 'decided' ? records.filter((record)=>record.phaseKind === 'test').at(-1)?.phase : records.at(-1)?.phase) : Number(selected);
+    if (selected !== null && !records.some((record)=>record.phase === phase)) return resultsError(404, 'not-found', 'Round not found');
+    const snapshot = snapshots.find((snapshot)=>snapshot.phase === phase)?.snapshot ?? null;
+    const response = {
+        phases,
+        snapshot,
+        ...decision ? {
+            decisionSnapshot: decision
+        } : {}
+    };
+    if (params.get('series') === '1') {
+        const series = phase === undefined ? [] : await readSnapshots(req, [
+            id
+        ], {
+            seriesPhase: phase
+        });
+        response.series = series.reverse().flatMap(({ snapshot, computedAt })=>snapshot.metrics.flatMap((metric)=>metric.comparisons.map((comparison)=>({
+                        computedAt,
+                        metricId: metric.metricId,
+                        arm: comparison.arm,
+                        lift: comparison.lift,
+                        ci: comparison.ciAdjusted
+                    }))));
+    }
+    return Response.json(response, {
+        headers
+    });
+}

package/dist/endpoints/summary.d.ts

@@ -0,0 +1,7 @@
+import type { PayloadRequest } from 'payload';
+import type { EndpointContext } from '../types/endpoints.js';
+export declare function handleSummary<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;

package/dist/endpoints/summary.js

@@ -0,0 +1,40 @@
+import { readSnapshots, resultsError } from './results.js';
+export async function handleSummary(req, _ctx) {
+    let ids;
+    try {
+        // Split before decoding: an opaque id can itself contain a comma.
+        const raw = new URL(req.url ?? 'http://localhost').search.slice(1).split('&').find((part)=>part.split('=')[0] === 'ids')?.slice(4);
+        if (raw === undefined) return resultsError(400, 'invalid-body', 'Provide experiment ids');
+        ids = raw.split(',').map((id)=>decodeURIComponent(id.replaceAll('+', ' ')));
+    } catch  {
+        return resultsError(400, 'invalid-body', 'Could not parse experiment ids');
+    }
+    if (ids.length > 100) return resultsError(422, 'too-many-ids', 'Request at most 100 experiments');
+    if (ids.some((id)=>!id.trim())) return resultsError(422, 'invalid-ids', 'Experiment ids must be nonempty');
+    const snapshots = await readSnapshots(req, [
+        ...new Set(ids)
+    ], {
+        per: 'experiment'
+    });
+    const response = Object.create(null);
+    for (const id of ids){
+        const snapshot = snapshots.find((row)=>String(typeof row.experiment === 'object' ? row.experiment.id : row.experiment) === id)?.snapshot;
+        response[id] = snapshot ? {
+            exposures: snapshot.exposures.total,
+            days: Math.max(0, (Date.parse(snapshot.window.to) - Date.parse(snapshot.window.from)) / 86_400_000),
+            verdict: {
+                code: snapshot.verdict.code,
+                headline: snapshot.verdict.headline
+            }
+        } : {
+            exposures: 0,
+            days: 0,
+            verdict: null
+        };
+    }
+    return Response.json(response, {
+        headers: {
+            'Cache-Control': 'no-store'
+        }
+    });
+}

package/dist/endpoints/transitions.d.ts

@@ -0,0 +1,42 @@
+import type { PayloadRequest } from 'payload';
+import type { EndpointContext } from '../types/endpoints.js';
+export declare function handleStart<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleAllocate<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleAddMetric<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleStop<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleDecide<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleReleaseHoldout<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleMakeContent<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, ctx: EndpointContext<TUser>): Promise<Response>;
+export declare function handleArchive<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(req: PayloadRequest, _ctx: EndpointContext<TUser>): Promise<Response>;

package/dist/endpoints/transitions.js

@@ -0,0 +1,154 @@
+import { XpRefusal } from '../errors.js';
+import { start } from '../transitions/start.js';
+import { allocate } from '../transitions/allocate.js';
+import { addMetric } from '../transitions/addMetric.js';
+import { stop } from '../transitions/stop.js';
+import { decide } from '../transitions/decide.js';
+import { releaseHoldout } from '../transitions/releaseHoldout.js';
+import { makeContent } from '../transitions/makeContent.js';
+import { archive } from '../transitions/archive.js';
+const invalidBody = ()=>Response.json({
+        errors: [
+            {
+                code: 'invalid-body',
+                message: 'Enter a valid request body.'
+            }
+        ]
+    }, {
+        status: 400
+    });
+async function body(req) {
+    try {
+        if (!req.body && !req.data) return {};
+        // An empty body (Content-Length: 0) means no options, not a malformed request.
+        const text = req.data === undefined ? await req.text() : '';
+        const value = req.data ?? (text.trim() ? JSON.parse(text) : {});
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    } catch  {
+        return null;
+    }
+}
+const only = (value, keys)=>Object.keys(value).every((key)=>keys.includes(key));
+async function respond(req, action) {
+    const id = req.routeParams?.id;
+    if (typeof id !== 'string' && typeof id !== 'number') return Response.json({
+        errors: [
+            {
+                code: 'not-found',
+                message: 'Experiment not found'
+            }
+        ]
+    }, {
+        status: 404
+    });
+    try {
+        return Response.json(await action(id), {
+            headers: {
+                'Cache-Control': 'no-store'
+            }
+        });
+    } catch (cause) {
+        if (cause instanceof XpRefusal) return Response.json({
+            errors: [
+                {
+                    code: cause.code,
+                    message: cause.message,
+                    ...cause.detail === undefined ? {} : {
+                        detail: cause.detail
+                    }
+                }
+            ]
+        }, {
+            status: cause.status === 409 ? 422 : cause.status
+        });
+        throw cause;
+    }
+}
+export async function handleStart(req, ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [])) return invalidBody();
+    return respond(req, (id)=>start(req, {
+            experimentId: id,
+            options: ctx.options
+        }));
+}
+export async function handleAllocate(req, _ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [
+        'allocation'
+    ]) || typeof value.allocation !== 'number' || !Number.isInteger(value.allocation) || value.allocation < 1 || value.allocation > 100) return invalidBody();
+    const allocation = value.allocation;
+    return respond(req, (id)=>allocate(req, {
+            experimentId: id,
+            allocation
+        }));
+}
+export async function handleAddMetric(req, ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [
+        'metric',
+        'role'
+    ]) || !(typeof value.metric === 'string' && value.metric.trim() || typeof value.metric === 'number' && Number.isSafeInteger(value.metric)) || value.role !== 'secondary' && value.role !== 'guardrail') return invalidBody();
+    const metric = value.metric, role = value.role;
+    return respond(req, (id)=>addMetric(req, {
+            experimentId: id,
+            metric,
+            role,
+            options: ctx.options
+        }));
+}
+export async function handleStop(req, _ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [])) return invalidBody();
+    return respond(req, (id)=>stop(req, {
+            experimentId: id
+        }));
+}
+export async function handleDecide(req, _ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [
+        'winnerArm',
+        'note',
+        'confirmation'
+    ]) || typeof value.winnerArm !== 'string' || value.note !== undefined && typeof value.note !== 'string' || value.confirmation !== undefined && typeof value.confirmation !== 'string') return invalidBody();
+    const { winnerArm, note, confirmation } = value;
+    return respond(req, (id)=>decide(req, {
+            experimentId: id,
+            winnerArm,
+            note,
+            confirmation
+        }));
+}
+export async function handleReleaseHoldout(req, _ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [])) return invalidBody();
+    return respond(req, (id)=>releaseHoldout(req, {
+            experimentId: id
+        }));
+}
+export async function handleMakeContent(req, ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [])) return invalidBody();
+    return respond(req, (id)=>makeContent(req, {
+            experimentId: id,
+            options: ctx.options
+        }));
+}
+export async function handleArchive(req, _ctx) {
+    const value = await body(req);
+    if (!value || !only(value, [
+        'mode',
+        'confirmation'
+    ]) || ![
+        'stopped',
+        'after-content',
+        'discard',
+        'hard-coded'
+    ].includes(value.mode) || value.confirmation !== undefined && typeof value.confirmation !== 'string') return invalidBody();
+    const { mode, confirmation } = value;
+    return respond(req, (id)=>archive(req, {
+            experimentId: id,
+            mode,
+            confirmation
+        }));
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { RefusalCode } from './types/endpoints.js';
+import type { Status } from './types/contracts.js';
+export declare class XpNotImplemented extends Error {
+    readonly lane: string;
+    name: string;
+    constructor(lane: string);
+}
+export declare class XpLockedFieldError extends Error {
+    readonly field: string;
+    readonly experimentStatus: Status;
+    name: string;
+    readonly status = 400;
+    readonly isPublic = true;
+    constructor(field: string, experimentStatus: Status);
+}
+export declare class XpNoTransactionError extends Error {
+    name: string;
+    constructor();
+}
+export declare class XpRefusal extends Error {
+    readonly code: RefusalCode;
+    readonly detail: unknown | undefined;
+    readonly status: 409 | 422 | 500 | 404;
+    name: string;
+    readonly isPublic = true;
+    constructor(code: RefusalCode, message: string, detail: unknown | undefined, status: 409 | 422 | 500 | 404);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class XpNotImplemented extends Error {
+    lane;
+    name = 'XpNotImplemented';
+    constructor(lane){
+        super(lane), this.lane = lane;
+    }
+}
+export class XpLockedFieldError extends Error {
+    field;
+    experimentStatus;
+    name = 'XpLockedFieldError';
+    status = 400;
+    isPublic = true;
+    constructor(field, experimentStatus){
+        super(`${field} is locked in ${experimentStatus}`), this.field = field, this.experimentStatus = experimentStatus;
+    }
+}
+export class XpNoTransactionError extends Error {
+    name = 'XpNoTransactionError';
+    constructor(){
+        super('An active transaction is required');
+    }
+}
+export class XpRefusal extends Error {
+    code;
+    detail;
+    status;
+    name = 'XpRefusal';
+    isPublic = true;
+    constructor(code, message, detail, status){
+        super(message), this.code = code, this.detail = detail, this.status = status;
+    }
+}

package/dist/events/body.d.ts

@@ -0,0 +1,7 @@
+export declare class EventsBodyError extends Error {
+    readonly status: 413 | 422;
+    readonly code: 'body-too-large' | 'invalid-body';
+    constructor(status: 413 | 422, code: 'body-too-large' | 'invalid-body', message: string);
+}
+/** Bound retained bytes while reading the original Fetch stream, before parsing. */
+export declare function readEvents(body: ReadableStream<Uint8Array> | null | undefined, maxBytes: number): Promise<unknown[]>;

package/dist/events/body.js

@@ -0,0 +1,43 @@
+import { MAX_EVENTS_PER_BODY } from '../constants.js';
+export class EventsBodyError extends Error {
+    status;
+    code;
+    constructor(status, code, message){
+        super(message), this.status = status, this.code = code;
+    }
+}
+/** Bound retained bytes while reading the original Fetch stream, before parsing. */ export async function readEvents(body, maxBytes) {
+    if (!body) throw new EventsBodyError(422, 'invalid-body', 'Expected an events array');
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while(true){
+            const { done, value } = await reader.read();
+            if (done) break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                // Cancellation must not wait for an uncooperative sender to finish.
+                void reader.cancel().catch(()=>{});
+                throw new EventsBodyError(413, 'body-too-large', 'Events body is too large');
+            }
+            chunks.push(value);
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks){
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !('events' in parsed) || !Array.isArray(parsed.events) || parsed.events.length > MAX_EVENTS_PER_BODY) {
+            throw new Error('Expected at most 20 events');
+        }
+        return parsed.events;
+    } catch (error) {
+        if (error instanceof EventsBodyError) throw error;
+        throw new EventsBodyError(422, 'invalid-body', 'Invalid events body');
+    } finally{
+        reader.releaseLock();
+    }
+}

package/dist/events/dimensions.d.ts

@@ -0,0 +1,4 @@
+/** Startup validation; hosts may supply options from JavaScript or config files. */
+export declare function validateDimensions(names: unknown): void;
+/** Pick only server-computed request attributes; never pass browser event data. */
+export declare function exposureDimensions(attributes: Readonly<Record<string, unknown>>, names?: readonly string[]): Record<string, string | number | boolean> | null;

package/dist/events/dimensions.js

@@ -0,0 +1,51 @@
+const identifyingKeys = new Set([
+    'userid',
+    'visitorid',
+    'unitid',
+    'id',
+    'email',
+    'emailaddress',
+    'sessionid',
+    'session',
+    'ip',
+    'ipaddress',
+    'phone',
+    'name'
+]);
+/** Startup validation; hosts may supply options from JavaScript or config files. */ export function validateDimensions(names) {
+    if (names === undefined) return;
+    if (!Array.isArray(names) || names.length > 8) {
+        throw new Error('Experiments events.dimensions must be an array of at most 8 unique attribute names');
+    }
+    const seen = new Set();
+    for (const name of names){
+        if (typeof name === 'string' && identifyingKeys.has(name.toLowerCase().replace(/[_-]/g, ''))) {
+            throw new Error(`Experiments events.dimensions forbids identifying key: ${name}`);
+        }
+        if (typeof name !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/.test(name)) {
+            throw new Error('Experiments events.dimensions names must match ^[a-zA-Z][a-zA-Z0-9_]{0,39}$');
+        }
+        if (seen.has(name)) throw new Error(`Experiments events.dimensions names must be unique: ${name}`);
+        seen.add(name);
+    }
+}
+/** Pick only server-computed request attributes; never pass browser event data. */ export function exposureDimensions(attributes, names = []) {
+    const entries = [];
+    for (const name of names){
+        if (!Object.hasOwn(attributes, name)) continue;
+        const value = attributes[name];
+        if (typeof value === 'string') {
+            const truncated = Array.from(value).slice(0, 64).join('');
+            // JSONB rejects NUL and unpaired UTF-16 surrogates. Optional telemetry
+            // must never make an otherwise valid exposure fail to persist.
+            if (!/\u0000|[\uD800-\uDFFF]/u.test(truncated)) entries.push([
+                name,
+                truncated
+            ]);
+        } else if (typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) entries.push([
+            name,
+            value
+        ]);
+    }
+    return entries.length ? Object.fromEntries(entries) : null;
+}

package/dist/events/preview.d.ts

@@ -0,0 +1,2 @@
+/** These signals only suppress telemetry; they never authorize a preview or an assignment. */
+export declare function isPreview(request: Request): boolean;

package/dist/events/preview.js

@@ -0,0 +1,9 @@
+import { XP_PREVIEW_PARAM } from '../constants.js';
+/** These signals only suppress telemetry; they never authorize a preview or an assignment. */ export function isPreview(request) {
+    if (new URL(request.url).searchParams.has(XP_PREVIEW_PARAM)) return true;
+    const referrer = request.headers.get('referer');
+    try {
+        if (referrer && new URL(referrer).searchParams.has(XP_PREVIEW_PARAM)) return true;
+    } catch  {}
+    return (request.headers.get('cookie') ?? '').split(';').some((part)=>part.trim().startsWith('__prerender_bypass='));
+}

package/dist/events/request.d.ts

@@ -0,0 +1,3 @@
+import { NextRequest } from 'next/server.js';
+/** Browser beacons carry their page URL in Referer. It supplies targeting context only. */
+export declare function sourceRequest(request: NextRequest): NextRequest | null;

package/dist/events/request.js

@@ -0,0 +1,14 @@
+import { NextRequest } from 'next/server.js';
+/** Browser beacons carry their page URL in Referer. It supplies targeting context only. */ export function sourceRequest(request) {
+    const referrer = request.headers.get('referer');
+    if (!referrer) return null;
+    try {
+        const url = new URL(referrer);
+        if (url.origin !== request.nextUrl.origin) return null;
+        return new NextRequest(url, {
+            headers: request.headers
+        });
+    } catch  {
+        return null;
+    }
+}

package/dist/events/rows.d.ts

@@ -0,0 +1,7 @@
+import type { EventRow } from '../db/events.js';
+import type { AssignmentResult } from '../runtime/assign.js';
+import type { ResolvedOptions } from '../types/contracts.js';
+import type { Manifest } from '../types/manifest.js';
+export declare function eventRows<TUser extends {
+    id: string | number;
+}>(events: unknown[], manifest: Manifest, assignments: AssignmentResult, options: ResolvedOptions<TUser>, visitorId: string, userId: string | undefined, ts: string, requestAttributes?: Readonly<Record<string, unknown>>): EventRow[];