@umituz/react-native-subscription 2.14.97 → 2.14.99

package/src/presentation/hooks/useDeductCredit.md

@@ -0,0 +1,176 @@
+# useDeductCredit Hook
+
+Hook for deducting credits from user balance with optimistic updates.
+
+## 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
+
+## Rules
+
+### Initialization
+
+```typescript
+// CORRECT
+const { deductCredit, isDeducting } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => showPaywall(),
+});
+
+// INCORRECT - Missing callback
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+});
+
+// INCORRECT - userId undefined
+const { deductCredit } = useDeductCredit({
+  userId: undefined,
+});
+```
+
+### Deduction Execution
+
+```typescript
+// CORRECT - Check return value
+const success = await deductCredit(5);
+if (success) {
+  executeFeature();
+}
+
+// INCORRECT - No return value check
+await deductCredit(5);
+executeFeature(); // May execute even if deduction failed
+
+// INCORRECT - Multiple simultaneous calls
+Promise.all([
+  deductCredit(5),
+  deductCredit(3), // Race condition!
+]);
+```
+
+### Loading States
+
+```typescript
+// CORRECT - Respect loading state
+<Button onPress={handleDeduct} disabled={isDeducting}>
+  {isDeducting ? 'Deducting...' : 'Use Feature'}
+</Button>
+
+// INCORRECT - Ignore loading state
+<Button onPress={handleDeduct}>
+  Use Feature
+</Button>
+```
+
+### Credit Exhaustion Handling
+
+```typescript
+// CORRECT - Implement callback
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => {
+    navigation.navigate('CreditPackages');
+  },
+});
+
+// MINIMUM - Show alert
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => {
+    Alert.alert('No Credits', 'Please purchase more credits');
+  },
+});
+```
+
+## 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`

package/src/presentation/hooks/useDevTestCallbacks.md

