@delmaredigital/payload-experiments 0.3.0-rc.4 → 0.4.0-rc.2

package/dist/blocks/formState.js

@@ -0,0 +1,146 @@
+import { BLOCK_SLOTS, EXPERIMENT_BLOCK_SLUG, isObject, slotBlocks } from './model.js';
+/** Mirror Payload 3.90.2's collections/operations/utilities/copyDataWithFreshRowIDs.js:
+ * walk configured row/subfield containers only. Mint ids for array/blocks rows, leaving
+ * opaque values (including json, richText, relationships and uploads) unchanged.
+ * Global block definitions resolve blockReferences; inline slot blocks retain host configs.
+ */ export function freshBlockIds(value, field, config = {}, mint = ()=>globalThis.crypto.randomUUID()) {
+    function copyObject(data, fields, parentIsLocalized = false) {
+        const result = {
+            ...data
+        };
+        for (const child of fields){
+            if (child.type === 'row' || child.type === 'collapsible' || child.type === 'group' && !('name' in child && child.name)) {
+                Object.assign(result, copyObject(result, child.fields, parentIsLocalized));
+            } else if (child.type === 'tabs') {
+                for (const tab of child.tabs){
+                    if ('name' in tab && tab.name) {
+                        if (Object.hasOwn(result, tab.name)) result[tab.name] = subfields(result[tab.name], tab.fields, tab.localized, parentIsLocalized);
+                    } else Object.assign(result, copyObject(result, tab.fields, parentIsLocalized));
+                }
+            } else if (child.type === 'group' && 'name' in child && child.name) {
+                if (Object.hasOwn(result, child.name)) result[child.name] = subfields(result[child.name], child.fields, child.localized, parentIsLocalized);
+            } else if (child.type === 'array' || child.type === 'blocks') {
+                if (Object.hasOwn(result, child.name)) result[child.name] = copyRows(result[child.name], child, parentIsLocalized || Boolean(child.localized));
+            }
+        }
+        return result;
+    }
+    function subfields(data, fields, localized, parentIsLocalized) {
+        if (!isObject(data)) return data;
+        const locales = config.localization ? config.localization.localeCodes : [];
+        if (localized && !parentIsLocalized && Object.keys(data).length > 0 && Object.keys(data).every((key)=>locales.includes(key))) return Object.fromEntries(Object.entries(data).map(([locale, value])=>[
+                locale,
+                isObject(value) ? copyObject(value, fields, true) : value
+            ]));
+        return copyObject(data, fields, parentIsLocalized || Boolean(localized));
+    }
+    function copyRows(data, rowsField, parentIsLocalized = false) {
+        if (Array.isArray(data)) return data.map((row)=>{
+            if (!isObject(row)) return row;
+            const fields = rowsField.type === 'array' ? rowsField.fields : (config.blocks?.find((block)=>block.slug === row.blockType) ?? [
+                ...rowsField.blocks,
+                ...(rowsField.blockReferences ?? []).filter((block)=>typeof block !== 'string')
+            ].find((block)=>block.slug === row.blockType))?.fields ?? [];
+            return {
+                ...copyObject(row, fields, parentIsLocalized),
+                id: mint()
+            };
+        });
+        if (isObject(data)) return Object.fromEntries(Object.entries(data).map(([locale, rows])=>[
+                locale,
+                Array.isArray(rows) ? copyRows(rows, rowsField, true) : rows
+            ]));
+        return data;
+    }
+    return copyRows(value, field);
+}
+export function wrapExperimentBlock(block, experiment, field, config = {}, blockSlug = EXPERIMENT_BLOCK_SLUG) {
+    if (block.blockType === blockSlug) throw new Error('Experiment blocks cannot be nested.');
+    return {
+        id: globalThis.crypto.randomUUID(),
+        blockType: blockSlug,
+        experiment,
+        slots: [
+            {
+                id: globalThis.crypto.randomUUID(),
+                slot: 'control',
+                blocks: [
+                    block
+                ]
+            },
+            {
+                id: globalThis.crypto.randomUUID(),
+                slot: 'variantA',
+                blocks: freshBlockIds([
+                    block
+                ], field, config)
+            }
+        ]
+    };
+}
+function copySlotBlocks(block, slot, field, config) {
+    // Traverse the wrapper too: slot content may use blocks defined only inside
+    // createExperimentBlock, rather than in the host's outer blocks field.
+    return slotBlocks(freshBlockIds([
+        block
+    ], field, config)[0], slot);
+}
+export function syncExperimentSlots(block, arms, field, config = {}) {
+    const wanted = arms.filter((a)=>a.kind !== 'holdout' && a.key !== 'holdout').map((a)=>a.slot ?? a.key).filter((slot)=>BLOCK_SLOTS.includes(slot));
+    const slots = [
+        ...new Set(wanted)
+    ].map((slot)=>block.slots.find((row)=>row.slot === slot) ?? {
+            id: globalThis.crypto.randomUUID(),
+            slot,
+            blocks: copySlotBlocks(block, 'control', field, config)
+        });
+    return {
+        ...block,
+        slots
+    };
+}
+export function copyOriginalIntoVersion(block, slot, field, config = {}) {
+    return {
+        ...block,
+        slots: block.slots.map((row)=>row.slot === slot && slot !== 'control' ? {
+                ...row,
+                blocks: copySlotBlocks(block, 'control', field, config)
+            } : row)
+    };
+}
+export function unwrapExperimentBlock(block, field, slot = 'control', config = {}) {
+    return copySlotBlocks(block, slot, field, config);
+}
+/** Config coordinates include unnamed layout containers. No field component is injected here. */ export function findRegisteredBlocksField(fields, name) {
+    function visit(fields, path) {
+        for(let i = 0; i < fields.length; i++){
+            const field = fields[i], here = [
+                ...path,
+                i
+            ];
+            if ('name' in field && field.name === name && field.type === 'blocks') return {
+                field,
+                path: here
+            };
+            if (field.type === 'tabs') for(let t = 0; t < field.tabs.length; t++){
+                const tab = field.tabs[t];
+                if ('name' in tab && tab.name) continue;
+                const found = visit(field.tabs[t].fields, [
+                    ...here,
+                    'tabs',
+                    t,
+                    'fields'
+                ]);
+                if (found) return found;
+            }
+            if (field.type === 'row' || field.type === 'collapsible') {
+                const found = visit(field.fields, [
+                    ...here,
+                    'fields'
+                ]);
+                if (found) return found;
+            }
+        }
+    }
+    return visit(fields, []);
+}

