@prosdevlab/experience-sdk-plugins 0.1.0

package/src/debug/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Debug Plugin - Barrel Export
+ */
+
+export type { DebugPlugin, DebugPluginConfig } from './debug';
+export { debugPlugin } from './debug';

package/src/frequency/frequency.test.ts

@@ -0,0 +1,361 @@
+import { SDK } from '@lytics/sdk-kit';
+import { type StoragePlugin, storagePlugin } from '@lytics/sdk-kit-plugins';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Decision } from '../types';
+import { type FrequencyPlugin, frequencyPlugin } from './frequency';
+
+type SDKWithFrequency = SDK & { frequency: FrequencyPlugin; storage: StoragePlugin };
+
+describe('Frequency Plugin', () => {
+  let sdk: SDKWithFrequency;
+
+  beforeEach(() => {
+    // Clear any existing storage to avoid pollution between tests
+    if (typeof sessionStorage !== 'undefined') {
+      sessionStorage.clear();
+    }
+    if (typeof localStorage !== 'undefined') {
+      localStorage.clear();
+    }
+
+    // Use memory storage for tests
+    sdk = new SDK({
+      frequency: { enabled: true },
+      storage: { backend: 'memory' },
+    }) as SDKWithFrequency;
+
+    // Install plugins
+    sdk.use(storagePlugin);
+    sdk.use(frequencyPlugin);
+  });
+
+  describe('Plugin Registration', () => {
+    it('should register frequency plugin', () => {
+      expect(sdk.frequency).toBeDefined();
+    });
+
+    it('should expose frequency API methods', () => {
+      expect(sdk.frequency.getImpressionCount).toBeTypeOf('function');
+      expect(sdk.frequency.hasReachedCap).toBeTypeOf('function');
+      expect(sdk.frequency.recordImpression).toBeTypeOf('function');
+    });
+
+    it('should auto-load storage plugin if not present', () => {
+      const newSdk = new SDK({ frequency: { enabled: true } }) as SDKWithFrequency;
+      newSdk.use(frequencyPlugin);
+      expect(newSdk.storage).toBeDefined();
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should use default config', () => {
+      const enabled = sdk.get('frequency.enabled');
+      const namespace = sdk.get('frequency.namespace');
+
+      expect(enabled).toBe(true);
+      expect(namespace).toBe('experiences:frequency');
+    });
+
+    it('should allow custom config', () => {
+      const customSdk = new SDK({
+        frequency: { enabled: false, namespace: 'custom:freq' },
+        storage: { backend: 'memory' },
+      }) as SDKWithFrequency;
+
+      customSdk.use(storagePlugin);
+      customSdk.use(frequencyPlugin);
+
+      expect(customSdk.get('frequency.enabled')).toBe(false);
+      expect(customSdk.get('frequency.namespace')).toBe('custom:freq');
+    });
+  });
+
+  describe('Impression Tracking', () => {
+    it('should initialize impression count at 0', () => {
+      const count = sdk.frequency.getImpressionCount('welcome-banner');
+      expect(count).toBe(0);
+    });
+
+    it('should record impressions', () => {
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(1);
+
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(2);
+    });
+
+    it('should track impressions per experience independently', () => {
+      sdk.frequency.recordImpression('banner-1');
+      sdk.frequency.recordImpression('banner-2');
+      sdk.frequency.recordImpression('banner-1');
+
+      expect(sdk.frequency.getImpressionCount('banner-1')).toBe(2);
+      expect(sdk.frequency.getImpressionCount('banner-2')).toBe(1);
+    });
+
+    it('should emit impression-recorded event', () => {
+      const handler = vi.fn();
+      sdk.on('experiences:impression-recorded', handler);
+
+      sdk.frequency.recordImpression('welcome-banner');
+
+      expect(handler).toHaveBeenCalledWith({
+        experienceId: 'welcome-banner',
+        count: 1,
+        timestamp: expect.any(Number),
+      });
+    });
+
+    it('should not record impressions when disabled', () => {
+      sdk.set('frequency.enabled', false);
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(0);
+    });
+  });
+
+  describe('Session Frequency Caps', () => {
+    it('should not reach cap below limit', () => {
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 2, 'session')).toBe(false);
+    });
+
+    it('should reach cap at limit', () => {
+      sdk.frequency.recordImpression('welcome-banner');
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 2, 'session')).toBe(true);
+    });
+
+    it('should reach cap above limit', () => {
+      sdk.frequency.recordImpression('welcome-banner');
+      sdk.frequency.recordImpression('welcome-banner');
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 2, 'session')).toBe(true);
+    });
+  });
+
+  describe('Time-Based Frequency Caps', () => {
+    it('should count impressions within day window', () => {
+      const now = Date.now();
+
+      // Mock Date.now() for first impression (25 hours ago - outside window)
+      vi.spyOn(Date, 'now').mockReturnValue(now - 25 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner', 'day');
+
+      // Mock Date.now() for second impression (now - inside window)
+      vi.spyOn(Date, 'now').mockReturnValue(now);
+      sdk.frequency.recordImpression('welcome-banner', 'day');
+
+      // Only 1 impression within last 24 hours
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 2, 'day')).toBe(false);
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 1, 'day')).toBe(true);
+
+      vi.restoreAllMocks();
+    });
+
+    it('should count impressions within week window', () => {
+      const now = Date.now();
+
+      // Record 2 impressions 8 days ago (outside week window)
+      vi.spyOn(Date, 'now').mockReturnValue(now - 8 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner', 'week');
+      sdk.frequency.recordImpression('welcome-banner', 'week');
+
+      // Record 1 impression 3 days ago (inside week window)
+      vi.spyOn(Date, 'now').mockReturnValue(now - 3 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner', 'week');
+
+      // Current time
+      vi.spyOn(Date, 'now').mockReturnValue(now);
+
+      // Only 1 impression within last 7 days
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 2, 'week')).toBe(false);
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 1, 'week')).toBe(true);
+
+      vi.restoreAllMocks();
+    });
+
+    it('should handle multiple impressions within time window', () => {
+      const now = Date.now();
+
+      // Record 3 impressions within last day
+      for (let i = 0; i < 3; i++) {
+        vi.spyOn(Date, 'now').mockReturnValue(now - i * 60 * 60 * 1000); // Each hour
+        sdk.frequency.recordImpression('welcome-banner', 'day');
+      }
+
+      vi.spyOn(Date, 'now').mockReturnValue(now);
+
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 3, 'day')).toBe(true);
+      expect(sdk.frequency.hasReachedCap('welcome-banner', 4, 'day')).toBe(false);
+
+      vi.restoreAllMocks();
+    });
+  });
+
+  describe('Event Integration', () => {
+    it('should auto-record impression on experiences:evaluated event when show=true', () => {
+      const decision: Decision = {
+        show: true,
+        experienceId: 'welcome-banner',
+        reasons: ['URL matches'],
+        trace: [],
+        context: {
+          url: 'https://example.com',
+          timestamp: Date.now(),
+        },
+        metadata: {
+          evaluatedAt: Date.now(),
+          totalDuration: 10,
+          experiencesEvaluated: 1,
+        },
+      };
+
+      sdk.emit('experiences:evaluated', { decision });
+
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(1);
+    });
+
+    it('should not record impression when show=false', () => {
+      const decision: Decision = {
+        show: false,
+        reasons: ['Frequency cap reached'],
+        trace: [],
+        context: {
+          url: 'https://example.com',
+          timestamp: Date.now(),
+        },
+        metadata: {
+          evaluatedAt: Date.now(),
+          totalDuration: 10,
+          experiencesEvaluated: 1,
+        },
+      };
+
+      sdk.emit('experiences:evaluated', { decision });
+
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(0);
+    });
+
+    it('should not record impression when experienceId is missing', () => {
+      const decision: Decision = {
+        show: true,
+        reasons: ['No matching experience'],
+        trace: [],
+        context: {
+          url: 'https://example.com',
+          timestamp: Date.now(),
+        },
+        metadata: {
+          evaluatedAt: Date.now(),
+          totalDuration: 10,
+          experiencesEvaluated: 0,
+        },
+      };
+
+      sdk.emit('experiences:evaluated', { decision });
+
+      // Should not throw or record
+      expect(sdk.frequency.getImpressionCount('any-experience')).toBe(0);
+    });
+
+    it('should not auto-record when frequency plugin is disabled', () => {
+      sdk.set('frequency.enabled', false);
+
+      const decision: Decision = {
+        show: true,
+        experienceId: 'welcome-banner',
+        reasons: ['URL matches'],
+        trace: [],
+        context: {
+          url: 'https://example.com',
+          timestamp: Date.now(),
+        },
+        metadata: {
+          evaluatedAt: Date.now(),
+          totalDuration: 10,
+          experiencesEvaluated: 1,
+        },
+      };
+
+      sdk.emit('experiences:evaluated', { decision });
+
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(0);
+    });
+  });
+
+  describe('Storage Integration', () => {
+    it('should persist impressions across SDK instances (session storage)', () => {
+      // Record impression in first instance (uses sessionStorage)
+      sdk.frequency.recordImpression('welcome-banner');
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(1);
+
+      // Create second instance with same storage backend
+      const sdk2 = new SDK({
+        frequency: { enabled: true },
+        storage: { backend: 'memory' },
+      }) as SDKWithFrequency;
+      sdk2.use(storagePlugin);
+      sdk2.use(frequencyPlugin);
+
+      // Impressions SHOULD persist (sessionStorage is shared)
+      expect(sdk2.frequency.getImpressionCount('welcome-banner')).toBe(1);
+    });
+
+    it('should use namespaced storage keys', () => {
+      sdk.frequency.recordImpression('welcome-banner');
+
+      // Check sessionStorage directly (frequency plugin uses sessionStorage for 'session' per)
+      const storageKey = 'experiences:frequency:welcome-banner';
+      const storageData = JSON.parse(sessionStorage.getItem(storageKey) || '{}');
+      expect(storageData).toBeDefined();
+      expect(storageData.count).toBe(1);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle empty experience ID gracefully', () => {
+      expect(() => sdk.frequency.recordImpression('')).not.toThrow();
+      expect(sdk.frequency.getImpressionCount('')).toBe(1);
+    });
+
+    it('should handle very large impression counts', () => {
+      for (let i = 0; i < 1000; i++) {
+        sdk.frequency.recordImpression('welcome-banner');
+      }
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(1000);
+    });
+
+    it('should clean up old impressions (beyond 7 days)', () => {
+      const now = Date.now();
+
+      // Record 5 impressions: 3 old (>7 days), 2 recent
+      vi.spyOn(Date, 'now').mockReturnValue(now - 10 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner');
+
+      vi.spyOn(Date, 'now').mockReturnValue(now - 8 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner');
+
+      vi.spyOn(Date, 'now').mockReturnValue(now - 9 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner');
+
+      vi.spyOn(Date, 'now').mockReturnValue(now - 2 * 24 * 60 * 60 * 1000);
+      sdk.frequency.recordImpression('welcome-banner');
+
+      vi.spyOn(Date, 'now').mockReturnValue(now);
+      sdk.frequency.recordImpression('welcome-banner');
+
+      // Total count should be 5, but old impressions cleaned up
+      expect(sdk.frequency.getImpressionCount('welcome-banner')).toBe(5);
+
+      // Check storage for cleaned impressions array
+      const storageKey = 'experiences:frequency:welcome-banner';
+      const storageData = JSON.parse(sessionStorage.getItem(storageKey) || '{}') as {
+        impressions: number[];
+      };
+      // Should only keep impressions from last 7 days (2 recent ones)
+      expect(storageData.impressions.length).toBe(2);
+
+      vi.restoreAllMocks();
+    });
+  });
+});

package/src/frequency/frequency.ts

@@ -0,0 +1,247 @@
+/**
+ * Frequency Capping Plugin
+ *
+ * Tracks experience impressions and enforces frequency caps.
+ * Uses sdk-kit's storage plugin for persistence.
+ */
+
+import type { PluginFunction, SDK } from '@lytics/sdk-kit';
+import { type StoragePlugin, storagePlugin } from '@lytics/sdk-kit-plugins';
+import type { Decision, TraceStep } from '../types';
+
+export interface FrequencyPluginConfig {
+  frequency?: {
+    enabled?: boolean;
+    namespace?: string;
+  };
+}
+
+export interface FrequencyPlugin {
+  getImpressionCount(experienceId: string): number;
+  hasReachedCap(experienceId: string, max: number, per: 'session' | 'day' | 'week'): boolean;
+  recordImpression(experienceId: string): void;
+}
+
+interface ImpressionData {
+  count: number;
+  lastImpression: number;
+  impressions: number[];
+  per?: 'session' | 'day' | 'week'; // Track which storage type this uses
+}
+
+/**
+ * Frequency Capping Plugin
+ *
+ * Automatically tracks impressions and enforces frequency caps.
+ * Requires storage plugin for persistence.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { frequencyPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * const sdk = createInstance({ frequency: { enabled: true } });
+ * sdk.use(frequencyPlugin);
+ * ```
+ */
+export const frequencyPlugin: PluginFunction = (plugin, instance, config) => {
+  plugin.ns('frequency');
+
+  // Set defaults
+  plugin.defaults({
+    frequency: {
+      enabled: true,
+      namespace: 'experiences:frequency',
+    },
+  });
+
+  // Track experience frequency configs
+  const experienceFrequencyMap = new Map<string, 'session' | 'day' | 'week'>();
+
+  // Auto-load storage plugin if not already loaded
+  if (!(instance as SDK & { storage?: StoragePlugin }).storage) {
+    instance.use(storagePlugin);
+  }
+
+  const isEnabled = (): boolean => config.get('frequency.enabled') ?? true;
+  const getNamespace = (): string => config.get('frequency.namespace') ?? 'experiences:frequency';
+
+  // Helper to get the right storage backend based on frequency type
+  const getStorageBackend = (per: 'session' | 'day' | 'week'): Storage => {
+    return per === 'session' ? sessionStorage : localStorage;
+  };
+
+  // Helper to get storage key
+  const getStorageKey = (experienceId: string): string => {
+    return `${getNamespace()}:${experienceId}`;
+  };
+
+  // Helper to get impression data
+  const getImpressionData = (
+    experienceId: string,
+    per: 'session' | 'day' | 'week'
+  ): ImpressionData => {
+    const storage = getStorageBackend(per);
+    const key = getStorageKey(experienceId);
+    const raw = storage.getItem(key);
+
+    if (!raw) {
+      return {
+        count: 0,
+        lastImpression: 0,
+        impressions: [],
+        per,
+      };
+    }
+
+    try {
+      return JSON.parse(raw) as ImpressionData;
+    } catch {
+      return {
+        count: 0,
+        lastImpression: 0,
+        impressions: [],
+        per,
+      };
+    }
+  };
+
+  // Helper to save impression data
+  const saveImpressionData = (experienceId: string, data: ImpressionData): void => {
+    const per = data.per || 'session'; // Default to session if not specified
+    const storage = getStorageBackend(per);
+    const key = getStorageKey(experienceId);
+    storage.setItem(key, JSON.stringify(data));
+  };
+
+  // Get time window in milliseconds
+  const getTimeWindow = (per: 'session' | 'day' | 'week'): number => {
+    switch (per) {
+      case 'session':
+        return Number.POSITIVE_INFINITY; // Session storage handles this
+      case 'day':
+        return 24 * 60 * 60 * 1000; // 24 hours
+      case 'week':
+        return 7 * 24 * 60 * 60 * 1000; // 7 days
+    }
+  };
+
+  /**
+   * Get impression count for an experience
+   */
+  const getImpressionCount = (
+    experienceId: string,
+    per: 'session' | 'day' | 'week' = 'session'
+  ): number => {
+    if (!isEnabled()) return 0;
+    const data = getImpressionData(experienceId, per);
+    return data.count;
+  };
+
+  /**
+   * Check if an experience has reached its frequency cap
+   */
+  const hasReachedCap = (
+    experienceId: string,
+    max: number,
+    per: 'session' | 'day' | 'week'
+  ): boolean => {
+    if (!isEnabled()) return false;
+
+    const data = getImpressionData(experienceId, per);
+    const timeWindow = getTimeWindow(per);
+    const now = Date.now();
+
+    // For session caps, just check total count
+    if (per === 'session') {
+      return data.count >= max;
+    }
+
+    // For time-based caps, count impressions within the window
+    const recentImpressions = data.impressions.filter((timestamp) => now - timestamp < timeWindow);
+
+    return recentImpressions.length >= max;
+  };
+
+  /**
+   * Record an impression for an experience
+   */
+  const recordImpression = (
+    experienceId: string,
+    per: 'session' | 'day' | 'week' = 'session'
+  ): void => {
+    if (!isEnabled()) return;
+
+    const data = getImpressionData(experienceId, per);
+    const now = Date.now();
+
+    // Update count and add timestamp
+    data.count += 1;
+    data.lastImpression = now;
+    data.impressions.push(now);
+    data.per = per; // Store the frequency type
+
+    // Keep only recent impressions (last 7 days)
+    const sevenDaysAgo = now - 7 * 24 * 60 * 60 * 1000;
+    data.impressions = data.impressions.filter((ts) => ts > sevenDaysAgo);
+
+    // Save updated data
+    saveImpressionData(experienceId, data);
+
+    // Emit event
+    instance.emit('experiences:impression-recorded', {
+      experienceId,
+      count: data.count,
+      timestamp: now,
+    });
+  };
+
+  // Expose frequency API
+  plugin.expose({
+    frequency: {
+      getImpressionCount,
+      hasReachedCap,
+      recordImpression,
+      // Internal method to register experience frequency config
+      _registerExperience: (experienceId: string, per: 'session' | 'day' | 'week') => {
+        experienceFrequencyMap.set(experienceId, per);
+      },
+    },
+  });
+
+  // Listen to evaluation events and record impressions
+  if (isEnabled()) {
+    instance.on('experiences:evaluated', (payload: unknown) => {
+      // Handle both single decision and array of decisions
+      // evaluate() emits: { decision, experience }
+      // evaluateAll() emits: [{ decision, experience }, ...]
+      const items = Array.isArray(payload) ? payload : [payload];
+
+      for (const item of items) {
+        // Item is { decision, experience }
+        const decision = (item as { decision?: Decision }).decision;
+
+        // Only record if experience was shown
+        if (decision?.show && decision.experienceId) {
+          // Try to get the 'per' value from our map, fall back to checking the input in trace
+          let per: 'session' | 'day' | 'week' =
+            experienceFrequencyMap.get(decision.experienceId) || 'session';
+
+          // If not in map, try to infer from the decision trace
+          if (!experienceFrequencyMap.has(decision.experienceId)) {
+            const freqStep = decision.trace.find(
+              (t: TraceStep) => t.step === 'check-frequency-cap'
+            );
+            if (freqStep?.input && typeof freqStep.input === 'object' && 'per' in freqStep.input) {
+              per = (freqStep.input as { per: 'session' | 'day' | 'week' }).per;
+              // Cache it for next time
+              experienceFrequencyMap.set(decision.experienceId, per);
+            }
+          }
+
+          recordImpression(decision.experienceId, per);
+        }
+      }
+    });
+  }
+};

package/src/frequency/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Frequency Capping Plugin - Barrel Export
+ */
+
+export type { FrequencyPlugin, FrequencyPluginConfig } from './frequency';
+export { frequencyPlugin } from './frequency';

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Experience SDK Plugins
+ *
+ * Official plugins for Experience SDK
+ */
+
+export * from './banner';
+
+// Export plugins
+export * from './debug';
+export * from './frequency';
+// Export shared types
+export type {
+  BannerContent,
+  Decision,
+  DecisionMetadata,
+  Experience,
+  ExperienceContent,
+  ModalContent,
+  TooltipContent,
+  TraceStep,
+} from './types';