@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/presentation/hooks/useSubscription.md

@@ -2,449 +2,93 @@
 
 Core hook for subscription status management and operations.
 
-## Import
+## Location
 
-```typescript
-import { useSubscription } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useSubscription.ts`
 
-```typescript
-function useSubscription(): {
-  status: SubscriptionStatus | null;
-  loading: boolean;
-  error: string | null;
-  isPremium: boolean;
-  loadStatus: (userId: string) => Promise<void>;
-  refreshStatus: (userId: string) => Promise<void>;
-  activateSubscription: (
-    userId: string,
-    productId: string,
-    expiresAt: string | null,
-  ) => Promise<void>;
-  deactivateSubscription: (userId: string) => Promise<void>;
-}
-```
+**Type**: Hook
 
-## Returns
+## Strategy
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `status` | `SubscriptionStatus \| null` | Current subscription status object |
-| `loading` | `boolean` | Loading state |
-| `error` | `string \| null` | Error message if any |
-| `isPremium` | `boolean` | Whether user has active subscription |
-| `loadStatus` | `(userId) => Promise<void>` | Load subscription status |
-| `refreshStatus` | `(userId) => Promise<void>` | Refresh subscription status |
-| `activateSubscription` | `(userId, productId, expiresAt) => Promise<void>` | Activate subscription |
-| `deactivateSubscription` | `(userId) => Promise<void>` | Deactivate subscription |
+### Subscription Management Flow
 
-## Basic Usage
+1. **Status Retrieval**: Fetch current subscription status from repository
+2. **State Caching**: Cache status for 5 minutes using TanStack Query
+3. **Real-time Updates**: Auto-refresh when user auth state changes
+4. **Manual Operations**: Provide functions for manual activation/deactivation
+5. **Loading States**: Handle loading and error states properly
+6. **Refresh Mechanisms**: Support both load and refresh operations
 
-```typescript
-function SubscriptionStatus() {
-  const { user } = useAuth();
-  const { status, isPremium, loading, loadStatus } = useSubscription();
+### Integration Points
 
-  useEffect(() => {
-    if (user?.uid) {
-      loadStatus(user.uid);
-    }
-  }, [user]);
+- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
+- **TanStack Query**: For caching and background updates
+- **Auth Context**: Sync with user authentication state
+- **RevenueCat**: For subscription data source
 
-  if (loading) return <ActivityIndicator />;
+## Restrictions
 
-  return (
-    <View>
-      <Text>Status: {isPremium ? 'Premium' : 'Free'}</Text>
-      {status && (
-        <Text>Product: {status.productId}</Text>
-      )}
-    </View>
-  );
-}
-```
+### REQUIRED
 
-## Advanced Usage
+- **User ID**: MUST provide valid userId for operations
+- **Loading State**: MUST handle loading state in UI
+- **Error Handling**: MUST handle error state
+- **Status Check**: MUST verify isPremium before showing premium features
 
-### With Auto-Refresh
+### PROHIBITED
 
-```typescript
-function SubscriptionWithRefresh() {
-  const { user } = useAuth();
-  const { status, isPremium, loading, refreshStatus } = useSubscription();
+- **NEVER** assume instant data availability (always check loading state)
+- **NEVER** use for security decisions without server validation
+- **DO NOT** call loadStatus/refreshStatus without userId
+- **DO NOT** activate/deactivate subscriptions without proper validation
 
-  useEffect(() => {
-    if (user?.uid) {
-      refreshStatus(user.uid);
-    }
-  }, [user]);
+### CRITICAL SAFETY
 
-  // Refresh when app comes to foreground
-  useFocusEffect(
-    useCallback(() => {
-      if (user?.uid) {
-        refreshStatus(user.uid);
-      }
-    }, [user])
-  );
+- **ALWAYS** check loading state before accessing status
+- **NEVER** trust client-side state for security enforcement
+- **MUST** validate userId before all operations
+- **ALWAYS** handle errors gracefully
 
-  // Refresh every 5 minutes
-  useEffect(() => {
-    const interval = setInterval(() => {
-      if (user?.uid) {
-        refreshStatus(user.uid);
-      }
-    }, 5 * 60 * 1000);
+## AI Agent Guidelines
 
-    return () => clearInterval(interval);
-  }, [user]);
+### When Implementing Subscription Features
 
-  if (loading) return <LoadingScreen />;
+1. **Always** check loading state before rendering subscription data
+2. **Always** handle error state
+3. **Always** verify isPremium before showing premium features
+4. **Always** validate userId before operations
+5. **Never** use for security decisions without server validation
 
-  return (
-    <View>
-      <Text>{isPremium ? 'Premium' : 'Free'} User</Text>
-    </View>
-  );
-}
-```
+### Integration Checklist
 
