@umituz/react-native-subscription 2.14.98 → 2.14.99

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

@@ -0,0 +1,325 @@
+# RevenueCat Infrastructure Services
+
+Service implementations for RevenueCat operations.
+
+## Overview
+
+This directory contains concrete implementations of RevenueCat interfaces, providing the actual integration with the RevenueCat SDK.
+
+## Services
+
+### RevenueCatServiceImpl
+
+Main service implementation for RevenueCat operations.
+
+```typescript
+import { Purchases } from '@revenuecat/purchases-capacitor';
+import type { IRevenueCatService } from '../../application/ports/IRevenueCatService';
+
+class RevenueCatServiceImpl implements IRevenueCatService {
+  // Configuration
+  async configure(params: {
+    apiKey: string;
+    userId?: string;
+    observerMode?: boolean;
+  }): Promise<void> {
+    await Purchases.configure({
+      apiKey: params.apiKey,
+      appUserID: params.userId,
+      observerMode: params.observerMode ?? false,
+    });
+  }
+
+  // Purchasing
+  async purchasePackage(pkg: Package): Promise<PurchaseResult> {
+    return await Purchases.purchasePackage({ aPackage: pkg });
+  }
+
+  async purchaseProduct(productId: string): Promise<PurchaseResult> {
+    return await Purchases.purchaseProduct({ productIdentifier: productId });
+  }
+
+  async restorePurchases(): Promise<RestoreResult> {
+    return await Purchases.restorePurchases();
+  }
+
+  // Customer Information
+  async getCustomerInfo(): Promise<CustomerInfo> {
+    return await Purchases.getCustomerInfo();
+  }
+
+  async getCustomerInfoUserId(): Promise<string | null> {
+    const info = await this.getCustomerInfo();
+    return info.originalAppUserId;
+  }
+
+  // Offerings
+  async getOfferings(): Promise<Offerings> {
+    return await Purchases.getOfferings();
+  }
+
+  async getCurrentOffering(): Promise<Offering | null> {
+    const offerings = await this.getOfferings();
+    return offerings.current;
+  }
+
+  // Entitlements
+  async checkEntitlement(entitlementId: string): Promise<boolean> {
+    const info = await this.getCustomerInfo();
+    return info.entitlements[entitlementId]?.isActive ?? false;
+  }
+
+  async checkEntitlementInfo(
+    entitlementId: string
+  ): Promise<EntitlementInfo | null> {
+    const info = await this.getCustomerInfo();
+    return info.entitlements[entitlementId] ?? null;
+  }
+
+  // Subscriber Attributes
+  async setAttributes(attributes: SubscriberAttributes): Promise<void> {
+    await Purchases.setAttributes(attributes);
+  }
+
+  async setEmail(email: string): Promise<void> {
+    await Purchases.setEmail(email);
+  }
+
+  async setPhoneNumber(phoneNumber: string): Promise<void> {
+    await Purchases.setPhoneNumber(phoneNumber);
+  }
+
+  // Log Out
+  async logOut(): Promise<void> {
+    await Purchases.logOut();
+  }
+}
+```
+
+### RevenueCatServiceProvider
+
+Provides the RevenueCat service instance.
+
+```typescript
+class RevenueCatServiceProvider {
+  private static instance: IRevenueCatService | null = null;
+
+  static getInstance(): IRevenueCatService {
+    if (!this.instance) {
+      this.instance = new RevenueCatServiceImpl();
+    }
+    return this.instance;
+  }
+
+  static configure(config: {
+    apiKey: string;
+    userId?: string;
+    observerMode?: boolean;
+  }): IRevenueCatService {
+    const service = this.getInstance();
+    service.configure(config);
+    return service;
+  }
+}
+```
+
+## Usage
+
+### Initializing the Service
+
+```typescript
+import { RevenueCatServiceProvider } from './services/RevenueCatServiceProvider';
+
+// Configure RevenueCat
+const service = RevenueCatServiceProvider.configure({
+  apiKey: 'your_api_key',
+  userId: user?.uid,
+  observerMode: false,
+});
+```
+
+### Making Purchases
+
+```typescript
+import { RevenueCatServiceProvider } from './services/RevenueCatServiceProvider';
+
+async function purchasePremium(userId: string) {
+  const service = RevenueCatServiceProvider.getInstance();
+
+  // Get offerings
+  const offerings = await service.getOfferings();
+  const monthlyPackage = offerings.current?.monthly;
+
+  if (!monthlyPackage) {
+    throw new Error('No package available');
+  }
+
+  // Purchase
+  const result = await service.purchasePackage(monthlyPackage);
+
+  if (result.error) {
+    throw new Error(result.error.message);
+  }
+
+  // Check entitlement
+  const hasPremium = await service.checkEntitlement('premium');
+  if (hasPremium) {
+    console.log('Premium activated!');
+  }
+
+  return result;
+}
+```
+
+### Restoring Purchases
+
+```typescript
+async function restorePurchases() {
+  const service = RevenueCatServiceProvider.getInstance();
+
+  try {
+    const result = await service.restorePurchases();
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    // Update local state
+    await updateSubscriptionStatus(result.customerInfo);
+
+    return result.customerInfo;
+  } catch (error) {
+    console.error('Restore failed:', error);
+    throw error;
+  }
+}
+```
+
+### Checking Entitlements
+
+```typescript
+async function checkPremiumAccess(): Promise<boolean> {
+  const service = RevenueCatServiceProvider.getInstance();
+
+  try {
+    const isActive = await service.checkEntitlement('premium');
+
+    if (isActive) {
+      const entitlement = await service.checkEntitlementInfo('premium');
+      console.log('Premium details:', entitlement);
+    }
+
+    return isActive;
+  } catch (error) {
+    console.error('Failed to check entitlement:', error);
+    return false;
+  }
+}
+```
+
+### Setting Subscriber Attributes
+
+```typescript
+async function updateUserAttributes(user: User) {
+  const service = RevenueCatServiceProvider.getInstance();
+
+  // Set email
+  if (user.email) {
+    await service.setEmail(user.email);
+  }
+
+  // Set phone number
+  if (user.phoneNumber) {
+    await service.setPhoneNumber(user.phoneNumber);
+  }
+
+  // Set custom attributes
+  await service.setAttributes({
+    $displayName: user.displayName,
+    account_created_at: user.createdAt.toISOString(),
+    subscription_tier: user.tier,
+  });
+}
+```
+
+## Error Handling
+
+### Wrapping Service Calls
+
+```typescript
+class RevenueCatServiceWrapper {
+  private service: IRevenueCatService;
+
+  constructor() {
+    this.service = RevenueCatServiceProvider.getInstance();
+  }
+
+  async safePurchase(
+    pkg: Package
+  ): Promise<PurchaseResult> {
+    try {
+      return await this.service.purchasePackage(pkg);
+    } catch (error) {
+      // Convert to domain error
+      if (isPurchasesError(error)) {
+        return {
+          customerInfo: {} as CustomerInfo,
+          error,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async safeGetOfferings(): Promise<Offerings | null> {
+    try {
+      return await this.getOfferings();
+    } catch (error) {
+      console.error('Failed to get offerings:', error);
+      return null;
+    }
+  }
+}
+```
+
+## Testing
+
+### Mock Implementation
+
+```typescript
+class MockRevenueCatService implements IRevenueCatService {
+  async configure(): Promise<void> {
+    console.log('Mock: Configure called');
+  }
+
+  async purchasePackage(pkg: Package): Promise<PurchaseResult> {
+    console.log('Mock: Purchase package', pkg.identifier);
+    return {
+      customerInfo: mockCustomerInfo,
+      transaction: mockTransaction,
+    };
+  }
+
+  // ... other mock implementations
+}
+
+// Use in tests
+const mockService = new MockRevenueCatService();
+```
+
+## Best Practices
+
+1. **Singleton**: Use singleton pattern for service instance
+2. **Error Handling**: Wrap all service calls in try-catch
+3. **Type Safety**: Use TypeScript types for all operations
+4. **Logging**: Log all RevenueCat operations
+5. **Caching**: Cache customer info and offerings appropriately
+6. **Validation**: Validate parameters before calling SDK
+7. **Configuration**: Configure service only once
+8. **Testing**: Use mock implementations for testing
+
+## Related
+
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Handlers](../handlers/README.md)
+- [RevenueCat Application Ports](../../application/ports/README.md)

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

