@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/useSubscriptionStatus.md

@@ -2,423 +2,93 @@
 
 Hook for accessing detailed subscription status information.
 
-## Import
+## Location
 
-```typescript
-import { useSubscriptionStatus } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useSubscriptionStatus.ts`
 
-```typescript
-function useSubscriptionStatus(): {
-  status: SubscriptionStatus | null;
-  tier: UserTier;
-  isActive: boolean;
-  isExpired: boolean;
-  willRenew: boolean;
-  expirationDate: Date | null;
-  daysUntilExpiration: number | null;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-}
-```
+**Type**: Hook
 
-## Returns
+## Strategy
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `status` | `SubscriptionStatus \| null` | Full status object |
-| `tier` | `UserTier` | User tier (guest/free/premium) |
-| `isActive` | `boolean` | Subscription is currently active |
-| `isExpired` | `boolean` | Subscription has expired |
-| `willRenew` | `boolean` | Subscription will auto-renew |
-| `expirationDate` | `Date \| null` | When subscription expires |
-| `daysUntilExpiration` | `number \| null` | Days until expiration |
-| `isLoading` | `boolean` | Loading state |
-| `error` | `Error \| null` | Error if any |
+### Subscription Status Flow
 
-## Basic Usage
+1. **Status Fetch**: Retrieve current subscription status from repository
+2. **Status Parsing**: Extract tier, active state, expiration info
+3. **Real-time Updates**: Update when subscription changes
+4. **Expiration Tracking**: Calculate days until expiration
+5. **Renewal Status**: Determine if subscription will auto-renew
+6. **Caching**: Cache status for performance (5 min default)
 
-```typescript
-function SubscriptionStatusDisplay() {
-  const {
-    status,
-    tier,
-    isActive,
-    expirationDate,
-    daysUntilExpiration,
-    isLoading,
-  } = useSubscriptionStatus();
+### Integration Points
 
-  if (isLoading) return <ActivityIndicator />;
+- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
+- **SubscriptionStatus Entity**: `src/domain/entities/README.md`
+- **TanStack Query**: For caching and real-time updates
+- **RevenueCat**: For subscription data source
 
-  return (
-    <View>
-      <Text>Tier: {tier}</Text>
-      <Text>Status: {isActive ? 'Active' : 'Inactive'}</Text>
+## Restrictions
 
-      {expirationDate && (
-        <Text>
-          Expires: {expirationDate.toLocaleDateString()}
-          ({daysUntilExpiration} days)
-        </Text>
-      )}
-    </View>
-  );
-}
-```
+### REQUIRED
 
-## Advanced Usage
+- **Loading State**: MUST handle loading state
+- **Error Handling**: MUST handle error state
+- **Null Check**: MUST handle null status (guest users)
+- **Expiration**: SHOULD warn users before expiration
 
-### With Expiration Warning
+### PROHIBITED
 
-```typescript
-function ExpirationWarning() {
-  const { daysUntilExpiration, willRenew } = useSubscriptionStatus();
+- **NEVER** assume status exists (check for null)
+- **NEVER** use for security decisions without server validation
+- **DO NOT** show expiration for lifetime subscriptions
+- **DO NOT** cache beyond configured time
 
-  if (willRenew) {
-    return <Text>Auto-renewal is on</Text>;
-  }
+### CRITICAL SAFETY
 
-  if (daysUntilExpiration === null) {
-    return null;
-  }
+- **ALWAYS** check if status is null before accessing properties
+- **NEVER** trust client-side status for security
+- **MUST** implement error boundaries
+- **ALWAYS** refresh status when app comes to foreground
 
-  if (daysUntilExpiration <= 3) {
-    return (
-      <WarningCard
-        type={daysUntilExpiration <= 1 ? 'critical' : 'warning'}
-        message={`Your subscription expires in ${daysUntilExpiration} day${daysUntilExpiration > 1 ? 's' : ''}`}
-      />
-    );
-  }
+## AI Agent Guidelines
 
-  if (daysUntilExpiration <= 7) {
-    return <InfoCard message={`Subscription expires in ${daysUntilExpiration} days`} />;
-  }
+### When Displaying Subscription Info
 
-  return null;
-}
-```
+1. **Always** check for null status (guest users)
+2. **Always** handle loading and error states
+3. **Always** show expiration warnings
+4. **Always** display auto-renewal status
+5. **Never** show technical details to end users
 
-### With Status Badge
+### Integration Checklist
 
