@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/usePremiumGate.md

@@ -2,422 +2,87 @@
 
 Feature gating hook for premium-only features with optional authentication.
 
-## Import
+## Location
 
-```typescript
-import { usePremiumGate } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/usePremiumGate.ts`
 
-```typescript
-function usePremiumGate(params: {
-  isPremium: boolean;
-  onPremiumRequired: () => void;
-  isAuthenticated?: boolean;
-  onAuthRequired?: () => void;
-}): {
-  isPremium: boolean;
-  isAuthenticated: boolean;
-  requirePremium: (action: () => void) => void;
-  requireAuth: (action: () => void) => void;
-  requirePremiumWithAuth: (action: () => void) => void;
-  canAccess: boolean;
-  canAccessWithAuth: boolean;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `isPremium` | `boolean` | **Required** | Whether user has premium access |
-| `onPremiumRequired` | `() => void` | **Required** | Callback when premium is required |
-| `isAuthenticated` | `boolean` | `true` | Whether user is authenticated |
-| `onAuthRequired` | `() => void` | `undefined` | Callback when auth is required |
+### Premium Gating Flow
 
-## Returns
+1. **Premium Check**: Verify if user has premium access
+2. **Auth Check**: Optionally verify authentication status
+3. **Gate Functions**: Provide requirePremium, requireAuth, requirePremiumWithAuth
+4. **Access Control**: Simple booleans for conditional rendering (canAccess, canAccessWithAuth)
+5. **Callback Triggers**: Execute appropriate callback when requirements not met
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `isPremium` | `boolean` | User has premium access |
-| `isAuthenticated` | `boolean` | User is authenticated |
-| `requirePremium` | `(action) => void` | Gate action behind premium |
-| `requireAuth` | `(action) => void` | Gate action behind auth |
-| `requirePremiumWithAuth` | `(action) => void` | Gate behind both auth and premium |
-| `canAccess` | `boolean` | Can access premium feature |
-| `canAccessWithAuth` | `boolean` | Can access (auth + premium) |
+### Integration Points
 
-## Basic Usage
+- **usePremium**: For premium status check
+- **useAuth**: For authentication status
+- **Paywall Domain**: For premium upgrade flow
+- **Auth UI**: For authentication flow
 
-```typescript
-function PremiumFeature() {
-  const { isPremium } = usePremium();
+## Restrictions
 
-  const { requirePremium, canAccess } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => {
-      showPaywall();
-    },
-  });
+### REQUIRED
 
-  const handleGenerate = () => {
-    requirePremium(() => {
-      // This only runs if user is premium
-      generatePremiumContent();
-    });
-  };
+- **Premium Status**: MUST provide isPremium parameter
+- **Callback**: MUST implement onPremiumRequired callback
+- **Access Check**: MUST verify canAccess before showing premium content
 
-  return (
-    <Button
-      onPress={handleGenerate}
-      disabled={!canAccess}
-      title={canAccess ? 'Generate' : 'Upgrade to Premium'}
-    />
-  );
-}
-```
+### PROHIBITED
 
-## Advanced Usage
+- **NEVER** show premium content without checking isPremium
+- **NEVER** use for security decisions without server validation
+- **DO NOT** assume premium status (always verify)
 
-### With Authentication Check
+### CRITICAL SAFETY
 
-```typescript
-function AuthenticatedPremiumFeature() {
-  const { isPremium } = usePremium();
-  const { user } = useAuth();
+- **ALWAYS** verify canAccess before showing premium features
+- **NEVER** trust client-side state for security
+- **MUST** implement proper upgrade flow
+- **ALWAYS** handle authentication when required
 
-  const { requirePremiumWithAuth, canAccessWithAuth } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => showPaywall(),
-    isAuthenticated: !!user,
-    onAuthRequired: () => showAuthModal(),
-  });
+## AI Agent Guidelines
 
-  const handleAction = () => {
-    requirePremiumWithAuth(() => {
-      // Only runs if user is both authenticated AND premium
-      executeAction();
-    });
-  };
+### When Implementing Premium Gates
 
