@buoy-gg/impersonate 1.0.3-beta.0

package/lib/module/impersonate/utils/impersonateStore.js

@@ -0,0 +1,604 @@
+"use strict";
+
+/**
+ * Impersonate Store - State Management with Persistence
+ *
+ * Singleton store for managing impersonation state. Uses a subscription
+ * pattern compatible with React's useSyncExternalStore.
+ */
+
+import { impersonateListener, setImpersonateConfig } from "./impersonateListener";
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const STORAGE_KEY = "@buoy/impersonate/state";
+const MAX_HISTORY = 10;
+const DEFAULT_DATA_NUKE_SETTINGS = {
+  reactQuery: true,
+  redux: true,
+  asyncStorage: false,
+  // Dangerous - default off
+  mmkv: false // Dangerous - default off
+};
+const DEFAULT_STATE = {
+  isActive: false,
+  isPaused: false,
+  currentUser: null,
+  headerKey: "x-impersonate-user-id",
+  ignorePatterns: [],
+  dataNukeSettings: DEFAULT_DATA_NUKE_SETTINGS,
+  showBanner: true,
+  history: []
+};
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+// Guard to prevent double-execution of data nuking
+let isNuking = false;
+
+// =============================================================================
+// SIMPLE STORAGE ABSTRACTION
+// =============================================================================
+
+// Use a simple localStorage-like interface for persistence
+// This works on both web and native (via polyfills)
+const storage = {
+  getItem: key => {
+    try {
+      if (typeof localStorage !== "undefined") {
+        return localStorage.getItem(key);
+      }
+      // React Native: use AsyncStorage if available
+      // For now, return null (state won't persist until async storage is loaded)
+      return null;
+    } catch {
+      return null;
+    }
+  },
+  setItem: (key, value) => {
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(key, value);
+      }
+      // React Native: handled separately via async methods
+    } catch {
+      // Ignore storage errors
+    }
+  },
+  removeItem: key => {
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.removeItem(key);
+      }
+    } catch {
+      // Ignore
+    }
+  }
+};
+
+// =============================================================================
+// STORE CLASS
+// =============================================================================
+
+/**
+ * Singleton store for impersonation state
+ *
+ * Features:
+ * - Subscription pattern for React integration
+ * - Persistence of settings and history
+ * - Data nuking on impersonation change
+ * - Automatic sync with impersonateListener
+ */
+class ImpersonateStore {
+  state = {
+    ...DEFAULT_STATE
+  };
+  listeners = new Set();
+  nukeCallbacks = {};
+  isInitialized = false;
+  asyncStorageRef = null;
+  storageReadyPromise = null;
+  resolveStorageReady = null;
+  developerDefaults = null;
+  constructor() {
+    // Try to load persisted state synchronously
+    this.loadFromStorage();
+
+    // Check if localStorage is available (web) - if so, storage is ready
+    if (typeof localStorage !== "undefined") {
+      this.storageReadyPromise = Promise.resolve();
+    } else {
+      // React Native - wait for AsyncStorage to be set up
+      this.storageReadyPromise = new Promise(resolve => {
+        this.resolveStorageReady = resolve;
+      });
+    }
+  }
+
+  // ===========================================================================
+  // INITIALIZATION
+  // ===========================================================================
+
+  /**
+   * Load persisted state from storage (sync)
+   */
+  loadFromStorage() {
+    try {
+      const stored = storage.getItem(STORAGE_KEY);
+      const effectiveDefaults = this.getEffectiveDefaults();
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        this.state = {
+          ...DEFAULT_STATE,
+          // Use effective defaults (developer > hardcoded) as fallback
+          headerKey: parsed.headerKey ?? effectiveDefaults.headerKey,
+          ignorePatterns: parsed.ignorePatterns ?? DEFAULT_STATE.ignorePatterns,
+          dataNukeSettings: {
+            ...effectiveDefaults.dataNukeSettings,
+            ...parsed.dataNukeSettings
+          },
+          showBanner: parsed.showBanner ?? effectiveDefaults.showBanner,
+          history: parsed.history ?? [],
+          // Restore active session for persistence across reloads
+          isActive: parsed.isActive ?? false,
+          isPaused: parsed.isPaused ?? false,
+          currentUser: parsed.currentUser ?? null
+        };
+
+        // If we restored an active session, sync with listener
+        if (this.state.isActive && this.state.currentUser) {
+          this.syncWithListener();
+        }
+      } else {
+        // No persisted state - use effective defaults
+        this.state = {
+          ...DEFAULT_STATE,
+          headerKey: effectiveDefaults.headerKey,
+          dataNukeSettings: effectiveDefaults.dataNukeSettings,
+          showBanner: effectiveDefaults.showBanner
+        };
+      }
+      this.isInitialized = true;
+    } catch {
+      this.isInitialized = true;
+    }
+  }
+
+  /**
+   * Set async storage reference for persistence (call before initializeAsync)
+   * This ensures all writes use AsyncStorage even before load completes
+   */
+  setAsyncStorage(asyncStorage) {
+    this.asyncStorageRef = asyncStorage;
+    // Resolve the storage ready promise so persist() can proceed
+    if (this.resolveStorageReady) {
+      this.resolveStorageReady();
+      this.resolveStorageReady = null;
+    }
+  }
+
+  /**
+   * Set developer-provided defaults
+   * These override hardcoded defaults but are overridden by persisted values
+   * Call this before the component mounts (in createImpersonateTool)
+   */
+  setDeveloperDefaults(defaults) {
+    this.developerDefaults = defaults;
+
+    // Apply defaults to current state if not already initialized from storage
+    // Priority: persisted > developer defaults > hardcoded defaults
+    const effectiveDefaults = this.getEffectiveDefaults();
+
+    // Only apply if we haven't loaded persisted values yet
+    if (!this.isInitialized) {
+      this.state = {
+        ...this.state,
+        headerKey: effectiveDefaults.headerKey,
+        dataNukeSettings: effectiveDefaults.dataNukeSettings,
+        showBanner: effectiveDefaults.showBanner
+      };
+    }
+  }
+
+  /**
+   * Get effective defaults (developer defaults merged with hardcoded defaults)
+   */
+  getEffectiveDefaults() {
+    return {
+      headerKey: this.developerDefaults?.headerKey ?? DEFAULT_STATE.headerKey,
+      dataNukeSettings: {
+        ...DEFAULT_DATA_NUKE_SETTINGS,
+        ...this.developerDefaults?.dataNukeSettings
+      },
+      showBanner: this.developerDefaults?.showBanner ?? DEFAULT_STATE.showBanner
+    };
+  }
+
+  /**
+   * Get developer defaults (for use in UI to show what the "default" values are)
+   */
+  getDeveloperDefaults() {
+    return this.developerDefaults;
+  }
+
+  /**
+   * Initialize with async storage (for React Native)
+   * Call this in useEffect to load from AsyncStorage
+   */
+  async initializeAsync(asyncStorage) {
+    if (!asyncStorage) return;
+
+    // Store reference for future persistence (in case not already set)
+    this.asyncStorageRef = asyncStorage;
+    try {
+      const stored = await asyncStorage.getItem(STORAGE_KEY);
+      console.log("[ImpersonateStore] initializeAsync - stored:", stored);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        console.log("[ImpersonateStore] initializeAsync - parsed dataNukeSettings:", parsed.dataNukeSettings);
+        this.state = {
+          ...this.state,
+          headerKey: parsed.headerKey ?? this.state.headerKey,
+          ignorePatterns: parsed.ignorePatterns ?? this.state.ignorePatterns,
+          dataNukeSettings: {
+            ...this.state.dataNukeSettings,
+            ...parsed.dataNukeSettings
+          },
+          showBanner: parsed.showBanner ?? this.state.showBanner,
+          history: parsed.history ?? this.state.history,
+          // Restore active session
+          isActive: parsed.isActive ?? this.state.isActive,
+          isPaused: parsed.isPaused ?? this.state.isPaused,
+          currentUser: parsed.currentUser ?? this.state.currentUser
+        };
+        console.log("[ImpersonateStore] initializeAsync - new dataNukeSettings:", this.state.dataNukeSettings);
+
+        // If we restored an active session, sync with listener
+        if (this.state.isActive && this.state.currentUser) {
+          this.syncWithListener();
+        }
+        this.notify();
+      }
+    } catch (e) {
+      console.log("[ImpersonateStore] initializeAsync error:", e);
+    }
+  }
+
+  /**
+   * Register callbacks for data nuking
+   */
+  registerNukeCallbacks(callbacks) {
+    this.nukeCallbacks = {
+      ...this.nukeCallbacks,
+      ...callbacks
+    };
+  }
+
+  // ===========================================================================
+  // STATE ACCESS
+  // ===========================================================================
+
+  /**
+   * Get current state (creates a copy)
+   */
+  getState() {
+    return {
+      ...this.state
+    };
+  }
+
+  /**
+   * Get snapshot for useSyncExternalStore
+   * Returns the same reference if state hasn't changed
+   */
+  getSnapshot = () => {
+    return this.state;
+  };
+
+  /**
+   * Subscribe to state changes
+   * Returns unsubscribe function
+   */
+  subscribe = listener => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  // ===========================================================================
+  // IMPERSONATION ACTIONS
+  // ===========================================================================
+
+  /**
+   * Start impersonating a user
+   *
+   * This will:
+   * 1. Execute data nuking based on settings
+   * 2. Update state with new user
+   * 3. Add to history
+   * 4. Sync with impersonateListener
+   * 5. Persist settings
+   */
+  async startImpersonation(user) {
+    // Execute data nuking BEFORE switching
+    await this.executeDataNuke();
+
+    // Create history entry with timestamp
+    const historyEntry = {
+      user,
+      lastUsedAt: new Date().toISOString()
+    };
+
+    // Update history (remove duplicate, add to front)
+    const newHistory = [historyEntry, ...this.state.history.filter(entry => entry.user.id !== user.id)].slice(0, MAX_HISTORY);
+
+    // Update state
+    this.state = {
+      ...this.state,
+      isActive: true,
+      currentUser: user,
+      history: newHistory
+    };
+
+    // Sync with listener
+    this.syncWithListener();
+
+    // Persist
+    await this.persist();
+
+    // Notify subscribers
+    this.notify();
+  }
+
+  /**
+   * Stop impersonating
+   *
+   * This will:
+   * 1. Execute data nuking based on settings
+   * 2. Clear impersonation state
+   * 3. Sync with impersonateListener
+   */
+  async stopImpersonation() {
+    // Execute data nuking
+    await this.executeDataNuke();
+
+    // Update state
+    this.state = {
+      ...this.state,
+      isActive: false,
+      isPaused: false,
+      currentUser: null
+    };
+
+    // Sync with listener
+    this.syncWithListener();
+
+    // Persist
+    await this.persist();
+
+    // Notify
+    this.notify();
+  }
+
+  /**
+   * Pause impersonation (temporarily stop injecting headers)
+   */
+  async pauseImpersonation() {
+    if (!this.state.isActive || this.state.isPaused) return;
+    this.state = {
+      ...this.state,
+      isPaused: true
+    };
+
+    // Sync with listener (will stop injecting headers)
+    this.syncWithListener();
+
+    // Persist
+    await this.persist();
+
+    // Notify
+    this.notify();
+  }
+
+  /**
+   * Resume impersonation (start injecting headers again)
+   */
+  async resumeImpersonation() {
+    if (!this.state.isActive || !this.state.isPaused) return;
+    this.state = {
+      ...this.state,
+      isPaused: false
+    };
+
+    // Sync with listener (will resume injecting headers)
+    this.syncWithListener();
+
+    // Persist
+    await this.persist();
+
+    // Notify
+    this.notify();
+  }
+
+  /**
+   * Quick switch to a user from history
+   */
+  async quickSwitch(user) {
+    return this.startImpersonation(user);
+  }
+
+  // ===========================================================================
+  // SETTINGS
+  // ===========================================================================
+
+  /**
+   * Update settings (header key, ignore patterns, data nuke settings, show banner)
+   */
+  async updateSettings(settings) {
+    console.log("[ImpersonateStore] updateSettings called with:", settings);
+    console.log("[ImpersonateStore] Current dataNukeSettings:", this.state.dataNukeSettings);
+    this.state = {
+      ...this.state,
+      headerKey: settings.headerKey ?? this.state.headerKey,
+      ignorePatterns: settings.ignorePatterns ?? this.state.ignorePatterns,
+      showBanner: settings.showBanner ?? this.state.showBanner,
+      dataNukeSettings: settings.dataNukeSettings ? {
+        ...this.state.dataNukeSettings,
+        ...settings.dataNukeSettings
+      } : this.state.dataNukeSettings
+    };
+    console.log("[ImpersonateStore] New dataNukeSettings:", this.state.dataNukeSettings);
+
+    // Sync header key with listener
+    if (settings.headerKey || settings.ignorePatterns) {
+      this.syncWithListener();
+    }
+    await this.persist();
+    this.notify();
+  }
+
+  // ===========================================================================
+  // HISTORY
+  // ===========================================================================
+
+  /**
+   * Remove a user from history
+   */
+  async removeFromHistory(userId) {
+    this.state = {
+      ...this.state,
+      history: this.state.history.filter(entry => entry.user.id !== userId)
+    };
+    await this.persist();
+    this.notify();
+  }
+
+  /**
+   * Clear all history
+   */
+  async clearHistory() {
+    this.state = {
+      ...this.state,
+      history: []
+    };
+    await this.persist();
+    this.notify();
+  }
+
+  // ===========================================================================
+  // PRIVATE METHODS
+  // ===========================================================================
+
+  /**
+   * Execute data nuking based on current settings
+   */
+  async executeDataNuke() {
+    // Guard against double-execution (can happen with React Strict Mode)
+    if (isNuking) {
+      return;
+    }
+    isNuking = true;
+    try {
+      const {
+        dataNukeSettings
+      } = this.state;
+      const promises = [];
+      if (dataNukeSettings.reactQuery && this.nukeCallbacks.reactQuery) {
+        promises.push(Promise.resolve(this.nukeCallbacks.reactQuery()));
+      }
+      if (dataNukeSettings.redux && this.nukeCallbacks.redux) {
+        promises.push(Promise.resolve(this.nukeCallbacks.redux()));
+      }
+      if (dataNukeSettings.asyncStorage && this.nukeCallbacks.asyncStorage) {
+        promises.push(Promise.resolve(this.nukeCallbacks.asyncStorage()));
+      }
+      if (dataNukeSettings.mmkv && this.nukeCallbacks.mmkv) {
+        promises.push(Promise.resolve(this.nukeCallbacks.mmkv()));
+      }
+
+      // Wait for all, but don't fail if some error
+      await Promise.allSettled(promises);
+    } finally {
+      // Reset flag after a short delay to allow next legitimate call
+      setTimeout(() => {
+        isNuking = false;
+      }, 100);
+    }
+  }
+
+  /**
+   * Sync current state with the impersonateListener
+   */
+  syncWithListener() {
+    // When paused, don't inject headers (pass null userId)
+    const shouldInject = this.state.isActive && !this.state.isPaused;
+    setImpersonateConfig({
+      headerKey: this.state.headerKey,
+      userId: shouldInject ? this.state.currentUser?.id ?? null : null,
+      ignorePatterns: this.state.ignorePatterns.map(p => new RegExp(p))
+    });
+
+    // Ensure listener is started
+    if (!impersonateListener().isListening) {
+      impersonateListener().startListening();
+    }
+  }
+
+  /**
+   * Persist state to storage
+   */
+  async persist() {
+    // Wait for storage to be ready (AsyncStorage setup on React Native)
+    if (this.storageReadyPromise) {
+      await this.storageReadyPromise;
+    }
+    const toStore = {
+      headerKey: this.state.headerKey,
+      ignorePatterns: this.state.ignorePatterns,
+      dataNukeSettings: this.state.dataNukeSettings,
+      showBanner: this.state.showBanner,
+      history: this.state.history,
+      // Persist active session for continuity across reloads
+      isActive: this.state.isActive,
+      isPaused: this.state.isPaused,
+      currentUser: this.state.currentUser
+    };
+    const serialized = JSON.stringify(toStore);
+    console.log("[ImpersonateStore] Persisting dataNukeSettings:", this.state.dataNukeSettings);
+    try {
+      // Prefer AsyncStorage for React Native
+      if (this.asyncStorageRef) {
+        await this.asyncStorageRef.setItem(STORAGE_KEY, serialized);
+        console.log("[ImpersonateStore] Persisted to AsyncStorage");
+      } else {
+        // Fall back to localStorage (web)
+        storage.setItem(STORAGE_KEY, serialized);
+        console.log("[ImpersonateStore] Persisted to localStorage");
+      }
+    } catch (e) {
+      console.log("[ImpersonateStore] Persist error:", e);
+    }
+  }
+
+  /**
+   * Notify all listeners of state change
+   */
+  notify() {
+    this.listeners.forEach(listener => {
+      try {
+        listener(this.state);
+      } catch {
+        // Ignore listener errors
+      }
+    });
+  }
+}
+
+// =============================================================================
+// SINGLETON EXPORT
+// =============================================================================
+
+export const impersonateStore = new ImpersonateStore();

