@createcms/core 0.1.1

package/dist/next/middleware.d.cts

@@ -0,0 +1,77 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/** One variant branch of the resolved test (enough for edge bucketing). */
+type ResolvedAbVariant = {
+    /** ab_test_variants.id — the `variantId` resolveVariant buckets to. */
+    variantId: string;
+    /** The published branch this variant renders. */
+    branchId: string;
+    weight: number;
+    isControl: boolean;
+};
+type AbResolveResult = {
+    test: {
+        testId: string;
+        /** The root the test attaches to (page root or an embedded block root). */
+        rootId: string;
+        trafficPercentage: number;
+        variants: ResolvedAbVariant[];
+    } | null;
+};
+
+type AbTestMiddlewareOptions = {
+    /** The slug-routed collection these public paths belong to (e.g. 'pages'). */
+    collection: string;
+    /** Where the CMS router is mounted. Default '/api/cms'. */
+    cmsBaseUrl?: string;
+    /**
+     * The control sentinel code used as the variant-code segment when there is no
+     * test / the visitor is outside traffic. Default 'control'. Must match the
+     * value your `[abVariant]` route treats as "render control".
+     */
+    controlCode?: string;
+    /**
+     * The static path prefix the variant render route lives under
+     * (`app/<prefix>/[abVariant]/[[...rest]]`). Default '/ab'. Keeps the
+     * variant-coded route off the URL root so it does not shadow sibling app
+     * routes (e.g. a `/app/*` dashboard). Must match your route folder.
+     */
+    variantPrefix?: string;
+    /**
+     * Name prefix for the per-test variant cookie (`<prefix><testId>`). Default
+     * 'ab_'. The cookie stores ONLY the assigned variant code — no identifier.
+     */
+    variantCookiePrefix?: string;
+    /**
+     * Lifetime of the variant cookie in seconds. Default 30 days. Keep it close to
+     * your test duration (ePrivacy discourages a long-lived cookie "without a
+     * technical reason").
+     */
+    variantCookieMaxAge?: number;
+    /**
+     * How to fetch the resolve seam for a path. Default: GET
+     * `<cmsBaseUrl>/<collection>/resolveAbVariant?path=`, forwarding the request
+     * cookies so the CMS resolves the same tenant/language scope. This default
+     * does the (cheap) resolve lookup PER REQUEST — a middleware fetch is not
+     * served by the Next.js Data Cache. For high traffic, override this with a
+     * reader backed by Vercel Edge Config / KV precomputed on test start/stop.
+     */
+    resolve?: (request: NextRequest, path: string) => Promise<AbResolveResult>;
+};
+/**
+ * Next.js Pattern A A/B fan-out — ALWAYS rewrites the request to the variant-
+ * coded `[abVariant]` route. Compose it inside your `proxy.ts` (Next 16) AFTER
+ * the auth gate, and only for PUBLIC CMS paths (it has no passthrough):
+ * ```ts
+ * // proxy.ts
+ * const abTest = abTestMiddleware({ collection: 'pages' });
+ * export default async function proxy(request) {
+ *   if (isProtected(request)) return authGate(request); // not rewritten
+ *   return abTest(request); // public CMS content → /ab/<code>/<path>
+ * }
+ * ```
+ */
+declare function abTestMiddleware(options: AbTestMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;
+
+export { abTestMiddleware };
+export type { AbTestMiddlewareOptions };

package/dist/next/middleware.d.ts

@@ -0,0 +1,77 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/** One variant branch of the resolved test (enough for edge bucketing). */
+type ResolvedAbVariant = {
+    /** ab_test_variants.id — the `variantId` resolveVariant buckets to. */
+    variantId: string;
+    /** The published branch this variant renders. */
+    branchId: string;
+    weight: number;
+    isControl: boolean;
+};
+type AbResolveResult = {
+    test: {
+        testId: string;
+        /** The root the test attaches to (page root or an embedded block root). */
+        rootId: string;
+        trafficPercentage: number;
+        variants: ResolvedAbVariant[];
+    } | null;
+};
+
+type AbTestMiddlewareOptions = {
+    /** The slug-routed collection these public paths belong to (e.g. 'pages'). */
+    collection: string;
+    /** Where the CMS router is mounted. Default '/api/cms'. */
+    cmsBaseUrl?: string;
+    /**
+     * The control sentinel code used as the variant-code segment when there is no
+     * test / the visitor is outside traffic. Default 'control'. Must match the
+     * value your `[abVariant]` route treats as "render control".
+     */
+    controlCode?: string;
+    /**
+     * The static path prefix the variant render route lives under
+     * (`app/<prefix>/[abVariant]/[[...rest]]`). Default '/ab'. Keeps the
+     * variant-coded route off the URL root so it does not shadow sibling app
+     * routes (e.g. a `/app/*` dashboard). Must match your route folder.
+     */
+    variantPrefix?: string;
+    /**
+     * Name prefix for the per-test variant cookie (`<prefix><testId>`). Default
+     * 'ab_'. The cookie stores ONLY the assigned variant code — no identifier.
+     */
+    variantCookiePrefix?: string;
+    /**
+     * Lifetime of the variant cookie in seconds. Default 30 days. Keep it close to
+     * your test duration (ePrivacy discourages a long-lived cookie "without a
+     * technical reason").
+     */
+    variantCookieMaxAge?: number;
+    /**
+     * How to fetch the resolve seam for a path. Default: GET
+     * `<cmsBaseUrl>/<collection>/resolveAbVariant?path=`, forwarding the request
+     * cookies so the CMS resolves the same tenant/language scope. This default
+     * does the (cheap) resolve lookup PER REQUEST — a middleware fetch is not
+     * served by the Next.js Data Cache. For high traffic, override this with a
+     * reader backed by Vercel Edge Config / KV precomputed on test start/stop.
+     */
+    resolve?: (request: NextRequest, path: string) => Promise<AbResolveResult>;
+};
+/**
+ * Next.js Pattern A A/B fan-out — ALWAYS rewrites the request to the variant-
+ * coded `[abVariant]` route. Compose it inside your `proxy.ts` (Next 16) AFTER
+ * the auth gate, and only for PUBLIC CMS paths (it has no passthrough):
+ * ```ts
+ * // proxy.ts
+ * const abTest = abTestMiddleware({ collection: 'pages' });
+ * export default async function proxy(request) {
+ *   if (isProtected(request)) return authGate(request); // not rewritten
+ *   return abTest(request); // public CMS content → /ab/<code>/<path>
+ * }
+ * ```
+ */
+declare function abTestMiddleware(options: AbTestMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;
+
+export { abTestMiddleware };
+export type { AbTestMiddlewareOptions };

package/dist/next/middleware.js

@@ -0,0 +1,111 @@
+import { NextResponse } from 'next/server';
+import { CONTROL_CODE, DEFAULT_VARIANT_PREFIX, decideEdgeVariant, variantRewritePath } from '../ab-edge/index.js';
+
+// ============================================================================
+// AB_FANOUT — Next.js edge middleware (Pattern A: cache-per-variant)
+// ============================================================================
+//
+// A THIN adapter over the framework-agnostic core in `@createcms/core/ab-edge`:
+// supplies the Next primitives (NextRequest cookies, NextResponse.rewrite, the
+// resolve fetch). The bucketing + rewrite decision lives in `decideEdgeVariant`.
+// EDGE-SAFE (only `next/server` + the core; no Node built-ins).
+//
+// ALWAYS-REWRITE + CONSENT-FREE: every request is rewritten to
+// `<prefix>/<code><pathname>` (the assigned branch, or the control sentinel) so
+// it lands on the single `[abVariant]` route. The variant is kept consistent via
+// a VARIANT-ONLY cookie `ab_<testId>=<code>` — no visitor id, no behavioural
+// data, no third-party transmission → ePrivacy "strictly necessary" exemption,
+// so fresh ad traffic gets real variants (not always control). The consent-gated
+// pieces (persistent visitor id, GA4/dataLayer forwarding) live in the client
+// pipeline, NOT here. There is NO passthrough, so scope this to PUBLIC CMS paths
+// only (compose it in your proxy after the auth gate).
+const DEFAULT_CMS_BASE = '/api/cms';
+const DEFAULT_VARIANT_COOKIE_PREFIX = 'ab_';
+const THIRTY_DAYS_SEC = 2_592_000;
+async function defaultResolve(request, options, path) {
+    const base = options.cmsBaseUrl ?? DEFAULT_CMS_BASE;
+    const url = new URL(`${base}/${options.collection}/resolveAbVariant`, request.nextUrl.origin);
+    url.searchParams.set('path', path);
+    try {
+        const res = await fetch(url, {
+            headers: {
+                cookie: request.headers.get('cookie') ?? ''
+            }
+        });
+        if (!res.ok) return {
+            test: null
+        };
+        return await res.json();
+    } catch  {
+        return {
+            test: null
+        }; // fail open to control — render/paint never blocks
+    }
+}
+/**
+ * Next.js Pattern A A/B fan-out — ALWAYS rewrites the request to the variant-
+ * coded `[abVariant]` route. Compose it inside your `proxy.ts` (Next 16) AFTER
+ * the auth gate, and only for PUBLIC CMS paths (it has no passthrough):
+ * ```ts
+ * // proxy.ts
+ * const abTest = abTestMiddleware({ collection: 'pages' });
+ * export default async function proxy(request) {
+ *   if (isProtected(request)) return authGate(request); // not rewritten
+ *   return abTest(request); // public CMS content → /ab/<code>/<path>
+ * }
+ * ```
+ */ function abTestMiddleware(options) {
+    const controlCode = options.controlCode ?? CONTROL_CODE;
+    const variantPrefix = options.variantPrefix ?? DEFAULT_VARIANT_PREFIX;
+    const cookiePrefix = options.variantCookiePrefix ?? DEFAULT_VARIANT_COOKIE_PREFIX;
+    const cookieMaxAge = options.variantCookieMaxAge ?? THIRTY_DAYS_SEC;
+    const resolve = options.resolve ?? ((req, path)=>defaultResolve(req, options, path));
+    return async (request)=>{
+        const { pathname } = request.nextUrl;
+        // Resolve, reuse-or-assign the variant, then ALWAYS rewrite to
+        // `<prefix>/<code><pathname>`. Any failure fails closed to the control code,
+        // so the request still lands on the `[abVariant]` route (never a 404).
+        let rewritePath;
+        let setCookie = null;
+        try {
+            const resolved = await resolve(request, pathname);
+            const testId = resolved.test?.testId ?? null;
+            const assignedCode = testId ? request.cookies.get(`${cookiePrefix}${testId}`)?.value ?? null : null;
+            const decision = decideEdgeVariant({
+                pathname,
+                resolve: resolved,
+                assignedCode,
+                controlCode,
+                variantPrefix
+            });
+            rewritePath = decision.rewritePath;
+            // A first assignment → persist the chosen variant code (variant-only).
+            if (decision.assignCode && decision.testId) {
+                setCookie = {
+                    name: `${cookiePrefix}${decision.testId}`,
+                    value: decision.assignCode
+                };
+            }
+        } catch  {
+            rewritePath = variantRewritePath(variantPrefix, controlCode, pathname);
+        }
+        const rewriteUrl = request.nextUrl.clone();
+        rewriteUrl.pathname = rewritePath; // transparent — browser URL unchanged
+        const response = NextResponse.rewrite(rewriteUrl);
+        if (setCookie) {
+            response.cookies.set(setCookie.name, setCookie.value, {
+                path: '/',
+                maxAge: cookieMaxAge,
+                sameSite: 'lax',
+                secure: true,
+                // httpOnly: the cookie is sent with every request, so cross-page
+                // conversion attribution reads it SERVER-side (no client read needed) —
+                // keep it httpOnly to harden against XSS. It holds only the variant code.
+                httpOnly: true
+            });
+        }
+        return response;
+    };
+}
+
+export { abTestMiddleware };

package/dist/plugins/ab-test/analytics/upstash.cjs

@@ -0,0 +1,345 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var drizzleOrm = require('drizzle-orm');
+var nanoid$1 = require('nanoid');
+
+const nanoid = nanoid$1.customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 20);
+const prefixes = {
+    root: 'rot',
+    commit: 'cmt',
+    branch: 'brn',
+    blockVersion: 'blv',
+    block: 'blk',
+    mergeRequest: 'mrq',
+    mergeConflict: 'mcf',
+    approval: 'apr',
+    assetFolder: 'afl',
+    asset: 'ast',
+    contentUsage: 'cus',
+    commentThread: 'cth',
+    commentMessage: 'cmg',
+    commentMention: 'cmn',
+    variable: 'var',
+    template: 'tpl',
+    tplVarUsage: 'tvu',
+    notification: 'ntf',
+    si: 'sid',
+    redirect: 'rdr'
+};
+const customPrefixes = new Map();
+function newId(prefix) {
+    const resolved = prefixes[prefix] ?? customPrefixes.get(prefix);
+    if (!resolved) {
+        throw new Error(`Unknown ID prefix "${prefix}". Register it with registerIdPrefix() first.`);
+    }
+    return `${resolved}_${nanoid()}`;
+}
+
+// Prevent Turbopack/webpack from statically analyzing these imports.
+// The bundler rewrites bare `import('...')` calls into require/resolve
+// that fail when the package lives in a different workspace. By
+// constructing the specifier at runtime the import stays a true
+// dynamic import that Node resolves at execution time.
+const _upstashRedisId = [
+    '@upstash',
+    'redis'
+].join('/');
+const _upstashRealtimeId = [
+    '@upstash',
+    'realtime'
+].join('/');
+const _importUpstashRedis = ()=>new Function('id', 'return import(id)')(_upstashRedisId);
+const _importUpstashRealtime = ()=>new Function('id', 'return import(id)')(_upstashRealtimeId);
+const aggregationsTable = {
+    tableName: 'ab_test_aggregations',
+    indexPrefix: 'aba',
+    columns: {
+        id: {
+            type: 'text',
+            primaryKey: true,
+            defaultId: true,
+            defaultIdPrefix: 'abTestAgg'
+        },
+        testId: {
+            type: 'text',
+            notNull: true,
+            references: {
+                table: 'abTests',
+                column: 'id',
+                onDelete: 'cascade'
+            }
+        },
+        variantId: {
+            type: 'text',
+            notNull: true,
+            references: {
+                table: 'abTestVariants',
+                column: 'id',
+                onDelete: 'cascade'
+            }
+        },
+        eventType: {
+            type: 'text',
+            notNull: true
+        },
+        count: {
+            type: 'integer',
+            notNull: true,
+            default: {
+                kind: 'literal',
+                value: 0
+            }
+        },
+        uniqueVisitors: {
+            type: 'integer',
+            notNull: true,
+            default: {
+                kind: 'literal',
+                value: 0
+            }
+        },
+        periodStart: {
+            type: 'timestamp',
+            notNull: true
+        },
+        periodEnd: {
+            type: 'timestamp',
+            notNull: true
+        },
+        updatedAt: {
+            type: 'timestamp',
+            notNull: true,
+            defaultNow: true
+        }
+    },
+    indexes: {
+        testPeriodIdx: {
+            columns: [
+                'testId',
+                'periodStart'
+            ]
+        },
+        uniqueBucketIdx: {
+            columns: [
+                'testId',
+                'variantId',
+                'eventType',
+                'periodStart'
+            ],
+            unique: true
+        }
+    }
+};
+/**
+ * Upstash Redis Stream adapter with batch flush and realtime delta publishing.
+ *
+ * Requires `@upstash/redis` and `@upstash/realtime` as peer dependencies.
+ * Events are stored in Redis Streams and flushed to Postgres on demand.
+ * Live deltas are published to `ab:live:{testId}` channels for realtime dashboards.
+ */ function upstashAnalytics(options) {
+    let db;
+    let redis;
+    const adapter = {
+        tables: {
+            abTestAggregations: aggregationsTable
+        },
+        realtimeInstance: null,
+        async init (instance) {
+            db = instance;
+            const upstashRedis = await _importUpstashRedis();
+            redis = new upstashRedis.Redis({
+                url: options.url,
+                token: options.token
+            });
+            try {
+                const upstashRealtime = await _importUpstashRealtime();
+                adapter.realtimeInstance = new upstashRealtime.Realtime({
+                    url: options.url,
+                    token: options.token
+                });
+            } catch  {
+            // @upstash/realtime not installed -- realtime disabled
+            }
+        },
+        async track (event) {
+            // The Upstash adapter is the A/B-dashboard sink: it streams per-test
+            // events (keyed by testId) for live deltas + flush-to-aggregations, and
+            // it does NOT provision an ab_test_events table. A non-A/B analytics
+            // event (no `ab`) therefore has no durable home in this adapter and is
+            // DROPPED — there is no other sink to catch it until the M3 event-bus
+            // ships (see AB_MEASUREMENT_DESIGN §9 carry-forward). Make the drop loud
+            // rather than silent so a single-sink upstash deployment can see it.
+            if (!event.ab) {
+                console.warn(`[cms] upstashAnalytics dropped a non-A/B event ("${event.name}"): this A/B-realtime adapter has no durable store for non-A/B events. Use the postgres adapter (or wait for the M3 event-bus) to persist page_view / form_submit events.`);
+                return;
+            }
+            const { testId, variantId } = event.ab;
+            const streamKey = `ab:events:${testId}`;
+            const entry = {
+                testId,
+                variantId,
+                visitorId: event.visitorId ?? '',
+                anonymous: String(event.anonymous),
+                eventType: event.name,
+                timestamp: event.timestamp.toISOString()
+            };
+            if (event.metadata) {
+                entry.metadata = JSON.stringify(event.metadata);
+            }
+            await redis.xadd(streamKey, '*', entry);
+            if (adapter.realtimeInstance) {
+                const delta = {
+                    variantId,
+                    eventType: event.name,
+                    count: 1,
+                    timestamp: Date.now()
+                };
+                try {
+                    await redis.publish(`ab:live:${testId}`, JSON.stringify(delta));
+                } catch  {
+                // Non-critical
+                }
+            }
+        },
+        async query (testId, options) {
+            const fromClause = options?.from ? drizzleOrm.sql` AND a.period_start >= ${options.from}` : drizzleOrm.sql``;
+            const toClause = options?.to ? drizzleOrm.sql` AND a.period_end <= ${options.to}` : drizzleOrm.sql``;
+            const rows = await db.execute(drizzleOrm.sql`
+        SELECT
+          a.variant_id,
+          v.name AS variant_name,
+          a.event_type,
+          SUM(a.count)::int AS count,
+          SUM(a.unique_visitors)::int AS unique_visitors
+        FROM cms.ab_test_aggregations a
+        INNER JOIN cms.ab_test_variants v ON v.id = a.variant_id
+        WHERE a.test_id = ${testId}
+          ${fromClause}
+          ${toClause}
+        GROUP BY a.variant_id, v.name, a.event_type
+        ORDER BY a.variant_id, a.event_type
+      `);
+            const variantMap = new Map();
+            for (const row of rows.rows){
+                let v = variantMap.get(row.variant_id);
+                if (!v) {
+                    v = {
+                        variantId: row.variant_id,
+                        variantName: row.variant_name,
+                        impressions: 0,
+                        conversions: 0,
+                        uniqueVisitors: 0,
+                        conversionRate: 0,
+                        // The upstash pre-aggregate flush does not track interaction ids, so
+                        // the funnel (attempts/completionRate) is the postgres path only.
+                        attempts: 0,
+                        completionRate: 0,
+                        eventBreakdown: {}
+                    };
+                    variantMap.set(row.variant_id, v);
+                }
+                v.eventBreakdown[row.event_type] = {
+                    count: row.count,
+                    uniqueVisitors: row.unique_visitors,
+                    distinctInteractions: 0
+                };
+                if (row.event_type === 'impression') {
+                    v.impressions = row.count;
+                    v.uniqueVisitors = row.unique_visitors;
+                } else if (row.event_type === 'conversion') {
+                    v.conversions = row.count;
+                }
+            }
+            const variants = [
+                ...variantMap.values()
+            ];
+            for (const v of variants){
+                v.conversionRate = v.impressions > 0 ? Math.round(v.conversions / v.impressions * 10000) / 100 : 0;
+            }
+            return {
+                testId,
+                variants,
+                totalImpressions: variants.reduce((s, v)=>s + v.impressions, 0),
+                totalConversions: variants.reduce((s, v)=>s + v.conversions, 0)
+            };
+        },
+        async flush (testId) {
+            const streamKeys = [];
+            if (testId) {
+                streamKeys.push(`ab:events:${testId}`);
+            } else {
+                let cursor = '0';
+                do {
+                    const [nextCursor, keys] = await redis.scan(cursor, {
+                        match: 'ab:events:*',
+                        count: 100
+                    });
+                    cursor = nextCursor;
+                    streamKeys.push(...keys);
+                }while (cursor !== '0')
+            }
+            let totalFlushed = 0;
+            for (const streamKey of streamKeys){
+                const cursorKey = `ab:cursor:${streamKey}`;
+                const lastId = await redis.get(cursorKey) ?? '0-0';
+                const results = await redis.xread([
+                    {
+                        key: streamKey,
+                        id: lastId
+                    }
+                ], {
+                    count: 10000
+                });
+                if (!results || results.length === 0) continue;
+                const stream = results[0];
+                if (!stream || !stream.messages || stream.messages.length === 0) continue;
+                const agg = new Map();
+                let maxId = lastId;
+                for (const msg of stream.messages){
+                    maxId = msg.id;
+                    const d = msg.message;
+                    const key = `${d.testId}:${d.variantId}:${d.eventType}`;
+                    let bucket = agg.get(key);
+                    if (!bucket) {
+                        bucket = {
+                            count: 0,
+                            visitors: new Set()
+                        };
+                        agg.set(key, bucket);
+                    }
+                    bucket.count++;
+                    bucket.visitors.add(d.visitorId);
+                }
+                const now = new Date();
+                const periodStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+                const periodEnd = new Date(periodStart.getTime() + 86400000);
+                for (const [key, bucket] of agg){
+                    const [tId, variantId, eventType] = key.split(':');
+                    const id = newId('abTestAgg');
+                    await db.execute(drizzleOrm.sql`
+            INSERT INTO cms.ab_test_aggregations
+              (id, test_id, variant_id, event_type, count, unique_visitors, period_start, period_end, updated_at)
+            VALUES
+              (${id}, ${tId}, ${variantId}, ${eventType}, ${bucket.count}, ${bucket.visitors.size}, ${periodStart}, ${periodEnd}, NOW())
+            ON CONFLICT (test_id, variant_id, event_type, period_start) DO UPDATE SET
+              count = cms.ab_test_aggregations.count + EXCLUDED.count,
+              unique_visitors = GREATEST(cms.ab_test_aggregations.unique_visitors, EXCLUDED.unique_visitors),
+              updated_at = NOW()
+          `);
+                    totalFlushed += bucket.count;
+                }
+                await redis.set(cursorKey, maxId);
+                await redis.xtrim(streamKey, {
+                    strategy: 'MINID',
+                    threshold: maxId
+                });
+            }
+            return {
+                flushed: totalFlushed
+            };
+        }
+    };
+    return adapter;
+}
+
+exports.upstashAnalytics = upstashAnalytics;