@umituz/react-native-subscription 2.14.99 → 2.14.101

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

@@ -1,218 +1,41 @@
 # RevenueCat Infrastructure Handlers
 
+## Location
 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
-
+## Strategy
+This directory contains handler implementations for managing RevenueCat events including purchase callbacks, customer info changes, and error handling with proper data validation and recovery.
+
+## Restrictions
+
+### REQUIRED
+- Must handle all events gracefully
+- Must validate incoming data before processing
+- Must log all events for debugging
+- Must invoke callbacks appropriately
+
+### PROHIBITED
+- DO NOT mutate incoming event data
+- DO NOT ignore event handling errors
+- DO NOT skip callback invocation
+- DO NOT process unvalidated data
+
+### CRITICAL SAFETY
+- All incoming data MUST be validated
+- All events MUST be logged for debugging
+- All callbacks MUST be invoked appropriately
+- Recovery options MUST be provided when possible
+
+## AI Agent Guidelines
+1. Never mutate incoming event data
+2. Handle all errors gracefully with proper boundaries
+3. Log all events for debugging and monitoring
+4. Invoke registered callbacks appropriately
+5. Use async/await for asynchronous operations
+6. Validate all incoming data before processing
+7. Provide recovery options when possible
+
+## Related Documentation
 - [RevenueCat Infrastructure](../README.md)
 - [RevenueCat Services](../services/README.md)
 - [RevenueCat Errors](../../domain/errors/README.md)

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

@@ -1,49 +1,41 @@
 # RevenueCat Infrastructure Managers
 
+## Location
 Manager classes for coordinating RevenueCat operations.
 
-## Overview
-
-This directory contains high-level manager classes that coordinate between different RevenueCat services and handle complex operations.
-
-## Contents
-
-- **SubscriptionManager.ts** - Manages RevenueCat configuration and entitlement access
-
-## SubscriptionManager
-
-Manages RevenueCat SDK configuration and provides access to entitlement IDs.
-
-### Key Methods
-
-```typescript
-class SubscriptionManager {
-  static configure(config: RevenueCatConfig): void;
-  static getEntitlementId(): string | null;
-  static getOfferings(): Promise<Offerings>;
-}
-```
-
-### Usage
-
-```typescript
-import { SubscriptionManager } from './managers/SubscriptionManager';
-
-// Configure at app startup
-SubscriptionManager.configure({
-  apiKey: 'your_api_key',
-  entitlementId: 'premium',
-});
-
-// Get entitlement ID
-const entitlementId = SubscriptionManager.getEntitlementId();
-
-// Get offerings
-const offerings = await SubscriptionManager.getOfferings();
-```
-
-## Related
-
+## Strategy
+This directory contains high-level manager classes that coordinate between different RevenueCat services and handle complex operations like SDK configuration and entitlement access.
+
+## Restrictions
+
+### REQUIRED
+- Must coordinate between services properly
+- Must manage SDK configuration correctly
+- Must provide access to entitlement IDs
+- Must handle complex operations safely
+
+### PROHIBITED
+- DO NOT bypass service coordination
+- DO NOT misconfigure SDK
+- DO NOT expose invalid entitlement IDs
+- DO NOT oversimplify complex operations
+
+### CRITICAL SAFETY
+- Service coordination MUST be correct
+- SDK configuration MUST be valid
+- Entitlement access MUST be safe
+- Complex operations MUST be handled properly
+
+## AI Agent Guidelines
+1. Coordinate properly between RevenueCat services
+2. Manage SDK configuration with correct parameters
+3. Provide safe access to entitlement IDs
+4. Handle complex operations with proper error handling
+5. Test coordination logic thoroughly
+6. Document manager responsibilities clearly
+7. Maintain separation of concerns
+
+## Related Documentation
 - [Services](../services/README.md)
 - [Config](../config/README.md)
 - [Domain](../../domain/README.md)

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

@@ -1,325 +1,42 @@
 # RevenueCat Infrastructure Services
 
+## Location
 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
-
+## Strategy
+This directory contains concrete implementations of RevenueCat interfaces, providing the actual integration with the RevenueCat SDK using singleton pattern with proper error handling and caching.
+
+## Restrictions
+
+### REQUIRED
+- Must use singleton pattern for service instance
+- Must wrap all service calls in try-catch
+- Must use TypeScript types for all operations
+- Must log all RevenueCat operations
+
+### PROHIBITED
+- DO NOT create multiple service instances
+- DO NOT skip error handling
+- DO NOT bypass type safety
+- DO NOT skip logging operations
+
+### CRITICAL SAFETY
+- Service MUST be configured only once
+- All calls MUST be wrapped in error handling
+- All operations MUST be type-safe
+- All operations MUST be logged
+
+## AI Agent Guidelines
+1. Use singleton pattern for service instance
+2. Wrap all service calls in try-catch blocks
+3. Use TypeScript types for all operations
+4. Log all RevenueCat operations for debugging
+5. Cache customer info and offerings appropriately
+6. Validate parameters before calling SDK
+7. Configure service only once at startup
+8. Use mock implementations for testing
+
+## Related Documentation
 - [RevenueCat Infrastructure](../README.md)
 - [RevenueCat Handlers](../handlers/README.md)
 - [RevenueCat Application Ports](../../application/ports/README.md)