@cognior/iap-sdk 0.1.0

package/src/styles/tooltip.css.ts

@@ -0,0 +1,149 @@
+export const tooltipCssText = `
+:host {
+  --dap-z: 2147483638;
+  --dap-tip-bg: #1f2937;
+  --dap-tip-fg: #ffffff;
+  --dap-tip-border: rgba(255,255,255,0.12);
+  --dap-tip-radius: 10px;
+  --dap-tip-shadow: 0 10px 30px rgba(0,0,0,0.25), 0 2px 10px rgba(0,0,0,0.1);
+  --dap-tip-maxw: min(320px, 80vw);
+  --dap-highlight-color: rgba(59, 130, 246, 0.15);
+  --dap-highlight-outline: rgba(59, 130, 246, 0.4);
+  --dap-gap: 10px;
+  --dap-pad: 10px 12px;
+  color: var(--dap-tip-fg);
+}
+
+/* Base styles */
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+/* Tooltip layer */
+.dap-tip-layer { 
+  position: fixed; 
+  inset: 0; 
+  z-index: var(--dap-z); 
+  pointer-events: none;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;
+}
+
+/* Ring highlight */
+.dap-tip-ring { 
+  position: fixed; 
+  border-radius: 12px; 
+  box-shadow: 0 0 0 2px var(--dap-highlight-outline) inset, 0 0 0 6px var(--dap-highlight-color); 
+  transition: transform .12s ease, top .12s ease, left .12s ease, width .12s ease, height .12s ease; 
+  animation: dapPulse 1.8s ease-in-out infinite;
+  pointer-events: none;
+}
+
+/* Tooltip bubble */
+.dap-tip-bubble { 
+  position: fixed; 
+  max-width: var(--dap-tip-maxw); 
+  background: var(--dap-tip-bg); 
+  color: var(--dap-tip-fg); 
+  border: 1px solid var(--dap-tip-border); 
+  border-radius: var(--dap-tip-radius); 
+  padding: var(--dap-pad); 
+  box-shadow: var(--dap-tip-shadow); 
+  font-size: 13.5px; 
+  line-height: 1.45; 
+  pointer-events: auto;
+  word-wrap: break-word;
+  z-index: calc(var(--dap-z) + 1);
+}
+
+.dap-tip-bubble a { 
+  color: #93c5fd; 
+  text-decoration: underline;
+}
+
+.dap-tip-bubble:focus-visible { 
+  outline: 2px solid #2563eb; 
+  outline-offset: 2px; 
+}
+
+/* Arrow styles */
+.dap-tip-bubble[data-placement^="top"]::after,
+.dap-tip-bubble[data-placement^="bottom"]::after,
+.dap-tip-bubble[data-placement^="left"]::after,
+.dap-tip-bubble[data-placement^="right"]::after { 
+  content: ""; 
+  position: absolute; 
+  width: 10px; 
+  height: 10px; 
+  background: var(--dap-tip-bg); 
+  border-left: 1px solid var(--dap-tip-border); 
+  border-top: 1px solid var(--dap-tip-border); 
+  transform: rotate(45deg); 
+}
+
+.dap-tip-bubble[data-placement^="top"]::after { 
+  bottom: -6px; 
+  left: 16px; 
+  border-left: 0; 
+  border-top: 0; 
+  border-right: 1px solid var(--dap-tip-border); 
+  border-bottom: 1px solid var(--dap-tip-border); 
+}
+
+.dap-tip-bubble[data-placement^="bottom"]::after { 
+  top: -6px; 
+  left: 16px; 
+}
+
+.dap-tip-bubble[data-placement^="left"]::after { 
+  right: -6px; 
+  top: 12px; 
+  border-left: 0; 
+  border-top: 0; 
+  border-right: 1px solid var(--dap-tip-border); 
+  border-bottom: 1px solid var(--dap-tip-border); 
+}
+
+.dap-tip-bubble[data-placement^="right"]::after { 
+  left: -6px; 
+  top: 12px; 
+}
+
+/* Animations */
+@keyframes dapPulse {
+  0% { 
+    box-shadow: 0 0 0 2px var(--dap-highlight-outline) inset, 0 0 0 4px var(--dap-highlight-color); 
+  }
+  50% { 
+    box-shadow: 0 0 0 2px var(--dap-highlight-outline) inset, 0 0 0 8px rgba(37,99,235,0.30); 
+  }
+  100% { 
+    box-shadow: 0 0 0 2px var(--dap-highlight-outline) inset, 0 0 0 4px var(--dap-highlight-color); 
+  }
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .dap-tip-bubble {
+    max-width: calc(100vw - 20px);
+    font-size: 13px;
+    padding: 8px 10px;
+  }
+  
+  .dap-tip-bubble[data-placement^="top"]::after,
+  .dap-tip-bubble[data-placement^="bottom"]::after {
+    left: 12px;
+  }
+  
+  .dap-tip-bubble[data-placement^="left"]::after,
+  .dap-tip-bubble[data-placement^="right"]::after {
+    top: 8px;
+  }
+}
+
+/* Accessibility */
+@media (prefers-reduced-motion: reduce) { 
+  .dap-tip-ring { 
+    animation: none; 
+  }
+}
+`;

