@buoy-gg/impersonate 1.0.3-beta.0

package/lib/module/impersonate/hooks/useAutoClearAsyncStorage.js

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * useAutoClearAsyncStorage Hook
+ *
+ * Auto-detects AsyncStorage and provides a clear function.
+ * Follows the same pattern as useAutoClearReactQuery and useAutoClearRedux.
+ *
+ * This hook:
+ * 1. Dynamically requires @react-native-async-storage/async-storage
+ * 2. Returns a clearStorage function that removes all non-buoy keys
+ *
+ * IMPORTANT: This preserves all @buoy/* keys to avoid clearing our own state.
+ */
+
+import { useCallback, useMemo, useState, useEffect } from "react";
+
+// ============================================
+// Types
+// ============================================
+
+// Flag to prevent double-firing (synchronous check)
+let isClearing = false;
+// ============================================
+// Safe Module Loading
+// ============================================
+
+/**
+ * Safely attempt to load @react-native-async-storage/async-storage
+ */
+function getAsyncStorage() {
+  try {
+    // Dynamic require to handle cases where async-storage isn't installed
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const AsyncStorage = require("@react-native-async-storage/async-storage").default;
+    return AsyncStorage;
+  } catch {
+    // @react-native-async-storage/async-storage not available
+    return null;
+  }
+}
+
+// ============================================
+// Main Hook
+// ============================================
+
+/**
+ * Hook to auto-detect AsyncStorage and provide clearing functionality.
+ *
+ * This clears all keys EXCEPT those starting with @buoy/ to preserve
+ * our own persisted state (impersonation settings, history, etc.).
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isAvailable, clearStorage } = useAutoClearAsyncStorage();
+ *
+ *   if (isAvailable && clearStorage) {
+ *     // Clear all app data except Buoy state
+ *     await clearStorage();
+ *   }
+ * }
+ * ```
+ */
+export function useAutoClearAsyncStorage() {
+  const [asyncStorage, setAsyncStorage] = useState(null);
+  const [error, setError] = useState(null);
+
+  // Check for AsyncStorage on mount
+  useEffect(() => {
+    const storage = getAsyncStorage();
+    if (storage) {
+      setAsyncStorage(storage);
+      setError(null);
+    } else {
+      setError("@react-native-async-storage/async-storage is not installed");
+    }
+  }, []);
+
+  // Create the clearStorage function with guard to prevent double-firing
+  const clearStorage = useCallback(async () => {
+    // Synchronous guard - set flag immediately before any async work
+    if (isClearing) {
+      return;
+    }
+    isClearing = true;
+    try {
+      if (asyncStorage) {
+        // Get all keys
+        const allKeys = await asyncStorage.getAllKeys();
+
+        // Filter out @buoy/* keys to preserve our own state
+        const keysToRemove = allKeys.filter(key => !key.startsWith("@buoy/") && !key.startsWith("@buoy-"));
+        if (keysToRemove.length > 0) {
+          await asyncStorage.multiRemove([...keysToRemove]);
+        }
+      }
+    } finally {
+      // Reset flag after a short delay to allow next legitimate call
+      setTimeout(() => {
+        isClearing = false;
+      }, 100);
+    }
+  }, [asyncStorage]);
+
+  // Memoize result
+  const result = useMemo(() => {
+    if (!asyncStorage || error) {
+      return {
+        isAvailable: false,
+        error: error || "@react-native-async-storage/async-storage is not available",
+        clearStorage: null
+      };
+    }
+    return {
+      isAvailable: true,
+      error: null,
+      clearStorage
+    };
+  }, [asyncStorage, error, clearStorage]);
+  return result;
+}
+
+/**
+ * Lightweight check to see if AsyncStorage is available
+ * without creating the clear function
+ */
+export function useAsyncStorageAvailability() {
+  const storage = getAsyncStorage();
+  if (!storage) {
+    return {
+      isInstalled: false,
+      error: "@react-native-async-storage/async-storage is not installed"
+    };
+  }
+  return {
+    isInstalled: true,
+    error: null
+  };
+}

