@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/useFeatureGate.md

@@ -2,156 +2,111 @@
 
 Unified feature gate combining authentication, subscription, and credits checks.
 
-## Import
-
-```typescript
-import { useFeatureGate } from '@umituz/react-native-subscription';
-```
-
-## Signature
-
-```typescript
-function useFeatureGate(params: {
-  isAuthenticated: boolean;
-  onShowAuthModal: (pendingCallback: () => void | Promise<void>) => void;
-  hasSubscription?: boolean;
-  hasCredits: boolean;
-  creditBalance: number;
-  requiredCredits?: number;
-  onShowPaywall: (requiredCredits?: number) => void;
-}): {
-  requireFeature: (action: () => void | Promise<void>) => void;
-  isAuthenticated: boolean;
-  hasSubscription: boolean;
-  hasCredits: boolean;
-  creditBalance: number;
-  canAccess: boolean;
-}
-```
-
-## Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `isAuthenticated` | `boolean` | **Required** | Whether user is authenticated |
-| `onShowAuthModal` | `(callback) => void` | **Required** | Show auth modal with pending action |
-| `hasSubscription` | `boolean` | `false` | Whether user has subscription |
-| `hasCredits` | `boolean` | **Required** | Whether user has enough credits |
-| `creditBalance` | `number` | **Required** | Current credit balance |
-| `requiredCredits` | `number` | `undefined` | Credits required for action |
-| `onShowPaywall` | `(credits?) => void` | **Required** | Show paywall/upgrade prompt |
-
-## Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `requireFeature` | `(action) => void` | Gate action behind auth, subscription, and credits |
-| `isAuthenticated` | `boolean` | User is authenticated |
-| `hasSubscription` | `boolean` | User has subscription |
-| `hasCredits` | `boolean` | User has enough credits |
-| `creditBalance` | `number` | Current credit balance |
-| `canAccess` | `boolean` | User can access the feature |
-
-## Basic Usage
-
-```typescript
-function PremiumFeature() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-  const { credits } = useCredits();
-
-  const { requireFeature, canAccess } = useFeatureGate({
-    isAuthenticated: !!user,
-    onShowAuthModal: (pendingAction) => {
-      navigation.navigate('Auth', { pendingAction });
-    },
-    hasSubscription: isPremium,
-    hasCredits: credits >= 5,
-    creditBalance: credits,
-    requiredCredits: 5,
-    onShowPaywall: (required) => {
-      if (isPremium) {
-        showInsufficientCreditsModal(required);
-      } else {
-        showPaywall();
-      }
-    },
-  });
-
-  const handleGenerate = () => {
-    requireFeature(async () => {
-      await generateContent();
-    });
-  };
-
-  return (
-    <Button
-      onPress={handleGenerate}
-      title={!canAccess ? 'Unlock Feature' : 'Generate'}
-    />
-  );
-}
-```
-
-## Advanced Usage
+## Location
+
+**Import Path**: `@umituz/react-native-subscription`
+
+**File**: `src/presentation/hooks/useFeatureGate.ts`
+
+**Type**: Hook
+
+## Strategy
 
 ### Progressive Access Control
 
