@el7ven/cookie-kit 0.3.1 → 0.3.2

package/src/plugins/PluginManager.js

@@ -0,0 +1,234 @@
+/**
+ * Plugin Manager
+ * @module PluginManager
+ * 
+ * Manages CMP plugins lifecycle and events
+ */
+
+export class PluginManager {
+  constructor(cmpInstance) {
+    this.cmp = cmpInstance
+    this.plugins = new Map() // name -> plugin instance
+    this.hooks = {
+      beforeInit: [],
+      afterInit: [],
+      beforeBannerShow: [],
+      afterBannerShow: [],
+      beforeConsentSave: [],
+      afterConsentSave: []
+    }
+  }
+
+  /**
+   * Register plugin
+   * @param {CMPPlugin} plugin - Plugin instance
+   * @returns {boolean}
+   */
+  register(plugin) {
+    if (!plugin || !plugin.name) return false
+    if (this.plugins.has(plugin.name)) return false
+
+    // Initialize plugin
+    plugin.init(this.cmp)
+
+    // Store plugin
+    this.plugins.set(plugin.name, plugin)
+
+    // Register lifecycle hooks
+    this._registerHooks(plugin)
+
+    // Setup event listeners
+    this._setupEventListeners(plugin)
+
+    this._debug(`Plugin "${plugin.name}" registered`)
+    return true
+  }
+
+  /**
+   * Unregister plugin
+   * @param {string} pluginName
+   * @returns {boolean}
+   */
+  unregister(pluginName) {
+    const plugin = this.plugins.get(pluginName)
+    if (!plugin) {
+      return false
+    }
+
+    // Cleanup plugin
+    plugin.destroy()
+
+    // Remove from hooks
+    this._unregisterHooks(plugin)
+
+    // Remove plugin
+    this.plugins.delete(pluginName)
+
+    this._debug(`Plugin "${pluginName}" unregistered`)
+    return true
+  }
+
+  /**
+   * Get plugin by name
+   * @param {string} pluginName
+   * @returns {CMPPlugin|null}
+   */
+  get(pluginName) {
+    return this.plugins.get(pluginName) || null
+  }
+
+  /**
+   * Get all plugins
+   * @returns {Array}
+   */
+  getAll() {
+    return Array.from(this.plugins.values())
+  }
+
+  /**
+   * Check if plugin is registered
+   * @param {string} pluginName
+   * @returns {boolean}
+   */
+  has(pluginName) {
+    return this.plugins.has(pluginName)
+  }
+
+  /**
+   * Execute lifecycle hook
+   * @param {string} hookName
+   * @param {*} data
+   * @returns {*}
+   */
+  async executeHook(hookName, data = null) {
+    const hooks = this.hooks[hookName] || []
+    
+    let result = data
+
+    for (const hook of hooks) {
+      try {
+        const hookResult = await hook(result)
+        // For beforeConsentSave, allow modification
+        if (hookName === 'beforeConsentSave' && hookResult !== undefined) {
+          result = hookResult
+        }
+      } catch (error) {
+        // Silent error
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Register plugin hooks
+   * @private
+   */
+  _registerHooks(plugin) {
+    // beforeInit
+    if (typeof plugin.beforeInit === 'function') {
+      this.hooks.beforeInit.push(() => plugin.beforeInit())
+    }
+
+    // afterInit
+    if (typeof plugin.afterInit === 'function') {
+      this.hooks.afterInit.push(() => plugin.afterInit())
+    }
+
+    // beforeBannerShow
+    if (typeof plugin.beforeBannerShow === 'function') {
+      this.hooks.beforeBannerShow.push(() => plugin.beforeBannerShow())
+    }
+
+    // afterBannerShow
+    if (typeof plugin.afterBannerShow === 'function') {
+      this.hooks.afterBannerShow.push(() => plugin.afterBannerShow())
+    }
+
+    // beforeConsentSave
+    if (typeof plugin.beforeConsentSave === 'function') {
+      this.hooks.beforeConsentSave.push((consent) => plugin.beforeConsentSave(consent))
+    }
+
+    // afterConsentSave
+    if (typeof plugin.afterConsentSave === 'function') {
+      this.hooks.afterConsentSave.push((consent) => plugin.afterConsentSave(consent))
+    }
+  }
+
+  /**
+   * Unregister plugin hooks
+   * @private
+   */
+  _unregisterHooks(plugin) {
+    Object.keys(this.hooks).forEach(hookName => {
+      this.hooks[hookName] = this.hooks[hookName].filter(hook => {
+        // Remove hooks that belong to this plugin
+        return hook.toString().indexOf(plugin.name) === -1
+      })
+    })
+  }
+
+  /**
+   * Setup event listeners for plugin
+   * @private
+   */
+  _setupEventListeners(plugin) {
+    // Consent changed
+    if (typeof plugin.onConsentChange === 'function') {
+      this.cmp.on('consentChanged', (data) => plugin.onConsentChange(data))
+    }
+
+    // Consent accepted
+    if (typeof plugin.onConsentAccepted === 'function') {
+      this.cmp.on('consentAccepted', (data) => plugin.onConsentAccepted(data))
+    }
+
+    // Consent rejected
+    if (typeof plugin.onConsentRejected === 'function') {
+      this.cmp.on('consentRejected', (data) => plugin.onConsentRejected(data))
+    }
+
+    // Consent expired
+    if (typeof plugin.onConsentExpired === 'function') {
+      this.cmp.on('consentExpired', () => plugin.onConsentExpired())
+    }
+
+    // Script loaded
+    if (typeof plugin.onScriptLoaded === 'function') {
+      if (typeof window !== 'undefined') {
+        window.addEventListener('cookie-consent:script-loaded', (e) => {
+          plugin.onScriptLoaded(e.detail)
+        })
+      }
+    }
+
+    // Tracker detected
+    if (typeof plugin.onTrackerDetected === 'function') {
+      if (typeof window !== 'undefined') {
+        window.addEventListener('cookie-consent:tracker-detected', (e) => {
+          plugin.onTrackerDetected(e.detail)
+        })
+      }
+    }
+  }
+
+  /**
+   * Get plugin stats
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      total: this.plugins.size,
+      plugins: this.getAll().map(p => ({
+        name: p.name,
+        version: p.version,
+        initialized: p.isInitialized
+      }))
+    }
+  }
+
+  _debug(...args) {
+    // Debug disabled
+  }
+}

package/src/plugins/index.js

@@ -0,0 +1,7 @@
+/**
+ * Plugin System
+ * @module plugins
+ */
+
+export { CMPPlugin } from './CMPPlugin.js'
+export { PluginManager } from './PluginManager.js'

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'