-```typescript
-function StatusBadge() {
-  const { isActive, isExpired } = useSubscriptionStatus();
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Handle loading state
+- [ ] Handle error state
+- [ ] Check for null status (guest users)
+- [ ] Display subscription tier
+- [ ] Show expiration date
+- [ ] Show days until expiration
+- [ ] Show auto-renewal status
+- [ ] Implement expiration warnings
+- [ ] Test with active subscription
+- [ ] Test with expired subscription
+- [ ] Test with guest user (null status)
 
-  const getStatusConfig = () => {
-    if (isExpired) {
-      return { color: 'red', icon: '⚠️', text: 'Expired' };
-    }
-    if (isActive) {
-      return { color: 'green', icon: '✅', text: 'Active' };
-    }
-    return { color: 'gray', icon: '⏸️', text: 'Inactive' };
-  };
+### Common Patterns
 
-  const config = getStatusConfig();
+1. **Status Badge**: Visual indicator of subscription status
+2. **Expiration Countdown**: Days remaining until expiration
+3. **Warning System**: Notify users before expiration
+4. **Detail Card**: Comprehensive subscription information
+5. **Lifecycle Management**: Handle subscription events
 
-  return (
-    <View style={[styles.badge, { backgroundColor: config.color }]}>
-      <Text>{config.icon}</Text>
-      <Text>{config.text}</Text>
-    </View>
-  );
-}
-```
+## Related Documentation
 
