@cognior/iap-sdk 0.1.0

package/src/utils/flowTrackingSystem.ts

@@ -0,0 +1,524 @@
+// src/utils/flowTrackingSystem.ts
+// A comprehensive tracking system for flows that ensures consistent
+// tracking aligned with actual user flow navigation
+
+import { DapConfig } from '../config';
+
+// Define the core flow states
+export enum FlowState {
+  NOT_STARTED = 'not_started',
+  STARTED = 'started',
+  NAVIGATING = 'navigating',
+  COMPLETED = 'completed',
+  EXITED = 'exited'
+}
+
+// Define the core step states
+export enum StepState {
+  NOT_VISITED = 'not_visited',
+  ACTIVE = 'active',
+  COMPLETED = 'completed',
+  SKIPPED = 'skipped'
+}
+
+// Define an action type for tracking
+export enum TrackingAction {
+  FLOW_IMPRESSION = 'flow_impression',    // Flow is visible/loaded
+  FLOW_STARTED = 'flow_started',          // User actively started the flow (formerly flow_initialized/flow_initiation)
+  FLOW_INTERACTION = 'flow_interaction',  // User interacted with flow elements
+  STEP_TRANSITION = 'step_transition',    // User navigated between steps
+  STEP_COMPLETION = 'step_completion',    // User completed a step in the flow
+  FLOW_COMPLETED = 'flow_completed',      // User completed the flow (formerly flow_completion)
+  FLOW_EXITED = 'flow_exited',            // User exited without completion (formerly flow_exit)
+  FLOW_REENTRY = 'flow_reentry',          // User returned to a previously started flow
+  FLOW_SUBMISSION = 'flow_submission',    // User submitted a form within the flow
+  FLOW_INPUT_INTERACTION = 'flow_input_interaction', // User interacted with an input field
+  FLOW_TRANSITION = 'flow_transition',    // User transitioned between flows
+  CUSTOM_ACTION = 'custom_action'         // Special user actions like downloads or video plays
+}
+
+// Interface for tracking data
+export interface FlowTrackingInfo {
+  flowId: string;
+  state: FlowState;
+  startTime: number | null;
+  lastInteractionTime: number | null;
+  steps: Record<string, {
+    id: string;
+    state: StepState;
+    timeSpent: number;
+    interactions: number;
+    firstVisitTime: number | null;
+    lastVisitTime: number | null;
+  }>;
+  currentStepId: string | null;
+  previousStepId: string | null;
+  completedSteps: string[];
+  totalSteps: number;
+  completionPercentage: number;
+  isTransitioning: boolean;
+  targetFlowId: string | null;
+}
+
+// The global registry of flow tracking information
+const flowRegistry = new Map<string, FlowTrackingInfo>();
+
+// Track impressions that have been sent in the current session
+const sentImpressions = new Set<string>();
+
+/**
+ * Initialize tracking for a flow
+ * @param flowId The ID of the flow to track
+ * @returns The flow tracking information
+ */
+export function initializeFlowTracking(flowId: string): FlowTrackingInfo {
+  // Check if we already have tracking for this flow
+  const existingTracking = flowRegistry.get(flowId);
+  if (existingTracking) {
+    console.debug(`[DAP] Flow tracking already initialized for flow ${flowId}`);
+    return existingTracking;
+  }
+
+  console.debug(`[DAP] Initializing flow tracking for flow ${flowId}`);
+  
+  // Try to restore tracking from session storage
+  const restoredTracking = restoreFlowTracking(flowId);
+  if (restoredTracking) {
+    flowRegistry.set(flowId, restoredTracking);
+    console.debug(`[DAP] Restored flow tracking from session storage for flow ${flowId}`);
+    return restoredTracking;
+  }
+  
+  // Create new tracking if not found
+  const newTracking: FlowTrackingInfo = {
+    flowId,
+    state: FlowState.NOT_STARTED,
+    startTime: null,
+    lastInteractionTime: null,
+    steps: {},
+    currentStepId: null,
+    previousStepId: null,
+    completedSteps: [],
+    totalSteps: 0,
+    completionPercentage: 0,
+    isTransitioning: false,
+    targetFlowId: null
+  };
+  
+  flowRegistry.set(flowId, newTracking);
+  console.debug(`[DAP] Created new flow tracking for flow ${flowId}`);
+  
+  // Persist to session storage
+  persistFlowTracking(flowId);
+  
+  return newTracking;
+}
+
+/**
+ * Get tracking information for a flow
+ * @param flowId The ID of the flow
+ * @returns The flow tracking information, or null if not found
+ */
+export function getFlowTracking(flowId: string): FlowTrackingInfo | null {
+  return flowRegistry.get(flowId) || null;
+}
+
+/**
+ * Mark a flow as started
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param stepId The ID of the starting step
+ */
+export function startFlow(config: DapConfig, flowId: string, stepId: string): void {
+  const tracking = initializeFlowTracking(flowId);
+  
+  // Only track if the flow hasn't been started
+  if (tracking.state === FlowState.NOT_STARTED) {
+    tracking.state = FlowState.STARTED;
+    tracking.startTime = Date.now();
+    tracking.currentStepId = stepId;
+    
+    // Initialize the step if it doesn't exist
+    ensureStepExists(tracking, stepId);
+    
+    // Mark the step as active
+    tracking.steps[stepId].state = StepState.ACTIVE;
+    tracking.steps[stepId].firstVisitTime = Date.now();
+    tracking.steps[stepId].lastVisitTime = Date.now();
+    
+    // Persist changes
+    persistFlowTracking(flowId);
+    
+    // Legacy tracking disabled - using simple step tracking only
+    console.debug(`[DAP] Legacy tracking call disabled - Flow ${flowId} started with step ${stepId}`);
+    
+    console.debug(`[DAP] Flow ${flowId} started with step ${stepId}`);
+  }
+}
+
+/**
+ * Track a step transition within a flow
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param fromStepId The ID of the previous step
+ * @param toStepId The ID of the new step
+ */
+export function trackStepTransition(
+  config: DapConfig, 
+  flowId: string, 
+  fromStepId: string, 
+  toStepId: string
+): void {
+  const tracking = getFlowTracking(flowId);
+  if (!tracking) return;
+  
+  // Skip if flow is completed or exited
+  if (tracking.state === FlowState.COMPLETED || tracking.state === FlowState.EXITED) {
+    console.debug(`[DAP] Ignoring step transition for ${flowId}: flow already in state ${tracking.state}`);
+    return;
+  }
+  
+  // Update flow state to navigating
+  tracking.state = FlowState.NAVIGATING;
+  tracking.lastInteractionTime = Date.now();
+  
+  // Ensure from step exists and update it
+  ensureStepExists(tracking, fromStepId);
+  tracking.steps[fromStepId].state = StepState.COMPLETED;
+  
+  // Calculate time spent on previous step
+  if (tracking.steps[fromStepId].lastVisitTime !== null) {
+    tracking.steps[fromStepId].timeSpent += 
+      Date.now() - tracking.steps[fromStepId].lastVisitTime;
+  }
+  
+  // Ensure to step exists and update it
+  ensureStepExists(tracking, toStepId);
+  tracking.steps[toStepId].state = StepState.ACTIVE;
+  tracking.steps[toStepId].lastVisitTime = Date.now();
+  
+  // If this is the first visit, set first visit time
+  if (tracking.steps[toStepId].firstVisitTime === null) {
+    tracking.steps[toStepId].firstVisitTime = Date.now();
+  }
+  
+  // Update current and previous step
+  tracking.previousStepId = fromStepId;
+  tracking.currentStepId = toStepId;
+  
+  // Add completed step if not already there
+  if (!tracking.completedSteps.includes(fromStepId)) {
+    tracking.completedSteps.push(fromStepId);
+  }
+  
+  // Update completion percentage
+  tracking.completionPercentage = calculateCompletionPercentage(tracking);
+  
+  // Persist changes
+  persistFlowTracking(flowId);
+  
+  // Legacy tracking disabled - using simple step tracking only
+  console.debug(`[DAP] Legacy tracking call disabled - Flow ${flowId} transition from ${fromStepId} to ${toStepId}`);
+  
+  console.debug(`[DAP] Flow ${flowId} transition from ${fromStepId} to ${toStepId}`);
+}
+
+/**
+ * Track user interaction with a flow element
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param stepId The ID of the step
+ * @param selector The CSS selector for the element
+ * @param context Additional context
+ */
+export function trackInteraction(
+  config: DapConfig, 
+  flowId: string, 
+  stepId: string, 
+  selector?: string, 
+  context?: string
+): void {
+  const tracking = getFlowTracking(flowId);
+  if (!tracking) return;
+  
+  // Skip if already completed
+  if (tracking.state === FlowState.COMPLETED || tracking.state === FlowState.EXITED) {
+    return;
+  }
+  
+  // Ensure step exists
+  ensureStepExists(tracking, stepId);
+  
+  // Update interaction count
+  tracking.steps[stepId].interactions++;
+  tracking.lastInteractionTime = Date.now();
+  
+  // If flow not yet started, mark as started
+  if (tracking.state === FlowState.NOT_STARTED) {
+    startFlow(config, flowId, stepId);
+  }
+  
+  // Legacy tracking disabled - using simple step tracking only
+  if (selector) {
+    console.debug(`[DAP] Legacy tracking call disabled - Flow ${flowId} interaction on step ${stepId}:`, selector);
+  }
+  
+  // Persist changes
+  persistFlowTracking(flowId);
+}
+
+/**
+ * Track impression of a flow
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @returns True if impression was tracked, false if already tracked
+ */
+export function trackImpression(config: DapConfig, flowId: string): boolean {
+  // Initialize tracking
+  const flowTracking = initializeFlowTracking(flowId);
+  
+  // Don't track impression again if flow is already started or beyond
+  if (flowTracking.state !== FlowState.NOT_STARTED) {
+    console.debug(`[DAP] Skipping impression tracking for flow ${flowId} - already in state ${flowTracking.state}`);
+    return false;
+  }
+  
+  // Only send impression once per page load
+  if (sentImpressions.has(flowId)) {
+    return false;
+  }
+  
+  // Mark as sent
+  sentImpressions.add(flowId);
+  
+  // Legacy tracking disabled - using simple step tracking only
+  console.debug(`[DAP] Legacy tracking call disabled - Flow impression for ${flowId}`);
+  
+  console.debug(`[DAP] Flow impression tracked for ${flowId}`);
+  return true;
+}
+
+/**
+ * Mark a flow as completed
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param finalStepId The ID of the final step (optional)
+ */
+export function completeFlow(
+  config: DapConfig, 
+  flowId: string, 
+  finalStepId?: string
+): void {
+  const tracking = getFlowTracking(flowId);
+  if (!tracking) return;
+  
+  // Skip if already completed
+  if (tracking.state === FlowState.COMPLETED) {
+    console.debug(`[DAP] Flow ${flowId} already marked as completed`);
+    return;
+  }
+  
+  // Use provided final step or current step
+  const effectiveStepId = finalStepId || tracking.currentStepId;
+  if (!effectiveStepId) return;
+  
+  // Update flow state
+  tracking.state = FlowState.COMPLETED;
+  tracking.lastInteractionTime = Date.now();
+  
+  // Ensure the step exists
+  ensureStepExists(tracking, effectiveStepId);
+  
+  // Mark the final step as completed
+  tracking.steps[effectiveStepId].state = StepState.COMPLETED;
+  tracking.steps[effectiveStepId].lastVisitTime = Date.now();
+  
+  // Update completion data
+  if (!tracking.completedSteps.includes(effectiveStepId)) {
+    tracking.completedSteps.push(effectiveStepId);
+  }
+  tracking.completionPercentage = 100;
+  
+  // Persist changes
+  persistFlowTracking(flowId);
+  
+  // Always send completion event
+  const totalTime = tracking.startTime ? Date.now() - tracking.startTime : 0;
+  
+  // Legacy tracking disabled - using simple step tracking only
+  console.debug(`[DAP] Legacy tracking call disabled - Flow ${flowId} completed on step ${effectiveStepId}`);
+  
+  console.debug(`[DAP] Flow ${flowId} completed on step ${effectiveStepId}`);
+}
+
+/**
+ * Track flow exit
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param reason The reason for exiting
+ */
+export function exitFlow(
+  config: DapConfig, 
+  flowId: string, 
+  reason: string
+): void {
+  const tracking = getFlowTracking(flowId);
+  if (!tracking) return;
+  
+  // Skip if already completed or exited
+  if (tracking.state === FlowState.COMPLETED || tracking.state === FlowState.EXITED) {
+    return;
+  }
+  
+  // Update flow state
+  tracking.state = FlowState.EXITED;
+  tracking.lastInteractionTime = Date.now();
+  
+  // If we have a current step, update its data
+  if (tracking.currentStepId) {
+    const stepId = tracking.currentStepId;
+    ensureStepExists(tracking, stepId);
+    
+    // Update time spent on current step
+    if (tracking.steps[stepId].lastVisitTime !== null) {
+      tracking.steps[stepId].timeSpent += 
+        Date.now() - tracking.steps[stepId].lastVisitTime;
+    }
+  }
+  
+  // Persist changes
+  persistFlowTracking(flowId);
+  
+  // Legacy tracking disabled - using simple step tracking only
+  console.debug(`[DAP] Legacy tracking call disabled - Flow ${flowId} exited:`, reason);
+  
+  console.debug(`[DAP] Flow ${flowId} exited with reason: ${reason}`);
+}
+
+/**
+ * Track custom user actions within a flow (downloads, video plays, etc.)
+ * @param config The DAP configuration
+ * @param flowId The ID of the flow
+ * @param stepId The current step ID 
+ * @param actionName Name of the action (e.g. download or video_play)
+ * @param actionDetails Additional details about the action
+ */
+export function trackCustomAction(
+  config: DapConfig,
+  flowId: string, 
+  stepId: string,
+  actionName: string,
+  actionDetails: Record<string, any> = {}
+): void {
+  const tracking = getFlowTracking(flowId);
+  if (!tracking) return;
+  
+  // Legacy tracking disabled - using simple step tracking only
+  console.debug(`[DAP] Legacy tracking call disabled - Custom action "${actionName}" for flow ${flowId} at step ${stepId}`);
+  
+  console.debug(`[DAP] Custom action "${actionName}" tracked for flow ${flowId} at step ${stepId}`);
+}
+
+// Helper functions
+
+/**
+ * Ensure a step exists in the tracking object
+ */
+function ensureStepExists(tracking: FlowTrackingInfo, stepId: string): void {
+  if (!tracking.steps[stepId]) {
+    tracking.steps[stepId] = {
+      id: stepId,
+      state: StepState.NOT_VISITED,
+      firstVisitTime: null,
+      lastVisitTime: null,
+      timeSpent: 0,
+      interactions: 0
+    };
+  }
+}
+
+/**
+ * Get the element type from a selector
+ */
+function getElementType(selector?: string): string {
+  if (!selector) return 'unknown';
+  
+  // Try to extract element type from selector
+  const elementMatch = selector.match(/^([a-zA-Z0-9-]+)/);
+  return elementMatch ? elementMatch[1].toLowerCase() : 'unknown';
+}
+
+/**
+ * Persist flow tracking to session storage
+ */
+function persistFlowTracking(flowId: string): void {
+  const tracking = flowRegistry.get(flowId);
+  if (!tracking) return;
+  
+  try {
+    sessionStorage.setItem(`dap_flow_tracking_${flowId}`, JSON.stringify(tracking));
+  } catch (e) {
+    console.error(`[DAP] Error persisting flow tracking for ${flowId}:`, e);
+  }
+}
+
+/**
+ * Restore flow tracking from session storage
+ */
+function restoreFlowTracking(flowId: string): FlowTrackingInfo | null {
+  try {
+    const stored = sessionStorage.getItem(`dap_flow_tracking_${flowId}`);
+    if (!stored) return null;
+    
+    const parsed = JSON.parse(stored) as FlowTrackingInfo;
+    
+    // Convert steps back to proper structure (JSON stringification loses Map/Set)
+    const restoredTracking: FlowTrackingInfo = {
+      ...parsed,
+      completedSteps: parsed.completedSteps || []
+    };
+    
+    return restoredTracking;
+  } catch (e) {
+    console.error(`[DAP] Error restoring flow tracking for ${flowId}:`, e);
+    return null;
+  }
+}
+
+/**
+ * Calculate completion percentage
+ */
+function calculateCompletionPercentage(tracking: FlowTrackingInfo): number {
+  if (tracking.totalSteps === 0) return 0;
+  return Math.min(100, Math.round((tracking.completedSteps.length / tracking.totalSteps) * 100));
+}
+
+/**
+ * Get total interactions across all steps
+ */
+function getTotalInteractions(tracking: FlowTrackingInfo): number {
+  let total = 0;
+  Object.values(tracking.steps).forEach(step => {
+    total += step.interactions;
+  });
+  return total;
+}
+
+// Export the flow tracking system API
+export const flowTrackingSystem = {
+  initializeFlowTracking,
+  getFlowTracking,
+  trackImpression,
+  startFlow,
+  trackStepTransition,
+  completeFlow,
+  exitFlow,
+  trackCustomAction
+};
+
+// Initialize tracking system
+export function initializeFlowTrackingSystem(config: DapConfig, flowId: string) {
+  // Initialize tracking for the flow
+  initializeFlowTracking(flowId);
+  return flowTrackingSystem;
+}

