@freshjuice/zest 0.1.0 → 2.0.0

package/src/index.js

@@ -0,0 +1,266 @@
+/**
+ * Zest - Lightweight Cookie Consent Toolkit
+ * Main entry (full build: logic + UI).
+ *
+ * For a logic-only build without any CSS / Shadow DOM mounting, import
+ * from `@freshjuice/zest/headless` instead.
+ */
+
+// Core lifecycle (UI-agnostic)
+import {
+  coreInit,
+  coreAcceptAll,
+  coreRejectAll,
+  coreUpdateConsent,
+  coreReset,
+  isInitialized,
+  getActiveConfig
+} from './core-lifecycle.js';
+
+// Consent store + events
+import {
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof
+} from './storage/consent-store.js';
+import { emitShow, emitHide, EVENTS, on, once } from './storage/events.js';
+
+// DNT introspection
+import { isDoNotTrackEnabled, getDNTDetails } from './core/dnt.js';
+
+// Config getters
+import { getConfig, getCurrentConfig } from './config/parser.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';
+
+/**
+ * Handle accept all — delegates consent logic to core, handles UI swap.
+ */
+function handleAcceptAll() {
+  coreAcceptAll();
+  const config = getActiveConfig();
+
+  hideBanner();
+  hideModal();
+
+  if (config?.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+}
+
+/**
+ * Handle reject all.
+ */
+function handleRejectAll() {
+  coreRejectAll();
+  const config = getActiveConfig();
+
+  hideBanner();
+  hideModal();
+
+  if (config?.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+}
+
+/**
+ * Handle save preferences from modal.
+ */
+function handleSavePreferences(selections) {
+  coreUpdateConsent(selections);
+  const config = getActiveConfig();
+
+  hideModal();
+
+  if (config?.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+}
+
+/**
+ * Open the settings modal.
+ */
+function handleShowSettings() {
+  hideBanner();
+  hideWidget();
+
+  showModal(getConsent(), {
+    onSave: handleSavePreferences,
+    onAcceptAll: handleAcceptAll,
+    onRejectAll: handleRejectAll,
+    onClose: handleCloseModal
+  });
+
+  emitShow('modal');
+}
+
+/**
+ * Close the modal — either bring the widget back (decision made) or
+ * fall back to the banner (no decision yet).
+ */
+function handleCloseModal() {
+  hideModal();
+  emitHide('modal');
+
+  const config = getActiveConfig();
+  if (hasConsentDecision() && config?.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  } else {
+    showBanner({
+      onAcceptAll: handleAcceptAll,
+      onRejectAll: handleRejectAll,
+      onSettings: handleShowSettings
+    });
+  }
+}
+
+/**
+ * Initialize Zest with UI.
+ */
+function init(userConfig = {}) {
+  const { alreadyInitialized, consent, hasDecision, dntApplied } = coreInit(userConfig);
+  if (alreadyInitialized) {
+    console.warn('[Zest] Already initialized');
+    return Zest;
+  }
+
+  const config = getActiveConfig();
+
+  if (!hasDecision && !dntApplied) {
+    showBanner({
+      onAcceptAll: handleAcceptAll,
+      onRejectAll: handleRejectAll,
+      onSettings: handleShowSettings
+    });
+    emitShow('banner');
+  } else if (config?.showWidget) {
+    showWidget({ onClick: handleShowSettings });
+  }
+
+  return Zest;
+}
+
+const Zest = {
+  init,
+
+  // Banner control
+  show() {
+    if (!isInitialized()) {
+      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 (!isInitialized()) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleShowSettings();
+  },
+
+  hideSettings() {
+    hideModal();
+    emitHide('modal');
+  },
+
+  // Consent state
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof,
+
+  // DNT
+  isDoNotTrackEnabled,
+  getDNTDetails,
+
+  // Programmatic accept / reject
+  acceptAll() {
+    if (!isInitialized()) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleAcceptAll();
+  },
+
+  rejectAll() {
+    if (!isInitialized()) {
+      console.warn('[Zest] Not initialized. Call Zest.init() first.');
+      return;
+    }
+    handleRejectAll();
+  },
+
+  // Reset everything and reshow the banner
+  reset() {
+    coreReset();
+    hideModal();
+    removeWidget();
+    if (isInitialized()) {
+      showBanner({
+        onAcceptAll: handleAcceptAll,
+        onRejectAll: handleRejectAll,
+        onSettings: handleShowSettings
+      });
+      emitShow('banner');
+    }
+  },
+
+  // Config introspection
+  getConfig: getCurrentConfig,
+
+  // Events
+  on,
+  once,
+  EVENTS
+};
+
+// Auto-init if config present
+if (typeof window !== 'undefined') {
+  // Make Zest available globally. defineProperty with writable:false +
+  // configurable:false stops a later-loaded script from replacing the
+  // global with a trojanned stand-in.
+  try {
+    Object.defineProperty(window, 'Zest', {
+      value: Object.freeze(Zest),
+      writable: false,
+      configurable: false,
+      enumerable: true
+    });
+  } catch (e) {
+    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,201 @@
+/**
+ * Consent Store - Manages consent state persistence
+ */
+
+import { getDefaultConsent, getCategoryIds } from '../core/categories.js';
+import { getOriginalCookieDescriptor } from '../core/cookie-interceptor.js';
+import { sanitizeConsentPayload } from '../core/security.js';
+
+const COOKIE_NAME = 'zest_consent';
+const CONSENT_VERSION = '1.0';
+
+/**
+ * Return the Secure flag fragment when running over HTTPS, empty otherwise.
+ * On HTTPS sites, omitting Secure lets the cookie leak over plain HTTP.
+ */
+function secureAttribute() {
+  try {
+    return typeof location !== 'undefined' && location.protocol === 'https:'
+      ? '; Secure'
+      : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+// 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.
+ *
+ * The parsed cookie is validated against the expected schema via
+ * sanitizeConsentPayload — only known category keys with boolean values
+ * survive, so a tampered cookie can't inject prototype-polluting props
+ * or unexpected category shapes.
+ */
+export function loadConsent() {
+  try {
+    const cookies = getRawCookie();
+    const match = cookies.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
+
+    if (match) {
+      const raw = JSON.parse(decodeURIComponent(match[1]));
+      const clean = sanitizeConsentPayload(raw, getCategoryIds());
+      if (clean && clean.categories) {
+        consent = { ...getDefaultConsent(), ...clean.categories };
+        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${secureAttribute()}`;
+
+  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=/; SameSite=Lax${secureAttribute()}`);
+  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) {
+      const raw = JSON.parse(decodeURIComponent(match[1]));
+      return sanitizeConsentPayload(raw, getCategoryIds());
+    }
+  } 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 });
+}