@umituz/react-native-subscription 2.14.98 → 2.14.100

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)

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

@@ -0,0 +1,41 @@
+# RevenueCat Domain Constants
+
+## Location
+Constants used throughout the RevenueCat integration.
+
+## Strategy
+This directory contains constant definitions for RevenueCat-specific values including entitlement IDs, error codes, and configuration defaults for maintainability and consistency.
+
+## Restrictions
+
+### REQUIRED
+- Must use constants for all RevenueCat-specific values
+- Must provide clear constant names
+- Must maintain consistency across codebase
+- Must document constant purposes
+
+### PROHIBITED
+- DO NOT use magic strings or numbers
+- DO NOT duplicate constant definitions
+- DO NOT use hardcoded values
+- DO NOT create ambiguous constants
+
+### CRITICAL SAFETY
+- All RevenueCat-specific values MUST use constants
+- Constants MUST be clearly named and documented
+- Constant values MUST be consistent
+- Entitlement IDs MUST match RevenueCat dashboard
+
+## AI Agent Guidelines
+1. Use constants for all RevenueCat-specific values
+2. Provide clear, descriptive constant names
+3. Maintain consistency across the codebase
+4. Document the purpose of each constant
+5. Organize constants by category (entitlements, offerings, errors)
+6. Validate constants match RevenueCat dashboard configuration
+7. Avoid magic strings and numbers throughout code
+
+## Related Documentation
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Errors](../errors/README.md)
+- [RevenueCat Entities](../entities/README.md)

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

@@ -0,0 +1,42 @@
+# RevenueCat Domain Entities
+
+## Location
+Core domain entities for RevenueCat integration.
+
+## Strategy
+This directory contains TypeScript type definitions and entities representing RevenueCat concepts like customer info, entitlements, offerings, and packages with proper type safety.
+
+## Restrictions
+
+### REQUIRED
+- Must use TypeScript types for all entities
+- Must maintain type safety
+- Must validate entity data
+- Must provide clear type definitions
+
+### PROHIBITED
+- DO NOT use `any` type for entities
+- DO NOT bypass type checking
+- DO NOT create invalid entity states
+- DO NOT use loose type definitions
+
+### CRITICAL SAFETY
+- All entities MUST be type-safe
+- Entity data MUST be validated
+- Type definitions MUST be clear and specific
+- Entity states MUST be valid
+
+## AI Agent Guidelines
+1. Define clear TypeScript types for all RevenueCat concepts
+2. Maintain strict type safety for all entities
+3. Validate entity data before use
+4. Provide comprehensive type definitions
+5. Document entity properties and relationships
+6. Use type guards for runtime validation
+7. Test entity creation and validation thoroughly
+
+## Related Documentation
+- [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

@@ -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

@@ -0,0 +1,41 @@
+# RevenueCat Domain Types
+
+## Location
+Type definitions and type utilities for RevenueCat integration.
+
+## 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)

package/src/revenuecat/domain/value-objects/README.md

@@ -0,0 +1,41 @@
+# RevenueCat Domain Value Objects
+
+## Location
+Value objects for RevenueCat integration.
+
+## Strategy
+This directory contains value objects - immutable types that represent concepts in the RevenueCat domain with no identity, defined by their attributes rather than identity.
+
+## Restrictions
+
+### REQUIRED
+- Must validate in constructor
+- Must keep value objects immutable
+- Must implement proper equality based on values
+- Must provide locale-aware formatting
+
+### PROHIBITED
+- DO NOT modify value objects after creation
+- DO NOT bypass validation in constructor
+- DO NOT use identity-based equality
+- DO NOT ignore locale in formatting
+
+### CRITICAL SAFETY
+- All value objects MUST be immutable
+- Validation MUST happen in constructor
+- Equality MUST be based on values, not identity
+- Formatting MUST be locale-aware
+
+## AI Agent Guidelines
+1. Never modify value objects after creation
+2. Validate all inputs in constructor with fail-fast
+3. Implement proper equality based on values
+4. Provide locale-aware formatting methods
+5. Return new instances for all operations
+6. Use TypeScript for compile-time type safety
+7. Provide toString/JSON methods if needed for serialization
+
+## Related Documentation
+- [RevenueCat Domain](../README.md)
+- [RevenueCat Entities](../entities/README.md)
+- [RevenueCat Types](../types/README.md)

package/src/revenuecat/infrastructure/README.md

@@ -0,0 +1,41 @@
+# RevenueCat Infrastructure
+
+## Location
+Infrastructure layer for RevenueCat integration.
+
+## Strategy
+This directory contains concrete implementations of RevenueCat interfaces, handling communication with the RevenueCat SDK and external services with proper error handling and data transformation.
+
+## Restrictions
+
+### REQUIRED
+- Must integrate directly with RevenueCat SDK
+- Must convert SDK errors to domain errors
+- Must map SDK types to domain types
+- Must manage purchase and customer info events
+
+### PROHIBITED
+- DO NOT expose SDK errors directly to application
+- DO NOT use SDK types in domain layer
+- DO NOT skip error mapping
+- DO NOT ignore lifecycle events
+
+### CRITICAL SAFETY
+- All SDK errors MUST be converted to domain errors
+- All SDK types MUST be mapped to domain types
+- All events MUST be handled appropriately
+- Configuration MUST be set up correctly
+
+## AI Agent Guidelines
+1. Integrate directly with RevenueCat SDK
+2. Convert all SDK errors to domain errors
+3. Map all SDK types to domain types
+4. Manage purchase and customer info events properly
+5. Set up and configure RevenueCat correctly
+6. Test SDK integration thoroughly
+7. Handle all edge cases in SDK communication
+
+## Related Documentation
+- [RevenueCat Integration](../README.md)
+- [RevenueCat Application](../application/README.md)
+- [RevenueCat Domain](../domain/README.md)