@delmaredigital/payload-experiments 0.2.0-rc.7 → 0.3.0-rc.1

package/dist/results/analyse.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 import { DEFAULT_GAUSSIAN_PRIOR, bonferroniAlpha, capValues, createThetaAdjustedStatistics, effectBayesianABTest, sequentialOneSidedTreatmentGreaterTTest, sequentialOneSidedTreatmentLesserTTest, sequentialTwoSidedTTest, statisticMean, statisticVariance } from '@delmaredigital/experiments-stats';
 import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { timestampMs } from './aggregate.js';
@@ -18,8 +19,8 @@ const severity = {
  */ export function analysePhase(input) {
     const { phase, units } = input;
     const { analysis } = phase;
-    // Start freezes this optional collection field as-is. Match the stats engine's
-    // default and record the effective value in every snapshot, including n = 0.
+    // Compatibility for phases created before Start froze the effective tuning
+    // value. Record that effective value in every snapshot, including n = 0.
     const sequentialTuningParameter = analysis.sequentialTuningParameter ?? DEFAULT_SEQUENTIAL_TUNING_PARAMETER;
     const alpha = analysis.alpha ?? 0.05;
     const prior = analysis.prior ?? DEFAULT_GAUSSIAN_PRIOR;
@@ -30,7 +31,7 @@ const severity = {
     const rollout = phase.phaseKind === 'rollout';
     const baselineArm = phase.arms.find((arm)=>arm.kind === (rollout ? 'holdout' : 'control'));
     const winner = rollout ? phase.arms.find((arm)=>arm.key === input.winnerArm && arm.kind !== 'holdout') : undefined;
-    if (!baselineArm || rollout && (!winner || phase.arms.length !== 2)) throw new RangeError('Phase comparison baseline or shipped arm is missing');
+    if (!baselineArm || rollout && (!winner || phase.arms.length !== 2)) throw new XpAnalysisError('no-baseline');
     const compared = phase.arms.filter((arm)=>rollout ? arm.key === winner.key : arm.kind === 'variant');
     const k = compared.length;
     const alphaAdjusted = analysis.method === 'sequential' ? bonferroniAlpha(alpha, k) : alpha;
@@ -42,22 +43,22 @@ const severity = {
         }));
     const primaryDefinition = definitions.find((metric)=>metric.role === 'primary');
     if (!primaryDefinition || phase.metricDefinitions.filter((metric)=>metric.role === 'primary').length !== 1) {
-        throw new RangeError('Phase must have exactly one primary metric');
+        throw new XpAnalysisError('primary-metric-count');
     }
     if (new Set(phase.metricDefinitions.map((metric)=>String(metric.metricId))).size !== phase.metricDefinitions.length || new Set(input.metricData.map((metric)=>String(metric.metricId))).size !== input.metricData.length) {
-        throw new RangeError('Duplicate metric id');
+        throw new XpAnalysisError('duplicate-metric');
     }
     const from = timestampMs(phase.startedAt);
     const now = timestampMs(input.now);
     const to = Math.min(now, phase.endedAt == null ? now : timestampMs(phase.endedAt));
-    if (to < from) throw new RangeError('Analysis window ends before the phase starts');
+    if (to < from) throw new XpAnalysisError('window-before-start');
     const byArm = new Map(phase.arms.map((arm)=>[
             arm.key,
             []
         ]));
     for (const [id, unit] of units){
         const ids = byArm.get(unit.arm);
-        if (!ids) throw new RangeError('Exposed unit has an unknown arm');
+        if (!ids) throw new XpAnalysisError('unknown-arm');
         ids.push(id);
     }
     const perArm = Object.fromEntries([
@@ -120,17 +121,19 @@ const severity = {
         let worstArmLabel = compared[0]?.label ?? '';
         let worstArm = compared[0]?.key ?? '';
         try {
-            if (!data || data.unavailable !== undefined) throw new Error(data?.unavailable ?? 'Metric data was not supplied');
+            if (!data || data.unavailable !== undefined) {
+                throw new XpAnalysisError('metric-not-supplied');
+            }
             const stats = new Map();
             const cap = kind === 'revenue' ? definition.resolvedCap ?? null : null;
             const useCovariates = analysis.cuped === 'auto' && data.covariates !== undefined && data.covariates.size > 0;
             for (const arm of phase.arms){
                 const ids = byArm.get(arm.key);
                 const values = ids.map((id)=>data.values.get(id) ?? 0);
-                if (!values.every(Number.isFinite)) throw new RangeError('Metric values must be finite');
+                if (!values.every(Number.isFinite)) throw new XpAnalysisError('non-finite-values');
                 const capped = capValues(values, cap);
                 const rawPre = useCovariates ? ids.map((id)=>data.covariates.get(id) ?? 0) : undefined;
-                if (rawPre && !rawPre.every(Number.isFinite)) throw new RangeError('Covariates must be finite');
+                if (rawPre && !rawPre.every(Number.isFinite)) throw new XpAnalysisError('non-finite-covariates');
                 const pre = rawPre && capValues(rawPre, cap).values;
                 const built = outcomeStatistic(kind, capped.values, pre);
                 stats.set(arm.key, built.statistic);
@@ -257,7 +260,20 @@ const severity = {
                 }
             }
         } catch (error) {
-            metric.unavailable = error instanceof Error ? error.message : 'Metric could not be analysed';
+            input.onMetricError?.(error, metricId);
+            let reason = 'analysis-failed';
+            if (error instanceof XpAnalysisError) {
+                switch(error.code){
+                    case 'metric-not-supplied':
+                        reason = data?.unavailable ?? 'not-supplied';
+                        break;
+                    case 'non-finite-values':
+                    case 'non-finite-covariates':
+                        reason = error.code;
+                        break;
+                }
+            }
+            metric.unavailable = reason;
             metric.perArm = [];
             metric.comparisons = [];
             metric.cupedApplied = false;

package/dist/results/cuped.js

@@ -1,13 +1,14 @@
+import { XpAnalysisError } from '../errors.js';
 import { buildRegressionAdjustedStatistic, buildStatistic, summarizeUnits, summarizeUnitsWithCovariate } from '@delmaredigital/experiments-stats';
 /** Build candidate CUPED statistics; the stats engine pools each pair, infers theta,
  * and falls back to the post statistic when pre-period variance/covariance is zero.
  * Missing units in a supplied pre-period map are zero-filled by the caller.
  */ export function outcomeStatistic(kind, values, covariates) {
     if (!values.every(Number.isFinite) || covariates && !covariates.every(Number.isFinite)) {
-        throw new RangeError('Metric values and covariates must be finite');
+        throw new XpAnalysisError('cuped-non-finite');
     }
     if (kind === 'binomial' && (values.some((value)=>value !== 0 && value !== 1) || covariates?.some((value)=>value !== 0 && value !== 1))) {
-        throw new RangeError('Binomial values and covariates must be 0 or 1');
+        throw new XpAnalysisError('cuped-binomial');
     }
     const moments = summarizeUnits(values);
     if (covariates === undefined) return {

package/dist/results/identityCredit.d.ts

@@ -1,16 +1,24 @@
 import type { ExposedUnit, MetricEvent, Timestamp } from './aggregate.js';
-/**
- * Spec §8.3: credit once to the earliest exposed linked visitor; conflicts are diagnostic only.
- * Callers must pass user ids through String() for both identities and user-keyed source events.
- */
-export declare function creditUserEvents(units: ReadonlyMap<string, ExposedUnit>, identities: readonly {
+export interface IdentityLink {
     anonymousId: string;
     userId: string;
-}[], userEvents: readonly {
+    verifiedAt: Timestamp | null;
+    /** Earliest verification across all the user's browsers, exposed or not. */
+    ownedAt: Timestamp | null;
+}
+/** Unverified links credit only events before anyone proves account ownership.
+ * Never-verified accounts keep crediting without a time limit.
+ */
+export declare function eligibleIdentityLinks<T extends IdentityLink>(links: readonly T[], ts: Timestamp): T[];
+/** Credit each event to the earliest exposed eligible visitor, with a stable ID
+ * tie-break. A user counts once if eligible links span arms for a credited event.
+ * Callers must normalize user IDs with String().
+ */
+export declare function creditUserEvents(units: ReadonlyMap<string, ExposedUnit>, identities: readonly IdentityLink[], userEvents: readonly {
     userId: string;
     value: number;
     ts: Timestamp;
-}[]): {
+}[], onConflict?: (userId: string) => void): {
     events: MetricEvent[];
     conflicts: number;
 };

package/dist/results/identityCredit.js

@@ -1,46 +1,45 @@
 import { timestampMs } from './aggregate.js';
-/**
- * Spec §8.3: credit once to the earliest exposed linked visitor; conflicts are diagnostic only.
- * Callers must pass user ids through String() for both identities and user-keyed source events.
- */ export function creditUserEvents(units, identities, userEvents) {
+/** Unverified links credit only events before anyone proves account ownership.
+ * Never-verified accounts keep crediting without a time limit.
+ */ export function eligibleIdentityLinks(links, ts) {
+    const t = timestampMs(ts);
+    return links.filter((link)=>link.verifiedAt !== null || link.ownedAt === null || t < timestampMs(link.ownedAt));
+}
+/** Credit each event to the earliest exposed eligible visitor, with a stable ID
+ * tie-break. A user counts once if eligible links span arms for a credited event.
+ * Callers must normalize user IDs with String().
+ */ export function creditUserEvents(units, identities, userEvents, onConflict) {
+    const starts = new Map([
+        ...units
+    ].map(([id, unit])=>[
+            id,
+            timestampMs(unit.firstTs)
+        ]));
     const users = new Map();
-    const starts = new Map();
-    for (const [unitId, unit] of units)starts.set(unitId, timestampMs(unit.firstTs));
-    for (const { anonymousId, userId } of identities){
-        const unit = units.get(anonymousId);
-        if (!unit) continue;
-        const firstTs = starts.get(anonymousId);
-        const user = users.get(userId);
-        if (!user) users.set(userId, {
-            unitId: anonymousId,
-            firstTs,
-            arms: new Set([
-                unit.arm
-            ])
-        });
-        else {
-            user.arms.add(unit.arm);
-            // Stable tie-break for simultaneous exposures, independent of identity row order.
-            if (firstTs < user.firstTs || firstTs === user.firstTs && anonymousId < user.unitId) {
-                user.unitId = anonymousId;
-                user.firstTs = firstTs;
-            }
-        }
+    for (const link of identities){
+        if (!units.has(link.anonymousId)) continue;
+        const links = users.get(link.userId) ?? [];
+        links.push(link);
+        users.set(link.userId, links);
     }
-    let conflicts = 0;
-    for (const user of users.values())if (user.arms.size > 1) conflicts++;
+    for (const links of users.values())links.sort((a, b)=>starts.get(a.anonymousId) - starts.get(b.anonymousId) || (a.anonymousId < b.anonymousId ? -1 : a.anonymousId > b.anonymousId ? 1 : 0));
+    const conflicts = new Set();
     const events = [];
     for (const event of userEvents){
-        timestampMs(event.ts);
-        const user = users.get(event.userId);
-        if (user) events.push({
-            unitId: user.unitId,
+        const eligible = eligibleIdentityLinks(users.get(event.userId) ?? [], event.ts);
+        if (!eligible.length) continue;
+        events.push({
+            unitId: eligible[0].anonymousId,
             value: event.value,
             ts: event.ts
         });
+        if (new Set(eligible.map((link)=>units.get(link.anonymousId).arm)).size > 1) {
+            conflicts.add(event.userId);
+            onConflict?.(event.userId);
+        }
     }
     return {
         events,
-        conflicts
+        conflicts: conflicts.size
     };
 }

package/dist/results/rolloutUnits.js

@@ -1,7 +1,8 @@
+import { XpAnalysisError } from '../errors.js';
 import { hash, layerSlice, rolloutBucketRanges } from '@delmaredigital/experiments-stats';
 import { timestampMs } from './aggregate.js';
 /** Spec §7.6/§8.1.5 (X1): first-ever rollout exposures inside assignment's exact ranges. */ export function rolloutAnalysisUnits({ exposuresAllPhases, rolloutPhase, seed, testWeights, coverage, layer }) {
-    if (!seed.endsWith('|')) throw new RangeError('Assignment seed must end in |');
+    if (!seed.endsWith('|')) throw new XpAnalysisError('seed-format');
     const first = new Map();
     for (const row of exposuresAllPhases){
         const ts = timestampMs(row.ts);

package/dist/results/snapshot.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 /** JSON cannot represent unbounded confidence limits. */ export function jsonInterval(ci) {
     return ci.map((bound)=>bound !== null && Number.isFinite(bound) ? bound : null);
 }
@@ -138,14 +139,19 @@ const shape = object({
         }),
         by: nullable(id)
     }))
+}, {
+    health: list(object({
+        code: oneOf('version-page-unavailable', 'version-page-unchecked'),
+        path: string
+    }))
 });
 /** Validate the frozen JSON shape and headline/rollout invariants before storage.
  * This also accepts the shared CORE-13/admin fixtures without any I/O.
  */ export function validateSnapshot(value) {
-    if (!shape(value)) throw new TypeError('Invalid Snapshot shape (all numbers must be finite)');
+    if (!shape(value)) throw new XpAnalysisError('snapshot-shape');
     const snapshot = value;
     if (snapshot.phaseKind === 'test' && snapshot.winnerArm !== null || snapshot.phaseKind === 'rollout' && (snapshot.winnerArm === null || !(snapshot.winnerArm in snapshot.exposures.perArm)) || snapshot.verdict.headline !== snapshot.verdict.finding + (snapshot.verdict.action ? ` ${snapshot.verdict.action}` : '') || new Date(snapshot.window.to).getTime() < new Date(snapshot.window.from).getTime()) {
-        throw new TypeError('Invalid Snapshot invariants');
+        throw new XpAnalysisError('snapshot-invariants');
     }
 }
 /** Assemble the already-computed snapshot at the pure/I/O boundary. */ export function assembleSnapshot(snapshot) {

package/dist/results/srm.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 import { checkSrm } from '@delmaredigital/experiments-stats';
 /** SRM uses exposed units and renormalised frozen weights, never allocation or
  * assignment counts. Rollout callers pass only shipped/holdout weights (100-h,h).
@@ -5,7 +6,7 @@ import { checkSrm } from '@delmaredigital/experiments-stats';
  */ export function exposureSrm(arms, perArm) {
     const active = arms.filter((arm)=>arm.weight > 0);
     const weight = active.reduce((sum, arm)=>sum + arm.weight, 0);
-    if (weight <= 0) throw new RangeError('SRM requires positive weights');
+    if (weight <= 0) throw new XpAnalysisError('srm-weights');
     const expected = Object.fromEntries(arms.map((arm)=>[
             arm.key,
             arm.weight / weight

package/dist/sanitizeReadinessDetail.d.ts

@@ -0,0 +1,7 @@
+import type { ReadinessCode } from './types/endpoints.js';
+/** Summary details contain identifiers only. Project known shapes rather than
+ * recursively copying host objects: titles, messages and placement detail are text.
+ * Other checks use authored client fallbacks and need no detail (including slot
+ * counts and layer capacity, which are not identifiers).
+ */
+export declare function sanitizeReadinessDetail(code: ReadinessCode, detail: unknown): unknown;

package/dist/sanitizeReadinessDetail.js

@@ -0,0 +1,54 @@
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+// The runtime's slug/key alphabet, bounded even for host-provided parameter keys.
+const key = (value)=>typeof value === 'string' && value.length <= 128 && /^[A-Za-z0-9_-]+$/.test(value);
+const arm = (value)=>typeof value === 'string' && [
+        'control',
+        'variantA',
+        'variantB',
+        'variantC',
+        'holdout'
+    ].includes(value);
+const failure = (value)=>value === 'placements-failed' || value === 'forbidden' || value === 'not-found';
+/** Summary details contain identifiers only. Project known shapes rather than
+ * recursively copying host objects: titles, messages and placement detail are text.
+ * Other checks use authored client fallbacks and need no detail (including slot
+ * counts and layer capacity, which are not identifiers).
+ */ export function sanitizeReadinessDetail(code, detail) {
+    switch(code){
+        case 'block-path-rule':
+            return object(detail) && Array.isArray(detail.rules) && detail.rules.length && detail.rules.every((index)=>Number.isSafeInteger(index) && index >= 0) ? {
+                rules: detail.rules
+            } : undefined;
+        case 'no-placements':
+            return failure(detail) ? detail : undefined;
+        case 'page-target-unpublished':
+            // Paths only: no query, fragment, whitespace, URL authority or encoded text.
+            return typeof detail === 'string' && detail.length <= 128 && detail.startsWith('/') && !detail.includes('//') && !/[^A-Za-z0-9_/-]/.test(detail) ? detail : undefined;
+        case 'flag-params-invalid':
+            {
+                if (!Array.isArray(detail) || !detail.length || !detail.every((item)=>object(item) && arm(item.arm) && key(item.field))) return undefined;
+                return detail.map((item)=>({
+                        arm: item.arm,
+                        field: item.field
+                    }));
+            }
+        case 'flag-placement-missing':
+            {
+                if (failure(detail)) return detail;
+                if (!object(detail) || !Array.isArray(detail.missing) || !detail.missing.every(arm) || !Array.isArray(detail.placements) || !detail.placements.every((item)=>object(item) && arm(item.arm))) return undefined;
+                return {
+                    missing: detail.missing,
+                    placements: detail.placements.map((item)=>({
+                            arm: item.arm
+                        }))
+                };
+            }
+        case 'undeclared-targeting-key':
+        case 'invalid-targeting-rule':
+            return object(detail) && Array.isArray(detail.attributes) && detail.attributes.length && detail.attributes.every(key) ? {
+                attributes: detail.attributes
+            } : undefined;
+        default:
+            return undefined;
+    }
+}

package/dist/server/linkIdentity.d.ts

@@ -1,4 +1,12 @@
 import type { ExperimentsServerRuntime } from '../types/runtime.js';
+import { type IdentityWriteOutcome } from '../db/identities.js';
+export type LinkIdentityOutcome = IdentityWriteOutcome | 'failed';
+/**
+ * verified: true means this request proves, in this browser, that the person owns
+ * the account: a magic-link or one-time-code callback, password sign-in, or OAuth
+ * callback. It does not mean "a session exists" or "the email is verified".
+ * Never throws into registration or sign-in.
+ */
 export declare function linkIdentity<TUser extends {
     id: string | number;
 } = {
@@ -6,4 +14,5 @@ export declare function linkIdentity<TUser extends {
 }>(serverRuntime: ExperimentsServerRuntime<TUser>, opts: {
     headers: Headers;
     userId: string;
-}): Promise<void>;
+    verified: boolean;
+}): Promise<LinkIdentityOutcome>;

package/dist/server/linkIdentity.js

@@ -2,33 +2,35 @@ import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { insertIdentityOnOwnConnection } from '../db/identities.js';
 import { readUnitCookie } from '../runtime/cookie.js';
-export async function linkIdentity(serverRuntime, opts) {
+/**
+ * verified: true means this request proves, in this browser, that the person owns
+ * the account: a magic-link or one-time-code callback, password sign-in, or OAuth
+ * callback. It does not mean "a session exists" or "the email is verified".
+ * Never throws into registration or sign-in.
+ */ 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 consent = runtime.cookie.consent?.(new NextRequest('http://consent.invalid/', {
+            headers: opts.headers
+        })) !== false;
+        if (!consent) return 'skipped';
         const anonymousId = readUnitCookie(opts.headers, runtime);
-        if (!anonymousId) return;
+        if (!anonymousId) return 'skipped';
         payload = await serverRuntime.getPayload();
-        await insertIdentityOnOwnConnection(payload, {
+        return await insertIdentityOnOwnConnection(payload, {
             anonymousId,
-            userId: opts.userId
+            userId: opts.userId,
+            verified: opts.verified
         });
     } catch (error) {
         try {
-            payload?.logger.error({
+            if (payload) payload.logger.error({
                 err: safeError(error)
             }, 'Experiments: linkIdentity failed');
+            else console.error('[payload-experiments] linkIdentity failed', safeError(error));
         } catch  {}
+        return 'failed';
     }
 }

package/dist/server/metadata.d.ts

@@ -1,5 +1,10 @@
 import type { Metadata } from 'next';
 import type { ExperimentsServerRuntime } from '../types/runtime.js';
+/**
+ * Reads the signed request context via `headers()`, so it decides from the URL the visitor requested, not the
+ * rewritten route. Call it only from a dynamic `generateMetadata`, never inside `'use cache'`. `path` is the
+ * fallback when the proxy did not run.
+ */
 export declare function experimentMetadata<TUser extends {
     id: string | number;
 } = {

package/dist/server/metadata.js

@@ -1,6 +1,14 @@
 import { findNormalisedPathKey, normalisePath } from '../runtime/normalisePath.js';
+import { headers } from 'next/headers.js';
+import { serverRequest } from './request.js';
 import { serverManifest } from './context.js';
-export async function experimentMetadata(serverRuntime, path) {
+/**
+ * Reads the signed request context via `headers()`, so it decides from the URL the visitor requested, not the
+ * rewritten route. Call it only from a dynamic `generateMetadata`, never inside `'use cache'`. `path` is the
+ * fallback when the proxy did not run.
+ */ export async function experimentMetadata(serverRuntime, path) {
+    const { request, hasContext } = serverRequest(new Headers(await headers()), serverRuntime.proxyRuntime.secrets);
+    if (hasContext) path = request.nextUrl.pathname;
     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) {

package/dist/server/runResults.d.ts

@@ -1,10 +1,11 @@
-import type { Payload } from 'payload';
+import { type Payload } from 'payload';
+import type { MetricUnavailableReason } from '../types/reasons.js';
 import type { DocId } from '../types/contracts.js';
 type UnavailableMetric = {
     experimentId: DocId;
     phase: number;
     metricId: DocId;
-    reason: string;
+    reason: MetricUnavailableReason;
 };
 export declare function runResults(payload: Payload, { budgetMs, experimentId, sweep }?: {
     budgetMs?: number;