@umituz/react-native-subscription 2.14.98 → 2.14.99

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

@@ -0,0 +1,441 @@
+# RevenueCat Domain Value Objects
+
+Value objects for RevenueCat integration.
+
+## Overview
+
+This directory contains value objects - immutable types that represent concepts in the RevenueCat domain with no identity. Value objects are defined by their attributes rather than an identity.
+
+## Value Objects
+
+### EntitlementId
+
+Represents an entitlement identifier.
+
+```typescript
+class EntitlementId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('Entitlement ID cannot be empty');
+    }
+    this.value = value.trim();
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  equals(other: EntitlementId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+// Usage
+const premiumId = new EntitlementId('premium');
+```
+
+### OfferingId
+
+Represents an offering identifier.
+
+```typescript
+class OfferingId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    const validIds = ['default', 'annual_offer', 'lifetime_offer'];
+    if (!validIds.includes(value)) {
+      throw new Error(`Invalid offering ID: ${value}`);
+    }
+    this.value = value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  isDefault(): boolean {
+    return this.value === 'default';
+  }
+
+  equals(other: OfferingId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+// Usage
+const defaultOffering = new OfferingId('default');
+const annualOffering = new OfferingId('annual_offer');
+```
+
+### PackageIdentifier
+
+Represents a package identifier.
+
+```typescript
+class PackageIdentifier {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('Package identifier cannot be empty');
+    }
+    this.value = value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  getType(): PackageType {
+    if (this.value.includes('monthly')) return 'monthly';
+    if (this.value.includes('annual')) return 'annual';
+    if (this.value.includes('lifetime')) return 'lifetime';
+    if (this.value.includes('weekly')) return 'weekly';
+    return 'single_purchase';
+  }
+
+  isSubscription(): boolean {
+    const type = this.getType();
+    return type === 'monthly' || type === 'annual' || type === 'weekly';
+  }
+
+  equals(other: PackageIdentifier): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+// Usage
+const monthlyPackage = new PackageIdentifier('$rc_monthly');
+console.log(monthlyPackage.getType()); // 'monthly'
+console.log(monthlyPackage.isSubscription()); // true
+```
+
+### ProductId
+
+Represents a product identifier.
+
+```typescript
+class ProductId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('Product ID cannot be empty');
+    }
+    this.value = value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  equals(other: ProductId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+// Usage
+const productId = new ProductId('com.app.premium.monthly');
+```
+
+### Money
+
+Represents monetary value with currency.
+
+```typescript
+class Money {
+  private readonly amount: number;
+  private readonly currency: string;
+
+  constructor(amount: number, currency: string) {
+    if (amount < 0) {
+      throw new Error('Amount cannot be negative');
+    }
+    if (currency.length !== 3) {
+      throw new Error('Currency must be ISO 4217 code (3 letters)');
+    }
+    this.amount = amount;
+    this.currency = currency.toUpperCase();
+  }
+
+  getAmount(): number {
+    return this.amount;
+  }
+
+  getCurrency(): string {
+    return this.currency;
+  }
+
+  format(locale: string = 'en-US'): string {
+    return new Intl.NumberFormat(locale, {
+      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);
+  }
+
+  multiply(factor: number): Money {
+    return new Money(this.amount * factor, this.currency);
+  }
+
+  equals(other: Money): boolean {
+    return this.amount === other.amount && this.currency === other.currency;
+  }
+
+  toString(): string {
+    return this.format();
+  }
+}
+
+// Usage
+const price = new Money(9.99, 'USD');
+console.log(price.format()); // '$9.99'
+console.log(price.format('tr-TR')); // '9,99 $'
+
+const annualPrice = price.multiply(12);
+console.log(annualPrice.format()); // '$119.88'
+```
+
+### SubscriptionPeriod
+
+Represents a subscription period.
+
+```typescript
+class SubscriptionPeriod {
+  private readonly value: number;
+  private readonly unit: 'day' | 'week' | 'month' | 'year';
+
+  constructor(value: number, unit: 'day' | 'week' | 'month' | 'year') {
+    if (value <= 0) {
+      throw new Error('Period value must be positive');
+    }
+    this.value = value;
+    this.unit = unit;
+  }
+
+  getValue(): number {
+    return this.value;
+  }
+
+  getUnit(): string {
+    return this.unit;
+  }
+
+  inDays(): number {
+    switch (this.unit) {
+      case 'day': return this.value;
+      case 'week': return this.value * 7;
+      case 'month': return this.value * 30; // Approximate
+      case 'year': return this.value * 365;
+    }
+  }
+
+  inMonths(): number {
+    switch (this.unit) {
+      case 'day': return this.value / 30;
+      case 'week': return this.value / 4;
+      case 'month': return this.value;
+      case 'year': return this.value * 12;
+    }
+  }
+
+  format(locale: string = 'en-US'): string {
+    const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'always' });
+    return formatter.format(this.value, this.unit);
+  }
+
+  equals(other: SubscriptionPeriod): boolean {
+    return this.value === other.value && this.unit === other.unit;
+  }
+
+  toString(): string {
+    return this.format();
+  }
+}
+
+// Usage
+const monthly = new SubscriptionPeriod(1, 'month');
+const annual = new SubscriptionPeriod(1, 'year');
+
+console.log(monthly.format()); // '1 month'
+console.log(annual.inDays()); // 365
+console.log(annual.inMonths()); // 12
+```
+
+### PurchaseToken
+
+Represents a purchase transaction token.
+
+```typescript
+class PurchaseToken {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('Purchase token cannot be empty');
+    }
+    this.value = value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  equals(other: PurchaseToken): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  // Mask sensitive parts
+  mask(): string {
+    if (this.value.length <= 8) {
+      return '***';
+    }
+    const start = this.value.substring(0, 4);
+    const end = this.value.substring(this.value.length - 4);
+    return `${start}...${end}`;
+  }
+}
+
+// Usage
+const token = new PurchaseToken('abc123def456ghi789');
+console.log(token.mask()); // 'abc1...i789'
+```
+
+## Usage Examples
+
+### Creating Value Objects
+
+```typescript
+import {
+  EntitlementId,
+  OfferingId,
+  PackageIdentifier,
+  Money,
+  SubscriptionPeriod,
+} from './value-objects';
+
+// Create entitlement ID
+const premiumId = new EntitlementId('premium');
+
+// Create offering ID
+const defaultOffering = new OfferingId('default');
+
+// Create package identifier
+const monthlyPackage = new PackageIdentifier('$rc_monthly');
+
+// Create price
+const price = new Money(9.99, 'USD');
+
+// Create subscription period
+const period = new SubscriptionPeriod(1, 'month');
+```
+
+### Comparing Value Objects
+
+```typescript
+const id1 = new EntitlementId('premium');
+const id2 = new EntitlementId('premium');
+const id3 = new EntitlementId('pro');
+
+console.log(id1.equals(id2)); // true
+console.log(id1.equals(id3)); // false
+
+const price1 = new Money(9.99, 'USD');
+const price2 = new Money(9.99, 'USD');
+const price3 = new Money(19.99, 'USD');
+
+console.log(price1.equals(price2)); // true
+console.log(price1.equals(price3)); // false
+```
+
+### Performing Operations
+
+```typescript
+// Money arithmetic
+const monthlyPrice = new Money(9.99, 'USD');
+const annualPrice = monthlyPrice.multiply(12);
+const withDiscount = annualPrice.multiply(0.8); // 20% off
+
+console.log(monthlyPrice.format()); // '$9.99'
+console.log(annualPrice.format()); // '$119.88'
+console.log(withDiscount.format()); // '$95.90'
+
+// Period conversions
+const period = new SubscriptionPeriod(1, 'year');
+console.log(period.inDays()); // 365
+console.log(period.inMonths()); // 12
+console.log(period.format('tr-TR')); // '1 yıl'
+```
+
+### Validation
+
+```typescript
+// Valid values
+const validEntitlement = new EntitlementId('premium');
+const validMoney = new Money(10.00, 'USD');
+const validPeriod = new SubscriptionPeriod(1, 'month');
+
+// Invalid values (will throw)
+try {
+  new EntitlementId(''); // Error: Entitlement ID cannot be empty
+} catch (error) {
+  console.error(error.message);
+}
+
+try {
+  new Money(-10, 'USD'); // Error: Amount cannot be negative
+} catch (error) {
+  console.error(error.message);
+}
+
+try {
+  new SubscriptionPeriod(0, 'month'); // Error: Period value must be positive
+} catch (error) {
+  console.error(error.message);
+}
+```
+
+## Best Practices
+
+1. **Immutability**: Never modify value objects after creation
+2. **Validation**: Validate in constructor, fail fast
+3. **Equality**: Implement proper equality based on values
+4. **Formatting**: Provide locale-aware formatting
+5. **Operations**: Return new instances for operations
+6. **Type Safety**: Use TypeScript for compile-time checks
+7. **Serialization**: Provide toString/JSON methods if needed
+
+## Related
+
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Entities](../entities/README.md)
+- [RevenueCat Types](../types/README.md)

