@prosdevlab/experience-sdk-plugins 0.1.4 → 0.3.0

package/src/time-delay/time-delay.ts

@@ -0,0 +1,296 @@
+/** @module timeDelayPlugin */
+
+import type { PluginFunction } from '@lytics/sdk-kit';
+import type { TimeDelayEvent, TimeDelayPlugin, TimeDelayPluginConfig } from './types';
+
+/**
+ * Pure function: Calculate elapsed time from start
+ */
+export function calculateElapsed(startTime: number, pausedDuration: number): number {
+  return Date.now() - startTime - pausedDuration;
+}
+
+/**
+ * Pure function: Check if document is hidden (Page Visibility API)
+ */
+export function isDocumentHidden(): boolean {
+  if (typeof document === 'undefined') return false;
+  return document.hidden || false;
+}
+
+/**
+ * Pure function: Create time delay event payload
+ */
+export function createTimeDelayEvent(
+  startTime: number,
+  pausedDuration: number,
+  wasPaused: boolean,
+  visibilityChanges: number
+): TimeDelayEvent {
+  const timestamp = Date.now();
+  const elapsed = timestamp - startTime;
+  const activeElapsed = elapsed - pausedDuration;
+
+  return {
+    timestamp,
+    elapsed,
+    activeElapsed,
+    wasPaused,
+    visibilityChanges,
+  };
+}
+
+/**
+ * Time Delay Plugin
+ *
+ * Tracks time elapsed since SDK initialization and emits trigger:timeDelay events
+ * when the configured delay is reached.
+ *
+ * **Features:**
+ * - Millisecond precision timing
+ * - Pause/resume on tab visibility change (optional)
+ * - Tracks active vs total elapsed time
+ * - Full timer lifecycle management
+ *
+ * **Event-Driven Architecture:**
+ * This plugin emits `trigger:timeDelay` events when the delay threshold is reached.
+ * The core runtime listens for these events and automatically re-evaluates experiences.
+ *
+ * **Usage Pattern:**
+ * Use `targeting.custom` to check if time delay has triggered:
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { init, register } from '@prosdevlab/experience-sdk';
+ *
+ * init({
+ *   timeDelay: {
+ *     delay: 5000,          // 5 seconds
+ *     pauseWhenHidden: true  // Pause when tab hidden (default)
+ *   }
+ * });
+ *
+ * // Show banner after 5 seconds of active viewing time
+ * register('timed-offer', {
+ *   type: 'banner',
+ *   content: {
+ *     message: 'Limited time offer!',
+ *     buttons: [{ text: 'Claim Now', variant: 'primary' }]
+ *   },
+ *   targeting: {
+ *     custom: (context) => {
+ *       const active = context.triggers?.timeDelay?.activeElapsed || 0;
+ *       return active >= 5000;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Combining with other triggers
+ * ```typescript
+ * // Show after 10s OR on exit intent (whichever comes first)
+ * register('engaged-offer', {
+ *   type: 'banner',
+ *   content: { message: 'Special offer for engaged users!' },
+ *   targeting: {
+ *     custom: (context) => {
+ *       const timeElapsed = (context.triggers?.timeDelay?.activeElapsed || 0) >= 10000;
+ *       const exitIntent = context.triggers?.exitIntent?.triggered;
+ *       return timeElapsed || exitIntent;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param plugin Plugin interface from sdk-kit
+ * @param instance SDK instance
+ * @param config SDK configuration
+ */
+export const timeDelayPlugin: PluginFunction = (plugin, instance, config) => {
+  plugin.ns('experiences.timeDelay');
+
+  // Set defaults
+  plugin.defaults({
+    timeDelay: {
+      delay: 0,
+      pauseWhenHidden: true,
+    },
+  });
+
+  // Get config
+  const timeDelayConfig = config.get('timeDelay') as TimeDelayPluginConfig['timeDelay'];
+  if (!timeDelayConfig) return;
+
+  const delay = timeDelayConfig.delay ?? 0;
+  const pauseWhenHidden = timeDelayConfig.pauseWhenHidden ?? true;
+
+  // Skip if delay is 0 (disabled)
+  if (delay <= 0) return;
+
+  // State
+  const startTime = Date.now();
+  let triggered = false;
+  let paused = false;
+  let pausedDuration = 0;
+  let lastPauseTime = 0;
+  let visibilityChanges = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let visibilityListener: (() => void) | null = null;
+
+  /**
+   * Trigger the time delay event
+   */
+  function trigger(): void {
+    if (triggered) return;
+
+    triggered = true;
+
+    // Create event payload using pure function
+    const eventPayload = createTimeDelayEvent(
+      startTime,
+      pausedDuration,
+      visibilityChanges > 0,
+      visibilityChanges
+    );
+
+    // Emit trigger event
+    instance.emit('trigger:timeDelay', eventPayload);
+
+    // Cleanup
+    cleanup();
+  }
+
+  /**
+   * Schedule timer with remaining delay
+   */
+  function scheduleTimer(remainingDelay: number): void {
+    if (timer) {
+      clearTimeout(timer);
+    }
+
+    timer = setTimeout(() => {
+      trigger();
+    }, remainingDelay);
+  }
+
+  /**
+   * Handle visibility change
+   */
+  function handleVisibilityChange(): void {
+    const hidden = isDocumentHidden();
+
+    if (hidden && !paused) {
+      // Tab just became hidden - pause timer
+      paused = true;
+      lastPauseTime = Date.now();
+      visibilityChanges++;
+
+      // Clear existing timer
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    } else if (!hidden && paused) {
+      // Tab just became visible - resume timer
+      paused = false;
+      const pauseDuration = Date.now() - lastPauseTime;
+      pausedDuration += pauseDuration;
+      visibilityChanges++;
+
+      // Calculate remaining delay
+      const elapsed = calculateElapsed(startTime, pausedDuration);
+      const remaining = delay - elapsed;
+
+      if (remaining > 0) {
+        scheduleTimer(remaining);
+      } else {
+        // Delay already elapsed during pause
+        trigger();
+      }
+    }
+  }
+
+  /**
+   * Cleanup listeners and timers
+   */
+  function cleanup(): void {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (visibilityListener && typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', visibilityListener);
+      visibilityListener = null;
+    }
+  }
+
+  /**
+   * Initialize timer and visibility listener
+   */
+  function initialize(): void {
+    // Check if already hidden on init
+    if (pauseWhenHidden && isDocumentHidden()) {
+      paused = true;
+      lastPauseTime = Date.now();
+      visibilityChanges++;
+    } else {
+      // Start timer
+      scheduleTimer(delay);
+    }
+
+    // Setup visibility listener if pause is enabled
+    if (pauseWhenHidden && typeof document !== 'undefined') {
+      visibilityListener = handleVisibilityChange;
+      document.addEventListener('visibilitychange', visibilityListener);
+    }
+  }
+
+  // Expose API
+  plugin.expose({
+    timeDelay: {
+      getElapsed: () => {
+        return Date.now() - startTime;
+      },
+
+      getActiveElapsed: () => {
+        let currentPausedDuration = pausedDuration;
+        if (paused) {
+          // Add current pause duration
+          currentPausedDuration += Date.now() - lastPauseTime;
+        }
+        return calculateElapsed(startTime, currentPausedDuration);
+      },
+
+      getRemaining: () => {
+        if (triggered) return 0;
+
+        const elapsed = calculateElapsed(startTime, pausedDuration);
+        const remaining = delay - elapsed;
+        return Math.max(0, remaining);
+      },
+
+      isPaused: () => paused,
+
+      isTriggered: () => triggered,
+
+      reset: () => {
+        triggered = false;
+        paused = false;
+        pausedDuration = 0;
+        lastPauseTime = 0;
+        visibilityChanges = 0;
+
+        cleanup();
+        initialize();
+      },
+    } satisfies TimeDelayPlugin,
+  });
+
+  // Initialize on plugin load
+  initialize();
+
+  // Cleanup on instance destroy
+  instance.on('sdk:destroy', () => {
+    cleanup();
+  });
+};