package/lib/module/impersonate/hooks/useAutoClearReactQuery.js

@@ -0,0 +1,151 @@
+"use strict";
+
+/**
+ * useAutoClearReactQuery Hook
+ *
+ * Auto-detects React Query and provides a clear function.
+ * Uses the same pattern as @buoy-gg/redux's useAutoInstrumentRedux.
+ *
+ * This hook:
+ * 1. Dynamically requires @tanstack/react-query
+ * 2. Uses useQueryClient() to get the client from context
+ * 3. Returns a clearCache function that clears queries + mutations
+ */
+
+import { useCallback, useMemo } from "react";
+
+// ============================================
+// Types
+// ============================================
+
+// Flag to prevent double-firing (synchronous check)
+let isClearing = false;
+// ============================================
+// Safe Module Loading
+// ============================================
+
+/**
+ * Safely attempt to load @tanstack/react-query and get useQueryClient hook
+ */
+function getReactQueryUseQueryClient() {
+  try {
+    // Dynamic require to handle cases where react-query isn't installed
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const reactQuery = require("@tanstack/react-query");
+    return reactQuery.useQueryClient;
+  } catch {
+    // @tanstack/react-query not available
+    return null;
+  }
+}
+
+// ============================================
+// Main Hook
+// ============================================
+
+/**
+ * Hook to auto-detect React Query and provide cache clearing functionality.
+ *
+ * This mirrors how the react-query package's QueryBrowserModal.tsx clears cache:
+ * `queryClient.getQueryCache().clear()`
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isAvailable, clearCache } = useAutoClearReactQuery();
+ *
+ *   if (isAvailable && clearCache) {
+ *     // Can clear React Query cache
+ *     clearCache();
+ *   }
+ * }
+ * ```
+ */
+export function useAutoClearReactQuery() {
+  // Check if @tanstack/react-query is available
+  const useQueryClientHook = getReactQueryUseQueryClient();
+  const isReactQueryInstalled = useQueryClientHook !== null;
+
+  // Try to get the query client using react-query's useQueryClient
+  // This must be called unconditionally due to hooks rules
+  let queryClient = null;
+  let clientError = null;
+  if (useQueryClientHook) {
+    try {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      queryClient = useQueryClientHook();
+    } catch (e) {
+      // Not inside a QueryClientProvider or other error
+      clientError = e instanceof Error ? e.message : "Failed to access QueryClient. Make sure your app is wrapped in a QueryClientProvider.";
+    }
+  } else {
+    clientError = "@tanstack/react-query is not installed";
+  }
+
+  // Create the clearCache function with guard to prevent double-firing
+  const clearCache = useCallback(() => {
+    // Synchronous guard - set flag immediately before any async work
+    if (isClearing) {
+      return;
+    }
+    isClearing = true;
+    if (queryClient) {
+      // Clear both query and mutation caches
+      // This is the same approach used in @buoy-gg/react-query
+      queryClient.getQueryCache().clear();
+      queryClient.getMutationCache().clear();
+    }
+
+    // Reset flag after a short delay to allow next legitimate call
+    setTimeout(() => {
+      isClearing = false;
+    }, 100);
+  }, [queryClient]);
+
+  // Memoize result
+  const result = useMemo(() => {
+    if (!isReactQueryInstalled || clientError || !queryClient) {
+      return {
+        isAvailable: false,
+        error: clientError,
+        clearCache: null
+      };
+    }
+    return {
+      isAvailable: true,
+      error: null,
+      clearCache
+    };
+  }, [isReactQueryInstalled, clientError, queryClient, clearCache]);
+  return result;
+}
+
+/**
+ * Lightweight hook to just check if React Query is available
+ * without getting the client
+ */
+export function useReactQueryAvailability() {
+  const useQueryClientHook = getReactQueryUseQueryClient();
+  if (!useQueryClientHook) {
+    return {
+      isInstalled: false,
+      isConnected: false,
+      error: "@tanstack/react-query is not installed"
+    };
+  }
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const client = useQueryClientHook();
+    return {
+      isInstalled: true,
+      isConnected: client !== null && client !== undefined,
+      error: null
+    };
+  } catch (e) {
+    return {
+      isInstalled: true,
+      isConnected: false,
+      error: e instanceof Error ? e.message : "Not inside a QueryClientProvider"
+    };
+  }
+}

