@prosdevlab/experience-sdk-plugins 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -117,6 +117,7 @@ interface BannerPluginConfig {
         position?: 'top' | 'bottom';
         dismissable?: boolean;
         zIndex?: number;
+        pushDown?: string;
     };
 }
 interface BannerPlugin {
@@ -134,7 +135,23 @@ interface BannerPlugin {
  * import { createInstance } from '@prosdevlab/experience-sdk';
  * import { bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
  *
- * const sdk = createInstance({ banner: { position: 'top', dismissable: true } });
+ * // Basic usage (banner overlays at top)
+ * const sdk = createInstance({
+ *   banner: {
+ *     position: 'top',
+ *     dismissable: true
+ *   }
+ * });
+ * sdk.use(bannerPlugin);
+ *
+ * // With pushDown (pushes navigation down instead of overlaying)
+ * const sdk = createInstance({
+ *   banner: {
+ *     position: 'top',
+ *     dismissable: true,
+ *     pushDown: 'header' // CSS selector of element to push down
+ *   }
+ * });
  * sdk.use(bannerPlugin);
  * ```
  */
@@ -175,6 +192,140 @@ interface DebugPlugin {
  */
 declare const debugPlugin: PluginFunction;
 
+/**
+ * Exit Intent Plugin Configuration
+ */
+interface ExitIntentPluginConfig {
+    exitIntent?: {
+        /**
+         * Maximum Y position (px) where exit intent can trigger
+         * @default 50
+         */
+        sensitivity?: number;
+        /**
+         * Minimum time on page (ms) before exit intent is active
+         * Prevents immediate triggers on page load
+         * @default 2000
+         */
+        minTimeOnPage?: number;
+        /**
+         * Delay (ms) between detection and trigger
+         * @default 0
+         */
+        delay?: number;
+        /**
+         * Number of mouse positions to track for velocity calculation
+         * @default 30
+         */
+        positionHistorySize?: number;
+        /**
+         * Disable exit intent on mobile devices
+         * @default true
+         */
+        disableOnMobile?: boolean;
+    };
+}
+/**
+ * Exit Intent Event Payload
+ */
+interface ExitIntentEvent {
+    timestamp: number;
+    lastY: number;
+    previousY: number;
+    velocity: number;
+    timeOnPage: number;
+}
+/**
+ * Exit Intent Plugin API
+ */
+interface ExitIntentPlugin {
+    isTriggered(): boolean;
+    reset(): void;
+    getPositions(): Array<{
+        x: number;
+        y: number;
+    }>;
+}
+
+/**
+ * Exit Intent Plugin
+ *
+ * Detects when users are about to leave the page by tracking upward mouse movement
+ * near the top of the viewport. Inspired by Pathfora's showOnExitIntent.
+ *
+ * **Event-Driven Architecture:**
+ * This plugin emits `trigger:exitIntent` events when exit intent is detected.
+ * The core runtime listens for these events and automatically re-evaluates experiences.
+ *
+ * **Usage Pattern:**
+ * Use `targeting.custom` to check if exit intent has triggered:
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { init, register } from '@prosdevlab/experience-sdk';
+ * import { exitIntentPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * init({
+ *   plugins: [exitIntentPlugin],
+ *   exitIntent: {
+ *     sensitivity: 20,      // Trigger within 20px of top (default: 50)
+ *     minTimeOnPage: 2000,  // Wait 2s before enabling (default: 2000)
+ *     delay: 0,             // Delay after trigger (default: 0)
+ *     disableOnMobile: true // Disable on mobile (default: true)
+ *   }
+ * });
+ *
+ * // Show banner only when exit intent is detected
+ * register('exit-offer', {
+ *   type: 'banner',
+ *   content: {
+ *     title: 'Wait! Don't leave yet!',
+ *     message: 'Get 15% off your first order',
+ *     buttons: [{ text: 'Claim Offer', variant: 'primary' }]
+ *   },
+ *   targeting: {
+ *     custom: (context) => context.triggers?.exitIntent?.triggered === true
+ *   },
+ *   frequency: { max: 1, per: 'session' } // Only show once per session
+ * });
+ * ```
+ *
+ * @example Combining with other conditions
+ * ```typescript
+ * // Show exit offer only on shop pages with items in cart
+ * register('cart-recovery', {
+ *   type: 'banner',
+ *   content: { message: 'Complete your purchase and save!' },
+ *   targeting: {
+ *     url: { contains: '/shop' },
+ *     custom: (context) => {
+ *       return (
+ *         context.triggers?.exitIntent?.triggered === true &&
+ *         getCart().items.length > 0
+ *       );
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Combining multiple triggers (exit intent + scroll depth)
+ * ```typescript
+ * // Show offer on exit intent OR after 70% scroll
+ * register('engaged-exit', {
+ *   type: 'banner',
+ *   content: { message: 'You're almost there!' },
+ *   targeting: {
+ *     custom: (context) => {
+ *       const exitIntent = context.triggers?.exitIntent?.triggered;
+ *       const scrolled = (context.triggers?.scrollDepth?.percent || 0) >= 70;
+ *       return exitIntent || scrolled;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const exitIntentPlugin: PluginFunction;
+
 /**
  * Frequency Capping Plugin
  *
@@ -210,4 +361,477 @@ interface FrequencyPlugin {
  */
 declare const frequencyPlugin: PluginFunction;
 
-export { type BannerContent, type BannerPlugin, type BannerPluginConfig, type DebugPlugin, type DebugPluginConfig, type Decision, type DecisionMetadata, type Experience, type ExperienceContent, type FrequencyPlugin, type FrequencyPluginConfig, type ModalContent, type TooltipContent, type TraceStep, bannerPlugin, debugPlugin, frequencyPlugin };
+/**
+ * Page Visits Plugin Types
+ *
+ * Generic page visit tracking for any SDK built on sdk-kit.
+ * Tracks session and lifetime visit counts with first-visit detection.
+ */
+/**
+ * Page visits plugin configuration
+ */
+interface PageVisitsPluginConfig {
+    pageVisits?: {
+        /**
+         * Enable/disable page visit tracking
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Honor Do Not Track browser setting
+         * @default true
+         */
+        respectDNT?: boolean;
+        /**
+         * Storage key for session count
+         * @default 'pageVisits:session'
+         */
+        sessionKey?: string;
+        /**
+         * Storage key for lifetime data
+         * @default 'pageVisits:total'
+         */
+        totalKey?: string;
+        /**
+         * TTL for lifetime data in seconds (GDPR compliance)
+         * @default undefined (no expiration)
+         */
+        ttl?: number;
+        /**
+         * Automatically increment on plugin load
+         * @default true
+         */
+        autoIncrement?: boolean;
+    };
+}
+/**
+ * Page visits event payload
+ */
+interface PageVisitsEvent {
+    /** Whether this is the user's first visit ever */
+    isFirstVisit: boolean;
+    /** Total visits across all sessions (lifetime) */
+    totalVisits: number;
+    /** Visits in current session */
+    sessionVisits: number;
+    /** Timestamp of first visit (unix ms) */
+    firstVisitTime?: number;
+    /** Timestamp of last visit (unix ms) */
+    lastVisitTime?: number;
+    /** Timestamp of current visit (unix ms) */
+    timestamp: number;
+}
+/**
+ * Page visits plugin API
+ */
+interface PageVisitsPlugin {
+    /**
+     * Get total visit count (lifetime)
+     */
+    getTotalCount(): number;
+    /**
+     * Get session visit count
+     */
+    getSessionCount(): number;
+    /**
+     * Check if this is the first visit
+     */
+    isFirstVisit(): boolean;
+    /**
+     * Get timestamp of first visit
+     */
+    getFirstVisitTime(): number | undefined;
+    /**
+     * Get timestamp of last visit
+     */
+    getLastVisitTime(): number | undefined;
+    /**
+     * Manually increment page visit
+     * (useful if autoIncrement is disabled)
+     */
+    increment(): void;
+    /**
+     * Reset all counters and data
+     * (useful for testing or user opt-out)
+     */
+    reset(): void;
+    /**
+     * Get full page visits state
+     */
+    getState(): PageVisitsEvent;
+}
+
+/**
+ * Page Visits Plugin
+ *
+ * Generic page visit tracking for any SDK built on sdk-kit.
+ *
+ * Features:
+ * - Session-scoped counter (sessionStorage)
+ * - Lifetime counter with timestamps (localStorage)
+ * - First-visit detection
+ * - DNT (Do Not Track) support
+ * - GDPR-compliant expiration
+ * - Auto-loads storage plugin if missing
+ *
+ * Events emitted:
+ * - 'pageVisits:incremented' with PageVisitsEvent
+ * - 'pageVisits:reset'
+ * - 'pageVisits:disabled' with { reason: 'dnt' | 'config' }
+ *
+ * @example
+ * ```typescript
+ * import { SDK } from '@lytics/sdk-kit';
+ * import { storagePlugin, pageVisitsPlugin } from '@lytics/sdk-kit-plugins';
+ *
+ * const sdk = new SDK({
+ *   pageVisits: {
+ *     enabled: true,
+ *     respectDNT: true,
+ *     ttl: 31536000  // 1 year
+ *   }
+ * });
+ *
+ * sdk.use(storagePlugin);
+ * sdk.use(pageVisitsPlugin);
+ *
+ * // Listen to visit events
+ * sdk.on('pageVisits:incremented', (event) => {
+ *   console.log('Visit count:', event.totalVisits);
+ *   if (event.isFirstVisit) {
+ *     console.log('Welcome, first-time visitor!');
+ *   }
+ * });
+ *
+ * // API methods
+ * console.log(sdk.pageVisits.getTotalCount());      // 5
+ * console.log(sdk.pageVisits.getSessionCount());    // 2
+ * console.log(sdk.pageVisits.isFirstVisit());       // false
+ * ```
+ */
+
+declare const pageVisitsPlugin: PluginFunction;
+
+/** @module scrollDepthPlugin */
+
+/**
+ * Scroll Depth Plugin
+ *
+ * Tracks scroll depth and emits `trigger:scrollDepth` events when thresholds are crossed.
+ *
+ * ## How It Works
+ *
+ * 1. **Detection**: Listens to `scroll` events (throttled)
+ * 2. **Calculation**: Calculates current scroll percentage
+ * 3. **Tracking**: Tracks maximum scroll depth and threshold crossings
+ * 4. **Emission**: Emits `trigger:scrollDepth` events when thresholds are crossed
+ *
+ * ## Configuration
+ *
+ * ```typescript
+ * init({
+ *   scrollDepth: {
+ *     thresholds: [25, 50, 75, 100],  // Percentages to track
+ *     throttle: 100,                   // Throttle interval (ms)
+ *     includeViewportHeight: true,     // Calculation method
+ *     recalculateOnResize: true        // Recalculate on resize
+ *   }
+ * });
+ * ```
+ *
+ * ## Experience Targeting
+ *
+ * ```typescript
+ * register('mid-article-cta', {
+ *   type: 'banner',
+ *   content: { message: 'Enjoying the article?' },
+ *   targeting: {
+ *     custom: (ctx) => (ctx.triggers?.scrollDepth?.percent || 0) >= 50
+ *   }
+ * });
+ * ```
+ *
+ * ## API Methods
+ *
+ * ```typescript
+ * // Get maximum scroll percentage reached
+ * instance.scrollDepth.getMaxPercent(); // 73
+ *
+ * // Get current scroll percentage
+ * instance.scrollDepth.getCurrentPercent(); // 50
+ *
+ * // Get all crossed thresholds
+ * instance.scrollDepth.getThresholdsCrossed(); // [25, 50]
+ *
+ * // Reset tracking (useful for testing)
+ * instance.scrollDepth.reset();
+ * ```
+ *
+ * @param plugin Plugin interface from sdk-kit
+ * @param instance SDK instance
+ * @param config SDK configuration
+ */
+declare const scrollDepthPlugin: PluginFunction;
+
+/** @module scrollDepthPlugin */
+/**
+ * Scroll Depth Plugin API
+ */
+interface ScrollDepthPlugin {
+    getMaxPercent(): number;
+    getCurrentPercent(): number;
+    getThresholdsCrossed(): number[];
+    getDevice(): 'mobile' | 'tablet' | 'desktop';
+    getAdvancedMetrics(): {
+        timeOnPage: number;
+        directionChanges: number;
+        timeScrollingUp: number;
+        thresholdTimes: Record<number, number>;
+    } | null;
+    reset(): void;
+}
+/**
+ * Scroll Depth Plugin Configuration
+ *
+ * Tracks scroll depth and emits trigger:scrollDepth events when thresholds are crossed.
+ */
+interface ScrollDepthPluginConfig {
+    scrollDepth?: {
+        /**
+         * Array of scroll percentage thresholds to track (0-100).
+         * When user scrolls past a threshold, a trigger:scrollDepth event is emitted.
+         * @default [25, 50, 75, 100]
+         * @example [50, 100]
+         */
+        thresholds?: number[];
+        /**
+         * Throttle interval in milliseconds for scroll event handler.
+         * Lower values are more responsive but impact performance.
+         * @default 100
+         * @example 200
+         */
+        throttle?: number;
+        /**
+         * Include viewport height in scroll percentage calculation.
+         *
+         * - true: (scrollTop + viewportHeight) / totalHeight
+         *   More intuitive: 100% when bottom of viewport reaches end
+         * - false: scrollTop / (totalHeight - viewportHeight)
+         *   Pathfora's method: 100% when top of viewport reaches end
+         *
+         * @default true
+         */
+        includeViewportHeight?: boolean;
+        /**
+         * Recalculate scroll on window resize.
+         * Useful for responsive layouts where content height changes.
+         * @default true
+         */
+        recalculateOnResize?: boolean;
+        /**
+         * Track advanced metrics (velocity, direction, time-to-threshold).
+         * Enables advanced engagement quality analysis.
+         * Slight performance overhead but provides rich insights.
+         * @default false
+         */
+        trackAdvancedMetrics?: boolean;
+        /**
+         * Velocity threshold (px/ms) to consider "fast scrolling".
+         * Fast scrolling often indicates skimming rather than reading.
+         * Only used when trackAdvancedMetrics is true.
+         * @default 3
+         */
+        fastScrollVelocityThreshold?: number;
+        /**
+         * Disable scroll tracking on mobile devices.
+         * Useful since mobile scroll behavior differs significantly from desktop.
+         * @default false
+         */
+        disableOnMobile?: boolean;
+    };
+}
+/**
+ * Scroll Depth Event Payload
+ *
+ * Emitted as `trigger:scrollDepth` when a threshold is crossed.
+ */
+interface ScrollDepthEvent {
+    /** Whether the trigger has fired */
+    triggered: boolean;
+    /** Timestamp when the event was emitted */
+    timestamp: number;
+    /** Current scroll percentage (0-100) */
+    percent: number;
+    /** Maximum scroll percentage reached during session */
+    maxPercent: number;
+    /** The threshold that was just crossed */
+    threshold: number;
+    /** All thresholds that have been triggered */
+    thresholdsCrossed: number[];
+    /** Device type (mobile, tablet, desktop) */
+    device: 'mobile' | 'tablet' | 'desktop';
+    /** Advanced metrics (only present when trackAdvancedMetrics is enabled) */
+    advanced?: {
+        /** Time in milliseconds to reach this threshold from page load */
+        timeToThreshold: number;
+        /** Current scroll velocity in pixels per millisecond */
+        velocity: number;
+        /** Whether user is scrolling fast (indicates skimming) */
+        isFastScrolling: boolean;
+        /** Number of direction changes (up/down) since last threshold */
+        directionChanges: number;
+        /** Total time spent scrolling up (indicates seeking behavior) */
+        timeScrollingUp: number;
+        /** Scroll quality score (0-100, higher = more engaged) */
+        engagementScore: number;
+    };
+}
+
+/** @module timeDelayPlugin */
+/**
+ * Time Delay Plugin Configuration
+ *
+ * Tracks time elapsed since SDK initialization and emits trigger:timeDelay events.
+ */
+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.
+ */
+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
+ */
+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;
+}
+
+/** @module timeDelayPlugin */
+
+/**
+ * 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
+ */
+declare const timeDelayPlugin: PluginFunction;
+
+export { type BannerContent, type BannerPlugin, type BannerPluginConfig, type DebugPlugin, type DebugPluginConfig, type Decision, type DecisionMetadata, type ExitIntentEvent, type ExitIntentPlugin, type ExitIntentPluginConfig, type Experience, type ExperienceContent, type FrequencyPlugin, type FrequencyPluginConfig, type ModalContent, type PageVisitsEvent, type PageVisitsPlugin, type PageVisitsPluginConfig, type ScrollDepthEvent, type ScrollDepthPlugin, type ScrollDepthPluginConfig, type TimeDelayEvent, type TimeDelayPlugin, type TimeDelayPluginConfig, type TooltipContent, type TraceStep, bannerPlugin, debugPlugin, exitIntentPlugin, frequencyPlugin, pageVisitsPlugin, scrollDepthPlugin, timeDelayPlugin };