package/src/time-delay/types.ts

@@ -0,0 +1,89 @@
+/** @module timeDelayPlugin */
+
+/**
+ * Time Delay Plugin Configuration
+ *
+ * Tracks time elapsed since SDK initialization and emits trigger:timeDelay events.
+ */
+export interface TimeDelayPluginConfig {
+  timeDelay?: {
+    /**
+     * Delay before emitting trigger event (milliseconds).
+     * Set to 0 to disable (immediate trigger on init).
+     * @default 0
+     * @example 5000  // 5 seconds
+     */
+    delay?: number;
+
+    /**
+     * Pause timer when tab is hidden (Page Visibility API).
+     * When true, only counts "active viewing time".
+     * When false, timer runs even when tab is hidden.
+     * @default true
+     */
+    pauseWhenHidden?: boolean;
+  };
+}
+
+/**
+ * Time Delay Event Payload
+ *
+ * Emitted via 'trigger:timeDelay' when the configured delay is reached.
+ */
+export interface TimeDelayEvent {
+  /** Timestamp when the trigger event was emitted */
+  timestamp: number;
+
+  /** Total elapsed time since init (milliseconds, includes paused time) */
+  elapsed: number;
+
+  /** Active elapsed time (milliseconds, excludes time when tab was hidden) */
+  activeElapsed: number;
+
+  /** Whether the timer was paused at any point */
+  wasPaused: boolean;
+
+  /** Number of times visibility changed (hidden/visible) */
+  visibilityChanges: number;
+}
+
+/**
+ * Time Delay Plugin API
+ */
+export interface TimeDelayPlugin {
+  /**
+   * Get total elapsed time since init (includes paused time)
+   * @returns Time in milliseconds
+   */
+  getElapsed(): number;
+
+  /**
+   * Get active elapsed time (excludes paused time)
+   * @returns Time in milliseconds
+   */
+  getActiveElapsed(): number;
+
+  /**
+   * Get remaining time until trigger
+   * @returns Time in milliseconds, or 0 if already triggered
+   */
+  getRemaining(): number;
+
+  /**
+   * Check if timer is currently paused (tab hidden)
+   * @returns True if paused
+   */
+  isPaused(): boolean;
+
+  /**
+   * Check if trigger has fired
+   * @returns True if triggered
+   */
+  isTriggered(): boolean;
+
+  /**
+   * Reset timer to initial state
+   * Clears trigger flag and restarts timing
+   */
+  reset(): void;
+}

