@umituz/react-native-subscription 2.14.97 → 2.14.99

package/src/domains/wallet/infrastructure/README.md

@@ -0,0 +1,96 @@
+# Wallet Infrastructure
+
+Infrastructure layer for wallet and credits functionality.
+
+## Overview
+
+This directory contains implementations for credit persistence, transactions, and credit operations.
+
+## Structure
+
+```
+infrastructure/
+├── repositories/    # Data persistence implementations
+│   └── CreditsRepository.ts
+└── services/         # External service integrations
+    └── CreditsService.ts
+```
+
+## Credits Repository
+
+Handles credit data persistence with duplicate protection.
+
+### Key Features
+
+- **Duplicate Protection**: Prevents duplicate credit allocations
+- **Optimistic Updates**: Immediate UI updates with rollback
+- **Transactional**: Atomic credit operations
+- **ACCUMULATE Mode**: Adds credits on renewal
+
+### Core Methods
+
+```typescript
+class CreditsRepository implements ICreditsRepository {
+  async getCredits(userId: string): Promise<UserCredits | null>;
+  async initializeCredits(
+    userId: string,
+    purchaseId?: string,
+    productId?: string
+  ): Promise<CreditsResult>;
+  async deductCredit(userId: string, amount: number): Promise<CreditsResult>;
+  async addCredits(userId: string, amount: number): Promise<CreditsResult>;
+}
+```
+
+### Usage
+
+```typescript
+import { CreditsRepository } from './repositories/CreditsRepository';
+import { getCreditsRepository } from './repositories/CreditsRepositoryProvider';
+
+const repository = getCreditsRepository();
+
+// Initialize credits
+const result = await repository.initializeCredits('user-123', 'purchase-456', 'premium_monthly');
+if (result.success) {
+  console.log('Credits:', result.data.credits);
+}
+
+// Deduct credits
+const deductResult = await repository.deductCredit('user-123', 5);
+if (deductResult.success) {
+  console.log('Credits deducted successfully');
+} else if (deductResult.error?.code === 'CREDITS_EXHAUSTED') {
+  console.log('Not enough credits');
+}
+```
+
+## Duplicate Protection
+
+The repository prevents duplicate credit allocations based on `purchaseId`:
+
+```typescript
+// First call
+await repository.initializeCredits(userId, 'renewal-123', 'premium');
+// Returns: { success: true, data: { credits: 100 } }
+
+// Second call with same purchaseId
+await repository.initializeCredits(userId, 'renewal-123', 'premium');
+// Returns: { success: true, duplicate: true, data: { credits: 100 } }
+// Credits not added again
+```
+
+## Best Practices
+
+1. **Check Before Deduct**: Always verify credit balance
+2. **Handle Errors**: Catch and handle credit errors appropriately
+3. **Use Transactions**: Ensure data consistency
+4. **Log Operations**: Track credit operations for debugging
+5. **Test Edge Cases**: Zero credits, max credits, duplicates
+6. **Validate Input**: Validate all input parameters
+
+## Related
+
+- [Wallet Domain](../domain/README.md)
+- [Credits Entity](../domain/entities/README.md)
+- [useCredits Hook](../../presentation/hooks/useCredits.md)

package/src/domains/wallet/presentation/components/BalanceCard.tsx

@@ -1,13 +1,13 @@
 /**
  * Balance Card Component
  *
- * Displays user's credit balance with gradient background.
+ * Displays user's credit balance with solid background.
  * Props-driven for full customization.
  */
 
 import React from "react";
 import { View, StyleSheet } from "react-native";
