@affectively/aeon-pages 1.3.0

package/packages/analytics/src/provider.tsx

@@ -0,0 +1,300 @@
+/**
+ * Aeon Analytics Provider
+ *
+ * React context provider for analytics configuration.
+ * Wraps useAeonAnalytics in a provider pattern for easier usage.
+ */
+
+import React, { createContext, useContext, useMemo } from 'react';
+import type { AnalyticsConfig, MerkleTree } from './types';
+import { useAeonAnalytics, type UseAnalyticsReturn } from './use-analytics';
+
+// ============================================================================
+// Context
+// ============================================================================
+
+interface AnalyticsContextValue extends UseAnalyticsReturn {
+  config: AnalyticsConfig;
+}
+
+const AnalyticsContext = createContext<AnalyticsContextValue | null>(null);
+
+// ============================================================================
+// Provider Props
+// ============================================================================
+
+export interface AeonAnalyticsProviderProps extends AnalyticsConfig {
+  children: React.ReactNode;
+}
+
+// ============================================================================
+// Provider Component
+// ============================================================================
+
+/**
+ * Aeon Analytics Provider
+ *
+ * Wrap your app with this provider to enable automatic click tracking.
+ *
+ * @example
+ * ```tsx
+ * import { AeonAnalyticsProvider } from '@affectively/aeon-pages-analytics/react';
+ *
+ * export default function App({ Component, pageProps }) {
+ *   return (
+ *     <AeonAnalyticsProvider
+ *       gtmContainerId="GTM-XXXXXX"
+ *       trackClicks={true}
+ *       syncESIContext={true}
+ *     >
+ *       <Component {...pageProps} />
+ *     </AeonAnalyticsProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AeonAnalyticsProvider({
+  children,
+  ...config
+}: AeonAnalyticsProviderProps): React.JSX.Element {
+  // Initialize analytics
+  const analytics = useAeonAnalytics(config);
+
+  // Memoize context value
+  const contextValue = useMemo<AnalyticsContextValue>(
+    () => ({
+      ...analytics,
+      config,
+    }),
+    [
+      analytics.isInitialized,
+      analytics.isGTMReady,
+      config.gtmContainerId,
+      config.trackClicks,
+      config.trackPageViews,
+      config.syncESIContext,
+    ],
+  );
+
+  return (
+    <AnalyticsContext.Provider value={contextValue}>
+      {children}
+    </AnalyticsContext.Provider>
+  );
+}
+
+// ============================================================================
+// Hook to use Analytics Context
+// ============================================================================
+
+/**
+ * Use analytics context in a component
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { trackClick, trackInteraction } = useAnalytics();
+ *
+ *   return (
+ *     <button onClick={(e) => trackInteraction('custom_action', { value: 123 })}>
+ *       Track Me
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useAnalytics(): AnalyticsContextValue {
+  const context = useContext(AnalyticsContext);
+
+  if (!context) {
+    throw new Error(
+      'useAnalytics must be used within an AeonAnalyticsProvider. ' +
+        'Wrap your app with <AeonAnalyticsProvider gtmContainerId="GTM-XXXXXX">.',
+    );
+  }
+
+  return context;
+}
+
+/**
+ * Optional analytics context (returns null if not in provider)
+ */
+export function useAnalyticsOptional(): AnalyticsContextValue | null {
+  return useContext(AnalyticsContext);
+}
+
+// ============================================================================
+// Higher-Order Component
+// ============================================================================
+
+/**
+ * HOC to inject analytics props into a component
+ */
+export function withAnalytics<P extends object>(
+  Component: React.ComponentType<P & { analytics: AnalyticsContextValue }>,
+): React.FC<P> {
+  return function WrappedComponent(props: P) {
+    const analytics = useAnalytics();
+    return <Component {...props} analytics={analytics} />;
+  };
+}
+
+// ============================================================================
+// Render Props Component
+// ============================================================================
+
+interface AnalyticsRenderProps {
+  children: (analytics: AnalyticsContextValue) => React.ReactNode;
+}
+
+/**
+ * Render props component for analytics
+ *
+ * @example
+ * ```tsx
+ * <Analytics>
+ *   {({ trackInteraction }) => (
+ *     <button onClick={() => trackInteraction('click', {})}>
+ *       Click me
+ *     </button>
+ *   )}
+ * </Analytics>
+ * ```
+ */
+export function Analytics({ children }: AnalyticsRenderProps): React.ReactNode {
+  const analytics = useAnalytics();
+  return children(analytics);
+}
+
+// ============================================================================
+// Merkle Tree Provider
+// ============================================================================
+
+interface MerkleTreeProviderProps {
+  tree: MerkleTree;
+  children: React.ReactNode;
+}
+
+/**
+ * Provide Merkle tree for current page
+ *
+ * Use this when you have a Merkle tree from SSR/build time.
+ */
+export function MerkleTreeProvider({
+  tree,
+  children,
+}: MerkleTreeProviderProps): React.JSX.Element {
+  const analytics = useAnalyticsOptional();
+
+  // Set Merkle tree on mount
+  React.useEffect(() => {
+    if (analytics) {
+      analytics.setMerkleTree(tree);
+    } else {
+      // No provider, set directly on window
+      window.__AEON_MERKLE_TREE__ = tree;
+    }
+  }, [tree, analytics]);
+
+  return <>{children}</>;
+}
+
+// ============================================================================
+// Track Component
+// ============================================================================
+
+interface TrackProps {
+  /** Tracking event name */
+  event: string;
+  /** Additional data to track */
+  data?: Record<string, unknown>;
+  /** Track on mount */
+  onMount?: boolean;
+  /** Track on click */
+  onClick?: boolean;
+  /** Track on visibility */
+  onVisible?: boolean;
+  /** Children to render */
+  children: React.ReactElement;
+}
+
+/**
+ * Wrapper component that automatically tracks events
+ *
+ * @example
+ * ```tsx
+ * <Track event="cta_view" onVisible data={{ variant: 'A' }}>
+ *   <button>Sign Up</button>
+ * </Track>
+ * ```
+ */
+export function Track({
+  event,
+  data = {},
+  onMount = false,
+  onClick = false,
+  onVisible = false,
+  children,
+}: TrackProps): React.ReactElement {
+  const analytics = useAnalyticsOptional();
+  const ref = React.useRef<HTMLElement>(null);
+  const hasTrackedVisibility = React.useRef(false);
+
+  // Track on mount
+  React.useEffect(() => {
+    if (onMount && analytics) {
+      analytics.trackInteraction(event, { ...data, trigger: 'mount' });
+    }
+  }, [onMount, event]);
+
+  // Track on visibility
+  React.useEffect(() => {
+    if (!onVisible || !analytics || hasTrackedVisibility.current) {
+      return;
+    }
+
+    const element = ref.current;
+    if (!element) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting && !hasTrackedVisibility.current) {
+            hasTrackedVisibility.current = true;
+            analytics.trackInteraction(
+              event,
+              { ...data, trigger: 'visible' },
+              element,
+            );
+            observer.disconnect();
+          }
+        }
+      },
+      { threshold: 0.5 },
+    );
+
+    observer.observe(element);
+
+    return () => observer.disconnect();
+  }, [onVisible, event, analytics]);
+
+  // Clone child with click handler
+  if (onClick && analytics) {
+    return React.cloneElement(children, {
+      ref,
+      onClick: (e: React.MouseEvent<HTMLElement>) => {
+        analytics.trackInteraction(
+          event,
+          { ...data, trigger: 'click' },
+          e.currentTarget,
+        );
+        // Call original onClick if exists
+        if (children.props.onClick) {
+          children.props.onClick(e);
+        }
+      },
+    });
+  }
+
+  return React.cloneElement(children, { ref });
+}

