@el7ven/cookie-kit 0.3.1 → 0.3.3

package/src/providers/GoogleConsentModeProvider.js

@@ -0,0 +1,278 @@
+/**
+ * Google Consent Mode v2 Provider
+ * Required for Google Ads, GA4, and GTM compliance
+ * @module GoogleConsentModeProvider
+ * @see https://developers.google.com/tag-platform/security/guides/consent
+ */
+
+export class GoogleConsentModeProvider {
+  constructor(consentManager, config = {}) {
+    this.consentManager = consentManager
+    this.config = {
+      // Category mapping: CMP category → Google consent type
+      categoryMapping: {
+        analytics: ['analytics_storage'],
+        marketing: ['ad_storage', 'ad_user_data', 'ad_personalization'],
+        preferences: ['functionality_storage', 'personalization_storage'],
+        ...config.categoryMapping
+      },
+      // Wait for GTM/GA to load
+      waitForGtag: true,
+      // Region-specific settings
+      regionSettings: {
+        EU: { wait_for_update: 500 },
+        UK: { wait_for_update: 500 },
+        US: { wait_for_update: 0 },
+        ...config.regionSettings
+      },
+      // Enable URL passthrough for conversion tracking
+      urlPassthrough: true,
+      // Enable ads data redaction
+      adsDataRedaction: true,
+      ...config
+    }
+
+    this.isInitialized = false
+    this.lastConsentHash = null // Prevent duplicate updates
+    this._debug('GoogleConsentModeProvider created')
+  }
+
+  /**
+   * Initialize Google Consent Mode
+   * MUST be called before GA/GTM loads
+   */
+  initialize() {
+    if (this.isInitialized) {
+      this._debug('Already initialized')
+      return
+    }
+
+    // Bootstrap gtag (CRITICAL: before GA/GTM loads)
+    this._bootstrapGtag()
+
+    // Set default consent state (DENIED for all)
+    this.setDefaultConsent()
+
+    // Listen for consent changes
+    this.consentManager.on('consentChanged', ({ consent, categories }) => {
+      this.updateConsent(categories, consent.region)
+    })
+
+    // Apply existing consent if available
+    const existingConsent = this.consentManager.getConsent()
+    if (existingConsent) {
+      this.updateConsent(existingConsent.categories, existingConsent.region)
+    }
+
+    this.isInitialized = true
+    this._debug('Google Consent Mode v2 initialized')
+    this._emitEvent('gcm:initialized', {})
+  }
+
+  /**
+   * Set default consent state (all DENIED)
+   * Called before GA/GTM loads
+   */
+  setDefaultConsent() {
+    const region = this.consentManager.getConsent()?.region || 'ROW'
+    const regionConfig = this.config.regionSettings[region] || {}
+
+    const defaultConsent = {
+      ad_storage: 'denied',
+      analytics_storage: 'denied',
+      ad_user_data: 'denied',
+      ad_personalization: 'denied',
+      functionality_storage: 'denied',
+      personalization_storage: 'denied',
+      security_storage: 'granted', // Always granted for security
+      
+      // CRITICAL: wait_for_update gives CMP time to update consent
+      // Prevents GA from firing before consent update
+      wait_for_update: regionConfig.wait_for_update !== undefined 
+        ? regionConfig.wait_for_update 
+        : 500, // Default 500ms for all regions
+      
+      ...regionConfig
+    }
+
+    // URL passthrough for conversion tracking without cookies
+    if (this.config.urlPassthrough) {
+      defaultConsent.url_passthrough = true
+    }
+
+    // Redact ads data until consent
+    if (this.config.adsDataRedaction) {
+      defaultConsent.ads_data_redaction = true
+    }
+
+    this._debug('Setting default consent:', defaultConsent)
+    
+    window.gtag('consent', 'default', defaultConsent)
+    
+    this._emitEvent('gcm:default-set', { consent: defaultConsent })
+  }
+
+  /**
+   * Update consent based on user choice
+   * @param {Object} categories - Consent categories
+   * @param {string} region - User region
+   */
+  updateConsent(categories, region = 'ROW') {
+    const consentUpdate = this._mapCategoriesToGoogleConsent(categories)
+    
+    // Deduplication: prevent duplicate updates
+    const consentHash = this._hashConsent(consentUpdate)
+    if (this.lastConsentHash === consentHash) {
+      this._debug('Consent unchanged, skipping update')
+      return
+    }
+    this.lastConsentHash = consentHash
+
+    this._debug('Updating consent:', consentUpdate)
+    
+    window.gtag('consent', 'update', consentUpdate)
+    
+    this._emitEvent('gcm:updated', { 
+      consent: consentUpdate,
+      categories,
+      region
+    })
+  }
+
+  /**
+   * Map CMP categories to Google consent types
+   * @param {Object} categories - CMP categories
+   * @returns {Object} Google consent object
+   * @private
+   */
+  _mapCategoriesToGoogleConsent(categories) {
+    const googleConsent = {}
+
+    // Map each CMP category to Google consent types
+    Object.entries(this.config.categoryMapping).forEach(([cmpCategory, googleTypes]) => {
+      const isGranted = categories[cmpCategory] === true
+      const consentValue = isGranted ? 'granted' : 'denied'
+
+      googleTypes.forEach(googleType => {
+        googleConsent[googleType] = consentValue
+      })
+    })
+
+    // Security storage always granted
+    googleConsent.security_storage = 'granted'
+
+    return googleConsent
+  }
+
+  /**
+   * Get current consent state
+   * @returns {Object}
+   */
+  getConsentState() {
+    const consent = this.consentManager.getConsent()
+    if (!consent) {
+      return {
+        ad_storage: 'denied',
+        analytics_storage: 'denied',
+        ad_user_data: 'denied',
+        ad_personalization: 'denied'
+      }
+    }
+
+    return this._mapCategoriesToGoogleConsent(consent.categories)
+  }
+
+  /**
+   * Check if specific Google consent type is granted
+   * @param {string} consentType - Google consent type
+   * @returns {boolean}
+   */
+  isGranted(consentType) {
+    const state = this.getConsentState()
+    return state[consentType] === 'granted'
+  }
+
+  /**
+   * Manually trigger consent update
+   * Useful for testing or manual control
+   */
+  refresh() {
+    const consent = this.consentManager.getConsent()
+    if (consent) {
+      this.updateConsent(consent.categories, consent.region)
+    }
+  }
+
+  /**
+   * Get category mapping configuration
+   * @returns {Object}
+   */
+  getCategoryMapping() {
+    return { ...this.config.categoryMapping }
+  }
+
+  /**
+   * Update category mapping
+   * @param {Object} mapping - New mapping
+   */
+  setCategoryMapping(mapping) {
+    this.config.categoryMapping = { ...this.config.categoryMapping, ...mapping }
+    this.refresh()
+  }
+
+  // --- Internal helpers ---
+
+  _emitEvent(eventName, detail) {
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(`cookie-consent:${eventName}`, { detail }))
+    }
+  }
+
+  /**
+   * Bootstrap gtag function
+   * MUST run before GA/GTM loads
+   * @private
+   */
+  _bootstrapGtag() {
+    // Initialize dataLayer
+    window.dataLayer = window.dataLayer || []
+    
+    // Create gtag function if not exists
+    if (!window.gtag) {
+      window.gtag = function() {
+        window.dataLayer.push(arguments)
+      }
+      
+      // Mark gtag as bootstrapped by CMP
+      window.gtag.l = Date.now()
+    }
+    
+    this._debug('gtag bootstrapped')
+  }
+
+  /**
+   * Hash consent object for deduplication
+   * @private
+   */
+  _hashConsent(consent) {
+    return JSON.stringify(consent)
+  }
+
+  _debug(...args) {
+    if (this.consentManager.config.debug) {
+      console.log('[GoogleConsentMode]', ...args)
+    }
+  }
+}
+
+/**
+ * Helper function to initialize Google Consent Mode
+ * @param {ConsentManager} consentManager - Consent manager instance
+ * @param {Object} config - Configuration
+ * @returns {GoogleConsentModeProvider}
+ */
+export function initGoogleConsentMode(consentManager, config = {}) {
+  const provider = new GoogleConsentModeProvider(consentManager, config)
+  provider.initialize()
+  return provider
+}