-import { LinearGradient } from "expo-linear-gradient";
+
 import {
     useAppDesignTokens,
     AtomicText,
@@ -31,17 +31,11 @@ export const BalanceCard: React.FC<BalanceCardProps> = ({
   iconName = "wallet",
 }) => {
   const tokens = useAppDesignTokens();
-  const gradientColors = [
-    tokens.colors.primary,
-    tokens.colors.primaryDark || tokens.colors.primary,
-  ] as const;
+
 
   return (
-    <LinearGradient
-      colors={gradientColors}
-      start={{ x: 0, y: 0 }}
-      end={{ x: 1, y: 1 }}
-      style={styles.container}
+    <View
+      style={[styles.container, { backgroundColor: tokens.colors.primary }]}
     >
       <View style={styles.content}>
         <View style={styles.textContainer}>
@@ -73,7 +67,7 @@ export const BalanceCard: React.FC<BalanceCardProps> = ({
           <AtomicIcon name={iconName} size="xl" color="onPrimary" />
         </View>
       </View>
-    </LinearGradient>
+    </View>
   );
 };
 

package/src/domains/wallet/presentation/components/README.md

@@ -0,0 +1,231 @@
+# Wallet Presentation Components
+
+UI components for wallet and credit display.
+
+## Overview
+
+This directory contains React Native components for displaying credits, transactions, and wallet information.
+
+## Components
+
+### CreditBalanceCard
+Card displaying current credit balance.
+
+```typescript
+interface CreditBalanceCardProps {
+  credits: number;
+  balance: number;
+  isLoading?: boolean;
+  onPress?: () => void;
+  onRefresh?: () => void;
+}
+```
+
+**Usage:**
+```typescript
+<CreditBalanceCard
+  credits={50}
+  balance={0.50}
+  onPress={() => navigation.navigate('CreditHistory')}
+  onRefresh={() => refetch()}
+/>
+```
+
+### TransactionItem
+Individual transaction display component.
+
+```typescript
+interface TransactionItemProps {
+  transaction: Transaction;
+  format?: 'full' | 'compact';
+}
+```
+
+**Usage:**
+```typescript
+<TransactionItem
+  transaction={{
+    id: 'tx_123',
+    amount: -5,
+    reason: 'AI Generation',
+    timestamp: new Date(),
+    type: 'deduction',
+  }}
+  format="full"
+/>
+```
+
+### CreditProgressBar
+Progress bar showing credit usage.
+
+```typescript
+interface CreditProgressBarProps {
+  current: number;
+  total: number;
+  showLabel?: boolean;
+  showPercentage?: boolean;
+  height?: number;
+}
+```
+
+**Usage:**
+```typescript
+<CreditProgressBar
+  current={50}
+  total={100}
+  showLabel={true}
+  showPercentage={true}
+  height={8}
+/>
+```
+
+### CreditPackageCard
+Display card for purchasable credit packages.
+
+```typescript
+interface CreditPackageCardProps {
+  package: {
+    id: string;
+    amount: number;
+    price: number;
+    bonus?: number;
+    currency: string;
+  };
+  onPress: () => void;
+  highlight?: boolean;
+}
+```
+
+**Usage:**
+```typescript
+<CreditPackageCard
+  package={{
+    id: 'premium_credits',
+    amount: 100,
+    price: 9.99,
+    bonus: 10,
+    currency: 'USD',
+  }}
+  onPress={() => purchaseCredits('premium_credits')}
+  highlight={true}
+/>
+```
+
+## Usage Patterns
+
+### Complete Credit Dashboard
+
+```typescript
+function CreditDashboard() {
+  const { credits, transactions, isLoading, refetch } = useCredits();
+
+  return (
+    <ScrollView>
+      <CreditBalanceCard
+        credits={credits}
+        balance={calculateBalance(credits)}
+        onRefresh={refetch}
+      />
+
+      <View style={styles.section}>
+        <Text style={styles.title}>Recent Transactions</Text>
+        {transactions.slice(0, 10).map(tx => (
+          <TransactionItem key={tx.id} transaction={tx} />
+        ))}
+      </View>
+
+      <Button onPress={() => navigation.navigate('CreditPackages')}>
+        Get More Credits
+      </Button>
+    </ScrollView>
+  );
+}
+```
+
+### Credit Warning Banner
+
+```typescript
+function LowCreditWarning() {
+  const { credits } = useCredits();
+  const warningThreshold = 20;
+
+  if (credits > warningThreshold) return null;
+
+  return (
+    <Banner type={credits === 0 ? 'error' : 'warning'}>
+      <Text>
+        {credits === 0
+          ? 'No credits remaining'
+          : `Only ${credits} credits left`
+        }
+      </Text>
+      <Button onPress={() => navigation.navigate('CreditPackages')}>
+        Get More
+      </Button>
+    </Banner>
+  );
+}
+```
+
+### Credit History List
+
+```typescript
+function TransactionHistory() {
+  const { transactions } = useCredits();
+
+  return (
+    <FlatList
+      data={transactions}
+      keyExtractor={(item) => item.id}
+      renderItem={({ item }) => (
+        <TransactionItem transaction={item} format="compact" />
+      )}
+      ListHeaderComponent={() => (
+        <Text style={styles.title}>Transaction History</Text>
+      )}
+      ListEmptyComponent={() => (
+        <EmptyState
+          icon="receipt"
+          title="No transactions yet"
+          message="Your credit transaction history will appear here"
+        />
+      )}
+    />
+  );
+}
+```
+
+## Styling
+
+Components use design system:
+
+```typescript
+import { useAppDesignTokens } from '@umituz/react-native-design-system';
+
+const tokens = useAppDesignTokens();
+
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: tokens.colors.surface,
+    borderRadius: tokens.radius.lg,
+    padding: tokens.spacing.lg,
+    marginBottom: tokens.spacing.md,
+  },
+});
+```
+
+## Best Practices
+
+1. **Visual Hierarchy**: Emphasize important information
+2. **Color Coding**: Use colors to indicate status (low/warning/good)
+3. **Loading States**: Show skeletons while loading
+4. **Empty States**: Provide helpful empty state messages
+5. **Refresh Capability**: Allow manual refresh
+6. **Transactional History**: Show clear transaction history
+7. **Purchase Links**: Easy access to purchase more credits
+
+## Related
+
+- [Credit Row](../../../presentation/components/details/CreditRow.md)
+- [Credits Hook](../hooks/README.md)
+- [Wallet Domain](../../domain/README.md)

package/src/domains/wallet/presentation/hooks/README.md

@@ -0,0 +1,255 @@
+# Wallet Presentation Hooks
+
+React hooks for wallet and credit functionality.
+
+## Overview
+
+This directory contains React hooks specifically for credit management and wallet operations.
+
+## Hooks
+
+### useCredits
+Access and manage credit balance.
+
+```typescript
+function useCredits(params: {
+  userId: string | undefined;
+  enabled?: boolean;
+}): {
+  credits: number;
+  balance: number;
+  transactions: Transaction[];
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+```
+
+**Usage:**
+```typescript
+function CreditBalance() {
+  const { credits, isLoading } = useCredits({ userId: user?.uid });
+
+  if (isLoading) return <LoadingSpinner />;
+
+  return (
+    <View>
+      <Text>Balance: {credits} credits</Text>
+    </View>
+  );
+}
+```
+
+### useDeductCredit
+Deduct credits with optimistic updates.
+
+```typescript
+function useDeductCredit(params: {
+  userId: string | undefined;
+  onCreditsExhausted?: () => void;
+}): {
+  deductCredit: (cost?: number) => Promise<boolean>;
+  deductCredits: (cost: number) => Promise<boolean>;
+  isDeducting: boolean;
+}
+```
+
+**Usage:**
+```typescript
+function AIGeneration() {
+  const { deductCredit } = useDeductCredit({
+    userId: user?.uid,
+    onCreditsExhausted: () => showPaywall(),
+  });
+
+  const handleGenerate = async () => {
+    const success = await deductCredit(5);
+    if (success) {
+      await callAIGenerationAPI();
+    }
+  };
+}
+```
+
+### useInitializeCredits
+Initialize credits after purchase.
+
+```typescript
+function useInitializeCredits(params: {
+  userId: string | undefined;
+}): {
+  initializeCredits: (options?: {
+    purchaseId?: string;
+    productId?: string;
+  }) => Promise<boolean>;
+  isInitializing: boolean;
+}
+```
+
+**Usage:**
+```typescript
+function PurchaseCompletion() {
+  const { initializeCredits } = useInitializeCredits({
+    userId: user?.uid,
+  });
+
+  const handlePurchaseComplete = async (transaction: Purchase) => {
+    const success = await initializeCredits({
+      purchaseId: transaction.transactionId,
+      productId: transaction.productId,
+    });
+
+    if (success) {
+      Alert.alert('Success', 'Credits added!');
+    }
+  };
+}
+```
+
+### useCreditChecker
+Check credit availability before operations.
+
+```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>;
+}
+```
+
+**Usage:**
+```typescript
+function PreCheckFeature() {
+  const { checkCreditsAvailable } = useCreditChecker();
+
+  const handleCheck = async () => {
+    const result = await checkCreditsAvailable(user?.uid, 10);
+
+    if (!result.canProceed) {
+      Alert.alert(
+        'Insufficient Credits',
+        `You need ${result.required} credits but have ${result.currentBalance}`
+      );
+      return;
+    }
+
+    await executeFeature();
+  };
+}
+```
+
+## Usage Patterns
+
+### Two-Step Credit Process
+
+```typescript
+function TwoStepCreditProcess() {
+  const { checkCreditsAvailable } = useCreditChecker();
+  const { deductCreditsAfterSuccess } = useCreditChecker();
+
+  const handleOperation = async () => {
+    // Step 1: Check credits
+    const check = await checkCreditsAvailable(user?.uid, 10);
+
+    if (!check.canProceed) {
+      showPaywall({ required: 10 });
+      return;
+    }
+
+    try {
+      // Step 2: Perform operation
+      await performOperation();
+
+      // Step 3: Deduct credits after success
+      await deductCreditsAfterSuccess(user?.uid, 10);
+
+      Alert.alert('Success', 'Operation completed');
+    } catch (error) {
+      Alert.alert('Error', 'Operation failed');
+    }
+  };
+}
+```
+
+### With Loading and Error States
+
+```typescript
+function CreditOperation() {
+  const { credits, isLoading, error } = useCredits({ userId: user?.uid });
+  const { deductCredit } = useDeductCredit({
+    userId: user?.uid,
+  });
+
+  const handleDeduct = async () => {
+    if (isLoading) return;
+
+    const success = await deductCredit(5);
+
+    if (success) {
+      await executeFeature();
+    } else {
+      Alert.alert('Failed', 'Could not deduct credits');
+    }
+  };
+
+  return (
+    <View>
+      {error && <ErrorBanner message={error.message} />}
+      {isLoading ? (
+        <LoadingSpinner />
+      ) : (
+        <>
+          <Text>Credits: {credits}</Text>
+          <Button onPress={handleDeduct} disabled={isLoading}>
+            Use 5 Credits
+          </Button>
+        </>
+      )}
+    </View>
+  );
+}
+```
+
+### With Auto-Initialization
+
+```typescript
+function AutoInitialize() {
+  const { isPremium } = usePremium();
+  const { credits } = useCredits({ userId: user?.uid });
+  const { initializeCredits, isInitializing } = useInitializeCredits({
+    userId: user?.uid,
+  });
+
+  useEffect(() => {
+    // Auto-initialize if premium but no credits
+    if (isPremium && !credits && !isInitializing) {
+      initializeCredits();
+    }
+  }, [isPremium, credits]);
+
+  return <YourComponent />;
+}
+```
+
+## Best Practices
+
+1. **Check Balance First**: Always check before deducting
+2. **Handle Loading**: Show loading states appropriately
+3. **Error Recovery**: Handle deduction failures gracefully
+4. **Optimistic Updates**: Use optimistic updates for better UX
+5. **Track Usage**: Log all credit operations
+6. **Auto-Init**: Initialize credits after premium purchase
+7. **Test Scenarios**: Test zero credits, max credits, failures
+
+## Related
+
+- [useCredits Hook Documentation](../../../presentation/hooks/useCredits.md)
+- [useDeductCredit Hook Documentation](../../../presentation/hooks/useDeductCredit.md)
+- [Credits Entity](../../domain/entities/README.md)