@createcms/core 0.1.1

package/dist/plugins/consent/index.js

@@ -0,0 +1,258 @@
+// ============================================================================
+// 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
+    };
+}
+
+export { CONSENT_WAIT_MS, DENIED_ALL, consent, createConsentGate, parseConsentEntries, parseConsentEntry, resolveVisitorKey, startConsentAutoRead };