@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/presentation/hooks/useAuthGate.md

@@ -2,402 +2,88 @@
 
 Hook for combining authentication and subscription gating.
 
-## Import
+## Location
 
-```typescript
-import { useAuthGate } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useAuthGate.ts`
 
-```typescript
-function useAuthGate(config?: {
-  requireAuth?: boolean;
-  requireSubscription?: boolean;
-}): {
-  isAuthenticated: boolean;
-  isAuthorized: boolean;
-  user: User | null;
-  subscription: SubscriptionStatus | null;
-  signIn: () => void;
-  signOut: () => void;
-  isLoading: boolean;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `requireAuth` | `boolean` | `false` | Require user to be logged in |
-| `requireSubscription` | `boolean` | `false` | Require premium subscription |
+### Auth Gate Flow
 
-## Returns
+1. **Authentication Check**: Verify if user is authenticated
+2. **Subscription Check**: Verify if user has required subscription
+3. **Authorization Evaluation**: Combine auth + subscription status
+4. **Gate Actions**: Provide functions to gate features
+5. **Sign In Flow**: Trigger authentication when required
+6. **Upgrade Flow**: Trigger subscription when required
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `isAuthenticated` | `boolean` | User is logged in |
-| `isAuthorized` | `boolean` | User meets all requirements |
-| `user` | `User \| null` | Current user object |
-| `subscription` | `SubscriptionStatus \| null` | Subscription status |
-| `signIn` | `() => void` | Trigger sign in |
-| `signOut` | `() => void` | Trigger sign out |
-| `isLoading` | `boolean` | Loading state |
+### Integration Points
 
-## Basic Usage
+- **Auth Context**: User authentication state
+- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
+- **Paywall Domain**: For subscription upgrade flow
+- **Auth UI**: For sign-in/sign-up flows
 
-```typescript
-function ProtectedFeature() {
-  const { isAuthorized, signIn, isLoading } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: true,
-  });
+## Restrictions
 
-  if (isLoading) return <ActivityIndicator />;
+### REQUIRED
 
-  if (!isAuthorized) {
-    return (
-      <View>
-        <Text>This feature requires Premium</Text>
-        <Button onPress={signIn} title="Sign In / Subscribe" />
-      </View>
-    );
-  }
+- **Loading State**: MUST handle loading state
+- **Authorization Check**: MUST verify isAuthorized before showing protected content
+- **Callback Implementation**: MUST implement onAuthRequired/onSubscriptionRequired callbacks
 
-  return <PremiumFeature />;
-}
-```
+### PROHIBITED
 
-## Use Cases
+- **NEVER** show protected content without checking isAuthorized
+- **NEVER** use for security decisions without server validation
+- **DO NOT** assume user is authenticated or subscribed
 
-### Auth Required Only
+### CRITICAL SAFETY
 
-```typescript
-function AuthRequiredComponent() {
-  const { isAuthorized, signIn } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: false,
-  });
+- **ALWAYS** check isAuthorized before showing protected features
+- **NEVER** trust client-side state for security
+- **MUST** implement proper auth flow
+- **ALWAYS** handle all states (loading, authorized, unauthorized)
 
-  if (!isAuthorized) {
-    return (
-      <View>
-        <Text>Please sign in to continue</Text>
-        <Button onPress={signIn} title="Sign In" />
-      </View>
-    );
-  }
+## AI Agent Guidelines
 
