@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/presentation/hooks/useCreditChecker.md

@@ -1,407 +1,102 @@
 # useCreditChecker Hook
 
-Provides credit checking utilities with dedicated repository integration.
+Simple hook for checking if user has sufficient credits before operations.
 
-## Import
+## Location
 
-```typescript
-import { useCreditChecker } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useCreditChecker.ts`
 
-```typescript
-function useCreditChecker(params?: {
-  onCreditDeducted?: (userId: string, cost: number) => void;
-}): {
-  checkCreditsAvailable: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<CreditCheckResult>;
-  deductCreditsAfterSuccess: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<void>;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `onCreditDeducted` | `(userId, cost) => void` | `undefined` | Callback after successful deduction |
+### Credit Validation Flow
 
-## Returns
+1. **Initial Check**
+   - Compare current balance against required amount
+   - Return boolean result immediately
+   - No network calls required (uses cached balance)
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `checkCreditsAvailable` | `(userId, cost?) => Promise<CreditCheckResult>` | Check if user has enough credits |
-| `deductCreditsAfterSuccess` | `(userId, cost?) => Promise<void>` | Deduct after successful operation |
+2. **Real-time Updates**
+   - Automatically re-checks when credits change
+   - Updates result via `useCredits` hook
+   - Triggers re-renders on balance changes
 
-## CreditCheckResult
+3. **Manual Refresh**
+   - Optionally trigger manual credit check
+   - Useful before expensive operations
+   - Validates current state before action
 
-```typescript
-interface CreditCheckResult {
-  hasCredits: boolean;
-  currentBalance: number;
-  required: number;
-  canProceed: boolean;
-}
-```
+### Integration Points
 
-## Basic Usage
+- **useCredits**: For fetching current credit balance
+- **useDeductCredit**: For deducting credits after check
+- **Credit Checking UI**: Pre-action validation displays
+- **Purchase Flows**: Redirect to credit packages
 
-```typescript
-function CreditFeature() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable } = useCreditChecker();
+## Restrictions
 
-  const handleUseFeature = async () => {
-    const result = await checkCreditsAvailable(user?.uid, 5);
+### REQUIRED
 
-    if (!result.canProceed) {
-      Alert.alert(
-        'Insufficient Credits',
-        `You need ${result.required} credits but only have ${result.currentBalance}`
-      );
-      return;
-    }
+- **Required Amount**: MUST specify positive credit cost
+- **Balance Check**: MUST verify `hasEnoughCredits` before action
+- **User Feedback**: MUST show credit cost to user
 
-    // Proceed with feature
-    await executeFeature();
-  };
+### PROHIBITED
 