package/src/providers/index.js

@@ -0,0 +1,6 @@
+/**
+ * Consent Providers — integrations with external systems
+ * @module providers
+ */
+
+export { GoogleConsentModeProvider, initGoogleConsentMode } from './GoogleConsentModeProvider.js'

package/src/rewriting/ScriptRewriter.js

@@ -0,0 +1,278 @@
+/**
+ * ScriptRewriter — automatically rewrites scripts to be CMP-compliant
+ * @module ScriptRewriter
+ * 
+ * Converts regular scripts:
+ *   <script src="https://www.google-analytics.com/gtag.js"></script>
+ * 
+ * Into CMP-compliant scripts:
+ *   <script 
+ *     type="text/plain"
+ *     data-cookie-category="analytics"
+ *     data-cookie-src="https://www.google-analytics.com/gtag.js"
+ *   ></script>
+ */
+
+import { getAllTrackerPatterns } from '../trackers/TrackerPatterns.js'
+
+export class ScriptRewriter {
+  constructor(config = {}) {
+    this.config = {
+      autoRewrite: true,
+      rewriteInline: false, // Rewrite inline scripts (dangerous!)
+      preserveAttributes: true, // Preserve original attributes
+      observeDOM: true, // Watch for new scripts
+      whitelist: [], // URLs to never rewrite
+      blacklist: [], // URLs to always rewrite
+      debug: false,
+      ...config
+    }
+
+    this.rewrittenScripts = new Map() // original script -> rewritten script
+    this.observer = null
+  }
+
+  /**
+   * Initialize rewriter
+   */
+  initialize() {
+    if (this.config.autoRewrite) {
+      this.rewriteAll()
+    }
+
+    if (this.config.observeDOM) {
+      this._startObserver()
+    }
+  }
+
+  /**
+   * Rewrite all scripts on the page
+   * @returns {number} Number of scripts rewritten
+   */
+  rewriteAll() {
+    this._debug('Starting script rewriting...')
+
+    const scripts = document.querySelectorAll('script[src]')
+    let rewrittenCount = 0
+
+    scripts.forEach(script => {
+      if (this._shouldRewrite(script)) {
+        const rewritten = this._rewriteScript(script)
+        if (rewritten) {
+          rewrittenCount++
+        }
+      }
+    })
+
+    this._debug(`Rewrote ${rewrittenCount} scripts`)
+    return rewrittenCount
+  }
+
+  /**
+   * Rewrite a single script element
+   * @param {HTMLScriptElement} script - Script to rewrite
+   * @returns {HTMLScriptElement|null} Rewritten script or null
+   */
+  _rewriteScript(script) {
+    const src = script.getAttribute('src')
+    if (!src) return null
+
+    // Check if already rewritten
+    if (script.type === 'text/plain' && script.dataset.cookieSrc) {
+      this._debug('Script already rewritten:', src)
+      return null
+    }
+
+    // Detect tracker category
+    const category = this._detectCategory(src)
+    if (!category) {
+      this._debug('No category detected for:', src)
+      return null
+    }
+
+    // Create new script element
+    const newScript = document.createElement('script')
+    
+    // Set CMP attributes
+    newScript.type = 'text/plain'
+    newScript.dataset.cookieCategory = category
+    newScript.dataset.cookieSrc = src
+
+    // Preserve original attributes
+    if (this.config.preserveAttributes) {
+      Array.from(script.attributes).forEach(attr => {
+        if (attr.name !== 'src' && attr.name !== 'type') {
+          newScript.setAttribute(attr.name, attr.value)
+        }
+      })
+    }
+
+    // Replace script
+    script.parentNode?.replaceChild(newScript, script)
+    
+    // Store mapping
+    this.rewrittenScripts.set(script, newScript)
+
+    this._debug(`Rewrote script: ${src} → category: ${category}`)
+    return newScript
+  }
+
+  /**
+   * Check if script should be rewritten
+   * @param {HTMLScriptElement} script
+   * @returns {boolean}
+   */
+  _shouldRewrite(script) {
+    const src = script.getAttribute('src')
+    if (!src) return false
+
+    // Already rewritten
+    if (script.type === 'text/plain' && script.dataset.cookieSrc) {
+      return false
+    }
+
+    // Check whitelist (never rewrite)
+    if (this.config.whitelist.length > 0) {
+      const isWhitelisted = this.config.whitelist.some(pattern => 
+        src.includes(pattern)
+      )
+      if (isWhitelisted) {
+        this._debug('Whitelisted, skipping:', src)
+        return false
+      }
+    }
+
+    // Check blacklist (always rewrite)
+    if (this.config.blacklist.length > 0) {
+      const isBlacklisted = this.config.blacklist.some(pattern => 
+        src.includes(pattern)
+      )
+      if (isBlacklisted) {
+        return true
+      }
+    }
+
+    // Check if tracker is detected
+    const category = this._detectCategory(src)
+    return category !== null
+  }
+
+  /**
+   * Detect category from script src
+   * @param {string} src - Script source URL
+   * @returns {string|null} Category name or null
+   */
+  _detectCategory(src) {
+    const patterns = getAllTrackerPatterns()
+
+    for (const pattern of patterns) {
+      for (const scriptPattern of pattern.scripts) {
+        if (src.includes(scriptPattern)) {
+          return pattern.category
+        }
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Start MutationObserver to watch for new scripts
+   * @private
+   */
+  _startObserver() {
+    if (typeof MutationObserver === 'undefined') {
+      return
+    }
+
+    this.observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === 1) {
+            // Check if it's a script
+            if (node.tagName === 'SCRIPT' && node.getAttribute('src')) {
+              if (this._shouldRewrite(node)) {
+                this._debug('New script detected, rewriting...')
+                this._rewriteScript(node)
+              }
+            }
+            
+            // Check for scripts inside added node
+            const scripts = node.querySelectorAll?.('script[src]')
+            scripts?.forEach(script => {
+              if (this._shouldRewrite(script)) {
+                this._rewriteScript(script)
+              }
+            })
+          }
+        })
+      })
+    })
+
+    this.observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true
+    })
+
+    this._debug('Script rewriter observer started')
+  }
+
+  /**
+   * Get rewritten scripts
+   * @returns {Array}
+   */
+  getRewrittenScripts() {
+    return Array.from(this.rewrittenScripts.entries()).map(([original, rewritten]) => ({
+      original: original.src,
+      category: rewritten.dataset.cookieCategory,
+      rewritten: rewritten.dataset.cookieSrc
+    }))
+  }
+
+  /**
+   * Get stats
+   * @returns {Object}
+   */
+  getStats() {
+    const scripts = this.getRewrittenScripts()
+    const byCategory = {}
+
+    scripts.forEach(script => {
+      if (!byCategory[script.category]) {
+        byCategory[script.category] = []
+      }
+      byCategory[script.category].push(script.original)
+    })
+
+    return {
+      total: scripts.length,
+      byCategory
+    }
+  }
+
+  /**
+   * Destroy rewriter
+   */
+  destroy() {
+    if (this.observer) {
+      this.observer.disconnect()
+      this.observer = null
+    }
+    this.rewrittenScripts.clear()
+  }
+
+  _debug(...args) {
+    // Debug disabled
+  }
+}
+
+/**
+ * Helper function to rewrite scripts automatically
+ * @param {Object} config - Configuration
+ * @returns {ScriptRewriter}
+ */
+export function initScriptRewriter(config = {}) {
+  const rewriter = new ScriptRewriter(config)
+  rewriter.initialize()
+  return rewriter
+}

package/src/rewriting/index.js

@@ -0,0 +1,6 @@
+/**
+ * Script Rewriting System — automatically rewrite scripts to be CMP-compliant
+ * @module rewriting
+ */
+
+export { ScriptRewriter, initScriptRewriter } from './ScriptRewriter.js'