package/packages/analytics/src/types.ts

@@ -0,0 +1,320 @@
+/**
+ * Aeon Analytics Types
+ *
+ * TypeScript interfaces for automatic click tracking, GTM integration,
+ * and Merkle tree-based node identification.
+ */
+
+// ============================================================================
+// GTM Configuration
+// ============================================================================
+
+export interface GTMConfig {
+  /** GTM Container ID (e.g., 'GTM-XXXXXX') */
+  containerId: string;
+
+  /** Defer script loading (default: true) */
+  defer?: boolean;
+
+  /** Custom dataLayer name (default: 'dataLayer') */
+  dataLayerName?: string;
+}
+
+// ============================================================================
+// Analytics Configuration
+// ============================================================================
+
+export interface ClickTrackingOptions {
+  /** Debounce rapid clicks in milliseconds (default: 0) */
+  debounceMs?: number;
+
+  /** Max text length to capture (default: 100) */
+  maxTextLength?: number;
+
+  /** CSS selectors to exclude from tracking */
+  excludeSelectors?: string[];
+
+  /** Include click position data (default: true) */
+  includePosition?: boolean;
+
+  /** Include full tree path (default: true) */
+  includeTreePath?: boolean;
+}
+
+export interface AnalyticsConfig {
+  /** Required: GTM container ID */
+  gtmContainerId: string;
+
+  /** Enable click tracking (default: true) */
+  trackClicks?: boolean;
+
+  /** Enable page view tracking (default: true) */
+  trackPageViews?: boolean;
+
+  /** Sync ESI context to dataLayer (default: true) */
+  syncESIContext?: boolean;
+
+  /** Click tracking options */
+  clickOptions?: ClickTrackingOptions;
+
+  /** Custom dataLayer name (default: 'dataLayer') */
+  dataLayerName?: string;
+
+  /** Event name prefix (default: 'aeon') */
+  eventPrefix?: string;
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+// ============================================================================
+// Merkle Tree Types
+// ============================================================================
+
+export interface MerkleNode {
+  /** SHA-256 hash truncated to 12 characters */
+  hash: string;
+
+  /** Original node ID from ComponentTree */
+  originalId: string;
+
+  /** Component type name */
+  type: string;
+
+  /** Component props (sanitized for hashing) */
+  props: Record<string, unknown>;
+
+  /** Child Merkle hashes */
+  childHashes: string[];
+
+  /** Ancestry path from root (node types) */
+  path: string[];
+
+  /** Ancestry path hashes */
+  pathHashes: string[];
+
+  /** Depth in tree (0 = root) */
+  depth: number;
+}
+
+export interface MerkleTree {
+  /** Root hash of the entire tree */
+  rootHash: string;
+
+  /** Map of original node ID to MerkleNode */
+  nodes: Map<string, MerkleNode>;
+
+  /** Get MerkleNode by original ID */
+  getNode(id: string): MerkleNode | undefined;
+
+  /** Get MerkleNode by hash */
+  getNodeByHash(hash: string): MerkleNode | undefined;
+
+  /** Get all nodes at a depth level */
+  getNodesAtDepth(depth: number): MerkleNode[];
+}
+
+// ============================================================================
+// DOM Attributes
+// ============================================================================
+
+/** Data attribute for Merkle hash */
+export const MERKLE_ATTR = 'data-aeon-merkle';
+
+/** Data attribute for tree path */
+export const PATH_ATTR = 'data-aeon-path';
+
+/** Data attribute for tree path hashes */
+export const PATH_HASHES_ATTR = 'data-aeon-path-hashes';
+
+/** Data attribute for node type */
+export const TYPE_ATTR = 'data-aeon-type';
+
+// ============================================================================
+// ESI State Types (mirrored from runtime for standalone usage)
+// ============================================================================
+
+export type UserTier = 'free' | 'starter' | 'pro' | 'enterprise' | 'admin';
+export type ConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'fast';
+
+export interface EmotionState {
+  primary: string;
+  valence: number;
+  arousal: number;
+  confidence?: number;
+}
+
+export interface ESIStateFeatures {
+  aiInference: boolean;
+  emotionTracking: boolean;
+  collaboration: boolean;
+  advancedInsights: boolean;
+  customThemes: boolean;
+  voiceSynthesis: boolean;
+  imageAnalysis: boolean;
+}
+
+export interface ESIState {
+  userTier: UserTier;
+  /** Admin flag - bypasses all tier restrictions */
+  isAdmin?: boolean;
+  emotionState?: EmotionState;
+  preferences: {
+    theme?: 'light' | 'dark' | 'auto';
+    reducedMotion: boolean;
+    language?: string;
+  };
+  sessionId?: string;
+  localHour: number;
+  timezone: string;
+  features: ESIStateFeatures;
+  userId?: string;
+  isNewSession: boolean;
+  recentPages: string[];
+  viewport: { width: number; height: number };
+  connection: ConnectionType;
+}
+
+// ============================================================================
+// DataLayer Event Types
+// ============================================================================
+
+export interface AeonEventBase {
+  event: string;
+  aeon: {
+    version: string;
+    timestamp: number;
+  };
+}
+
+export interface ElementInfo {
+  tagName: string;
+  text: string;
+  ariaLabel?: string;
+  role?: string;
+  href?: string;
+  id?: string;
+  className?: string;
+}
+
+export interface PositionInfo {
+  x: number;
+  y: number;
+  viewportX: number;
+  viewportY: number;
+}
+
+export interface ContextEvent extends AeonEventBase {
+  event: 'aeon.context';
+  user: {
+    tier: UserTier;
+    id?: string;
+    sessionId?: string;
+    isNewSession: boolean;
+  };
+  emotion?: EmotionState;
+  preferences: {
+    theme?: 'light' | 'dark' | 'auto';
+    reducedMotion: boolean;
+    language?: string;
+  };
+  features: ESIStateFeatures;
+  device: {
+    viewport: { width: number; height: number };
+    connection: ConnectionType;
+  };
+  time: {
+    localHour: number;
+    timezone: string;
+  };
+  recentPages: string[];
+}
+
+export interface PageViewEvent extends AeonEventBase {
+  event: 'aeon.pageview';
+  page: {
+    path: string;
+    title: string;
+    merkleRoot: string;
+  };
+  user: {
+    tier: UserTier;
+    id?: string;
+    sessionId?: string;
+    isNewSession: boolean;
+  };
+  emotion?: EmotionState;
+  features: ESIStateFeatures;
+  device: {
+    viewport: { width: number; height: number };
+    connection: ConnectionType;
+    reducedMotion: boolean;
+  };
+  time: {
+    localHour: number;
+    timezone: string;
+  };
+}
+
+export interface ClickEvent extends AeonEventBase {
+  event: 'aeon.click';
+  click: {
+    merkleHash: string;
+    treePath: string[];
+    treePathHashes: string[];
+    element: ElementInfo;
+    position: PositionInfo;
+  };
+  context: Partial<ESIState>;
+}
+
+export type DataLayerEvent = ContextEvent | PageViewEvent | ClickEvent;
+
+// ============================================================================
+// Window Extensions
+// ============================================================================
+
+declare global {
+  interface Window {
+    __AEON_ESI_STATE__?: ESIState & {
+      update?: (partial: Partial<ESIState>) => void;
+      subscribe?: (listener: (state: ESIState) => void) => () => void;
+    };
+    dataLayer?: unknown[];
+    __AEON_MERKLE_TREE__?: MerkleTree;
+    __AEON_ANALYTICS_INITIALIZED__?: boolean;
+  }
+}
+
+// ============================================================================
+// Component Tree Types (for build-time integration)
+// ============================================================================
+
+export interface ComponentNode {
+  id: string;
+  type: string;
+  props?: Record<string, unknown>;
+  children?: string[];
+  requiredTier?: UserTier;
+  relevanceSignals?: string[];
+  defaultHidden?: boolean;
+}
+
+export interface ComponentTree {
+  rootId: string;
+  nodes: Map<string, ComponentNode>;
+  getNode(id: string): ComponentNode | undefined;
+  getChildren(id: string): ComponentNode[];
+}
+
+// ============================================================================
+// Serialized Types (for data attributes)
+// ============================================================================
+
+export interface SerializedMerkleInfo {
+  hash: string;
+  path: string[];
+  pathHashes: string[];
+  type: string;
+  depth: number;
+}