@umituz/react-native-subscription 2.14.98 → 2.14.99

package/src/revenuecat/application/README.md

@@ -0,0 +1,158 @@
+# RevenueCat Application Layer
+
+Application layer for RevenueCat integration, containing use cases and orchestration logic.
+
+## Overview
+
+This directory contains use cases and application-level operations for managing RevenueCat subscriptions and purchases.
+
+## Structure
+
+```
+application/
+└── ports/    # Interface definitions for RevenueCat services
+```
+
+## Ports
+
+### IRevenueCatService
+
+Main service interface for RevenueCat operations.
+
+```typescript
+interface IRevenueCatService {
+  // Purchasing
+  purchasePackage(package: PurchasesPackage): Promise<PurchaseResult>;
+  restorePurchases(): Promise<RestoreResult>;
+
+  // Customer Info
+  getCustomerInfo(): Promise<CustomerInfo>;
+  getOfferings(): Promise<Offerings>;
+
+  // Configuration
+  configure(apiKey: string, userId?: string): Promise<void>;
+
+  // Entitlements
+  checkEntitlement(entitlementId: string): Promise<boolean>;
+}
+```
+
+## Use Cases
+
+### Purchase Flow
+
+```typescript
+async function purchasePremiumPackage(userId: string) {
+  const service = getRevenueCatService();
+
+  // 1. Get offerings
+  const offerings = await service.getOfferings();
+  const package = offerings.current?.monthly;
+
+  if (!package) {
+    throw new Error('No package available');
+  }
+
+  // 2. Purchase
+  const result = await service.purchasePackage(package);
+
+  // 3. Handle result
+  if (result.error) {
+    throw new Error(result.error.message);
+  }
+
+  // 4. Update local state
+  await updateSubscriptionStatus(userId, result.customerInfo);
+}
+```
+
+### Restore Purchases
+
+```typescript
+async function restoreUserPurchases() {
+  const service = getRevenueCatService();
+
+  try {
+    const result = await service.restorePurchases();
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    // Update local subscription status
+    await updateSubscriptionStatusFromRestored(result.customerInfo);
+
+    return { success: true, customerInfo: result.customerInfo };
+  } catch (error) {
+    return { success: false, error };
+  }
+}
+```
+
+### Check Entitlement
+
+```typescript
+async function checkPremiumAccess(userId: string): Promise<boolean> {
+  const service = getRevenueCatService();
+
+  try {
+    const hasPremium = await service.checkEntitlement('premium');
+
+    if (hasPremium) {
+      await activatePremiumStatus(userId);
+    }
+
+    return hasPremium;
+  } catch (error) {
+    console.error('Failed to check entitlement:', error);
+    return false;
+  }
+}
+```
+
+## Best Practices
+
+1. **Error Handling**: Always handle RevenueCat errors gracefully
+2. **User ID**: Provide user ID when available for better tracking
+3. **Entitlements**: Use entitlements instead of product IDs for flexibility
+4. **Offerings**: Check if offerings are available before purchasing
+5. **Validation**: Validate customer info after purchases
+6. **Sync**: Keep local state synchronized with RevenueCat
+7. **Timeouts**: Handle network timeouts appropriately
+8. **Logging**: Log all RevenueCat operations for debugging
+
+## Error Handling
+
+```typescript
+import { PurchaseError } from '../domain/errors';
+
+async function safePurchase(pkg: PurchasesPackage) {
+  try {
+    const result = await service.purchasePackage(pkg);
+
+    if (result.error) {
+      // Map RevenueCat errors to domain errors
+      if (result.error.code === 'PURCHASE_CANCELLED') {
+        throw new PurchaseError('User cancelled purchase');
+      }
+
+      throw new PurchaseError(result.error.message);
+    }
+
+    return result;
+  } catch (error) {
+    if (error instanceof PurchaseError) {
+      throw error;
+    }
+
+    throw new PurchaseError('Purchase failed', { cause: error });
+  }
+}
+```
+
+## Related
+
+- [RevenueCat Integration](../README.md)
+- [RevenueCat Domain](../domain/README.md)
+- [RevenueCat Infrastructure](../infrastructure/README.md)
+- [Application Ports](./ports/README.md)

