@umituz/react-native-subscription 2.14.99 → 2.14.101

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

@@ -2,196 +2,52 @@
 
 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
+## Location
+
+`src/revenuecat/domain/errors/`
+
+## Strategy
+
+Custom error classes for RevenueCat-specific error conditions, providing typed error handling for purchase, entitlement, configuration, and offering failures.
+
+## Restrictions
+
+### REQUIRED
+
+- MUST use specific error types (not generic errors)
+- MUST include machine-readable error codes
+- MUST include relevant contextual data
+- MUST implement recovery strategies
+- MUST convert errors to user-friendly messages
+- MUST log errors for debugging
+- MUST track errors for analytics
+
+### PROHIBITED
+
+- MUST NOT expose sensitive RevenueCat API keys or tokens
+- MUST NOT leak raw RevenueCat errors to users
+- MUST NOT ignore error conditions
+
+### CRITICAL
+
+- Always implement specific error types
+- Include machine-readable codes for programmatic handling
+- Provide recovery strategies where applicable
+- Convert technical errors to user-friendly messages
+- Log all errors for debugging and monitoring
+
+## AI Agent Guidelines
+
+When working with RevenueCat errors:
+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 Documentation
 
 - [RevenueCat Domain](../README.md)
-- [RevenueCat Services](../infrastructure/services/README.md)
+- [RevenueCat Services](../../infrastructure/services/README.md)

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

@@ -1,373 +1,41 @@
 # RevenueCat Domain Types
 
+## Location
 Type definitions and type utilities for RevenueCat integration.
 
