@umituz/react-native-subscription 2.14.97 → 2.14.99

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

@@ -0,0 +1,382 @@
+# RevenueCat Domain Entities
+
+Core domain entities for RevenueCat integration.
+
+## Overview
+
+This directory contains TypeScript type definitions and entities representing RevenueCat concepts like customer info, entitlements, offerings, and packages.
+
+## Entities
+
+### CustomerInfo
+
+Represents the subscriber's current information and entitlements.
+
+```typescript
+interface CustomerInfo {
+  // Subscriber Information
+  originalAppUserId: string;
+  originalApplicationVersion: string | null;
+  requestDate: Date;
+  allExpirationDates: Record<string, Date | null>;
+  allPurchaseDates: Record<string, Date | null>;
+  originalPurchaseDates: Record<string, Date | null>;
+
+  // Entitlements
+  entitlements: EntitlementInfos;
+
+  // Active Subscriptions
+  activeSubscriptions: string[];
+
+  // All Purchases
+  allPurchasedProductIds: string[];
+
+  // Latest Purchase
+  latestExpirationDate: Date | null;
+  firstSeen: Date;
+  managementURL: string | null;
+}
+```
+
+### EntitlementInfos
+
+Collection of entitlement information.
+
+```typescript
+interface EntitlementInfos {
+  [key: string]: EntitlementInfo;
+}
+```
+
+### EntitlementInfo
+
+Information about a specific entitlement.
+
+```typescript
+interface EntitlementInfo {
+  // Identifier
+  identifier: string;
+
+  // Active Status
+  isActive: boolean;
+  willRenew: boolean;
+
+  // Period Type
+  periodType: 'normal' | 'trial' | 'intro';
+
+  // Product Information
+  productId: string;
+  productIdentifier: string;
+
+  // Dates
+  latestPurchaseDate: Date;
+  originalPurchaseDate: Date;
+  expirationDate: Date | null;
+
+  // Renewal Information
+  renewAt: Date | null;
+  isSandbox: boolean;
+
+  // Billing
+  billingIssueDetectedAt: Date | null;
+
+  // Cancellation
+  unsubscribeDetectedAt: Date | null;
+
+  // Store
+  store: 'app_store' | 'play_store' | 'stripe' | 'mac_app_store' | 'play_store_amazon' | 'promotional';
+}
+```
+
+### Offerings
+
+Collection of available offerings.
+
+```typescript
+interface Offerings {
+  // All Offerings
+  all: Record<string, Offering>;
+
+  // Current Offering
+  current: Offering | null;
+
+  // Specific Offerings
+  [key: string]: Offering | null;
+}
+```
+
+### Offering
+
+A collection of packages available for purchase.
+
+```typescript
+interface Offering {
+  // Identifier
+  identifier: string;
+
+  // Server Description
+  serverDescription: string;
+
+  // Available Packages
+  availablePackages: Package[];
+
+  // Lifetime Packages
+  lifetime: Package | null;
+
+  // Annual Packages
+  annual: Package | null;
+
+  // Monthly Packages
+  monthly: Package | null;
+
+  // Weekly Packages
+  weekly: Package | null;
+
+  // Single Purchase
+  singlePurchase: Package | null;
+}
+```
+
+### Package
+
+A purchasable product within an offering.
+
+```typescript
+interface Package {
+  // Identifier
+  identifier: string;
+
+  // Package Type
+  packageType: PackageType;
+
+  // Product Information
+  product: Product;
+
+  // Offering
+  offeringIdentifier: string;
+
+  // Pricing
+  price: Price;
+  localizedPriceString: string;
+
+  // Metadata
+  metadata: PackageMetadata;
+}
+
+type PackageType =
+  | 'monthly'
+  | 'annual'
+  | 'lifetime'
+  | 'weekly'
+  | 'single_purchase';
+```
+
+### Product
+
+Details about a purchasable product.
+
+```typescript
+interface Product {
+  // Identifier
+  identifier: string;
+
+  // Description
+  description: string;
+
+  // Title
+  title: string;
+
+  // Price
+  price: Price;
+
+  // Subscription Period
+  subscriptionPeriod: SubscriptionPeriod | null;
+
+  // Introductory Offer
+  introductoryPrice: IntroductoryOffer | null;
+
+  // Product Type
+  type: ProductType;
+
+  // Store
+  defaultOption: ProductOption;
+
+  // Options (for iOS)
+  options: ProductOption[];
+}
+
+type ProductType = 'subscription' | 'non_subscription' | 'consumable';
+```
+
+### Price
+
+Price information.
+
+```typescript
+interface Price {
+  amount: number;
+  currencyCode: string;
+  formattedPrice: string;
+}
+```
+
+### SubscriptionPeriod
+
+Duration of a subscription period.
+
+```typescript
+interface SubscriptionPeriod {
+  value: number;
+  unit: 'day' | 'week' | 'month' | 'year';
+}
+```
+
+### IntroductoryOffer
+
+Special pricing for new subscribers.
+
+```typescript
+interface IntroductoryOffer {
+  price: Price;
+  period: SubscriptionPeriod;
+  periodNumberOfUnits: number;
+  cycles: number;
+}
+```
+
+### PurchaseResult
+
+Result of a purchase operation.
+
+```typescript
+interface PurchaseResult {
+  // Customer Information
+  customerInfo: CustomerInfo;
+
+  // Transaction
+  transaction: Transaction | null;
+
+  // Error (if failed)
+  error?: PurchasesError;
+
+  // Whether it was a renewal
+  isRenewal: boolean;
+}
+```
+
+### RestoreResult
+
+Result of a restore purchases operation.
+
+```typescript
+interface RestoreResult {
+  // Customer Information
+  customerInfo: CustomerInfo;
+
+  // Error (if failed)
+  error?: PurchasesError;
+}
+```
+
+### Transaction
+
+Information about a purchase transaction.
+
+```typescript
+interface Transaction {
+  transactionIdentifier: string;
+  productIdentifier: string;
+  purchaseDate: Date;
+  transactionDate: Date;
+  revenueCatId: string;
+}
+```
+
+## Usage Examples
+
+### Accessing Customer Info
+
+```typescript
+const customerInfo: CustomerInfo = await getCustomerInfo();
+
+// Check if user has premium
+const premiumEntitlement = customerInfo.entitlements.premium;
+if (premiumEntitlement?.isActive) {
+  console.log('User has premium');
+}
+
+// Get expiration date
+const expirationDate = premiumEntitlement?.expirationDate;
+console.log('Expires on:', expirationDate);
+
+// Check active subscriptions
+console.log('Active subscriptions:', customerInfo.activeSubscriptions);
+```
+
+### Working with Offerings
+
+```typescript
+const offerings: Offerings = await getOfferings();
+
+// Get current offering
+const current = offerings.current;
+if (current) {
+  // Get monthly package
+  const monthly = current.monthly;
+  console.log('Monthly price:', monthly?.localizedPriceString);
+
+  // Get all packages
+  current.availablePackages.forEach(pkg => {
+    console.log(pkg.identifier, pkg.localizedPriceString);
+  });
+}
+```
+
+### Handling Purchase Results
+
+```typescript
+const result: PurchaseResult = await purchasePackage(selectedPackage);
+
+if (result.error) {
+  console.error('Purchase failed:', result.error.message);
+  return;
+}
+
+console.log('Purchase successful!');
+console.log('Transaction ID:', result.transaction?.transactionIdentifier);
+
+// Check entitlement
+if (result.customerInfo.entitlements.premium?.isActive) {
+  console.log('Premium is now active');
+}
+```
+
+### Checking Entitlement Details
+
+```typescript
+const entitlement: EntitlementInfo = customerInfo.entitlements.premium;
+
+if (entitlement) {
+  console.log('Active:', entitlement.isActive);
+  console.log('Will Renew:', entitlement.willRenew);
+  console.log('Period Type:', entitlement.periodType);
+  console.log('Expiration:', entitlement.expirationDate);
+  console.log('Store:', entitlement.store);
+  console.log('Is Sandbox:', entitlement.isSandbox);
+
+  if (entitlement.billingIssueDetectedAt) {
+    console.warn('Billing issue detected');
+  }
+
+  if (entitlement.unsubscribeDetectedAt) {
+    console.warn('User cancelled subscription');
+  }
+}
+```
+
+## Related
+
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Value Objects](../value-objects/README.md)
+- [RevenueCat Errors](../errors/README.md)
+- [RevenueCat Types](../types/README.md)

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