package/src/revenuecat/application/ports/README.md

@@ -0,0 +1,169 @@
+# RevenueCat Application Ports
+
+Interface definitions for RevenueCat service layer.
+
+## Overview
+
+This directory defines the ports (interfaces) that the RevenueCat infrastructure must implement. Following Dependency Inversion Principle, the application layer depends on these abstractions rather than concrete implementations.
+
+## Ports
+
+### IRevenueCatService
+
+Core service interface for RevenueCat operations.
+
+```typescript
+interface IRevenueCatService {
+  // Configuration
+  configure(params: {
+    apiKey: string;
+    userId?: string;
+    observerMode?: boolean;
+  }): Promise<void>;
+
+  // Purchasing Operations
+  purchasePackage(pkg: PurchasesPackage): Promise<PurchaseResult>;
+  purchaseProduct(productId: string): Promise<PurchaseResult>;
+  restorePurchases(): Promise<RestoreResult>;
+
+  // Customer Information
+  getCustomerInfo(): Promise<CustomerInfo>;
+  getCustomerInfoUserId(): string | null;
+
+  // Offerings
+  getOfferings(): Promise<Offerings>;
+  getCurrentOffering(): Promise<Offering | null>;
+
+  // Entitlements
+  checkEntitlement(entitlementId: string): Promise<boolean>;
+  checkEntitlementInfo(entitlementId: string): Promise<EntitlementInfo | null>;
+
+  // Subscriber Attributes
+  setAttributes(attributes: SubscriberAttributes): Promise<void>;
+  setEmail(email: string): Promise<void>;
+  setPhoneNumber(phoneNumber: string): Promise<void>;
+
+  // Log Out
+  logOut(): Promise<void>;
+}
+```
+
+### IRevenueCatPurchaseHandler
+
+Handles purchase callbacks and results.
+
+```typescript
+interface IRevenueCatPurchaseHandler {
+  onPurchaseStarted?(package: PurchasesPackage): void;
+  onPurchaseSuccess?(result: PurchaseResult): void;
+  onPurchaseError?(error: PurchaseError): void;
+  onPurchaseCancelled?(result: PurchaseResult): void;
+  onRestoreStarted?(): void;
+  onRestoreSuccess?(result: RestoreResult): void;
+  onRestoreError?(error: Error): void;
+}
+```
+
+### IRevenueCatCustomerInfoListener
+
+Listens to customer info changes.
+
+```typescript
+interface IRevenueCatCustomerInfoListener {
+  onCustomerInfoChanged(customerInfo: CustomerInfo): void;
+  onEntitlementsChanged(entitlements: EntitlementInfos): void;
+}
+```
+
+## Usage
+
+### Injecting Dependencies
+
+```typescript
+import type { IRevenueCatService } from './ports/IRevenueCatService';
+
+class PurchaseManager {
+  constructor(
+    private revenueCatService: IRevenueCatService
+  ) {}
+
+  async purchasePremium() {
+    const offerings = await this.revenueCatService.getOfferings();
+    const package = offerings.current?.monthly;
+
+    if (!package) {
+      throw new Error('No package available');
+    }
+
+    return await this.revenueCatService.purchasePackage(package);
+  }
+}
+```
+
+### Implementing Ports
+
+```typescript
+import type { IRevenueCatService } from './ports/IRevenueCatService';
+import { Purchases } from '@revenuecat/purchases-capacitor';
+
+class RevenueCatServiceImpl implements IRevenueCatService {
+  async configure(params: {
+    apiKey: string;
+    userId?: string;
+    observerMode?: boolean;
+  }): Promise<void> {
+    await Purchases.configure({
+      apiKey: params.apiKey,
+      appUserID: params.userId,
+      observerMode: params.observerMode ?? false,
+    });
+  }
+
+  async purchasePackage(pkg: PurchasesPackage): Promise<PurchaseResult> {
+    return await Purchases.purchasePackage({
+      aPackage: pkg,
+    });
+  }
+
+  // ... other implementations
+}
+
+// Provide implementation
+const revenueCatService: IRevenueCatService = new RevenueCatServiceImpl();
+```
+
+## Benefits of Ports
+
+1. **Testability**: Easy to mock for testing
+2. **Flexibility**: Can swap implementations
+3. **Decoupling**: Application layer doesn't depend on concrete implementations
+4. **Maintainability**: Clear contracts between layers
+
+## Testing with Mocks
+
+```typescript
+import type { IRevenueCatService } from './ports/IRevenueCatService';
+
+const mockRevenueCatService: IRevenueCatService = {
+  configure: vi.fn().mockResolvedValue(undefined),
+  purchasePackage: vi.fn().mockResolvedValue({
+    customerInfo: mockCustomerInfo,
+  }),
+  restorePurchases: vi.fn().mockResolvedValue({
+    customerInfo: mockCustomerInfo,
+  }),
+  getCustomerInfo: vi.fn().mockResolvedValue(mockCustomerInfo),
+  getOfferings: vi.fn().mockResolvedValue(mockOfferings),
+  checkEntitlement: vi.fn().mockResolvedValue(true),
+  // ... other methods
+};
+
+// Use in tests
+const manager = new PurchaseManager(mockRevenueCatService);
+```
+
+## Related
+
+- [RevenueCat Application Layer](../README.md)
+- [RevenueCat Infrastructure](../infrastructure/README.md)
+- [RevenueCat Domain](../domain/README.md)

