@cognior/iap-sdk 0.1.0

package/src/utils/immediateValidationPrevention.ts

@@ -0,0 +1,184 @@
+/**
+ * Immediate Validation Prevention
+ * This script runs immediately to prevent ANY browser validation tooltips
+ * Must be loaded BEFORE any forms are rendered
+ */
+
+// Immediate global validation suppression
+(function immediateValidationPrevention() {
+  'use strict';
+  
+  console.debug('[DAP] Immediate validation prevention activated');
+  
+  // 1. Override native validation methods
+  if (typeof HTMLFormElement !== 'undefined') {
+    const originalCheckValidity = HTMLFormElement.prototype.checkValidity;
+    const originalReportValidity = HTMLFormElement.prototype.reportValidity;
+    
+    HTMLFormElement.prototype.checkValidity = function() {
+      console.debug('[DAP] Form.checkValidity() intercepted');
+      return true; // Always return true to prevent validation UI
+    };
+    
+    HTMLFormElement.prototype.reportValidity = function() {
+      console.debug('[DAP] Form.reportValidity() intercepted');
+      return true; // Always return true to prevent validation UI
+    };
+  }
+  
+  // 2. Override input validation methods
+  if (typeof HTMLInputElement !== 'undefined') {
+    const originalCheckValidity = HTMLInputElement.prototype.checkValidity;
+    const originalReportValidity = HTMLInputElement.prototype.reportValidity;
+    
+    HTMLInputElement.prototype.checkValidity = function() {
+      console.debug('[DAP] Input.checkValidity() intercepted');
+      return true;
+    };
+    
+    HTMLInputElement.prototype.reportValidity = function() {
+      console.debug('[DAP] Input.reportValidity() intercepted');
+      return true;
+    };
+  }
+  
+  // 3. Immediate DOM event prevention with deduplication
+  let lastPreventedTarget: Element | null = null;
+  let lastPreventedTime = 0;
+  
+  const preventValidation = (event: Event) => {
+    const now = Date.now();
+    // Prevent duplicate prevention calls within 100ms for same element
+    if (event.target === lastPreventedTarget && now - lastPreventedTime < 100) {
+      return false;
+    }
+    
+    lastPreventedTarget = event.target as Element;
+    lastPreventedTime = now;
+    
+    console.debug('[DAP] Validation event prevented:', event.type, event.target);
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    
+    // Clear any validation state
+    const target = event.target as HTMLInputElement;
+    if (target && typeof target.setCustomValidity === 'function') {
+      target.setCustomValidity('');
+    }
+    
+    return false;
+  };
+  
+  // Add listeners immediately
+  document.addEventListener('invalid', preventValidation, { capture: true, passive: false });
+  document.addEventListener('submit', (event) => {
+    const form = event.target as HTMLFormElement;
+    if (form && form.tagName === 'FORM') {
+      // Force disable validation
+      form.setAttribute('novalidate', '');
+      form.noValidate = true;
+      console.debug('[DAP] Form novalidate applied during submit');
+    }
+  }, { capture: true });
+  
+  // 4. CSS to hide any validation bubbles that might slip through
+  const style = document.createElement('style');
+  style.id = 'dap-validation-override';
+  style.textContent = `
+    /* Hide all browser validation UI */
+    input:invalid,
+    input:-webkit-any(invalid),
+    input:-moz-ui-invalid {
+      box-shadow: none !important;
+    }
+    
+    /* Hide validation pseudo-elements */
+    input::-webkit-validation-bubble,
+    input::-webkit-validation-bubble-message,
+    input::-webkit-validation-bubble-arrow,
+    input::-webkit-validation-bubble-arrow-clipper {
+      display: none !important;
+    }
+    
+    /* Firefox validation hiding */
+    input:-moz-ui-invalid {
+      box-shadow: none !important;
+    }
+    
+    /* Hide any tooltips or popups */
+    [role="tooltip"]:not(.dap-tooltip):not(.dap-tip-bubble) {
+      display: none !important;
+    }
+  `;
+  
+  // Insert styles immediately
+  if (document.head) {
+    document.head.appendChild(style);
+  } else {
+    // If head doesn't exist yet, wait for it
+    const observer = new MutationObserver(() => {
+      if (document.head) {
+        document.head.appendChild(style);
+        observer.disconnect();
+      }
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+  }
+  
+  // 5. Process existing forms immediately
+  const processExistingForms = () => {
+    const forms = document.querySelectorAll('form');
+    forms.forEach(form => {
+      form.setAttribute('novalidate', '');
+      (form as HTMLFormElement).noValidate = true;
+      console.debug('[DAP] Existing form processed:', form);
+    });
+  };
+  
+  // Process immediately if DOM is ready
+  if (document.readyState !== 'loading') {
+    processExistingForms();
+  } else {
+    document.addEventListener('DOMContentLoaded', processExistingForms);
+  }
+  
+  // 6. Monitor for new forms
+  const formObserver = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      mutation.addedNodes.forEach((node) => {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          const element = node as Element;
+          
+          // Check if it's a form
+          if (element.tagName === 'FORM') {
+            const form = element as HTMLFormElement;
+            form.setAttribute('novalidate', '');
+            form.noValidate = true;
+            console.debug('[DAP] New form processed:', form);
+          }
+          
+          // Check for forms within the element
+          const forms = element.querySelectorAll?.('form');
+          forms?.forEach(form => {
+            form.setAttribute('novalidate', '');
+            (form as HTMLFormElement).noValidate = true;
+            console.debug('[DAP] Nested form processed:', form);
+          });
+        }
+      });
+    });
+  });
+  
+  // Start observing
+  if (document.body) {
+    formObserver.observe(document.body, { childList: true, subtree: true });
+  } else {
+    document.addEventListener('DOMContentLoaded', () => {
+      formObserver.observe(document.body, { childList: true, subtree: true });
+    });
+  }
+  
+  console.debug('[DAP] Immediate validation prevention setup complete');
+})();
+
+export {}; // Make this a module

