@createcms/core 0.1.1

package/dist/plugins/consent/client.js

@@ -0,0 +1,313 @@
+import { useState, useEffect } from 'react';
+
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default-deny: nothing is granted until a CMP / Consent Mode signal says so. */ const DENIED_ALL = {
+    analytics_storage: 'denied',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied'
+};
+/**
+ * How long (ms) to buffer events before resolving the gate when no consent
+ * DECISION has arrived yet — the Consent Mode `wait_for_update` window. Render
+ * is NEVER blocked on this; only event emission waits.
+ */ const CONSENT_WAIT_MS = 2000;
+// ============================================================================
+// Pure: parse Consent Mode v2 entries off a dataLayer
+// ============================================================================
+const SIGNALS = [
+    'analytics_storage',
+    'ad_storage',
+    'ad_user_data',
+    'ad_personalization'
+];
+function isSignal(value) {
+    return value === 'granted' || value === 'denied';
+}
+/**
+ * Extracts the mode + partial {@link ConsentState} from a single dataLayer entry
+ * IF it is a Consent Mode command (`gtag('consent','default'|'update',{...})`,
+ * which lands on the dataLayer as an arguments-like `['consent', mode, params]`).
+ * Returns `null` for any non-consent entry. The `mode` matters: a `default` only
+ * seeds state, while an `update` is the user's decision (see {@link ConsentGate}).
+ */ function parseConsentEntry(entry) {
+    if (entry == null || typeof entry !== 'object') return null;
+    // Works for both real arrays and the arguments-objects gtag pushes.
+    const indexed = entry;
+    if (indexed[0] !== 'consent') return null;
+    const mode = indexed[1];
+    if (mode !== 'default' && mode !== 'update') return null;
+    const params = indexed[2];
+    if (params == null || typeof params !== 'object') return null;
+    const out = {};
+    for (const signal of SIGNALS){
+        const v = params[signal];
+        if (isSignal(v)) out[signal] = v;
+    }
+    return Object.keys(out).length > 0 ? {
+        mode,
+        state: out
+    } : null;
+}
+function createConsentGate(initial = DENIED_ALL) {
+    let state = {
+        ...initial
+    };
+    let resolved = false;
+    let buffer = [];
+    const listeners = new Set();
+    const notify = ()=>{
+        for (const l of listeners)l({
+            ...state
+        }, resolved);
+    };
+    const drain = ()=>{
+        if (!resolved) return;
+        const pending = buffer;
+        buffer = [];
+        const granted = state.analytics_storage === 'granted';
+        for (const item of pending){
+            if (granted) item.effect();
+            else item.onDrop?.();
+        }
+    };
+    return {
+        getState () {
+            return {
+                ...state
+            };
+        },
+        isGranted (purpose) {
+            return state[purpose] === 'granted';
+        },
+        isResolved () {
+            return resolved;
+        },
+        applyDefault (update) {
+            state = {
+                ...state,
+                ...update
+            };
+            notify();
+        },
+        applyUpdate (update) {
+            state = {
+                ...state,
+                ...update
+            };
+            // Only a decision about analytics (or one arriving after we've already
+            // resolved) drains. A partial update touching only ad_* keeps buffering.
+            if ('analytics_storage' in update || resolved) {
+                resolved = true;
+                notify();
+                drain();
+            } else {
+                notify();
+            }
+        },
+        resolve () {
+            if (resolved) return;
+            resolved = true;
+            notify();
+            drain();
+        },
+        run (effect, onDrop) {
+            if (!resolved) {
+                buffer.push({
+                    effect,
+                    onDrop
+                });
+                return;
+            }
+            if (state.analytics_storage === 'granted') effect();
+            else onDrop?.();
+        },
+        onChange (listener) {
+            listeners.add(listener);
+            return ()=>listeners.delete(listener);
+        },
+        reset () {
+            const pending = buffer;
+            buffer = [];
+            state = {
+                ...DENIED_ALL
+            };
+            resolved = true;
+            for (const item of pending)item.onDrop?.();
+            notify();
+        }
+    };
+}
+
+function routeConsentEntry(gate, entry) {
+    const parsed = parseConsentEntry(entry);
+    if (!parsed) return;
+    // A `default` only seeds state; an `update` (or explicit setConsent) is the
+    // decision that may resolve the gate.
+    if (parsed.mode === 'default') gate.applyDefault(parsed.state);
+    else gate.applyUpdate(parsed.state);
+}
+/**
+ * Zero-config consent: reads Consent Mode v2 commands off `window.dataLayer`
+ * (already-present `default`/`update` entries and future pushes) and feeds the
+ * gate. Resilient to GTM/gtag.js loading LATER — which reassigns `dataLayer` /
+ * its `push` and would discard an in-place patch — via a short re-scan poll over
+ * the wait window that re-reads `window.dataLayer` fresh each tick (and re-scans
+ * from 0 if the array was replaced). The `push` patch is only a fast path. When
+ * running GTM, driving consent explicitly via `setConsent` from the CMP's
+ * Consent Mode update callback is the most reliable path.
+ */ function startConsentAutoRead(gate) {
+    if (typeof window === 'undefined') return;
+    const w = window;
+    let scannedArray = null;
+    let idx = 0;
+    const scan = ()=>{
+        const dl = w.dataLayer = w.dataLayer || [];
+        if (dl !== scannedArray) {
+            // First scan, or the host (GTM) replaced the array — re-read from 0.
+            scannedArray = dl;
+            idx = 0;
+        }
+        for(; idx < dl.length; idx++)routeConsentEntry(gate, dl[idx]);
+        // Best-effort fast path: observe pushes on the current array (once).
+        if (!dl.__cmsConsentObserved) {
+            dl.__cmsConsentObserved = true;
+            const originalPush = dl.push.bind(dl);
+            dl.push = (...args)=>{
+                const ret = originalPush(...args);
+                try {
+                    for (const arg of args)routeConsentEntry(gate, arg);
+                } catch  {
+                // never let consent observation break a host dataLayer push
+                }
+                return ret;
+            };
+        }
+    };
+    scan();
+    // Poll fallback: survives GTM clobbering the push hook / replacing the array.
+    const interval = setInterval(()=>{
+        if (gate.isResolved()) {
+            clearInterval(interval);
+            return;
+        }
+        try {
+            scan();
+        } catch  {
+        // ignore
+        }
+    }, 300);
+}
+
+const PLUGIN_ID = 'consent';
+/** Shallow-equal two consent states across the four Consent Mode v2 signals. */ function sameConsent(a, b) {
+    return a.analytics_storage === b.analytics_storage && a.ad_storage === b.ad_storage && a.ad_user_data === b.ad_user_data && a.ad_personalization === b.ad_personalization;
+}
+/**
+ * Client plugin that exposes the generic consent gate under its own namespace,
+ * decoupled from A/B. Lets any consumer gate side effects or rendering of
+ * embedded third-party content (YouTube, Maps, Vimeo) behind Google Consent
+ * Mode v2 — render only after the visitor consents.
+ *
+ * The gate is created once per client (closed over in `getActions`, like
+ * `abTest.useLiveResults`), auto-reads Consent Mode commands off the dataLayer,
+ * and resolves after a short wait-window. Reached via the client proxy:
+ *
+ * ```tsx
+ * import { consentClient } from '@createcms/core/plugins/consent/client';
+ *
+ * const client = createCMSClient<typeof cms>({
+ *   baseURL: '/api/cms',
+ *   plugins: [consentClient()],
+ * });
+ *
+ * // Drive consent from a CMP callback:
+ * client.consent.setConsent({ ad_storage: 'granted' });
+ *
+ * // Gate an embed (component bound to this client's gate):
+ * const { ConsentGate } = client.consent;
+ * <ConsentGate purpose="ad_storage" fallback={<p>Bitte Cookies akzeptieren.</p>}>
+ *   <iframe src="https://www.youtube.com/embed/..." />
+ * </ConsentGate>
+ * ```
+ */ function consentClient() {
+    return {
+        id: PLUGIN_ID,
+        getActions (_$fetch, _$store, _baseURL) {
+            const gate = createConsentGate();
+            // Zero-config Consent Mode read + a wait-window fallback so a denied
+            // default doesn't strand the gate. Render never waits on this; only the
+            // gate's buffered side effects do.
+            startConsentAutoRead(gate);
+            if (typeof window !== 'undefined') {
+                setTimeout(()=>gate.resolve(), CONSENT_WAIT_MS);
+            }
+            /** React hook: subscribe to the gate and re-render on every change. */ function useConsentState() {
+                const [snap, setSnap] = useState(()=>({
+                        state: gate.getState(),
+                        resolved: gate.isResolved()
+                    }));
+                useEffect(()=>{
+                    // Re-sync in case a decision landed in the render->effect gap. The
+                    // functional updater returns `prev` when nothing actually changed so
+                    // React bails out via Object.is — no wasted render on the common path.
+                    setSnap((prev)=>{
+                        const state = gate.getState();
+                        const resolved = gate.isResolved();
+                        return prev.resolved === resolved && sameConsent(prev.state, state) ? prev : {
+                            state,
+                            resolved
+                        };
+                    });
+                    return gate.onChange((state, resolved)=>setSnap({
+                            state,
+                            resolved
+                        }));
+                }, []);
+                return {
+                    state: snap.state,
+                    resolved: snap.resolved,
+                    isGranted: (purpose)=>snap.state[purpose] === 'granted'
+                };
+            }
+            /** Render wrapper bound to this client's gate (default-deny). */ function ConsentGate(props) {
+                const { isGranted } = useConsentState();
+                return isGranted(props.purpose) ? props.children : props.fallback ?? null;
+            }
+            return {
+                consent: {
+                    /**
+           * 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; when running
+           * GTM, calling this from the CMP's update callback is the most reliable
+           * path.
+           */ setConsent (consent) {
+                        gate.applyUpdate(consent);
+                    },
+                    /** Read the current consent state. */ getConsent () {
+                        return gate.getState();
+                    },
+                    /** Whether a given Consent Mode v2 signal is currently granted. */ isGranted (purpose) {
+                        return gate.isGranted(purpose);
+                    },
+                    /** True once a real decision arrived or the wait-window elapsed. */ isResolved () {
+                        return gate.isResolved();
+                    },
+                    /** Subscribe to consent changes. Returns an unsubscribe function. */ onChange (listener) {
+                        return gate.onChange(listener);
+                    },
+                    /** Revoke consent in-session: back to default-deny. */ reset () {
+                        gate.reset();
+                    },
+                    useConsentState,
+                    ConsentGate
+                }
+            };
+        }
+    };
+}
+
+export { consentClient };

