@umituz/react-native-subscription 2.15.3 → 2.15.5

package/src/presentation/hooks/useCredits.md.bak

@@ -1,231 +0,0 @@
-# useCredits Hook
-
-Hook for accessing and managing credits balance with real-time updates.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useCredits.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Data Fetching Flow
-
-1. **Initial Load**
-   - Fetch credits from repository on mount
-   - Cache results in TanStack Query
-   - Handle loading/error states
-
-2. **Real-time Updates**
-   - Subscribe to credit changes via repository listener
-   - Auto-update on balance changes
-   - Invalidate query on external modifications
-
-3. **Cache Management**
-   - Use TanStack Query for caching
-   - Background refetch on window focus
-   - Manual refetch capability
-
-### Integration Points
-
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
-- **TanStack Query**: For cache management and background updates
-- **useFocusEffect**: For refresh on screen focus
-
-## Restrictions
-
-### REQUIRED
-
-- **User Authentication**: User MUST be authenticated to access credits
-- **Error Handling**: MUST handle error state in UI
-- **Loading State**: MUST show loading indicator while fetching
-
-### PROHIBITED
-
-- **NEVER** assume credits are available without checking loading state
-- **NEVER** use this hook for unauthenticated users
-- **DO NOT** mutate credits directly - use `useDeductCredit` instead
-- **DO NOT** call refetch excessively (causes unnecessary network calls)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check `isLoading` before displaying credits
-- **ALWAYS** handle `error` state to prevent crashes
-- **NEVER** use `credits` value for security decisions (validate on backend)
-- **MUST** implement error boundaries when displaying balance
-
-## Rules
-
-### Basic Usage
-
-```typescript
-// CORRECT - Handle all states
-function CreditsDisplay() {
-  const { credits, isLoading, error } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-  if (error) return <ErrorDisplay error={error} />;
-
-  return <Text>Credits: {credits}</Text>;
-}
-
-// INCORRECT - No loading check
-function CreditsDisplay() {
-  const { credits } = useCredits();
-  return <Text>Credits: {credits}</Text>; // May show undefined
-}
-
-// INCORRECT - No error handling
-function CreditsDisplay() {
-  const { credits, isLoading, error } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-  return <Text>Credits: {credits}</Text>; // Crashes if error
-}
-```
-
-### Manual Refresh
-
-```typescript
-// CORRECT - Manual refetch with loading state
-function CreditsWithRefresh() {
-  const { credits, refetch, isLoading } = useCredits();
-
-  const handleRefresh = async () => {
-    await refetch();
-  };
-
-  return (
-    <Button onPress={handleRefresh} disabled={isLoading}>
-      Refresh
-    </Button>
-  );
-}
-
-// INCORRECT - Ignore loading state during refresh
-const handleRefresh = () => {
-  refetch(); // No loading indication
-};
-```
-
-### Transaction History
-
-```typescript
-// CORRECT - Display transactions with safety checks
-function CreditsWithHistory() {
-  const { credits, transactions, isLoading } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
-      <FlatList
-        data={transactions || []}
-        keyExtractor={(item) => item.id}
-        renderItem={({ item }) => <TransactionItem {...item} />}
-      />
-    </View>
-  );
-}
-
-// INCORRECT - Assume transactions exist
-<FlatList
-  data={transactions} // Crashes if undefined
-  keyExtractor={(item) => item.id}
-  renderItem={({ item }) => <TransactionItem {...item} />}
-/>
-```
-
-### Auto-Refresh Patterns
-
-```typescript
-// CORRECT - Refresh on focus with effect cleanup
-function AutoRefreshCredits() {
-  const { credits, refetch } = useCredits();
-
-  useFocusEffect(
-    useCallback(() => {
-      refetch();
-    }, [refetch])
-  );
-
-  return <Text>Credits: {credits}</Text>;
-}
-
-// INCORRECT - Missing dependency
-useFocusEffect(
-  useCallback(() => {
-    refetch();
-  }, []) // Missing refetch dependency
-);
-```
-
-### Balance Display
-
-```typescript
-// CORRECT - Safe balance display with formatting
-function BalanceDisplay() {
-  const { credits, balance, isLoading } = useCredits();
-
-  if (isLoading) return <Skeleton />;
-
-  return (
-    <View>
-      <Text>{credits} Credits</Text>
-      <Text>Value: ${(balance || 0).toFixed(2)}</Text>
-    </View>
-  );
-}
-
-// INCORRECT - Unsafe balance access
-<Text>Value: ${balance.toFixed(2)}</Text> // Crashes if undefined
-```
-
-## AI Agent Guidelines
-
-### When Implementing Credit Displays
-
-1. **Always** handle loading state explicitly
-2. **Always** handle error state gracefully
-3. **Always** provide manual refresh option
-4. **Always** format balance safely (handle undefined/null)
-5. **Never** use credits for security decisions (server-side validation required)
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Handle loading state in UI
-- [ ] Handle error state in UI
-- [ ] Provide refresh mechanism
-- [ ] Format balance safely with default values
-- [ ] Implement error boundaries
-- [ ] Test with no credits (zero balance)
-- [ ] Test with loading states
-- [ ] Test with error states
-- [ ] Test refresh functionality
-
-### Common Patterns to Implement
-
-1. **Balance Card**: Display credits with currency conversion
-2. **Transaction List**: Show recent credit activity
-3. **Low Credits Warning**: Alert when balance is low
-4. **Refresh Control**: Pull-to-refresh or button
-5. **Real-time Updates**: Use focus effect for auto-refresh
-6. **Purchase Prompt**: Link to credit packages when low
-7. **Skeletal Loading**: Show skeleton during initial load
-8. **Error Recovery**: Retry mechanism for failed fetches
-
-## Related Documentation
-
-- **useDeductCredit**: Deduct credits from balance
-- **useCreditChecker**: Check credit availability before operations
-- **useInitializeCredits**: Initialize credits after purchase
-- **useCreditsGate**: Gate features behind credit requirements
-- **useFeatureGate**: Unified feature gating with credits
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
-- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useFeatureGate.md.bak