package/src/types.ts

@@ -3,10 +3,25 @@
  * These types are re-exported by core for user convenience
  */
 
+import type { InlineContent as _InlineContent } from './inline/types';
+// Import modal and inline content types from their plugins
+import type { ModalContent as _ModalContent } from './modal/types';
+export type ModalContent = _ModalContent;
+export type InlineContent = _InlineContent;
+
 /**
- * Experience content - varies by type
+ * Experience button configuration (used across all experience types)
  */
-export type ExperienceContent = BannerContent | ModalContent | TooltipContent;
+export interface ExperienceButton {
+  text: string;
+  action?: string;
+  url?: string;
+  variant?: 'primary' | 'secondary' | 'link';
+  dismiss?: boolean;
+  metadata?: Record<string, any>;
+  className?: string;
+  style?: Record<string, string>;
+}
 
 /**
  * Banner content configuration
@@ -14,31 +29,13 @@ export type ExperienceContent = BannerContent | ModalContent | TooltipContent;
 export interface BannerContent {
   title?: string;
   message: string;
-  buttons?: Array<{
-    text: string;
-    action?: string;
-    url?: string;
-    variant?: 'primary' | 'secondary' | 'link';
-    metadata?: Record<string, any>;
-    className?: string;
-    style?: Record<string, string>;
-  }>;
+  buttons?: ExperienceButton[];
   dismissable?: boolean;
   position?: 'top' | 'bottom';
   className?: string;
   style?: Record<string, string>;
 }
 
-/**
- * Modal content configuration
- */
-export interface ModalContent {
-  title: string;
-  message: string;
-  confirmText?: string;
-  cancelText?: string;
-}
-
 /**
  * Tooltip content configuration
  */
@@ -48,22 +45,9 @@ export interface TooltipContent {
 }
 
 /**
- * Modal content configuration
- */
-export interface ModalContent {
-  title: string;
-  message: string;
-  confirmText?: string;
-  cancelText?: string;
-}
-
-/**
- * Tooltip content configuration
+ * Experience content - varies by type
  */
-export interface TooltipContent {
-  message: string;
-  position?: 'top' | 'bottom' | 'left' | 'right';
-}
+export type ExperienceContent = BannerContent | ModalContent | InlineContent | TooltipContent;
 
 /**
  * Experience definition

package/src/utils/sanitize.ts

@@ -11,7 +11,7 @@
  * Allowed HTML tags for sanitization
  * Only safe formatting tags are permitted
  */
-const ALLOWED_TAGS = ['strong', 'em', 'a', 'br', 'span', 'b', 'i', 'p'] as const;
+const ALLOWED_TAGS = ['strong', 'em', 'a', 'br', 'span', 'b', 'i', 'p', 'div', 'ul', 'li'] as const;
 
 /**
  * Allowed attributes per tag
@@ -20,6 +20,9 @@ const ALLOWED_ATTRIBUTES: Record<string, string[]> = {
   a: ['href', 'class', 'style', 'title'],
   span: ['class', 'style'],
   p: ['class', 'style'],
+  div: ['class', 'style'],
+  ul: ['class', 'style'],
+  li: ['class', 'style'],
   // Other tags have no attributes allowed
 };
 
@@ -92,7 +95,7 @@ export function sanitizeHTML(html: string): string {
         }
       }
 
-      const attrString = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
+      const attrString = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
 
       // Process child nodes
       let innerHTML = '';