@umituz/react-native-subscription 2.14.96 → 2.14.98

package/src/presentation/hooks/useDeductCredit.md

@@ -0,0 +1,160 @@
+# useDeductCredit Hook
+
+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)

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)