@@ -0,0 +1,382 @@
+# RevenueCat Infrastructure Utils
+
+Utility functions for RevenueCat operations.
+
+## Overview
+
+This directory contains utility functions for common RevenueCat operations including error mapping, data transformation, and validation.
+
+## Utilities
+
+### Error Mapping
+
+Convert RevenueCat SDK errors to domain errors.
+
+```typescript
+function mapRevenueCatError(error: PurchasesError): DomainError {
+  switch (error.code) {
+    case 'PURCHASE_CANCELLED':
+      return {
+        code: 'PURCHASE_CANCELLED',
+        message: 'Purchase was cancelled',
+        userMessage: 'You cancelled the purchase',
+      };
+
+    case 'NETWORK_ERROR':
+      return {
+        code: 'NETWORK_ERROR',
+        message: 'Network error occurred',
+        userMessage: 'Please check your internet connection',
+      };
+
+    case 'INVALID_CREDENTIALS_ERROR':
+      return {
+        code: 'CONFIGURATION_ERROR',
+        message: 'Invalid RevenueCat credentials',
+        userMessage: 'Configuration error. Please contact support.',
+      };
+
+    case 'PRODUCT_NOT_AVAILABLE_FOR_PURCHASE':
+      return {
+        code: 'PRODUCT_NOT_AVAILABLE',
+        message: 'Product not available',
+        userMessage: 'This product is currently unavailable',
+      };
+
+    default:
+      return {
+        code: 'UNKNOWN_ERROR',
+        message: error.message || 'Unknown error',
+        userMessage: 'An error occurred. Please try again.',
+      };
+  }
+}
+```
+
+### Entitlement Extraction
+
+Extract entitlement information from customer info.
+
+```typescript
+function extractEntitlementInfo(
+  customerInfo: CustomerInfo,
+  entitlementId: string
+): EntitlementInfo | null {
+  const entitlement = customerInfo.entitlements[entitlementId];
+
+  if (!entitlement) {
+    return null;
+  }
+
+  return {
+    identifier: entitlementId,
+    isActive: entitlement.isActive,
+    willRenew: entitlement.willRenew,
+    periodType: entitlement.periodType,
+    productId: entitlement.productId,
+    latestPurchaseDate: entitlement.latestPurchaseDate,
+    originalPurchaseDate: entitlement.originalPurchaseDate,
+    expirationDate: entitlement.expirationDate,
+    renewAt: entitlement.renewAt,
+    isSandbox: entitlement.isSandbox,
+    billingIssueDetectedAt: entitlement.billingIssueDetectedAt,
+    unsubscribeDetectedAt: entitlement.unsubscribeDetectedAt,
+    store: entitlement.store,
+  };
+}
+```
+
+### Package Filtering
+
+Filter packages by type or criteria.
+
+```typescript
+function filterPackagesByType(
+  offering: Offering,
+  packageType: PackageType
+): Package[] {
+  return offering.availablePackages.filter(
+    pkg => pkg.packageType === packageType
+  );
+}
+
+function getSubscriptionPackages(offering: Offering): Package[] {
+  return offering.availablePackages.filter(pkg =>
+    ['monthly', 'annual', 'weekly'].includes(pkg.packageType)
+  );
+}
+
+function getLifetimePackages(offering: Offering): Package[] {
+  return offering.availablePackages.filter(pkg =>
+    pkg.packageType === 'lifetime'
+  );
+}
+
+function getSinglePurchasePackages(offering: Offering): Package[] {
+  return offering.availablePackages.filter(pkg =>
+    pkg.packageType === 'single_purchase'
+  );
+}
+```
+
+### Price Formatting
+
+Format prices for display.
+
+```typescript
+function formatPrice(
+  price: Price,
+  locale?: string
+): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: price.currencyCode,
+  }).format(price.amount);
+}
+
+function formatPricePerMonth(
+  package: Package,
+  locale?: string
+): string {
+  const { price, product } = package;
+
+  if (product.subscriptionPeriod) {
+    const { value, unit } = product.subscriptionPeriod;
+
+    // Calculate monthly equivalent
+    let months = 1;
+    if (unit === 'week') months = value / 4;
+    if (unit === 'month') months = value;
+    if (unit === 'year') months = value * 12;
+
+    const monthlyPrice = price.amount / months;
+    return formatPrice(
+      { amount: monthlyPrice, currencyCode: price.currencyCode },
+      locale
+    );
+  }
+
+  return formatPrice(price, locale);
+}
+```
+
+### Period Formatting
+
+Format subscription periods.
+
+```typescript
+function formatPeriod(
+  period: SubscriptionPeriod,
+  locale = 'en-US'
+): string {
+  const formatter = new Intl.RelativeTimeFormat(locale, {
+    numeric: 'always',
+  });
+  return formatter.format(period.value, period.unit);
+}
+
+function getPeriodInMonths(period: SubscriptionPeriod): number {
+  switch (period.unit) {
+    case 'day': return period.value / 30;
+    case 'week': return period.value / 4;
+    case 'month': return period.value;
+    case 'year': return period.value * 12;
+  }
+}
+
+function getPeriodInDays(period: SubscriptionPeriod): number {
+  switch (period.unit) {
+    case 'day': return period.value;
+    case 'week': return period.value * 7;
+    case 'month': return period.value * 30;
+    case 'year': return period.value * 365;
+  }
+}
+```
+
+### Subscription Status
+
+Determine subscription status from entitlement.
+
+```typescript
+function getSubscriptionStatus(
+  entitlement: EntitlementInfo | null
+): SubscriptionStatus {
+  if (!entitlement || !entitlement.isActive) {
+    return 'expired';
+  }
+
+  if (entitlement.billingIssueDetectedAt) {
+    return 'in_billing_retry';
+  }
+
+  if (entitlement.unsubscribeDetectedAt && !entitlement.willRenew) {
+    return 'cancelled';
+  }
+
+  return 'active';
+}
+
+function getSubscriptionStatusType(
+  entitlement: EntitlementInfo | null
+): 'active' | 'expired' | 'canceled' | 'none' {
+  if (!entitlement) {
+    return 'none';
+  }
+
+  if (!entitlement.isActive) {
+    return 'expired';
+  }
+
+  if (entitlement.unsubscribeDetectedAt && !entitlement.willRenew) {
+    return 'canceled';
+  }
+
+  return 'active';
+}
+```
+
+### Validation
+
+Validate RevenueCat data.
+
+```typescript
+function isValidEntitlementId(id: string): boolean {
+  const validIds = ['premium', 'pro', 'lifetime'];
+  return validIds.includes(id);
+}
+
+function isValidOffering(offering: Offering | null): boolean {
+  return (
+    offering !== null &&
+    offering.availablePackages.length > 0
+  );
+}
+
+function isValidPackage(pkg: Package | null): boolean {
+  return (
+    pkg !== null &&
+    !!pkg.identifier &&
+    !!pkg.product &&
+    !!pkg.price
+  );
+}
+```
+
+### Debug Helpers
+
+Helper functions for debugging.
+
+```typescript
+function logCustomerInfo(info: CustomerInfo): void {
+  if (__DEV__) {
+    console.log('[RevenueCat] Customer Info:', {
+      userId: info.originalAppUserId,
+      activeSubscriptions: info.activeSubscriptions,
+      allPurchasedProductIds: info.allPurchasedProductIds,
+      entitlements: Object.keys(info.entitlements),
+    });
+  }
+}
+
+function logPurchaseResult(result: PurchaseResult): void {
+  if (__DEV__) {
+    console.log('[RevenueCat] Purchase Result:', {
+      transactionId: result.transaction?.transactionIdentifier,
+      productId: result.transaction?.productIdentifier,
+      hasPremium: !!result.customerInfo.entitlements.premium?.isActive,
+    });
+  }
+}
+
+function logError(error: PurchasesError): void {
+  if (__DEV__) {
+    console.error('[RevenueCat] Error:', {
+      code: error.code,
+      message: error.message,
+      readableMessage: error.readableErrorMessage,
+    });
+  }
+}
+```
+
+## Usage Examples
+
+### Using Error Mapping
+
+```typescript
+import { mapRevenueCatError } from './utils';
+
+try {
+  const result = await purchasePackage(pkg);
+} catch (error) {
+  const domainError = mapRevenueCatError(error);
+
+  // Show user-friendly message
+  Alert.alert('Error', domainError.userMessage);
+
+  // Log technical details
+  console.error(domainError.message);
+}
+```
+
+### Extracting Entitlement Info
+
+```typescript
+import { extractEntitlementInfo } from './utils';
+
+const customerInfo = await getCustomerInfo();
+const premium = extractEntitlementInfo(customerInfo, 'premium');
+
+if (premium?.isActive) {
+  console.log('Premium active until', premium.expirationDate);
+}
+```
+
+### Filtering Packages
+
+```typescript
+import { filterPackagesByType, getSubscriptionPackages } from './utils';
+
+const offering = await getOfferings();
+const monthlyPackages = filterPackagesByType(offering.current, 'monthly');
+const allSubscriptions = getSubscriptionPackages(offering.current);
+```
+
+### Formatting Prices
+
+```typescript
+import { formatPrice, formatPricePerMonth } from './utils';
+
+// Standard price
+const priceString = formatPrice(pkg.price, 'en-US'); // '$9.99'
+const priceStringTR = formatPrice(pkg.price, 'tr-TR'); // '9,99 $'
+
+// Per month (for annual)
+const perMonth = formatPricePerMonth(annualPackage, 'en-US'); // '$8.33/mo'
+```
+
+### Getting Subscription Status
+
+```typescript
+import { getSubscriptionStatus, getSubscriptionStatusType } from './utils';
+
+const entitlement = customerInfo.entitlements.premium;
+const status = getSubscriptionStatus(entitlement); // 'active'
+const statusType = getSubscriptionStatusType(entitlement); // 'active'
+```
+
+## Best Practices
+
+1. **Error Handling**: Always use error mapping for user-facing messages
+2. **Type Safety**: Ensure types are validated before use
+3. **Locale**: Respect user locale for formatting
+4. **Null Checks**: Always check for null/undefined values
+5. **Logging**: Use debug helpers in development
+6. **Validation**: Validate data before processing
+
+## Related
+
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Domain Types](../../domain/types/README.md)
+- [RevenueCat Errors](../../domain/errors/README.md)