@affectively/aeon-pages 1.3.0

package/packages/analytics/src/data-layer.ts

@@ -0,0 +1,302 @@
+/**
+ * GTM dataLayer Integration
+ *
+ * Manages the dataLayer array and provides typed event pushing.
+ * Ensures dataLayer exists and handles event formatting.
+ */
+
+import type {
+  AnalyticsConfig,
+  AeonEventBase,
+  ContextEvent,
+  PageViewEvent,
+  ClickEvent,
+  DataLayerEvent,
+  ESIState,
+  ElementInfo,
+  PositionInfo,
+} from './types';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Current analytics version */
+export const ANALYTICS_VERSION = '1.0.0';
+
+// ============================================================================
+// dataLayer Management
+// ============================================================================
+
+/**
+ * Ensure dataLayer array exists on window
+ */
+export function ensureDataLayer(name = 'dataLayer'): unknown[] {
+  const w = window as unknown as Record<string, unknown>;
+
+  if (!w[name]) {
+    w[name] = [];
+  }
+
+  return w[name] as unknown[];
+}
+
+/**
+ * Push event to dataLayer
+ */
+export function pushToDataLayer(
+  event: DataLayerEvent,
+  dataLayerName = 'dataLayer',
+): void {
+  const dataLayer = ensureDataLayer(dataLayerName);
+  dataLayer.push(event);
+
+  // Debug logging
+  if (
+    (window as Window & { __AEON_ANALYTICS_DEBUG__?: boolean })
+      .__AEON_ANALYTICS_DEBUG__
+  ) {
+    console.log('[Aeon Analytics]', event.event, event);
+  }
+}
+
+// ============================================================================
+// Event Builders
+// ============================================================================
+
+/**
+ * Create base event structure
+ */
+function createBaseEvent(eventName: string, prefix = 'aeon'): AeonEventBase {
+  return {
+    event: prefix ? `${prefix}.${eventName}` : eventName,
+    aeon: {
+      version: ANALYTICS_VERSION,
+      timestamp: Date.now(),
+    },
+  };
+}
+
+/**
+ * Build context event from ESI state
+ */
+export function buildContextEvent(
+  esiState: ESIState,
+  prefix = 'aeon',
+): ContextEvent {
+  return {
+    ...createBaseEvent('context', prefix),
+    event: `${prefix}.context` as 'aeon.context',
+    user: {
+      tier: esiState.userTier,
+      id: esiState.userId,
+      sessionId: esiState.sessionId,
+      isNewSession: esiState.isNewSession,
+    },
+    emotion: esiState.emotionState,
+    preferences: esiState.preferences,
+    features: esiState.features,
+    device: {
+      viewport: esiState.viewport,
+      connection: esiState.connection,
+    },
+    time: {
+      localHour: esiState.localHour,
+      timezone: esiState.timezone,
+    },
+    recentPages: esiState.recentPages,
+  };
+}
+
+/**
+ * Build page view event
+ */
+export function buildPageViewEvent(
+  path: string,
+  title: string,
+  merkleRoot: string,
+  esiState: ESIState,
+  prefix = 'aeon',
+): PageViewEvent {
+  return {
+    ...createBaseEvent('pageview', prefix),
+    event: `${prefix}.pageview` as 'aeon.pageview',
+    page: {
+      path,
+      title,
+      merkleRoot,
+    },
+    user: {
+      tier: esiState.userTier,
+      id: esiState.userId,
+      sessionId: esiState.sessionId,
+      isNewSession: esiState.isNewSession,
+    },
+    emotion: esiState.emotionState,
+    features: esiState.features,
+    device: {
+      viewport: esiState.viewport,
+      connection: esiState.connection,
+      reducedMotion: esiState.preferences.reducedMotion,
+    },
+    time: {
+      localHour: esiState.localHour,
+      timezone: esiState.timezone,
+    },
+  };
+}
+
+/**
+ * Build click event
+ */
+export function buildClickEvent(
+  merkleHash: string,
+  treePath: string[],
+  treePathHashes: string[],
+  element: ElementInfo,
+  position: PositionInfo,
+  context: Partial<ESIState>,
+  prefix = 'aeon',
+): ClickEvent {
+  return {
+    ...createBaseEvent('click', prefix),
+    event: `${prefix}.click` as 'aeon.click',
+    click: {
+      merkleHash,
+      treePath,
+      treePathHashes,
+      element,
+      position,
+    },
+    context,
+  };
+}
+
+// ============================================================================
+// Element Info Extraction
+// ============================================================================
+
+/**
+ * Extract element info for tracking
+ */
+export function extractElementInfo(
+  element: HTMLElement,
+  maxTextLength = 100,
+): ElementInfo {
+  // Get text content, truncated
+  let text = element.innerText || element.textContent || '';
+  if (text.length > maxTextLength) {
+    text = text.slice(0, maxTextLength) + '...';
+  }
+  // Clean whitespace
+  text = text.replace(/\s+/g, ' ').trim();
+
+  return {
+    tagName: element.tagName,
+    text,
+    ariaLabel: element.getAttribute('aria-label') || undefined,
+    role: element.getAttribute('role') || undefined,
+    href: (element as HTMLAnchorElement).href || undefined,
+    id: element.id || undefined,
+    className: element.className || undefined,
+  };
+}
+
+/**
+ * Extract position info from mouse event
+ */
+export function extractPositionInfo(event: MouseEvent): PositionInfo {
+  return {
+    x: event.pageX,
+    y: event.pageY,
+    viewportX: event.clientX,
+    viewportY: event.clientY,
+  };
+}
+
+// ============================================================================
+// Push Helpers
+// ============================================================================
+
+/**
+ * Push context event to dataLayer
+ */
+export function pushContextEvent(
+  esiState: ESIState,
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): void {
+  const event = buildContextEvent(esiState, config.eventPrefix);
+  pushToDataLayer(event, config.dataLayerName);
+}
+
+/**
+ * Push page view event to dataLayer
+ */
+export function pushPageViewEvent(
+  path: string,
+  title: string,
+  merkleRoot: string,
+  esiState: ESIState,
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): void {
+  const event = buildPageViewEvent(
+    path,
+    title,
+    merkleRoot,
+    esiState,
+    config.eventPrefix,
+  );
+  pushToDataLayer(event, config.dataLayerName);
+}
+
+/**
+ * Push click event to dataLayer
+ */
+export function pushClickEvent(
+  merkleHash: string,
+  treePath: string[],
+  treePathHashes: string[],
+  element: ElementInfo,
+  position: PositionInfo,
+  context: Partial<ESIState>,
+  config: Pick<AnalyticsConfig, 'dataLayerName' | 'eventPrefix'>,
+): void {
+  const event = buildClickEvent(
+    merkleHash,
+    treePath,
+    treePathHashes,
+    element,
+    position,
+    context,
+    config.eventPrefix,
+  );
+  pushToDataLayer(event, config.dataLayerName);
+}
+
+// ============================================================================
+// Debug Mode
+// ============================================================================
+
+/**
+ * Enable/disable debug logging
+ */
+export function setDebugMode(enabled: boolean): void {
+  (
+    window as Window & { __AEON_ANALYTICS_DEBUG__?: boolean }
+  ).__AEON_ANALYTICS_DEBUG__ = enabled;
+}
+
+/**
+ * Get current dataLayer contents (for debugging)
+ */
+export function getDataLayer(name = 'dataLayer'): unknown[] {
+  return ensureDataLayer(name);
+}
+
+/**
+ * Clear dataLayer (for testing)
+ */
+export function clearDataLayer(name = 'dataLayer'): void {
+  const w = window as unknown as Record<string, unknown>;
+  w[name] = [];
+}

