@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/presentation/hooks/useCreditsGate.md

@@ -2,345 +2,93 @@
 
 Hook for gating features behind credit requirements.
 
-## Import
+## Location
 
-```typescript
-import { useCreditsGate } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useCreditsGate.ts`
 
-```typescript
-function useCreditsGate(config: {
-  creditCost: number;
-  featureId: string;
-}): {
-  hasCredits: boolean;
-  credits: number;
-  consumeCredit: () => Promise<CreditsResult>;
-  isLoading: boolean;
-  showPurchasePrompt: () => void;
-}
-```
+**Type**: Hook
 
-## Parameters
+## Strategy
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `config.creditCost` | `number` | Yes | Number of credits required |
-| `config.featureId` | `string` | Yes | Unique identifier for the feature |
+### Credit Gating Flow
 
-## Returns
+1. **Credit Check**: Verify user has sufficient credits for feature
+2. **Balance Display**: Show current credit balance to user
+3. **Feature Access Control**: Enable/disable features based on credit availability
+4. **Consumption**: Deduct credits when feature is used
+5. **Purchase Prompt**: Guide users to purchase when insufficient
+6. **Transaction Tracking**: Record all credit transactions
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `hasCredits` | `boolean` | Whether user has enough credits |
-| `credits` | `number` | Current credit balance |
-| `consumeCredit` | `() => Promise<CreditsResult>` | Function to consume credits |
-| `isLoading` | `boolean` | Whether hook is loading |
-| `showPurchasePrompt` | `() => void` | Show purchase prompt UI |
+### Integration Points
 
-## Basic Usage
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
+- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
+- **TanStack Query**: For optimistic updates and caching
+- **Paywall Domain**: For purchase flow integration
 
-```typescript
-function CreditFeature() {
-  const { hasCredits, credits, consumeCredit } = useCreditsGate({
-    creditCost: 5,
-    featureId: 'export_data',
-  });
+## Restrictions
 
-  const handleExport = async () => {
-    if (!hasCredits) {
-      Alert.alert('Insufficient Credits', `You need 5 credits, have ${credits}`);
-      return;
-    }
+### REQUIRED
 
-    const result = await consumeCredit();
+- **Credit Cost**: MUST specify credit cost for feature
+- **Feature ID**: MUST provide unique feature identifier
+- **Balance Check**: MUST verify hasCredits before allowing action
+- **Error Handling**: MUST handle consumption failures
 
-    if (result.success) {
-      await exportData();
-      Alert.alert('Success', `Data exported! ${result.newBalance} credits remaining`);
-    } else {
-      Alert.alert('Error', result.error?.message || 'Failed to consume credits');
-    }
-  };
+### PROHIBITED
 
-  return (
-    <Button
-      onPress={handleExport}
-      title={`Export Data (5 credits)`}
-      disabled={!hasCredits}
-    />
-  );
-}
-```
+- **NEVER** allow feature access when hasCredits is false
+- **NEVER** consume credits without checking balance first
+- **NEVER** assume credits will be sufficient (always check)
+- **DO NOT** use for security decisions without server validation
 
-## Advanced Usage
+### CRITICAL SAFETY
 
-### With Purchase Prompt
+- **ALWAYS** check return value from consumeCredit
+- **NEVER** allow negative credit balance
+- **MUST** handle insufficient credits gracefully
+- **ALWAYS** show credit cost to user before action
 
-```typescript
-function AdvancedCreditFeature() {
-  const { hasCredits, credits, consumeCredit, showPurchasePrompt } =
-    useCreditsGate({
-      creditCost: 10,
-      featureId: 'ai_analysis',
-    });
+## AI Agent Guidelines
 
-  const handleAnalyze = async () => {
-    if (!hasCredits) {
-      showPurchasePrompt();
-      return;
-    }
+### When Implementing Credit Gates
 
-    const result = await consumeCredit();
+1. **Always** display credit cost to user before action
+2. **Always** check hasCredits before enabling buttons
+3. **Always** handle consumeCredit result
+4. **Never** allow action when credits are insufficient
+5. **Always** provide purchase path for credits
 
-    if (result.success) {
-      await performAIAnalysis();
-    }
-  };
+### Integration Checklist
 
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
-      <Text>Cost: 10 credits</Text>
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Specify credit cost in config
+- [ ] Provide unique feature ID
+- [ ] Check hasCredits before enabling feature
+- [ ] Handle consumeCredit result
+- [ ] Show credit cost in UI
+- [ ] Display current balance
+- [ ] Implement purchase prompt for insufficient credits
+- [ ] Test with zero balance
+- [ ] Test with insufficient credits
+- [ ] Test with sufficient credits
 
-      <Button
-        onPress={handleAnalyze}
-        title={hasCredits ? 'Analyze (10 credits)' : 'Get More Credits'}
-        disabled={!hasCredits && credits < 10}
-      />
-    </View>
-  );
-}
-```
+### Common Patterns
 
