@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/revenuecat/application/README.md

@@ -1,157 +1,42 @@
 # RevenueCat Application Layer
 
+## Location
 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
-
+## Strategy
+This directory contains use cases and application-level operations for managing RevenueCat subscriptions and purchases with proper error handling and state synchronization.
+
+## Restrictions
+
+### REQUIRED
+- Must handle RevenueCat errors gracefully
+- Must provide user ID when available
+- Must use entitlements instead of product IDs
+- Must keep local state synchronized
+
+### PROHIBITED
+- DO NOT ignore RevenueCat errors
+- DO NOT skip user ID provision
+- DO NOT use product IDs directly
+- DO NOT allow state desynchronization
+
+### CRITICAL SAFETY
+- All errors MUST be handled gracefully
+- User IDs MUST be provided when available
+- Entitlements MUST be used for flexibility
+- Local state MUST stay synchronized
+
+## AI Agent Guidelines
+1. Always handle RevenueCat errors with proper recovery
+2. Provide user ID when available for better tracking
+3. Use entitlements instead of product IDs for flexibility
+4. Check if offerings are available before purchasing
+5. Validate customer info after purchases
+6. Keep local state synchronized with RevenueCat
+7. Handle network timeouts appropriately
+8. Log all RevenueCat operations for debugging
+
+## Related Documentation
 - [RevenueCat Integration](../README.md)
 - [RevenueCat Domain](../domain/README.md)
 - [RevenueCat Infrastructure](../infrastructure/README.md)

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

@@ -1,169 +1,41 @@
 # RevenueCat Application Ports
 
+## Location
 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
-
+## Strategy
+This directory defines the ports (interfaces) that the RevenueCat infrastructure must implement, following the Dependency Inversion Principle for testability and flexibility.
+
+## Restrictions
+
+### REQUIRED
+- Must define clear interfaces for all operations
+- Must support mocking for testing
+- Must enable implementation swapping
+- Must maintain contracts between layers
+
+### PROHIBITED
+- DO NOT depend on concrete implementations
+- DO NOT create interfaces without clear purpose
+- DO NOT break interface contracts
+- DO NOT couple application to infrastructure
+
+### CRITICAL SAFETY
+- All dependencies MUST be inverted
+- Interfaces MUST be clearly defined
+- Implementations MUST be swappable
+- Contracts MUST be maintained
+
+## AI Agent Guidelines
+1. Define clear interfaces for all RevenueCat operations
+2. Design interfaces for easy mocking in tests
+3. Enable implementation swapping when needed
+4. Keep application layer decoupled from infrastructure
+5. Maintain clear contracts between layers
+6. Document interface behavior thoroughly
+7. Test with mock implementations
+
+## Related Documentation
 - [RevenueCat Application Layer](../README.md)
 - [RevenueCat Infrastructure](../infrastructure/README.md)
 - [RevenueCat Domain](../domain/README.md)

package/src/revenuecat/domain/README.md

@@ -2,146 +2,47 @@
 
 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
+## Location
+
+`src/revenuecat/domain/`
+
+## Strategy
+
+Domain-specific entities representing RevenueCat concepts like entitlements, offerings, and packages, with proper type mapping and validation.
+
+## Restrictions
+
+### REQUIRED
+
+- MUST map RevenueCat types to domain types
+- MUST handle optional properties safely (null safety)
+- MUST validate RevenueCat data
+- MUST format prices and dates consistently
+- MUST use constants for identifiers
+
+### PROHIBITED
+
+- MUST NOT expose RevenueCat implementation details to other layers
+- MUST NOT leak RevenueCat SDK types outside this module
+- MUST NOT assume all properties are present (null safety)
+
+### CRITICAL
+
+- Always validate RevenueCat data before use
+- Handle all optional properties safely
+- Use constants for all identifiers
+- Maintain consistent formatting for prices and dates
+
+## AI Agent Guidelines
+
+When working with RevenueCat domain:
+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 Documentation
 
 - [RevenueCat README](../README.md)
-- [Subscription Manager](../infrastructure/managers/README.md)
+- [Subscription Manager](../../infrastructure/managers/README.md)