@umituz/react-native-subscription 2.14.97 → 2.14.99

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/README.md

@@ -0,0 +1,147 @@
+# RevenueCat Domain
+
+Domain entities and types for RevenueCat integration.
+
+## Overview
+
+This directory contains domain-specific entities representing RevenueCat concepts like entitlements, offerings, and packages.
+
+## Entities
+
+### EntitlementInfo
+Represents a RevenueCat entitlement.
+
+```typescript
+interface EntitlementInfo {
+  identifier: string;
+  isActive: boolean;
+  willRenew: boolean;
+  expirationDate?: Date;
+  productIdentifier?: string;
+  period?: PackagePeriod;
+}
+```
+
+**Usage:**
+```typescript
+const entitlement: EntitlementInfo = {
+  identifier: 'premium',
+  isActive: true,
+  willRenew: true,
+  expirationDate: new Date('2024-12-31'),
+  productIdentifier: 'com.app.premium.annual',
+  period: 'annual',
+};
+```
+
+### OfferingInfo
+Represents a RevenueCat offering containing packages.
+
+```typescript
+interface OfferingInfo {
+  identifier: string;
+  packages: PackageInfo[];
+  lifetime?: PackageInfo;
+  monthly?: PackageInfo;
+  annual?: PackageInfo;
+}
+```
+
+### PackageInfo
+Represents a purchasable package.
+
+```typescript
+interface PackageInfo {
+  identifier: string;
+  packageType: PackageType;
+  product: ProductInfo;
+  offeringIdentifier: string;
+}
+
+interface ProductInfo {
+  identifier: string;
+  title: string;
+  description: string;
+  price: number;
+  pricePerMonth?: number;
+  currencyCode: string;
+}
+
+type PackageType = 'WEEKLY' | 'MONTHLY' | 'THREE_MONTHLY' | 'SIX_MONTHLY' | 'ANNUAL' | 'LIFETIME';
+```
+
+## Constants
+
+### Entitlement Identifiers
+
+```typescript
+export const ENTITLEMENT_IDS = {
+  PREMIUM: 'premium',
+  PRO: 'pro',
+  BASIC: 'basic',
+} as const;
+```
+
+### Package Periods
+
+```typescript
+export const PACKAGE_PERIODS = {
+  WEEKLY: 'weekly',
+  MONTHLY: 'monthly',
+  ANNUAL: 'annual',
+  LIFETIME: 'lifetime',
+} as const;
+```
+
+## Helper Functions
+
+### Get Package Period
+
+```typescript
+function getPackagePeriod(packageType: PackageType): PackagePeriod {
+  const periodMap: Record<PackageType, PackagePeriod> = {
+    WEEKLY: 'monthly',
+    MONTHLY: 'monthly',
+    THREE_MONTHLY: 'monthly',
+    SIX_MONTHLY: 'monthly',
+    ANNUAL: 'annual',
+    LIFETIME: 'lifetime',
+  };
+  return periodMap[packageType];
+}
+```
+
+### Calculate Price Per Month
+
+```typescript
+function calculatePricePerMonth(packageInfo: PackageInfo): number | null {
+  if (!packageInfo.product.pricePerMonth) {
+    return packageInfo.product.price;
+  }
+  return packageInfo.product.pricePerMonth;
+}
+```
+
+### Format Price
+
+```typescript
+function formatPrice(price: number, currencyCode: string): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: currencyCode,
+  }).format(price);
+}
+```
+
+## Best Practices
+
+1. **Type Mapping**: Map RevenueCat types to domain types
+2. **Null Safety**: Handle optional properties safely
+3. **Validation**: Validate RevenueCat data
+4. **Formatting**: Format prices and dates consistently
+5. **Constants**: Use constants for identifiers
+
+## Related
+
+- [RevenueCat README](../README.md)
+- [Subscription Manager](../infrastructure/managers/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)