package/lib/module/impersonate/hooks/useAutoClearRedux.js

@@ -0,0 +1,183 @@
+"use strict";
+
+/**
+ * useAutoClearRedux Hook
+ *
+ * Auto-detects Redux store and provides a reset function.
+ * Uses the same pattern as @buoy-gg/redux's useAutoInstrumentRedux.
+ *
+ * This hook:
+ * 1. Dynamically requires react-redux
+ * 2. Uses useStore() to get the store from context
+ * 3. Returns a resetStore function that dispatches a reset action
+ *
+ * IMPORTANT: Unlike React Query which has a universal .clear() method,
+ * Redux reset requires the app's reducer to handle the reset action.
+ * The default action type is '@@RESET' but can be customized.
+ *
+ * Example reducer handling:
+ * ```typescript
+ * const rootReducer = (state, action) => {
+ *   if (action.type === '@@RESET') {
+ *     return undefined; // Returns to initial state
+ *   }
+ *   return appReducer(state, action);
+ * };
+ * ```
+ */
+
+import { useCallback, useMemo } from "react";
+
+// ============================================
+// Types
+// ============================================
+
+// Flag to prevent double-firing (synchronous check)
+let isDispatching = false;
+
+/** The default action type dispatched to reset Redux state */
+export const REDUX_RESET_ACTION_TYPE = "@@RESET";
+// ============================================
+// Safe Module Loading
+// ============================================
+
+/**
+ * Safely attempt to load react-redux and get useStore hook
+ */
+function getReactReduxUseStore() {
+  try {
+    // Dynamic require to handle cases where react-redux isn't installed
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const reactRedux = require("react-redux");
+    return reactRedux.useStore;
+  } catch {
+    // react-redux not available
+    return null;
+  }
+}
+
+// ============================================
+// Main Hook
+// ============================================
+
+/**
+ * Hook to auto-detect Redux store and provide state reset functionality.
+ *
+ * This dispatches a reset action (default: '@@RESET') to the store.
+ * Your app's root reducer must handle this action to actually reset state.
+ *
+ * @example
+ * ```tsx
+ * // In your component:
+ * function MyComponent() {
+ *   const { isAvailable, resetStore } = useAutoClearRedux();
+ *
+ *   if (isAvailable && resetStore) {
+ *     resetStore(); // Dispatches { type: '@@RESET' }
+ *   }
+ * }
+ *
+ * // In your root reducer:
+ * const rootReducer = (state, action) => {
+ *   if (action.type === '@@RESET') {
+ *     // Return undefined to reset to initial state
+ *     // Or return a specific "logged out" state
+ *     return undefined;
+ *   }
+ *   return appReducer(state, action);
+ * };
+ * ```
+ */
+export function useAutoClearRedux(options = {}) {
+  const {
+    resetActionType = REDUX_RESET_ACTION_TYPE
+  } = options;
+
+  // Check if react-redux is available
+  const useStoreHook = getReactReduxUseStore();
+  const isReactReduxInstalled = useStoreHook !== null;
+
+  // Try to get the store using react-redux's useStore
+  // This must be called unconditionally due to hooks rules
+  let store = null;
+  let storeError = null;
+  if (useStoreHook) {
+    try {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      store = useStoreHook();
+    } catch (e) {
+      // Not inside a Provider or other error
+      storeError = e instanceof Error ? e.message : "Failed to access Redux store. Make sure your app is wrapped in a Redux Provider.";
+    }
+  } else {
+    storeError = "react-redux is not installed";
+  }
+
+  // Create the resetStore function with guard to prevent double-firing
+  const resetStore = useCallback(() => {
+    // Synchronous guard - set flag immediately before any async work
+    if (isDispatching) {
+      return;
+    }
+    isDispatching = true;
+    if (store) {
+      // Dispatch the reset action
+      // The app's root reducer must handle this to actually reset state
+      store.dispatch({
+        type: resetActionType
+      });
+    }
+
+    // Reset flag after a short delay to allow next legitimate call
+    setTimeout(() => {
+      isDispatching = false;
+    }, 100);
+  }, [store, resetActionType]);
+
+  // Memoize result
+  const result = useMemo(() => {
+    if (!isReactReduxInstalled || storeError || !store) {
+      return {
+        isAvailable: false,
+        error: storeError,
+        resetStore: null
+      };
+    }
+    return {
+      isAvailable: true,
+      error: null,
+      resetStore
+    };
+  }, [isReactReduxInstalled, storeError, store, resetStore]);
+  return result;
+}
+
+/**
+ * Lightweight hook to just check if Redux is available
+ * without getting the store
+ */
+export function useReduxAvailability() {
+  const useStoreHook = getReactReduxUseStore();
+  if (!useStoreHook) {
+    return {
+      isInstalled: false,
+      isConnected: false,
+      error: "react-redux is not installed"
+    };
+  }
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const store = useStoreHook();
+    return {
+      isInstalled: true,
+      isConnected: store !== null && store !== undefined,
+      error: null
+    };
+  } catch (e) {
+    return {
+      isInstalled: true,
+      isConnected: false,
+      error: e instanceof Error ? e.message : "Not inside a Redux Provider"
+    };
+  }
+}

