@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/presentation/hooks/usePaywallOperations.md

@@ -2,485 +2,91 @@
 
 Complete paywall purchase operations with authentication handling.
 
-## Import
+## Location
 
-```typescript
-import { usePaywallOperations } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/usePaywallOperations.ts`
 
-```typescript
-function usePaywallOperations(params: {
-  userId: string | undefined;
-  isAnonymous: boolean;
-  onPaywallClose?: () => void;
-  onPurchaseSuccess?: () => void;
-  onAuthRequired?: () => void;
-}): {
-  pendingPackage: PurchasesPackage | null;
-  handlePurchase: (pkg: PurchasesPackage) => Promise<boolean>;
-  handleRestore: () => Promise<boolean>;
-  handleInAppPurchase: (pkg: PurchasesPackage) => Promise<boolean>;
-  handleInAppRestore: () => Promise<boolean>;
-  completePendingPurchase: () => Promise<boolean>;
-  clearPendingPackage: () => void;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `userId` | `string \| undefined` | **Required** | Current user ID |
-| `isAnonymous` | `boolean` | **Required** | Whether user is anonymous/guest |
-| `onPaywallClose` | `() => void` | `undefined` | Callback when paywall closes |
-| `onPurchaseSuccess` | `() => void` | `undefined` | Callback after successful purchase |
-| `onAuthRequired` | `() => void` | `undefined` | Callback when auth is required |
+### Paywall Purchase Flow with Auth
 
-## Returns
+1. **Auth Check**: Verify if user is authenticated before purchase
+2. **Pending Package Management**: Store package when auth is required
+3. **Auth Flow Trigger**: Show auth modal for unauthenticated users
+4. **Purchase Execution**: Complete purchase after authentication
+5. **Restore Support**: Handle purchase restoration with auth check
+6. **Callback Handling**: Execute appropriate callbacks at each stage
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `pendingPackage` | `PurchasesPackage \| null` | Package waiting for auth |
-| `handlePurchase` | `(pkg) => Promise<boolean>` | Handle purchase (post-auth) |
-| `handleRestore` | `() => Promise<boolean>` | Handle restore (post-auth) |
-| `handleInAppPurchase` | `(pkg) => Promise<boolean>` | Handle purchase (in-app) |
-| `handleInAppRestore` | `() => Promise<boolean>` | Handle restore (in-app) |
-| `completePendingPurchase` | `() => Promise<boolean>` | Complete purchase after auth |
-| `clearPendingPackage` | `() => void` | Clear pending package |
+### Integration Points
 
-## Basic Usage
+- **usePremium**: For purchase and restore operations
+- **Auth Context**: User authentication state
+- **Paywall Domain**: For paywall display and management
+- **Auth UI**: For authentication modal
+- **RevenueCat**: For purchase transactions
 
-```typescript
-function PaywallScreen() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
+## Restrictions
 
-  const {
-    handlePurchase,
-    handleRestore,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onPurchaseSuccess: () => {
-      navigation.goBack();
-    },
-    onAuthRequired: () => {
-      showAuthModal();
-    },
-  });
+### REQUIRED
 
-  const onPackagePress = async (pkg: PurchasesPackage) => {
-    const success = await handlePurchase(pkg);
-    if (success) {
-      console.log('Purchase successful');
-    }
-  };
+- **User ID**: MUST provide valid userId parameter
+- **Anonymous Check**: MUST provide isAnonymous parameter
+- **Auth Required Callback**: MUST implement onAuthRequired callback
+- **Error Handling**: MUST handle purchase failures
 
-  const onRestorePress = async () => {
-    const success = await handleRestore();
-    if (success) {
-      console.log('Restore successful');
-    }
-  };
+### PROHIBITED
 
-  return (
-    <View>
-      <PackageList onSelectPackage={onPackagePress} />
-      <Button onPress={onRestorePress} title="Restore Purchases" />
-    </View>
-  );
-}
-```
+- **NEVER** call without valid userId
+- **NEVER** call without isAnonymous parameter
+- **DO NOT** proceed with purchase without auth check
+- **DO NOT** ignore pending package state
 
-## Advanced Usage
+### CRITICAL SAFETY
 
-### With Pending Purchase Flow
+- **ALWAYS** check authentication status before purchase
+- **MUST** handle pending package after auth
+- **ALWAYS** provide clear auth flow for users
+- **NEVER** allow anonymous purchases without auth
 
-```typescript
-function PaywallWithPendingFlow() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
+## AI Agent Guidelines
 
-  const {
-    pendingPackage,
-    handlePurchase,
-    completePendingPurchase,
-    clearPendingPackage,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onAuthRequired: () => {
-      navigation.navigate('AuthModal', {
-        purpose: 'purchase',
-        onAuthSuccess: () => {
-          // Complete purchase after auth
-          completePendingPurchase();
-        },
-      });
-    },
-  });
+### When Implementing Paywall Operations
 
