@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/usePremiumWithCredits.md

@@ -2,428 +2,91 @@
 
 Combined hook for premium subscription with credits system integration.
 
-## Import
+## Location
 
-```typescript
-import { usePremiumWithCredits } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/usePremiumWithCredits.ts`
 
-```typescript
-function usePremiumWithCredits(params: {
-  userId: string | undefined;
-  isPremium: boolean;
-}): {
-  credits: number;
-  balance: number;
-  transactions: Transaction[];
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-  ensureCreditsInitialized: () => Promise<void>;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `userId` | `string \| undefined` | **Required** | User ID |
-| `isPremium` | `boolean` | **Required** | Whether user has premium subscription |
+### Premium + Credits Integration
 
-## Returns
+1. **Credits Access**: Provide all credits data from useCredits hook
+2. **Auto-Initialization**: Automatically initialize credits when user becomes premium
+3. **Premium Check**: Monitor isPremium status to trigger initialization
+4. **Duplicate Prevention**: Skip initialization if credits already exist
+5. **Loading Management**: Handle loading state during initialization
+6. **Error Handling**: Handle initialization failures gracefully
 
-Returns all properties from `useCredits` plus:
+### Integration Points
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `ensureCreditsInitialized` | `() => Promise<void>` | Ensure credits are initialized |
+- **useCredits**: For credits balance and transactions
+- **usePremium**: For premium status check
+- **useInitializeCredits**: For credit initialization
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
 
-## Basic Usage
+## Restrictions
 
-```typescript
-function PremiumUserDashboard() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
+### REQUIRED
 
-  const { credits, isLoading, ensureCreditsInitialized } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
+- **User ID**: MUST provide valid userId parameter
+- **Premium Status**: MUST provide isPremium parameter
+- **Loading State**: MUST handle loading state
+- **Error Handling**: MUST handle initialization errors
 
-  useEffect(() => {
-    if (isPremium) {
-      ensureCreditsInitialized();
-    }
-  }, [isPremium]);
+### PROHIBITED
 
-  if (isLoading) return <ActivityIndicator />;
+- **NEVER** call without valid userId
+- **NEVER** call without isPremium parameter
+- **DO NOT** manually manage credits state (use hook values)
+- **DO NOT** call ensureCreditsInitialized excessively
 
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
-      <Text>Status: {isPremium ? 'Premium' : 'Free'}</Text>
-    </View>
-  );
-}
-```
+### CRITICAL SAFETY
 
-## Advanced Usage
+- **ALWAYS** validate userId before use
+- **MUST** handle loading state during initialization
+- **ALWAYS** check isPremium before showing premium features
+- **NEVER** trust client-side state for security
 
-### With Auto-Initialization
+## AI Agent Guidelines
 
-```typescript
-function PremiumCreditsManager() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
+### When Implementing Premium + Credits
 
-  const {
-    credits,
-    transactions,
-    isLoading,
-    ensureCreditsInitialized,
-  } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
+1. **Always** provide valid userId
+2. **Always** provide isPremium status
+3. **Always** handle loading state
+4. **Always** call ensureCreditsInitialized for premium users
+5. **Never** manually initialize credits without checking isPremium
 
-  // Hook automatically initializes credits when user becomes premium
-  useEffect(() => {
-    if (isPremium && !credits) {
-      console.log('User is premium but has no credits, initializing...');
-      ensureCreditsInitialized();
-    }
-  }, [isPremium, credits]);
+### Integration Checklist
 
-  if (isLoading) return <LoadingScreen />;
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide valid userId
+- [ ] Provide isPremium from usePremium
+- [ ] Handle loading state
+- [ ] Call ensureCreditsInitialized when isPremium is true
+- [ ] Test with premium user (no credits)
+- [ ] Test with premium user (has credits)
+- [ ] Test with free user
+- [ ] Test subscription upgrade flow
+- [ ] Test error scenarios
 
