@umituz/react-native-subscription 2.14.97 → 2.14.99

package/src/domains/wallet/README.md

@@ -0,0 +1,292 @@
+# Wallet Domain
+
+Kredi bakiyesi yönetimi, işlem geçmişi takibi ve ürün metadata yönetimi için kapsamlı çözüm.
+
+## Özellikler
+
+- **Kredi Bakiyesi Yönetimi**: Kullanıcıların kredi bakiyelerini takip edin ve yönetin
+- **İşlem Geçmişi**: Tüm kredi işlemlerini geçmişte takip edin
+- **Ürün Metadata**: Satın alınan ürünler için metadata yönetimi
+- **Tür Desteği**: Farklı kredi türlerini (AI, premium, vb.) destekleyin
+
+## Kurulum
+
+### 1. Service Konfigürasyonu
+
+```typescript
+import { configureProductMetadataService } from '@umituz/react-native-subscription';
+
+// Service'i konfigüre edin
+configureProductMetadataService({
+  firebase: firebaseInstance,
+  storage: storageInstance,
+});
+```
+
+### 2. Repository Oluşturma
+
+```typescript
+import { createTransactionRepository } from '@umituz/react-native-subscription';
+
+const transactionRepository = createTransactionRepository({
+  firebase: firebaseInstance,
+  userId: 'user-123',
+});
+```
+
+## Kullanım
+
+### useWallet Hook
+
+Kredi bakiyesi ve temel cüzdan işlemleri için:
+
+```typescript
+import { useWallet } from '@umituz/react-native-subscription';
+
+function MyComponent() {
+  const { balance, loading, error, refresh } = useWallet({
+    userId: 'user-123',
+  });
+
+  if (loading) return <ActivityIndicator />;
+  if (error) return <Text>Error: {error.message}</Text>;
+
+  return (
+    <View>
+      <Text>Balance: {balance.credits}</Text>
+      <Button onPress={refresh} title="Refresh" />
+    </View>
+  );
+}
+```
+
+### useTransactionHistory Hook
+
+İşlem geçmişini görüntülemek için:
+
+```typescript
+import { useTransactionHistory } from '@umituz/react-native-subscription';
+
+function TransactionHistory() {
+  const { transactions, loading, hasMore, loadMore } = useTransactionHistory({
+    userId: 'user-123',
+    limit: 20,
+  });
+
+  return (
+    <FlatList
+      data={transactions}
+      keyExtractor={(item) => item.id}
+      onEndReached={hasMore ? loadMore : undefined}
+      renderItem={({ item }) => (
+        <View>
+          <Text>{item.reason}</Text>
+          <Text>{item.amount} credits</Text>
+          <Text>{new Date(item.timestamp).toLocaleString()}</Text>
+        </View>
+      )}
+    />
+  );
+}
+```
+
+### useProductMetadata Hook
+
+Ürün metadata yönetimi için:
+
+```typescript
+import { useProductMetadata } from '@umituz/react-native-subscription';
+
+function ProductInfo() {
+  const { metadata, loading, updateMetadata } = useProductMetadata({
+    userId: 'user-123',
+    productId: 'premium_monthly',
+  });
+
+  const handleUpdate = async () => {
+    await updateMetadata({
+      lastUsed: new Date().toISOString(),
+      usageCount: (metadata?.usageCount || 0) + 1,
+    });
+  };
+
+  return (
+    <View>
+      <Text>Product: {metadata?.productId}</Text>
+      <Text>Usage: {metadata?.usageCount} times</Text>
+      <Button onPress={handleUpdate} title="Update Usage" />
+    </View>
+  );
+}
+```
+
+## Bileşenler
+
+### BalanceCard
+
+Kredi bakiyesini gösteren kart bileşeni:
+
+```typescript
+import { BalanceCard } from '@umituz/react-native-subscription';
+
+<BalanceCard
+  balance={150}
+  currency="USD"
+  translations={{
+    title: "Your Balance",
+    subtitle: "Credits available",
+  }}
+/>
+```
+
+### TransactionItem
+
+Tek işlem öğesi:
+
+```typescript
+import { TransactionItem } from '@umituz/react-native-subscription';
+
+<TransactionItem
+  transaction={{
+    id: 'tx-123',
+    amount: -50,
+    reason: 'purchase',
+    timestamp: '2024-01-01T00:00:00Z',
+  }}
+  translations={{
+    purchase: 'Purchase',
+    refund: 'Refund',
+  }}
+/>
+```
+
+### TransactionList
+
+İşlem listesi bileşeni:
+
+```typescript
+import { TransactionList } from '@umituz/react-native-subscription';
+
+<TransactionList
+  transactions={transactions}
+  loading={loading}
+  onEndReached={loadMore}
+  translations={{
+    title: 'Transaction History',
+    empty: 'No transactions yet',
+  }}
+/>
+```
+
+### WalletScreen
+
+Tam cüzdan ekranı:
+
+```typescript
+import { WalletScreen } from '@umituz/react-native-subscription';
+
+<WalletScreen
+  userId="user-123"
+  config={{
+    showBalance: true,
+    showHistory: true,
+    enableRefresh: true,
+  }}
+  translations={{
+    title: 'My Wallet',
+    balance: 'Balance',
+    history: 'History',
+  }}
+/>
+```
+
+## API Referansı
+
+### Tip Tanımlamaları
+
+```typescript
+interface CreditBalance {
+  credits: number;
+  lastUpdated: string;
+}
+
+interface TransactionLog {
+  id: string;
+  amount: number;
+  reason: TransactionReason;
+  timestamp: string;
+  metadata?: Record<string, any>;
+}
+
+type TransactionReason =
+  | 'purchase'
+  | 'refund'
+  | 'usage'
+  | 'bonus'
+  | 'expiration';
+```
+
+### Yardımcı Fonksiyonlar
+
+```typescript
+// Kredi maliyeti hesaplama
+import { getCreditCost, creditsToDollars } from '@umituz/react-native-subscription';
+
+const cost = getCreditCost('ai_generation'); // AI işlem maliyeti
+const dollars = creditsToDollars(150, 0.01); // 150 kredi = $1.50
+```
+
+## Hata Yönetimi
+
+```typescript
+import {
+  WalletError,
+  CreditLimitError,
+  handleWalletError,
+} from '@umituz/react-native-subscription';
+
+try {
+  // İşlem
+} catch (error) {
+  if (error instanceof CreditLimitError) {
+    console.log('Yetersiz bakiye');
+  }
+  handleWalletError(error);
+}
+```
+
+## Örnek Uygulama
+
+```typescript
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import {
+  useWallet,
+  useTransactionHistory,
+  BalanceCard,
+  TransactionList,
+} from '@umituz/react-native-subscription';
+
+export default function WalletExample() {
+  const { balance, refresh } = useWallet({ userId: 'user-123' });
+  const { transactions, loading } = useTransactionHistory({
+    userId: 'user-123',
+  });
+
+  return (
+    <View>
+      <BalanceCard balance={balance} />
+      <Button title="Refresh" onPress={refresh} />
+      <TransactionList transactions={transactions} loading={loading} />
+    </View>
+  );
+}
+```
+
+## Best Practices
+
+1. **Kredi Türleri**: Farklı kredi türleri için farklı cost config'leri kullanın
+2. **Hata Yönetimi**: Tüm işlemleri try-catch blokları içinde sarın
+3. **Loading State**: Yüklenme durumlarını her zaman gösterin
+4. **Refresh**: Kullanıcıya manuel refresh imkanı verin
+5. **Transaction Log**: Tüm işlemleri loglayın ve audit trail tutun

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

