@umituz/react-native-subscription 2.14.97 → 2.14.98

package/src/domains/wallet/domain/entities/README.md

@@ -0,0 +1,122 @@
+# Wallet Domain Entities
+
+Core entities for credits and transaction management.
+
+## Overview
+
+This directory contains domain entities representing credits, transactions, and wallet-related business concepts.
+
+## Entities
+
+### UserCredits
+Represents user's credit balance and metadata.
+
+```typescript
+interface UserCredits {
+  credits: number;           // Current credit balance
+  purchasedAt: Date;         // When credits were purchased
+  lastUpdatedAt: Date;      // Last update timestamp
+}
+
+interface CreditsResult {
+  success: boolean;
+  data?: UserCredits;
+  error?: {
+    code: string;
+    message: string;
+  };
+  duplicate?: boolean;       // If this was a duplicate operation
+}
+```
+
+**Usage:**
+```typescript
+const credits: UserCredits = {
+  credits: 100,
+  purchasedAt: new Date('2024-01-01'),
+  lastUpdatedAt: new Date('2024-01-15'),
+};
+```
+
+### Transaction
+Represents a credit transaction record.
+
+```typescript
+interface Transaction {
+  id: string;
+  amount: number;           // Positive for additions, negative for deductions
+  reason: string;           // Description of transaction
+  timestamp: Date;          // When transaction occurred
+  type: TransactionType;    // Transaction category
+}
+
+type TransactionType =
+  | 'purchase'      // Initial purchase
+  | 'deduction'     // Feature usage
+  | 'bonus'         // Bonus credits
+  | 'renewal'       // Subscription renewal
+  | 'adjustment';   // Manual adjustment
+```
+
+**Usage:**
+```typescript
+const transaction: Transaction = {
+  id: 'tx_123',
+  amount: -5,
+  reason: 'ai_generation',
+  timestamp: new Date(),
+  type: 'deduction',
+};
+```
+
+### CreditPackage
+Represents a credit package for purchase.
+
+```typescript
+interface CreditPackage {
+  id: string;
+  amount: number;           // Number of credits
+  price: number;            // Price in currency units
+  currency: string;         // Currency code (USD, EUR, etc.)
+  description?: string;
+}
+```
+
+## Key Operations
+
+### Check Balance
+```typescript
+function hasEnoughCredits(credits: UserCredits, required: number): boolean {
+  return credits.credits >= required;
+}
+```
+
+### Calculate Remaining
+```typescript
+function calculateRemaining(credits: UserCredits, spent: number): number {
+  return Math.max(0, credits.credits - spent);
+}
+```
+
+### Validate Credits
+```typescript
+function validateCredits(amount: number): void {
+  if (amount < 0) {
+    throw new Error('Credits cannot be negative');
+  }
+}
+```
+
+## Best Practices
+
+1. **Immutability**: Treat entities as immutable values
+2. **Validation**: Validate in entity methods
+3. **Type Safety**: Use strict TypeScript types
+4. **Business Rules**: Keep business logic in entities
+5. **Serialization**: Handle date serialization properly
+
+## Related
+
+- [Wallet Domain](../README.md)
+- [Credits Repository](../../infrastructure/repositories/README.md)
+- [useCredits Hook](../../../../presentation/hooks/useCredits.md)

package/src/domains/wallet/domain/errors/README.md