@@ -1,284 +0,0 @@
-# useFeatureGate Hook
-
-Unified feature gate combining authentication, subscription, and credits checks.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useFeatureGate.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Progressive Access Control
-
-1. **Authentication Check**
-   - Verify user is authenticated
-   - Show auth modal if not authenticated
-   - Queue pending action for post-auth execution
-
-2. **Subscription Check**
-   - Verify user has required subscription tier
-   - Show paywall if subscription insufficient
-   - Bypass credit check for premium users
-
-3. **Credit Check**
-   - Verify sufficient credit balance
-   - Show purchase prompt if insufficient
-   - Deduct credits only after all checks pass
-
-4. **Action Execution**
-   - Execute gated action only if all checks pass
-   - Handle failures gracefully
-   - Update UI state appropriately
-
-### Integration Points
-
-- **useAuth**: For authentication state
-- **usePremium**: For subscription status
-- **useCredits**: For credit balance
-- **useDeductCredit**: For credit deduction
-- **Auth Modals**: Custom authentication UI
-- **Paywall Components**: Upgrade prompts
-
-## Restrictions
-
-### REQUIRED
-
-- **Authentication Check**: MUST implement `onShowAuthModal` callback
-- **Paywall Handler**: MUST implement `onShowPaywall` callback
-- **Credit Validation**: MUST check `hasCredits` before allowing actions
-- **State Management**: MUST respect `canAccess` boolean
-
-### PROHIBITED
-
-- **NEVER** bypass authentication check for sensitive features
-- **NEVER** show feature gate if user has access (confusing UX)
-- **NEVER** execute action without checking all gates first
-- **DO NOT** hardcode gate logic (use hook parameters)
-- **NEVER** deduct credits without checking subscription status first
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check gates in order: Auth → Subscription → Credits
-- **ALWAYS** provide clear messaging about why access is denied
-- **ALWAYS** preserve user intent through auth/purchase flows
-- **NEVER** trust client-side gate for security (server-side validation required)
-- **MUST** implement proper error boundaries around gated actions
-
-## Rules
-
-### Basic Feature Gating
-
-```typescript
-// CORRECT - All gates with clear messaging
-function PremiumFeature() {
-  const { requireFeature, canAccess, isAuthenticated, hasSubscription, hasCredits } =
-    useFeatureGate({
-      isAuthenticated: !!user,
-      onShowAuthModal: (pendingAction) => {
-        navigation.navigate('Auth', { pendingAction });
-      },
-      hasSubscription: isPremium,
-      hasCredits: credits >= 5,
-      creditBalance: credits,
-      requiredCredits: 5,
-      onShowPaywall: (required) => {
-        if (!isAuthenticated) return;
-        if (!hasSubscription) showPaywall();
-        else showCreditPurchase(required);
-      },
-    });
-
-  const handleAction = () => {
-    requireFeature(async () => {
-      await executeFeature();
-    });
-  };
-
-  return (
-    <Button
-      onPress={handleAction}
-      title={!canAccess ? 'Unlock Feature' : 'Execute'}
-    />
-  );
-}
-
-// INCORRECT - Missing auth callback
-const { requireFeature } = useFeatureGate({
-  isAuthenticated: !!user,
-  // Missing onShowAuthModal
-  hasSubscription: isPremium,
-  hasCredits: credits >= 5,
-  creditBalance: credits,
-  onShowPaywall: showPaywall,
-});
-
-// INCORRECT - No access check
-const handleAction = () => {
-  requireFeature(() => executeFeature());
-};
-// Always shows button, even if user can't access
-```
-
-### Progressive Access Control
-
-```typescript
-// CORRECT - Show appropriate message for each gate
-function ProgressiveGate() {
-  const { canAccess, isAuthenticated, hasSubscription, hasCredits } = useFeatureGate({
-    isAuthenticated: !!user,
-    onShowAuthModal: (pending) => showAuthModal({ pendingAction: pending }),
-    hasSubscription: isPremium,
-    hasCredits: credits >= 3,
-    creditBalance: credits,
-    requiredCredits: 3,
-    onShowPaywall: (required) => showUpgradeModal({ requiredCredits: required }),
-  });
-
-  const getAccessMessage = () => {
-    if (!isAuthenticated) return 'Sign in to access';
-    if (!hasSubscription && !hasCredits) return 'Upgrade or purchase credits';
-    if (!hasCredits) return `Need ${requiredCredits} credits`;
-    return 'Full access';
-  };
-
-  return (
-    <View>
-      <Text>{getAccessMessage()}</Text>
-      <Button
-        onPress={() => requireFeature(() => executeAction())}
-        disabled={!canAccess}
-        title={canAccess ? 'Execute' : 'Unlock'}
-      />
-    </View>
-  );
-}
-
-// INCORRECT - Generic message for all gates
-if (!canAccess) {
-  return <Text>You cannot access this feature</Text>;
-}
-// Doesn't tell user what they need to do
-```
-
-### Premium Bypass Logic
-
-```typescript
-// CORRECT - Premium users bypass credit check
-function PremiumBypass() {
-  const { requireFeature } = useFeatureGate({
-    isAuthenticated: !!user,
-    onShowAuthModal: (pending) => showAuthModal({ pendingAction: pending }),
-    hasSubscription: isPremium,
-    hasCredits: isPremium ? true : credits >= 5,
-    creditBalance: credits,
-    requiredCredits: isPremium ? 0 : 5,
-    onShowPaywall: (required) => {
-      if (isPremium) {
-        showInsufficientCreditsModal(required);
-      } else {
-        showPaywall();
-      }
-    },
-  });
-
-  return <Button onPress={() => requireFeature(executeAction)} />;
-}
-
-// INCORRECT - Charges premium users for credits
-hasCredits: credits >= 5, // Even if isPremium is true
-requiredCredits: 5, // Charges premium users
-```
-
-### Callback Implementation
-
-```typescript
-// CORRECT - Proper auth modal with pending action
-onShowAuthModal: (pendingAction) => {
-  navigation.navigate('Auth', {
-    onAuthSuccess: pendingAction,
-  });
-}
-
-// CORRECT - Context-aware paywall
-onShowPaywall: (requiredCredits) => {
-  if (isPremium) {
-    // Already premium, need credits
-    showCreditPurchaseModal({ requiredCredits });
-  } else {
-    // Not premium, show subscription
-    showSubscriptionPaywall();
-  }
-}
-
-// INCORRECT - No pending action preservation
-onShowAuthModal: () => {
-  navigation.navigate('Auth');
-  // User's intent is lost
-}
-```
-
-### Action Gating
-
-```typescript
-// CORRECT - Gate action execution
-const handleGenerate = () => {
-  requireFeature(async () => {
-    // Only runs if all gates pass
-    const result = await generateContent();
-    showResult(result);
-  });
-};
-
-// INCORRECT - Execute action before gating
-const handleGenerate = async () => {
-  const result = await generateContent(); // Runs regardless!
-  requireFeature(() => showResult(result));
-};
-```
-
-## AI Agent Guidelines
-
-### When Implementing Feature Gates
-
-1. **Always** check gates in order: Auth → Subscription → Credits
-2. **Always** provide clear, specific messaging for each gate
-3. **Always** preserve user intent through auth/purchase flows
-4. **Always** bypass credit check for premium users (if applicable)
-5. **Never** trust client-side gates for security (server validation required)
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Implement `onShowAuthModal` with pending action preservation
-- [ ] Implement `onShowPaywall` with context-aware messaging
-- [ ] Check `canAccess` before showing feature
-- [ ] Provide appropriate messaging for each gate state
-- [ ] Respect premium status (bypass credit check if needed)
-- [ ] Test all gate combinations (auth, subscription, credits)
-- [ ] Test pending action execution after auth/purchase
-- [ ] Implement error boundaries around gated actions
-
-### Common Patterns to Implement
-
-1. **Progressive Unlocking**: Show upgrade path for each gate
-2. **Smart Paywalls**: Show subscription OR credits based on user state
-3. **Intent Preservation**: Queue actions through auth/purchase flows
-4. **Clear Messaging**: Tell users exactly what's required
-5. **Premium Bypass**: Skip credit check for premium users
-6. **Access Indicators**: Show lock/unlock status in UI
-7. **Graceful Degradation**: Show limited version for free users
-8. **Analytics Tracking**: Monitor gate triggers and conversions
-
-## Related Documentation
-
-- **useAuthGate**: Authentication gating only
-- **useSubscriptionGate**: Subscription gating only
-- **useCreditsGate**: Credits gating only
-- **usePremiumGate**: Premium feature gating
-- **useDeductCredit**: Credit deduction after gate passes
-- **Feature Gating**: `../../../docs/FEATURE_GATING.md`
-- **Access Control**: `../../../docs/ACCESS_PATTERNS.md`