package/lib/module/impersonate/utils/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { impersonateListener, startImpersonateListener, stopImpersonateListener, setImpersonateConfig, isImpersonating, getImpersonatedUserId } from "./impersonateListener";
+export { impersonateStore } from "./impersonateStore";

package/lib/module/index.js

@@ -0,0 +1,103 @@
+"use strict";
+
+/**
+ * @buoy-gg/impersonate
+ *
+ * User impersonation tool for React Native DevTools.
+ * Injects custom headers into fetch/XHR requests when impersonating.
+ *
+ * @example
+ * ```tsx
+ * import { createImpersonateTool } from '@buoy-gg/impersonate';
+ *
+ * const impersonateTool = createImpersonateTool({
+ *   onSearchUsers: async (query) => {
+ *     const res = await api.searchUsers(query);
+ *     return res.users;
+ *   },
+ *   onClearReactQuery: () => queryClient.clear(),
+ * });
+ *
+ * <FloatingDevTools apps={[impersonateTool]} />
+ * ```
+ */
+
+// =============================================================================
+// FACTORY (Primary entry point)
+// =============================================================================
+
+export { createImpersonateTool } from "./preset";
+
+// =============================================================================
+// COMPONENTS (For custom UI implementations)
+// =============================================================================
+
+export { ImpersonateModal } from "./impersonate/components/ImpersonateModal";
+export { ImpersonateBanner, ImpersonateBannerMinimal } from "./impersonate/components/ImpersonateBanner";
+export { UserSearchView } from "./impersonate/components/UserSearchView";
+export { DataNukeSettings as DataNukeSettingsComponent } from "./impersonate/components/DataNukeSettings";
+export { ImpersonateHistoryList } from "./impersonate/components/ImpersonateHistoryList";
+export { ImpersonateStatusBar } from "./impersonate/components/ImpersonateStatusBar";
+
+// =============================================================================
+// HOOKS (For consuming impersonation state in custom components)
+// =============================================================================
+
+export { useImpersonate } from "./impersonate/hooks/useImpersonate";
+export { useImpersonateHistory } from "./impersonate/hooks/useImpersonateHistory";
+
+// =============================================================================
+// TYPES (For TypeScript users)
+// =============================================================================
+
+// =============================================================================
+// LOW-LEVEL EXPORTS (For advanced use cases)
+// =============================================================================
+
+/**
+ * Direct access to the impersonation store singleton.
+ * Use this for custom integrations or debugging.
+ *
+ * @example
+ * ```typescript
+ * import { impersonateStore } from '@buoy-gg/impersonate';
+ *
+ * // Check if impersonating
+ * const state = impersonateStore.getState();
+ * if (state.isActive) {
+ *   console.log('Impersonating:', state.currentUser?.email);
+ * }
+ *
+ * // Subscribe to changes
+ * const unsubscribe = impersonateStore.subscribe((state) => {
+ *   console.log('Impersonation state changed:', state);
+ * });
+ * ```
+ */
+export { impersonateStore } from "./impersonate/utils/impersonateStore";
+
+/**
+ * Direct access to the impersonate listener for advanced control.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   impersonateListener,
+ *   startImpersonateListener,
+ *   setImpersonateConfig,
+ * } from '@buoy-gg/impersonate';
+ *
+ * // Manually start the listener
+ * startImpersonateListener();
+ *
+ * // Configure impersonation
+ * setImpersonateConfig({
+ *   headerKey: 'x-custom-impersonate-header',
+ *   userId: 'user_123',
+ * });
+ *
+ * // Check status
+ * console.log('Listener active:', impersonateListener().isListening);
+ * ```
+ */
+export { impersonateListener, startImpersonateListener, stopImpersonateListener, setImpersonateConfig, isImpersonating, getImpersonatedUserId } from "./impersonate/utils/impersonateListener";