@@ -0,0 +1,157 @@
+# Wallet Domain Errors
+
+Domain-specific errors for wallet and credit operations.
+
+## Overview
+
+This directory contains custom error classes representing wallet-related error conditions.
+
+## Error Types
+
+### CreditsExhaustedError
+Thrown when user doesn't have enough credits for an operation.
+
+```typescript
+class CreditsExhaustedError extends Error {
+  constructor(
+    public currentBalance: number,
+    public required: number
+  ) {
+    super(
+      `Insufficient credits: ${currentBalance}/${required} required`,
+      'CREDITS_EXHAUSTED'
+    );
+    this.name = 'CreditsExhaustedError';
+  }
+}
+```
+
+**Usage:**
+```typescript
+import { CreditsExhaustedError } from './errors/CreditsExhaustedError';
+
+function deductCredits(credits: UserCredits, amount: number) {
+  if (credits.credits < amount) {
+    throw new CreditsExhaustedError(credits.credits, amount);
+  }
+  // Proceed with deduction
+}
+```
+
+### DuplicatePurchaseError
+Thrown when attempting to add credits for a duplicate purchase ID.
+
+```typescript
+class DuplicatePurchaseError extends Error {
+  constructor(
+    public purchaseId: string,
+    public existingCredits: UserCredits
+  ) {
+    super(
+      `Duplicate purchase ID: ${purchaseId}`,
+      'DUPLICATE_PURCHASE'
+    );
+    this.name = 'DuplicatePurchaseError';
+  }
+}
+```
+
+**Usage:**
+```typescript
+try {
+  await repository.initializeCredits(userId, purchaseId);
+} catch (error) {
+  if (error instanceof DuplicatePurchaseError) {
+    console.log('Credits already added for this purchase');
+  }
+}
+```
+
+### CreditsValidationError
+Thrown when credit validation fails.
+
+```typescript
+class CreditsValidationError extends Error {
+  constructor(
+    message: string,
+    public code: string
+  ) {
+    super(message, code);
+    this.name = 'CreditsValidationError';
+  }
+}
+```
+
+**Usage:**
+```typescript
+function validateCreditAmount(amount: number) {
+  if (amount < 0) {
+    throw new CreditsValidationError(
+      'Credit amount cannot be negative',
+      'INVALID_AMOUNT'
+    );
+  }
+  if (amount > 10000) {
+    throw new CreditsValidationError(
+      'Credit amount exceeds maximum',
+      'EXCEEDS_MAXIMUM'
+    );
+  }
+}
+```
+
+## Error Handling Pattern
+
+```typescript
+import {
+  CreditsExhaustedError,
+  DuplicatePurchaseError,
+  CreditsValidationError
+} from './errors';
+
+async function handleCreditOperation(userId: string, cost: number) {
+  try {
+    const result = await repository.deductCredit(userId, cost);
+    return result;
+  } catch (error) {
+    if (error instanceof CreditsExhaustedError) {
+      // Show paywall or upgrade prompt
+      showPaywall({ required: cost, current: error.currentBalance });
+    } else if (error instanceof DuplicatePurchaseError) {
+      // Log and continue (not a critical error)
+      console.warn('Duplicate purchase detected');
+    } else if (error instanceof CreditsValidationError) {
+      // Log validation error
+      console.error('Validation failed:', error.message);
+    } else {
+      // Unexpected error
+      console.error('Unexpected error:', error);
+    }
+    throw error;
+  }
+}
+```
+
+## Error Codes Reference
+
+| Code | Description | Recovery |
+|------|-------------|----------|
+| `CREDITS_EXHAUSTED` | Not enough credits | Show paywall/upgrade |
+| `DUPLICATE_PURCHASE` | Duplicate purchase ID | Ignore (idempotent) |
+| `INVALID_AMOUNT` | Invalid credit amount | Validate input |
+| `EXCEEDS_MAXIMUM` | Amount too large | Cap at maximum |
+| `USER_NOT_FOUND` | User doesn't exist | Create user record |
+| `INITIALIZATION_FAILED` | Credit init failed | Retry operation |
+
+## Best Practices
+
+1. **Specific Errors**: Use specific error types for different scenarios
+2. **Error Context**: Include relevant data in error properties
+3. **Graceful Handling**: Handle errors appropriately at boundaries
+4. **Logging**: Log errors for debugging
+5. **User Feedback**: Convert errors to user-friendly messages
+
+## Related
+
+- [Wallet Entities](../entities/README.md)
+- [Credits Repository](../../infrastructure/repositories/README.md)

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)