@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/presentation/hooks/useAuthSubscriptionSync.md

@@ -2,397 +2,93 @@
 
 Automatically synchronizes subscription state with authentication changes.
 
-## Import
+## Location
 
-```typescript
-import { useAuthSubscriptionSync } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useAuthSubscriptionSync.ts`
 
-```typescript
-function useAuthSubscriptionSync(config: {
-  onAuthStateChanged: (callback: (userId: string | null) => void) => () => void;
-  initializeSubscription: (userId: string) => Promise<void>;
-}): void
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `onAuthStateChanged` | `(callback) => () => void` | **Required** | Subscribe to auth changes, returns unsubscribe function |
-| `initializeSubscription` | `(userId) => Promise<void>` | **Required** | Initialize subscription for user |
+### Auth-Subscription Synchronization
 
-## Basic Usage
+1. **Auth Listener Setup**: Subscribe to auth state changes via provided callback
+2. **User Change Detection**: Detect when userId changes (including sign out)
+3. **Subscription Initialization**: Initialize subscription when user signs in
+4. **One-Time Init**: Only initialize once per user session (skips duplicates)
+5. **User Switching**: Re-initialize when switching between accounts
+6. **Cleanup**: Unsubscribe from auth listener on unmount
 
-```typescript
-function App() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      // Subscribe to Firebase auth changes
-      const unsubscribe = auth.onAuthStateChanged((user) => {
-        callback(user?.uid || null);
-      });
-      return unsubscribe;
-    },
-    initializeSubscription: async (userId) => {
-      // Initialize RevenueCat or subscription service
-      await Purchases.configure({ apiKey: 'your_key', appUserID: userId });
-      await fetchSubscriptionStatus(userId);
-    },
-  });
+### Integration Points
 
-  return <YourAppNavigation />;
-}
-```
+- **Auth Provider**: Any auth system (Firebase, Auth0, custom)
+- **RevenueCat**: For subscription initialization with logIn
+- **Subscription Service**: Backend subscription sync
+- **Credits System**: Optional credits initialization
+- **App Root**: Should be placed in root App component
 
-## Advanced Usage
+## Restrictions
 
-### With Firebase Auth
+### REQUIRED
 
-```typescript
-function AppWithFirebase() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      const unsubscribe = auth.onAuthStateChanged((user) => {
-        callback(user?.uid || null);
-      });
-      return unsubscribe;
-    },
-    initializeSubscription: async (userId) => {
-      if (!userId) return;
+- **Auth State Change Callback**: MUST provide onAuthStateChanged function
+- **Subscription Init**: MUST provide initializeSubscription function
+- **App Root Setup**: SHOULD be placed in root App component
+- **Unsubscribe Handling**: Callback MUST return unsubscribe function
 
-      // Configure RevenueCat with user ID
-      await Purchases.logIn(userId);
-      await syncSubscriptionWithBackend(userId);
-    },
-  });
+### PROHIBITED
 
-  return <AppNavigator />;
-}
-```
+- **NEVER** place in individual screen components (use app root)
+- **NEVER** call without proper auth callback
+- **DO NOT** manually call initializeSubscription (hook handles it)
+- **DO NOT** configure multiple times (one-time setup)
 
-### With Custom Auth Provider
+### CRITICAL SAFETY
 
-```typescript
-function AppWithCustomAuth() {
-  const authManager = useAuthManager();
+- **ALWAYS** configure at app root level
+- **MUST** handle user switching correctly
+- **ALWAYS** return unsubscribe function from callback
+- **NEVER** rely on manual subscription initialization
 
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      // Your custom auth system
-      const unsubscribe = authManager.addListener((user) => {
-        callback(user?.id || null);
-      });
-      return unsubscribe;
-    },
-    initializeSubscription: async (userId) => {
-      // Initialize your subscription system
-      await subscriptionService.initialize(userId);
-      await loadSubscriptionData(userId);
-    },
-  });
+## AI Agent Guidelines
 
