@createcms/core 0.1.1

package/dist/plugins/ab-test/client.d.cts

@@ -0,0 +1,233 @@
+import { WritableAtom } from 'nanostores';
+import { ConsentState } from '../consent/index.cjs';
+export { ConsentPurpose, ConsentSignal, ConsentState } from '../consent/index.cjs';
+
+type CMSFetch = (path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: unknown;
+    /**
+     * Forwarded to the underlying `fetch` (better-call → @better-fetch → native
+     * `fetch`). Set for fire-and-forget analytics beacons (the A/B event ingest)
+     * so the POST is NOT cancelled when the page unloads/navigates mid-request.
+     */
+    keepalive?: boolean;
+}) => Promise<unknown>;
+interface CMSClientStore {
+    notify: (signal: string) => void;
+    listen: (signal: string, listener: () => void) => void;
+    atoms: Record<string, WritableAtom<unknown>>;
+}
+
+type AggregatedVariantResult = {
+    variantId: string;
+    variantName: string;
+    impressions: number;
+    conversions: number;
+    uniqueVisitors: number;
+    conversionRate: number;
+    /**
+     * Funnel (M4): total distinct interaction ids (each <TrackedForm> submit mints
+     * one) = the attempts. completionRate = distinct interactions that reached the
+     * goal event / attempts (computed by getResults when a goal is set).
+     */
+    attempts: number;
+    completionRate: number;
+    eventBreakdown: Record<string, {
+        count: number;
+        uniqueVisitors: number;
+        distinctInteractions: number;
+    }>;
+};
+type AggregatedResults = {
+    testId: string;
+    variants: AggregatedVariantResult[];
+    totalImpressions: number;
+    totalConversions: number;
+};
+
+/**
+ * The client-side event a sink receives. Decoupled from the server `CMSEvent`
+ * (no `timestamp`/storage `id` — those are minted server-side): this is what the
+ * browser knows at fire time.
+ */
+type ClientCMSEvent = {
+    /** Canonical event name, e.g. `'impression' | 'conversion' | 'form_submit'`. */
+    name: string;
+    /**
+     * A/B attribution by the SERVER-served branch (Pattern A: the variant came
+     * from the URL). `branchId` is what the client has; the store leg resolves it
+     * to a `variantId` server-side. Absent for non-A/B analytics events.
+     */
+    ab?: {
+        testId: string;
+        branchId?: string;
+        variantId?: string;
+    };
+    /** Identity — only on the consent-gated unique-visitor path; never anonymous. */
+    visitorId?: string;
+    /** True when no identifier is attached (the consent-free aggregate path). */
+    anonymous: boolean;
+    /** Originating functional block instance (the `trackingId` + block type). */
+    source?: {
+        handle?: string;
+        type?: string;
+    };
+    /** Funnel grouping id (M4): shared by the attempt + success legs of one interaction. */
+    interactionId?: string;
+    /** GA4 stitching ids (M5): set only when consent is granted; the store leg
+     *  forwards them so the server-MP can attribute the hit. */
+    transport?: {
+        clientId?: string;
+        sessionId?: string;
+        engagementTimeMsec?: number;
+    };
+    /**
+     * Consent Mode v2 state at fire time (M5). Stamped ALONGSIDE `transport` (only
+     * when analytics_storage is granted), so the store leg can relay it to the
+     * server, where `buildGa4Payload` needs it to authorize the server-MP forward.
+     * Absent on the consent-free anonymous path — its absence is exactly what keeps
+     * the server's denied-consent guard from dropping the anonymous aggregate count.
+     */
+    consent?: ConsentState;
+    /** Scalar event params (GA4 wire params). */
+    params?: Record<string, string | number | boolean>;
+    metadata?: Record<string, unknown>;
+};
+
+type ABTestContext = {
+    key: string;
+    anonymous?: boolean;
+};
+type CachedAssignment = {
+    variantId: string;
+    branchId: string;
+    assignedAt: number;
+};
+type ABTestClientOptions = {
+    /**
+     * Drop the client-side dataLayer/GTM sink (M5). Enable this when the SAME
+     * goals are forwarded server-side via the plugin's `ga4` (server-MP) config —
+     * otherwise GA4 double-counts (one hit from the browser push + one from the
+     * server). With it set, the consent-free anonymous A/B store leg still fires;
+     * only the `window.dataLayer.push` leg is removed.
+     */
+    disableDataLayerSink?: boolean;
+};
+declare function abTestClient(options?: ABTestClientOptions): {
+    id: "abTest";
+    $ERROR_CODES: {
+        readonly AB_TEST_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test not found";
+        };
+        readonly AB_TEST_INVALID_STATUS: {
+            readonly status: 400;
+            readonly message: "Invalid status transition for this A/B test";
+        };
+        readonly AB_TEST_WEIGHTS_INVALID: {
+            readonly status: 400;
+            readonly message: "Variant weights must sum to 100";
+        };
+        readonly AB_TEST_DUPLICATE_RUNNING: {
+            readonly status: 409;
+            readonly message: "Another test is already running for this root";
+        };
+        readonly AB_TEST_CROSS_EMBED_CONFLICT: {
+            readonly status: 409;
+            readonly message: "Cannot run: a co-rendering root (an embedded reusable block or its host page) already has a running test — at most one A/B axis may vary per render";
+        };
+        readonly AB_TEST_BRANCH_NOT_PUBLISHED: {
+            readonly status: 400;
+            readonly message: "All variant branches must be published";
+        };
+        readonly AB_TEST_NO_CONTEXT: {
+            readonly status: 400;
+            readonly message: "No visitor context set. Call identify() first.";
+        };
+        readonly AB_TEST_FLUSH_NOT_SUPPORTED: {
+            readonly status: 400;
+            readonly message: "Flush is not supported by the current analytics adapter";
+        };
+        readonly AB_TEST_VARIANT_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test variant not found";
+        };
+        readonly AB_TEST_TRACKING_ID_MISSING: {
+            readonly status: 400;
+            readonly message: "A functional block (one that declares events) is missing its trackingId — every such block must have a non-empty trackingId before the branch can be published";
+        };
+        readonly AB_TEST_TRACKING_ID_DUPLICATE: {
+            readonly status: 400;
+            readonly message: "Duplicate trackingId in this branch — each functional block must have a unique trackingId";
+        };
+        readonly AB_TEST_TRACKING_ID_DRIFT: {
+            readonly status: 409;
+            readonly message: "trackingId drift across A/B variant branches — the set of functional trackingIds must be identical across all variant branches of a root, so a chosen goal exists in every arm";
+        };
+    };
+    init(_$fetch: CMSFetch, _$store: CMSClientStore): Promise<{
+        context: {
+            [x: string]: null;
+        };
+    }>;
+    getActions($fetch: CMSFetch, _$store: CMSClientStore, baseURL: string): {
+        abTest: {
+            /**
+             * Tell the CMS about the visitor's consent (Consent Mode v2) — a real
+             * decision (treated like a Consent Mode `update`). Optional: the gate
+             * also auto-reads Consent Mode commands off the dataLayer. That
+             * auto-read is best-effort (a `push`-hook fast path plus a re-scan
+             * poll); when running GTM, calling this from the CMP's Consent Mode
+             * update callback is the most reliable path.
+             */
+            setConsent(consent: Partial<ConsentState>): void;
+            /** Read the current resolved consent state. */
+            getConsent(): ConsentState;
+            /**
+             * Report the impression for a SERVER-rendered variant (AB_FANOUT
+             * Pattern A). Call with the served branch (the `/<branchId>/` URL
+             * segment). ANONYMOUS + consent-free: sends no visitor id, not
+             * consent-gated, deduped per session via sessionStorage. Reach it from
+             * the variant route via {@link useImpression}.
+             */
+            recordImpression: (testId: string, branchId: string) => void;
+            /**
+             * React hook: fire the Pattern A impression once per (testId, branchId)
+             * on mount. Render a tiny `'use client'` beacon from the variant-coded
+             * route: `cmsClient.abTest.useImpression(testId, branchId)`.
+             */
+            useImpression(testId: string, branchId: string): void;
+            /**
+             * Fire a raw client event through the M3a sink pipeline (the SAME
+             * sinks + consent gate as recordImpression — so consent state never
+             * diverges). The M3c `<TrackingRuntimeProvider>` wires this as its
+             * `dispatch`; functional blocks reach it via `useTrackedBlock().fire`.
+             * Anonymous aggregate legs are consent-free; the GA4/gtm leg is gated.
+             */
+            dispatchEvent(event: ClientCMSEvent): void;
+            identify(ctx: ABTestContext): void;
+            getVariant(testId: string): Promise<CachedAssignment>;
+            reset(): void;
+            /**
+             * React hook for live dashboard results.
+             * Connects to the auto-registered realtime SSE route.
+             */
+            useLiveResults(opts: {
+                testId: string;
+                initial: AggregatedResults;
+            }): {
+                results: AggregatedResults;
+                isLive: boolean;
+            };
+        };
+    };
+    pathMethods: {
+        '/abTest/assignVariant': "POST";
+        '/abTest/trackEvent': "POST";
+        '/abTest/getResults': "GET";
+    };
+};
+
+export { abTestClient };
+export type { ABTestClientOptions };