package/src/utils/normalize.ts

@@ -0,0 +1,50 @@
+// src/utils/normalize.ts
+/**
+ * Normalization utilities for DAP SDK
+ * 
+ * This module provides central normalization functions to ensure consistent behavior across the SDK:
+ * 1. Trigger normalization: Converting variations like "on hover", "hover", "onhover" to standard values
+ * 2. Placement normalization: Handling casing variations like "Top", "TOP", "top" 
+ * 
+ * These utilities ensure that regardless of how data is provided from the server,
+ * the SDK processes it consistently.
+ */
+
+/**
+ * Normalizes trigger strings to standard format regardless of input format
+ * Examples: "on hover", "hover", "onHover" -> "hover"
+ */
+export function normalizeTrigger(t: string | undefined): "hover" | "focus" | "click" {
+  if (!t) return "hover";
+  
+  const s = t.trim().toLowerCase();
+  if (s.includes("hover")) return "hover";
+  if (s.includes("focus")) return "focus";
+  if (s.includes("click")) return "click";
+  if (s.includes("load")) return "hover";
+  return "hover";
+}
+
+/**
+ * Normalizes placement strings to standard format regardless of casing
+ * Examples: "Top", "TOP", "top" -> "top"
+ */
+export function normalizePlacement(p: string | undefined): "top" | "bottom" | "left" | "right" | "auto" {
+  if (!p) return "top";
+  
+  const s = p.trim().toLowerCase();
+  if (s.startsWith("top")) return "top";
+  if (s.startsWith("bottom")) return "bottom";
+  if (s.startsWith("left")) return "left";
+  if (s.startsWith("right")) return "right";
+  if (s === "auto") return "auto";
+  return "top";
+}
+
+/**
+ * Convert server-side trigger values to client-side normalized triggers
+ * For backward compatibility with existing code
+ */
+export function toTrigger(input: string | undefined): "hover" | "focus" | "click" {
+  return normalizeTrigger(input);
+}