-  return <UserDashboard />;
-}
-```
+### When Implementing Auth Gates
 
-### Subscription Required (Auth Implicit)
+1. **Always** check loading state first
+2. **Always** verify isAuthorized before showing content
+3. **Always** provide sign-in option for unauthenticated users
+4. **Always** provide upgrade option for non-subscribed users
+5. **Never** bypass auth checks for convenience
 
-```typescript
-function SubscriptionRequiredComponent() {
-  const { isAuthorized, user, subscription } = useAuthGate({
-    requireAuth: false, // Auto-handles auth internally
-    requireSubscription: true,
-  });
+### Integration Checklist
 
-  if (!isAuthorized) {
-    return (
-      <View>
-        <Text>This feature requires Premium</Text>
-        <Button
-          onPress={() => user ? showPaywall() : signIn()}
-          title={user ? 'Upgrade' : 'Sign In & Subscribe'}
-        />
-      </View>
-    );
-  }
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Configure requireAuth and requireSubscription
+- [ ] Handle loading state
+- [ ] Check isAuthorized before showing content
+- [ ] Implement sign-in callback
+- [ ] Implement subscription upgrade callback
+- [ ] Test with unauthenticated user
+- [ ] Test with authenticated non-subscribed user
+- [ ] Test with authenticated subscribed user
+- [ ] Test loading states
 
-  return <PremiumContent />;
-}
-```
+### Common Patterns
 
-### Both Auth and Subscription Required
+1. **Auth Only**: Require authentication only
+2. **Subscription Only**: Require subscription only (auth handled internally)
+3. **Both**: Require both auth and subscription
+4. **Conditional Gates**: Different requirements per feature
+5. **Nested Gates**: Layer multiple gate conditions
 
-```typescript
-function FullyProtectedFeature() {
-  const {
-    isAuthorized,
-    user,
-    subscription,
-    signIn,
-    isLoading
-  } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: true,
-  });
+## Related Documentation
 
