@umituz/react-native-subscription 2.14.96 → 2.14.98

package/src/domains/paywall/entities/README.md

@@ -0,0 +1,199 @@
+# Paywall Entities
+
+Domain entities for paywall configuration and state management.
+
+## Overview
+
+This directory contains entities representing paywall configuration, triggers, and display logic.
+
+## Entities
+
+### PaywallTrigger
+Represents an event that triggers paywall display.
+
+```typescript
+interface PaywallTrigger {
+  type: PaywallTriggerType;
+  feature?: string;
+  packageName?: string;
+  context?: Record<string, any>;
+  timestamp: number;
+}
+
+type PaywallTriggerType =
+  | 'premium_feature'     // Premium feature access attempt
+  | 'credit_gate'         // Credit gate failure
+  | 'manual'              // User manually opened
+  | 'onboarding_complete' // Post-onboarding
+  | 'usage_limit'         // Free tier limit reached
+  | 'subscription_expired'; // Subscription expired
+```
+
+**Usage:**
+```typescript
+const trigger: PaywallTrigger = {
+  type: 'premium_feature',
+  feature: 'ai_generation',
+  context: { cost: 5 },
+  timestamp: Date.now(),
+};
+```
+
+### PaywallConfig
+Configuration for paywall display.
+
+```typescript
+interface PaywallConfig {
+  title: string;
+  subtitle: string;
+  description?: string;
+  features: string[];
+  highlightBenefit?: string;  // Main value proposition
+  packages: PaywallPackage[];
+  defaultPackage?: string;    // Pre-selected package
+  dismissible: boolean;
+  showCloseButton: boolean;
+  onUpgrade: (pkg: PaywallPackage) => void;
+  onDismiss: () => void;
+}
+```
+
+**Usage:**
+```typescript
+const config: PaywallConfig = {
+  title: 'Upgrade to Premium',
+  subtitle: 'Unlock all features',
+  features: [
+    'Unlimited access',
+    'Priority support',
+    'Ad-free experience',
+  ],
+  packages: availablePackages,
+  dismissible: true,
+  showCloseButton: true,
+  onUpgrade: (pkg) => purchasePackage(pkg),
+  onDismiss: () => navigation.goBack(),
+};
+```
+
+### PaywallPackage
+Represents a subscription package displayed in paywall.
+
+```typescript
+interface PaywallPackage {
+  identifier: string;         // Unique package ID
+  productIdentifier: string;  // RevenueCat product ID
+  title: string;              // Display title
+  description: string;        // Package description
+  price: number;              // Price in local currency
+  pricePerMonth?: number;     // Monthly equivalent (for annual)
+  currencyCode: string;       // Currency code
+  period: PackagePeriod;      // Billing period
+  features: string[];         // Package features
+  popular?: boolean;          // Highlight as popular
+  savings?: number;           // Savings amount (for annual)
+  badge?: string;             // Custom badge text
+}
+
+type PackagePeriod = 'monthly' | 'annual' | 'lifetime';
+```
+
+**Usage:**
+```typescript
+const premiumPackage: PaywallPackage = {
+  identifier: 'premium_annual',
+  productIdentifier: 'com.app.premium.annual',
+  title: 'Premium Annual',
+  description: 'Best value - Save 50%',
+  price: 99.99,
+  pricePerMonth: 8.33,
+  currencyCode: 'USD',
+  period: 'annual',
+  features: [
+    'Unlimited access',
+    'Priority support',
+    'Ad-free',
+    'Advanced features',
+  ],
+  popular: true,
+  savings: 20.00,
+  badge: 'BEST VALUE',
+};
+```
+
+### PaywallState
+Manages current paywall state and context.
+
+```typescript
+interface PaywallState {
+  visible: boolean;
+  trigger?: PaywallTrigger;
+  selectedPackage?: string;
+  pendingAction?: () => void;  // Execute after upgrade
+  metadata?: {
+    userId?: string;
+    screen?: string;          // Screen where paywall shown
+    previousScreen?: string;  // Screen before paywall
+  };
+}
+```
+
+**Usage:**
+```typescript
+const state: PaywallState = {
+  visible: true,
+  trigger: {
+    type: 'premium_feature',
+    feature: 'ai_generation',
+    timestamp: Date.now(),
+  },
+  selectedPackage: 'premium_annual',
+  pendingAction: () => executeAIGeneration(),
+  metadata: {
+    userId: 'user-123',
+    screen: 'AIGeneration',
+  },
+};
+```
+
+## Key Operations
+
+### Create Trigger
+```typescript
+function createTrigger(
+  type: PaywallTriggerType,
+  context?: Record<string, any>
+): PaywallTrigger {
+  return {
+    type,
+    context,
+    timestamp: Date.now(),
+  };
+}
+```
+
+### Validate Config
+```typescript
+function validatePaywallConfig(config: PaywallConfig): void {
+  if (!config.title) throw new Error('Title is required');
+  if (!config.packages || config.packages.length === 0) {
+    throw new Error('At least one package is required');
+  }
+  if (config.defaultPackage && !config.packages.find(p => p.identifier === config.defaultPackage)) {
+    throw new Error('Default package must be in packages list');
+  }
+}
+```
+
+## Best Practices
+
+1. **Rich Context**: Include context in triggers for analytics
+2. **Validation**: Validate configurations before use
+3. **Immutability**: Treat entities as immutable values
+4. **Type Safety**: Use strict TypeScript types
+5. **Analytics**: Track all paywall events and triggers
+
+## Related
+
+- [Paywall README](../README.md)
+- [PaywallVisibility Hook](../../presentation/hooks/usePaywallVisibility.md)