package/src/utils/privacyManager.ts

@@ -0,0 +1,166 @@
+// src/utils/privacyManager.ts
+// Provides tools for managing user consent and privacy preferences for tracking
+
+/**
+ * Privacy consent levels for tracking
+ */
+export enum TrackingConsentLevel {
+  NONE = 'none',           // No tracking allowed
+  ESSENTIAL = 'essential', // Only essential tracking (errors, basic flow usage)
+  FUNCTIONAL = 'functional', // Functional tracking (user interactions, completion rates)
+  ANALYTICS = 'analytics', // Full analytics tracking (detailed user behavior)
+  ALL = 'all'              // All tracking including external analytics integration
+}
+
+/**
+ * User data categories that may be collected
+ */
+export enum UserDataCategory {
+  DEVICE_INFO = 'device_info',     // Browser, OS, screen size
+  USER_ID = 'user_id',             // Anonymous user identifier
+  INTERACTION = 'interaction',     // Clicks, form inputs, etc.
+  TIMING = 'timing',               // Time spent on pages/steps
+  LOCATION = 'location',           // Geographic location
+  CONTEXT = 'context',             // Page URL, referrer
+  CUSTOM_ATTRIBUTES = 'custom_attributes' // Any custom attributes
+}
+
+// Storage key for privacy preferences
+const PRIVACY_PREFS_KEY = 'dap_privacy_preferences';
+
+/**
+ * User privacy preferences
+ */
+interface PrivacyPreferences {
+  consentLevel: TrackingConsentLevel;
+  allowedDataCategories: UserDataCategory[];
+  lastUpdated: number; // timestamp
+  expiresAt: number; // timestamp
+  hasExplicitConsent: boolean;
+}
+
+// Default preferences - minimal tracking only
+const DEFAULT_PREFERENCES: PrivacyPreferences = {
+  consentLevel: TrackingConsentLevel.ESSENTIAL,
+  allowedDataCategories: [
+    UserDataCategory.DEVICE_INFO,
+    UserDataCategory.USER_ID
+  ],
+  lastUpdated: Date.now(),
+  expiresAt: Date.now() + (180 * 24 * 60 * 60 * 1000), // 180 days
+  hasExplicitConsent: false
+};
+
+/**
+ * Get the current privacy preferences
+ * @returns The current privacy preferences
+ */
+export function getPrivacyPreferences(): PrivacyPreferences {
+  try {
+    const storedPrefs = localStorage.getItem(PRIVACY_PREFS_KEY);
+    if (!storedPrefs) {
+      return DEFAULT_PREFERENCES;
+    }
+    
+    const parsedPrefs = JSON.parse(storedPrefs);
+    
+    // Check if preferences have expired
+    if (parsedPrefs.expiresAt < Date.now()) {
+      // Reset to default if expired
+      return DEFAULT_PREFERENCES;
+    }
+    
+    return parsedPrefs;
+  } catch (error) {
+    console.error('[DAP] Error reading privacy preferences:', error);
+    return DEFAULT_PREFERENCES;
+  }
+}
+
+/**
+ * Set privacy preferences
+ * @param preferences The privacy preferences to set
+ */
+export function setPrivacyPreferences(preferences: Partial<PrivacyPreferences>): void {
+  try {
+    const currentPrefs = getPrivacyPreferences();
+    const updatedPrefs = {
+      ...currentPrefs,
+      ...preferences,
+      lastUpdated: Date.now(),
+      hasExplicitConsent: true
+    };
+    
+    localStorage.setItem(PRIVACY_PREFS_KEY, JSON.stringify(updatedPrefs));
+  } catch (error) {
+    console.error('[DAP] Error saving privacy preferences:', error);
+  }
+}
+
+/**
+ * Check if a specific data category can be collected
+ * @param category The data category to check
+ * @returns Whether the data category can be collected
+ */
+export function canCollectDataCategory(category: UserDataCategory): boolean {
+  const prefs = getPrivacyPreferences();
+  return prefs.allowedDataCategories.includes(category);
+}
+
+/**
+ * Check if a specific consent level is granted
+ * @param level The consent level to check
+ * @returns Whether the consent level is granted
+ */
+export function hasConsentLevel(level: TrackingConsentLevel): boolean {
+  const prefs = getPrivacyPreferences();
+  const levels = [
+    TrackingConsentLevel.NONE,
+    TrackingConsentLevel.ESSENTIAL,
+    TrackingConsentLevel.FUNCTIONAL,
+    TrackingConsentLevel.ANALYTICS,
+    TrackingConsentLevel.ALL
+  ];
+  
+  const currentLevelIndex = levels.indexOf(prefs.consentLevel);
+  const requestedLevelIndex = levels.indexOf(level);
+  
+  return currentLevelIndex >= requestedLevelIndex;
+}
+
+/**
+ * Reset privacy preferences to default
+ */
+export function resetPrivacyPreferences(): void {
+  localStorage.removeItem(PRIVACY_PREFS_KEY);
+}
+
+/**
+ * Get a sanitized version of tracking data based on privacy preferences
+ * @param data The tracking data to sanitize
+ * @returns Sanitized tracking data
+ */
+export function sanitizeTrackingData(data: any): any {
+  const prefs = getPrivacyPreferences();
+  const result = { ...data };
+  
+  // Remove user ID if not allowed
+  if (!canCollectDataCategory(UserDataCategory.USER_ID) && result.clientInfo) {
+    result.clientInfo = { ...result.clientInfo, userId: undefined };
+  }
+  
+  // Remove interaction data if not allowed
+  if (!canCollectDataCategory(UserDataCategory.INTERACTION)) {
+    result.elementSelector = undefined;
+    result.elementContext = undefined;
+    result.interactionDepth = undefined;
+  }
+  
+  // Remove timing data if not allowed
+  if (!canCollectDataCategory(UserDataCategory.TIMING)) {
+    result.timeOnStep = undefined;
+    result.totalFlowTime = undefined;
+  }
+  
+  return result;
+}