package/src/revenuecat/infrastructure/README.md

@@ -0,0 +1,50 @@
+# RevenueCat Infrastructure
+
+Infrastructure layer for RevenueCat integration.
+
+## Overview
+
+This directory contains concrete implementations of RevenueCat interfaces, handling communication with the RevenueCat SDK and external services.
+
+## Structure
+
+```
+infrastructure/
+├── handlers/     # Event handlers and callbacks
+├── services/     # Service implementations
+└── utils/        # Utility functions
+```
+
+## Components
+
+### Handlers
+
+Event handlers for RevenueCat lifecycle events.
+
+**See**: [Handlers README](./handlers/README.md)
+
+### Services
+
+Service implementations for RevenueCat operations.
+
+**See**: [Services README](./services/README.md)
+
+### Utils
+
+Utility functions for common operations.
+
+**See**: [Utils README](./utils/README.md)
+
+## Key Responsibilities
+
+1. **SDK Integration**: Direct integration with RevenueCat SDK
+2. **Error Handling**: Converting SDK errors to domain errors
+3. **Data Transformation**: Mapping SDK types to domain types
+4. **Event Handling**: Managing purchase and customer info events
+5. **Configuration**: Setting up and configuring RevenueCat
+
+## Related
+
+- [RevenueCat Integration](../README.md)
+- [RevenueCat Application](../application/README.md)
+- [RevenueCat Domain](../domain/README.md)

