@prosdevlab/experience-sdk-plugins 0.1.4 → 0.3.0

package/src/modal/types.ts

@@ -0,0 +1,114 @@
+import type { PluginFunction } from '@lytics/sdk-kit';
+import type { ExperienceButton } from '../types';
+
+export 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;
+  };
+}
+
+export interface ModalContent {
+  /** 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>;
+}
+
+export 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;
+}
+
+export 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>;
+}
+
+export interface FormState {
+  /** Title to show in success/error state */
+  title?: string;
+  /** Message to show */
+  message: string;
+  /** Optional buttons (e.g., "Close", "Try Again") */
+  buttons?: ExperienceButton[];
+}
+
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** Validation errors by field name */
+  errors?: Record<string, string>;
+}
+
+export 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;
+}
+
+export type { PluginFunction };

package/src/page-visits/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Page Visits Plugin - Barrel Export
+ */
+
+export { pageVisitsPlugin } from './page-visits';
+export type { PageVisitsEvent, PageVisitsPlugin, PageVisitsPluginConfig } from './types';

package/src/page-visits/page-visits.test.ts

@@ -0,0 +1,562 @@
+/**
+ * Page Visits Plugin Tests
+ *
+ * Comprehensive tests covering:
+ * - Session and lifetime counting
+ * - First-visit detection
+ * - Storage persistence
+ * - DNT (Do Not Track) support
+ * - API methods
+ * - Event emission
+ */
+
+import { SDK } from '@lytics/sdk-kit';
+import { storagePlugin } from '@lytics/sdk-kit-plugins';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { pageVisitsPlugin } from './index';
+import type { PageVisitsEvent, PageVisitsPlugin } from './types';
+
+type SDKWithPageVisits = SDK & {
+  pageVisits: PageVisitsPlugin;
+};
+
+describe('Page Visits Plugin', () => {
+  let sdk: SDKWithPageVisits;
+
+  // Helper to initialize plugin with config
+  const initPlugin = async (config?: any) => {
+    sdk = new SDK({
+      pageVisits: config,
+      storage: { backend: 'memory' },
+    }) as SDKWithPageVisits;
+    sdk.use(storagePlugin);
+    sdk.use(pageVisitsPlugin);
+    await sdk.init();
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Clear storage
+    sessionStorage.clear();
+    localStorage.clear();
+    // Reset DNT mock
+    Object.defineProperty(navigator, 'doNotTrack', {
+      value: '0',
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    if (sdk) {
+      sdk.destroy?.();
+    }
+  });
+
+  describe('Default Configuration', () => {
+    it('should initialize with default config', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits).toBeDefined();
+    });
+
+    it('should auto-increment on initialization', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+      expect(sdk.pageVisits.getSessionCount()).toBe(1);
+    });
+
+    it('should detect first visit', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.isFirstVisit()).toBe(false); // After increment, no longer first
+    });
+  });
+
+  describe('Session Counter (sessionStorage)', () => {
+    it('should increment session count on each page load', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getSessionCount()).toBe(1);
+
+      // Simulate second page load (reinitialize)
+      sdk.destroy?.();
+      await initPlugin();
+      expect(sdk.pageVisits.getSessionCount()).toBe(2);
+    });
+
+    it('should reset session count when sessionStorage is cleared', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getSessionCount()).toBe(1);
+
+      // Clear session storage
+      sessionStorage.clear();
+
+      // Reinitialize
+      sdk.destroy?.();
+      await initPlugin();
+      expect(sdk.pageVisits.getSessionCount()).toBe(1); // Back to 1
+    });
+
+    it('should not persist session count across tabs', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getSessionCount()).toBe(1);
+
+      // Session storage is tab-specific, so count shouldn't persist
+      // (This is a characteristic test, not a functional test)
+      expect(sessionStorage.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Lifetime Counter (localStorage)', () => {
+    it('should increment total count on each page load', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+
+      // Simulate second page load (reinitialize)
+      sdk.destroy?.();
+      await initPlugin();
+      expect(sdk.pageVisits.getTotalCount()).toBe(2);
+
+      // Third page load
+      sdk.destroy?.();
+      await initPlugin();
+      expect(sdk.pageVisits.getTotalCount()).toBe(3);
+    });
+
+    it('should persist total count in localStorage', async () => {
+      await initPlugin();
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+
+      // Check localStorage directly
+      const stored = localStorage.getItem('pageVisits:total');
+      expect(stored).toBeDefined();
+      expect(stored).not.toBeNull();
+    });
+
+    it('should store timestamps for first and last visit', async () => {
+      await initPlugin();
+
+      const firstVisitTime = sdk.pageVisits.getFirstVisitTime();
+      const lastVisitTime = sdk.pageVisits.getLastVisitTime();
+
+      expect(firstVisitTime).toBeDefined();
+      expect(lastVisitTime).toBeDefined();
+      expect(typeof firstVisitTime).toBe('number');
+      expect(typeof lastVisitTime).toBe('number');
+    });
+
+    it('should keep first visit time constant across visits', async () => {
+      await initPlugin();
+      const firstVisitTime1 = sdk.pageVisits.getFirstVisitTime();
+
+      // Second visit
+      sdk.destroy?.();
+      await initPlugin();
+      const firstVisitTime2 = sdk.pageVisits.getFirstVisitTime();
+
+      expect(firstVisitTime1).toBe(firstVisitTime2);
+    });
+
+    it('should update last visit time on each visit', async () => {
+      await initPlugin();
+      const lastVisitTime1 = sdk.pageVisits.getLastVisitTime();
+
+      // Wait a bit
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Second visit
+      sdk.destroy?.();
+      await initPlugin();
+      const lastVisitTime2 = sdk.pageVisits.getLastVisitTime();
+
+      expect(lastVisitTime2).toBeGreaterThan(lastVisitTime1 ?? 0);
+    });
+  });
+
+  describe('First Visit Detection', () => {
+    it('should detect first visit when no data exists', async () => {
+      const events: PageVisitsEvent[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:incremented', (event: PageVisitsEvent) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events.length).toBe(1);
+      expect(events[0].isFirstVisit).toBe(true);
+      expect(events[0].totalVisits).toBe(1);
+      expect(events[0].sessionVisits).toBe(1);
+    });
+
+    it('should not be first visit on subsequent loads', async () => {
+      // First visit
+      await initPlugin();
+
+      // Second visit - set up event listener BEFORE init
+      sdk.destroy?.();
+
+      const events: PageVisitsEvent[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:incremented', (event: PageVisitsEvent) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events.length).toBe(1);
+      expect(events[0].isFirstVisit).toBe(false);
+      expect(events[0].totalVisits).toBe(2);
+    });
+  });
+
+  describe('DNT (Do Not Track)', () => {
+    it('should respect DNT when enabled', async () => {
+      // Mock DNT
+      Object.defineProperty(navigator, 'doNotTrack', {
+        value: '1',
+        configurable: true,
+      });
+
+      const events: any[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: true, respectDNT: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:disabled', (event: any) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events.length).toBe(1);
+      expect(events[0].reason).toBe('dnt');
+    });
+
+    it('should not track when DNT is enabled', async () => {
+      // Mock DNT
+      Object.defineProperty(navigator, 'doNotTrack', {
+        value: '1',
+        configurable: true,
+      });
+
+      await initPlugin({ enabled: true, respectDNT: true });
+
+      // No tracking should occur
+      expect(sdk.pageVisits.getTotalCount()).toBe(0);
+      expect(sdk.pageVisits.getSessionCount()).toBe(0);
+    });
+
+    it('should ignore DNT when respectDNT is false', async () => {
+      // Mock DNT
+      Object.defineProperty(navigator, 'doNotTrack', {
+        value: '1',
+        configurable: true,
+      });
+
+      await initPlugin({ enabled: true, respectDNT: false });
+
+      // Should still track
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+      expect(sdk.pageVisits.getSessionCount()).toBe(1);
+    });
+  });
+
+  describe('API Methods', () => {
+    describe('getTotalCount', () => {
+      it('should return total visit count', async () => {
+        await initPlugin();
+        expect(sdk.pageVisits.getTotalCount()).toBe(1);
+      });
+    });
+
+    describe('getSessionCount', () => {
+      it('should return session visit count', async () => {
+        await initPlugin();
+        expect(sdk.pageVisits.getSessionCount()).toBe(1);
+      });
+    });
+
+    describe('isFirstVisit', () => {
+      it('should return false after first increment', async () => {
+        await initPlugin();
+        expect(sdk.pageVisits.isFirstVisit()).toBe(false);
+      });
+    });
+
+    describe('getFirstVisitTime', () => {
+      it('should return first visit timestamp', async () => {
+        await initPlugin();
+        const time = sdk.pageVisits.getFirstVisitTime();
+        expect(time).toBeDefined();
+        expect(typeof time).toBe('number');
+      });
+    });
+
+    describe('getLastVisitTime', () => {
+      it('should return last visit timestamp', async () => {
+        await initPlugin();
+        const time = sdk.pageVisits.getLastVisitTime();
+        expect(time).toBeDefined();
+        expect(typeof time).toBe('number');
+      });
+    });
+
+    describe('increment', () => {
+      it('should manually increment counters', async () => {
+        await initPlugin({ autoIncrement: false });
+        expect(sdk.pageVisits.getTotalCount()).toBe(0);
+
+        sdk.pageVisits.increment();
+        expect(sdk.pageVisits.getTotalCount()).toBe(1);
+        expect(sdk.pageVisits.getSessionCount()).toBe(1);
+      });
+
+      it('should emit pageVisits:incremented event', async () => {
+        await initPlugin({ autoIncrement: false });
+
+        const events: PageVisitsEvent[] = [];
+        sdk.on('pageVisits:incremented', (event: PageVisitsEvent) => {
+          events.push(event);
+        });
+
+        sdk.pageVisits.increment();
+
+        expect(events.length).toBe(1);
+        expect(events[0].totalVisits).toBe(1);
+        expect(events[0].sessionVisits).toBe(1);
+      });
+    });
+
+    describe('reset', () => {
+      it('should reset all counters', async () => {
+        await initPlugin();
+        expect(sdk.pageVisits.getTotalCount()).toBe(1);
+
+        sdk.pageVisits.reset();
+
+        expect(sdk.pageVisits.getTotalCount()).toBe(0);
+        expect(sdk.pageVisits.getSessionCount()).toBe(0);
+        expect(sdk.pageVisits.isFirstVisit()).toBe(false);
+        expect(sdk.pageVisits.getFirstVisitTime()).toBeUndefined();
+        expect(sdk.pageVisits.getLastVisitTime()).toBeUndefined();
+      });
+
+      it('should clear storage', async () => {
+        await initPlugin();
+        sdk.pageVisits.reset();
+
+        const sessionData = sessionStorage.getItem('pageVisits:session');
+        const totalData = localStorage.getItem('pageVisits:total');
+
+        expect(sessionData).toBeNull();
+        expect(totalData).toBeNull();
+      });
+
+      it('should emit pageVisits:reset event', async () => {
+        await initPlugin();
+
+        const events: any[] = [];
+        sdk.on('pageVisits:reset', () => {
+          events.push(true);
+        });
+
+        sdk.pageVisits.reset();
+
+        expect(events.length).toBe(1);
+      });
+    });
+
+    describe('getState', () => {
+      it('should return full page visits state', async () => {
+        await initPlugin();
+
+        const state = sdk.pageVisits.getState();
+
+        expect(state).toHaveProperty('isFirstVisit');
+        expect(state).toHaveProperty('totalVisits');
+        expect(state).toHaveProperty('sessionVisits');
+        expect(state).toHaveProperty('firstVisitTime');
+        expect(state).toHaveProperty('lastVisitTime');
+        expect(state).toHaveProperty('timestamp');
+      });
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should support custom storage keys', async () => {
+      await initPlugin({
+        sessionKey: 'custom:session',
+        totalKey: 'custom:total',
+      });
+
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+
+      // Check custom keys in storage
+      const sessionData = sessionStorage.getItem('custom:session');
+      const totalData = localStorage.getItem('custom:total');
+
+      expect(sessionData).toBeDefined();
+      expect(totalData).toBeDefined();
+    });
+
+    it('should support disabling via config', async () => {
+      const events: any[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: false },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:disabled', (event: any) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events.length).toBe(1);
+      expect(events[0].reason).toBe('config');
+    });
+
+    it('should support disabling auto-increment', async () => {
+      await initPlugin({ autoIncrement: false });
+
+      expect(sdk.pageVisits.getTotalCount()).toBe(0);
+      expect(sdk.pageVisits.getSessionCount()).toBe(0);
+    });
+  });
+
+  describe('Event Emission', () => {
+    it('should emit pageVisits:incremented with full payload', async () => {
+      const events: PageVisitsEvent[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:incremented', (event: PageVisitsEvent) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events.length).toBe(1);
+      expect(events[0]).toMatchObject({
+        isFirstVisit: true,
+        totalVisits: 1,
+        sessionVisits: 1,
+      });
+      expect(events[0].firstVisitTime).toBeDefined();
+      expect(events[0].lastVisitTime).toBeDefined();
+      expect(events[0].timestamp).toBeDefined();
+    });
+  });
+
+  describe('Integration Scenarios', () => {
+    it('should track session-scoped visits correctly', async () => {
+      // First page load
+      await initPlugin();
+      const session1 = sdk.pageVisits.getSessionCount();
+      expect(session1).toBe(1);
+
+      // Second page load (same session)
+      sdk.destroy?.();
+      await initPlugin();
+      const session2 = sdk.pageVisits.getSessionCount();
+      expect(session2).toBe(2);
+
+      // Clear sessionStorage (simulate new session)
+      sessionStorage.clear();
+      sdk.destroy?.();
+      await initPlugin();
+      const session3 = sdk.pageVisits.getSessionCount();
+      expect(session3).toBe(1); // Reset
+    });
+
+    it('should track lifetime visits across sessions', async () => {
+      // First visit
+      await initPlugin();
+      const total1 = sdk.pageVisits.getTotalCount();
+      expect(total1).toBe(1);
+
+      // Second visit
+      sdk.destroy?.();
+      await initPlugin();
+      const total2 = sdk.pageVisits.getTotalCount();
+      expect(total2).toBe(2);
+
+      // Clear sessionStorage (new session) but keep localStorage
+      sessionStorage.clear();
+      sdk.destroy?.();
+      await initPlugin();
+      const total3 = sdk.pageVisits.getTotalCount();
+      expect(total3).toBe(3); // Continues incrementing
+    });
+
+    it('should support first-visit detection', async () => {
+      const events: PageVisitsEvent[] = [];
+      sdk = new SDK({
+        pageVisits: { enabled: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithPageVisits;
+      sdk.use(storagePlugin);
+      sdk.use(pageVisitsPlugin);
+
+      sdk.on('pageVisits:incremented', (event: PageVisitsEvent) => {
+        events.push(event);
+      });
+
+      await sdk.init();
+
+      expect(events[0].isFirstVisit).toBe(true);
+    });
+
+    it('should support all comparison operators in targeting', async () => {
+      await initPlugin();
+
+      // Simulate 5 visits
+      for (let i = 0; i < 4; i++) {
+        sdk.destroy?.();
+        await initPlugin();
+      }
+
+      const count = sdk.pageVisits.getTotalCount();
+      expect(count).toBe(5);
+
+      // Support all operators for flexible targeting
+      expect(count >= 5).toBe(true);
+      expect(count === 5).toBe(true);
+      expect(count < 10).toBe(true);
+    });
+  });
+
+  describe('Storage Backend Integration', () => {
+    it('should auto-load storage plugin if missing', async () => {
+      // Don't manually load storagePlugin
+      sdk = new SDK({
+        pageVisits: { enabled: true },
+      }) as SDKWithPageVisits;
+      sdk.use(pageVisitsPlugin);
+
+      await sdk.init();
+
+      // Should still work (auto-loaded)
+      expect(sdk.pageVisits.getTotalCount()).toBe(1);
+    });
+  });
+});