package/src/utils/ruleEvaluator.ts

@@ -0,0 +1,199 @@
+// src/utils/ruleEvaluator.ts
+// Rule evaluation engine for dynamic flow switching
+
+import type { 
+  ConditionRuleBlock, 
+  RuleCondition, 
+  ConditionOperator, 
+  LogicalOperator,
+  ConditionValueType 
+} from '../experiences/types';
+
+/**
+ * Evaluates a single condition against a given value
+ */
+export function evaluateCondition(condition: RuleCondition, inputValue: string | number | boolean): boolean {
+  try {
+    let targetValue = inputValue;
+    let conditionValue = condition.value;
+    
+    // Type coercion based on valueType
+    if (condition.valueType === 'Number') {
+      targetValue = typeof inputValue === 'string' ? parseFloat(inputValue) : Number(inputValue);
+      conditionValue = Number(condition.value);
+      
+      if (isNaN(targetValue as number) || isNaN(conditionValue as number)) {
+        console.warn(`[DAP] Invalid number comparison: ${inputValue} vs ${condition.value}`);
+        return false;
+      }
+    } else if (condition.valueType === 'Boolean') {
+      targetValue = typeof inputValue === 'string' ? 
+        inputValue.toLowerCase() === 'true' : Boolean(inputValue);
+      conditionValue = typeof condition.value === 'string' ? 
+        condition.value.toLowerCase() === 'true' : Boolean(condition.value);
+    } else {
+      // String comparison - convert both to strings
+      targetValue = String(inputValue);
+      conditionValue = String(condition.value);
+    }
+    
+    switch (condition.operator) {
+      case 'Equals':
+        return targetValue === conditionValue;
+        
+      case 'NotEquals':
+        return targetValue !== conditionValue;
+        
+      case 'Contains':
+        return String(targetValue).toLowerCase().includes(String(conditionValue).toLowerCase());
+        
+      case 'NotContains':
+        return !String(targetValue).toLowerCase().includes(String(conditionValue).toLowerCase());
+        
+      case 'GreaterThan':
+        if (condition.valueType === 'Number') {
+          return (targetValue as number) > (conditionValue as number);
+        }
+        // For strings, compare lexicographically
+        return String(targetValue) > String(conditionValue);
+        
+      case 'LessThan':
+        if (condition.valueType === 'Number') {
+          return (targetValue as number) < (conditionValue as number);
+        }
+        // For strings, compare lexicographically
+        return String(targetValue) < String(conditionValue);
+        
+      default:
+        console.warn(`[DAP] Unknown condition operator: ${condition.operator}`);
+        return false;
+    }
+  } catch (error) {
+    console.error(`[DAP] Error evaluating condition:`, error, condition);
+    return false;
+  }
+}
+
+/**
+ * Evaluates a rule block with multiple conditions
+ */
+export function evaluateRuleBlock(ruleBlock: ConditionRuleBlock, inputValue: string | number | boolean): boolean {
+  try {
+    if (!ruleBlock.conditions || ruleBlock.conditions.length === 0) {
+      console.warn(`[DAP] Rule block ${ruleBlock.ruleBlockId} has no conditions`);
+      return false;
+    }
+    
+    const results = ruleBlock.conditions.map(condition => evaluateCondition(condition, inputValue));
+    
+    if (ruleBlock.logicalOperator === 'And') {
+      return results.every(result => result === true);
+    } else if (ruleBlock.logicalOperator === 'Or') {
+      return results.some(result => result === true);
+    } else {
+      console.warn(`[DAP] Unknown logical operator: ${ruleBlock.logicalOperator}`);
+      return false;
+    }
+  } catch (error) {
+    console.error(`[DAP] Error evaluating rule block:`, error, ruleBlock);
+    return false;
+  }
+}
+
+/**
+ * Evaluates multiple rule blocks and returns the first matching nextFlowId
+ */
+export function evaluateRules(ruleBlocks: ConditionRuleBlock[], inputValue: string | number | boolean): string | null {
+  try {
+    for (const ruleBlock of ruleBlocks) {
+      if (evaluateRuleBlock(ruleBlock, inputValue)) {
+        console.debug(`[DAP] Rule block ${ruleBlock.ruleBlockId} matched, nextFlowId: ${ruleBlock.nextFlowId}`);
+        return ruleBlock.nextFlowId;
+      }
+    }
+    
+    console.debug(`[DAP] No rule blocks matched for value: ${inputValue}`);
+    return null;
+  } catch (error) {
+    console.error(`[DAP] Error evaluating rules:`, error);
+    return null;
+  }
+}
+
+/**
+ * Gets the current value from a DOM element based on its type
+ */
+export function getElementValue(element: HTMLElement): string | number | boolean {
+  try {
+    if (element instanceof HTMLInputElement) {
+      switch (element.type) {
+        case 'checkbox':
+        case 'radio':
+          return element.checked;
+        case 'number':
+          return element.valueAsNumber || 0;
+        default:
+          return element.value;
+      }
+    } else if (element instanceof HTMLSelectElement) {
+      return element.value;
+    } else if (element instanceof HTMLTextAreaElement) {
+      return element.value;
+    } else {
+      // For other elements, return text content
+      return element.textContent || element.innerText || '';
+    }
+  } catch (error) {
+    console.error(`[DAP] Error getting element value:`, error);
+    return '';
+  }
+}
+
+/**
+ * Creates an input event listener for rule evaluation with comprehensive error handling
+ */
+export function createRuleEvaluationListener(
+  ruleBlocks: ConditionRuleBlock[],
+  onRuleMatch: (nextFlowId: string) => void
+): (event: Event) => void {
+  return (event: Event) => {
+    try {
+      const target = event.target as HTMLElement;
+      if (!target) {
+        console.warn('[DAP] Rule evaluation: No target element');
+        return;
+      }
+      
+      // Validate rule blocks
+      if (!Array.isArray(ruleBlocks) || ruleBlocks.length === 0) {
+        console.warn('[DAP] Rule evaluation: No valid rule blocks');
+        return;
+      }
+      
+      // Validate callback
+      if (typeof onRuleMatch !== 'function') {
+        console.error('[DAP] Rule evaluation: Invalid callback function');
+        return;
+      }
+      
+      const inputValue = getElementValue(target);
+      console.debug(`[DAP] Evaluating rules for value:`, inputValue);
+      
+      const nextFlowId = evaluateRules(ruleBlocks, inputValue);
+      
+      if (nextFlowId) {
+        console.debug(`[DAP] Rule evaluation triggered flow transition to: ${nextFlowId}`);
+        
+        try {
+          onRuleMatch(nextFlowId);
+        } catch (callbackError) {
+          console.error(`[DAP] Error in rule match callback:`, callbackError);
+        }
+      } else {
+        console.debug(`[DAP] No rules matched for value:`, inputValue);
+      }
+    } catch (error) {
+      console.error(`[DAP] Error in rule evaluation listener:`, error);
+    }
+  };
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,79 @@
+/**
+ * Minimal allowlist-based HTML sanitizer.
+ * - Keeps only allowed tags/attributes
+ * - Validates href/src as http(s)
+ * - No dependency on dom.iterable (index loops only)
+ */
+
+export function sanitizeHtml(unsafe: string): string {
+  const tmp = document.createElement("div");
+  tmp.innerHTML = unsafe || "";
+
+  const elements = tmp.querySelectorAll("*");
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i] as HTMLElement;
+    const name = el.nodeName.toLowerCase();
+
+    if (!ALLOW.has(name)) {
+      const text = document.createTextNode(el.textContent || "");
+      const parent = el.parentNode;
+      if (parent) parent.replaceChild(text, el);
+      continue;
+    }
+
+    const attrs = el.attributes;
+    for (let j = attrs.length - 1; j >= 0; j--) {
+      const attr = attrs[j];
+      const an = attr.name.toLowerCase();
+      const av = attr.value;
+
+      if (!ATTR_ALLOW.has(an)) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+
+      if (an === "href" || an === "src") {
+        if (!isSafeHttpUrl(av)) {
+          el.removeAttribute(attr.name);
+          continue;
+        }
+        if (an === "href" && isHttpUrl(av)) {
+          if (!el.getAttribute("rel")) el.setAttribute("rel", "noopener noreferrer");
+          if (!el.getAttribute("target")) el.setAttribute("target", "_blank");
+        }
+      }
+    }
+  }
+
+  return tmp.innerHTML;
+}
+
+const ALLOW = new Set<string>([
+  "b","strong","i","em","u",
+  "span","p","br","ul","ol","li",
+  "a","code","pre","small","div",
+  // for DOCX previews (Mammoth)
+  "h1","h2","h3","h4","h5","h6",
+  "table","thead","tbody","tr","td","th"
+]);
+
+const ATTR_ALLOW = new Set<string>([
+  "href","target","rel","class","style",
+  "src","alt","title","aria-label","colspan","rowspan","scope"
+]);
+
+export function isSafeHttpUrl(u?: string | null): boolean {
+  if (!u) return false;
+  try {
+    const url = new URL(u, location.origin);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function isHttpUrl(u: string): boolean {
+  try {
+    const url = new URL(u, location.origin);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch { return false; }
+}