@umituz/react-native-subscription 2.14.97 → 2.14.99

package/src/domain/errors/README.md

@@ -0,0 +1,307 @@
+# Domain Errors
+
+Domain-specific error types for subscription system.
+
+## Purpose
+
+Domain errors provide typed, contextual error handling for business logic failures. They make error handling explicit and type-safe.
+
+## Error Hierarchy
+
+```
+Error (JavaScript)
+└── SubscriptionError (Domain base)
+    ├── SubscriptionValidationError
+    ├── SubscriptionRepositoryError
+    ├── SubscriptionOperationError
+    └── InsufficientCreditsError
+```
+
+## Error Types
+
+### SubscriptionError
+
+Base error for all subscription-related errors.
+
+```typescript
+class SubscriptionError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly context?: Record<string, any>
+  ) {
+    super(message);
+    this.name = 'SubscriptionError';
+  }
+}
+```
+
+### SubscriptionValidationError
+
+Thrown when validation fails.
+
+```typescript
+throw new SubscriptionValidationError('Invalid user ID');
+```
+
+### SubscriptionRepositoryError
+
+Thrown when repository operations fail.
+
+```typescript
+throw new SubscriptionRepositoryError('Database connection failed');
+```
+
+### InsufficientCreditsError
+
+Thrown when user doesn't have enough credits.
+
+```typescript
+throw new InsufficientCreditsError(
+  'Not enough credits',
+  {
+    required: 10,
+    available: 5,
+    featureId: 'export',
+  }
+);
+```
+
+## Usage
+
+### Throwing Errors
+
+```typescript
+function deductCredits(amount: number) {
+  if (amount <= 0) {
+    throw new SubscriptionValidationError(
+      'Amount must be positive',
+      'INVALID_AMOUNT',
+      { amount }
+    );
+  }
+
+  if (currentBalance < amount) {
+    throw new InsufficientCreditsError(
+      'Insufficient credits',
+      {
+        required: amount,
+        available: currentBalance,
+      }
+    );
+  }
+}
+```
+
+### Catching Errors
+
+```typescript
+try {
+  await purchasePackage(packageToPurchase);
+} catch (error) {
+  if (error instanceof InsufficientCreditsError) {
+    console.log(`Need ${error.context.required} credits`);
+    showPaywall();
+  } else if (error instanceof SubscriptionValidationError) {
+    console.error('Validation error:', error.message);
+  } else if (error instanceof SubscriptionError) {
+    console.error('Subscription error:', error.code, error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Type Guards
+
+```typescript
+function isSubscriptionError(error: unknown): error is SubscriptionError {
+  return error instanceof SubscriptionError;
+}
+
+function isInsufficientCreditsError(error: unknown): error is InsufficientCreditsError {
+  return error instanceof InsufficientCreditsError;
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `INVALID_USER_ID` | User ID is invalid or missing |
+| `INVALID_PRODUCT_ID` | Product ID is not recognized |
+| `INVALID_AMOUNT` | Amount is invalid (e.g., negative) |
+| `INSUFFICIENT_CREDITS` | User doesn't have enough credits |
+| `SUBSCRIPTION_EXPIRED` | Subscription has expired |
+| `SUBSCRIPTION_NOT_FOUND` | Subscription doesn't exist |
+| `REPOSITORY_ERROR` | Database/repository error |
+| `NETWORK_ERROR` | Network connectivity issue |
+| `PURCHASE_CANCELLED` | User cancelled purchase |
+| `PURCHASE_FAILED` | Purchase operation failed |
+
+## Error Context
+
+Errors can include contextual information:
+
+```typescript
+interface InsufficientCreditsContext {
+  required: number;
+  available: number;
+  featureId?: string;
+  currency?: string;
+}
+
+throw new InsufficientCreditsError(
+  'Insufficient credits',
+  {
+    required: 10,
+    available: 5,
+    featureId: 'export',
+    currency: 'credits',
+  }
+);
+```
+
+## Custom Errors
+
+Create your own domain errors:
+
+```typescript
+class FeatureAccessError extends SubscriptionError {
+  constructor(
+    featureId: string,
+    public readonly requiredTier: UserTier,
+    public readonly currentTier: UserTier
+  ) {
+    super(
+      `Feature "${featureId}" requires ${requiredTier} tier`,
+      'FEATURE_ACCESS_DENIED',
+      { featureId, requiredTier, currentTier }
+    );
+    this.name = 'FeatureAccessError';
+  }
+}
+
+// Usage
+if (!canAccessFeature('advanced_analytics')) {
+  throw new FeatureAccessError(
+    'advanced_analytics',
+    'premium',
+    userTier
+  );
+}
+```
+
+## Error Handling Patterns
+
+### 1. Try-Catch with Type Guards
+
+```typescript
+try {
+  await executeOperation();
+} catch (error) {
+  if (error instanceof InsufficientCreditsError) {
+    handleInsufficientCredits(error);
+  } else if (error instanceof SubscriptionError) {
+    handleSubscriptionError(error);
+  } else {
+    handleUnexpectedError(error);
+  }
+}
+```
+
+### 2. Result Type
+
+```typescript
+type Result<T, E extends Error = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+async function deductCredits(
+  amount: number
+): Promise<Result<number, InsufficientCreditsError>> {
+  if (currentBalance < amount) {
+    return {
+      success: false,
+      error: new InsufficientCreditsError('...', {...}),
+    };
+  }
+
+  return { success: true, data: newBalance };
+}
+
+// Usage
+const result = await deductCredits(10);
+if (result.success) {
+  console.log('New balance:', result.data);
+} else {
+  console.error('Error:', result.error.message);
+}
+```
+
+### 3. Error Boundary
+
+```typescript
+class SubscriptionErrorBoundary extends React.Component {
+  state = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: any) {
+    if (error instanceof SubscriptionError) {
+      analytics().logEvent('subscription_error', {
+        code: error.code,
+        message: error.message,
+      });
+    }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+## Best Practices
+
+1. **Use specific error types** - Don't use generic Error
+2. **Include context** - Add relevant data to errors
+3. **Document error codes** - List all possible errors
+4. **Handle gracefully** - Show user-friendly messages
+5. **Log errors** - Track for debugging
+6. **Don't swallow errors** - Always handle or rethrow
+7. **Use type guards** - Enable type-safe error handling
+
+## Testing
+
+```typescript
+describe('InsufficientCreditsError', () => {
+  it('should create error with context', () => {
+    const error = new InsufficientCreditsError('Not enough credits', {
+      required: 10,
+      available: 5,
+    });
+
+    expect(error.context.required).toBe(10);
+    expect(error.context.available).toBe(5);
+  });
+
+  it('should be instance of SubscriptionError', () => {
+    const error = new InsufficientCreditsError('...', {...});
+
+    expect(error).toBeInstanceOf(SubscriptionError);
+  });
+});
+```
+
+## Related
+
+- [Domain Entities](../entities/README.md)
+- [Value Objects](../value-objects/README.md)
+- [Domain Layer](../../README.md)

package/src/domain/value-objects/README.md

@@ -0,0 +1,186 @@
+# Domain Value Objects
+
+Value objects for the subscription domain.
+
+## Purpose
+
+Value objects are immutable objects that represent concepts by their attributes rather than identity. They are used to ensure validity and prevent primitive obsession.
+
+## Value Objects
+
+### SubscriptionConfig
+
+Configuration object for subscription system.
+
+```typescript
+interface SubscriptionConfig {
+  revenueCatApiKey: string;
+  revenueCatEntitlementId: string;
+  plans: Record<string, Plan>;
+  defaultPlan: string;
+  features: ConfigFeatures;
+  ui?: ConfigUI;
+  onStatusChanged?: (userId: string, status: SubscriptionStatus) => void;
+  onError?: (error: Error) => void;
+}
+```
+
+**Usage:**
+```typescript
+import { SubscriptionConfig } from '@umituz/react-native-subscription/domain';
+
+const config: SubscriptionConfig = {
+  revenueCatApiKey: 'your_key',
+  revenueCatEntitlementId: 'premium',
+  plans: {
+    monthly: monthlyPlan,
+    annual: annualPlan,
+  },
+  defaultPlan: 'monthly',
+  features: {
+    requireAuth: true,
+    allowRestore: true,
+  },
+};
+```
+
+## Characteristics
+
+### 1. Immutable
+
+```typescript
+const config = SubscriptionConfig.create({...});
+// config.apiKey = 'new_key'; // Error: Cannot assign
+```
+
+### 2. Value-Based Equality
+
+```typescript
+const config1 = SubscriptionConfig.create({...});
+const config2 = SubscriptionConfig.create({...});
+
+config1.equals(config2); // true (if same values)
+```
+
+### 3. Self-Validating
+
+```typescript
+const config = SubscriptionConfig.create({
+  apiKey: '', // Invalid!
+  entitlementId: 'premium',
+});
+// Throws ValidationError
+```
+
+## Creating Value Objects
+
+### Factory Method
+
+```typescript
+const config = SubscriptionConfig.create({
+  apiKey: 'your_key',
+  entitlementId: 'premium',
+});
+```
+
+### Builder Pattern
+
+```typescript
+const config = SubscriptionConfig.builder()
+  .apiKey('your_key')
+  .entitlementId('premium')
+  .addPlan('monthly', monthlyPlan)
+  .addPlan('annual', annualPlan)
+  .build();
+```
+
+## Common Value Objects
+
+### Money
+
+```typescript
+class Money {
+  private constructor(
+    private amount: number,
+    private currency: string
+  ) {}
+
+  static create(amount: number, currency: string): Money {
+    if (amount < 0) throw new Error('Amount cannot be negative');
+    return new Money(amount, currency);
+  }
+
+  format(): string {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: this.currency,
+    }).format(this.amount);
+  }
+
+  add(other: Money): Money {
+    if (this.currency !== other.currency) {
+      throw new Error('Cannot add different currencies');
+    }
+    return new Money(this.amount + other.amount, this.currency);
+  }
+}
+```
+
+### DateRange
+
+```typescript
+class DateRange {
+  constructor(
+    private start: Date,
+    private end: Date
+  ) {}
+
+  includes(date: Date): boolean {
+    return date >= this.start && date <= this.end;
+  }
+
+  durationInDays(): number {
+    return Math.ceil(
+      (this.end.getTime() - this.start.getTime()) / (1000 * 60 * 60 * 24)
+    );
+  }
+}
+```
+
+## Best Practices
+
+1. **Make immutable** - All properties readonly
+2. **Validate on creation** - Fail fast
+3. **Override equality** - Compare by value, not reference
+4. **Use for complex attributes** - Don't use for simple primitives
+5. **Keep small** - Value objects should be focused
+
+## Testing
+
+```typescript
+describe('SubscriptionConfig', () => {
+  it('should create valid config', () => {
+    const config = SubscriptionConfig.create({
+      apiKey: 'test_key',
+      entitlementId: 'premium',
+    });
+
+    expect(config.apiKey).toBe('test_key');
+  });
+
+  it('should reject invalid config', () => {
+    expect(() => {
+      SubscriptionConfig.create({
+        apiKey: '',
+        entitlementId: 'premium',
+      });
+    }).toThrow();
+  });
+});
+```
+
+## Related
+
+- [Domain Entities](../entities/README.md)
+- [Domain Errors](../errors/README.md)
+- [Domain Layer](../../README.md)

package/src/domains/README.md

@@ -0,0 +1,240 @@
+# Domains
+
+This directory contains specialized domain modules that implement specific business logic and features.
+
+## Overview
+
+The `domains` directory organizes business logic into focused, self-contained modules. Each domain follows Domain-Driven Design (DDD) principles and Clean Architecture patterns.
+
+## Domain Modules
+
+### Wallet Domain (`wallet/`)
+
+Manages credits, transactions, and wallet operations.
+
+**Key Features:**
+- Credit balance tracking
+- Transaction history
+- Credit deduction and allocation
+- Purchase initialization
+- Duplicate protection
+
+**Structure:**
+```
+wallet/
+├── domain/              # Business logic and entities
+│   ├── entities/        # UserCredits, Transaction, CreditPackage
+│   ├── types/           # Type definitions
+│   └── mappers/         # Data transformation
+├── infrastructure/      # External integrations
+│   ├── repositories/    # Data persistence
+│   └── services/        # External services
+└── presentation/        # UI layer
+    ├── hooks/           # React hooks
+    ├── components/      # React components
+    └── screens/         # Screen components
+```
+
+**Key Entities:**
+- `UserCredits`: Credit balance and allocations
+- `Transaction`: Credit transaction records
+- `CreditPackage`: Purchasable credit packages
+
+**Allocation Modes:**
+- **ACCUMULATE**: Add credits on renewal (default)
+- **REPLACE**: Replace existing credits with new allocation
+
+**Related:**
+- [Wallet Domain README](./wallet/README.md)
+- [Wallet Entities](./wallet/domain/entities/README.md)
+- [Wallet Hooks](./wallet/presentation/hooks/README.md)
+
+### Paywall Domain (`paywall/`)
+
+Manages paywall display, triggers, and purchase flows.
+
+**Key Features:**
+- Paywall visibility management
+- Trigger-based paywall display
+- Package selection and comparison
+- Purchase operations
+- Feedback collection
+
+**Structure:**
+```
+paywall/
+├── domain/              # Business logic
+│   └── entities/        # PaywallTrigger, PaywallConfig, PaywallState
+├── components/          # UI components
+│   ├── PaywallScreen/
+│   ├── PackageCard/
+│   └── FeatureComparison/
+└── hooks/               # React hooks
+    └── usePaywallOperations/
+```
+
+**Triggers:**
+- `premium_feature`: User attempts premium feature
+- `credit_gate`: Insufficient credits
+- `manual`: Manually triggered
+- `onboarding_complete`: After onboarding
+- `usage_limit`: Reached usage limit
+
+**Related:**
+- [Paywall Domain README](./paywall/README.md)
+- [Paywall Entities](./paywall/entities/README.md)
+- [Paywall Components](./paywall/components/README.md)
+
+### Config Domain (`config/`)
+
+Manages subscription and feature configuration.
+
+**Key Features:**
+- Package configuration
+- Feature flags
+- Subscription settings
+- Paywall customization
+
+**Structure:**
+```
+config/
+├── domain/              # Configuration entities
+│   ├── entities/        # Config entities
+│   └── value-objects/   # Configuration value objects
+└── utils/               # Configuration utilities
+```
+
+**Related:**
+- [Config Domain README](./config/README.md)
+
+## Architecture Principles
+
+### 1. Domain-Driven Design (DDD)
+Each domain represents a distinct business capability with:
+- Clear boundaries
+- Ubiquitous language
+- Domain entities
+- Business rules
+
+### 2. Clean Architecture
+Each domain follows layered architecture:
+- **Domain Layer**: Business logic, entities (pure)
+- **Application Layer**: Use cases, orchestration
+- **Infrastructure Layer**: External integrations (persistence, APIs)
+- **Presentation Layer**: UI components, hooks
+
+### 3. Independence
+Domains are independent and can:
+- Be developed in isolation
+- Have their own data stores
+- Be tested independently
+- Scale independently
+
+### 4. Communication
+Domains communicate through:
+- Well-defined interfaces
+- Events (when needed)
+- Shared kernels (when necessary)
+
+## Usage Patterns
+
+### Using Wallet Domain
+
+```typescript
+import { useCredits } from './wallet/presentation/hooks';
+import { CreditBalanceCard } from './wallet/presentation/components';
+
+function MyComponent() {
+  const { credits, transactions } = useCredits({ userId: user?.uid });
+
+  return (
+    <CreditBalanceCard
+      credits={credits}
+      balance={calculateBalance(credits)}
+    />
+  );
+}
+```
+
+### Using Paywall Domain
+
+```typescript
+import { usePaywallOperations } from './paywall/hooks';
+
+function MyScreen() {
+  const { handlePurchase } = usePaywallOperations({
+    userId: user?.uid,
+    isAnonymous: false,
+  });
+
+  const onBuyPress = () => {
+    handlePurchase(selectedPackage);
+  };
+}
+```
+
+### Using Config Domain
+
+```typescript
+import { getPackageConfiguration } from './config/utils';
+
+const packages = getPackageConfiguration('premium');
+```
+
+## Adding New Domains
+
+When adding a new domain:
+
+1. **Create Domain Structure**
+```bash
+src/domains/your-domain/
+├── domain/
+│   ├── entities/
+│   ├── value-objects/
+│   └── types/
+├── infrastructure/
+│   ├── repositories/
+│   └── services/
+└── presentation/
+    ├── hooks/
+    ├── components/
+    └── screens/
+```
+
+2. **Define Entities**
+   - Create core business entities
+   - Define business rules
+   - Implement validations
+
+3. **Implement Infrastructure**
+   - Create repositories for data persistence
+   - Implement external service integrations
+   - Add mappers for data transformation
+
+4. **Create Presentation Layer**
+   - Implement React hooks
+   - Create UI components
+   - Build screens
+
+5. **Add Documentation**
+   - Create README for domain
+   - Document entities
+   - Provide usage examples
+
+## Best Practices
+
+1. **Encapsulation**: Keep domain logic isolated
+2. **Purity**: Domain layer should have no external dependencies
+3. **Interfaces**: Depend on abstractions, not concretions
+4. **Testing**: Each domain should be independently testable
+5. **Documentation**: Document business rules and entities
+6. **Type Safety**: Use TypeScript for all domain models
+7. **Validation**: Validate at domain boundaries
+8. **Error Handling**: Use domain-specific errors
+
+## Related
+
+- [Domain Layer README](../domain/README.md)
+- [Application Layer README](../application/README.md)
+- [Infrastructure Layer README](../infrastructure/README.md)
+- [RevenueCat Integration README](../revenuecat/README.md)