@prosdevlab/experience-sdk 0.1.5 → 0.3.0

package/README.md

@@ -2,17 +2,20 @@
 
 A lightweight, explainable client-side experience runtime built on [@lytics/sdk-kit](https://github.com/lytics/sdk-kit).
 
-**Size:** 6.9 KB gzipped (includes core + 3 plugins)
+**Size:** 13.4 KB gzipped core + 12.7 KB gzipped plugins = 26.1 KB total
 
 ## Features
 
 - **Explainability-First** - Every decision includes structured reasons
 - **Plugin-Based** - Built on sdk-kit's powerful plugin system
-- **Multiple Buttons** - Primary, secondary, and link variants
-- **Frequency Capping** - Control impression limits per session/day/week
+- **Multiple Layouts** - Banners, modals, and inline experiences
+- **Form Support** - Email capture with built-in validation
+- **Display Conditions** - Exit intent, scroll depth, time delays, page visits
+- **Frequency Capping** - Control impression limits per session/lifetime
 - **Responsive Layout** - Automatically adapts to mobile/desktop
 - **Script Tag Ready** - Works without build tools
 - **Type-Safe** - Full TypeScript support
+- **CSS Variables** - Full theming support
 
 ## Installation
 
@@ -41,18 +44,41 @@ const experiences = createInstance({ debug: true });
 // Initialize
 await experiences.init();
 
-// Register a banner
+// Register a modal with form
+experiences.register('newsletter', {
+  type: 'modal',
+  targeting: {
+    custom: (context) => context.triggers.exitIntent
+  },
+  content: {
+    title: 'Before You Go!',
+    message: 'Subscribe for 10% off your first order.',
+    size: 'sm',
+    form: {
+      fields: [
+        { name: 'email', type: 'email', required: true, placeholder: 'you@example.com' }
+      ],
+      submitButton: { text: 'Get Discount', variant: 'primary' },
+      successState: { 
+        title: '✓ Check Your Inbox',
+        message: 'Your discount code is on the way!'
+      }
+    }
+  }
+});
+
+// Or register a banner
 experiences.register('welcome', {
   type: 'banner',
   targeting: {
     url: { contains: '/' }
   },
   content: {
-    title: 'Welcome!',
-    message: 'Thanks for visiting.',
+    message: 'Welcome! Get 20% off today.',
     buttons: [
-      { text: 'Get Started', url: '/start', variant: 'primary' }
-    ]
+      { text: 'Shop Now', url: '/shop', variant: 'primary' }
+    ],
+    position: 'top'
   },
   frequency: {
     max: 3,
@@ -128,9 +154,20 @@ experiences.on('experiences:dismissed', ({ experienceId }) => {
 
 ## Included Plugins
 
-This package includes three official plugins:
+This package auto-registers the following official plugins:
+
+### Layout Plugins
+- **Banner Plugin** - Top/bottom notification bars
+- **Modal Plugin** - Overlay dialogs with forms
+- **Inline Plugin** - In-content experiences
+
+### Display Conditions
+- **Exit Intent** - Detect when users are leaving
+- **Scroll Depth** - Track scroll engagement
+- **Page Visits** - Session and lifetime counters
+- **Time Delay** - Show after time elapsed
 
-- **Banner Plugin** - DOM rendering with responsive layout
+### Utility Plugins
 - **Frequency Plugin** - Impression tracking and capping
 - **Debug Plugin** - Logging and window events
 

package/dist/experience-sdk.d.ts

@@ -1,5 +1,6 @@
 import { BannerContent, ModalContent, TooltipContent } from '@prosdevlab/experience-sdk-plugins';
 export { BannerContent, ModalContent, TooltipContent, bannerPlugin, debugPlugin, frequencyPlugin } from '@prosdevlab/experience-sdk-plugins';
+import { SDK } from '@lytics/sdk-kit';
 
 /**
  * Type Definitions for Experience SDK
@@ -17,7 +18,7 @@ interface Experience {
     /** Unique identifier for the experience */
     id: string;
     /** Type of experience to render */
-    type: 'banner' | 'modal' | 'tooltip';
+    type: 'banner' | 'modal' | 'tooltip' | 'inline';
     /** Rules that determine when/where to show this experience */
     targeting: TargetingRules;
     /** Content to display (type-specific) */
@@ -26,6 +27,8 @@ interface Experience {
     frequency?: FrequencyConfig;
     /** Priority for ordering (higher = more important, default: 0) */
     priority?: number;
+    /** Display conditions (triggers, timing) */
+    display?: DisplayConditions;
 }
 /**
  * Targeting Rules
@@ -75,6 +78,19 @@ interface FrequencyConfig {
     /** Time period for the cap */
     per: 'session' | 'day' | 'week';
 }
+/**
+ * Display Conditions
+ *
+ * Conditions that determine when an experience should be displayed.
+ */
+interface DisplayConditions {
+    /** Trigger type (e.g., scrollDepth, exitIntent, timeDelay) */
+    trigger?: string;
+    /** Trigger-specific configuration data */
+    triggerData?: any;
+    /** Frequency capping for this experience */
+    frequency?: FrequencyConfig;
+}
 
 /**
  * Experience Content (type-specific)
@@ -110,6 +126,68 @@ interface Context {
     timestamp?: number;
     /** Custom context properties */
     custom?: Record<string, any>;
+    /** Trigger state (for display condition plugins) */
+    triggers?: TriggerState;
+}
+/**
+ * Trigger State
+ *
+ * Tracks which trigger-based display conditions have fired.
+ * Used by plugins like exitIntent, scrollDepth, pageVisits, timeDelay.
+ */
+interface TriggerState {
+    /** Exit intent trigger state */
+    exitIntent?: {
+        /** Whether the trigger has fired */
+        triggered: boolean;
+        /** When the trigger fired (unix timestamp) */
+        timestamp?: number;
+        /** Additional trigger-specific data */
+        lastY?: number;
+        previousY?: number;
+        velocity?: number;
+        timeOnPage?: number;
+    };
+    /** Scroll depth trigger state */
+    scrollDepth?: {
+        triggered: boolean;
+        timestamp?: number;
+        /** Current scroll percentage (0-100) */
+        percent?: number;
+    };
+    /** Page visits trigger state */
+    pageVisits?: {
+        triggered: boolean;
+        timestamp?: number;
+        /** Total visit count */
+        count?: number;
+        /** Whether this is the first visit */
+        firstVisit?: boolean;
+    };
+    /** Time delay trigger state */
+    timeDelay?: {
+        triggered: boolean;
+        timestamp?: number;
+        /** Total elapsed time (ms, includes paused time) */
+        elapsed?: number;
+        /** Active elapsed time (ms, excludes paused time) */
+        activeElapsed?: number;
+        /** Whether timer was paused */
+        wasPaused?: boolean;
+        /** Number of visibility changes */
+        visibilityChanges?: number;
+    };
+    /** Modal trigger state (when modal is shown) */
+    modal?: {
+        triggered: boolean;
+        timestamp?: number;
+        /** Experience ID of the shown modal */
+        experienceId?: string;
+        /** Whether the modal is currently showing */
+        shown?: boolean;
+    };
+    /** Extensible for future triggers */
+    [key: string]: any;
 }
 /**
  * User Context
@@ -218,12 +296,26 @@ interface RuntimeState {
  * - Explainability-first (every decision has reasons)
  */
 declare class ExperienceRuntime {
-    private sdk;
+    sdk: SDK;
     private experiences;
     private decisions;
     private initialized;
     private destroyed;
+    private triggerContext;
     constructor(config?: ExperienceConfig);
+    /**
+     * Setup listeners for trigger:* events
+     * This enables event-driven display conditions
+     */
+    /**
+     * Setup listeners for trigger:* events
+     * This enables event-driven display conditions
+     *
+     * Note: sdk-kit's emitter passes only the event payload to wildcard listeners,
+     * not the event name. Display condition plugins must include trigger metadata
+     * in their payload (e.g., { trigger: 'exitIntent', ...data })
+     */
+    private setupTriggerListeners;
     /**
      * Initialize the runtime
      */
@@ -414,5 +506,16 @@ declare function on(event: string, handler: (...args: unknown[]) => void): () =>
  * ```
  */
 declare function destroy(): Promise<void>;
+declare const experiencesProxy: {
+    createInstance: typeof createInstance;
+    init: typeof init;
+    register: typeof register;
+    evaluate: typeof evaluate;
+    evaluateAll: typeof evaluateAll;
+    explain: typeof explain;
+    getState: typeof getState;
+    on: typeof on;
+    destroy: typeof destroy;
+};
 
-export { type Context, type Decision, type DecisionMetadata, type Experience, type ExperienceConfig, type ExperienceContent, ExperienceRuntime, type FrequencyConfig, type FrequencyRule, type ModalAction, type RuntimeState, type TargetingRules, type TraceStep, type UrlRule, type UserContext, buildContext, createInstance, destroy, evaluate, evaluateAll, evaluateExperience, evaluateUrlRule, explain, getState, init, on, register };
+export { type Context, type Decision, type DecisionMetadata, type Experience, type ExperienceConfig, type ExperienceContent, ExperienceRuntime, type FrequencyConfig, type FrequencyRule, type ModalAction, type RuntimeState, type TargetingRules, type TraceStep, type UrlRule, type UserContext, buildContext, createInstance, destroy, evaluate, evaluateAll, evaluateExperience, evaluateUrlRule, experiencesProxy as experiences, explain, getState, init, on, register };