package/packages/analytics/src/gtm-loader.ts

@@ -0,0 +1,239 @@
+/**
+ * GTM Script Loader
+ *
+ * Injects Google Tag Manager script and noscript iframe.
+ * Handles async loading and ensures proper initialization order.
+ */
+
+import type { GTMConfig } from './types';
+import { ensureDataLayer } from './data-layer';
+
+// ============================================================================
+// GTM Script Injection
+// ============================================================================
+
+/** Track if GTM has been injected */
+let gtmInjected = false;
+
+/**
+ * Generate GTM script inline code
+ */
+function generateGTMScript(containerId: string, dataLayerName: string): string {
+  return `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','${dataLayerName}','${containerId}');`;
+}
+
+/**
+ * Validate GTM container ID format
+ */
+function validateContainerId(containerId: string): boolean {
+  // GTM container ID format: GTM-XXXXXX (6-8 alphanumeric characters)
+  return /^GTM-[A-Z0-9]{6,8}$/i.test(containerId);
+}
+
+/**
+ * Inject GTM script into document head
+ */
+export function injectGTM(config: GTMConfig): boolean {
+  // Prevent double injection
+  if (gtmInjected) {
+    console.warn('[Aeon Analytics] GTM already injected');
+    return false;
+  }
+
+  // Validate container ID
+  if (!validateContainerId(config.containerId)) {
+    console.error(
+      `[Aeon Analytics] Invalid GTM container ID: ${config.containerId}. ` +
+        'Expected format: GTM-XXXXXX',
+    );
+    return false;
+  }
+
+  // Ensure dataLayer exists before GTM loads
+  const dataLayerName = config.dataLayerName || 'dataLayer';
+  ensureDataLayer(dataLayerName);
+
+  // Create and inject script element
+  const script = document.createElement('script');
+  script.innerHTML = generateGTMScript(config.containerId, dataLayerName);
+
+  // Insert at beginning of head for earliest execution
+  if (document.head.firstChild) {
+    document.head.insertBefore(script, document.head.firstChild);
+  } else {
+    document.head.appendChild(script);
+  }
+
+  gtmInjected = true;
+  return true;
+}
+
+/**
+ * Inject GTM noscript iframe into document body
+ * For tracking when JavaScript is disabled
+ */
+export function injectGTMNoScript(containerId: string): boolean {
+  // Validate container ID
+  if (!validateContainerId(containerId)) {
+    return false;
+  }
+
+  // Check if noscript already exists
+  const existingNoscript = document.querySelector(
+    `noscript iframe[src*="googletagmanager.com/ns.html?id=${containerId}"]`,
+  );
+  if (existingNoscript) {
+    return false;
+  }
+
+  // Create noscript element with iframe
+  const noscript = document.createElement('noscript');
+  const iframe = document.createElement('iframe');
+
+  iframe.src = `https://www.googletagmanager.com/ns.html?id=${containerId}`;
+  iframe.height = '0';
+  iframe.width = '0';
+  iframe.style.display = 'none';
+  iframe.style.visibility = 'hidden';
+
+  noscript.appendChild(iframe);
+
+  // Insert at beginning of body
+  if (document.body.firstChild) {
+    document.body.insertBefore(noscript, document.body.firstChild);
+  } else {
+    document.body.appendChild(noscript);
+  }
+
+  return true;
+}
+
+/**
+ * Initialize GTM with full configuration
+ */
+export function initializeGTM(config: GTMConfig): boolean {
+  const scriptInjected = injectGTM(config);
+
+  // Only inject noscript if script was successfully injected
+  if (scriptInjected) {
+    injectGTMNoScript(config.containerId);
+  }
+
+  return scriptInjected;
+}
+
+// ============================================================================
+// Server-Side Rendering Helpers
+// ============================================================================
+
+/**
+ * Generate GTM script tag for SSR
+ * Returns HTML string to inject into <head>
+ */
+export function generateGTMScriptTag(config: GTMConfig): string {
+  if (!validateContainerId(config.containerId)) {
+    return '';
+  }
+
+  const dataLayerName = config.dataLayerName || 'dataLayer';
+
+  return `<script>${generateGTMScript(config.containerId, dataLayerName)}</script>`;
+}
+
+/**
+ * Generate GTM noscript tag for SSR
+ * Returns HTML string to inject at start of <body>
+ */
+export function generateGTMNoScriptTag(containerId: string): string {
+  if (!validateContainerId(containerId)) {
+    return '';
+  }
+
+  return `<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=${containerId}" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>`;
+}
+
+/**
+ * Generate dataLayer initialization script for SSR
+ * Use this before GTM script to pre-populate data
+ */
+export function generateDataLayerScript(
+  initialData: Record<string, unknown>,
+  dataLayerName = 'dataLayer',
+): string {
+  const dataJson = JSON.stringify(initialData);
+  return `<script>window.${dataLayerName}=window.${dataLayerName}||[];window.${dataLayerName}.push(${dataJson});</script>`;
+}
+
+// ============================================================================
+// Status Helpers
+// ============================================================================
+
+/**
+ * Check if GTM has been injected
+ */
+export function isGTMInjected(): boolean {
+  return gtmInjected;
+}
+
+/**
+ * Check if GTM is loaded and ready
+ */
+export function isGTMReady(): boolean {
+  if (!gtmInjected) return false;
+
+  // Check for gtm.js event in dataLayer
+  const dataLayer = (window as Window & { dataLayer?: unknown[] }).dataLayer;
+  if (!dataLayer) return false;
+
+  return dataLayer.some(
+    (item) =>
+      typeof item === 'object' &&
+      item !== null &&
+      (item as Record<string, unknown>).event === 'gtm.js',
+  );
+}
+
+/**
+ * Wait for GTM to be ready
+ */
+export function waitForGTM(timeout = 5000): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (isGTMReady()) {
+      resolve(true);
+      return;
+    }
+
+    const startTime = Date.now();
+
+    const check = () => {
+      if (isGTMReady()) {
+        resolve(true);
+        return;
+      }
+
+      if (Date.now() - startTime > timeout) {
+        resolve(false);
+        return;
+      }
+
+      requestAnimationFrame(check);
+    };
+
+    check();
+  });
+}
+
+// ============================================================================
+// Reset (for testing)
+// ============================================================================
+
+/**
+ * Reset GTM injection state (for testing only)
+ */
+export function resetGTMState(): void {
+  gtmInjected = false;
+}