@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/domains/wallet/README.md

@@ -1,292 +1,51 @@
 # Wallet Domain
 
-Kredi bakiyesi yönetimi, işlem geçmişi takibi ve ürün metadata yönetimi için kapsamlı çözüm.
+Credit balance management, transaction history tracking, and product metadata management.
 
-## Özellikler
+## Location
 
-- **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
+`src/domains/wallet/`
 
-## Kurulum
+## Strategy
 
-### 1. Service Konfigürasyonu
+Implements layered architecture for credit management with domain layer (entities, value objects, errors), infrastructure layer (repositories, Firebase services, mappers), and presentation layer (hooks, components). Handles initialization, operations, and transaction history with real-time updates.
 
-```typescript
-import { configureProductMetadataService } from '@umituz/react-native-subscription';
+## Restrictions
 
-// Service'i konfigüre edin
-configureProductMetadataService({
-  firebase: firebaseInstance,
-  storage: storageInstance,
-});
-```
+### REQUIRED
 
-### 2. Repository Oluşturma
+- All operations require authenticated user
+- Credit operations MUST be validated server-side
+- All credit changes MUST be recorded in transaction history
+- MUST handle insufficient credits gracefully
 
-```typescript
-import { createTransactionRepository } from '@umituz/react-native-subscription';
+### PROHIBITED
 
-const transactionRepository = createTransactionRepository({
-  firebase: firebaseInstance,
-  userId: 'user-123',
-});
-```
+- MUST NOT allow client-side credit modifications without server validation
+- MUST NOT deduct credits without sufficient balance
+- MUST NOT expose internal repository logic to UI
+- MUST NOT store credit balance in AsyncStorage (use secure backend)
 
-## Kullanım
+### CRITICAL
 
-### useWallet Hook
+- Always validate credit amounts (must be positive)
+- Always implement optimistic updates with rollback
+- Never trust client-side credit balance for security decisions
+- Must implement retry logic for failed operations
+- Always sanitize transaction reasons to prevent injection attacks
 
-Kredi bakiyesi ve temel cüzdan işlemleri için:
+## AI Agent Guidelines
 