-  if (isLoading) return <LoadingScreen />;
-
-  if (!isAuthorized) {
-    if (!user) {
-      return <SignInPrompt onSignIn={signIn} />;
-    }
-
-    if (!subscription?.isPremium) {
-      return <UpgradePrompt onUpgrade={() => navigation.navigate('Paywall')} />;
-    }
-  }
-
-  return <PremiumContent />;
-}
-```
-
-## Advanced Usage
-
-### Progressive Gating
-
-```typescript
-function ProgressiveAccess() {
-  const { isAuthorized, user, subscription } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: true,
-  });
-
-  // Determine access level
-  const accessLevel = !user
-    ? 'public'
-    : !subscription?.isPremium
-    ? 'authenticated'
-    : 'premium';
-
-  const features = {
-    public: ['Basic Browse'],
-    authenticated: ['Save Favorites', 'View History'],
-    premium: ['Advanced Filters', 'AI Features', 'Priority Support'],
-  };
-
-  return (
-    <FeatureList
-      availableFeatures={features[accessLevel]}
-      onFeatureLocked={(feature) => showUpgradePrompt(feature, accessLevel)}
-    />
-  );
-}
-```
-
-### With Graceful Degradation
-
-```typescript
-function GracefulDegradationComponent() {
-  const { isAuthorized, user, subscription } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: true,
-  });
-
-  if (!isAuthorized) {
-    // Show limited version with upgrade prompt
-    return (
-      <View>
-        <FeatureFreeVersion />
-
-        <View style={styles.upgradeBanner}>
-          <Text>Upgrade to unlock all features</Text>
-          <Button onPress={() => user ? showPaywall() : signIn()} />
-        </View>
-      </View>
-    );
-  }
-
-  return <FullVersion />;
-}
-```
-
-### With Custom Auth Flow
-
-```typescript
-function CustomAuthFlow() {
-  const { isAuthorized, signIn } = useAuthGate({
-    requireAuth: true,
-  });
-
-  const handleSignIn = () => {
-    // Navigate to custom auth flow
-    navigation.navigate('CustomAuth', {
-      onSuccess: () => {
-        // Auth success, callback will trigger re-render
-      },
-    });
-  };
-
-  if (!isAuthorized) {
-    return (
-      <View>
-        <Text>Sign in to access this feature</Text>
-        <Button onPress={handleSignIn} title="Sign In" />
-      </View>
-    );
-  }
-
-  return <ProtectedContent />;
-}
-```
-
-## Integration Examples
-
-### Navigation Guard
-
-```typescript
-function ProtectedScreen() {
-  const { isAuthorized, signIn } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: true,
-  });
-
-  useEffect(() => {
-    if (!isAuthorized) {
-      // Replace navigation instead of just showing UI
-      navigation.replace('AuthGate', {
-        requireAuth: true,
-        requireSubscription: true,
-        returnTo: 'ProtectedScreen',
-      });
-    }
-  }, [isAuthorized]);
-
-  if (!isAuthorized) return null;
-
-  return <ScreenContent />;
-}
-```
-
-### Settings Screen
-
-```typescript
-function SettingsScreen() {
-  const { user, subscription, signIn, signOut } = useAuthGate({
-    requireAuth: true,
-  });
-
-  return (
-  <ScrollView>
-    <Section title="Account">
-      <InfoRow label="Email" value={user?.email} />
-      <InfoRow
-        label="Subscription"
-        value={subscription?.type || 'Free'}
-      />
-    </Section>
-
-    <Section title="Actions">
-      <Button
-        onPress={signIn}
-        title="Sign In"
-      />
-      <Button
-        onPress={signOut}
-        title="Sign Out"
-      />
-    </Section>
-  </ScrollView>
-);
-}
-```
-
-### Content Based on Access Level
-
-```typescript
-function DynamicContent() {
-  const { isAuthorized, user, subscription } = useAuthGate({
-    requireAuth: true,
-    requireSubscription: false,
-  });
-
-  return (
-    <View>
-      {/* Always visible */}
-      <PublicContent />
-
-      {/* Authenticated users */}
-      {user && <AuthenticatedContent />}
-
-      {/* Premium users */}
-      {subscription?.isPremium && <PremiumContent />}
-    </View>
-  );
-}
-```
-
-## Best Practices
-
-1. **Check authorization first** - Before rendering content
-2. **Provide clear messaging** - Tell users what's required
-3. **Easy sign-in flow** - Make authentication simple
-4. **Show upgrade path** - Guide users to subscription
-5. **Handle loading** - Show loading states appropriately
-6. **Cache auth state** - Avoid unnecessary re-authentication
-7. **Sign out cleanup** - Clear sensitive data on sign out
-
-## Testing
-
-```typescript
-describe('useAuthGate', () => {
-  it('should authorize authenticated user', () => {
-    const { result } = renderHook(() =>
-      useAuthGate({ requireAuth: true }),
-      {
-        wrapper: ({ children }) => (
-          <AuthProvider value={{ user: { uid: '123' }}}>
-            {children}
-          </AuthProvider>
-        ),
-      }
-    );
-
-    expect(result.current.isAuthorized).toBe(true);
-  });
-
-  it('should not authorize unauthenticated user', () => {
-    const { result } = renderHook(() =>
-      useAuthGate({ requireAuth: true }),
-      {
-        wrapper: ({ children }) => (
-          <AuthProvider value={{ user: null }}>
-            {children}
-          </AuthProvider>
-        ),
-      }
-    );
-
-    expect(result.current.isAuthorized).toBe(false);
-  });
-
-  it('should authorize premium user', () => {
-    const { result } = renderHook(() =>
-      useAuthGate({ requireSubscription: true }),
-      {
-        wrapper: ({ children }) => (
-          <AuthProvider
-            value={{
-              user: { uid: '123' },
-              subscription: { type: 'premium', isActive: true },
-            }}
-          >
-            {children}
-          </AuthProvider>
-        ),
-      }
-    );
-
-    expect(result.current.isAuthorized).toBe(true);
-  });
-});
-```
-
-## Related Hooks
-
-- **useAuth** - Authentication only
-- **usePremium** - Premium check only
-- **useSubscriptionGate** - Subscription gating
-- **useUserTier** - Tier information
-
-## See Also
-
-- [Auth Integration](../../hooks/useAuthSubscriptionSync.md)
-- [usePremium](./usePremium.md)
-- [useUserTier](./useUserTier.md)
+- **useAuth**: Authentication state
+- **usePremiumGate**: Premium-only gating
+- **useSubscriptionGate**: Subscription-only gating
+- **useFeatureGate**: Unified feature gating
+- **Auth Domain**: `src/domains/config/README.md`