package/dist/blocks/model.d.ts

@@ -0,0 +1,41 @@
+import type { RenderedExposure } from '../types/assignments.js';
+export declare const EXPERIMENT_BLOCK_SLUG = "xpExperiment";
+export declare const BLOCK_SLOTS: readonly ["control", "variantA", "variantB", "variantC"];
+export interface HostBlock {
+    id?: string;
+    blockType: string;
+    blockName?: string;
+    [field: string]: unknown;
+}
+export interface ExperimentBlock extends HostBlock {
+    experiment: string;
+    slots: Array<{
+        id?: string;
+        slot: string;
+        blocks: HostBlock[];
+    }>;
+}
+export interface ExperimentBlockGroup {
+    slug: string;
+    expose?: RenderedExposure;
+}
+export type ResolvedHostBlock = HostBlock & {
+    xpGroup?: ExperimentBlockGroup;
+};
+export interface ResolvedExperimentBlocks {
+    blocks: ResolvedHostBlock[];
+    rendered: RenderedExposure[];
+    groups: Array<ExperimentBlockGroup & {
+        start: number;
+        end: number;
+    }>;
+}
+export declare const isObject: (v: unknown) => v is Record<string, unknown>;
+export declare const hostBlocks: (v: unknown) => HostBlock[];
+export declare function slotBlocks(block: HostBlock, slot: string): HostBlock[];
+/** Experiments-off rendering preserves stored row ids; only top-level wrappers are read. */
+export declare function controlOnlyBlocks(blocks: unknown, blockSlug?: string): HostBlock[];
+export declare function segmentExperimentBlocks(blocks: readonly ResolvedHostBlock[]): Array<{
+    group?: ExperimentBlockGroup;
+    blocks: HostBlock[];
+}>;