package/dist/plugins/ab-test/client.d.ts

@@ -0,0 +1,233 @@
+import { WritableAtom } from 'nanostores';
+import { ConsentState } from '../consent/index.js';
+export { ConsentPurpose, ConsentSignal, ConsentState } from '../consent/index.js';
+
+type CMSFetch = (path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: unknown;
+    /**
+     * Forwarded to the underlying `fetch` (better-call → @better-fetch → native
+     * `fetch`). Set for fire-and-forget analytics beacons (the A/B event ingest)
+     * so the POST is NOT cancelled when the page unloads/navigates mid-request.
+     */
+    keepalive?: boolean;
+}) => Promise<unknown>;
+interface CMSClientStore {
+    notify: (signal: string) => void;
+    listen: (signal: string, listener: () => void) => void;
+    atoms: Record<string, WritableAtom<unknown>>;
+}
+
+type AggregatedVariantResult = {
+    variantId: string;
+    variantName: string;
+    impressions: number;
+    conversions: number;
+    uniqueVisitors: number;
+    conversionRate: number;
+    /**
+     * Funnel (M4): total distinct interaction ids (each <TrackedForm> submit mints
+     * one) = the attempts. completionRate = distinct interactions that reached the
+     * goal event / attempts (computed by getResults when a goal is set).
+     */
+    attempts: number;
+    completionRate: number;
+    eventBreakdown: Record<string, {
+        count: number;
+        uniqueVisitors: number;
+        distinctInteractions: number;
+    }>;
+};
+type AggregatedResults = {
+    testId: string;
+    variants: AggregatedVariantResult[];
+    totalImpressions: number;
+    totalConversions: number;
+};
+
+/**
+ * The client-side event a sink receives. Decoupled from the server `CMSEvent`
+ * (no `timestamp`/storage `id` — those are minted server-side): this is what the
+ * browser knows at fire time.
+ */
+type ClientCMSEvent = {
+    /** Canonical event name, e.g. `'impression' | 'conversion' | 'form_submit'`. */
+    name: string;
+    /**
+     * A/B attribution by the SERVER-served branch (Pattern A: the variant came
+     * from the URL). `branchId` is what the client has; the store leg resolves it
+     * to a `variantId` server-side. Absent for non-A/B analytics events.
+     */
+    ab?: {
+        testId: string;
+        branchId?: string;
+        variantId?: string;
+    };
+    /** Identity — only on the consent-gated unique-visitor path; never anonymous. */
+    visitorId?: string;
+    /** True when no identifier is attached (the consent-free aggregate path). */
+    anonymous: boolean;
+    /** Originating functional block instance (the `trackingId` + block type). */
+    source?: {
+        handle?: string;
+        type?: string;
+    };
+    /** Funnel grouping id (M4): shared by the attempt + success legs of one interaction. */
+    interactionId?: string;
+    /** GA4 stitching ids (M5): set only when consent is granted; the store leg
+     *  forwards them so the server-MP can attribute the hit. */
+    transport?: {
+        clientId?: string;
+        sessionId?: string;
+        engagementTimeMsec?: number;
+    };
+    /**
+     * Consent Mode v2 state at fire time (M5). Stamped ALONGSIDE `transport` (only
+     * when analytics_storage is granted), so the store leg can relay it to the
+     * server, where `buildGa4Payload` needs it to authorize the server-MP forward.
+     * Absent on the consent-free anonymous path — its absence is exactly what keeps
+     * the server's denied-consent guard from dropping the anonymous aggregate count.
+     */
+    consent?: ConsentState;
+    /** Scalar event params (GA4 wire params). */
+    params?: Record<string, string | number | boolean>;
+    metadata?: Record<string, unknown>;
+};
+
+type ABTestContext = {
+    key: string;
+    anonymous?: boolean;
+};
+type CachedAssignment = {
+    variantId: string;
+    branchId: string;
+    assignedAt: number;
+};
+type ABTestClientOptions = {
+    /**
+     * Drop the client-side dataLayer/GTM sink (M5). Enable this when the SAME
+     * goals are forwarded server-side via the plugin's `ga4` (server-MP) config —
+     * otherwise GA4 double-counts (one hit from the browser push + one from the
+     * server). With it set, the consent-free anonymous A/B store leg still fires;
+     * only the `window.dataLayer.push` leg is removed.
+     */
+    disableDataLayerSink?: boolean;
+};
+declare function abTestClient(options?: ABTestClientOptions): {
+    id: "abTest";
+    $ERROR_CODES: {
+        readonly AB_TEST_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test not found";
+        };
+        readonly AB_TEST_INVALID_STATUS: {
+            readonly status: 400;
+            readonly message: "Invalid status transition for this A/B test";
+        };
+        readonly AB_TEST_WEIGHTS_INVALID: {
+            readonly status: 400;
+            readonly message: "Variant weights must sum to 100";
+        };
+        readonly AB_TEST_DUPLICATE_RUNNING: {
+            readonly status: 409;
+            readonly message: "Another test is already running for this root";
+        };
+        readonly AB_TEST_CROSS_EMBED_CONFLICT: {
+            readonly status: 409;
+            readonly message: "Cannot run: a co-rendering root (an embedded reusable block or its host page) already has a running test — at most one A/B axis may vary per render";
+        };
+        readonly AB_TEST_BRANCH_NOT_PUBLISHED: {
+            readonly status: 400;
+            readonly message: "All variant branches must be published";
+        };
+        readonly AB_TEST_NO_CONTEXT: {
+            readonly status: 400;
+            readonly message: "No visitor context set. Call identify() first.";
+        };
+        readonly AB_TEST_FLUSH_NOT_SUPPORTED: {
+            readonly status: 400;
+            readonly message: "Flush is not supported by the current analytics adapter";
+        };
+        readonly AB_TEST_VARIANT_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test variant not found";
+        };
+        readonly AB_TEST_TRACKING_ID_MISSING: {
+            readonly status: 400;
+            readonly message: "A functional block (one that declares events) is missing its trackingId — every such block must have a non-empty trackingId before the branch can be published";
+        };
+        readonly AB_TEST_TRACKING_ID_DUPLICATE: {
+            readonly status: 400;
+            readonly message: "Duplicate trackingId in this branch — each functional block must have a unique trackingId";
+        };
+        readonly AB_TEST_TRACKING_ID_DRIFT: {
+            readonly status: 409;
+            readonly message: "trackingId drift across A/B variant branches — the set of functional trackingIds must be identical across all variant branches of a root, so a chosen goal exists in every arm";
+        };
+    };
+    init(_$fetch: CMSFetch, _$store: CMSClientStore): Promise<{
+        context: {
+            [x: string]: null;
+        };
+    }>;
+    getActions($fetch: CMSFetch, _$store: CMSClientStore, baseURL: string): {
+        abTest: {
+            /**
+             * Tell the CMS about the visitor's consent (Consent Mode v2) — a real
+             * decision (treated like a Consent Mode `update`). Optional: the gate
+             * also auto-reads Consent Mode commands off the dataLayer. That
+             * auto-read is best-effort (a `push`-hook fast path plus a re-scan
+             * poll); when running GTM, calling this from the CMP's Consent Mode
+             * update callback is the most reliable path.
+             */
+            setConsent(consent: Partial<ConsentState>): void;
+            /** Read the current resolved consent state. */
+            getConsent(): ConsentState;
+            /**
+             * Report the impression for a SERVER-rendered variant (AB_FANOUT
+             * Pattern A). Call with the served branch (the `/<branchId>/` URL
+             * segment). ANONYMOUS + consent-free: sends no visitor id, not
+             * consent-gated, deduped per session via sessionStorage. Reach it from
+             * the variant route via {@link useImpression}.
+             */
+            recordImpression: (testId: string, branchId: string) => void;
+            /**
+             * React hook: fire the Pattern A impression once per (testId, branchId)
+             * on mount. Render a tiny `'use client'` beacon from the variant-coded
+             * route: `cmsClient.abTest.useImpression(testId, branchId)`.
+             */
+            useImpression(testId: string, branchId: string): void;
+            /**
+             * Fire a raw client event through the M3a sink pipeline (the SAME
+             * sinks + consent gate as recordImpression — so consent state never
+             * diverges). The M3c `<TrackingRuntimeProvider>` wires this as its
+             * `dispatch`; functional blocks reach it via `useTrackedBlock().fire`.
+             * Anonymous aggregate legs are consent-free; the GA4/gtm leg is gated.
+             */
+            dispatchEvent(event: ClientCMSEvent): void;
+            identify(ctx: ABTestContext): void;
+            getVariant(testId: string): Promise<CachedAssignment>;
+            reset(): void;
+            /**
+             * React hook for live dashboard results.
+             * Connects to the auto-registered realtime SSE route.
+             */
+            useLiveResults(opts: {
+                testId: string;
+                initial: AggregatedResults;
+            }): {
+                results: AggregatedResults;
+                isLive: boolean;
+            };
+        };
+    };
+    pathMethods: {
+        '/abTest/assignVariant': "POST";
+        '/abTest/trackEvent': "POST";
+        '/abTest/getResults': "GET";
+    };
+};
+
+export { abTestClient };
+export type { ABTestClientOptions };