-```typescript
-function ProgressiveFeatureGate() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-  const { credits } = useCredits();
-
-  const { requireFeature, canAccess, isAuthenticated, hasSubscription, hasCredits } =
-    useFeatureGate({
-      isAuthenticated: !!user,
-      onShowAuthModal: (pending) => showAuthModal({ pendingAction: pending }),
-      hasSubscription: isPremium,
-      hasCredits: credits >= 3,
-      creditBalance: credits,
-      requiredCredits: 3,
-      onShowPaywall: (required) => showUpgradeModal({ requiredCredits: required }),
-    });
-
-  const getAccessMessage = () => {
-    if (!isAuthenticated) return 'Sign in to access';
-    if (!hasSubscription && !hasCredits) return 'Upgrade or purchase credits';
-    if (!hasCredits) return 'Insufficient credits';
-    return 'Full access';
-  };
-
-  return (
-    <View>
-      <Text>{getAccessMessage()}</Text>
-      <Button
-        onPress={() => requireFeature(() => executeAction())}
-        disabled={!canAccess}
-        title={canAccess ? 'Execute Action' : 'Unlock'}
-      />
-    </View>
-  );
-}
-```
-
-## Best Practices
-
-1. **Check in order** - Auth → Subscription → Credits
-2. **Clear messaging** - Tell users exactly what's required
-3. **Preserve intent** - Queue pending actions through auth/purchase
-4. **Smart prompts** - Show relevant upgrade option
-5. **Track events** - Monitor gate triggers for optimization
-6. **Respect premium** - Bypass credits for subscribers
-7. **Show alternatives** - Offer both subscription and credits options
-
-## Related Hooks
-
-- **useAuthGate** - Auth gating only
-- **useSubscriptionGate** - Subscription gating only
-- **useCreditsGate** - Credits gating only
-- **usePremiumGate** - Premium feature gating
-
-## See Also
-
-- [Feature Gating](../../../docs/FEATURE_GATING.md)
-- [Access Control Patterns](../../../docs/ACCESS_PATTERNS.md)
+1. **Authentication Check**
+   - Verify user is authenticated
+   - Show auth modal if not authenticated
+   - Queue pending action for post-auth execution
+
+2. **Subscription Check**
+   - Verify user has required subscription tier
+   - Show paywall if subscription insufficient
+   - Bypass credit check for premium users
+
+3. **Credit Check**
+   - Verify sufficient credit balance
+   - Show purchase prompt if insufficient
+   - Deduct credits only after all checks pass
+
+4. **Action Execution**
+   - Execute gated action only if all checks pass
+   - Handle failures gracefully
+   - Update UI state appropriately
+
+### Integration Points
+
+- **useAuth**: For authentication state
+- **usePremium**: For subscription status
+- **useCredits**: For credit balance
+- **useDeductCredit**: For credit deduction
+- **Auth Modals**: Custom authentication UI
+- **Paywall Components**: Upgrade prompts
+
+## Restrictions
+
+### REQUIRED
+
+- **Authentication Check**: MUST implement `onShowAuthModal` callback
+- **Paywall Handler**: MUST implement `onShowPaywall` callback
+- **Credit Validation**: MUST check `hasCredits` before allowing actions
+- **State Management**: MUST respect `canAccess` boolean
+
+### PROHIBITED
+
+- **NEVER** bypass authentication check for sensitive features
+- **NEVER** show feature gate if user has access (confusing UX)
+- **NEVER** execute action without checking all gates first
+- **DO NOT** hardcode gate logic (use hook parameters)
+- **NEVER** deduct credits without checking subscription status first
+
+### CRITICAL SAFETY
+
+- **ALWAYS** check gates in order: Auth → Subscription → Credits
+- **ALWAYS** provide clear messaging about why access is denied
+- **ALWAYS** preserve user intent through auth/purchase flows
+- **NEVER** trust client-side gate for security (server-side validation required)
+- **MUST** implement proper error boundaries around gated actions
+
+## AI Agent Guidelines
+
+### When Implementing Feature Gates
+
+1. **Always** check gates in order: Auth → Subscription → Credits
+2. **Always** provide clear, specific messaging for each gate
+3. **Always** preserve user intent through auth/purchase flows
+4. **Always** bypass credit check for premium users (if applicable)
+5. **Never** trust client-side gates for security (server validation required)
+
+### Integration Checklist
+
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Implement `onShowAuthModal` with pending action preservation
+- [ ] Implement `onShowPaywall` with context-aware messaging
+- [ ] Check `canAccess` before showing feature
+- [ ] Provide appropriate messaging for each gate state
+- [ ] Respect premium status (bypass credit check if needed)
+- [ ] Test all gate combinations (auth, subscription, credits)
+- [ ] Test pending action execution after auth/purchase
+- [ ] Implement error boundaries around gated actions
+
+### Common Patterns to Implement
+
+1. **Progressive Unlocking**: Show upgrade path for each gate
+2. **Smart Paywalls**: Show subscription OR credits based on user state
+3. **Intent Preservation**: Queue actions through auth/purchase flows
+4. **Clear Messaging**: Tell users exactly what's required
+5. **Premium Bypass**: Skip credit check for premium users
+6. **Access Indicators**: Show lock/unlock status in UI
+7. **Graceful Degradation**: Show limited version for free users
+8. **Analytics Tracking**: Monitor gate triggers and conversions
+
+## Related Documentation
+
+- **useAuthGate**: Authentication gating only
+- **useSubscriptionGate**: Subscription gating only
+- **useCreditsGate**: Credits gating only
+- **usePremiumGate**: Premium feature gating
+- **useDeductCredit**: Credit deduction after gate passes
+- **Feature Gating**: `../../../docs/FEATURE_GATING.md`
+- **Access Control**: `../../../docs/ACCESS_PATTERNS.md`

package/src/presentation/hooks/useFeatureGate.md.bak