package/src/tracking.ts

@@ -0,0 +1,223 @@
+// src/tracking.ts
+// Simple, deterministic step view tracking for DAP SDK
+
+import type { DapConfig } from "./config";
+import { userContextService } from './services/userContextService';
+
+// =============================================================================
+// SIMPLE TRACKING SYSTEM
+// =============================================================================
+
+/**
+ * In-memory tracking state to prevent duplicate tracking
+ */
+class StepTrackingState {
+  private trackedSteps = new Set<string>();
+  private currentFlowId: string | null = null;
+
+  /**
+   * Check if a step has already been tracked for the current flow
+   */
+  isStepTracked(flowId: string, stepId: string): boolean {
+    if (this.currentFlowId !== flowId) {
+      // New flow started - reset tracking state
+      this.reset(flowId);
+    }
+    
+    const key = `${flowId}:${stepId}`;
+    return this.trackedSteps.has(key);
+  }
+
+  /**
+   * Mark a step as tracked
+   */
+  markStepTracked(flowId: string, stepId: string): void {
+    if (this.currentFlowId !== flowId) {
+      this.reset(flowId);
+    }
+    
+    const key = `${flowId}:${stepId}`;
+    this.trackedSteps.add(key);
+    
+    console.debug(`[DAP Tracking] Step marked as tracked: ${key}`);
+  }
+
+  /**
+   * Reset tracking state for a new flow
+   */
+  reset(flowId: string): void {
+    this.currentFlowId = flowId;
+    this.trackedSteps.clear();
+    console.debug(`[DAP Tracking] Tracking state reset for flow: ${flowId}`);
+  }
+
+  /**
+   * Get current tracking state (for debugging)
+   */
+  getState(): { flowId: string | null; trackedCount: number; trackedSteps: string[] } {
+    return {
+      flowId: this.currentFlowId,
+      trackedCount: this.trackedSteps.size,
+      trackedSteps: Array.from(this.trackedSteps)
+    };
+  }
+}
+
+// Global tracking state
+const trackingState = new StepTrackingState();
+
+/**
+ * Track a step view - fire and forget
+ * 
+ * @param flowId - The flow ID
+ * @param stepId - The step ID
+ * @param config - DAP configuration (optional, will use global if not provided)
+ */
+export async function trackStepView(
+  flowId: string, 
+  stepId: string, 
+  config?: DapConfig
+): Promise<void> {
+  // Validation
+  if (!flowId || !stepId) {
+    console.warn('[DAP Tracking] Cannot track step: flowId and stepId are required');
+    return;
+  }
+
+  // Check for duplicate tracking
+  if (trackingState.isStepTracked(flowId, stepId)) {
+    console.debug(`[DAP Tracking] Step already tracked, skipping: ${flowId}:${stepId}`);
+    return;
+  }
+
+  // Get configuration
+  const dapConfig = config || (window as any).__DAP_CONFIG__;
+  if (!dapConfig) {
+    console.error('[DAP Tracking] No configuration available for tracking');
+    return;
+  }
+
+  // Get user ID
+  const userAnalyticsContext = userContextService.getAnalyticsContext();
+  const userId = userAnalyticsContext.userId;
+
+  if (!userId) {
+    console.warn('[DAP Tracking] No user ID available for tracking');
+    return;
+  }
+
+  // Mark step as tracked immediately to prevent duplicates
+  trackingState.markStepTracked(flowId, stepId);
+
+  // Prepare tracking payload (MVP - only required fields)
+  const payload = {
+    flowId,
+    stepId,
+    userId
+  };
+
+  // Build API URL
+  const apiUrl = buildTrackingApiUrl(dapConfig);
+  if (!apiUrl) {
+    console.error('[DAP Tracking] Could not build API URL');
+    return;
+  }
+
+  // Fire and forget - send tracking call
+  try {
+    console.debug('[DAP Tracking] Sending step view:', payload);
+    
+    const response = await fetch(apiUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Host-Url': window.location.origin,
+        'X-Api-Key': dapConfig.apikey || ''
+      },
+      body: JSON.stringify(payload)
+    });
+
+    if (!response.ok) {
+      console.warn(`[DAP Tracking] API call failed with status ${response.status}`);
+    } else {
+      console.debug(`[DAP Tracking] Step view tracked successfully: ${flowId}:${stepId}`);
+    }
+  } catch (error) {
+    console.warn('[DAP Tracking] Failed to send tracking call:', error);
+    // Note: We don't retry to avoid duplicates
+  }
+}
+
+/**
+ * Build the tracking API URL
+ */
+function buildTrackingApiUrl(config: DapConfig): string | null {
+  const { organizationid, siteid, apiurl } = config;
+  
+  if (!organizationid || !siteid || !apiurl) {
+    console.error('[DAP Tracking] Missing required config fields for API URL:', {
+      hasOrganizationId: !!organizationid,
+      hasSiteId: !!siteid,
+      hasApiUrl: !!apiurl
+    });
+    return null;
+  }
+
+  const baseUrl = apiurl.replace(/\/$/, ''); // Remove trailing slash
+  return `${baseUrl}/analytics/organizationId/${organizationid}/siteCollectionId/${siteid}`;
+}
+
+/**
+ * Reset tracking state (useful when starting a new flow)
+ */
+export function resetFlowTracking(flowId: string): void {
+  trackingState.reset(flowId);
+}
+
+/**
+ * Get current tracking state (for debugging)
+ */
+export function getTrackingState(): { flowId: string | null; trackedCount: number; trackedSteps: string[] } {
+  return trackingState.getState();
+}
+
+// =============================================================================
+// LEGACY COMPATIBILITY STUBS
+// =============================================================================
+
+/**
+ * @deprecated Use trackStepView() instead
+ */
+export async function trackAction(): Promise<any> {
+  console.warn('[DAP Tracking] trackAction() is deprecated. Use trackStepView() instead.');
+  return Promise.resolve();
+}
+
+/**
+ * @deprecated No longer needed
+ */
+export function setupActionTracking(): void {
+  console.warn('[DAP Tracking] setupActionTracking() is deprecated and no longer needed.');
+}
+
+// For backward compatibility - some files might import these
+export const TrackingAction = {
+  FLOW_IMPRESSION: 'FLOW_IMPRESSION',
+  FLOW_STARTED: 'FLOW_STARTED', 
+  FLOW_INTERACTION: 'FLOW_INTERACTION',
+  STEP_TRANSITION: 'STEP_TRANSITION',
+  FLOW_COMPLETED: 'FLOW_COMPLETED',
+  FLOW_EXITED: 'FLOW_EXITED',
+  STEP_COMPLETION: 'STEP_COMPLETION'
+} as const;
+
+export interface TrackActionPayload {
+  stepId?: string;
+  actionType?: string;
+  [key: string]: any;
+}
+
+export interface ClientInfo {
+  userId?: string;
+  [key: string]: any;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,66 @@
+/**
+ * Creates a debounced function that delays invoking the provided function
+ * until after 'wait' milliseconds have elapsed since the last time the debounced function was invoked.
+ * 
+ * @param func The function to debounce
+ * @param wait The number of milliseconds to delay
+ * @returns A debounced version of the function
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  
+  return function(this: any, ...args: Parameters<T>): void {
+    const context = this;
+    
+    if (timeout !== null) {
+      clearTimeout(timeout);
+    }
+    
+    timeout = setTimeout(() => {
+      func.apply(context, args);
+      timeout = null;
+    }, wait);
+  };
+}
+
+/**
+ * Creates a throttled function that only invokes the provided function at most once per
+ * every 'limit' milliseconds.
+ * 
+ * @param func The function to throttle
+ * @param limit The number of milliseconds to throttle invocations to
+ * @returns A throttled version of the function
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+  let lastArgs: Parameters<T> | null = null;
+  let lastContext: any = null;
+  
+  return function(this: any, ...args: Parameters<T>): void {
+    const context = this;
+    
+    if (!inThrottle) {
+      func.apply(context, args);
+      inThrottle = true;
+      
+      setTimeout(() => {
+        inThrottle = false;
+        
+        if (lastArgs !== null) {
+          func.apply(lastContext, lastArgs);
+          lastArgs = null;
+          lastContext = null;
+        }
+      }, limit);
+    } else {
+      lastArgs = args;
+      lastContext = context;
+    }
+  };
+}

package/src/utils/eventSequenceValidator.ts

@@ -0,0 +1,124 @@
+// src/utils/eventSequenceValidator.ts
+// Validates that tracking events occur in the proper sequence
+
+import { TrackingAction } from './flowTrackingSystem';
+
+// Define the allowed sequences of tracking events
+const validSequences: Record<string, string[]> = {
+  // Valid starting events (no prerequisites)
+  initial: [
+    TrackingAction.FLOW_IMPRESSION,
+  ],
+  
+  // Events that can follow FLOW_IMPRESSION
+  [TrackingAction.FLOW_IMPRESSION]: [
+    TrackingAction.FLOW_STARTED,  // FLOW_STARTED is the consistent action type used instead of flow_initiation
+    TrackingAction.STEP_TRANSITION,
+    TrackingAction.FLOW_EXITED
+  ],
+  
+  // Events that can follow FLOW_STARTED
+  [TrackingAction.FLOW_STARTED]: [
+    TrackingAction.FLOW_INTERACTION,
+    TrackingAction.STEP_TRANSITION,
+    TrackingAction.FLOW_EXITED
+  ],
+  
+  // Events that can follow FLOW_INTERACTION
+  [TrackingAction.FLOW_INTERACTION]: [
+    TrackingAction.FLOW_INTERACTION,
+    TrackingAction.STEP_TRANSITION,
+    TrackingAction.FLOW_COMPLETED,  // FLOW_COMPLETED is the consistent action type used instead of flow_completion
+    TrackingAction.FLOW_EXITED      // FLOW_EXITED is the consistent action type used instead of flow_exit
+  ],
+  
+  // Events that can follow STEP_TRANSITION
+  [TrackingAction.STEP_TRANSITION]: [
+    TrackingAction.FLOW_INTERACTION,
+    TrackingAction.STEP_TRANSITION,
+    TrackingAction.FLOW_COMPLETED,
+    TrackingAction.FLOW_EXITED
+  ],
+  
+  // Events that can follow FLOW_COMPLETED
+  [TrackingAction.FLOW_COMPLETED]: [
+    // Terminal state - no valid next events
+  ],
+  
+  // Events that can follow FLOW_EXITED
+  [TrackingAction.FLOW_EXITED]: [
+    // Terminal state - no valid next events
+  ],
+  
+  // Special case for flow reentry
+  [TrackingAction.FLOW_REENTRY]: [
+    TrackingAction.FLOW_INTERACTION,
+    TrackingAction.STEP_TRANSITION,
+    TrackingAction.FLOW_COMPLETED,
+    TrackingAction.FLOW_EXITED
+  ],
+};
+
+// Keeps track of the last event for each flow
+const flowLastEvents: Record<string, string> = {};
+
+/**
+ * Validates that an event follows a valid sequence based on the previous event
+ * @param flowId The ID of the flow
+ * @param actionType The action type to validate
+ * @returns Whether the event is valid in the current sequence
+ */
+export function validateEventSequence(flowId: string, actionType: string): { 
+  valid: boolean;
+  reason?: string;
+} {
+  // Get the last event for this flow
+  const lastEvent = flowLastEvents[flowId];
+  
+  // If this is the first event for this flow, check if it's a valid initial event
+  if (!lastEvent) {
+    const isValidStart = validSequences.initial.includes(actionType as TrackingAction);
+    // Store this event as the last one
+    if (isValidStart) {
+      flowLastEvents[flowId] = actionType;
+    }
+    
+    return {
+      valid: isValidStart,
+      reason: isValidStart ? undefined : `Invalid initial event: ${actionType}. Must be one of: ${validSequences.initial.join(', ')}`
+    };
+  }
+  
+  // Look up valid next events based on the last event
+  const validNextEvents = validSequences[lastEvent as keyof typeof validSequences] || [];
+  
+  // Check if the current event is a valid next event
+  const isValidNext = validNextEvents.includes(actionType as any);
+  
+  // Store this event as the last one if it's valid
+  if (isValidNext) {
+    flowLastEvents[flowId] = actionType;
+  }
+  
+  return { 
+    valid: isValidNext,
+    reason: isValidNext ? undefined : `Invalid event sequence: ${lastEvent} -> ${actionType}. Valid next events: ${validNextEvents.join(', ')}`
+  };
+}
+
+/**
+ * Reset the event sequence for a flow (useful for testing or manual resets)
+ * @param flowId The ID of the flow
+ */
+export function resetEventSequence(flowId: string): void {
+  delete flowLastEvents[flowId];
+}
+
+/**
+ * Get the last event type for a flow
+ * @param flowId The ID of the flow
+ * @returns The last event type, or undefined if no events have been tracked
+ */
+export function getLastEventType(flowId: string): string | undefined {
+  return flowLastEvents[flowId];
+}