@@ -0,0 +1,108 @@
+# Wallet Domain
+
+Wallet domain containing credits and transaction management logic.
+
+## Overview
+
+The wallet domain manages user credits, transactions, and credit allocation strategies. It handles credit initialization after purchase, credit deduction, and transaction history.
+
+## Structure
+
+```
+wallet/
+├── domain/
+│   ├── entities/      # Credit and transaction entities
+│   ├── errors/        # Wallet-specific errors
+│   ├── types/         # Wallet type definitions
+│   └── mappers/       # Data transformation mappers
+├── infrastructure/
+│   ├── repositories/  # Credits persistence
+│   └── services/      # Credit operations
+├── presentation/
+│   ├── hooks/         # React hooks for credits
+│   ├── components/    # Credit UI components
+│   └── screens/       # Credit management screens
+```
+
+## Core Concepts
+
+### Credits
+User credits balance that can be consumed for premium features.
+
+```typescript
+interface UserCredits {
+  credits: number;
+  purchasedAt: Date;
+  lastUpdatedAt: Date;
+}
+```
+
+### Transactions
+Record of credit transactions (additions and deductions).
+
+```typescript
+interface Transaction {
+  id: string;
+  amount: number;
+  reason: string;
+  timestamp: Date;
+  type: 'purchase' | 'deduction' | 'bonus' | 'renewal';
+}
+```
+
+### Allocation Modes
+
+**ACCUMULATE**: Add credits to existing balance (renewals)
+```typescript
+// Renewal: 100 + 100 = 200 credits
+```
+
+**REPLACE**: Replace existing credits (new purchase)
+```typescript
+// New purchase: Old balance replaced with new amount
+```
+
+## Key Features
+
+- **Duplicate Protection**: Prevent duplicate credit allocations
+- **Transactional Operations**: Atomic credit updates
+- **Optimistic Updates**: Immediate UI with rollback
+- **Transaction History**: Complete audit trail
+- **Monthly Reset**: Credits reset on subscription renewal
+
+## Usage
+
+```typescript
+// In hooks or components
+import { useCredits } from './presentation/hooks/useCredits';
+import { useDeductCredit } from './presentation/hooks/useDeductCredit';
+
+function Feature() {
+  const { credits } = useCredits({ userId: user?.uid });
+  const { deductCredit } = useDeductCredit({
+    userId: user?.uid,
+    onCreditsExhausted: () => showPaywall(),
+  });
+
+  const handleUseFeature = async () => {
+    const success = await deductCredit(5);
+    if (success) {
+      await executeFeature();
+    }
+  };
+}
+```
+
+## Best Practices
+
+1. **Check Balance First**: Verify credits before operations
+2. **Handle Exhaustion**: Provide upgrade path when credits low
+3. **Track Usage**: Log all credit transactions
+4. **Reset Credits**: Clear credits on subscription renewal
+5. **Test Edge Cases**: Zero credits, max credits, duplicates
+
+## Related
+
+- [Credits README](./README.md)
+- [Credits Entity](./domain/entities/Credits.md)
+- [useCredits Hook](../../presentation/hooks/useCredits.md)

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)