-## Overview
-
-This directory contains TypeScript type definitions, type guards, and utility types used throughout the RevenueCat integration.
-
-## Core Types
-
-### PurchasesError
-
-Error type for RevenueCat operations.
-
-```typescript
-interface PurchasesError {
-  code: string;
-  message: string;
-  underlyingErrorMessage?: string;
-  readableErrorMessage?: string;
-}
-
-type PurchasesErrorCode =
-  | 'UNKNOWN_ERROR'
-  | 'NETWORK_ERROR'
-  | 'INVALID_CREDENTIALS_ERROR'
-  | 'OPERATION_ALREADY_IN_PROGRESS'
-  | 'PRODUCT_NOT_AVAILABLE_FOR_PURCHASE'
-  | 'INVALIDreceipt_ERROR'
-  | 'MISSING_RECEIPT_ERROR'
-  | 'INVALID_APP_USER_ID_ERROR'
-  | 'CONFLICTING_SUBS_ERROR'
-  | 'CUSTOMER_INFO_ERROR'
-  | 'INVALID_CONFIGURATION_ERROR'
-  | 'UNSUPPORTED_OPERATION_ERROR'
-  | 'PURCHASE_CANCELLED'
-  | 'PURCHASE_INVALID'
-  | 'PRODUCT_ALREADY_OWNED'
-  | 'RECEIPT_ALREADY_IN_USE'
-  | 'INVALID_OFFERINGS_ERROR'
-  | 'INVALID_ELIGIBILITY_ERROR'
-  | 'INELIGIBLE_FOR_INTRO_PRICING'
-  | 'EXPIRED_RECEIPT_ERROR';
-```
-
-### PackageType
-
-Available package types.
-
-```typescript
-type PackageType =
-  | 'monthly'
-  | 'annual'
-  | 'lifetime'
-  | 'weekly'
-  | 'single_purchase';
-```
-
-### ProductType
-
-Types of products.
-
-```typescript
-type ProductType =
-  | 'subscription'
-  | 'non_subscription'
-  | 'consumable';
-```
-
-### PeriodType
-
-Subscription period types.
-
-```typescript
-type PeriodType =
-  | 'normal'
-  | 'trial'
-  | 'intro';
-```
-
-### Store
-
-Available app stores.
-
-```typescript
-type Store =
-  | 'app_store'
-  | 'play_store'
-  | 'stripe'
-  | 'mac_app_store'
-  | 'play_store_amazon'
-  | 'promotional';
-```
-
-### SubscriptionStatus
-
-Subscription status representation.
-
-```typescript
-type SubscriptionStatus =
-  | 'active'
-  | 'expired'
-  | 'cancelled'
-  | 'in_billing_retry'
-  | 'paused';
-
-interface SubscriptionInfo {
-  status: SubscriptionStatus;
-  expiresAt: Date | null;
-  willRenew: boolean;
-  periodType: PeriodType;
-  isTrial: boolean;
-  isIntro: boolean;
-  isSandbox: boolean;
-}
-```
-
-## Type Guards
-
-### isPurchasesError
-
-Check if an error is a PurchasesError.
-
-```typescript
-function isPurchasesError(error: unknown): error is PurchasesError {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    'message' in error
-  );
-}
-```
-
-### isActiveEntitlement
-
-Check if entitlement is active.
-
-```typescript
-function isActiveEntitlement(
-  entitlement: EntitlementInfo | null
-): entitlement is EntitlementInfo & { isActive: true } {
-  return entitlement?.isActive === true;
-}
-```
-
-### isSubscriptionProduct
-
-Check if product is a subscription.
-
-```typescript
-function isSubscriptionProduct(
-  product: Product
-): product is Product & { type: 'subscription' } {
-  return product.type === 'subscription';
-}
-```
-
-### isConsumableProduct
-
-Check if product is consumable.
-
-```typescript
-function isConsumableProduct(
-  product: Product
-): product is Product & { type: 'consumable' } {
-  return product.type === 'consumable';
-}
-```
-
-## Utility Types
-
-### PurchaseResult
-
-Result of a purchase operation.
-
-```typescript
-type PurchaseResult =
-  | { success: true; customerInfo: CustomerInfo; transaction: Transaction }
-  | { success: false; error: PurchasesError };
-```
-
-### RestoreResult
-
-Result of a restore operation.
-
-```typescript
-type RestoreResult =
-  | { success: true; customerInfo: CustomerInfo }
-  | { success: false; error: PurchasesError };
-```
-
-### EntitlementCheckResult
-
-Result of checking an entitlement.
-
-```typescript
-type EntitlementCheckResult =
-  | { hasAccess: true; entitlement: EntitlementInfo }
-  | { hasAccess: false; reason: 'not_entitled' | 'expired' | 'cancelled' };
-```
-
-### OfferingConfig
-
-Configuration for an offering.
-
-```typescript
-interface OfferingConfig {
-  identifier: string;
-  metadata?: {
-    highlight?: boolean;
-    recommended?: boolean;
-    discount_percentage?: number;
-    features?: string[];
-  };
-}
-```
-
-### PurchaseConfig
-
-Configuration for purchase flow.
-
-```typescript
-interface PurchaseConfig {
-  onPurchaseStarted?: () => void;
-  onPurchaseSuccess?: (result: PurchaseResult) => void;
-  onPurchaseError?: (error: PurchasesError) => void;
-  onPurchaseCancelled?: () => void;
-}
-```
-
-## Usage Examples
-
-### Using Type Guards
-
-```typescript
-import { isPurchasesError, isActiveEntitlement } from './types';
-
-try {
-  const result = await purchasePackage(pkg);
-} catch (error) {
-  if (isPurchasesError(error)) {
-    // Now TypeScript knows error is PurchasesError
-    console.error('Error code:', error.code);
-    console.error('Message:', error.message);
-  }
-}
-
-// Checking entitlements
-const premium = customerInfo.entitlements.premium;
-if (isActiveEntitlement(premium)) {
-  // TypeScript knows premium is active
-  console.log('Premium expires:', premium.expirationDate);
-}
-```
-
-### Using Utility Types
-
-```typescript
-async function handlePurchase(
-  pkg: Package
-): Promise<PurchaseResult> {
-  try {
-    const result = await revenueCatService.purchasePackage(pkg);
-    return {
-      success: true,
-      customerInfo: result.customerInfo,
-      transaction: result.transaction,
-    };
-  } catch (error) {
-    if (isPurchasesError(error)) {
-      return {
-        success: false,
-        error,
-      };
-    }
-    throw error;
-  }
-}
-
-// Usage
-const result = await handlePurchase(selectedPackage);
-
-if (result.success) {
-  console.log('Purchased:', result.transaction?.transactionIdentifier);
-} else {
-  console.error('Failed:', result.error.message);
-}
-```
-
-### Checking Entitlements
-
-```typescript
-function checkEntitlement(
-  customerInfo: CustomerInfo,
-  entitlementId: string
-): EntitlementCheckResult {
-  const entitlement = customerInfo.entitlements[entitlementId];
-
-  if (!entitlement) {
-    return { hasAccess: false, reason: 'not_entitled' };
-  }
-
-  if (!entitlement.isActive) {
-    if (entitlement.expirationDate && entitlement.expirationDate < new Date()) {
-      return { hasAccess: false, reason: 'expired' };
-    }
-    if (entitlement.unsubscribeDetectedAt) {
-      return { hasAccess: false, reason: 'cancelled' };
-    }
-    return { hasAccess: false, reason: 'not_entitled' };
-  }
-
-  return { hasAccess: true, entitlement };
-}
-
-// Usage
-const check = checkEntitlement(customerInfo, 'premium');
-
-if (check.hasAccess) {
-  console.log('Premium active');
-} else {
-  console.log('Reason:', check.reason);
-}
-```
-
-## Type Assertions
-
-### Assert Subscription Status
-
-```typescript
-function getSubscriptionStatus(
-  entitlement: EntitlementInfo | null
-): SubscriptionStatus {
-  if (!entitlement || !entitlement.isActive) {
-    return 'expired';
-  }
-
-  if (entitlement.billingIssueDetectedAt) {
-    return 'in_billing_retry';
-  }
-
-  if (entitlement.unsubscribeDetectedAt && !entitlement.willRenew) {
-    return 'cancelled';
-  }
-
-  return 'active';
-}
-```
-
-### Assert Product Type
-
-```typescript
-function getProductPrice(
-  product: Product
-): string | null {
-  if (isSubscriptionProduct(product)) {
-    return product.price.formattedPrice;
-  }
-
-  if (isConsumableProduct(product)) {
-    return product.price.formattedPrice;
-  }
-
-  return null;
-}
-```
-
-## Related
-
+## Strategy
+This directory contains TypeScript type definitions, type guards, and utility types used throughout the RevenueCat integration for type safety and compile-time checks.
+
+## Restrictions
+
+### REQUIRED
+- Must use type guards for runtime checks
+- Must provide utility types for common operations
+- Must maintain type safety throughout
+- Must use strict TypeScript types
+
+### PROHIBITED
+- DO NOT use `any` type
+- DO NOT bypass type guards
+- DO NOT ignore type safety
+- DO NOT use loose type definitions
+
+### CRITICAL SAFETY
+- All type checks MUST use type guards
+- All types MUST be strictly defined
+- Type assertions MUST be safe
+- Utility types MUST be used appropriately
+
+## AI Agent Guidelines
+1. Use type guards for runtime type checking
+2. Define utility types for common operations
+3. Maintain strict type safety throughout codebase
+4. Provide clear type definitions for all RevenueCat concepts
+5. Use type assertions only when safe
+6. Test type guards thoroughly
+7. Document complex types with comments
+
+## Related Documentation
 - [RevenueCat Domain](../README.md)
 - [RevenueCat Entities](../entities/README.md)
 - [RevenueCat Value Objects](../value-objects/README.md)