-  // Show pending package indicator
-  useEffect(() => {
-    if (pendingPackage && !user) {
-      console.log('Package pending authentication:', pendingPackage.identifier);
-    }
-  }, [pendingPackage, user]);
+1. **Always** provide valid userId
+2. **Always** provide isAnonymous status
+3. **Always** implement onAuthRequired with pending package handling
+4. **Always** implement onPurchaseSuccess callback
+5. **Always** handle purchase and restore failures
 
-  const handleCancelAuth = () => {
-    clearPendingPackage();
-    navigation.goBack();
-  };
+### Integration Checklist
 
-  return (
-    <View>
-      {pendingPackage && !user && (
-        <Banner>
-          <Text>Complete your purchase after signing in</Text>
-          <Button onPress={handleCancelAuth} title="Cancel" />
-        </Banner>
-      )}
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide valid userId
+- [ ] Provide isAnonymous status
+- [ ] Implement onAuthRequired callback
+- [ ] Implement onPurchaseSuccess callback
+- [ ] Implement onPaywallClose callback
+- [ ] Handle pending package state
+- [ ] Test purchase with authenticated user
+- [ ] Test purchase with anonymous user
+- [ ] Test purchase flow after authentication
 
-      <PackageList onSelectPackage={handlePurchase} />
-    </View>
-  );
-}
-```
+### Common Patterns
 
-### With In-App Purchases
+1. **Pending Purchase Flow**: Store package, show auth, complete purchase
+2. **In-App Purchases**: Use handleInAppPurchase for modal paywalls
+3. **Purchase Analytics**: Track purchase attempts and completions
+4. **Error Recovery**: Handle failures and provide retry options
+5. **Post-Onboarding**: Handle purchases after onboarding flow
 
-```typescript
-function InAppPaywall() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
+## Related Documentation
 