@@ -0,0 +1,284 @@
+# useFeatureGate Hook
+
+Unified feature gate combining authentication, subscription, and credits checks.
+
+## Location
+
+**Import Path**: `@umituz/react-native-subscription`
+
+**File**: `src/presentation/hooks/useFeatureGate.ts`
+
+**Type**: Hook
+
+## Strategy
+
+### Progressive Access Control
+
+1. **Authentication Check**
+   - Verify user is authenticated
+   - Show auth modal if not authenticated
+   - Queue pending action for post-auth execution
+
+2. **Subscription Check**
+   - Verify user has required subscription tier
+   - Show paywall if subscription insufficient
+   - Bypass credit check for premium users
+
+3. **Credit Check**
+   - Verify sufficient credit balance
+   - Show purchase prompt if insufficient
+   - Deduct credits only after all checks pass
+
+4. **Action Execution**
+   - Execute gated action only if all checks pass
+   - Handle failures gracefully
+   - Update UI state appropriately
+
+### Integration Points
+
+- **useAuth**: For authentication state
+- **usePremium**: For subscription status
+- **useCredits**: For credit balance
+- **useDeductCredit**: For credit deduction
+- **Auth Modals**: Custom authentication UI
+- **Paywall Components**: Upgrade prompts
+
+## Restrictions
+
+### REQUIRED
+
+- **Authentication Check**: MUST implement `onShowAuthModal` callback
+- **Paywall Handler**: MUST implement `onShowPaywall` callback
+- **Credit Validation**: MUST check `hasCredits` before allowing actions
+- **State Management**: MUST respect `canAccess` boolean
+
+### PROHIBITED
+
+- **NEVER** bypass authentication check for sensitive features
+- **NEVER** show feature gate if user has access (confusing UX)
+- **NEVER** execute action without checking all gates first
+- **DO NOT** hardcode gate logic (use hook parameters)
+- **NEVER** deduct credits without checking subscription status first
+
+### CRITICAL SAFETY
+
+- **ALWAYS** check gates in order: Auth → Subscription → Credits
+- **ALWAYS** provide clear messaging about why access is denied
+- **ALWAYS** preserve user intent through auth/purchase flows
+- **NEVER** trust client-side gate for security (server-side validation required)
+- **MUST** implement proper error boundaries around gated actions
+
+## Rules
+
+### Basic Feature Gating
+
+```typescript
+// CORRECT - All gates with clear messaging
+function PremiumFeature() {
+  const { requireFeature, canAccess, isAuthenticated, hasSubscription, hasCredits } =
+    useFeatureGate({
+      isAuthenticated: !!user,
+      onShowAuthModal: (pendingAction) => {
+        navigation.navigate('Auth', { pendingAction });
+      },
+      hasSubscription: isPremium,
+      hasCredits: credits >= 5,
+      creditBalance: credits,
+      requiredCredits: 5,
+      onShowPaywall: (required) => {
+        if (!isAuthenticated) return;
+        if (!hasSubscription) showPaywall();
+        else showCreditPurchase(required);
+      },
+    });
+
+  const handleAction = () => {
+    requireFeature(async () => {
+      await executeFeature();
+    });
+  };
+
+  return (
+    <Button
+      onPress={handleAction}
+      title={!canAccess ? 'Unlock Feature' : 'Execute'}
+    />
+  );
+}
+
+// INCORRECT - Missing auth callback
+const { requireFeature } = useFeatureGate({
+  isAuthenticated: !!user,
+  // Missing onShowAuthModal
+  hasSubscription: isPremium,
+  hasCredits: credits >= 5,
+  creditBalance: credits,
+  onShowPaywall: showPaywall,
+});
+
+// INCORRECT - No access check
+const handleAction = () => {
+  requireFeature(() => executeFeature());
+};
+// Always shows button, even if user can't access
+```
+
+### Progressive Access Control
+
+```typescript
+// CORRECT - Show appropriate message for each gate
+function ProgressiveGate() {
+  const { canAccess, isAuthenticated, hasSubscription, hasCredits } = useFeatureGate({
+    isAuthenticated: !!user,
+    onShowAuthModal: (pending) => showAuthModal({ pendingAction: pending }),
+    hasSubscription: isPremium,
+    hasCredits: credits >= 3,
+    creditBalance: credits,
+    requiredCredits: 3,
+    onShowPaywall: (required) => showUpgradeModal({ requiredCredits: required }),
+  });
+
+  const getAccessMessage = () => {
+    if (!isAuthenticated) return 'Sign in to access';
+    if (!hasSubscription && !hasCredits) return 'Upgrade or purchase credits';
+    if (!hasCredits) return `Need ${requiredCredits} credits`;
+    return 'Full access';
+  };
+
+  return (
+    <View>
+      <Text>{getAccessMessage()}</Text>
+      <Button
+        onPress={() => requireFeature(() => executeAction())}
+        disabled={!canAccess}
+        title={canAccess ? 'Execute' : 'Unlock'}
+      />
+    </View>
+  );
+}
+
+// INCORRECT - Generic message for all gates
+if (!canAccess) {
+  return <Text>You cannot access this feature</Text>;
+}
+// Doesn't tell user what they need to do
+```
+
+### Premium Bypass Logic
+
+```typescript
+// CORRECT - Premium users bypass credit check
+function PremiumBypass() {
+  const { requireFeature } = useFeatureGate({
+    isAuthenticated: !!user,
+    onShowAuthModal: (pending) => showAuthModal({ pendingAction: pending }),
+    hasSubscription: isPremium,
+    hasCredits: isPremium ? true : credits >= 5,
+    creditBalance: credits,
+    requiredCredits: isPremium ? 0 : 5,
+    onShowPaywall: (required) => {
+      if (isPremium) {
+        showInsufficientCreditsModal(required);
+      } else {
+        showPaywall();
+      }
+    },
+  });
+
+  return <Button onPress={() => requireFeature(executeAction)} />;
+}
+
+// INCORRECT - Charges premium users for credits
+hasCredits: credits >= 5, // Even if isPremium is true
+requiredCredits: 5, // Charges premium users
+```
+
+### Callback Implementation
+
+```typescript
+// CORRECT - Proper auth modal with pending action
+onShowAuthModal: (pendingAction) => {
+  navigation.navigate('Auth', {
+    onAuthSuccess: pendingAction,
+  });
+}
+
+// CORRECT - Context-aware paywall
+onShowPaywall: (requiredCredits) => {
+  if (isPremium) {
+    // Already premium, need credits
+    showCreditPurchaseModal({ requiredCredits });
+  } else {
+    // Not premium, show subscription
+    showSubscriptionPaywall();
+  }
+}
+
+// INCORRECT - No pending action preservation
+onShowAuthModal: () => {
+  navigation.navigate('Auth');
+  // User's intent is lost
+}
+```
+
+### Action Gating
+
+```typescript
+// CORRECT - Gate action execution
+const handleGenerate = () => {
+  requireFeature(async () => {
+    // Only runs if all gates pass
+    const result = await generateContent();
+    showResult(result);
+  });
+};
+
+// INCORRECT - Execute action before gating
+const handleGenerate = async () => {
+  const result = await generateContent(); // Runs regardless!
+  requireFeature(() => showResult(result));
+};
+```
+
+## AI Agent Guidelines
+
+### When Implementing Feature Gates
+
+1. **Always** check gates in order: Auth → Subscription → Credits
+2. **Always** provide clear, specific messaging for each gate
+3. **Always** preserve user intent through auth/purchase flows
+4. **Always** bypass credit check for premium users (if applicable)
+5. **Never** trust client-side gates for security (server validation required)
+
+### Integration Checklist
+
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Implement `onShowAuthModal` with pending action preservation
+- [ ] Implement `onShowPaywall` with context-aware messaging
+- [ ] Check `canAccess` before showing feature
+- [ ] Provide appropriate messaging for each gate state
+- [ ] Respect premium status (bypass credit check if needed)
+- [ ] Test all gate combinations (auth, subscription, credits)
+- [ ] Test pending action execution after auth/purchase
+- [ ] Implement error boundaries around gated actions
+
+### Common Patterns to Implement
+
+1. **Progressive Unlocking**: Show upgrade path for each gate
+2. **Smart Paywalls**: Show subscription OR credits based on user state
+3. **Intent Preservation**: Queue actions through auth/purchase flows
+4. **Clear Messaging**: Tell users exactly what's required
+5. **Premium Bypass**: Skip credit check for premium users
+6. **Access Indicators**: Show lock/unlock status in UI
+7. **Graceful Degradation**: Show limited version for free users
+8. **Analytics Tracking**: Monitor gate triggers and conversions
+
+## Related Documentation
+
+- **useAuthGate**: Authentication gating only
+- **useSubscriptionGate**: Subscription gating only
+- **useCreditsGate**: Credits gating only
+- **usePremiumGate**: Premium feature gating
+- **useDeductCredit**: Credit deduction after gate passes
+- **Feature Gating**: `../../../docs/FEATURE_GATING.md`
+- **Access Control**: `../../../docs/ACCESS_PATTERNS.md`