@createcms/core 0.1.1

package/dist/ab-edge/index.js

@@ -0,0 +1,205 @@
+/**
+ * MurmurHash3 (32-bit) for deterministic variant assignment.
+ * Inlined to avoid an external dependency for ~30 lines of code.
+ */ function murmur3(key, seed = 0) {
+    let h = seed >>> 0;
+    const len = key.length;
+    let i = 0;
+    while(i + 4 <= len){
+        let k = key.charCodeAt(i) & 0xff | (key.charCodeAt(i + 1) & 0xff) << 8 | (key.charCodeAt(i + 2) & 0xff) << 16 | (key.charCodeAt(i + 3) & 0xff) << 24;
+        k = Math.imul(k, 0xcc9e2d51);
+        k = k << 15 | k >>> 17;
+        k = Math.imul(k, 0x1b873593);
+        h ^= k;
+        h = h << 13 | h >>> 19;
+        h = Math.imul(h, 5) + 0xe6546b64;
+        i += 4;
+    }
+    let k = 0;
+    switch(len & 3){
+        case 3:
+            k ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+        // falls through
+        case 2:
+            k ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+        // falls through
+        case 1:
+            k ^= key.charCodeAt(i) & 0xff;
+            k = Math.imul(k, 0xcc9e2d51);
+            k = k << 15 | k >>> 17;
+            k = Math.imul(k, 0x1b873593);
+            h ^= k;
+    }
+    h ^= len;
+    h ^= h >>> 16;
+    h = Math.imul(h, 0x85ebca6b);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0xc2b2ae35);
+    h ^= h >>> 16;
+    return h >>> 0;
+}
+/**
+ * Deterministic variant assignment.
+ *
+ * The same `contextKey + testId` always produces the same variant.
+ * No DB writes needed -- pure function.
+ *
+ * @param contextKey  - Visitor identifier (user ID or anonymous key)
+ * @param testId      - The A/B test ID
+ * @param trafficPercentage - 0-100, how much total traffic enters the test
+ * @param variants    - Must be sorted by id for stability
+ */ function resolveVariant(contextKey, testId, trafficPercentage, variants) {
+    const hash = murmur3(contextKey + ':' + testId);
+    const bucket = hash % 10000;
+    const control = variants.find((v)=>v.isControl);
+    if (bucket >= trafficPercentage * 100) {
+        return {
+            variantId: control.id,
+            inTest: false
+        };
+    }
+    const sorted = [
+        ...variants
+    ].sort((a, b)=>a.id.localeCompare(b.id));
+    const normalizedBucket = Math.floor(bucket * 100 / (trafficPercentage * 100));
+    let cumulative = 0;
+    for (const v of sorted){
+        cumulative += v.weight;
+        if (normalizedBucket < cumulative) {
+            return {
+                variantId: v.id,
+                inTest: true
+            };
+        }
+    }
+    return {
+        variantId: control.id,
+        inTest: true
+    };
+}
+
+/**
+ * The control sentinel code. Pattern A ALWAYS rewrites (Vercel "precompute"
+ * model): a request with no running test / no consent / outside traffic is
+ * rewritten to `/<CONTROL_CODE><pathname>` so it still lands on the single
+ * `[abVariant]` route — there is no un-coded passthrough. It is never a real
+ * branch id (ids are prefixed), and the render route maps it to the control
+ * tree (pickVariant fails closed to control for any non-variant code anyway).
+ */ const CONTROL_CODE = 'control';
+/**
+ * The static path prefix the render route lives under (`app/<prefix>/[abVariant]/
+ * [[...rest]]`). Pattern A rewrites every public request UNDER this prefix so the
+ * variant-coded route never sits at the URL root — otherwise a root catch-all
+ * would shadow sibling app routes (e.g. a `/app/*` dashboard). It is internal +
+ * transparent (the browser keeps the original URL), so the value only needs to
+ * differ from your real top-level app prefixes; with always-rewrite even a real
+ * page slugged `/ab` still works (it is rewritten THROUGH the prefix).
+ */ const DEFAULT_VARIANT_PREFIX = '/ab';
+/**
+ * Build the variant-coded rewrite path: `<prefix>/<code><pathname>`. The variant
+ * code is the first segment AFTER the static prefix — the cache key — never a
+ * header/searchParam, so each variant is its own CDN/ISR cache entry (Vercel
+ * Flags precompute pattern, nested under `<prefix>` to coexist with other app
+ * routes). The matching render route reads the code segment back.
+ */ function variantRewritePath(prefix, code, pathname) {
+    // For the root path, omit the trailing slash (`<prefix>/<code>`, not
+    // `<prefix>/<code>/`) so the optional-catch-all variant route matches cleanly.
+    const suffix = pathname === '/' ? '' : pathname;
+    return `${prefix}/${encodeURIComponent(code)}${suffix}`;
+}
+/** Parse a first-party consent cookie value; analytics granted → true. */ function parseConsentCookie(value) {
+    if (!value) return false;
+    try {
+        const state = JSON.parse(decodeURIComponent(value));
+        return state.analytics_storage === 'granted';
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Edge-safe random visitor id (mirrors the client `anon_` key shape). Uses the
+ * `crypto` global (Web Crypto), available in every edge/worker/browser runtime.
+ */ function generateEdgeVisitorId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const b of bytes)hex += b.toString(16).padStart(2, '0');
+    return `anon_${hex}`;
+}
+/**
+ * PURE bucketing: given a one-shot `key`, the branch to render IN-TEST, or null =
+ * serve control (no running test, or the roll lands outside the test traffic).
+ * NO consent / NO persistent identifier — the caller passes an EPHEMERAL random
+ * key for a first assignment and then persists only the chosen branch (a
+ * variant-only cookie), so nothing identifying is stored. Reuses the same
+ * weighted hash as the server pick.
+ */ function pickEdgeVariant(opts) {
+    const test = opts.resolve.test;
+    if (!test) return {
+        branchId: null
+    };
+    const result = resolveVariant(opts.key, test.testId, test.trafficPercentage, test.variants.map((v)=>({
+            id: v.variantId,
+            weight: v.weight,
+            isControl: v.isControl
+        })));
+    if (!result.inTest) return {
+        branchId: null
+    }; // outside traffic → control
+    const picked = test.variants.find((v)=>v.variantId === result.variantId);
+    return {
+        branchId: picked?.branchId ?? null
+    };
+}
+/**
+ * The framework-agnostic edge decision (ALWAYS-rewrite / Vercel precompute).
+ * CONSENT-FREE by design: serving a variant + a VARIANT-ONLY cookie (no visitor
+ * id, no behavioural data, no third-party transmission) falls under the ePrivacy
+ * "strictly necessary" exemption, so fresh ad traffic gets real variants (not
+ * always control).
+ *
+ * - `assignedCode` is the value of the test's variant cookie (`ab_<testId>`) — a
+ *   branch id, or the control sentinel — from a previous visit. If still valid
+ *   it is REUSED (consistent variant across requests, no re-roll).
+ * - Otherwise a FIRST assignment is rolled from an ephemeral random key; the
+ *   chosen code is returned in `assignCode` for the adapter to persist in the
+ *   variant cookie. Out-of-traffic → the control sentinel (no impression).
+ *
+ * `rewritePath` is always non-null. Returns the `testId` so the adapter knows
+ * which cookie to set. No persistent identifier is ever minted here — the
+ * consent-gated visitor id + GA4 forwarding live in the client pipeline.
+ */ function decideEdgeVariant(input) {
+    const controlCode = input.controlCode ?? CONTROL_CODE;
+    const prefix = input.variantPrefix ?? DEFAULT_VARIANT_PREFIX;
+    const test = input.resolve.test;
+    if (!test) {
+        return {
+            rewritePath: variantRewritePath(prefix, controlCode, input.pathname),
+            assignCode: null,
+            testId: null
+        };
+    }
+    // Reuse a still-valid prior assignment (a published variant branch, or the
+    // control sentinel for an out-of-traffic visitor) → consistent, no re-roll.
+    const reusable = input.assignedCode === controlCode || input.assignedCode != null && test.variants.some((v)=>v.branchId === input.assignedCode);
+    if (reusable) {
+        return {
+            rewritePath: variantRewritePath(prefix, input.assignedCode, input.pathname),
+            assignCode: null,
+            testId: test.testId
+        };
+    }
+    // First assignment: roll once from an ephemeral (non-persisted) random key.
+    const { branchId } = pickEdgeVariant({
+        key: generateEdgeVisitorId(),
+        resolve: input.resolve
+    });
+    const code = branchId ?? controlCode; // out-of-traffic → control sentinel
+    return {
+        rewritePath: variantRewritePath(prefix, code, input.pathname),
+        assignCode: code,
+        testId: test.testId
+    };
+}
+
+export { CONTROL_CODE, DEFAULT_VARIANT_PREFIX, decideEdgeVariant, generateEdgeVisitorId, parseConsentCookie, pickEdgeVariant, resolveVariant, variantRewritePath };