@freshjuice/zest 0.1.0 → 1.0.0

package/src/index.js

@@ -0,0 +1,377 @@
+/**
+ * Zest - Lightweight Cookie Consent Toolkit
+ * Main entry point
+ */
+
+// Core
+import { interceptCookies, setConsentChecker as setCookieChecker, replayCookies, getOriginalCookieDescriptor } from './core/cookie-interceptor.js';
+import { interceptStorage, setConsentChecker as setStorageChecker, replayStorage } from './core/storage-interceptor.js';
+import { startScriptBlocking, setConsentChecker as setScriptChecker, replayScripts } from './core/script-blocker.js';
+import { setPatterns } from './core/pattern-matcher.js';
+import { getCategoryIds } from './core/categories.js';
+import { isDoNotTrackEnabled, getDNTDetails } from './core/dnt.js';
+
+// Integrations
+import { applyConsentSignals } from './integrations/consent-signals.js';
+
+// Config
+import { getConfig, setConfig, getCurrentConfig } from './config/parser.js';
+
+// Storage
+import {
+  loadConsent,
+  getConsent,
+  hasConsent,
+  updateConsent,
+  acceptAll as storeAcceptAll,
+  rejectAll as storeRejectAll,
+  resetConsent,
+  hasConsentDecision,
+  getConsentProof
+} from './storage/consent-store.js';
+import { emitReady, emitConsent, emitReject, emitChange, emitShow, emitHide, EVENTS } from './storage/events.js';
+
+// UI
+import { showBanner, hideBanner, isBannerVisible } from './ui/banner.js';
+import { showModal, hideModal, isModalVisible } from './ui/modal.js';
+import { showWidget, hideWidget, removeWidget, isWidgetVisible } from './ui/widget.js';
+
+// State
+let initialized = false;
+let config = null;
+
+/**
+ * Consent checker function shared across interceptors
+ */
+function checkConsent(category) {
+  return hasConsent(category);
+}
+
+/**
+ * Replay all queued items for newly allowed categories
+ */
+function replayAll(allowedCategories) {
+  replayCookies(allowedCategories);
+  replayStorage(allowedCategories);
+  replayScripts(allowedCategories);
+}
+
+/**
+ * Handle accept all
+ */
+function handleAcceptAll() {
+  const result = storeAcceptAll(config.expiration);
+  const categories = getCategoryIds();
+
+  applyConsentSignals(result.current, config, false);
+
+  hideBanner();
+  hideModal();
+
+  replayAll(categories);
+
+  if (config.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+
+  emitConsent(result.current, result.previous);
+  emitChange(result.current, result.previous);
+  config.callbacks?.onAccept?.(result.current);
+  config.callbacks?.onChange?.(result.current);
+}
+
+/**
+ * Handle reject all
+ */
+function handleRejectAll() {
+  const result = storeRejectAll(config.expiration);
+
+  applyConsentSignals(result.current, config, false);
+
+  hideBanner();
+  hideModal();
+
+  if (config.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+
+  emitReject(result.current);
+  emitChange(result.current, result.previous);
+  config.callbacks?.onReject?.();
+  config.callbacks?.onChange?.(result.current);
+}
+
+/**
+ * Handle save preferences from modal
+ */
+function handleSavePreferences(selections) {
+  const result = updateConsent(selections, config.expiration);
+
+  applyConsentSignals(result.current, config, false);
+
+  // Find newly allowed categories
+  const newlyAllowed = Object.keys(result.current).filter(
+    cat => result.current[cat] && !result.previous[cat]
+  );
+
+  if (newlyAllowed.length > 0) {
+    replayAll(newlyAllowed);
+  }
+
+  hideModal();
+
+  if (config.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+
+  // Determine if this was acceptance or rejection based on selections
+  const hasNonEssential = Object.entries(selections)
+    .some(([cat, val]) => cat !== 'essential' && val);
+
+  if (hasNonEssential) {
+    emitConsent(result.current, result.previous);
+  } else {
+    emitReject(result.current);
+  }
+
+  emitChange(result.current, result.previous);
+  config.callbacks?.onChange?.(result.current);
+}
+
+/**
+ * Handle show settings
+ */
+function handleShowSettings() {
+  hideBanner();
+  hideWidget();
+
+  showModal(getConsent(), {
+    onSave: handleSavePreferences,
+    onAcceptAll: handleAcceptAll,
+    onRejectAll: handleRejectAll,
+    onClose: handleCloseModal
+  });
+
+  emitShow('modal');
+}
+
+/**
+ * Handle close modal
+ */
+function handleCloseModal() {
+  hideModal();
+  emitHide('modal');
+
+  // Show widget if consent was already given
+  if (hasConsentDecision() && config.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  } else {
+    // Show banner again if no decision made
+    showBanner({
+      onAcceptAll: handleAcceptAll,
+      onRejectAll: handleRejectAll,
+      onSettings: handleShowSettings
+    });
+  }
+}
+
+/**
+ * Initialize Zest
+ */
+function init(userConfig = {}) {
+  if (initialized) {
+    console.warn('[Zest] Already initialized');
+    return Zest;
+  }
+
+  // Merge config
+  config = setConfig(userConfig);
+
+  // Push default denied state to vendor consent mode APIs (must happen before scripts load)
+  applyConsentSignals(
+    { essential: true, functional: false, analytics: false, marketing: false },
+    config,
+    true
+  );
+
+  // Set patterns if provided
+  if (config.patterns) {
+    setPatterns(config.patterns);
+  }
+
+  // Set up consent checkers
+  setCookieChecker(checkConsent);
+  setStorageChecker(checkConsent);
+  setScriptChecker(checkConsent);
+
+  // Start interception
+  interceptCookies();
+  interceptStorage();
+  startScriptBlocking(config.mode, config.blockedDomains);
+
+  // Load saved consent
+  const consent = loadConsent();
+
+  initialized = true;
+
+  // Push update for returning visitors with saved consent
+  if (hasConsentDecision()) {
+    applyConsentSignals(consent, config, false);
+  }
+
+  // Check Do Not Track / Global Privacy Control
+  const dntEnabled = isDoNotTrackEnabled();
+  let dntApplied = false;
+
+  if (dntEnabled && config.respectDNT && config.dntBehavior !== 'ignore') {
+    if (config.dntBehavior === 'reject' && !hasConsentDecision()) {
+      // Auto-reject non-essential cookies silently
+      const result = storeRejectAll(config.expiration);
+      dntApplied = true;
+
+      applyConsentSignals(result.current, config, false);
+
+      // Emit events
+      emitReject(result.current);
+      emitChange(result.current, result.previous);
+      config.callbacks?.onReject?.();
+      config.callbacks?.onChange?.(result.current);
+    }
+    // 'preselect' behavior is handled by default (banner shows with defaults off)
+  }
+
+  // Emit ready event
+  emitReady(consent);
+  config.callbacks?.onReady?.(consent);
+
+  // Show UI based on consent state
+  if (!hasConsentDecision() && !dntApplied) {
+    // No consent decision yet - show banner
+    showBanner({
+      onAcceptAll: handleAcceptAll,
+      onRejectAll: handleRejectAll,
+      onSettings: handleShowSettings
+    });
+    emitShow('banner');
+  } else {
+    // Consent already given (or DNT auto-rejected) - show widget for reopening settings
+    if (config.showWidget) {
+      showWidget({ onClick: handleShowSettings });
+    }
+  }
+
+  return Zest;
+}
+
+/**
+ * Public API
+ */
+const Zest = {
+  // Initialization
+  init,
+
+  // Banner control
+  show() {
+    if (!initialized) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    hideModal();
+    hideWidget();
+    showBanner({
+      onAcceptAll: handleAcceptAll,
+      onRejectAll: handleRejectAll,
+      onSettings: handleShowSettings
+    });
+    emitShow('banner');
+  },
+
+  hide() {
+    hideBanner();
+    emitHide('banner');
+  },
+
+  // Settings modal
+  showSettings() {
+    if (!initialized) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleShowSettings();
+  },
+
+  hideSettings() {
+    hideModal();
+    emitHide('modal');
+  },
+
+  // Consent management
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof,
+
+  // DNT detection
+  isDoNotTrackEnabled,
+  getDNTDetails,
+
+  // Accept/Reject programmatically
+  acceptAll() {
+    if (!initialized) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleAcceptAll();
+  },
+
+  rejectAll() {
+    if (!initialized) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleRejectAll();
+  },
+
+  // Reset and show banner again
+  reset() {
+    resetConsent();
+    hideModal();
+    removeWidget();
+
+    if (initialized) {
+      showBanner({
+        onAcceptAll: handleAcceptAll,
+        onRejectAll: handleRejectAll,
+        onSettings: handleShowSettings
+      });
+      emitShow('banner');
+    }
+  },
+
+  // Config
+  getConfig: getCurrentConfig,
+
+  // Events
+  EVENTS
+};
+
+// Auto-init if config present
+if (typeof window !== 'undefined') {
+  // Make Zest available globally
+  window.Zest = Zest;
+
+  const autoInit = () => {
+    const cfg = getConfig();
+    if (cfg.autoInit !== false) {
+      init(window.ZestConfig);
+    }
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoInit);
+  } else {
+    autoInit();
+  }
+}
+
+export default Zest;

package/src/integrations/consent-signals.js

@@ -0,0 +1,71 @@
+/**
+ * Consent Signals - Optional vendor consent mode integrations
+ *
+ * Pushes consent state to Google Consent Mode v2 and/or Microsoft UET
+ * Consent Mode when enabled via config.
+ */
+
+/**
+ * Map Zest consent state to Google Consent Mode v2 signals
+ */
+function toGoogleSignals(consent) {
+  const g = (val) => val ? 'granted' : 'denied';
+  return {
+    ad_storage: g(consent.marketing),
+    ad_user_data: g(consent.marketing),
+    ad_personalization: g(consent.marketing),
+    analytics_storage: g(consent.analytics),
+    functionality_storage: 'granted', // essential is always true
+    personalization_storage: g(consent.functional)
+  };
+}
+
+/**
+ * Push consent signal to Google via gtag or dataLayer fallback.
+ * Uses a local function to preserve the `arguments` object shape
+ * that gtag/dataLayer expects (not an array).
+ */
+function pushGoogle(type, signals) {
+  window.dataLayer = window.dataLayer || [];
+  if (typeof window.gtag === 'function') {
+    window.gtag('consent', type, signals);
+  } else {
+    function gtagFallback() { window.dataLayer.push(arguments); }
+    gtagFallback('consent', type, signals);
+  }
+}
+
+/**
+ * Map Zest consent state to Microsoft UET signal.
+ * Microsoft UET only exposes ad_storage.
+ */
+function toMicrosoftSignals(consent) {
+  return { ad_storage: consent.marketing ? 'granted' : 'denied' };
+}
+
+/**
+ * Push consent signal to Microsoft UET
+ */
+function pushMicrosoft(type, signals) {
+  window.uetq = window.uetq || [];
+  window.uetq.push('consent', type, signals);
+}
+
+/**
+ * Apply consent signals to enabled vendor integrations.
+ *
+ * @param {Object} consent    Current Zest consent state
+ * @param {Object} config     Merged Zest config
+ * @param {boolean} isDefault true on first call (pushes 'default'), false for updates
+ */
+export function applyConsentSignals(consent, config, isDefault) {
+  const type = isDefault ? 'default' : 'update';
+
+  if (config.consentModeGoogle) {
+    pushGoogle(type, toGoogleSignals(consent));
+  }
+
+  if (config.consentModeMicrosoft) {
+    pushMicrosoft(type, toMicrosoftSignals(consent));
+  }
+}

package/src/storage/consent-store.js

@@ -0,0 +1,177 @@
+/**
+ * Consent Store - Manages consent state persistence
+ */
+
+import { getDefaultConsent } from '../core/categories.js';
+import { getOriginalCookieDescriptor } from '../core/cookie-interceptor.js';
+
+const COOKIE_NAME = 'zest_consent';
+const CONSENT_VERSION = '1.0';
+
+// Current consent state
+let consent = null;
+
+/**
+ * Get the original cookie setter (bypasses interception)
+ */
+function setRawCookie(value) {
+  const descriptor = getOriginalCookieDescriptor();
+  if (descriptor?.set) {
+    descriptor.set.call(document, value);
+  } else {
+    // Fallback if interceptor not initialized yet
+    document.cookie = value;
+  }
+}
+
+/**
+ * Get the original cookie getter
+ */
+function getRawCookie() {
+  const descriptor = getOriginalCookieDescriptor();
+  if (descriptor?.get) {
+    return descriptor.get.call(document);
+  }
+  return document.cookie;
+}
+
+/**
+ * Load consent from cookie
+ */
+export function loadConsent() {
+  try {
+    const cookies = getRawCookie();
+    const match = cookies.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
+
+    if (match) {
+      const data = JSON.parse(decodeURIComponent(match[1]));
+      consent = data.categories || getDefaultConsent();
+      return { ...consent };
+    }
+  } catch (e) {
+    // Invalid or missing cookie
+  }
+
+  consent = getDefaultConsent();
+  return { ...consent };
+}
+
+/**
+ * Save consent to cookie
+ */
+export function saveConsent(expirationDays = 365) {
+  if (!consent) {
+    consent = getDefaultConsent();
+  }
+
+  const data = {
+    version: CONSENT_VERSION,
+    timestamp: Date.now(),
+    categories: consent
+  };
+
+  const expires = new Date(Date.now() + expirationDays * 24 * 60 * 60 * 1000).toUTCString();
+  const cookieValue = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(data))}; expires=${expires}; path=/; SameSite=Lax`;
+
+  setRawCookie(cookieValue);
+}
+
+/**
+ * Get current consent state
+ */
+export function getConsent() {
+  if (!consent) {
+    consent = loadConsent();
+  }
+  return { ...consent };
+}
+
+/**
+ * Update consent state
+ */
+export function updateConsent(newConsent, expirationDays = 365) {
+  const previous = consent ? { ...consent } : getDefaultConsent();
+
+  consent = {
+    essential: true, // Always true
+    functional: !!newConsent.functional,
+    analytics: !!newConsent.analytics,
+    marketing: !!newConsent.marketing
+  };
+
+  saveConsent(expirationDays);
+
+  return { current: { ...consent }, previous };
+}
+
+/**
+ * Check if specific category is allowed
+ */
+export function hasConsent(category) {
+  if (!consent) {
+    consent = loadConsent();
+  }
+  return consent[category] === true;
+}
+
+/**
+ * Accept all categories
+ */
+export function acceptAll(expirationDays = 365) {
+  return updateConsent({
+    essential: true,
+    functional: true,
+    analytics: true,
+    marketing: true
+  }, expirationDays);
+}
+
+/**
+ * Reject all (except essential)
+ */
+export function rejectAll(expirationDays = 365) {
+  return updateConsent({
+    essential: true,
+    functional: false,
+    analytics: false,
+    marketing: false
+  }, expirationDays);
+}
+
+/**
+ * Reset consent (clear cookie)
+ */
+export function resetConsent() {
+  setRawCookie(`${COOKIE_NAME}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`);
+  consent = null;
+}
+
+/**
+ * Check if consent has been given (any decision made)
+ */
+export function hasConsentDecision() {
+  try {
+    const cookies = getRawCookie();
+    return cookies.includes(COOKIE_NAME);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Get consent proof for compliance
+ */
+export function getConsentProof() {
+  try {
+    const cookies = getRawCookie();
+    const match = cookies.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
+
+    if (match) {
+      return JSON.parse(decodeURIComponent(match[1]));
+    }
+  } catch (e) {
+    // Invalid cookie
+  }
+
+  return null;
+}

package/src/storage/events.js

@@ -0,0 +1,84 @@
+/**
+ * Events - Custom event dispatching for consent changes
+ */
+
+// Event names
+export const EVENTS = {
+  READY: 'zest:ready',
+  CONSENT: 'zest:consent',
+  REJECT: 'zest:reject',
+  CHANGE: 'zest:change',
+  SHOW: 'zest:show',
+  HIDE: 'zest:hide'
+};
+
+/**
+ * Dispatch a custom event
+ */
+export function emit(eventName, detail = {}) {
+  const event = new CustomEvent(eventName, {
+    detail,
+    bubbles: true,
+    cancelable: true
+  });
+
+  document.dispatchEvent(event);
+  return event;
+}
+
+/**
+ * Emit ready event
+ */
+export function emitReady(consent) {
+  return emit(EVENTS.READY, { consent });
+}
+
+/**
+ * Emit consent event (user accepted)
+ */
+export function emitConsent(consent, previous) {
+  return emit(EVENTS.CONSENT, { consent, previous });
+}
+
+/**
+ * Emit reject event (user rejected all)
+ */
+export function emitReject(consent) {
+  return emit(EVENTS.REJECT, { consent });
+}
+
+/**
+ * Emit change event (any consent change)
+ */
+export function emitChange(consent, previous) {
+  return emit(EVENTS.CHANGE, { consent, previous });
+}
+
+/**
+ * Emit show event (banner/modal shown)
+ */
+export function emitShow(type = 'banner') {
+  return emit(EVENTS.SHOW, { type });
+}
+
+/**
+ * Emit hide event (banner/modal hidden)
+ */
+export function emitHide(type = 'banner') {
+  return emit(EVENTS.HIDE, { type });
+}
+
+/**
+ * Subscribe to an event
+ */
+export function on(eventName, callback) {
+  document.addEventListener(eventName, callback);
+  return () => document.removeEventListener(eventName, callback);
+}
+
+/**
+ * Subscribe to an event once
+ */
+export function once(eventName, callback) {
+  document.addEventListener(eventName, callback, { once: true });
+}