package/src/revenuecat/infrastructure/handlers/README.md

@@ -0,0 +1,218 @@
+# RevenueCat Infrastructure Handlers
+
+Event handlers for RevenueCat lifecycle events.
+
+## Overview
+
+This directory contains handler implementations for managing RevenueCat events including purchase callbacks, customer info changes, and error handling.
+
+## Handlers
+
+### PurchaseCompletedHandler
+
+Handles successful purchase completion.
+
+```typescript
+class PurchaseCompletedHandler {
+  async handle(result: PurchaseResult): Promise<void> {
+    // 1. Extract transaction info
+    const { customerInfo, transaction } = result;
+
+    // 2. Update local subscription status
+    await updateSubscriptionStatus(customerInfo);
+
+    // 3. Handle credits allocation
+    if (isPremiumPurchase(transaction)) {
+      await allocatePremiumCredits(customerInfo.originalAppUserId);
+    }
+
+    // 4. Trigger success callbacks
+    triggerSuccessCallbacks(result);
+
+    // 5. Log purchase
+    logPurchaseEvent(transaction);
+  }
+}
+```
+
+### PurchaseErrorHandler
+
+Handles purchase errors.
+
+```typescript
+class PurchaseErrorHandler {
+  async handle(error: PurchasesError): Promise<void> {
+    // 1. Categorize error
+    const category = categorizeError(error);
+
+    // 2. Show appropriate message
+    showErrorMessage(category);
+
+    // 3. Log error
+    logPurchaseError(error);
+
+    // 4. Trigger error callbacks
+    triggerErrorCallbacks(error);
+
+    // 5. Offer recovery options
+    if (category === 'network') {
+      offerRetry();
+    }
+  }
+}
+```
+
+### CustomerInfoChangedHandler
+
+Handles customer info changes.
+
+```typescript
+class CustomerInfoChangedHandler {
+  async handle(customerInfo: CustomerInfo): Promise<void> {
+    // 1. Check for subscription changes
+    const changes = detectSubscriptionChanges(customerInfo);
+
+    // 2. Update local state
+    await updateLocalState(customerInfo);
+
+    // 3. Handle status changes
+    if (changes.subscriptionChanged) {
+      await handleSubscriptionChange(changes);
+    }
+
+    // 4. Trigger UI refresh
+    triggerUIRefresh();
+  }
+}
+```
+
+### EntitlementsChangedHandler
+
+Handles entitlement changes.
+
+```typescript
+class EntitlementsChangedHandler {
+  async handle(entitlements: EntitlementInfos): Promise<void> {
+    // 1. Check premium status
+    const premium = entitlements.premium;
+
+    // 2. Update access controls
+    if (premium?.isActive) {
+      grantPremiumAccess();
+    } else {
+      revokePremiumAccess();
+    }
+
+    // 3. Handle new entitlements
+    for (const [key, entitlement] of Object.entries(entitlements)) {
+      if (entitlement.isActive) {
+        await handleNewEntitlement(key, entitlement);
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Setting Up Handlers
+
+```typescript
+import { Purchases } from '@revenuecat/purchases-capacitor';
+import {
+  PurchaseCompletedHandler,
+  PurchaseErrorHandler,
+  CustomerInfoChangedHandler,
+} from './handlers';
+
+// Set up customer info listener
+Purchases.addCustomerInfoUpdateListener((customerInfo) => {
+  const handler = new CustomerInfoChangedHandler();
+  handler.handle(customerInfo);
+});
+
+// Use in purchase flow
+async function purchasePackage(pkg: Package) {
+  const completedHandler = new PurchaseCompletedHandler();
+  const errorHandler = new PurchaseErrorHandler();
+
+  try {
+    const result = await Purchases.purchasePackage({ aPackage: pkg });
+    await completedHandler.handle(result);
+  } catch (error) {
+    await errorHandler.handle(error);
+  }
+}
+```
+
+### Custom Handlers
+
+```typescript
+class CustomPurchaseHandler {
+  constructor(
+    private onSuccess: (result: PurchaseResult) => void,
+    private onError: (error: PurchasesError) => void
+  ) {}
+
+  async handle(result: PurchaseResult | PurchasesError): Promise<void> {
+    if (isPurchasesError(result)) {
+      await this.onError(result);
+    } else {
+      await this.onSuccess(result);
+    }
+  }
+}
+
+// Usage
+const handler = new CustomPurchaseHandler(
+  (result) => {
+    Alert.alert('Success', 'Purchase completed!');
+    navigation.navigate('Home');
+  },
+  (error) => {
+    Alert.alert('Error', error.message);
+  }
+);
+```
+
+## Error Categorization
+
+```typescript
+function categorizeError(error: PurchasesError): ErrorCategory {
+  switch (error.code) {
+    case 'PURCHASE_CANCELLED':
+      return 'cancelled';
+    case 'NETWORK_ERROR':
+      return 'network';
+    case 'INVALID_CREDENTIALS_ERROR':
+      return 'config';
+    case 'PRODUCT_NOT_AVAILABLE_FOR_PURCHASE':
+      return 'availability';
+    default:
+      return 'unknown';
+  }
+}
+
+type ErrorCategory =
+  | 'cancelled'
+  | 'network'
+  | 'config'
+  | 'availability'
+  | 'unknown';
+```
+
+## Best Practices
+
+1. **Immutability**: Don't mutate incoming data
+2. **Error Boundaries**: Handle errors gracefully
+3. **Logging**: Log all events for debugging
+4. **Callbacks**: Invoke registered callbacks appropriately
+5. **Async Handling**: Use async/await for asynchronous operations
+6. **Validation**: Validate incoming data before processing
+7. **Recovery**: Provide recovery options when possible
+
+## Related
+
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Services](../services/README.md)
+- [RevenueCat Errors](../../domain/errors/README.md)