-### With Manual Activation
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Handle loading state
+- [ ] Handle error state
+- [ ] Check isPremium before rendering premium content
+- [ ] Validate userId before operations
+- [ ] Implement refresh mechanism
+- [ ] Test with premium user
+- [ ] Test with free user
+- [ ] Test with guest user
+- [ ] Test offline scenario
 
-```typescript
-function SubscriptionManager() {
-  const { user } = useAuth();
-  const {
-    status,
-    activateSubscription,
-    deactivateSubscription,
-    loading,
-  } = useSubscription();
+### Common Patterns
 
-  const handleActivate = async () => {
-    if (!user?.uid) return;
+1. **Status Display**: Show current subscription status
+2. **Conditional Rendering**: Show/hide features based on isPremium
+3. **Manual Refresh**: Provide refresh button for users
+4. **Auto-refresh**: Refresh on screen focus or app foreground
+5. **Status Polling**: Periodic refresh for real-time updates
+6. **Purchase Completion**: Refresh after successful purchase
+7. **Error Recovery**: Provide retry mechanism on failure
 
-    try {
-      await activateSubscription(
-        user.uid,
-        'premium_monthly',
-        new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
-      );
-      Alert.alert('Success', 'Subscription activated');
-    } catch (error) {
-      Alert.alert('Error', 'Failed to activate subscription');
-    }
-  };
+## Related Documentation
 
-  const handleDeactivate = async () => {
-    if (!user?.uid) return;
-
-    try {
-      await deactivateSubscription(user.uid);
-      Alert.alert('Success', 'Subscription deactivated');
-    } catch (error) {
-      Alert.alert('Error', 'Failed to deactivate subscription');
-    }
-  };
-
-  return (
-    <View>
-      <Text>Status: {status?.type || 'None'}</Text>
-
-      <Button
-        onPress={handleActivate}
-        disabled={loading}
-        title="Activate Subscription"
-      />
-
-      <Button
-        onPress={handleDeactivate}
-        disabled={loading || !status}
-        title="Deactivate Subscription"
-      />
-    </View>
-  );
-}
-```
-
-### With Error Handling
-
-```typescript
-function RobustSubscription() {
-  const { user } = useAuth();
-  const { status, error, loading, loadStatus } = useSubscription();
-
-  useEffect(() => {
-    if (user?.uid) {
-      loadStatus(user.uid).catch((err) => {
-        console.error('Failed to load subscription:', err);
-      });
-    }
-  }, [user]);
-
-  useEffect(() => {
-    if (error) {
-      Alert.alert(
-        'Subscription Error',
-        error,
-        [{ text: 'Retry', onPress: () => user && loadStatus(user.uid) }]
-      );
-    }
-  }, [error]);
-
-  if (loading) return <LoadingScreen />;
-
-  return (
-    <View>
-      {error ? (
-        <ErrorBanner message={error} />
-      ) : (
-        <SubscriptionDisplay status={status} />
-      )}
-    </View>
-  );
-}
-```
-
-### With Status Polling
-
-```typescript
-function PollingSubscription() {
-  const { user } = useAuth();
-  const { status, refreshStatus, loading } = useSubscription();
-
-  const [isPolling, setIsPolling] = useState(false);
-
-  useEffect(() => {
-    if (!user?.uid) return;
-
-    // Initial load
-    refreshStatus(user.uid);
-
-    // Poll for status updates
-    const interval = setInterval(async () => {
-      if (!isPolling) {
-        setIsPolling(true);
-        try {
-          await refreshStatus(user.uid);
-        } finally {
-          setIsPolling(false);
-        }
-      }
-    }, 30000); // Every 30 seconds
-
-    return () => clearInterval(interval);
-  }, [user]);
-
-  return (
-    <View>
-      <Text>Status: {status?.type || 'Loading...'}</Text>
-      {loading && <ActivityIndicator size="small" />}
-    </View>
-  );
-}
-```
-
-## Examples
-
-### Complete Subscription Dashboard
-
-```typescript
-function SubscriptionDashboard() {
-  const { user } = useAuth();
-  const {
-    status,
-    isPremium,
-    loading,
-    error,
-    refreshStatus,
-  } = useSubscription();
-
-  useEffect(() => {
-    if (user?.uid) {
-      refreshStatus(user.uid);
-    }
-  }, [user]);
-
-  useFocusEffect(
-    useCallback(() => {
-      if (user?.uid) {
-        refreshStatus(user.uid);
-      }
-    }, [user])
-  );
-
-  if (loading) {
-    return <LoadingScreen />;
-  }
-
-  return (
-    <ScrollView>
-      {error && <ErrorBanner message={error} />}
-
-      <SubscriptionCard
-        status={status}
-        isPremium={isPremium}
-      />
-
-      {status && (
-        <>
-          <DetailRow
-            label="Product ID"
-            value={status.productId}
-          />
-          <DetailRow
-            label="Status"
-            value={status.isActive ? 'Active' : 'Inactive'}
-          />
-          {status.expirationDate && (
-            <DetailRow
-              label="Expires"
-              value={new Date(status.expirationDate).toLocaleDateString()}
-            />
-          )}
-        </>
-      )}
-
-      <Button
-        onPress={() => user && refreshStatus(user.uid)}
-        title="Refresh Status"
-      />
-    </ScrollView>
-  );
-}
-```
-
-### Subscription State Machine
-
-```typescript
-function SubscriptionStateMachine() {
-  const { user } = useAuth();
-  const { status, loading, isPremium } = useSubscription();
-
-  useEffect(() => {
-    if (user?.uid) {
-      loadStatus(user.uid);
-    }
-  }, [user]);
-
-  const getState = () => {
-    if (loading) return 'loading';
-    if (!status) return 'none';
-    if (!status.isActive) return 'expired';
-    if (isPremium) return 'active';
-    return 'inactive';
-  };
-
-  const state = getState();
-
-  switch (state) {
-    case 'loading':
-      return <LoadingScreen />;
-    case 'none':
-      return <EmptyState message="No subscription found" />;
-    case 'expired':
-      return <ExpiredState onRenew={() => navigation.navigate('Paywall')} />;
-    case 'active':
-      return <PremiumContent />;
-    default:
-      return <FreeContent />;
-  }
-}
-```
-
-### With Analytics Tracking
-
-```typescript
-function TrackedSubscription() {
-  const { user } = useAuth();
-  const { status, isPremium, loading, loadStatus } = useSubscription();
-
-  const previousStatus = useRef(status);
-
-  useEffect(() => {
-    if (user?.uid) {
-      loadStatus(user.uid);
-    }
-  }, [user]);
-
-  useEffect(() => {
-    // Track subscription status changes
-    if (previousStatus.current?.isActive !== status?.isActive) {
-      analytics.track('subscription_status_changed', {
-        from: previousStatus.current?.isActive,
-        to: status?.isActive,
-        userId: user?.uid,
-      });
-    }
-
-    if (previousStatus.current?.type !== status?.type) {
-      analytics.track('subscription_type_changed', {
-        from: previousStatus.current?.type,
-        to: status?.type,
-        userId: user?.uid,
-      });
-    }
-
-    previousStatus.current = status;
-  }, [status]);
-
-  if (loading) return <LoadingScreen />;
-
-  return (
-    <View>
-      <Text>Status: {isPremium ? 'Premium' : 'Free'}</Text>
-    </View>
-  );
-}
-```
-
-## Best Practices
-
-1. **Validate user ID** - Always check userId before operations
-2. **Handle loading** - Show loading states appropriately
-3. **Handle errors** - Display user-friendly error messages
-4. **Refresh on focus** - Update when screen regains focus
-5. **Auto-load** - Load status when user changes
-6. **Track changes** - Monitor status transitions
-7. **Cache wisely** - Don't over-refresh
-
-## Common Patterns
-
-### Basic Load
-
-```typescript
-const { status, loadStatus } = useSubscription();
-useEffect(() => {
-  if (user?.uid) loadStatus(user.uid);
-}, [user]);
-```
-
-### With Refresh
-
-```typescript
-const { status, refreshStatus } = useSubscription();
-const handleRefresh = () => user && refreshStatus(user.uid);
-```
-
-### Manual Activation
-
-```typescript
-const { activateSubscription } = useSubscription();
-await activateSubscription(userId, productId, expiresAt);
-```
-
-## Related Hooks
-
-- **usePremium** - Simplified premium checking
-- **useSubscriptionStatus** - Detailed subscription status
-- **useSubscriptionDetails** - Package and pricing info
-- **useUserTier** - Tier information
-
-## See Also
-
-- [Subscription Entity](../../domain/entities/SubscriptionStatus.md)
-- [Subscription Service](../../infrastructure/services/SubscriptionService.md)
-- [Status Utilities](../../utils/subscriptionUtils.md)
+- **usePremium**: Simplified premium checking
+- **useSubscriptionStatus**: Detailed subscription status
+- **useSubscriptionDetails**: Package and pricing info
+- **useUserTier**: Tier information
+- **Subscription Repository**: `src/infrastructure/repositories/README.md`
+- **Domain Layer**: `src/domain/README.md`