package/dist/blocks/model.js

@@ -0,0 +1,34 @@
+export const EXPERIMENT_BLOCK_SLUG = 'xpExperiment';
+export const BLOCK_SLOTS = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC'
+];
+export const isObject = (v)=>!!v && typeof v === 'object' && !Array.isArray(v);
+export const hostBlocks = (v)=>Array.isArray(v) ? v.filter((b)=>isObject(b) && typeof b.blockType === 'string') : [];
+export function slotBlocks(block, slot) {
+    const row = Array.isArray(block.slots) ? block.slots.find((row)=>isObject(row) && row.slot === slot) : undefined;
+    return isObject(row) ? hostBlocks(row.blocks) : [];
+}
+/** Experiments-off rendering preserves stored row ids; only top-level wrappers are read. */ export function controlOnlyBlocks(blocks, blockSlug = EXPERIMENT_BLOCK_SLUG) {
+    return hostBlocks(blocks).flatMap((block)=>block.blockType === blockSlug ? slotBlocks(block, 'control') : [
+            block
+        ]);
+}
+export function segmentExperimentBlocks(blocks) {
+    const runs = [];
+    for (const block of blocks){
+        const group = block.xpGroup, last = runs.at(-1);
+        if (last && last.group === group) last.blocks.push(block);
+        else runs.push({
+            ...group ? {
+                group
+            } : {},
+            blocks: [
+                block
+            ]
+        });
+    }
+    return runs;
+}

package/dist/client/ExperimentGroup.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import type { RenderedExposure } from '../types/assignments.js';
+export declare function ExperimentGroup({ expose, children }: {
+    expose?: RenderedExposure;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/client/ExperimentGroup.js

@@ -0,0 +1,9 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ViewportExposure } from './ViewportExposure.js';
+export function ExperimentGroup({ expose, children }) {
+    return /*#__PURE__*/ _jsx(ViewportExposure, {
+        expose: expose,
+        children: children
+    });
+}

package/dist/client/ExperimentsProvider.js

@@ -1,9 +1,12 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useLayoutEffect, useRef } from 'react';
+import { createContext, useContext, useLayoutEffect, useRef } from 'react';
 import { registerApiRoute, unregisterApiRoute } from './beacon.js';
+import { registerClickGoals, unregisterClickGoals } from './clickGoals.js';
 import { ExperimentsContext } from './context.js';