package/dist/plugins/consent/index.cjs

@@ -0,0 +1,267 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default-deny: nothing is granted until a CMP / Consent Mode signal says so. */ const DENIED_ALL = {
+    analytics_storage: 'denied',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied'
+};
+/**
+ * How long (ms) to buffer events before resolving the gate when no consent
+ * DECISION has arrived yet — the Consent Mode `wait_for_update` window. Render
+ * is NEVER blocked on this; only event emission waits.
+ */ const CONSENT_WAIT_MS = 2000;
+// ============================================================================
+// Pure: parse Consent Mode v2 entries off a dataLayer
+// ============================================================================
+const SIGNALS = [
+    'analytics_storage',
+    'ad_storage',
+    'ad_user_data',
+    'ad_personalization'
+];
+function isSignal(value) {
+    return value === 'granted' || value === 'denied';
+}
+/**
+ * Extracts the mode + partial {@link ConsentState} from a single dataLayer entry
+ * IF it is a Consent Mode command (`gtag('consent','default'|'update',{...})`,
+ * which lands on the dataLayer as an arguments-like `['consent', mode, params]`).
+ * Returns `null` for any non-consent entry. The `mode` matters: a `default` only
+ * seeds state, while an `update` is the user's decision (see {@link ConsentGate}).
+ */ function parseConsentEntry(entry) {
+    if (entry == null || typeof entry !== 'object') return null;
+    // Works for both real arrays and the arguments-objects gtag pushes.
+    const indexed = entry;
+    if (indexed[0] !== 'consent') return null;
+    const mode = indexed[1];
+    if (mode !== 'default' && mode !== 'update') return null;
+    const params = indexed[2];
+    if (params == null || typeof params !== 'object') return null;
+    const out = {};
+    for (const signal of SIGNALS){
+        const v = params[signal];
+        if (isSignal(v)) out[signal] = v;
+    }
+    return Object.keys(out).length > 0 ? {
+        mode,
+        state: out
+    } : null;
+}
+/** Parses every Consent Mode command on a dataLayer, in order. */ function parseConsentEntries(dataLayer) {
+    const out = [];
+    for (const entry of dataLayer){
+        const parsed = parseConsentEntry(entry);
+        if (parsed) out.push(parsed);
+    }
+    return out;
+}
+function createConsentGate(initial = DENIED_ALL) {
+    let state = {
+        ...initial
+    };
+    let resolved = false;
+    let buffer = [];
+    const listeners = new Set();
+    const notify = ()=>{
+        for (const l of listeners)l({
+            ...state
+        }, resolved);
+    };
+    const drain = ()=>{
+        if (!resolved) return;
+        const pending = buffer;
+        buffer = [];
+        const granted = state.analytics_storage === 'granted';
+        for (const item of pending){
+            if (granted) item.effect();
+            else item.onDrop?.();
+        }
+    };
+    return {
+        getState () {
+            return {
+                ...state
+            };
+        },
+        isGranted (purpose) {
+            return state[purpose] === 'granted';
+        },
+        isResolved () {
+            return resolved;
+        },
+        applyDefault (update) {
+            state = {
+                ...state,
+                ...update
+            };
+            notify();
+        },
+        applyUpdate (update) {
+            state = {
+                ...state,
+                ...update
+            };
+            // Only a decision about analytics (or one arriving after we've already
+            // resolved) drains. A partial update touching only ad_* keeps buffering.
+            if ('analytics_storage' in update || resolved) {
+                resolved = true;
+                notify();
+                drain();
+            } else {
+                notify();
+            }
+        },
+        resolve () {
+            if (resolved) return;
+            resolved = true;
+            notify();
+            drain();
+        },
+        run (effect, onDrop) {
+            if (!resolved) {
+                buffer.push({
+                    effect,
+                    onDrop
+                });
+                return;
+            }
+            if (state.analytics_storage === 'granted') effect();
+            else onDrop?.();
+        },
+        onChange (listener) {
+            listeners.add(listener);
+            return ()=>listeners.delete(listener);
+        },
+        reset () {
+            const pending = buffer;
+            buffer = [];
+            state = {
+                ...DENIED_ALL
+            };
+            resolved = true;
+            for (const item of pending)item.onDrop?.();
+            notify();
+        }
+    };
+}
+// ============================================================================
+// Pure: visitor-key resolution (consent-gated persistence)
+// ============================================================================
+/**
+ * Decides which visitor key to use and whether it may be persisted. Before
+ * `analytics_storage` is granted, the key is in-memory only (page lifetime, no
+ * device storage). On grant, an existing cookie wins; otherwise the in-memory
+ * key is promoted to the cookie so a buffered impression and later events share
+ * one identity.
+ */ function resolveVisitorKey(opts) {
+    if (opts.granted) {
+        if (opts.cookieKey) {
+            return {
+                key: opts.cookieKey,
+                persist: false,
+                memKey: opts.cookieKey
+            };
+        }
+        const key = opts.memKey ?? opts.generate();
+        return {
+            key,
+            persist: true,
+            memKey: key
+        };
+    }
+    const key = opts.memKey ?? opts.generate();
+    return {
+        key,
+        persist: false,
+        memKey: key
+    };
+}
+
+function routeConsentEntry(gate, entry) {
+    const parsed = parseConsentEntry(entry);
+    if (!parsed) return;
+    // A `default` only seeds state; an `update` (or explicit setConsent) is the
+    // decision that may resolve the gate.
+    if (parsed.mode === 'default') gate.applyDefault(parsed.state);
+    else gate.applyUpdate(parsed.state);
+}
+/**
+ * Zero-config consent: reads Consent Mode v2 commands off `window.dataLayer`
+ * (already-present `default`/`update` entries and future pushes) and feeds the
+ * gate. Resilient to GTM/gtag.js loading LATER — which reassigns `dataLayer` /
+ * its `push` and would discard an in-place patch — via a short re-scan poll over
+ * the wait window that re-reads `window.dataLayer` fresh each tick (and re-scans
+ * from 0 if the array was replaced). The `push` patch is only a fast path. When
+ * running GTM, driving consent explicitly via `setConsent` from the CMP's
+ * Consent Mode update callback is the most reliable path.
+ */ function startConsentAutoRead(gate) {
+    if (typeof window === 'undefined') return;
+    const w = window;
+    let scannedArray = null;
+    let idx = 0;
+    const scan = ()=>{
+        const dl = w.dataLayer = w.dataLayer || [];
+        if (dl !== scannedArray) {
+            // First scan, or the host (GTM) replaced the array — re-read from 0.
+            scannedArray = dl;
+            idx = 0;
+        }
+        for(; idx < dl.length; idx++)routeConsentEntry(gate, dl[idx]);
+        // Best-effort fast path: observe pushes on the current array (once).
+        if (!dl.__cmsConsentObserved) {
+            dl.__cmsConsentObserved = true;
+            const originalPush = dl.push.bind(dl);
+            dl.push = (...args)=>{
+                const ret = originalPush(...args);
+                try {
+                    for (const arg of args)routeConsentEntry(gate, arg);
+                } catch  {
+                // never let consent observation break a host dataLayer push
+                }
+                return ret;
+            };
+        }
+    };
+    scan();
+    // Poll fallback: survives GTM clobbering the push hook / replacing the array.
+    const interval = setInterval(()=>{
+        if (gate.isResolved()) {
+            clearInterval(interval);
+            return;
+        }
+        try {
+            scan();
+        } catch  {
+        // ignore
+        }
+    }, 300);
+}
+
+const PLUGIN_ID = 'consent';
+/**
+ * The consent plugin. Owns the generic Google Consent Mode v2 infrastructure
+ * (the buffer-then-flush gate, the dataLayer/CMP auto-read, the state model)
+ * that any consumer can ride — A/B tracking, analytics sinks, or consent-gated
+ * rendering of embedded third-party content.
+ *
+ * Server-side it is a marker plugin (no schema/endpoints/hooks): consent is a
+ * client-side concern today. The client capability (gate + setConsent/getConsent
+ * + the <ConsentGate> render wrapper) is exposed via the client entry.
+ */ function consent() {
+    return {
+        id: PLUGIN_ID
+    };
+}
+
+exports.CONSENT_WAIT_MS = CONSENT_WAIT_MS;
+exports.DENIED_ALL = DENIED_ALL;
+exports.consent = consent;
+exports.createConsentGate = createConsentGate;
+exports.parseConsentEntries = parseConsentEntries;
+exports.parseConsentEntry = parseConsentEntry;
+exports.resolveVisitorKey = resolveVisitorKey;
+exports.startConsentAutoRead = startConsentAutoRead;