-  const {
-    handleInAppPurchase,
-    handleInAppRestore,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onPaywallClose: () => {
-      navigation.goBack();
-    },
-    onPurchaseSuccess: () => {
-      navigation.goBack();
-    },
-    onAuthRequired: () => {
-      showAuthModal();
-    },
-  });
-
-  return (
-    <Modal>
-      <PaywallContent>
-        <PackageList onSelectPackage={handleInAppPurchase} />
-        <RestoreButton onPress={handleInAppRestore} />
-        <CloseButton onPress={() => navigation.goBack()} />
-      </PaywallContent>
-    </Modal>
-  );
-}
-```
-
-### With Purchase Analytics
-
-```typescript
-function TrackedPaywall() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
-
-  const {
-    handlePurchase,
-    handleRestore,
-    pendingPackage,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onPurchaseSuccess: () => {
-      analytics.track('purchase_completed', {
-        userId: user?.uid,
-        packageIdentifier: pendingPackage?.identifier,
-      });
-    },
-    onAuthRequired: () => {
-      analytics.track('auth_required_for_purchase');
-      showAuthModal();
-    },
-  });
-
-  const onPackageSelect = async (pkg: PurchasesPackage) => {
-    analytics.track('purchase_attempted', {
-      packageIdentifier: pkg.identifier,
-      price: pkg.product.price,
-    });
-
-    const success = await handlePurchase(pkg);
-
-    if (!success) {
-      analytics.track('purchase_failed', {
-        packageIdentifier: pkg.identifier,
-      });
-    }
-  };
-
-  return <PackageList onSelectPackage={onPackageSelect} />;
-}
-```
-
-### With Error Handling
-
-```typescript
-function RobustPaywall() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
-
-  const {
-    handlePurchase,
-    handleRestore,
-    completePendingPurchase,
-    clearPendingPackage,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onAuthRequired: () => {
-      showAuthModal({
-        onAuthSuccess: async () => {
-          const success = await completePendingPurchase();
-          if (!success) {
-            Alert.alert('Error', 'Could not complete purchase');
-            clearPendingPackage();
-          }
-        },
-        onAuthCancelled: () => {
-          clearPendingPackage();
-        },
-      });
-    },
-  });
-
-  const handlePackagePress = async (pkg: PurchasesPackage) => {
-    try {
-      const success = await handlePurchase(pkg);
-
-      if (!success) {
-        if (!user) {
-          // Auth required - handled by onAuthRequired
-          return;
-        }
-        // Other failure
-        Alert.alert('Purchase Failed', 'Could not complete purchase. Please try again.');
-      }
-    } catch (error) {
-      console.error('Purchase error:', error);
-      Alert.alert('Error', 'An unexpected error occurred');
-    }
-  };
-
-  return <PackageList onSelectPackage={handlePackagePress} />;
-}
-```
-
-## Examples
-
-### Complete Paywall Implementation
-
-```typescript
-function PaywallScreen() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
-  const navigation = useNavigation();
-
-  const {
-    pendingPackage,
-    handlePurchase,
-    handleRestore,
-    completePendingPurchase,
-    clearPendingPackage,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onPaywallClose: () => {
-      navigation.goBack();
-    },
-    onPurchaseSuccess: () => {
-      // Refresh user data
-      queryClient.invalidateQueries(['subscription']);
-      navigation.goBack();
-    },
-    onAuthRequired: () => {
-      // Show auth modal with pending purchase context
-      navigation.push('AuthModal', {
-        purpose: 'purchase',
-        message: 'Sign in to complete your purchase',
-        onAuthSuccess: async () => {
-          const success = await completePendingPurchase();
-          if (success) {
-            navigation.goBack();
-          }
-        },
-        onAuthCancelled: () => {
-          clearPendingPackage();
-        },
-      });
-    },
-  });
-
-  const [selectedPackage, setSelectedPackage] = useState<PurchasesPackage | null>(null);
-
-  const onPackagePress = async (pkg: PurchasesPackage) => {
-    setSelectedPackage(pkg);
-    const success = await handlePurchase(pkg);
-    setSelectedPackage(null);
-  };
-
-  const onRestorePress = async () => {
-    const success = await handleRestore();
-    Alert.alert(
-      success ? 'Success' : 'No Purchases Found',
-      success
-        ? 'Your purchases have been restored'
-        : 'No previous purchases found for this account'
-    );
-  };
-
-  return (
-    <ScrollView style={styles.container}>
-      <PaywallHeader />
-
-      {pendingPackage && !user && (
-        <Banner style={styles.pendingBanner}>
-          <Text>Complete your purchase after signing in</Text>
-        </Banner>
-      )}
-
-      <PackageList
-        packages={packages}
-        selectedPackage={selectedPackage}
-        onSelectPackage={onPackagePress}
-      />
-
-      <View style={styles.restoreSection}>
-        <Button
-          onPress={onRestorePress}
-          variant="outline"
-          title="Restore Purchases"
-        />
-      </View>
-
-      <TermsAndConditions />
-    </ScrollView>
-  );
-}
-```
-
-### Post-Onboarding Purchase
-
-```typescript
-function PostOnboardingPaywall() {
-  const { user } = useAuth();
-  const { isAnonymous } = useAuth();
-
-  const {
-    handlePurchase,
-    completePendingPurchase,
-  } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous,
-    onPurchaseSuccess: () => {
-      // Navigate to onboarding completion
-      navigation.reset({
-        index: 0,
-        routes: [{ name: 'Home' }],
-      });
-    },
-    onAuthRequired: () => {
-      navigation.navigate('Auth', {
-        screen: 'SignUp',
-        params: {
-          onAuthSuccess: async () => {
-            await completePendingPurchase();
-          },
-        },
-      });
-    },
-  });
-
-  return (
-    <View>
-      <OnboardingPaywallContent />
-      <PackageList onSelectPackage={handlePurchase} />
-    </View>
-  );
-}
-```
-
-## Purchase Flow
-
-### Authenticated User
-
-```typescript
-user = { uid: 'user-123' }
-isAnonymous = false
-
-handlePurchase(package)
-→ Purchase proceeds immediately ✅
-→ onPurchaseSuccess() called ✅
-```
-
-### Anonymous User
-
-```typescript
-user = null
-isAnonymous = true
-
-handlePurchase(package)
-→ Purchase blocked 🚫
-→ pendingPackage = package 📦
-→ onAuthRequired() called 🔐
-→ User completes auth...
-→ completePendingPurchase()
-→ Purchase proceeds ✅
-```
-
-### Pending Package Management
-
-```typescript
-// User selects package while not authenticated
-handlePurchase(monthlyPackage)
-→ pendingPackage = monthlyPackage
-→ onAuthRequired() triggered
-
-// User cancels auth
-clearPendingPackage()
-→ pendingPackage = null
-
-// Or user completes auth
-completePendingPurchase()
-→ Purchases monthlyPackage
-→ pendingPackage = null
-```
-
-## Best Practices
-
-1. **Handle auth flow** - Implement onAuthRequired callback
-2. **Show pending state** - Display indicator when package is pending
-3. **Clear pending** - Reset pending when user cancels auth
-4. **Track events** - Monitor purchase attempts and completions
-5. **Handle errors** - Show user-friendly error messages
-6. **Test both flows** - Authenticated and anonymous users
-7. **Provide restore** - Always offer restore purchases option
-
-## Related Hooks
-
-- **usePremium** - For purchase and restore operations
-- **useAuthAwarePurchase** - For auth-gated purchases
-- **usePaywallVisibility** - For paywall visibility control
-
-## See Also
-
-- [Paywall Screen](../screens/README.md)
-- [Purchase Flow](../../../docs/PURCHASE_FLOW.md)
-- [Auth Integration](./useAuthSubscriptionSync.md)
+- **usePremium**: For purchase and restore operations
+- **useAuthAwarePurchase**: For auth-gated purchases
+- **usePaywallVisibility**: For paywall visibility control
+- **Paywall Screen**: `src/presentation/screens/README.md`
+- **Purchase Flow**: `src/docs/PURCHASE_FLOW.md`