-### With Auto-Refresh
-
-```typescript
-function AutoRefreshStatus() {
-  const { status, refetch, isLoading } = useSubscriptionStatus();
-
-  // Refetch every 5 minutes
-  useEffect(() => {
-    const interval = setInterval(() => {
-      refetch();
-    }, 5 * 60 * 1000);
-
-    return () => clearInterval(interval);
-  }, [refetch]);
-
-  // Refetch when app comes to foreground
-  useFocusEffect(
-    useCallback(() => {
-      refetch();
-    }, [refetch])
-  );
-
-  return (
-    <View>
-      <Text>Status: {status?.type}</Text>
-      <Button
-        onPress={refetch}
-        disabled={isLoading}
-        title="Refresh"
-      />
-    </View>
-  );
-}
-```
-
-### With Detailed Info Card
-
-```typescript
-function DetailedSubscriptionCard() {
-  const {
-    status,
-    tier,
-    isActive,
-    willRenew,
-    expirationDate,
-    daysUntilExpiration,
-  } = useSubscriptionStatus();
-
-  if (!status) return null;
-
-  return (
-    <Card style={styles.card}>
-      <View style={styles.header}>
-        <Badge tier={tier} />
-        <Badge
-          variant={isActive ? 'success' : 'default'}
-          text={isActive ? 'Active' : 'Inactive'}
-        />
-      </View>
-
-      <Divider />
-
-      <View style={styles.section}>
-        <DetailRow
-          label="Plan"
-          value={status.productId?.replace('_', ' ').toUpperCase()}
-        />
-        <DetailRow
-          label="Auto-renew"
-          value={willRenew ? 'Enabled' : 'Disabled'}
-        />
-      </View>
-
-      {expirationDate && (
-        <>
-          <Divider />
-          <View style={styles.section}>
-            <DetailRow
-              label="Expires"
-              value={expirationDate.toLocaleDateString()}
-            />
-            {daysUntilExpiration !== null && (
-              <DetailRow
-                label="Days remaining"
-                value={daysUntilExpiration.toString()}
-              />
-            )}
-          </View>
-        </>
-      )}
-
-      {daysUntilExpiration !== null &&
-        daysUntilExpiration <= 7 && (
-        <Alert
-          severity={daysUntilExpiration <= 3 ? 'warning' : 'info'}
-          message={`Subscription expires in ${daysUntilExpiration} days`}
-        />
-      )}
-    </Card>
-  );
-}
-```
-
-## Examples
-
-### Subscription Countdown
-
-```typescript
-function SubscriptionCountdown() {
-  const { expirationDate, daysUntilExpiration, isActive } =
-    useSubscriptionStatus();
-
-  if (!isActive || !expirationDate) {
-    return null;
-  }
-
-  const [timeLeft, setTimeLeft] = useState('');
-
-  useEffect(() => {
-    const updateCountdown = () => {
-      const now = new Date();
-      const diff = expirationDate.getTime() - now.getTime();
-
-      if (diff <= 0) {
-        setTimeLeft('Expired');
-        return;
-      }
-
-      const days = Math.floor(diff / (1000 * 60 * 60 * 24));
-      const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
-      const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
-
-      setTimeLeft(`${days}d ${hours}h ${minutes}m`);
-    };
-
-    updateCountdown();
-    const interval = setInterval(updateCountdown, 60000); // Every minute
-
-    return () => clearInterval(interval);
-  }, [expirationDate]);
-
-  return (
-    <View style={styles.countdown}>
-      <Text>Expires in:</Text>
-      <Text style={styles.timeLeft}>{timeLeft}</Text>
-    </View>
-  );
-}
-```
-
-### Status History Tracker
-
-```typescript
-function StatusHistoryTracker() {
-  const { status } = useSubscriptionStatus();
-  const previousStatus = useRef(status);
-
-  useEffect(() => {
-    if (previousStatus.current?.type !== status?.type) {
-      analytics.track('subscription_status_changed', {
-        from: previousStatus.current?.type,
-        to: status?.type,
-        timestamp: Date.now(),
-      });
-
-      // Log to database for audit trail
-      logStatusChange(previousStatus.current, status);
-    }
-
-    previousStatus.current = status;
-  }, [status]);
-
-  return null;
-}
-```
-
-### Lifecycle Management
-
-```typescript
-function SubscriptionLifecycleManager() {
-  const { status, isActive, daysUntilExpiration, willRenew } =
-    useSubscriptionStatus();
-
-  useEffect(() => {
-    if (!isActive) {
-      return;
-    }
-
-    // Expiration warning
-    if (daysUntilExpiration === 3) {
-      notifications.send({
-        title: 'Subscription Expiring Soon',
-        body: 'Your subscription expires in 3 days',
-      });
-    }
-
-    // Renewal reminder
-    if (daysUntilExpiration === 1 && !willRenew) {
-      notifications.send({
-        title: 'Last Chance!',
-        body: 'Your subscription expires tomorrow. Renew now to maintain access.',
-      });
-    }
-  }, [daysUntilExpiration, willRenew, isActive]);
-
-  return null;
-}
-```
-
-## State Machine
-
-```typescript
-function SubscriptionStateMachine() {
-  const { status, isActive, isExpired } = useSubscriptionStatus();
-
-  const getState = () => {
-    if (!status) return 'unknown';
-    if (!isActive) return 'inactive';
-    if (isExpired) return 'expired';
-    return 'active';
-  };
-
-  const state = getState();
-
-  switch (state) {
-    case 'unknown':
-      return <LoadingState />;
-    case 'inactive':
-      return <UpgradePrompt />;
-    case 'expired':
-      return <RenewPrompt />;
-    case 'active':
-      return <PremiumContent />;
-    default:
-      return null;
-  }
-}
-```
-
-## Visual Status Indicator
-
-```typescript
-function StatusIndicator() {
-  const { isActive, isExpired, willRenew } = useSubscriptionStatus();
-
-  const getStatusColor = () => {
-    if (isExpired) return '#F44336'; // red
-    if (isActive) return '#4CAF50'; // green
-    return '#9E9E9E'; // gray
-  };
-
-  const getStatusIcon = () => {
-    if (isExpired) return '⚠️';
-    if (isActive && willRenew) return '♻️';
-    if (isActive && !willRenew) return '⏳';
-    return '⏸️';
-  };
-
-  return (
-    <View style={[styles.indicator, { borderColor: getStatusColor() }]}>
-      <Text>{getStatusIcon()}</Text>
-      <ActivityIndicator
-        size={8}
-        color={getStatusColor()}
-        animating={isActive}
-      />
-    </View>
-  );
-}
-```
-
-## Best Practices
-
-1. **Handle null status** - Check if status exists
-2. **Show expiration warnings** - Remind users before expiry
-3. **Display renewal status** - Show if auto-renew is on/off
-4. **Track changes** - Monitor status transitions
-5. **Refresh regularly** - Keep status up to date
-6. **Handle errors** - Show user-friendly error messages
-
-## Related Hooks
-
-- **usePremium** - Simple premium check
-- **useSubscription** - Subscription details
-- **useSubscriptionDetails** - Package and plan info
-- **useUserTier** - Tier information
-
-## See Also
-
-- [SubscriptionStatus Entity](../../domain/entities/README.md)
-- [usePremium](./usePremium.md)
-- [useUserTier](./useUserTier.md)
+- **usePremium**: Simple premium status check
+- **useSubscription**: Detailed subscription information
+- **useSubscriptionDetails**: Package and feature details
+- **useUserTier**: Tier information
+- **SubscriptionStatus Entity**: `src/domain/entities/README.md`
+- **Subscription Repository**: `src/infrastructure/repositories/README.md`