-### With Transaction Tracking
+1. **Pre-check**: Verify balance before showing feature
+2. **Confirmation**: Ask user before expensive operations
+3. **Success Feedback**: Show message after successful consumption
+4. **Failure Handling**: Display appropriate error on failure
+5. **Purchase Flow**: Navigate to purchase screen on exhaustion
 
-```typescript
-function TrackedCreditFeature() {
-  const { consumeCredit, hasCredits } = useCreditsGate({
-    creditCost: 3,
-    featureId: 'filter_apply',
-  });
+## Related Documentation
 
-  const handleApplyFilter = async () => {
-    const result = await consumeCredit();
-
-    if (result.success) {
-      // Track usage
-      analytics.track('credit_consumed', {
-        feature_id: 'filter_apply',
-        amount: 3,
-        transaction_id: result.transaction?.id,
-      });
-
-      // Apply filter
-      await applyFilter();
-    }
-  };
-
-  return <Button onPress={handleApplyFilter} title="Apply Filter (3 credits)" />;
-}
-```
-
-### With Loading State
-
-```typescript
-function CreditFeatureWithLoading() {
-  const { consumeCredit, isLoading, hasCredits } = useCreditsGate({
-    creditCost: 5,
-    featureId: 'premium_template',
-  });
-
-  const handleUse = async () => {
-    if (!hasCredits) return;
-
-    const result = await consumeCredit();
-
-    if (result.success) {
-      // Show loading while processing
-      await processFeature();
-    }
-  };
-
-  return (
-    <View>
-      <Button
-        onPress={handleUse}
-        disabled={isLoading || !hasCredits}
-        title={isLoading ? 'Processing...' : 'Use Feature (5 credits)'}
-      />
-    </View>
-  );
-}
-```
-
-## Examples
-
-### Credit-Based Action Button
-
-```typescript
-function CreditActionButton({ featureId, cost, action, label }) {
-  const { hasCredits, credits, consumeCredit } = useCreditsGate({
-    creditCost: cost,
-    featureId,
-  });
-
-  const handlePress = async () => {
-    if (!hasCredits) {
-      showInsufficientCreditsDialog(cost, credits);
-      return;
-    }
-
-    const result = await consumeCredit();
-    if (result.success) {
-      await action();
-    }
-  };
-
-  return (
-    <TouchableOpacity
-      onPress={handlePress}
-      disabled={!hasCredits}
-      style={hasCredits ? styles.buttonEnabled : styles.buttonDisabled}
-    >
-      <Text style={styles.buttonText}>{label}</Text>
-      <Text style={styles.costText}>{cost} credits</Text>
-    </TouchableOpacity>
-  );
-}
-```
-
-### Credit Balance Display
-
-```typescript
-function CreditBalanceDisplay() {
-  const { credits, isLoading } = useCreditsGate({
-    creditCost: 1,
-    featureId: 'any',
-  });
-
-  return (
-    <View style={styles.balanceContainer}>
-      <Text style={styles.balanceLabel}>Your Credits:</Text>
-
-      {isLoading ? (
-        <ActivityIndicator size="small" />
-      ) : (
-        <Text style={styles.balanceValue}>{credits}</Text>
-      )}
-    </View>
-  );
-}
-```
-
-### Multiple Credit Tiers
-
-```typescript
-function TieredFeatureAccess() {
-  const { credits: basicCredits, hasCredits: hasBasic } = useCreditsGate({
-    creditCost: 5,
-    featureId: 'basic_feature',
-  });
-
-  const { credits: proCredits, hasCredits: hasPro } = useCreditsGate({
-    creditCost: 20,
-    featureId: 'pro_feature',
-  });
-
-  return (
-    <View>
-      <Button
-        onPress={handleBasicFeature}
-        disabled={!hasBasic}
-        title={`Basic Feature (5 credits)`}
-      />
-
-      <Button
-        onPress={handleProFeature}
-        disabled={!hasPro}
-        title={`Pro Feature (20 credits)`}
-      />
-
-      <Text>Balance: {basicCredits} credits</Text>
-    </View>
-  );
-}
-```
-
-## Result Type
-
-```typescript
-interface CreditsResult {
-  success: boolean;
-  newBalance?: number;
-  transaction?: {
-    id: string;
-    amount: number;
-    reason: string;
-    timestamp: string;
-  };
-  error?: Error;
-}
-```
-
-## Error Handling
-
-```typescript
-function RobustCreditFeature() {
-  const { consumeCredit } = useCreditsGate({
-    creditCost: 10,
-    featureId: 'robust_feature',
-  });
-
-  const handleAction = async () => {
-    const result = await consumeCredit();
-
-    if (!result.success) {
-      if (result.error?.message.includes('Insufficient')) {
-        Alert.alert('Insufficient Credits', 'Please purchase more credits');
-      } else if (result.error?.message.includes('Network')) {
-        Alert.alert('Network Error', 'Please check your connection');
-      } else {
-        Alert.alert('Error', 'Failed to process. Please try again');
-      }
-
-      // Log error
-      analytics.track('credit_consumption_failed', {
-        feature_id: 'robust_feature',
-        error: result.error?.message,
-      });
-      return;
-    }
-
-    // Success
-    await executeFeature();
-  };
-
-  return <Button onPress={handleAction} title="Execute (10 credits)" />;
-}
-```
-
-## Best Practices
-
-1. **Always check `hasCredits`** before enabling actions
-2. **Show credit cost** in UI
-3. **Handle errors gracefully**
-4. **Provide purchase prompt** when credits are insufficient
-5. **Display current balance**
-6. **Track credit consumption** in analytics
-7. **Refetch balance** after consumption
-
-## Related Hooks
-
-- **useCredits** - For credit balance only
-- **useDeductCredit** - For manual credit deduction
-- **usePremiumWithCredits** - For premium OR credits access
-- **useCreditChecker** - For simple credit checks
-
-## See Also
-
-- [useCredits](./useCredits.md)
-- [useDeductCredit](./useDeductCredit.md)
-- [usePremiumWithCredits](./usePremiumWithCredits.md)
+- **useCredits**: Access current credit balance
+- **useDeductCredit**: Manual credit deduction with optimistic updates
+- **useCreditChecker**: Simple credit validation
+- **usePremiumWithCredits**: Hybrid premium/credits access
+- **useFeatureGate**: Unified feature gating
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
+- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useDeductCredit.md

