@umituz/react-native-subscription 2.14.99 → 2.14.101

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

@@ -60,82 +60,6 @@ Hook for deducting credits from user balance with optimistic updates.
 - **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

package/src/presentation/hooks/useDeductCredit.ts

@@ -9,7 +9,7 @@ import type { UserCredits } from "../../domain/entities/Credits";
 import { getCreditsRepository } from "../../infrastructure/repositories/CreditsRepositoryProvider";
 import { creditsQueryKeys } from "./useCredits";
 
-import { timezoneService } from "@umituz/react-native-timezone";
+import { timezoneService } from "@umituz/react-native-design-system";
 
 export interface UseDeductCreditParams {
   userId: string | undefined;