+const DepthContext = /*#__PURE__*/ createContext(0);
 export function ExperimentsProvider(props) {
+    const depth = useContext(DepthContext) + 1;
     const token = useRef(Symbol()).current;
     // Register committed providers before descendants can send from passive effects.
     useLayoutEffect(()=>{
@@ -15,8 +18,21 @@ export function ExperimentsProvider(props) {
     useLayoutEffect(()=>()=>unregisterApiRoute(token), [
         token
     ]);
-    return /*#__PURE__*/ _jsx(ExperimentsContext.Provider, {
-        value: props.value,
-        children: props.children
+    useLayoutEffect(()=>{
+        registerClickGoals(token, depth, props.value);
+    }, [
+        token,
+        depth,
+        props.value
+    ]);
+    useLayoutEffect(()=>()=>unregisterClickGoals(token), [
+        token
+    ]);
+    return /*#__PURE__*/ _jsx(DepthContext.Provider, {
+        value: depth,
+        children: /*#__PURE__*/ _jsx(ExperimentsContext.Provider, {
+            value: props.value,
+            children: props.children
+        })
     });
 }

package/dist/client/clickGoals.d.ts

@@ -0,0 +1,4 @@
+import type { ClientAssignments } from '../types/assignments.js';
+/** One delegated listener; depth, rather than React's child-first commit order, decides ownership. */
+export declare function registerClickGoals(token: symbol, depth: number, value: ClientAssignments): void;
+export declare function unregisterClickGoals(token: symbol): void;

package/dist/client/clickGoals.js

@@ -0,0 +1,43 @@
+'use client';
+import { CLICK_KEY } from '../goals/key.js';
+import { sendEvent } from './beacon.js';
+import { idempotencyKey } from './idempotency.js';
+const providers = new Map();
+let listening;
+function onClick(event) {
+    let owner;
+    for (const provider of providers.values()){
+        if (provider.value.clickGoalsArmed && (!owner || provider.depth >= owner.depth)) owner = provider;
+    }
+    if (!owner) return;
+    const target = event.target;
+    const element = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+    const key = element?.closest('[data-xp-goal]')?.getAttribute('data-xp-goal');
+    if (!key || !CLICK_KEY.test(key)) return;
+    sendEvent(owner.value.apiRoute, {
+        type: 'conversion',
+        eventName: `click:${key}`,
+        idempotencyKey: `${owner.pageviewId}:${key}`
+    });
+}
+/** One delegated listener; depth, rather than React's child-first commit order, decides ownership. */ export function registerClickGoals(token, depth, value) {
+    const previous = providers.get(token);
+    const pageviewId = previous?.value === value ? previous.pageviewId : idempotencyKey();
+    providers.delete(token);
+    providers.set(token, {
+        depth,
+        value,
+        pageviewId
+    });
+    if (!listening && typeof document !== 'undefined') {
+        listening = document;
+        listening.addEventListener('click', onClick);
+    }
+}
+export function unregisterClickGoals(token) {
+    providers.delete(token);
+    if (!providers.size && listening) {
+        listening.removeEventListener('click', onClick);
+        listening = undefined;
+    }
+}

package/dist/collections/experiments/config.js

@@ -1,3 +1,4 @@
+import { SURFACE_COPY } from '../../admin/copy/surface.js';
 import * as paths from '../../admin/paths.js';
 import { managedAccess } from '../access.js';
 import { serializeAttributeKeys, serializeFlagPoints } from '../serialize.js';
@@ -5,8 +6,9 @@ import { TARGETING_OPS, isOpValid } from '../../targeting/ops.js';
 import { readListValue } from '../../targeting/values.js';
 import { createDefaults } from './createDefaults.js';
 import { flagControlParams } from './flagControlParams.js';
+import { pickExperimentSlug } from './pickSlug.js';
 import { lockHook } from './lockHook.js';
-import { deleteGuard, deleteGuardAfter } from './deleteGuard.js';
+import { deleteGuard, deleteGuardAfter, deleteGuardBeforeOperation } from './deleteGuard.js';
 import { checkArms } from './armInvariants.js';
 import { XpNotImplemented, XpRefusal } from '../../errors.js';
 const targetingValue = (rule)=>rule.op === 'in' || rule.op === 'nin' ? readListValue(rule.value) : rule.value;
@@ -36,6 +38,10 @@ export function experimentsCollection(options) {
             drafts: false,
             maxPerDoc: 50
         },
+        labels: {
+            singular: SURFACE_COPY.test,
+            plural: SURFACE_COPY.navAllTests
+        },
         access: {
             ...managedAccess(options),
             delete: async ({ req })=>await options.access.manage({
@@ -50,8 +56,7 @@ export function experimentsCollection(options) {
                 } : false
         },
         admin: {
-            // group:false hides navigation while keeping custom view routes reachable (hidden causes 404s).
-            group: false,
+            group: SURFACE_COPY.title,
             useAsTitle: 'name',
             defaultColumns: [
                 'name',
@@ -62,7 +67,7 @@ export function experimentsCollection(options) {
             components: {
                 views: {
                     list: {
-                        Component: paths.XP_TESTS_LIST_REDIRECT
+                        Component: paths.XP_TESTS_COLLECTION_LIST
                     },
                     edit: {
                         default: {
@@ -81,12 +86,16 @@ export function experimentsCollection(options) {
             }
         },
         hooks: {
+            beforeOperation: [
+                deleteGuardBeforeOperation
+            ],
             beforeValidate: [
                 createDefaults
             ],
             beforeChange: [
                 flagControlParams,
-                lockHook
+                lockHook,
+                pickExperimentSlug
             ],
             beforeDelete: [
                 deleteGuard
@@ -96,8 +105,8 @@ export function experimentsCollection(options) {
             ],
             afterError: [
                 ({ error })=>{
-                    // Payload preserves public Error status/message, but omits custom codes.
-                    if (error instanceof XpRefusal && error.code === 'stale-edit') {
+                    // Payload preserves public Error status/message, but omits custom codes; the admin maps refusals by code.
+                    if (error instanceof XpRefusal) {
                         return {
                             status: error.status,
                             response: {
@@ -166,6 +175,11 @@ export function experimentsCollection(options) {
                                     read: async (args)=>args.doc?.kind !== 'code' || adminOnly(args)
                                 }
                             },
+                            {
+                                name: 'pageCollection',
+                                type: 'text',
+                                validate: (value, { previousValue })=>value === previousValue || value == null || value === '' || options.pages?.collections.some((entry)=>entry.slug === value) || 'Choose a registered page collection.'
+                            },
                             {
                                 name: 'flagPoint',
                                 type: 'text',

package/dist/collections/experiments/deleteGuard.d.ts

@@ -1,3 +1,4 @@
-import type { CollectionAfterDeleteHook, CollectionBeforeDeleteHook } from 'payload';
+import type { CollectionBeforeOperationHook, CollectionAfterDeleteHook, CollectionBeforeDeleteHook } from 'payload';
 export declare const deleteGuard: CollectionBeforeDeleteHook;
 export declare const deleteGuardAfter: CollectionAfterDeleteHook;
+export declare const deleteGuardBeforeOperation: CollectionBeforeOperationHook;

package/dist/collections/experiments/deleteGuard.js

@@ -1,4 +1,5 @@
-import { deleteExperiment, deleteExperimentAfter } from '../../transitions/deleteExperiment.js';
+import { deleteExperiment, deleteExperimentAfter, prepareBulkDelete } from '../../transitions/deleteExperiment.js';
+import { xpOptionsFromReq } from '../../options/fromReq.js';
 export const deleteGuard = async ({ req, id })=>{
     await deleteExperiment(req, id);
 };
@@ -6,3 +7,13 @@ export const deleteGuardAfter = async ({ req, id, doc })=>{
     await deleteExperimentAfter(req, id);
     return doc;
 };
+export const deleteGuardBeforeOperation = async ({ operation, args, req })=>{
+    if (operation === 'delete' && 'where' in args && args.where) {
+        // Payload runs beforeOperation before access; only a manager, or an explicit overrideAccess call, may make the plugin discover and lock the delete scope.
+        if (args.overrideAccess !== true && await xpOptionsFromReq(req).access.manage({
+            req
+        }) !== true) return args;
+        await prepareBulkDelete(req, args.where);
+    }
+    return args;
+};

package/dist/collections/experiments/editability.js

@@ -8,7 +8,8 @@ export const EDITABLE_BY_STATUS = {
         'flagPoint',
         'metrics',
         'analysis',
-        'exposurePolicy'
+        'exposurePolicy',
+        'pageCollection'
     ],
     stopped: [
         'name',
@@ -18,7 +19,8 @@ export const EDITABLE_BY_STATUS = {
         'allocation',
         'metrics',
         'analysis',
-        'exposurePolicy'
+        'exposurePolicy',
+        'pageCollection'
     ],
     running: [
         'name',

package/dist/collections/experiments/pickSlug.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionBeforeChangeHook } from 'payload';
+export declare const pickExperimentSlug: CollectionBeforeChangeHook;

package/dist/collections/experiments/pickSlug.js

@@ -0,0 +1,8 @@
+import { pickSlug } from '../../db/slugs.js';
+import { pooledExecutor, txExecutor } from '../../db/executor.js';
+export const pickExperimentSlug = async ({ req, data, operation })=>{
+    if (operation !== 'create' || typeof data.slug !== 'string' || !data.slug) return data;
+    const transactional = await req.transactionID != null;
+    data.slug = await pickSlug(transactional ? txExecutor(req) : pooledExecutor(req.payload), data.slug, transactional);
+    return data;
+};

package/dist/collections/labels.d.ts

@@ -0,0 +1,3 @@
+import type { PayloadRequest } from 'payload';
+/** Payload labels may be translated strings or functions. Keep server entries dependency-safe. */
+export declare function collectionLabel(label: unknown, slug: string, req: PayloadRequest): string;

package/dist/collections/labels.js

@@ -0,0 +1,20 @@
+/** Payload labels may be translated strings or functions. Keep server entries dependency-safe. */ export function collectionLabel(label, slug, req) {
+    try {
+        if (typeof label === 'function') {
+            const value = label({
+                i18n: req.i18n,
+                t: req.i18n.t
+            });
+            return typeof value === 'string' ? value : slug;
+        }
+        if (typeof label === 'string') return label;
+        const translations = label && typeof label === 'object' ? label : {};
+        return [
+            translations[req.i18n?.language ?? 'en'],
+            translations.en,
+            ...Object.values(translations)
+        ].find((value)=>typeof value === 'string') ?? slug;
+    } catch  {
+        return slug;
+    }
+}

package/dist/collections/metrics.js

@@ -1,4 +1,6 @@
-import { XP_METRIC_SOURCE_SELECT } from '../admin/paths.js';
+import { SURFACE_COPY } from '../admin/copy/surface.js';
+import { CLICK_KEY, isClickSource, validClickSource } from '../goals/key.js';
+import { XP_METRIC_SOURCE_SELECT, XP_GOALS_COLLECTION_LIST, XP_GOAL_EDIT_REDIRECT } from '../admin/paths.js';
 import { managedAccess } from './access.js';
 import { serializeMetricSources } from './serialize.js';
 import { validateCappingType, validateCappingValue } from './metricValidation.js';
@@ -10,14 +12,25 @@ export function metricsCollection(options) {
         graphQL: false,
         disableDuplicate: true,
         versions: false,
-        // group:false hides navigation while keeping collection routes reachable (hidden causes 404s).
         labels: {
             singular: 'Goal',
             plural: 'Goals'
         },
         admin: {
-            group: false,
-            useAsTitle: 'name'
+            group: SURFACE_COPY.title,
+            useAsTitle: 'name',
+            components: {
+                views: {
+                    list: {
+                        Component: XP_GOALS_COLLECTION_LIST
+                    },
+                    edit: {
+                        default: {
+                            Component: XP_GOAL_EDIT_REDIRECT
+                        }
+                    }
+                }
+            }
         },
         access: managedAccess(options),
         hooks: {
@@ -30,6 +43,14 @@ export function metricsCollection(options) {
             beforeValidate: [
                 ({ data, originalDoc })=>{
                     if (!data) return data;
+                    if (isClickSource(data.source ?? originalDoc?.source)) {
+                        data.source = `click:${data.slug ?? originalDoc?.slug ?? ''}`;
+                        data.direction = 'increase';
+                        data.capping = {
+                            type: null,
+                            value: null
+                        };
+                    }
                     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 }.
@@ -58,6 +79,7 @@ export function metricsCollection(options) {
                 type: 'text',
                 required: true,
                 unique: true,
+                validate: (value, { data })=>!isClickSource(data?.source) || typeof value === 'string' && CLICK_KEY.test(value) || 'Use 1–64 lowercase letters, numbers, underscores or hyphens, starting with a letter or number.',
                 admin: {
                     description: 'Use a unique short name for code that refers to this goal.'
                 }
@@ -67,7 +89,7 @@ export function metricsCollection(options) {
                 label: 'Measured by',
                 type: 'text',
                 required: true,
-                validate: (value)=>sources.some((source)=>source.id === value) || 'Choose what this goal is measured by.',
+                validate: (value)=>(isClickSource(value) ? validClickSource(value) : sources.some((source)=>source.id === value)) || 'Choose what this goal is measured by.',
                 admin: {
                     description: 'Choose the outcome this goal measures.',
                     components: {
@@ -135,7 +157,7 @@ export function metricsCollection(options) {
                         },
                         validate: (value, { data, siblingData })=>{
                             const source = sources.find((source)=>source.id === data?.source);
-                            return validateCappingType(value, siblingData?.value, source?.kind);
+                            return validateCappingType(value, siblingData?.value, isClickSource(data?.source) ? 'binomial' : source?.kind);
                         }
                     },
                     {

package/dist/collections/phases.js

@@ -50,6 +50,7 @@ export function phasesCollection(options) {
                 'targeting',
                 'metricDefinitions',
                 'analysis',
+                'placementDocs',
                 'contentChanges'
             ].map((name)=>({
                     name,

package/dist/collections/serialize.js

@@ -12,6 +12,13 @@ export function serializeFlagPoints(options) {
 }
 export function serializeMetricSources(options) {
     return [
+        {
+            id: 'click:',
+            label: 'A click on the page',
+            kind: 'binomial',
+            keyedBy: 'visitor',
+            clientWritable: true
+        },
         ...(options.metricSources ?? []).map(({ id, label, kind, keyedBy, clientWritable })=>({
                 id,
                 label,

package/dist/db/clickGoals.d.ts

@@ -0,0 +1,9 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+/** Defined click goals only; called on the pool by the public events endpoint. */
+export declare function definedClickKeys(exec: Executor): Promise<Set<string>>;
+/** §7.8: click-goal fairness reads published content raw. Never read draft versions. */
+export declare function clickGoalContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | undefined>;

package/dist/db/clickGoals.js

@@ -0,0 +1,22 @@
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Defined click goals only; called on the pool by the public events endpoint. */ export async function definedClickKeys(exec) {
+    const c = COLUMNS.metrics;
+    const { rows } = await exec.query(`SELECT ${q(c.slug)} AS slug FROM ${qualifiedTable(exec, TABLES.metrics)} WHERE ${q(c.source)} = 'click:' || ${q(c.slug)}`);
+    return new Set(rows.map((row)=>row.slug));
+}
+/** §7.8: click-goal fairness reads published content raw. Never read draft versions. */ export async function clickGoalContent(req, collection, id) {
+    const doc = await req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Adapter read: click-goal fairness reads published content raw.
+        overrideAccess: true
+    });
+    const drafts = req.payload.config.collections?.find((c)=>c.slug === collection)?.versions;
+    return doc && (!(drafts && drafts.drafts) || doc._status === 'published') ? doc : undefined;
+}

package/dist/db/delete.d.ts

@@ -3,6 +3,7 @@ import type { DocId } from '../types/contracts.js';
 import type { Executor } from './executor.js';
 interface DeleteState {
     tail: Promise<void>;
+    retiredSlugs: Set<string>;
     excludedIds: Map<string, DocId>;
     pruneFlagDefaultIds: Map<string, DocId>;
 }

package/dist/db/delete.js

@@ -16,6 +16,7 @@ const transactions = new WeakMap();
     if (!state) {
         state = {
             tail: Promise.resolve(),
+            retiredSlugs: new Set(),
             excludedIds: new Map(),
             pruneFlagDefaultIds: new Map()
         };