-  return <App />;
-}
-```
+### When Implementing Auth-Subscription Sync
 
-### With Multiple Subscription Services
+1. **Always** place in root App component
+2. **Always** provide onAuthStateChanged that returns unsubscribe
+3. **Always** provide initializeSubscription for user ID
+4. **Always** test user switching scenarios
+5. **Never** place in child components
 
-```typescript
-function AppWithMultipleServices() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      return auth.onAuthStateChanged((user) => {
-        callback(user?.uid || null);
-      });
-    },
-    initializeSubscription: async (userId) => {
-      // Initialize RevenueCat
-      await Purchases.logIn(userId);
+### Integration Checklist
 
-      // Initialize custom credits system
-      await creditsRepository.initialize(userId);
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Place in root App component
+- [ ] Provide onAuthStateChanged callback
+- [ ] Ensure callback returns unsubscribe function
+- [ ] Provide initializeSubscription function
+- [ ] Test with initial user sign-in
+- [ ] Test with user sign-out
+- [ ] Test with account switching
+- [ ] Verify subscription initializes only once per user
+- [ ] Test cleanup on unmount
 
-      // Sync with backend
-      await subscriptionSyncService.sync(userId);
-    },
-  });
+### Common Patterns
 
-  return <App />;
-}
-```
+1. **Firebase + RevenueCat**: Sync Firebase auth with RevenueCat
+2. **Custom Auth + Backend**: Use custom auth with backend sync
+3. **Multi-Service Setup**: Initialize multiple services (RevenueCat, credits, backend)
+4. **Error Handling**: Handle initialization failures gracefully
+5. **Loading State**: Show loading during sync
+6. **Analytics Tracking**: Track auth and subscription events
 
-### With Error Handling
+## Related Documentation
 
-```typescript
-function AppWithErrorHandling() {
-  const [syncError, setSyncError] = useState<Error | null>(null);
-
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      return auth.onAuthStateChanged((user) => {
-        callback(user?.uid || null);
-      });
-    },
-    initializeSubscription: async (userId) => {
-      try {
-        setSyncError(null);
-        await Purchases.logIn(userId);
-        await syncSubscriptionData(userId);
-      } catch (error) {
-        console.error('Subscription sync failed:', error);
-        setSyncError(error as Error);
-        // Optionally retry or show error to user
-      }
-    },
-  });
-
-  if (syncError) {
-    return <ErrorScreen error={syncError} />;
-  }
-
-  return <AppNavigation />;
-}
-```
-
-### With Loading State
-
-```typescript
-function AppWithLoadingState() {
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [isInitialized, setIsInitialized] = useState(false);
-
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      return auth.onAuthStateChanged((user) => {
-        callback(user?.uid || null);
-      });
-    },
-    initializeSubscription: async (userId) => {
-      if (!userId) {
-        setIsInitialized(false);
-        return;
-      }
-
-      setIsSyncing(true);
-      try {
-        await Purchases.logIn(userId);
-        await loadUserSubscription(userId);
-        setIsInitialized(true);
-      } finally {
-        setIsSyncing(false);
-      }
-    },
-  });
-
-  if (isSyncing) {
-    return <LoadingScreen message="Syncing subscription..." />;
-  }
-
-  return <AppNavigation />;
-}
-```
-
-## Examples
-
-### Complete App Setup
-
-```typescript
-import React from 'react';
-import { useAuthSubscriptionSync } from '@umituz/react-native-subscription';
-import { auth } from './firebase/config';
-import { Purchases } from 'react-native-purchases';
-import { subscriptionService } from './services/subscription';
-
-function App() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      const unsubscribe = auth.onAuthStateChanged(async (user) => {
-        console.log('Auth state changed:', user?.uid || 'none');
-        callback(user?.uid || null);
-      });
-      return unsubscribe;
-    },
-    initializeSubscription: async (userId) => {
-      if (!userId) {
-        console.log('No user, skipping subscription init');
-        return;
-      }
-
-      console.log('Initializing subscription for:', userId);
-
-      try {
-        // Step 1: Identify user in RevenueCat
-        await Purchases.logIn(userId);
-
-        // Step 2: Fetch subscription status
-        await subscriptionService.fetchStatus(userId);
-
-        // Step 3: Sync with backend
-        await subscriptionService.syncWithBackend(userId);
-
-        console.log('Subscription initialized successfully');
-      } catch (error) {
-        console.error('Failed to initialize subscription:', error);
-      }
-    },
-  });
-
-  return <AppNavigator />;
-}
-
-export default App;
-```
-
-### With Analytics Tracking
-
-```typescript
-function AppWithAnalytics() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      return auth.onAuthStateChanged((user) => {
-        const userId = user?.uid || null;
-        analytics.identify(userId);
-        callback(userId);
-      });
-    },
-    initializeSubscription: async (userId) => {
-      analytics.track('subscription_sync_start', { userId });
-
-      await Purchases.logIn(userId);
-
-      const customerInfo = await Purchases.getCustomerInfo();
-      const isPremium = !!customerInfo.entitlements.active.premium;
-
-      analytics.track('subscription_sync_complete', {
-        userId,
-        isPremium,
-      });
-    },
-  });
-
-  return <App />;
-}
-```
-
-### With User Switching
-
-```typescript
-function AppWithUserSwitching() {
-  useAuthSubscriptionSync({
-    onAuthStateChanged: (callback) => {
-      return auth.onAuthStateChanged((user) => {
-        const newUserId = user?.uid || null;
-        console.log('User changed:', newUserId);
-        callback(newUserId);
-      });
-    },
-    initializeSubscription: async (userId) => {
-      if (!userId) {
-        // User signed out - clear subscription data
-        subscriptionService.clear();
-        return;
-      }
-
-      // New user signed in or account switch
-      // The hook handles detecting userId changes
-      await Purchases.logIn(userId);
-      await subscriptionService.loadForUser(userId);
-    },
-  });
-
-  return <App />;
-}
-```
-
-## How It Works
-
-### Automatic Initialization
-
-The hook automatically:
-
-1. **Listens to auth changes** - Subscribes to your auth provider
-2. **Detects user changes** - Identifies when user ID changes
-3. **Initializes once** - Only initializes once per user session
-4. **Re-initializes on user switch** - Detects account switching
-5. **Cleans up** - Unsubscribes when component unmounts
-
-### User Change Detection
-
-```typescript
-// Initial mount with user A
-auth.onAuthStateChanged => callback('user-a-id')
-initializeSubscription('user-a-id') // ✅ Runs
-
-// Same user, no change
-auth.onAuthStateChanged => callback('user-a-id')
-initializeSubscription('user-a-id') // ❌ Skipped (same user)
-
-// User switches to user B
-auth.onAuthStateChanged => callback('user-b-id')
-initializeSubscription('user-b-id') // ✅ Runs (user changed)
-
-// User signs out
-auth.onAuthStateChanged => callback(null)
-// ❌ No initialization (no user)
-```
-
-## Best Practices
-
-1. **Configure at app root** - Place in root App component
-2. **Handle errors gracefully** - Catch and log initialization errors
-3. **Show loading state** - Display loading during sync
-4. **Test user switching** - Verify account switching works
-5. **Cleanup properly** - Let hook handle unsubscribe
-6. **One-time setup** - Configure once, don't reinitialize
-7. **Monitor logs** - Use dev logs to verify behavior
-
-## Common Patterns
-
-### Firebase + RevenueCat
-
-```typescript
-useAuthSubscriptionSync({
-  onAuthStateChanged: (callback) => auth.onAuthStateChanged((user) => callback(user?.uid || null)),
-  initializeSubscription: (userId) => Purchases.logIn(userId),
-});
-```
-
-### Custom Auth + Backend
-
-```typescript
-useAuthSubscriptionSync({
-  onAuthStateChanged: (callback) => customAuth.onAuthChange((user) => callback(user?.id || null)),
-  initializeSubscription: (userId) => backend.syncSubscription(userId),
-});
-```
-
-### Multi-Service Setup
-
-```typescript
-useAuthSubscriptionSync({
-  onAuthStateChanged: (callback) => auth.onAuthStateChanged((user) => callback(user?.uid)),
-  initializeSubscription: async (userId) => {
-    await Promise.all([
-      Purchases.logIn(userId),
-      creditsService.init(userId),
-      subscriptionBackend.sync(userId),
-    ]);
-  },
-});
-```
-
-## Related Hooks
-
-- **useAuth** - For authentication state
-- **usePremium** - For subscription status
-- **useAuthAwarePurchase** - For auth-gated purchases
-- **useUserTier** - For tier determination
-
-## See Also
-
-- [Auth Integration Guide](../../../docs/AUTH_INTEGRATION.md)
-- [RevenueCat Setup](../../../docs/REVENUECAT_SETUP.md)
-- [Subscription State Management](../providers/README.md)
+- **useAuth**: For authentication state
+- **usePremium**: For subscription status
+- **useAuthAwarePurchase**: For auth-gated purchases
+- **useUserTier**: For tier determination
+- **Auth Integration Guide**: `src/docs/AUTH_INTEGRATION.md`
+- **RevenueCat Setup**: `src/docs/REVENUECAT_SETUP.md`