@prosdevlab/experience-sdk-plugins 0.1.0

package/src/banner/banner.ts

@@ -0,0 +1,369 @@
+/**
+ * Banner Plugin
+ *
+ * Renders banner experiences at the top or bottom of the page.
+ * Auto-shows banners when experiences are evaluated.
+ */
+
+import type { PluginFunction } from '@lytics/sdk-kit';
+import type { BannerContent, Decision, Experience } from '../types';
+
+export interface BannerPluginConfig {
+  banner?: {
+    position?: 'top' | 'bottom';
+    dismissable?: boolean;
+    zIndex?: number;
+  };
+}
+
+export interface BannerPlugin {
+  show(experience: Experience): void;
+  remove(): void;
+  isShowing(): boolean;
+}
+
+/**
+ * Banner Plugin
+ *
+ * Automatically renders banner experiences when they are evaluated.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * const sdk = createInstance({ banner: { position: 'top', dismissable: true } });
+ * sdk.use(bannerPlugin);
+ * ```
+ */
+export const bannerPlugin: PluginFunction = (plugin, instance, config) => {
+  plugin.ns('banner');
+
+  // Set defaults
+  plugin.defaults({
+    banner: {
+      position: 'top',
+      dismissable: true,
+      zIndex: 10000,
+    },
+  });
+
+  // Track multiple active banners by experience ID
+  const activeBanners = new Map<string, HTMLElement>();
+
+  /**
+   * Create banner DOM element
+   */
+  function createBannerElement(experience: Experience): HTMLElement {
+    const content = experience.content as BannerContent;
+    // Allow per-experience position override, fall back to global config
+    const position = content.position ?? config.get('banner.position') ?? 'top';
+    const dismissable = content.dismissable ?? config.get('banner.dismissable') ?? true;
+    const zIndex = config.get('banner.zIndex') ?? 10000;
+
+    // Detect dark mode
+    const isDarkMode = document.documentElement.classList.contains('dark');
+
+    // Theme-aware colors - professional subtle style
+    const bgColor = isDarkMode ? '#1f2937' : '#f9fafb';
+    const textColor = isDarkMode ? '#f3f4f6' : '#111827';
+    const borderColor = isDarkMode ? '#374151' : '#e5e7eb';
+    const shadowColor = isDarkMode ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.05)';
+
+    // Create banner container
+    const banner = document.createElement('div');
+    banner.setAttribute('data-experience-id', experience.id);
+
+    // Add responsive media query styles
+    const styleId = `banner-responsive-${experience.id}`;
+    if (!document.getElementById(styleId)) {
+      const style = document.createElement('style');
+      style.id = styleId;
+      style.textContent = `
+        @media (max-width: 640px) {
+          [data-experience-id="${experience.id}"] {
+            flex-direction: column !important;
+            align-items: flex-start !important;
+          }
+          [data-experience-id="${experience.id}"] > div:last-child {
+            width: 100%;
+            flex-direction: column !important;
+          }
+          [data-experience-id="${experience.id}"] button {
+            width: 100%;
+          }
+        }
+      `;
+      document.head.appendChild(style);
+    }
+
+    banner.style.cssText = `
+      position: fixed;
+      ${position}: 0;
+      left: 0;
+      right: 0;
+      background: ${bgColor};
+      color: ${textColor};
+      padding: 16px 20px;
+      border-${position === 'top' ? 'bottom' : 'top'}: 1px solid ${borderColor};
+      box-shadow: 0 ${position === 'top' ? '1' : '-1'}px 3px 0 ${shadowColor};
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      font-size: 14px;
+      line-height: 1.5;
+      z-index: ${zIndex};
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      box-sizing: border-box;
+    `;
+
+    // Create content container
+    const contentDiv = document.createElement('div');
+    contentDiv.style.cssText = 'flex: 1; margin-right: 20px;';
+
+    // Add title if present
+    if (content.title) {
+      const title = document.createElement('div');
+      title.textContent = content.title;
+      title.style.cssText = 'font-weight: 600; margin-bottom: 4px;';
+      contentDiv.appendChild(title);
+    }
+
+    // Add message
+    const message = document.createElement('div');
+    message.textContent = content.message;
+    contentDiv.appendChild(message);
+
+    banner.appendChild(contentDiv);
+
+    // Create button container for actions and/or dismiss
+    const buttonContainer = document.createElement('div');
+    buttonContainer.style.cssText = `
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      flex-wrap: wrap;
+    `;
+
+    // Helper function to create button with variant styling
+    function createButton(buttonConfig: {
+      text: string;
+      action?: string;
+      url?: string;
+      variant?: 'primary' | 'secondary' | 'link';
+      metadata?: Record<string, unknown>;
+    }): HTMLButtonElement {
+      const button = document.createElement('button');
+      button.textContent = buttonConfig.text;
+
+      const variant = buttonConfig.variant || 'primary';
+
+      // Variant-based styling
+      let bg: string, hoverBg: string, textColor: string, border: string;
+
+      if (variant === 'primary') {
+        bg = isDarkMode ? '#3b82f6' : '#2563eb';
+        hoverBg = isDarkMode ? '#2563eb' : '#1d4ed8';
+        textColor = '#ffffff';
+        border = 'none';
+      } else if (variant === 'secondary') {
+        bg = isDarkMode ? '#374151' : '#ffffff';
+        hoverBg = isDarkMode ? '#4b5563' : '#f9fafb';
+        textColor = isDarkMode ? '#f3f4f6' : '#374151';
+        border = isDarkMode ? '1px solid #4b5563' : '1px solid #d1d5db';
+      } else {
+        // 'link'
+        bg = 'transparent';
+        hoverBg = isDarkMode ? 'rgba(255, 255, 255, 0.1)' : 'rgba(0, 0, 0, 0.05)';
+        textColor = isDarkMode ? '#93c5fd' : '#2563eb';
+        border = 'none';
+      }
+
+      button.style.cssText = `
+        background: ${bg};
+        border: ${border};
+        color: ${textColor};
+        padding: ${variant === 'link' ? '4px 8px' : '8px 16px'};
+        font-size: 14px;
+        font-weight: ${variant === 'link' ? '400' : '500'};
+        border-radius: 6px;
+        cursor: pointer;
+        transition: all 0.2s;
+        text-decoration: ${variant === 'link' ? 'underline' : 'none'};
+      `;
+
+      button.addEventListener('mouseenter', () => {
+        button.style.background = hoverBg;
+      });
+
+      button.addEventListener('mouseleave', () => {
+        button.style.background = bg;
+      });
+
+      button.addEventListener('click', () => {
+        // Emit action event
+        instance.emit('experiences:action', {
+          experienceId: experience.id,
+          type: 'banner',
+          action: buttonConfig.action,
+          url: buttonConfig.url,
+          metadata: buttonConfig.metadata,
+          variant: variant,
+          timestamp: Date.now(),
+        });
+
+        // Navigate if URL provided
+        if (buttonConfig.url) {
+          window.location.href = buttonConfig.url;
+        }
+      });
+
+      return button;
+    }
+
+    // Add buttons from buttons array
+    if (content.buttons && content.buttons.length > 0) {
+      content.buttons.forEach((buttonConfig) => {
+        const button = createButton(buttonConfig);
+        buttonContainer.appendChild(button);
+      });
+    }
+
+    // Add dismiss button if dismissable
+    if (dismissable) {
+      const closeButton = document.createElement('button');
+      closeButton.innerHTML = '&times;';
+      closeButton.setAttribute('aria-label', 'Close banner');
+
+      const closeColor = isDarkMode ? '#9ca3af' : '#6b7280';
+
+      closeButton.style.cssText = `
+        background: transparent;
+        border: none;
+        color: ${closeColor};
+        font-size: 24px;
+        line-height: 1;
+        cursor: pointer;
+        padding: 0;
+        margin: 0;
+        opacity: 0.7;
+        transition: opacity 0.2s;
+      `;
+
+      closeButton.addEventListener('mouseenter', () => {
+        closeButton.style.opacity = '1';
+      });
+
+      closeButton.addEventListener('mouseleave', () => {
+        closeButton.style.opacity = '0.7';
+      });
+
+      closeButton.addEventListener('click', () => {
+        remove(experience.id);
+        instance.emit('experiences:dismissed', {
+          experienceId: experience.id,
+          type: 'banner',
+        });
+      });
+
+      buttonContainer.appendChild(closeButton);
+    }
+
+    banner.appendChild(buttonContainer);
+
+    return banner;
+  }
+
+  /**
+   * Show a banner experience
+   */
+  function show(experience: Experience): void {
+    // If banner already showing for this experience, skip
+    if (activeBanners.has(experience.id)) {
+      return;
+    }
+
+    // Only show if we're in a browser environment
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const banner = createBannerElement(experience);
+    document.body.appendChild(banner);
+    activeBanners.set(experience.id, banner);
+
+    instance.emit('experiences:shown', {
+      experienceId: experience.id,
+      type: 'banner',
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Remove a banner by experience ID (or all if no ID provided)
+   */
+  function remove(experienceId?: string): void {
+    if (experienceId) {
+      // Remove specific banner
+      const banner = activeBanners.get(experienceId);
+      if (banner?.parentNode) {
+        banner.parentNode.removeChild(banner);
+      }
+      activeBanners.delete(experienceId);
+    } else {
+      // Remove all banners
+      for (const [id, banner] of activeBanners.entries()) {
+        if (banner?.parentNode) {
+          banner.parentNode.removeChild(banner);
+        }
+        activeBanners.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Check if any banner is currently showing
+   */
+  function isShowing(): boolean {
+    return activeBanners.size > 0;
+  }
+
+  // Expose banner API
+  plugin.expose({
+    banner: {
+      show,
+      remove,
+      isShowing,
+    },
+  });
+
+  // Auto-show banner on experiences:evaluated event
+  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 typedItem = item as { decision?: Decision; experience?: Experience };
+      const decision = typedItem.decision;
+      const experience = typedItem.experience;
+
+      // Only handle banner-type experiences
+      if (experience?.type === 'banner') {
+        if (decision?.show) {
+          show(experience);
+        } else if (experience.id && activeBanners.has(experience.id)) {
+          // Hide specific banner if decision says don't show
+          remove(experience.id);
+        }
+      }
+    }
+  });
+
+  // Cleanup on destroy
+  instance.on('sdk:destroy', () => {
+    remove();
+  });
+};

package/src/banner/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Banner Plugin - Barrel Export
+ */
+
+export type { BannerPlugin, BannerPluginConfig } from './banner';
+export { bannerPlugin } from './banner';

package/src/debug/debug.test.ts

@@ -0,0 +1,230 @@
+import { SDK } from '@lytics/sdk-kit';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { type DebugPlugin, debugPlugin } from './debug';
+
+describe('Debug Plugin', () => {
+  let sdk: SDK & { debug: DebugPlugin };
+
+  beforeEach(() => {
+    sdk = new SDK({ debug: { enabled: true, console: true, window: true } }) as SDK & {
+      debug: DebugPlugin;
+    };
+  });
+
+  describe('Plugin Registration', () => {
+    it('should register without errors', () => {
+      expect(() => sdk.use(debugPlugin)).not.toThrow();
+    });
+
+    it('should expose debug API', () => {
+      sdk.use(debugPlugin);
+
+      expect(sdk.debug).toBeDefined();
+      expect(sdk.debug.log).toBeTypeOf('function');
+      expect(sdk.debug.isEnabled).toBeTypeOf('function');
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should respect debug.enabled config', () => {
+      const disabledSdk = new SDK({ debug: { enabled: false } });
+      disabledSdk.use(debugPlugin);
+
+      expect(disabledSdk.debug.isEnabled()).toBe(false);
+    });
+
+    it('should default to disabled', () => {
+      const defaultSdk = new SDK();
+      defaultSdk.use(debugPlugin);
+
+      expect(defaultSdk.debug.isEnabled()).toBe(false);
+    });
+
+    it('should respect debug.console config', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      const consoleEnabledSdk = new SDK({ debug: { enabled: true, console: true } });
+      consoleEnabledSdk.use(debugPlugin);
+      consoleEnabledSdk.debug.log('test message');
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] test message', '');
+      consoleSpy.mockRestore();
+    });
+
+    it('should not log to console when disabled', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      const consoleDisabledSdk = new SDK({ debug: { enabled: true, console: false } });
+      consoleDisabledSdk.use(debugPlugin);
+      consoleDisabledSdk.debug.log('test message');
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('Window Events', () => {
+    it('should emit window events when enabled', () => {
+      if (typeof window === 'undefined') {
+        // Skip in non-browser environment
+        return;
+      }
+
+      const eventHandler = vi.fn();
+      window.addEventListener('experience-sdk:debug', eventHandler);
+
+      sdk.use(debugPlugin);
+      sdk.debug.log('test message', { foo: 'bar' });
+
+      expect(eventHandler).toHaveBeenCalled();
+      const event = eventHandler.mock.calls[0][0] as CustomEvent;
+      expect(event.detail).toMatchObject({
+        message: 'test message',
+        data: { foo: 'bar' },
+      });
+      expect(event.detail.timestamp).toBeDefined();
+
+      window.removeEventListener('experience-sdk:debug', eventHandler);
+    });
+
+    it('should not emit window events when debug is disabled', () => {
+      if (typeof window === 'undefined') {
+        return;
+      }
+
+      const eventHandler = vi.fn();
+      window.addEventListener('experience-sdk:debug', eventHandler);
+
+      const disabledSdk = new SDK({ debug: { enabled: false } });
+      disabledSdk.use(debugPlugin);
+      disabledSdk.debug.log('test message');
+
+      expect(eventHandler).not.toHaveBeenCalled();
+
+      window.removeEventListener('experience-sdk:debug', eventHandler);
+    });
+
+    it('should not emit window events when window is disabled', () => {
+      if (typeof window === 'undefined') {
+        return;
+      }
+
+      const eventHandler = vi.fn();
+      window.addEventListener('experience-sdk:debug', eventHandler);
+
+      const windowDisabledSdk = new SDK({ debug: { enabled: true, window: false } });
+      windowDisabledSdk.use(debugPlugin);
+      windowDisabledSdk.debug.log('test message');
+
+      expect(eventHandler).not.toHaveBeenCalled();
+
+      window.removeEventListener('experience-sdk:debug', eventHandler);
+    });
+  });
+
+  describe('Event Listening', () => {
+    it('should listen to experiences:ready event', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      sdk.use(debugPlugin);
+      sdk.emit('experiences:ready');
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] SDK initialized and ready', '');
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should listen to experiences:registered event', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      sdk.use(debugPlugin);
+      const payload = { id: 'test', experience: { type: 'banner' } };
+      sdk.emit('experiences:registered', payload);
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] Experience registered', payload);
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should listen to experiences:evaluated event', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      sdk.use(debugPlugin);
+      const decision = { show: true, experienceId: 'test' };
+      sdk.emit('experiences:evaluated', decision);
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] Experience evaluated', decision);
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should not log when debug is disabled', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      const disabledSdk = new SDK({ debug: { enabled: false } });
+      disabledSdk.use(debugPlugin);
+      disabledSdk.emit('experiences:ready');
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('debug.log() method', () => {
+    it('should log message without data', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      sdk.use(debugPlugin);
+      sdk.debug.log('test message');
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] test message', '');
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should log message with data', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      sdk.use(debugPlugin);
+      const data = { foo: 'bar', count: 42 };
+      sdk.debug.log('test message', data);
+
+      expect(consoleSpy).toHaveBeenCalledWith('[experiences] test message', data);
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should include timestamp in window event', () => {
+      if (typeof window === 'undefined') {
+        return;
+      }
+
+      const eventHandler = vi.fn();
+      window.addEventListener('experience-sdk:debug', eventHandler);
+
+      sdk.use(debugPlugin);
+      sdk.debug.log('test message');
+
+      const event = eventHandler.mock.calls[0][0] as CustomEvent;
+      expect(event.detail.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+
+      window.removeEventListener('experience-sdk:debug', eventHandler);
+    });
+  });
+
+  describe('debug.isEnabled() method', () => {
+    it('should return true when enabled', () => {
+      sdk.use(debugPlugin);
+
+      expect(sdk.debug.isEnabled()).toBe(true);
+    });
+
+    it('should return false when disabled', () => {
+      const disabledSdk = new SDK({ debug: { enabled: false } });
+      disabledSdk.use(debugPlugin);
+
+      expect(disabledSdk.debug.isEnabled()).toBe(false);
+    });
+  });
+});

package/src/debug/debug.ts

@@ -0,0 +1,106 @@
+/**
+ * Debug Plugin
+ *
+ * Emits structured debug events to window and optionally logs to console.
+ * Useful for debugging and Chrome extension integration.
+ */
+
+import type { PluginFunction } from '@lytics/sdk-kit';
+
+export interface DebugPluginConfig {
+  debug?: {
+    enabled?: boolean;
+    console?: boolean;
+    window?: boolean;
+  };
+}
+
+export interface DebugPlugin {
+  log(message: string, data?: unknown): void;
+  isEnabled(): boolean;
+}
+
+/**
+ * Debug Plugin
+ *
+ * Listens to all SDK events and emits them as window events for debugging.
+ * Also optionally logs to console.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { debugPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * const sdk = createInstance({ debug: { enabled: true, console: true } });
+ * sdk.use(debugPlugin);
+ * ```
+ */
+export const debugPlugin: PluginFunction = (plugin, instance, config) => {
+  plugin.ns('debug');
+
+  // Set defaults
+  plugin.defaults({
+    debug: {
+      enabled: false,
+      console: false,
+      window: true,
+    },
+  });
+
+  // Helper to check if debug is enabled
+  const isEnabled = (): boolean => config.get('debug.enabled') ?? false;
+  const shouldLogConsole = (): boolean => config.get('debug.console') ?? false;
+  const shouldEmitWindow = (): boolean => config.get('debug.window') ?? true;
+
+  // Log function
+  const log = (message: string, data?: unknown): void => {
+    if (!isEnabled()) return;
+
+    const timestamp = new Date().toISOString();
+    const logData = {
+      timestamp,
+      message,
+      data,
+    };
+
+    // Console logging
+    if (shouldLogConsole()) {
+      console.log(`[experiences] ${message}`, data || '');
+    }
+
+    // Window event emission
+    if (shouldEmitWindow() && typeof window !== 'undefined') {
+      const event = new CustomEvent('experience-sdk:debug', {
+        detail: logData,
+      });
+      window.dispatchEvent(event);
+    }
+  };
+
+  // Expose debug API
+  plugin.expose({
+    debug: {
+      log,
+      isEnabled,
+    },
+  });
+
+  // If debug is enabled, listen to all events
+  if (isEnabled()) {
+    // Listen to experiences:* events
+    instance.on('experiences:ready', () => {
+      if (!isEnabled()) return;
+      log('SDK initialized and ready');
+    });
+
+    instance.on('experiences:registered', (payload) => {
+      if (!isEnabled()) return;
+      log('Experience registered', payload);
+    });
+
+    instance.on('experiences:evaluated', (payload) => {
+      if (!isEnabled()) return;
+      log('Experience evaluated', payload);
+    });
+  }
+};