@delmaredigital/payload-experiments 0.1.0-rc.3 → 0.1.0-rc.6

package/README.md

@@ -372,12 +372,20 @@ is frozen for the round. Capping affects decision statistics, while results
 also show uncapped totals. Count and binomial metrics are never capped.
 
 For simple yes/no outcomes, list names in `eventSources`, for example
-`eventSources: ['signup']`. Names must match `/^[a-z0-9_]+$/`. Editors can then
-choose `events:signup` as a binomial source, backed by stored conversions with
-`eventName: 'signup'`, from either `trackConversion` or
-`trackConversionBeacon`. Only listed event names become `events:<name>`
-sources. They support visitor and user units and allow client writes; they do
-not represent counts or revenue in v1.
+`eventSources: ['signup']`. A bare string allows client writes; the object form
+sets that permission explicitly:
+
+```ts
+eventSources: ['signup', { name: 'donation_completed', clientWritable: false }]
+```
+
+Names must match `/^[a-z0-9_]+$/` and be unique across both forms. Editors can
+choose `events:signup` or `events:donation_completed` as binomial sources backed
+by stored conversions with the corresponding `eventName`. Writable sources
+accept both `trackConversion` and `trackConversionBeacon`; server-only sources
+are recorded with `trackConversion`. Beacon conversions for a non-writable name
+are dropped silently. Only listed names become `events:<name>` sources. They
+support visitor and user units and do not represent counts or revenue in v1.
 
 ## Security
 

package/dist/collections/serialize.js

@@ -16,12 +16,12 @@ export function serializeMetricSources(options) {
                 keyedBy,
                 clientWritable: clientWritable === true
             })),
-        ...(options.eventSources ?? []).map((name)=>({
+        ...(options.eventSources ?? []).map(({ name, clientWritable })=>({
                 id: `events:${name}`,
                 label: name,
                 kind: 'binomial',
                 keyedBy: 'visitor',
-                clientWritable: true
+                clientWritable
             }))
     ];
 }

package/dist/events/rows.js

@@ -42,7 +42,7 @@ export function eventRows(events, manifest, assignments, options, visitorId, use
         } else if (event.type === 'conversion') {
             if (typeof event.eventName !== 'string' || typeof event.idempotencyKey !== 'string' || !event.idempotencyKey.trim() || event.value !== undefined && (typeof event.value !== 'number' || !Number.isFinite(event.value))) continue;
             const source = options.metricSources?.find((source)=>source.id === event.eventName);
-            if (source ? source.clientWritable !== true || source.kind === 'revenue' : !options.eventSources?.includes(event.eventName)) continue;
+            if (source ? source.clientWritable !== true || source.kind === 'revenue' : !options.eventSources?.some((source)=>source.name === event.eventName && source.clientWritable)) continue;
             row = {
                 type: 'conversion',
                 eventName: event.eventName,

package/dist/options.js

@@ -42,9 +42,19 @@ export function resolveOptions(input) {
             throw new Error(`Experiments attribute values must be strings: ${key}`);
         }
     }
-    for (const name of input.eventSources ?? []){
+    const eventNames = new Set();
+    const eventSources = (input.eventSources ?? []).map((entry)=>{
+        const object = entry !== null && typeof entry === 'object' && !Array.isArray(entry);
+        const name = typeof entry === 'string' ? entry : object ? entry.name : undefined;
         if (typeof name !== 'string' || !/^[a-z0-9_]+$/.test(name)) throw new Error('Experiments event source names must match /^[a-z0-9_]+$/');
-    }
+        if (object && typeof entry.clientWritable !== 'boolean') throw new Error('Experiments event source clientWritable must be a boolean');
+        if (eventNames.has(name)) throw new Error('Experiments event source names must be unique');
+        eventNames.add(name);
+        return {
+            name,
+            clientWritable: typeof entry === 'string' ? true : entry.clientWritable
+        };
+    });
     const retentionDays = input.events?.retentionDays ?? 180;
     const maxBodyBytes = input.events?.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
     for (const [name, value] of Object.entries({
@@ -68,9 +78,7 @@ export function resolveOptions(input) {
         metricSources: [
             ...input.metricSources ?? []
         ],
-        eventSources: [
-            ...input.eventSources ?? []
-        ],
+        eventSources,
         attributeKeys: Object.fromEntries(Object.entries(input.attributeKeys ?? {}).map(([key, attribute])=>[
                 key,
                 {

package/dist/server/runResults.js

@@ -88,7 +88,7 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
             let events, covariates;
             if (definition.source.startsWith('events:')) {
                 const eventName = definition.source.slice(7);
-                if (!options.eventSources?.includes(eventName)) throw new Error('Metric source unavailable');
+                if (!options.eventSources?.some((source)=>source.name === eventName)) throw new Error('Metric source unavailable');
                 const read = async (start)=>{
                     if (candidate.unitType === 'user') return metricEventRows(exec, {
                         eventName,

package/dist/types/contracts.d.ts

@@ -105,7 +105,10 @@ export interface ExperimentsPluginOptions<TUser extends {
         readIdentities?: ExperimentsAccess;
     };
     metricSources?: MetricSource[];
-    eventSources?: string[];
+    eventSources?: Array<string | {
+        name: string;
+        clientWritable: boolean;
+    }>;
     flagPoints?: FlagPoint[];
     attributeKeys?: Record<string, {
         type: 'string' | 'number' | 'boolean';
@@ -130,4 +133,9 @@ export type ResolvedOptions<TUser extends {
     id: string | number;
 } = {
     id: string | number;
-}> = ExperimentsPluginOptions<TUser>;
+}> = Omit<ExperimentsPluginOptions<TUser>, 'eventSources'> & {
+    eventSources?: Array<{
+        name: string;
+        clientWritable: boolean;
+    }>;
+};

package/dist/types/contracts.js

@@ -1,2 +1 @@
-/** Options required by the route table; CORE-02c resolves optional defaults. */ // CORE-02c may narrow this alias (pre-authorised exception to the src/types freeze)
-export { };
+/** Options required by the route table; CORE-02c resolves optional defaults. */ export { };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-experiments",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.6",
   "description": "No-code A/B testing for Payload CMS and Next.js: block, page and flag experiments with holdouts, layers, exposure logging and honest statistics inside the admin — no vendor",
   "type": "module",
   "license": "MIT",
@@ -60,7 +60,8 @@
       "types": "./dist/exports/puckEditor.d.ts",
       "import": "./dist/exports/puckEditor.js",
       "default": "./dist/exports/puckEditor.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",