@@ -0,0 +1,422 @@
+# useDevTestCallbacks Hook
+
+**Development-only** hook for testing subscription renewal and credit operations.
+
+## Import
+
+```typescript
+import { useDevTestCallbacks } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+function useDevTestCallbacks(): {
+  onTestRenewal: () => void;
+  onCheckCredits: () => void;
+  onTestDuplicate: () => void;
+} | undefined
+```
+
+## Returns
+
+Returns `undefined` in production. In development, returns:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `onTestRenewal` | `() => void` | Simulate subscription renewal |
+| `onCheckCredits` | `() => void` | Show current credits in alert |
+| `onTestDuplicate` | `() => void` | Test duplicate renewal protection |
+
+## Important Notes
+
+⚠️ **Development Only**
+- This hook only works in `__DEV__` mode
+- Returns `undefined` in production builds
+- Use for testing and development purposes only
+
+## Basic Usage
+
+```typescript
+function DevTestSection() {
+  const devCallbacks = useDevTestCallbacks();
+
+  // Don't render in production
+  if (!devCallbacks) return null;
+
+  const { onTestRenewal, onCheckCredits, onTestDuplicate } = devCallbacks;
+
+  return (
+    <View style={styles.devSection}>
+      <Text style={styles.title}>Developer Tools</Text>
+
+      <Button onPress={onTestRenewal} title="Test Renewal" />
+      <Button onPress={onCheckCredits} title="Check Credits" />
+      <Button onPress={onTestDuplicate} title="Test Duplicate Protection" />
+    </View>
+  );
+}
+```
+
+## Advanced Usage
+
+### Complete Dev Test Panel
+
+```typescript
+function DevTestPanel() {
+  const devCallbacks = useDevTestCallbacks();
+
+  if (!__DEV__ || !devCallbacks) return null;
+
+  const { onTestRenewal, onCheckCredits, onTestDuplicate } = devCallbacks;
+
+  return (
+    <ScrollView style={styles.devPanel}>
+      <Text style={styles.header}>Developer Test Panel</Text>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Renewal Testing</Text>
+
+        <TouchableOpacity
+          style={styles.button}
+          onPress={onTestRenewal}
+        >
+          <Text>Test Renewal (Add Credits)</Text>
+        </TouchableOpacity>
+
+        <Text style={styles.help}>
+          Simulates a subscription renewal and adds credits using ACCUMULATE mode
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Credits Inspection</Text>
+
+        <TouchableOpacity
+          style={styles.button}
+          onPress={onCheckCredits}
+        >
+          <Text>Check Current Credits</Text>
+        </TouchableOpacity>
+
+        <Text style={styles.help}>
+          Display current credit balance and purchase date
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Duplicate Protection</Text>
+
+        <TouchableOpacity
+          style={styles.button}
+          onPress={onTestDuplicate}
+        >
+          <Text>Test Duplicate Protection</Text>
+        </TouchableOpacity>
+
+        <Text style={styles.help}>
+          Tests that duplicate renewals with the same ID are prevented
+        </Text>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+### With Settings Screen Integration
+
+```typescript
+function SettingsScreen() {
+  const devCallbacks = useDevTestCallbacks();
+
+  return (
+    <ScrollView>
+      <Section title="Account">
+        <SettingsItem label="Email" value={user?.email} />
+        <SettingsItem label="Subscription" value={isPremium ? 'Premium' : 'Free'} />
+      </Section>
+
+      {/* Only show in development */}
+      {__DEV__ && devCallbacks && (
+        <Section title="Developer Tools">
+          <SettingsItem
+            label="Test Renewal"
+            onPress={devCallbacks.onTestRenewal}
+          />
+          <SettingsItem
+            label="Check Credits"
+            onPress={devCallbacks.onCheckCredits}
+          />
+          <SettingsItem
+            label="Test Duplicate Protection"
+            onPress={devCallbacks.onTestDuplicate}
+          />
+        </Section>
+      )}
+    </ScrollView>
+  );
+}
+```
+
+### With Debug Menu
+
+```typescript
+function DebugMenu() {
+  const devCallbacks = useDevTestCallbacks();
+
+  if (!__DEV__) return null;
+
+  return (
+    <Menu>
+      {devCallbacks && (
+        <>
+          <MenuItem onPress={devCallbacks.onTestRenewal}>
+            Test Renewal
+          </MenuItem>
+          <MenuItem onPress={devCallbacks.onCheckCredits}>
+            Check Credits
+          </MenuItem>
+          <MenuItem onPress={devCallbacks.onTestDuplicate}>
+            Test Duplicate Protection
+          </MenuItem>
+        </>
+      )}
+    </Menu>
+  );
+}
+```
+
+## Test Functions
+
+### onTestRenewal
+
+Simulates a subscription renewal event:
+
+```typescript
+const onTestRenewal = () => {
+  // Simulates renewal with:
+  // - renewalId: `dev_renewal_${Date.now()}`
+  // - productId: 'test_yearly_subscription'
+  // - Mode: ACCUMULATE (adds to existing credits)
+
+  // Shows alert with:
+  // - New credit balance
+  // - Confirmation of ACCUMULATE mode
+};
+```
+
+**Example output:**
+```
+✅ Test Renewal Success
+Credits Updated!
+
+New Balance: 1200
+
+(ACCUMULATE mode - credits added to existing)
+```
+
+### onCheckCredits
+
+Displays current credit information:
+
+```typescript
+const onCheckCredits = () => {
+  // Shows alert with:
+  // - Current credit balance
+  // - Purchase date (or "N/A")
+};
+```
+
+**Example output:**
+```
+📊 Current Credits
+Credits: 100
+
+Purchased: January 15, 2024
+```
+
+### onTestDuplicate
+
+Tests duplicate renewal protection:
+
+```typescript
+const onTestDuplicate = () => {
+  // Performs two initialization calls with same renewalId:
+  // - First call: Adds credits
+  // - Second call: Should be skipped
+
+  // Shows alert with:
+  // - First call result
+  // - Second call result (should indicate protection worked)
+};
+```
+
+**Example output:**
+```
+Duplicate Test
+First call: ✅ Added credits
+
+Second call: ✅ Skipped (protection works!)
+```
+
+## Development Logging
+
+The hook logs detailed information in development:
+
+```typescript
+// Test renewal
+🧪 [Dev Test] Simulating auto-renewal...
+{
+  userId: 'user-123',
+  renewalId: 'dev_renewal_1705311234567'
+}
+✅ [Dev Test] Renewal completed:
+{
+  success: true,
+  credits: 1100
+}
+
+// Check credits
+📊 Current Credits
+Credits: 100
+Purchased: January 15, 2024
+
+// Test duplicate
+🧪 [Dev Test] Testing duplicate protection...
+First call: { credits: 100, ... }
+Second call: { credits: 100, ... }
+```
+
+## Examples
+
+### Comprehensive Dev Dashboard
+
+```typescript
+function DevDashboard() {
+  const devCallbacks = useDevTestCallbacks();
+
+  if (!__DEV__ || !devCallbacks) return null;
+
+  const { user } = useAuth();
+  const { credits } = useCredits();
+
+  return (
+    <View style={styles.dashboard}>
+      <View style={styles.header}>
+        <Text style={styles.title}>Development Dashboard</Text>
+        <Text style={styles.subtitle}>
+          User: {user?.uid || 'Not logged in'}
+        </Text>
+        <Text style={styles.subtitle}>
+          Credits: {credits?.credits || 0}
+        </Text>
+      </View>
+
+      <View style={styles.actions}>
+        <TouchableOpacity
+          style={styles.actionButton}
+          onPress={devCallbacks.onTestRenewal}
+        >
+          <Icon name="refresh" size={20} />
+          <Text>Simulate Renewal</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          style={styles.actionButton}
+          onPress={devCallbacks.onCheckCredits}
+        >
+          <Icon name="search" size={20} />
+          <Text>Inspect Credits</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          style={styles.actionButton}
+          onPress={devCallbacks.onTestDuplicate}
+        >
+          <Icon name="shield" size={20} />
+          <Text>Test Duplicate Protection</Text>
+        </TouchableOpacity>
+      </View>
+
+      <View style={styles.info}>
+        <Text style={styles.infoTitle}>Test Mode Active</Text>
+        <Text style={styles.infoText}>
+          All operations use test data and won't affect production
+        </Text>
+      </View>
+    </View>
+  );
+}
+```
+
+### With Flow Testing
+
+```typescript
+function RenewalFlowTest() {
+  const devCallbacks = useDevTestCallbacks();
+
+  if (!__DEV__ || !devCallbacks) return null;
+
+  const testRenewalFlow = async () => {
+    // 1. Check initial credits
+    devCallbacks.onCheckCredits();
+
+    // 2. Simulate renewal
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    devCallbacks.onTestRenewal();
+
+    // 3. Verify credits increased
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    devCallbacks.onCheckCredits();
+
+    // 4. Test duplicate protection
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    devCallbacks.onTestDuplicate();
+  };
+
+  return (
+    <Button
+      onPress={testRenewalFlow}
+      title="Run Complete Renewal Flow Test"
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Development only** - Never use in production code
+2. **Guard with `__DEV__`** - Always check if in development mode
+3. **Clear UI** - Make dev tools visually distinct
+4. **Test thoroughly** - Use for testing renewal flows
+5. **Document behavior** - Leave clear comments for other developers
+6. **Remove before release** - Ensure dev UI doesn't ship
+7. **Test edge cases** - Duplicate handling, error cases
+
+## Production Safety
+
+The hook is production-safe:
+
+```typescript
+export const useDevTestCallbacks = (): DevTestActions | undefined => {
+  // ... implementation
+
+  if (!__DEV__) {
+    return undefined; // ✅ Returns undefined in production
+  }
+
+  return { onTestRenewal, onCheckCredits, onTestDuplicate };
+};
+```
+
+## Related Hooks
+
+- **useCredits** - For accessing credits balance
+- **useInitializeCredits** - For credit initialization
+- **usePremiumWithCredits** - For premium + credits integration
+
+## See Also
+
+- [Credits README](../../../domains/wallet/README.md)
+- [Renewal Testing Guide](../../../docs/RENEWAL_TESTING.md)
+- [Development Tools](../../../docs/DEV_TOOLS.md)