package/src/revenuecat/domain/constants/README.md

@@ -0,0 +1,183 @@
+# RevenueCat Domain Constants
+
+Constants used throughout the RevenueCat integration.
+
+## Overview
+
+This directory contains constant definitions for RevenueCat-specific values including entitlement IDs, error codes, and configuration defaults.
+
+## Constants
+
+### Entitlement IDs
+
+```typescript
+export const ENTITLEMENT_IDS = {
+  PREMIUM: 'premium',
+  PRO: 'pro',
+  LIFETIME: 'lifetime',
+} as const;
+
+export type EntitlementId = typeof ENTITLEMENT_IDS[keyof typeof ENTITLEMENT_IDS];
+```
+
+### Offering Identifiers
+
+```typescript
+export const OFFERING_IDS = {
+  DEFAULT: 'default',
+  ANNUAL_OFFER: 'annual_offer',
+  LIFETIME_OFFER: 'lifetime_offer',
+} as const;
+
+export type OfferingId = typeof OFFERING_IDS[keyof typeof OFFERING_IDS];
+```
+
+### Package Periods
+
+```typescript
+export const PACKAGE_PERIODS = {
+  MONTHLY: 'monthly',
+  ANNUAL: 'annual',
+  LIFETIME: 'lifetime',
+  WEEKLY: 'weekly',
+} as const;
+
+export type PackagePeriod = typeof PACKAGE_PERIODS[keyof typeof PACKAGE_PERIODS];
+```
+
+### Product Categories
+
+```typescript
+export const PRODUCT_CATEGORIES = {
+  SUBSCRIPTION: 'subscription',
+  ONE_TIME_PURCHASE: 'non_subscription',
+  CONSUMABLE: 'consumable',
+} as const;
+
+export type ProductCategory = typeof PRODUCT_CATEGORIES[keyof typeof PRODUCT_CATEGORIES];
+```
+
+### Error Codes
+
+```typescript
+export const ERROR_CODES = {
+  // Configuration Errors
+  CONFIGURATION_ERROR: 'CONFIGURATION_ERROR',
+  API_KEY_NOT_SET: 'API_KEY_NOT_SET',
+  INVALID_API_KEY: 'INVALID_API_KEY',
+
+  // Purchase Errors
+  PURCHASE_ERROR: 'PURCHASE_ERROR',
+  PURCHASE_CANCELLED: 'PURCHASE_CANCELLED',
+  PURCHASE_INVALID: 'PURCHASE_INVALID',
+  PRODUCT_NOT_AVAILABLE: 'PRODUCT_NOT_AVAILABLE',
+
+  // Network Errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT',
+  SERVER_ERROR: 'SERVER_ERROR',
+
+  // Customer Info Errors
+  CUSTOMER_INFO_ERROR: 'CUSTOMER_INFO_ERROR',
+  ENTITLEMENT_NOT_FOUND: 'ENTITLEMENT_NOT_FOUND',
+  OFFERING_NOT_FOUND: 'OFFERING_NOT_FOUND',
+
+  // Receipt Errors
+  RECEIPT_ERROR: 'RECEIPT_ERROR',
+  RECEIPT_INVALID: 'RECEIPT_INVALID',
+  RECEIPT_ALREADY_USED: 'RECEIPT_ALREADY_USES',
+
+  // User Errors
+  USER_NOT_AUTHENTICATED: 'USER_NOT_AUTHENTICATED',
+  USER_ID_NOT_SET: 'USER_ID_NOT_SET',
+} as const;
+```
+
+### Configuration Defaults
+
+```typescript
+export const CONFIG_DEFAULTS = {
+  // Timeout Settings
+  NETWORK_TIMEOUT_MS: 10000,
+  PURCHASE_TIMEOUT_MS: 30000,
+
+  // Retry Settings
+  MAX_RETRIES: 3,
+  RETRY_DELAY_MS: 1000,
+
+  // Cache Settings
+  CUSTOMER_INFO_CACHE_TTL_MS: 60000, // 1 minute
+  OFFERINGS_CACHE_TTL_MS: 300000, // 5 minutes
+
+  // Debug Settings
+  ENABLE_DEBUG_LOGS: __DEV__,
+  LOG_LEVEL: 'info' as const,
+} as const;
+```
+
+### Entitlement Verification
+
+```typescript
+export const ENTITLEMENT_VERIFICATION = {
+  // Verification Modes
+  MODE_STRICT: 'strict',
+  MODE_LOOSE: 'loose',
+
+  // Grace Periods (milliseconds)
+  GRACE_PERIOD_MS: 3 * 24 * 60 * 60 * 1000, // 3 days
+  REFUND_GRACE_PERIOD_MS: 7 * 24 * 60 * 60 * 1000, // 7 days
+} as const;
+```
+
+## Usage Examples
+
+### Checking Entitlements
+
+```typescript
+import { ENTITLEMENT_IDS } from './constants';
+
+const hasPremium = await checkEntitlement(ENTITLEMENT_IDS.PREMIUM);
+```
+
+### Filtering Offerings
+
+```typescript
+import { OFFERING_IDS } from './constants';
+
+const defaultOffering = offerings[OFFERING_IDS.DEFAULT];
+const annualOffering = offerings[OFFERING_IDS.ANNUAL_OFFER];
+```
+
+### Handling Errors
+
+```typescript
+import { ERROR_CODES } from './constants';
+
+try {
+  await purchasePackage(pkg);
+} catch (error) {
+  if (error.code === ERROR_CODES.PURCHASE_CANCELLED) {
+    // Handle cancellation
+  } else if (error.code === ERROR_CODES.NETWORK_ERROR) {
+    // Handle network error
+  }
+}
+```
+
+### Configuration
+
+```typescript
+import { CONFIG_DEFAULTS } from './constants';
+
+const config = {
+  apiKey: 'your_api_key',
+  timeout: CONFIG_DEFAULTS.NETWORK_TIMEOUT_MS,
+  enableDebugLogs: CONFIG_DEFAULTS.ENABLE_DEBUG_LOGS,
+};
+```
+
+## Related
+
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Errors](../errors/README.md)
+- [RevenueCat Entities](../entities/README.md)