-  return (
-    <Button
-      onPress={handleAction}
-      disabled={!canAccessWithAuth}
-      title="Premium Action"
-    />
-  );
-}
-```
+1. **Always** check canAccess before showing premium content
+2. **Always** provide clear upgrade path in callback
+3. **Always** use requirePremium for action gating
+4. **Always** handle authentication when using requirePremiumWithAuth
+5. **Never** bypass premium checks
 
-### With Separate Gates
+### Integration Checklist
 
-```typescript
-function MultiGateFeature() {
-  const { isPremium } = usePremium();
-  const { user } = useAuth();
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide isPremium from usePremium
+- [ ] Implement onPremiumRequired callback
+- [ ] Optionally provide auth status and callback
+- [ ] Use requirePremium for action gating
+- [ ] Check canAccess for conditional rendering
+- [ ] Test with premium user
+- [ ] Test with non-premium user
+- [ ] Test with authenticated user
+- [ ] Test with unauthenticated user
 
-  const {
-    requirePremium,
-    requireAuth,
-    canAccess,
-  } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => showPaywall(),
-    isAuthenticated: !!user,
-    onAuthRequired: () => showAuthModal(),
-  });
+### Common Patterns
 
-  return (
-    <View>
-      <Button
-        onPress={() => requireAuth(() => saveToAccount())}
-        title="Save to Account (Auth required)"
-      />
+1. **Premium Only**: Gate features behind premium only
+2. **Auth + Premium**: Require both authentication and premium
+3. **Conditional Rendering**: Check canAccess for UI
+4. **Button States**: Disable buttons when not premium
+5. **Upgrade Prompts**: Show in callback when not premium
 
-      <Button
-        onPress={() => requirePremium(() => usePremiumFeature())}
-        title="Premium Feature (Premium required)"
-      />
-    </View>
-  );
-}
-```
+## Related Documentation
 
-### With Progressive Access
-
-```typescript
-function ProgressiveAccess() {
-  const { isPremium } = usePremium();
-  const { user } = useAuth();
-
-  const {
-    isPremium: premium,
-    isAuthenticated: auth,
-    canAccess,
-    canAccessWithAuth,
-  } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => showPaywall(),
-    isAuthenticated: !!user,
-    onAuthRequired: () => showAuthModal(),
-  });
-
-  const getAccessLevel = () => {
-    if (!auth) return 'guest';
-    if (!premium) return 'free';
-    return 'premium';
-  };
-
-  const accessLevel = getAccessLevel();
-
-  return (
-    <View>
-      <Badge text={accessLevel} />
-
-      <FeatureList accessibleTo={['guest', 'free', 'premium']} />
-      <FeatureList accessibleTo={['free', 'premium']} />
-      <FeatureList accessibleTo={['premium']} />
-    </View>
-  );
-}
-```
-
-### With Navigation Guard
-
-```typescript
-function PremiumScreen() {
-  const { isPremium } = usePremium();
-  const navigation = useNavigation();
-
-  const { requirePremium } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => {
-      navigation.replace('Paywall', {
-        returnTo: 'PremiumScreen',
-      });
-    },
-  });
-
-  useEffect(() => {
-    // Redirect if not premium
-    requirePremium(() => {});
-  }, []);
-
-  if (!isPremium) return null;
-
-  return (
-    <View>
-      <Text>Premium Screen Content</Text>
-    </View>
-  );
-}
-```
-
-## Examples
-
-### Premium Button Component
-
-```typescript
-function PremiumButton({
-  children,
-  onAction,
-  showUpgradeMessage = true,
-}) {
-  const { isPremium } = usePremium();
-
-  const { requirePremium, canAccess } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => {
-      if (showUpgradeMessage) {
-        Alert.alert(
-          'Premium Feature',
-          'This feature requires a Premium subscription',
-          [
-            { text: 'Cancel', style: 'cancel' },
-            { text: 'Upgrade', onPress: () => navigation.navigate('Paywall') },
-          ]
-        );
-      }
-    },
-  });
-
-  const handlePress = () => {
-    requirePremium(() => {
-      onAction?.();
-    });
-  };
-
-  return (
-    <TouchableOpacity
-      onPress={handlePress}
-      style={[styles.button, !canAccess && styles.lockedButton]}
-      disabled={!canAccess}
-    >
-      <PremiumIcon active={canAccess} />
-      <Text style={styles.text}>{children}</Text>
-      {!canAccess && <LockIcon />}
-    </TouchableOpacity>
-  );
-}
-```
-
-### Batch Premium Operations
-
-```typescript
-function BatchPremiumOperations({ items }) {
-  const { isPremium } = usePremium();
-
-  const { requirePremium } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => {
-      showPaywall({
-        feature: 'Batch Operations',
-        highlight: `Process ${items.length} items at once`,
-      });
-    },
-  });
-
-  const handleBatchProcess = () => {
-    requirePremium(async () => {
-      for (const item of items) {
-        await processItem(item);
-        updateProgress();
-      }
-      Alert.alert('Complete', `Processed ${items.length} items`);
-    });
-  };
-
-  return (
-    <Button
-      onPress={handleBatchProcess}
-      title={`Process ${items.length} items`}
-    />
-  );
-}
-```
-
-### Conditional Rendering
-
-```typescript
-function ConditionalPremiumFeature() {
-  const { isPremium } = usePremium();
-
-  const { canAccess } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => showPaywall(),
-  });
-
-  if (!canAccess) {
-    return (
-      <View style={styles.lockedContainer}>
-        <LockIcon size={48} />
-        <Text style={styles.title}>Premium Feature</Text>
-        <Text style={styles.message}>
-          Upgrade to access this feature
-        </Text>
-        <Button
-          onPress={() => showPaywall()}
-          title="Upgrade Now"
-        />
-      </View>
-    );
-  }
-
-  return (
-    <View>
-      <Text>Premium Content</Text>
-      <PremiumFeatureComponent />
-    </View>
-  );
-}
-```
-
-### With Analytics
-
-```typescript
-function TrackedPremiumFeature() {
-  const { isPremium } = usePremium();
-
-  const { requirePremium } = usePremiumGate({
-    isPremium,
-    onPremiumRequired: () => {
-      analytics.track('premium_feature_accessed', {
-        feature: 'advanced_analytics',
-        success: false,
-        reason: 'not_premium',
-      });
-      showPaywall();
-    },
-  });
-
-  const handleFeature = () => {
-    requirePremium(() => {
-      analytics.track('premium_feature_used', {
-        feature: 'advanced_analytics',
-        success: true,
-      });
-      executeFeature();
-    });
-  };
-
-  return <Button onPress={handleFeature} title="Use Premium Feature" />;
-}
-```
-
-## Best Practices
-
-1. **Clear messaging** - Tell users what they're missing
-2. **Smooth upgrades** - Make subscription path obvious
-3. **Respect auth** - Check authentication before premium
-4. **Track events** - Monitor gate triggers
-5. **Value first** - Show benefits before locking
-6. **Graceful fallbacks** - Show limited version if appropriate
-7. **Context-aware** - Customize paywall based on feature
-
-## Use Case Patterns
-
-### Premium Only (No Auth)
-
-```typescript
-const { requirePremium } = usePremiumGate({
-  isPremium,
-  onPremiumRequired: () => showPaywall(),
-});
-```
-
-### Auth + Premium Required
-
-```typescript
-const { requirePremiumWithAuth } = usePremiumGate({
-  isPremium,
-  onPremiumRequired: () => showPaywall(),
-  isAuthenticated: !!user,
-  onAuthRequired: () => showAuthModal(),
-});
-```
-
-### Separate Auth and Premium Gates
-
-```typescript
-const { requireAuth, requirePremium } = usePremiumGate({
-  isPremium,
-  onPremiumRequired: () => showPaywall(),
-  isAuthenticated: !!user,
-  onAuthRequired: () => showAuthModal(),
-});
-```
-
-## Related Hooks
-
-- **useAuthGate** - Authentication gating only
-- **useSubscriptionGate** - Subscription gating
-- **useFeatureGate** - Combined auth + subscription + credits
-- **usePremium** - Premium status checking
-
-## See Also
-
-- [Premium Gating](../../../docs/PREMIUM_GATING.md)
-- [Feature Access Patterns](../../../docs/ACCESS_PATTERNS.md)
-- [Paywall Triggers](../screens/README.md#triggers)
+- **usePremium**: Premium status check
+- **useAuthGate**: Auth + subscription gating
+- **useSubscriptionGate**: Subscription-only gating
+- **useFeatureGate**: Unified feature gating
+- **Paywall Domain**: `src/domains/paywall/README.md`