-  return (
-    <View>
-      <CreditBalance credits={credits} />
-      <TransactionHistory transactions={transactions} />
-    </View>
-  );
-}
-```
+### Common Patterns
 
-### With Subscription Change Detection
+1. **Auto-Initialization**: Automatically initialize credits for premium users
+2. **Subscription Change Detection**: Detect when user subscribes
+3. **Premium Benefits Display**: Show credits along with premium status
+4. **Subscription Monitor**: Refresh status periodically
+5. **Manual Init**: Provide button for manual initialization
 
-```typescript
-function SubscriptionWatcher() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
+## Related Documentation
 
-  const { credits, ensureCreditsInitialized } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  const previousPremium = useRef(isPremium);
-
-  useEffect(() => {
-    // User just subscribed
-    if (isPremium && !previousPremium.current) {
-      console.log('User subscribed to premium!');
-      ensureCreditsInitialized();
-    }
-
-    previousPremium.current = isPremium;
-  }, [isPremium]);
-
-  return (
-    <View>
-      <Text>Status: {isPremium ? 'Premium' : 'Free'}</Text>
-      <Text>Credits: {credits || 0}</Text>
-    </View>
-  );
-}
-```
-
-### With Manual Initialization
-
-```typescript
-function ManualCreditInit() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-
-  const { credits, isLoading, ensureCreditsInitialized } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  const handleInitializeCredits = async () => {
-    if (!isPremium) {
-      Alert.alert('Premium Required', 'This feature requires a subscription');
-      return;
-    }
-
-    if (credits) {
-      Alert.alert('Already Initialized', 'Credits are already set up');
-      return;
-    }
-
-    await ensureCreditsInitialized();
-    Alert.alert('Success', 'Credits initialized successfully');
-  };
-
-  return (
-    <View>
-      <Text>Credits: {credits || 'Not initialized'}</Text>
-
-      {!credits && isPremium && (
-        <Button
-          onPress={handleInitializeCredits}
-          disabled={isLoading}
-          title="Initialize Credits"
-        />
-      )}
-    </View>
-  );
-}
-```
-
-### With Error Handling
-
-```typescript
-function RobustCreditManager() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-
-  const {
-    credits,
-    error,
-    isLoading,
-    ensureCreditsInitialized,
-  } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  useEffect(() => {
-    if (error) {
-      console.error('Credits error:', error);
-      Alert.alert('Error', 'Failed to load credits');
-    }
-  }, [error]);
-
-  const handleRetry = async () => {
-    try {
-      await ensureCreditsInitialized();
-    } catch (err) {
-      Alert.alert('Error', 'Failed to initialize credits');
-    }
-  };
-
-  if (isLoading) return <LoadingScreen />;
-
-  return (
-    <View>
-      <Text>Credits: {credits || 0}</Text>
-
-      {error && (
-        <Button onPress={handleRetry} title="Retry" />
-      )}
-    </View>
-  );
-}
-```
-
-## Examples
-
-### Premium Onboarding Flow
-
-```typescript
-function PremiumOnboarding() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-
-  const {
-    credits,
-    isLoading,
-    ensureCreditsInitialized,
-  } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  useEffect(() => {
-    // Auto-initialize credits for new premium users
-    if (isPremium && !credits && !isLoading) {
-      const initialize = async () => {
-        await ensureCreditsInitialized();
-        analytics.track('premium_credits_initialized', {
-          userId: user?.uid,
-        });
-      };
-      initialize();
-    }
-  }, [isPremium, credits, isLoading]);
-
-  if (!isPremium) {
-    return <PremiumUpgradePrompt />;
-  }
-
-  if (isLoading) {
-    return <LoadingScreen message="Setting up your account..." />;
-  }
-
-  return (
-    <View>
-      <CongratulationsMessage />
-
-      <CreditCard credits={credits} />
-
-      <Button
-        onPress={() => navigation.navigate('Home')}
-        title="Get Started"
-      />
-    </View>
-  );
-}
-```
-
-### Premium Benefits Display
-
-```typescript
-function PremiumBenefits() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-
-  const { credits, balance, transactions } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  return (
-    <ScrollView>
-      <PremiumBadge />
-
-      <View style={styles.section}>
-        <Text style={styles.title}>Your Premium Benefits</Text>
-        <BenefitItem icon="✓" text="Ad-free experience" />
-        <BenefitItem icon="✓" text="Unlimited access" />
-        <BenefitItem icon="✓" text={`${credits} monthly credits`} />
-        <BenefitItem icon="✓" text="Priority support" />
-      </View>
-
-      <View style={styles.section}>
-        <Text style={styles.title}>Credit Balance</Text>
-        <Text style={styles.balance}>{credits} Credits</Text>
-        <Text style={styles.value}>Worth ~${balance.toFixed(2)}</Text>
-      </View>
-
-      <View style={styles.section}>
-        <Text style={styles.title}>Recent Activity</Text>
-        {transactions.slice(0, 5).map((tx) => (
-          <TransactionItem key={tx.id} transaction={tx} />
-        ))}
-      </View>
-    </ScrollView>
-  );
-}
-```
-
-### Subscription Status Monitor
-
-```typescript
-function SubscriptionMonitor() {
-  const { user } = useAuth();
-  const { isPremium } = usePremium();
-
-  const {
-    credits,
-    isLoading,
-    ensureCreditsInitialized,
-  } = usePremiumWithCredits({
-    userId: user?.uid,
-    isPremium,
-  });
-
-  const [lastChecked, setLastChecked] = useState<Date | null>(null);
-
-  const handleRefresh = async () => {
-    await ensureCreditsInitialized();
-    setLastChecked(new Date());
-  };
-
-  useEffect(() => {
-    // Periodic refresh every 5 minutes
-    const interval = setInterval(() => {
-      if (isPremium) {
-        handleRefresh();
-      }
-    }, 5 * 60 * 1000);
-
-    return () => clearInterval(interval);
-  }, [isPremium]);
-
-  return (
-    <View>
-      <Text>Subscription Status: {isPremium ? 'Active' : 'Inactive'}</Text>
-      <Text>Credits: {credits || 0}</Text>
-      {lastChecked && (
-        <Text>Last checked: {lastChecked.toLocaleTimeString()}</Text>
-      )}
-
-      <Button
-        onPress={handleRefresh}
-        disabled={isLoading}
-        title="Refresh Status"
-      />
-    </View>
-  );
-}
-```
-
-## How It Works
-
-### Automatic Initialization
-
-The hook automatically:
-
-1. **Detects premium status** - Checks if user is premium
-2. **Monitors credits** - Watches credits value
-3. **Initializes when needed** - Calls init if premium but no credits
-4. **Prevents duplicate inits** - Won't initialize if credits exist
-5. **Handles loading** - Shows loading state during initialization
-
-```typescript
-// Premium user without credits
-isPremium = true
-credits = undefined
-→ Auto-initializes credits ✅
-
-// Premium user with credits
-isPremium = true
-credits = 100
-→ No initialization needed ✅
-
-// Free user
-isPremium = false
-credits = undefined
-→ No initialization (not premium) ✅
-```
-
-## Best Practices
-
-1. **Trust the hook** - Let it handle auto-initialization
-2. **Monitor loading** - Show loading during initialization
-3. **Handle errors** - Catch and display init failures
-4. **Track events** - Log credit initialization
-5. **Refresh periodically** - Keep credits up to date
-6. **Check premium first** - Verify user is premium before showing features
-7. **Test scenarios** - Test new subscription, existing subscription, cancellation
-
-## Related Hooks
-
-- **useCredits** - Credits management
-- **useInitializeCredits** - Manual credit initialization
-- **usePremium** - Premium status
-- **useDeductCredit** - Credit deduction
-
-## See Also
-
-- [Credits System](../../../domains/wallet/README.md)
-- [Premium Integration](../../../docs/PREMIUM_INTEGRATION.md)
-- [Credits README](./useCredits.md)
+- **useCredits**: Credits management
+- **useInitializeCredits**: Manual credit initialization
+- **usePremium**: Premium status
+- **useDeductCredit**: Credit deduction
+- **Credits System**: `src/domains/wallet/README.md`
+- **Premium Integration**: `src/docs/PREMIUM_INTEGRATION.md`