@affectively/aeon-pages 1.3.0

package/packages/analytics/src/click-tracker.ts

@@ -0,0 +1,368 @@
+/**
+ * Automatic Click Tracker
+ *
+ * Intercepts all clicks using event delegation and automatically
+ * tracks them to GTM dataLayer with Merkle tree context.
+ *
+ * Features:
+ * - Single delegated listener (no per-element handlers)
+ * - Walks up DOM to find Merkle-annotated ancestor
+ * - Captures full tree path and element metadata
+ * - Includes ESI context snapshot with each click
+ */
+
+import type { AnalyticsConfig, ClickTrackingOptions, ESIState } from './types';
+import {
+  extractElementInfo,
+  extractPositionInfo,
+  pushClickEvent,
+} from './data-layer';
+import {
+  parseMerkleFromElement,
+  findNearestMerkleElement,
+} from './merkle-tree';
+import { getESIContextSnapshot } from './context-bridge';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ClickHandler {
+  listener: (event: MouseEvent) => void;
+  cleanup: () => void;
+}
+
+// ============================================================================
+// State
+// ============================================================================
+
+/** Active click handler */
+let activeHandler: ClickHandler | null = null;
+
+/** Debounce timer */
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Last click timestamp for debouncing */
+let lastClickTime = 0;
+
+// ============================================================================
+// Click Handler
+// ============================================================================
+
+/**
+ * Check if element should be excluded from tracking
+ */
+function shouldExclude(
+  element: HTMLElement,
+  excludeSelectors: string[],
+): boolean {
+  for (const selector of excludeSelectors) {
+    if (element.matches(selector) || element.closest(selector)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Create click event handler
+ */
+function createClickHandler(
+  config: AnalyticsConfig,
+  options: ClickTrackingOptions,
+): (event: MouseEvent) => void {
+  return (event: MouseEvent) => {
+    const target = event.target as HTMLElement;
+
+    if (!target || !(target instanceof HTMLElement)) {
+      return;
+    }
+
+    // Check exclusions
+    if (options.excludeSelectors?.length) {
+      if (shouldExclude(target, options.excludeSelectors)) {
+        return;
+      }
+    }
+
+    // Debounce if configured
+    if (options.debounceMs && options.debounceMs > 0) {
+      const now = Date.now();
+      if (now - lastClickTime < options.debounceMs) {
+        return;
+      }
+      lastClickTime = now;
+    }
+
+    // Find nearest element with Merkle attributes
+    const merkleElement = findNearestMerkleElement(target);
+
+    // Parse Merkle info
+    let merkleHash = 'unknown';
+    let treePath: string[] = [];
+    let treePathHashes: string[] = [];
+
+    if (merkleElement) {
+      const merkleInfo = parseMerkleFromElement(merkleElement);
+      if (merkleInfo) {
+        merkleHash = merkleInfo.hash;
+        treePath = options.includeTreePath !== false ? merkleInfo.path : [];
+        treePathHashes =
+          options.includeTreePath !== false ? merkleInfo.pathHashes : [];
+      }
+    } else {
+      // No Merkle element found - generate path from DOM structure
+      treePath = generateDOMPath(target);
+    }
+
+    // Extract element info (from clicked element, not Merkle ancestor)
+    const elementInfo = extractElementInfo(target, options.maxTextLength);
+
+    // Extract position if enabled
+    const position =
+      options.includePosition !== false
+        ? extractPositionInfo(event)
+        : { x: 0, y: 0, viewportX: 0, viewportY: 0 };
+
+    // Get ESI context snapshot
+    const context = getESIContextSnapshot();
+
+    // Push to dataLayer
+    pushClickEvent(
+      merkleHash,
+      treePath,
+      treePathHashes,
+      elementInfo,
+      position,
+      context,
+      {
+        dataLayerName: config.dataLayerName,
+        eventPrefix: config.eventPrefix,
+      },
+    );
+  };
+}
+
+/**
+ * Generate DOM path for elements without Merkle attributes
+ */
+function generateDOMPath(element: HTMLElement): string[] {
+  const path: string[] = [];
+  let current: HTMLElement | null = element;
+
+  while (current && current !== document.body) {
+    let identifier = current.tagName.toLowerCase();
+
+    // Add ID if present
+    if (current.id) {
+      identifier += `#${current.id}`;
+    }
+    // Or first meaningful class
+    else if (current.className && typeof current.className === 'string') {
+      const classes = current.className.split(' ').filter(Boolean);
+      const meaningfulClass = classes.find(
+        (c) => !c.startsWith('_') && !c.match(/^[a-z]{1,3}\d+/),
+      );
+      if (meaningfulClass) {
+        identifier += `.${meaningfulClass}`;
+      }
+    }
+
+    path.unshift(identifier);
+    current = current.parentElement;
+  }
+
+  // Limit depth
+  if (path.length > 10) {
+    return ['...', ...path.slice(-9)];
+  }
+
+  return path;
+}
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+/**
+ * Initialize click tracking
+ */
+export function initClickTracker(config: AnalyticsConfig): () => void {
+  // Skip if disabled
+  if (config.trackClicks === false) {
+    return () => {};
+  }
+
+  // Clean up existing handler
+  if (activeHandler) {
+    activeHandler.cleanup();
+  }
+
+  const options: ClickTrackingOptions = {
+    debounceMs: 0,
+    maxTextLength: 100,
+    excludeSelectors: [],
+    includePosition: true,
+    includeTreePath: true,
+    ...config.clickOptions,
+  };
+
+  // Create handler
+  const listener = createClickHandler(config, options);
+
+  // Add event listener with capture for earliest interception
+  document.addEventListener('click', listener, {
+    capture: true,
+    passive: true,
+  });
+
+  // Cleanup function
+  const cleanup = () => {
+    document.removeEventListener('click', listener, { capture: true });
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+
+    activeHandler = null;
+  };
+
+  activeHandler = { listener, cleanup };
+
+  return cleanup;
+}
+
+/**
+ * Stop click tracking
+ */
+export function stopClickTracker(): void {
+  if (activeHandler) {
+    activeHandler.cleanup();
+  }
+}
+
+/**
+ * Check if click tracking is active
+ */
+export function isClickTrackerActive(): boolean {
+  return activeHandler !== null;
+}
+
+// ============================================================================
+// Manual Tracking
+// ============================================================================
+
+/**
+ * Manually track a click event
+ * Useful for custom elements or programmatic clicks
+ */
+export function trackClick(
+  element: HTMLElement,
+  event?: MouseEvent,
+  config?: Pick<
+    AnalyticsConfig,
+    'dataLayerName' | 'eventPrefix' | 'clickOptions'
+  >,
+): void {
+  const options = config?.clickOptions || {};
+
+  // Find Merkle element
+  const merkleElement = findNearestMerkleElement(element);
+
+  let merkleHash = 'unknown';
+  let treePath: string[] = [];
+  let treePathHashes: string[] = [];
+
+  if (merkleElement) {
+    const merkleInfo = parseMerkleFromElement(merkleElement);
+    if (merkleInfo) {
+      merkleHash = merkleInfo.hash;
+      treePath = merkleInfo.path;
+      treePathHashes = merkleInfo.pathHashes;
+    }
+  } else {
+    treePath = generateDOMPath(element);
+  }
+
+  // Extract element info
+  const elementInfo = extractElementInfo(element, options.maxTextLength || 100);
+
+  // Extract position if event provided
+  const position = event
+    ? extractPositionInfo(event)
+    : { x: 0, y: 0, viewportX: 0, viewportY: 0 };
+
+  // Get context
+  const context = getESIContextSnapshot();
+
+  // Push to dataLayer
+  pushClickEvent(
+    merkleHash,
+    treePath,
+    treePathHashes,
+    elementInfo,
+    position,
+    context,
+    {
+      dataLayerName: config?.dataLayerName || 'dataLayer',
+      eventPrefix: config?.eventPrefix || 'aeon',
+    },
+  );
+}
+
+// ============================================================================
+// Custom Event Tracking
+// ============================================================================
+
+/**
+ * Track a custom interaction (not necessarily a click)
+ */
+export function trackInteraction(
+  name: string,
+  data: Record<string, unknown>,
+  element?: HTMLElement,
+  config?: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): void {
+  const context = getESIContextSnapshot();
+
+  let treePath: string[] = [];
+  let merkleHash = 'none';
+
+  if (element) {
+    const merkleElement = findNearestMerkleElement(element);
+    if (merkleElement) {
+      const merkleInfo = parseMerkleFromElement(merkleElement);
+      if (merkleInfo) {
+        merkleHash = merkleInfo.hash;
+        treePath = merkleInfo.path;
+      }
+    } else {
+      treePath = generateDOMPath(element);
+    }
+  }
+
+  const dataLayerName = config?.dataLayerName || 'dataLayer';
+  const eventPrefix = config?.eventPrefix || 'aeon';
+
+  const event = {
+    event: `${eventPrefix}.interaction`,
+    aeon: {
+      version: '1.0.0',
+      timestamp: Date.now(),
+    },
+    interaction: {
+      name,
+      merkleHash,
+      treePath,
+      data,
+    },
+    context,
+  };
+
+  const w = window as unknown as Record<string, unknown[]>;
+  const dataLayer = w[dataLayerName];
+  if (dataLayer) {
+    dataLayer.push(event);
+  }
+}

package/packages/analytics/src/context-bridge.ts

@@ -0,0 +1,319 @@
+/**
+ * ESI Context Bridge
+ *
+ * Syncs ESI state from window.__AEON_ESI_STATE__ to GTM dataLayer.
+ * Handles initial sync and subscribes to state changes.
+ */
+
+import type { AnalyticsConfig, ESIState } from './types';
+import { pushContextEvent, pushPageViewEvent } from './data-layer';
+
+// ============================================================================
+// ESI State Access
+// ============================================================================
+
+/**
+ * Get current ESI state from window
+ */
+export function getESIState(): ESIState | null {
+  return window.__AEON_ESI_STATE__ || null;
+}
+
+/**
+ * Check if ESI state is available
+ */
+export function hasESIState(): boolean {
+  return !!window.__AEON_ESI_STATE__;
+}
+
+/**
+ * Get specific ESI state property
+ */
+export function getESIProperty<K extends keyof ESIState>(
+  key: K,
+): ESIState[K] | undefined {
+  const state = getESIState();
+  return state ? state[key] : undefined;
+}
+
+// ============================================================================
+// ESI State Subscription
+// ============================================================================
+
+/** Active subscription cleanup function */
+let unsubscribe: (() => void) | null = null;
+
+/**
+ * Subscribe to ESI state changes
+ */
+export function subscribeToESIChanges(
+  callback: (state: ESIState) => void,
+): () => void {
+  const state = window.__AEON_ESI_STATE__;
+
+  if (state?.subscribe) {
+    return state.subscribe(callback);
+  }
+
+  // No subscribe method available - return no-op
+  return () => {};
+}
+
+// ============================================================================
+// DataLayer Sync
+// ============================================================================
+
+/**
+ * Sync current ESI state to dataLayer
+ */
+export function syncESIToDataLayer(
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): boolean {
+  const esiState = getESIState();
+
+  if (!esiState) {
+    return false;
+  }
+
+  pushContextEvent(esiState, config);
+  return true;
+}
+
+/**
+ * Push page view with current ESI context
+ */
+export function pushPageView(
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+  merkleRoot = '',
+): boolean {
+  const esiState = getESIState();
+
+  if (!esiState) {
+    return false;
+  }
+
+  pushPageViewEvent(
+    window.location.pathname,
+    document.title,
+    merkleRoot,
+    esiState,
+    config,
+  );
+
+  return true;
+}
+
+// ============================================================================
+// Watch Mode
+// ============================================================================
+
+/**
+ * Start watching for ESI state changes and sync to dataLayer
+ */
+export function watchESIChanges(
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): () => void {
+  // Clean up any existing subscription
+  if (unsubscribe) {
+    unsubscribe();
+  }
+
+  // Subscribe to changes
+  unsubscribe = subscribeToESIChanges(() => {
+    syncESIToDataLayer(config);
+  });
+
+  return () => {
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+  };
+}
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+/**
+ * Initialize context bridge with full sync
+ */
+export function initContextBridge(
+  config: Pick<
+    AnalyticsConfig,
+    'dataLayerName' | 'eventPrefix' | 'syncESIContext'
+  >,
+): () => void {
+  if (config.syncESIContext === false) {
+    return () => {};
+  }
+
+  // Initial sync
+  syncESIToDataLayer(config);
+
+  // Watch for changes
+  return watchESIChanges(config);
+}
+
+// ============================================================================
+// Retry Logic
+// ============================================================================
+
+/**
+ * Wait for ESI state to be available
+ */
+export function waitForESIState(timeout = 5000): Promise<ESIState | null> {
+  return new Promise((resolve) => {
+    // Check immediately
+    const state = getESIState();
+    if (state) {
+      resolve(state);
+      return;
+    }
+
+    const startTime = Date.now();
+
+    const check = () => {
+      const state = getESIState();
+      if (state) {
+        resolve(state);
+        return;
+      }
+
+      if (Date.now() - startTime > timeout) {
+        resolve(null);
+        return;
+      }
+
+      requestAnimationFrame(check);
+    };
+
+    check();
+  });
+}
+
+/**
+ * Initialize context bridge with retry
+ */
+export async function initContextBridgeWithRetry(
+  config: Pick<
+    AnalyticsConfig,
+    'dataLayerName' | 'eventPrefix' | 'syncESIContext'
+  >,
+  timeout = 5000,
+): Promise<() => void> {
+  if (config.syncESIContext === false) {
+    return () => {};
+  }
+
+  // Wait for ESI state
+  const state = await waitForESIState(timeout);
+
+  if (!state) {
+    console.warn('[Aeon Analytics] ESI state not available after timeout');
+    return () => {};
+  }
+
+  // Now initialize
+  return initContextBridge(config);
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Get partial ESI state for click events
+ */
+export function getESIContextSnapshot(): Partial<ESIState> {
+  const state = getESIState();
+
+  if (!state) {
+    return {};
+  }
+
+  // Return relevant context for click tracking
+  return {
+    userTier: state.userTier,
+    isAdmin: state.isAdmin,
+    userId: state.userId,
+    sessionId: state.sessionId,
+    isNewSession: state.isNewSession,
+    emotionState: state.emotionState,
+    features: state.features,
+    viewport: state.viewport,
+    connection: state.connection,
+    localHour: state.localHour,
+    timezone: state.timezone,
+  };
+}
+
+/**
+ * Check if current user is an admin
+ * Admins bypass all tier restrictions
+ */
+export function isAdmin(): boolean {
+  const state = getESIState();
+  return state?.isAdmin === true || state?.userTier === 'admin';
+}
+
+/**
+ * Check if user has specific feature enabled
+ * Admins always have access to all features
+ */
+export function hasFeature(feature: keyof ESIState['features']): boolean {
+  const state = getESIState();
+
+  // Admins bypass all tier restrictions
+  if (state?.isAdmin === true || state?.userTier === 'admin') {
+    return true;
+  }
+
+  return state?.features?.[feature] ?? false;
+}
+
+/**
+ * Check if user meets minimum tier requirement
+ * Admins always meet any tier requirement
+ */
+export function meetsTierRequirement(
+  requiredTier: ESIState['userTier'],
+): boolean {
+  const state = getESIState();
+
+  if (!state) {
+    return false;
+  }
+
+  // Admins bypass all tier restrictions
+  if (state.isAdmin === true || state.userTier === 'admin') {
+    return true;
+  }
+
+  // Tier hierarchy: free < starter < pro < enterprise
+  const tierOrder: ESIState['userTier'][] = [
+    'free',
+    'starter',
+    'pro',
+    'enterprise',
+    'admin',
+  ];
+  const userTierIndex = tierOrder.indexOf(state.userTier);
+  const requiredTierIndex = tierOrder.indexOf(requiredTier);
+
+  return userTierIndex >= requiredTierIndex;
+}
+
+/**
+ * Get user tier
+ */
+export function getUserTier(): ESIState['userTier'] | null {
+  return getESIProperty('userTier') ?? null;
+}
+
+/**
+ * Get emotion state
+ */
+export function getEmotionState(): ESIState['emotionState'] | null {
+  return getESIProperty('emotionState') ?? null;
+}