feat: add debug plugin

- Emit structured debug events to window
- Optional console logging
- Respects debug.enabled config
- Listens to experiences:* events
- Exposes debug.log() and debug.isEnabled()

Closes #4

Author: prosdev

packages/plugins/src/debug/debug.ts

@@ -0,0 +1,117 @@
+/**
+ * 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', () => {
+      log('SDK initialized and ready');
+    });
+
+    instance.on('experiences:registered', (payload) => {
+      log('Experience registered', payload);
+    });
+
+    instance.on('experiences:evaluated', (payload) => {
+      log('Experience evaluated', payload);
+    });
+
+    // Listen to all events using wildcard
+    instance.on('*', (eventName, ...args) => {
+      // Skip if already logged above
+      if (
+        eventName === 'experiences:ready' ||
+        eventName === 'experiences:registered' ||
+        eventName === 'experiences:evaluated'
+      ) {
+        return;
+      }
+      log(`Event: ${eventName}`, args);
+    });
+  }
+};
+

packages/plugins/src/debug/index.ts

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

packages/plugins/src/index.ts

@@ -1,4 +1,7 @@
-// Placeholder for plugins package
-// Will be implemented in Phase 0
+/**
+ * Experience SDK Plugins
+ *
+ * Official plugins for Experience SDK
+ */
 
-export {};
+export * from './debug';