@prosdevlab/experience-sdk-plugins 0.1.4 → 0.3.0

package/dist/index.d.ts

@@ -1,57 +1,187 @@
-import { PluginFunction } from '@lytics/sdk-kit';
+import { PluginFunction, SDK } from '@lytics/sdk-kit';
+export { PluginFunction } from '@lytics/sdk-kit';
 
 /**
- * Shared types for Experience SDK plugins
- * These types are re-exported by core for user convenience
+ * Inline plugin configuration
  */
+interface InlinePluginConfig {
+    inline?: {
+        /** Retry selector lookup if not found (default: false) */
+        retry?: boolean;
+        /** Retry timeout in ms (default: 5000) */
+        retryTimeout?: number;
+    };
+}
 /**
- * Experience content - varies by type
- */
-type ExperienceContent = BannerContent | ModalContent | TooltipContent;
-/**
- * Banner content configuration
+ * Inline content configuration
  */
-interface BannerContent {
-    title?: string;
+interface InlineContent$1 {
+    /** CSS selector for target element */
+    selector: string;
+    /** Where to insert content (default: 'replace') */
+    position?: 'replace' | 'append' | 'prepend' | 'before' | 'after';
+    /** HTML content to insert */
     message: string;
-    buttons?: Array<{
-        text: string;
-        action?: string;
-        url?: string;
-        variant?: 'primary' | 'secondary' | 'link';
-        metadata?: Record<string, any>;
-        className?: string;
-        style?: Record<string, string>;
-    }>;
+    /** Show close button (default: false) */
     dismissable?: boolean;
-    position?: 'top' | 'bottom';
+    /** Remember dismissal in localStorage (default: false) */
+    persist?: boolean;
+    /** Custom CSS class */
     className?: string;
+    /** Inline styles */
     style?: Record<string, string>;
 }
 /**
- * Modal content configuration
+ * Inline plugin API
  */
-interface ModalContent {
-    title: string;
-    message: string;
-    confirmText?: string;
-    cancelText?: string;
+interface InlinePlugin {
+    /** Show an inline experience */
+    show(experience: any): void;
+    /** Remove a specific inline experience */
+    remove(experienceId: string): void;
+    /** Check if an inline experience is showing */
+    isShowing(experienceId?: string): boolean;
 }
 /**
- * Modal content configuration
+ * Insertion position for inline content
  */
-interface ModalContent {
-    title: string;
+type InsertionPosition = 'replace' | 'append' | 'prepend' | 'before' | 'after';
+
+interface ModalConfig {
+    modal?: {
+        /** Allow dismissal via close button (default: true) */
+        dismissable?: boolean;
+        /** Allow dismissal via backdrop click (default: true) */
+        backdropDismiss?: boolean;
+        /** Z-index for modal (default: 10001) */
+        zIndex?: number;
+        /** Modal size (default: 'md') */
+        size?: 'sm' | 'md' | 'lg' | 'fullscreen' | 'auto';
+        /** Auto-fullscreen on mobile screens <640px (default: true for 'lg', false for others) */
+        mobileFullscreen?: boolean;
+        /** Modal position (default: 'center') */
+        position?: 'center' | 'bottom';
+        /** Animation type (default: 'fade') */
+        animation?: 'fade' | 'slide-up' | 'none';
+        /** Animation duration in ms (default: 200) */
+        animationDuration?: number;
+    };
+}
+interface ModalContent$1 {
+    /** Optional hero image at top of modal */
+    image?: {
+        /** Image source URL */
+        src: string;
+        /** Alt text for accessibility */
+        alt: string;
+        /** Max height in pixels (default: 300, 200 on mobile) */
+        maxHeight?: number;
+    };
+    /** Modal title */
+    title?: string;
+    /** Modal message (supports HTML via sanitizer) */
+    message: string;
+    /** Array of action buttons */
+    buttons?: ExperienceButton[];
+    /** Optional form configuration */
+    form?: FormConfig;
+    /** Custom CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: Record<string, string>;
+}
+interface FormConfig {
+    /** Array of form fields */
+    fields: FormField[];
+    /** Submit button configuration */
+    submitButton: ExperienceButton;
+    /** Success state after submission */
+    successState?: FormState;
+    /** Error state on submission failure */
+    errorState?: FormState;
+    /** Custom validation function (optional) */
+    validate?: (data: Record<string, string>) => ValidationResult;
+}
+interface FormField {
+    /** Field name (used in form data) */
+    name: string;
+    /** Field type */
+    type: 'email' | 'text' | 'textarea' | 'tel' | 'url' | 'number';
+    /** Label text (optional) */
+    label?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Required field (default: false) */
+    required?: boolean;
+    /** Custom validation pattern (regex) */
+    pattern?: string;
+    /** Error message for validation failure */
+    errorMessage?: string;
+    /** Custom CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: Record<string, string>;
+}
+interface FormState {
+    /** Title to show in success/error state */
+    title?: string;
+    /** Message to show */
     message: string;
-    confirmText?: string;
-    cancelText?: string;
+    /** Optional buttons (e.g., "Close", "Try Again") */
+    buttons?: ExperienceButton[];
+}
+interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors by field name */
+    errors?: Record<string, string>;
 }
+interface ModalPlugin {
+    /** Show a modal experience */
+    show(experience: any): void;
+    /** Remove a specific modal */
+    remove(experienceId: string): void;
+    /** Check if a modal is showing */
+    isShowing(experienceId?: string): boolean;
+    /** Show form success or error state */
+    showFormState(experienceId: string, state: 'success' | 'error'): void;
+    /** Reset form to initial state */
+    resetForm(experienceId: string): void;
+    /** Get current form data */
+    getFormData(experienceId: string): Record<string, string> | null;
+}
+
 /**
- * Tooltip content configuration
+ * Shared types for Experience SDK plugins
+ * These types are re-exported by core for user convenience
  */
-interface TooltipContent {
+
+type ModalContent = ModalContent$1;
+type InlineContent = InlineContent$1;
+/**
+ * Experience button configuration (used across all experience types)
+ */
+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
+ */
+interface BannerContent {
+    title?: string;
     message: string;
-    position?: 'top' | 'bottom' | 'left' | 'right';
+    buttons?: ExperienceButton[];
+    dismissable?: boolean;
+    position?: 'top' | 'bottom';
+    className?: string;
+    style?: Record<string, string>;
 }
 /**
  * Tooltip content configuration
@@ -60,6 +190,10 @@ interface TooltipContent {
     message: string;
     position?: 'top' | 'bottom' | 'left' | 'right';
 }
+/**
+ * Experience content - varies by type
+ */
+type ExperienceContent = BannerContent | ModalContent | InlineContent | TooltipContent;
 /**
  * Experience definition
  */
@@ -192,6 +326,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
  *
@@ -227,4 +495,514 @@ 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 };
+/**
+ * Inline Plugin
+ *
+ * Embeds experiences directly within page content using DOM selectors.
+ * Supports multiple insertion positions and dismissal with persistence.
+ */
+declare const inlinePlugin: (plugin: any, instance: SDK, config: any) => void;
+
+/**
+ * Insert content into a target element using specified position
+ *
+ * @param selector - CSS selector for target element
+ * @param content - HTML content to insert
+ * @param position - Where to insert the content
+ * @param experienceId - Unique identifier for the experience
+ * @returns The created wrapper element, or null if target not found
+ */
+declare function insertContent(selector: string, content: string, position: InsertionPosition, experienceId: string): HTMLElement | null;
+/**
+ * Remove inline content by experience ID
+ *
+ * @param experienceId - Unique identifier for the experience
+ * @returns True if element was found and removed, false otherwise
+ */
+declare function removeContent(experienceId: string): boolean;
+
+/**
+ * Modal Plugin for @prosdevlab/experience-sdk
+ *
+ * Renders experiences as accessible modal dialogs with:
+ * - Focus trap and keyboard handling
+ * - ARIA attributes for screen readers
+ * - Backdrop and close button
+ * - Responsive design
+ */
+declare const modalPlugin: (plugin: any, instance: SDK) => void;
+
+/**
+ * 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 FormConfig, type FormField, type FormState, type FrequencyPlugin, type FrequencyPluginConfig, type InlineContent$1 as InlineContent, type InlinePlugin, type InlinePluginConfig, type InsertionPosition, type ModalConfig, type ModalContent, type ModalPlugin, type PageVisitsEvent, type PageVisitsPlugin, type PageVisitsPluginConfig, type ScrollDepthEvent, type ScrollDepthPlugin, type ScrollDepthPluginConfig, type TimeDelayEvent, type TimeDelayPlugin, type TimeDelayPluginConfig, type TooltipContent, type TraceStep, type ValidationResult, bannerPlugin, debugPlugin, exitIntentPlugin, frequencyPlugin, inlinePlugin, insertContent, modalPlugin, pageVisitsPlugin, removeContent, scrollDepthPlugin, timeDelayPlugin };