package/lib/module/impersonate/hooks/useImpersonate.js

@@ -0,0 +1,212 @@
+"use strict";
+
+/**
+ * useImpersonate Hook
+ *
+ * Main hook for managing impersonation state and actions.
+ * Provides all the controls needed to search users, start/stop
+ * impersonation, and manage settings.
+ */
+
+import { useState, useEffect, useCallback, useSyncExternalStore } from "react";
+import { impersonateStore } from "../utils/impersonateStore";
+import { impersonateListener } from "../utils/impersonateListener";
+/**
+ * Hook for managing impersonation
+ *
+ * @example
+ * ```tsx
+ * function ImpersonatePanel() {
+ *   const {
+ *     isActive,
+ *     currentUser,
+ *     searchUsers,
+ *     searchResults,
+ *     startImpersonation,
+ *     stopImpersonation,
+ *   } = useImpersonate({
+ *     onSearchUsers: async (query) => api.searchUsers(query),
+ *     onClearReactQuery: () => queryClient.clear(),
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       {isActive ? (
+ *         <Text>Impersonating: {currentUser?.email}</Text>
+ *       ) : (
+ *         <Text>Not impersonating</Text>
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useImpersonate(options = {}) {
+  const [searchQuery, setSearchQuery] = useState("");
+  const [searchResults, setSearchResults] = useState([]);
+  const [isSearching, setIsSearching] = useState(false);
+  const [searchError, setSearchError] = useState(null);
+
+  // Subscribe to store state using useSyncExternalStore
+  const state = useSyncExternalStore(impersonateStore.subscribe, impersonateStore.getSnapshot, impersonateStore.getSnapshot // Server snapshot (same for SSR)
+  );
+
+  // Register nuke callbacks when they change
+  useEffect(() => {
+    impersonateStore.registerNukeCallbacks({
+      reactQuery: options.onClearReactQuery,
+      redux: options.onClearRedux,
+      asyncStorage: options.onClearAsyncStorage,
+      mmkv: options.onClearMMKV
+    });
+  }, [options.onClearReactQuery, options.onClearRedux, options.onClearAsyncStorage, options.onClearMMKV]);
+
+  // Set up AsyncStorage reference immediately for writes, then load persisted state
+  useEffect(() => {
+    let isMounted = true;
+    const setupAsyncStorage = async () => {
+      try {
+        // Dynamically import AsyncStorage
+        const AsyncStorage = await import("@react-native-async-storage/async-storage").then(m => m.default);
+        const storageAdapter = {
+          getItem: key => AsyncStorage.getItem(key),
+          setItem: (key, value) => AsyncStorage.setItem(key, value)
+        };
+
+        // Set storage reference FIRST so writes work immediately
+        impersonateStore.setAsyncStorage(storageAdapter);
+
+        // Then load persisted state
+        if (isMounted) {
+          await impersonateStore.initializeAsync(storageAdapter);
+        }
+      } catch {
+        // AsyncStorage not available - using localStorage fallback (web)
+      }
+    };
+    setupAsyncStorage();
+
+    // Start listener
+    if (!impersonateListener().isListening) {
+      impersonateListener().startListening();
+    }
+    return () => {
+      isMounted = false;
+    };
+    // Don't stop listener on unmount - headers should keep being injected
+  }, []);
+
+  // Search users
+  const searchUsers = useCallback(async query => {
+    setSearchQuery(query);
+    setSearchError(null);
+    if (!query.trim()) {
+      setSearchResults([]);
+      return;
+    }
+    if (!options.onSearchUsers) {
+      setSearchError("Search not configured");
+      setSearchResults([]);
+      return;
+    }
+    setIsSearching(true);
+    try {
+      const results = await options.onSearchUsers(query);
+      setSearchResults(results);
+    } catch (error) {
+      setSearchError(error instanceof Error ? error.message : "Search failed");
+      setSearchResults([]);
+    } finally {
+      setIsSearching(false);
+    }
+  }, [options.onSearchUsers]);
+
+  // Clear search
+  const clearSearch = useCallback(() => {
+    setSearchQuery("");
+    setSearchResults([]);
+    setSearchError(null);
+  }, []);
+
+  // Start impersonation
+  const startImpersonation = useCallback(async user => {
+    await impersonateStore.startImpersonation(user);
+  }, []);
+
+  // Stop impersonation
+  const stopImpersonation = useCallback(async () => {
+    await impersonateStore.stopImpersonation();
+  }, []);
+
+  // Quick switch
+  const quickSwitch = useCallback(async user => {
+    await impersonateStore.quickSwitch(user);
+  }, []);
+
+  // Update header key
+  const updateHeaderKey = useCallback(async key => {
+    await impersonateStore.updateSettings({
+      headerKey: key
+    });
+  }, []);
+
+  // Update ignore patterns
+  const updateIgnorePatterns = useCallback(async patterns => {
+    await impersonateStore.updateSettings({
+      ignorePatterns: patterns
+    });
+  }, []);
+
+  // Update data nuke settings
+  const updateDataNukeSettings = useCallback(async settings => {
+    await impersonateStore.updateSettings({
+      dataNukeSettings: settings
+    });
+  }, []);
+
+  // Update show banner
+  const updateShowBanner = useCallback(async show => {
+    await impersonateStore.updateSettings({
+      showBanner: show
+    });
+  }, []);
+
+  // Remove from history
+  const removeFromHistory = useCallback(async userId => {
+    await impersonateStore.removeFromHistory(userId);
+  }, []);
+
+  // Clear history
+  const clearHistory = useCallback(async () => {
+    await impersonateStore.clearHistory();
+  }, []);
+  return {
+    // State
+    isActive: state.isActive,
+    currentUser: state.currentUser,
+    headerKey: state.headerKey,
+    ignorePatterns: state.ignorePatterns,
+    dataNukeSettings: state.dataNukeSettings,
+    showBanner: state.showBanner,
+    history: state.history,
+    // Search
+    searchQuery,
+    searchResults,
+    isSearching,
+    searchError,
+    searchUsers,
+    clearSearch,
+    // Actions
+    startImpersonation,
+    stopImpersonation,
+    quickSwitch,
+    // Settings
+    updateHeaderKey,
+    updateIgnorePatterns,
+    updateDataNukeSettings,
+    updateShowBanner,
+    // History
+    removeFromHistory,
+    clearHistory
+  };
+}