-```typescript
-import { useWallet } from '@umituz/react-native-subscription';
+When implementing credit operations:
+1. Always check balance before deducting
+2. Always provide transaction reason and metadata
+3. Always handle insufficient credits gracefully
+4. Always implement optimistic updates with rollback
+5. Never trust client-side balance for security
 
-function MyComponent() {
-  const { balance, loading, error, refresh } = useWallet({
-    userId: 'user-123',
-  });
+## Related Documentation
 
-  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
+- [Credits Repository](infrastructure/README.md)
+- [useCredits Hook](../../presentation/hooks/README.md)
+- [UserCredits Entity](domain/entities/README.md)
+- [Transaction Errors](domain/errors/README.md)

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

@@ -0,0 +1,209 @@
+# Wallet Domain
+
+Credit balance management, transaction history tracking, and product metadata management.
+
+## Location
+
+**Directory**: `src/domains/wallet/`
+
+**Type**: Domain
+
+## Strategy
+
+### Domain Architecture
+
+The Wallet Domain implements a layered architecture for credit management:
+
+1. **Domain Layer**
+   - Entities: `UserCredits`, `Transaction`, `CreditType`
+   - Value Objects: `CreditAmount`, `TransactionReason`
+   - Errors: `InsufficientCreditsError`, `InvalidCreditAmountError`
+
+2. **Infrastructure Layer**
+   - Repositories: `CreditsRepository`, `TransactionsRepository`
+   - Firebase Services: Data persistence and real-time updates
+   - Mappers: Entity ↔ DTO transformations
+
+3. **Presentation Layer**
+   - Hooks: `useCredits`, `useDeductCredit`, `useInitializeCredits`
+   - Components: Credit displays, transaction lists
+
+### Credit Flow
+
+1. **Initialization**
+   - Fetch initial credit balance from backend
+   - Subscribe to real-time credit updates
+   - Cache in TanStack Query
+
+2. **Operations**
+   - Check balance before operations
+   - Deduct credits optimistically
+   - Sync with backend
+   - Rollback on failure
+
+3. **Transaction History**
+   - Record all credit operations
+   - Provide audit trail
+   - Support pagination and filtering
+
+### Integration Points
+
+- **Firebase**: Real database for persistence
+- **TanStack Query**: Client-side caching and state management
+- **RevenueCat**: Purchase flow integration
+- **Presentation Hooks**: UI integration layer
+
+## Restrictions
+
+### REQUIRED
+
+- **User Authentication**: All operations require authenticated user
+- **Server Validation**: Credit operations MUST be validated server-side
+- **Transaction Recording**: All credit changes MUST be recorded in transaction history
+- **Error Handling**: MUST handle insufficient credits gracefully
+
+### PROHIBITED
+
+- **NEVER** allow client-side credit modifications without server validation
+- **NEVER** deduct credits without sufficient balance
+- **DO NOT** expose internal repository logic to UI
+- **NEVER** store credit balance in AsyncStorage (use secure backend)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** validate credit amounts (must be positive)
+- **ALWAYS** implement optimistic updates with rollback
+- **NEVER** trust client-side credit balance for security decisions
+- **MUST** implement retry logic for failed operations
+- **ALWAYS** sanitize transaction reasons to prevent injection attacks
+
+## Rules
+
+### Repository Initialization
+
+```typescript
+// CORRECT - Proper repository setup
+const creditsRepository = new CreditsRepository({
+  firebase: firebaseInstance,
+  userId: user.uid,
+});
+
+// INCORRECT - Missing userId
+const creditsRepository = new CreditsRepository({
+  firebase: firebaseInstance,
+  // userId undefined
+});
+```
+
+### Credit Operations
+
+```typescript
+// CORRECT - Check before deduct
+const hasEnoughCredits = await creditsRepository.checkBalance(requiredAmount);
+if (hasEnoughCredits) {
+  await creditsRepository.deductCredits(requiredAmount, 'feature_usage');
+}
+
+// INCORRECT - Deduct without checking
+await creditsRepository.deductCredits(requiredAmount, 'feature_usage');
+// May throw InsufficientCreditsError
+```
+
+### Transaction Recording
+
+```typescript
+// CORRECT - Record all operations
+await creditsRepository.deductCredits(
+  amount,
+  reason,
+  { featureId, metadata } // Include context
+);
+
+// INCORRECT - Missing context
+await creditsRepository.deductCredits(amount, reason);
+// Lost audit trail
+```
+
+### Error Handling
+
+```typescript
+// CORRECT - Handle specific errors
+try {
+  await creditsRepository.deductCredits(amount, reason);
+} catch (error) {
+  if (error instanceof InsufficientCreditsError) {
+    showUpgradePrompt();
+  } else if (error instanceof InvalidCreditAmountError) {
+    showInvalidAmountError();
+  } else {
+    showGenericError();
+  }
+}
+
+// INCORRECT - Generic error handling
+try {
+  await creditsRepository.deductCredits(amount, reason);
+} catch (error) {
+  console.error(error); // Doesn't help user
+}
+```
+
+## AI Agent Guidelines
+
+### When Implementing Credit Operations
+
+1. **Always** check balance before deducting
+2. **Always** provide transaction reason and metadata
+3. **Always** handle insufficient credits gracefully
+4. **Always** implement optimistic updates with rollback
+5. **Never** trust client-side balance for security
+
+### Integration Checklist
+
+- [ ] Initialize repository with valid userId
+- [ ] Implement error boundaries
+- [ ] Handle loading states
+- [ ] Provide user feedback for all operations
+- [ ] Test with insufficient credits
+- [ ] Test with zero balance
+- [ ] Test transaction history
+- [ ] Test real-time updates
+- [ ] Implement retry logic
+- [ ] Sanitize user inputs
+
+### Common Patterns
+
+1. **Pre-check**: Always verify balance before operations
+2. **Optimistic Updates**: Update UI immediately, rollback on failure
+3. **Transaction Context**: Include featureId and metadata in all operations
+4. **Error Recovery**: Provide upgrade path when credits insufficient
+5. **Real-time Sync**: Subscribe to credit changes for multi-device sync
+6. **Audit Trail**: Maintain complete transaction history
+7. **Caching**: Use TanStack Query for performance
+8. **Validation**: Validate all inputs on both client and server
+
+## Related Documentation
+
+- **Credits Repository**: `infrastructure/repositories/README.md`
+- **useCredits Hook**: `../../presentation/hooks/useCredits.md`
+- **useDeductCredit Hook**: `../../presentation/hooks/useDeductCredit.md`
+- **UserCredits Entity**: `domain/entities/README.md`
+- **Transaction Errors**: `domain/errors/README.md`
+
+## Domain Structure
+
+```
+src/domains/wallet/
+├── domain/
+│   ├── entities/           # Core entities
+│   │   ├── UserCredits.ts
+│   │   └── Transaction.ts
+│   ├── value-objects/      # Value objects
+│   └── errors/             # Domain errors
+├── infrastructure/
+│   ├── repositories/       # Data access
+│   └── services/          # External services
+└── presentation/
+    ├── hooks/             # React hooks
+    └── components/        # UI components
+```

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

@@ -1,108 +1,41 @@
 # Wallet Domain
 
+## Location
 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
-
+## Strategy
+The wallet domain manages user credits, transactions, and credit allocation strategies with duplicate protection, transactional operations, and complete audit trail.
+
+## Restrictions
+
+### REQUIRED
+- Must check credit balance before operations
+- Must handle credit exhaustion gracefully
+- Must track all credit transactions
+- Must reset credits on subscription renewal
+
+### PROHIBITED
+- DO NOT perform operations without balance check
+- DO NOT allow duplicate credit allocations
+- DO NOT skip transaction logging
+- DO NOT bypass credit exhaustion handling
+
+### CRITICAL SAFETY
+- Credit allocations MUST be protected against duplicates
+- All credit operations MUST be transactional
+- Transaction history MUST be complete and accurate
+- Credit exhaustion MUST trigger upgrade flow
+
+## AI Agent Guidelines
+1. Always verify credit balance before performing operations
+2. Handle credit exhaustion with clear upgrade path
+3. Log all credit transactions for audit trail
+4. Implement monthly credit reset on subscription renewal
+5. Test edge cases: zero credits, max credits, duplicates
+6. Use ACCUMULATE mode for renewals, REPLACE for new purchases
+7. Provide optimistic updates with rollback capability
+
+## Related Documentation
 - [Credits README](./README.md)
 - [Credits Entity](./domain/entities/Credits.md)
 - [useCredits Hook](../../presentation/hooks/useCredits.md)