@@ -2,159 +2,99 @@
 
 Hook for deducting credits from user balance with optimistic updates.
 
-## Import
-
-```typescript
-import { useDeductCredit } from '@umituz/react-native-subscription';
-```
-
-## Signature
-
-```typescript
-function useDeductCredit(params: {
-  userId: string | undefined;
-  onCreditsExhausted?: () => void;
-}): {
-  deductCredit: (cost?: number) => Promise<boolean>;
-  deductCredits: (cost: number) => Promise<boolean>;
-  isDeducting: boolean;
-}
-```
-
-## Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `userId` | `string \| undefined` | **Required** | User ID for credit deduction |
-| `onCreditsExhausted` | `() => void` | `undefined` | Callback when credits are exhausted |
-
-## Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `deductCredit` | `(cost?: number) => Promise<boolean>` | Deduct credits (defaults to 1) |
-| `deductCredits` | `(cost: number) => Promise<boolean>` | Deduct specific amount |
-| `isDeducting` | `boolean` | Mutation is in progress |
-
-## Basic Usage
-
-```typescript
-function CreditButton() {
-  const { user } = useAuth();
-  const { deductCredit, isDeducting } = useDeductCredit({
-    userId: user?.uid,
-    onCreditsExhausted: () => {
-      Alert.alert('Low Credits', 'Please purchase more credits');
-    },
-  });
-
-  const handleUseFeature = async () => {
-    const success = await deductCredit(1);
-    if (success) {
-      executePremiumFeature();
-    }
-  };
-
-  return (
-    <Button onPress={handleUseFeature} disabled={isDeducting}>
-      Use Feature (1 Credit)
-    </Button>
-  );
-}
-```
-
-## Advanced Usage
-
-### With Custom Cost
-
-```typescript
-function FeatureWithCost() {
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-  });
-
-  const features = {
-    basic: { cost: 1, name: 'Basic Generation' },
-    advanced: { cost: 5, name: 'Advanced Generation' },
-    premium: { cost: 10, name: 'Premium Generation' },
-  };
-
-  const handleFeature = async (cost: number) => {
-    const success = await deductCredit(cost);
-    if (success) {
-      console.log('Feature used');
-    }
-  };
-
-  return (
-    <View>
-      {Object.entries(features).map(([key, { cost, name }]) => (
-        <Button
-          key={key}
-          onPress={() => handleFeature(cost)}
-          title={`${name} (${cost} credits)`}
-        />
-      ))}
-    </View>
-  );
-}
-```
-
-### With Confirmation
-
-```typescript
-function CreditDeductionWithConfirmation() {
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-  });
-
-  const handleActionWithConfirmation = async (cost: number, action: string) => {
-    Alert.alert(
-      'Confirm Action',
-      `This will cost ${cost} credit${cost > 1 ? 's' : ''}. Continue?`,
-      [
-        { text: 'Cancel', style: 'cancel' },
-        {
-          text: 'Confirm',
-          onPress: async () => {
-            const success = await deductCredit(cost);
-            if (success) {
-              await performAction(action);
-            }
-          },
-        },
-      ]
-    );
-  };
-
-  return (
-    <Button
-      onPress={() => handleActionWithConfirmation(5, 'export')}
-      title="Export Data (5 Credits)"
-    />
-  );
-}
-```
-
-## Best Practices
-
-1. **Check balance first** - Show user if they have enough credits
-2. **Handle exhausted credits** - Provide purchase option
-3. **Show loading state** - Disable button during deduction
-4. **Optimistic updates** - UI updates automatically
-5. **Error handling** - Handle deduction failures gracefully
-6. **Confirm expensive actions** - Ask before large deductions
-7. **Clear messaging** - Tell users cost before deducting
-
-## Related Hooks
-
-- **useCredits** - For accessing credits balance
-- **useCreditsGate** - For gating features with credits
-- **useInitializeCredits** - For initializing credits after purchase
-- **useCreditChecker** - For checking credit availability
-
-## See Also
-
-- [Credits README](../../../domains/wallet/README.md)
-- [Credits Entity](../../../domains/wallet/domain/entities/Credits.md)
-- [Credits Repository](../../../infrastructure/repositories/CreditsRepository.md)
+## Location
+
+**Import Path**: `@umituz/react-native-subscription`
+
+**File**: `src/presentation/hooks/useDeductCredit.ts`
+
+## Strategy
+
+### Credit Deduction Flow
+
+1. **Pre-deduction Validation**
+   - Verify user is authenticated (userId must be defined)
+   - Check if sufficient credits exist
+   - Validate deduction amount is positive
+
+2. **Optimistic Update**
+   - Immediately update UI with new balance
+   - Store previous state for potential rollback
+   - Update TanStack Query cache
+
+3. **Server Synchronization**
+   - Send deduction request to backend
+   - Handle success/failure responses
+   - Rollback on failure
+
+4. **Post-deduction Handling**
+   - Trigger `onCreditsExhausted` callback if balance reaches zero
+   - Return success/failure boolean
+   - Reset loading state
+
+### 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 optimistic updates
+
+## Restrictions
+
+### REQUIRED
+
+- **User Authentication**: `userId` parameter MUST be provided and cannot be undefined
+- **Positive Amount**: Credit cost MUST be greater than zero
+- **Callback Implementation**: `onCreditsExhausted` callback SHOULD be implemented to handle zero balance scenarios
+
+### PROHIBITED
+
+- **NEVER** call `deductCredit` or `deductCredits` without checking `isDeducting` state first
+- **NEVER** allow multiple simultaneous deduction calls for the same user
+- **NEVER** deduce credits when balance is insufficient (should check with `useCreditChecker` first)
+- **DO NOT** use this hook for guest users (userId undefined)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** check return value before proceeding with feature execution
+- **ALWAYS** handle the case where deduction returns `false`
+- **NEVER** assume deduction succeeded without checking return value
+- **MUST** implement error boundaries when using this hook
+
+## AI Agent Guidelines
+
+### When Implementing Features
+
+1. **Always** check if user has sufficient credits BEFORE allowing action
+2. **Always** show the credit cost to user before deducting
+3. **Always** disable buttons while `isDeducting` is true
+4. **Always** handle the case where deduction returns false
+5. **Never** allow zero or negative credit costs
+
+### Integration Checklist
+
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide valid `userId` from authentication context
+- [ ] Implement `onCreditsExhausted` callback
+- [ ] Check `isDeducting` before calling deduct functions
+- [ ] Validate return value before proceeding
+- [ ] Show credit cost to user before action
+- [ ] Handle error cases gracefully
+- [ ] Test with insufficient credits
+- [ ] Test with zero balance
+
+### Common Patterns to Implement
+
+1. **Pre-check**: Use `useCreditChecker` before showing feature button
+2. **Confirmation Dialog**: Ask user before expensive operations (>5 credits)
+3. **Success Feedback**: Show success message after deduction
+4. **Failure Handling**: Show appropriate error message on failure
+5. **Purchase Flow**: Navigate to purchase screen on exhaustion
+
+## Related Documentation
+
+- **useCredits**: Access current credit balance
+- **useCreditChecker**: Check credit availability before operations
+- **useInitializeCredits**: Initialize credits after purchase
+- **useFeatureGate**: Unified feature gating with credits
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
+- **Wallet Domain**: `src/domains/wallet/README.md`