@@ -0,0 +1,197 @@
+# RevenueCat Domain Errors
+
+Domain-specific errors for RevenueCat operations.
+
+## Overview
+
+This directory contains custom error classes for RevenueCat-specific error conditions.
+
+## Error Types
+
+### PurchaseError
+Base error for purchase failures.
+
+```typescript
+class PurchaseError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public underlyingError?: Error
+  ) {
+    super(message);
+    this.name = 'PurchaseError';
+  }
+}
+```
+
+**Common Codes:**
+- `PURCHASE_CANCELLED`: User cancelled purchase
+- `PURCHASE_INVALID`: Invalid purchase data
+- `NETWORK_ERROR`: Network connectivity issue
+- `STORE_PROBLEM`: App store issue
+
+### EntitlementNotFoundError
+Thrown when expected entitlement is not found.
+
+```typescript
+class EntitlementNotFoundError extends Error {
+  constructor(public entitlementId: string) {
+    super(
+      `Entitlement not found: ${entitlementId}`,
+      'ENTITLEMENT_NOT_FOUND'
+    );
+    this.name = 'EntitlementNotFoundError';
+  }
+}
+```
+
+**Usage:**
+```typescript
+import { EntitlementNotFoundError } from './errors/EntitlementNotFoundError';
+
+function getEntitlement(customerInfo: CustomerInfo, id: string): Entitlement {
+  const entitlement = customerInfo.entitlements.active[id];
+  if (!entitlement) {
+    throw new EntitlementNotFoundError(id);
+  }
+  return entitlement;
+}
+```
+
+### ConfigurationError
+Thrown when RevenueCat configuration is invalid.
+
+```typescript
+class ConfigurationError extends Error {
+  constructor(missingConfig: string[]) {
+    super(
+      `RevenueCat not configured: ${missingConfig.join(', ')}`,
+      'CONFIGURATION_ERROR'
+    );
+    this.name = 'ConfigurationError';
+  }
+}
+```
+
+**Usage:**
+```typescript
+function validateRevenueCatConfig(config: any) {
+  const required = ['apiKey'];
+  const missing = required.filter(key => !config[key]);
+
+  if (missing.length > 0) {
+    throw new ConfigurationError(missing);
+  }
+}
+```
+
+### OfferingNotFoundError
+Thrown when requested offering is not available.
+
+```typescript
+class OfferingNotFoundError extends Error {
+  constructor(public offeringId: string) {
+    super(
+      `Offering not found: ${offeringId}`,
+      'OFFERING_NOT_FOUND'
+    );
+    this.name = 'OfferingNotFoundError';
+  }
+}
+```
+
+## Error Handling Pattern
+
+```typescript
+import {
+  PurchaseError,
+  EntitlementNotFoundError,
+  ConfigurationError
+} from './errors';
+
+async function handlePurchase(package: Package) {
+  try {
+    const result = await Purchases.purchasePackage(package);
+    return { success: true, result };
+  } catch (error) {
+    if (error instanceof UserCancelledError) {
+      // User cancelled - not really an error
+      return { success: false, cancelled: true };
+    }
+
+    if (error instanceof PurchaseError) {
+      switch (error.code) {
+        case 'PURCHASE_CANCELLED':
+          analytics.track('purchase_cancelled');
+          break;
+        case 'NETWORK_ERROR':
+          showRetryDialog();
+          break;
+        case 'STORE_PROBLEM':
+          showStoreProblemDialog();
+          break;
+        default:
+          showErrorDialog(error.message);
+      }
+      return { success: false, error };
+    }
+
+    // Unexpected error
+    console.error('Unexpected purchase error:', error);
+    return { success: false, error };
+  }
+}
+```
+
+## Error Recovery
+
+### Retry Logic
+```typescript
+async function purchaseWithRetry(pkg: Package, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const result = await Purchases.purchasePackage(pkg);
+      return result;
+    } catch (error) {
+      if (error instanceof PurchaseError) {
+        if (error.code === 'NETWORK_ERROR' && i < maxRetries - 1) {
+          await delay(1000 * (i + 1)); // Exponential backoff
+          continue;
+        }
+      }
+      throw error;
+    }
+  }
+}
+```
+
+### User-Friendly Messages
+```typescript
+function getUserFriendlyMessage(error: Error): string {
+  if (error instanceof PurchaseError) {
+    const messages: Record<string, string> = {
+      PURCHASE_CANCELLED: 'Purchase was cancelled',
+      NETWORK_ERROR: 'Network error. Please check your connection.',
+      STORE_PROBLEM: 'There was an issue with the app store.',
+      PURCHASE_INVALID: 'Purchase data is invalid.',
+    };
+    return messages[error.code] || 'An error occurred';
+  }
+  return error.message;
+}
+```
+
+## Best Practices
+
+1. **Specific Errors**: Use specific error types
+2. **Error Codes**: Include machine-readable codes
+3. **Context**: Include relevant data in error
+4. **Recovery**: Implement recovery strategies
+5. **User Feedback**: Convert errors to user-friendly messages
+6. **Logging**: Log errors for debugging
+7. **Analytics**: Track errors for monitoring
+
+## Related
+
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Services](../infrastructure/services/README.md)