package/src/domains/paywall/hooks/README.md

@@ -0,0 +1,129 @@
+# Paywall Hooks
+
+React hooks for paywall management and subscription upgrades.
+
+## Overview
+
+This directory contains React hooks specifically for paywall functionality.
+
+## Hooks
+
+### usePaywallVisibility
+Manages paywall visibility state.
+
+```typescript
+function usePaywallVisibility(): {
+  showPaywall: boolean;
+  setShowPaywall: (visible: boolean) => void;
+  openPaywall: () => void;
+  closePaywall: () => void;
+}
+```
+
+**Usage:**
+```typescript
+function PaywallWrapper() {
+  const { showPaywall, closePaywall } = usePaywallVisibility();
+
+  return (
+    <>
+      <YourApp />
+      <Modal visible={showPaywall} onRequestClose={closePaywall}>
+        <PaywallScreen onClose={closePaywall} />
+      </Modal>
+    </>
+  );
+}
+```
+
+### usePaywallOperations
+Handles paywall purchase operations.
+
+```typescript
+function usePaywallOperations(config: {
+  userId: string | undefined;
+  isAnonymous: boolean;
+  onPaywallClose?: () => void;
+  onPurchaseSuccess?: () => void;
+  onAuthRequired?: () => void;
+}): {
+  handlePurchase: (pkg: Package) => Promise<boolean>;
+  handleRestore: () => Promise<boolean>;
+  pendingPackage: Package | null;
+}
+```
+
+**Usage:**
+```typescript
+function Paywall() {
+  const { handlePurchase, handleRestore } = usePaywallOperations({
+    userId: user?.uid,
+    isAnonymous: !user,
+    onPurchaseSuccess: () => navigation.goBack(),
+    onAuthRequired: () => showAuthModal(),
+  });
+
+  return (
+    <View>
+      <PackageList onSelectPackage={handlePurchase} />
+      <Button onPress={handleRestore}>Restore</Button>
+    </View>
+  );
+}
+```
+
+## Usage Patterns
+
+### Feature Gating
+```typescript
+function useFeatureGate(feature: string) {
+  const { openPaywall } = usePaywallVisibility();
+  const { isPremium } = usePremium();
+
+  const gateFeature = useCallback(() => {
+    if (!isPremium) {
+      analytics.track('paywall_triggered', { feature });
+      openPaywall();
+      return false;
+    }
+    return true;
+  }, [isPremium, openPaywall]);
+
+  return gateFeature;
+}
+```
+
+### Trigger-Based Paywall
+```typescript
+function useTriggeredPaywall() {
+  const { openPaywall } = usePaywallVisibility();
+
+  const showPaywallForFeature = (feature: string, context?: any) => {
+    openPaywall();
+    // Store trigger context for analytics
+    PaywallTracker.record({
+      type: 'premium_feature',
+      feature,
+      context,
+      timestamp: Date.now(),
+    });
+  };
+
+  return { showPaywallForFeature };
+}
+```
+
+## Best Practices
+
+1. **Centralized State**: Use global paywall visibility
+2. **Auth Integration**: Handle authentication before purchase
+3. **Pending Actions**: Store pending actions for post-purchase
+4. **Analytics**: Track all paywall interactions
+5. **Error Handling**: Handle purchase failures gracefully
+6. **User Context**: Show relevant paywall based on context
+
+## Related
+
+- [usePaywallVisibility](../../presentation/hooks/usePaywallVisibility.md)
+- [usePaywallOperations](../../presentation/hooks/usePaywallOperations.md)
+- [PremiumGate Hook](../../presentation/hooks/usePremiumGate.md)

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)