-  return <Button onPress={handleUseFeature} title="Use Feature (5 credits)" />;
-}
-```
+- **NEVER** assume credits are sufficient without checking
+- **NEVER** use for security decisions (server-side validation required)
+- **DO NOT** deduct credits with this hook (use `useDeductCredit`)
+- **NEVER** hardcode credit costs (should be configurable)
 
-## Advanced Usage
+### CRITICAL SAFETY
 
-### With Deduction Callback
+- **ALWAYS** check return value before proceeding with action
+- **ALWAYS** show credit cost to user before execution
+- **NEVER** trust client-side check for security (server must validate)
+- **MUST** handle case where credits become insufficient between check and action
 
-```typescript
-function CreditWithCallback() {
-  const { user } = useAuth();
+## AI Agent Guidelines
 
-  const { checkCreditsAvailable } = useCreditChecker({
-    onCreditDeducted: (userId, cost) => {
-      console.log(`Deducted ${cost} credits from ${userId}`);
-      analytics.track('credits_deducted', { userId, cost });
-    },
-  });
+### When Implementing Credit Checks
 
-  const handleAction = async () => {
-    const result = await checkCreditsAvailable(user?.uid, 3);
+1. **Always** specify positive credit cost
+2. **Always** check `hasEnoughCredits` before action
+3. **Always** show credit cost to user in UI
+4. **Always** provide upgrade path when insufficient
+5. **Never** use for security decisions (server validation required)
 
-    if (!result.canProceed) {
-      showPaywall();
-      return;
-    }
+### Integration Checklist
 
-    await performAction();
-  };
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Specify positive credit cost
+- [ ] Check `hasEnoughCredits` before action
+- [ ] Display credit cost to user
+- [ ] Show upgrade/purchase option when insufficient
+- [ ] Validate credit cost is positive number
+- [ ] Test with sufficient credits
+- [ ] Test with insufficient credits
+- [ ] Test with zero credits
+- [ ] Test credit changes between check and action
 
-  return <Button onPress={handleAction} title="Execute (3 credits)" />;
-}
-```
+### Common Patterns to Implement
 
-### With Two-Step Process
+1. **Pre-action Validation**: Check before showing button
+2. **Cost Display**: Always show credit cost to user
+3. **Upgrade Prompts**: Link to credit packages when low
+4. **Manual Refresh**: Check again before expensive operations
+5. **Credit Deduction**: Use with `useDeductCredit` for complete flow
+6. **Visual Feedback**: Disable buttons when insufficient
+7. **Warning Messages**: Alert user before high-cost operations
+8. **Balance Display**: Show current balance alongside cost
 
-```typescript
-function TwoStepCreditProcess() {
-  const { user } = useAuth();
+## Related Documentation
 
-  const {
-    checkCreditsAvailable,
-    deductCreditsAfterSuccess,
-  } = useCreditChecker();
-
-  const handleProcess = async () => {
-    // Step 1: Check credits
-    const check = await checkCreditsAvailable(user?.uid, 10);
-
-    if (!check.canProceed) {
-      Alert.alert('Insufficient Credits', 'You need 10 credits for this operation');
-      return;
-    }
-
-    try {
-      // Step 2: Perform operation
-      const result = await expensiveOperation();
-
-      // Step 3: Deduct credits only after success
-      await deductCreditsAfterSuccess(user?.uid, 10);
-
-      Alert.alert('Success', 'Operation completed!');
-    } catch (error) {
-      Alert.alert('Error', 'Operation failed, credits not deducted');
-    }
-  };
-
-  return <Button onPress={handleProcess} title="Process (10 credits)" />;
-}
-```
-
-### With Pre-Check UI
-
-```typescript
-function CreditPreCheck() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable } = useCreditChecker();
-
-  const [creditCheck, setCreditCheck] = useState<CreditCheckResult | null>(null);
-
-  useEffect(() => {
-    // Pre-check on mount
-    checkCreditsAvailable(user?.uid, 5).then(setCreditCheck);
-  }, [user]);
-
-  if (!creditCheck) return <ActivityIndicator />;
-
-  return (
-    <View>
-      <Text>Required: {creditCheck.required} credits</Text>
-      <Text>Balance: {creditCheck.currentBalance} credits</Text>
-
-      {creditCheck.canProceed ? (
-        <Button
-          onPress={() => executeAction()}
-          title="Proceed"
-        />
-      ) : (
-        <Button
-          onPress={() => showPaywall()}
-          title="Get More Credits"
-        />
-      )}
-    </View>
-  );
-}
-```
-
-### With Cost Estimation
-
-```typescript
-function CostEstimator() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable } = useCreditChecker();
-
-  const estimateCost = (itemCount: number) => {
-    return Math.ceil(itemCount / 10); // 1 credit per 10 items
-  };
-
-  const handleExport = async (items: any[]) => {
-    const cost = estimateCost(items.length);
-    const result = await checkCreditsAvailable(user?.uid, cost);
-
-    if (!result.canProceed) {
-      Alert.alert(
-        'Insufficient Credits',
-        `Exporting ${items.length} items costs ${cost} credits. You have ${result.currentBalance}.`
-      );
-      return;
-    }
-
-    await exportItems(items);
-    await deductCreditsAfterSuccess(user?.uid, cost);
-  };
-
-  return (
-    <FlatList
-      data={items}
-      renderItem={({ item }) => <ItemRow item={item} />}
-      ListHeaderComponent={
-        <Button
-          onPress={() => handleExport(selectedItems)}
-          title={`Export (${estimateCost(selectedItems.length)} credits)`}
-        />
-      }
-    />
-  );
-}
-```
-
-## Examples
-
-### AI Generation with Credits
-
-```typescript
-function AIGeneration() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable, deductCreditsAfterSuccess } = useCreditChecker({
-    onCreditDeducted: (userId, cost) => {
-      analytics.track('ai_generation_completed', { userId, cost });
-    },
-  });
-
-  const creditsNeeded = 5;
-
-  const handleGenerate = async () => {
-    // Check if user has enough credits
-    const check = await checkCreditsAvailable(user?.uid, creditsNeeded);
-
-    if (!check.canProceed) {
-      Alert.alert(
-        'Insufficient Credits',
-        `You need ${creditsNeeded} credits to generate. Current balance: ${check.currentBalance}`,
-        [
-          { text: 'Cancel' },
-          { text: 'Get Credits', onPress: () => navigation.navigate('CreditPackages') },
-        ]
-      );
-      return;
-    }
-
-    try {
-      // Show loading
-      setGenerating(true);
-
-      // Generate AI content
-      const result = await callAIGenerationAPI(prompt);
-
-      // Only deduct credits after successful generation
-      await deductCreditsAfterSuccess(user?.uid, creditsNeeded);
-
-      setContent(result);
-    } catch (error) {
-      Alert.alert('Error', 'Failed to generate content');
-    } finally {
-      setGenerating(false);
-    }
-  };
-
-  return (
-    <View>
-      <Text>Credits needed: {creditsNeeded}</Text>
-      <Button
-        onPress={handleGenerate}
-        disabled={generating}
-        title={generating ? 'Generating...' : `Generate (${creditsNeeded} credits)`}
-      />
-    </View>
-  );
-}
-```
-
-### Batch Operations
-
-```typescript
-function BatchOperations() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable, deductCreditsAfterSuccess } = useCreditChecker();
-
-  const handleBatchProcess = async (items: Item[]) => {
-    const cost = items.length; // 1 credit per item
-
-    const check = await checkCreditsAvailable(user?.uid, cost);
-
-    if (!check.canProceed) {
-      Alert.alert(
-        'Insufficient Credits',
-        `Processing ${items.length} items requires ${cost} credits. You have ${check.currentBalance}.`,
-        [
-          { text: 'Cancel' },
-          {
-            text: 'Get Credits',
-            onPress: () => navigation.navigate('CreditPackages', { required: cost }),
-          },
-        ]
-      );
-      return;
-    }
-
-    // Confirm before proceeding
-    Alert.alert(
-      'Confirm Batch Process',
-      `Process ${items.length} items for ${cost} credits?`,
-      [
-        { text: 'Cancel', style: 'cancel' },
-        {
-          text: 'Process',
-          onPress: async () => {
-            try {
-              // Process all items
-              for (const item of items) {
-                await processItem(item);
-                updateProgress();
-              }
-
-              // Deduct only after all succeed
-              await deductCreditsAfterSuccess(user?.uid, cost);
-
-              Alert.alert('Success', `Processed ${items.length} items`);
-            } catch (error) {
-              Alert.alert('Error', 'Batch processing failed');
-            }
-          },
-        },
-      ]
-    );
-  };
-
-  return (
-    <Button
-      onPress={() => handleBatchProcess(selectedItems)}
-      title={`Process ${selectedItems.length} items`}
-    />
-  );
-}
-```
-
-### Progressive Credit Check
-
-```typescript
-function ProgressiveFeature() {
-  const { user } = useAuth();
-  const { checkCreditsAvailable } = useCreditChecker();
-
-  const handleProgressiveAction = async () => {
-    // Try from most expensive to least expensive
-    const tiers = [10, 5, 3, 1];
-
-    for (const cost of tiers) {
-      const check = await checkCreditsAvailable(user?.uid, cost);
-
-      if (check.canProceed) {
-        // Use the highest tier user can afford
-        await executeAction(cost);
-        Alert.alert('Success', `Used ${cost} credits`);
-        return;
-      }
-    }
-
-    // User can't afford any tier
-    Alert.alert('Insufficient Credits', 'You need at least 1 credit to proceed');
-  };
-
-  return (
-    <Button
-      onPress={handleProgressiveAction}
-      title="Smart Action (1-10 credits)"
-    />
-  );
-}
-```
-
-## Best Practices
-
-1. **Check before deduct** - Always verify credits before operations
-2. **Deduct after success** - Only deduct when operation succeeds
-3. **Show clear messaging** - Tell users cost and balance
-4. **Handle failures** - Don't deduct on error
-5. **Track deductions** - Use callback for analytics
-6. **Provide alternatives** - Link to credit purchase when low
-7. **Estimate costs** - Calculate and show cost upfront
-
-## Related Hooks
-
-- **useCredits** - For accessing credits balance
-- **useDeductCredit** - For direct credit deduction
-- **useCreditsGate** - For gating features with credits
-- **useCreditChecker** (utility) - For reusable credit checker
-
-## See Also
-
-- [Credit Checker Utility](../../../utils/creditChecker.md)
-- [Credits README](../../../domains/wallet/README.md)
-- [Credits Entity](../../../domains/wallet/domain/entities/Credits.md)
+- **useCredits**: Access current credit balance
+- **useDeductCredit**: Deduct credits after check passes
+- **useCreditsGate**: Complete credit gating with deduction
+- **useFeatureGate**: Unified feature gating with credits
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
+- **Wallet Domain**: `src/domains/wallet/README.md`