package/src/utils/idGenerator.ts

@@ -0,0 +1,155 @@
+// src/utils/idGenerator.ts
+// Utility for consistent step ID generation and validation
+
+// Registry for mapping DOM elements to their step IDs
+const elementStepIdRegistry = new WeakMap<HTMLElement, string>();
+
+// Store the current flow ID for context
+let currentFlowContextId: string | null = null;
+
+/**
+ * Validates if a step ID is in the correct format
+ * @param stepId The step ID to validate
+ * @returns Whether the step ID is valid
+ */
+export function isValidStepId(stepId: string | null | undefined): boolean {
+  if (!stepId) return false;
+  
+  // Valid formats:
+  // 1. step-{number}
+  // 2. m{number}, t{number}, p{number}, s{number} (modal, tooltip, popover, survey)
+  // 3. Any alphanumeric string without special characters (except dash and underscore)
+  
+  const validPattern = /^(step-\d+|[mtps]\d+|[a-zA-Z0-9_-]+)$/;
+  return validPattern.test(stepId);
+}
+
+/**
+ * Generates a valid step ID
+ * @param prefix The prefix for the step ID (step by default)
+ * @param index The index of the step (optional)
+ * @returns A valid step ID
+ */
+export function generateStepId(prefix: string = 'step', index?: number): string {
+  if (index !== undefined) {
+    return `${prefix}-${index}`;
+  }
+  
+  // Generate a deterministic step ID with timestamp and random suffix
+  const timestamp = Date.now().toString(36);
+  const randomSuffix = Math.random().toString(36).substring(2, 6);
+  
+  return `${prefix}-${timestamp}${randomSuffix}`;
+}
+
+/**
+ * Normalizes a step ID to ensure it follows the correct format
+ * @param stepId The step ID to normalize
+ * @param fallbackPrefix The prefix to use if a new ID needs to be generated
+ * @param index The index to use in the fallback ID
+ * @returns A normalized step ID
+ */
+export function normalizeStepId(stepId: string | null | undefined, fallbackPrefix: string = 'step', index?: number): string {
+  if (isValidStepId(stepId)) {
+    return stepId as string;
+  }
+  
+  return generateStepId(fallbackPrefix, index);
+}
+
+/**
+ * Creates a step ID registry to ensure uniqueness
+ * @returns A registry object with methods to register and check step IDs
+ */
+export function createStepIdRegistry() {
+  const registry = new Set<string>();
+  
+  return {
+    /**
+     * Register a step ID
+     * @param stepId The step ID to register
+     * @returns The registered step ID (may be modified if already exists)
+     */
+    register(stepId: string): string {
+      let finalId = stepId;
+      let counter = 1;
+      
+      // If the ID already exists, append a counter
+      while (registry.has(finalId)) {
+        finalId = `${stepId}-${counter}`;
+        counter++;
+      }
+      
+      registry.add(finalId);
+      return finalId;
+    },
+    
+    /**
+     * Check if a step ID is registered
+     * @param stepId The step ID to check
+     * @returns Whether the step ID is registered
+     */
+    has(stepId: string): boolean {
+      return registry.has(stepId);
+    },
+    
+    /**
+     * Get all registered step IDs
+     * @returns Array of registered step IDs
+     */
+    getAll(): string[] {
+      return Array.from(registry);
+    },
+    
+    /**
+     * Clear all registered step IDs
+     */
+    clear(): void {
+      registry.clear();
+    }
+  };
+}
+
+// Create a global step ID registry for use across the SDK
+export const globalStepIdRegistry = createStepIdRegistry();
+
+/**
+ * Set the current flow context ID for step ID generation
+ * @param flowId The ID of the current flow
+ */
+export function setFlowContext(flowId: string | null): void {
+  currentFlowContextId = flowId;
+}
+
+/**
+ * Get the current flow context ID
+ * @returns The current flow context ID
+ */
+export function getFlowContext(): string | null {
+  return currentFlowContextId;
+}
+
+/**
+ * Associate a step ID with a DOM element
+ * @param element The DOM element
+ * @param stepId The step ID
+ */
+export function registerElementStepId(element: HTMLElement, stepId: string): void {
+  if (!element || !stepId) return;
+  
+  elementStepIdRegistry.set(element, stepId);
+  
+  // Also set it as a data attribute for easier identification
+  if (!element.hasAttribute('data-dap-normalized-step')) {
+    element.setAttribute('data-dap-normalized-step', stepId);
+  }
+}
+
+/**
+ * Get the step ID associated with a DOM element
+ * @param element The DOM element
+ * @returns The associated step ID, or null if not found
+ */
+export function getElementStepId(element: HTMLElement): string | null {
+  return elementStepIdRegistry.get(element) || null;
+}