@umituz/react-native-subscription 2.14.99 → 2.14.100

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

@@ -1,183 +1,41 @@
 # RevenueCat Domain Constants
 
+## Location
 Constants used throughout the RevenueCat integration.
 
-## Overview
-
-This directory contains constant definitions for RevenueCat-specific values including entitlement IDs, error codes, and configuration defaults.
-
-## Constants
-
-### Entitlement IDs
-
-```typescript
-export const ENTITLEMENT_IDS = {
-  PREMIUM: 'premium',
-  PRO: 'pro',
-  LIFETIME: 'lifetime',
-} as const;
-
-export type EntitlementId = typeof ENTITLEMENT_IDS[keyof typeof ENTITLEMENT_IDS];
-```
-
-### Offering Identifiers
-
-```typescript
-export const OFFERING_IDS = {
-  DEFAULT: 'default',
-  ANNUAL_OFFER: 'annual_offer',
-  LIFETIME_OFFER: 'lifetime_offer',
-} as const;
-
-export type OfferingId = typeof OFFERING_IDS[keyof typeof OFFERING_IDS];
-```
-
-### Package Periods
-
-```typescript
-export const PACKAGE_PERIODS = {
-  MONTHLY: 'monthly',
-  ANNUAL: 'annual',
-  LIFETIME: 'lifetime',
-  WEEKLY: 'weekly',
-} as const;
-
-export type PackagePeriod = typeof PACKAGE_PERIODS[keyof typeof PACKAGE_PERIODS];
-```
-
-### Product Categories
-
-```typescript
-export const PRODUCT_CATEGORIES = {
-  SUBSCRIPTION: 'subscription',
-  ONE_TIME_PURCHASE: 'non_subscription',
-  CONSUMABLE: 'consumable',
-} as const;
-
-export type ProductCategory = typeof PRODUCT_CATEGORIES[keyof typeof PRODUCT_CATEGORIES];
-```
-
-### Error Codes
-
-```typescript
-export const ERROR_CODES = {
-  // Configuration Errors
-  CONFIGURATION_ERROR: 'CONFIGURATION_ERROR',
-  API_KEY_NOT_SET: 'API_KEY_NOT_SET',
-  INVALID_API_KEY: 'INVALID_API_KEY',
-
-  // Purchase Errors
-  PURCHASE_ERROR: 'PURCHASE_ERROR',
-  PURCHASE_CANCELLED: 'PURCHASE_CANCELLED',
-  PURCHASE_INVALID: 'PURCHASE_INVALID',
-  PRODUCT_NOT_AVAILABLE: 'PRODUCT_NOT_AVAILABLE',
-
-  // Network Errors
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT',
-  SERVER_ERROR: 'SERVER_ERROR',
-
-  // Customer Info Errors
-  CUSTOMER_INFO_ERROR: 'CUSTOMER_INFO_ERROR',
-  ENTITLEMENT_NOT_FOUND: 'ENTITLEMENT_NOT_FOUND',
-  OFFERING_NOT_FOUND: 'OFFERING_NOT_FOUND',
-
-  // Receipt Errors
-  RECEIPT_ERROR: 'RECEIPT_ERROR',
-  RECEIPT_INVALID: 'RECEIPT_INVALID',
-  RECEIPT_ALREADY_USED: 'RECEIPT_ALREADY_USES',
-
-  // User Errors
-  USER_NOT_AUTHENTICATED: 'USER_NOT_AUTHENTICATED',
-  USER_ID_NOT_SET: 'USER_ID_NOT_SET',
-} as const;
-```
-
-### Configuration Defaults
-
-```typescript
-export const CONFIG_DEFAULTS = {
-  // Timeout Settings
-  NETWORK_TIMEOUT_MS: 10000,
-  PURCHASE_TIMEOUT_MS: 30000,
-
-  // Retry Settings
-  MAX_RETRIES: 3,
-  RETRY_DELAY_MS: 1000,
-
-  // Cache Settings
-  CUSTOMER_INFO_CACHE_TTL_MS: 60000, // 1 minute
-  OFFERINGS_CACHE_TTL_MS: 300000, // 5 minutes
-
-  // Debug Settings
-  ENABLE_DEBUG_LOGS: __DEV__,
-  LOG_LEVEL: 'info' as const,
-} as const;
-```
-
-### Entitlement Verification
-
-```typescript
-export const ENTITLEMENT_VERIFICATION = {
-  // Verification Modes
-  MODE_STRICT: 'strict',
-  MODE_LOOSE: 'loose',
-
-  // Grace Periods (milliseconds)
-  GRACE_PERIOD_MS: 3 * 24 * 60 * 60 * 1000, // 3 days
-  REFUND_GRACE_PERIOD_MS: 7 * 24 * 60 * 60 * 1000, // 7 days
-} as const;
-```
-
-## Usage Examples
-
-### Checking Entitlements
-
-```typescript
-import { ENTITLEMENT_IDS } from './constants';
-
-const hasPremium = await checkEntitlement(ENTITLEMENT_IDS.PREMIUM);
-```
-
-### Filtering Offerings
-
-```typescript
-import { OFFERING_IDS } from './constants';
-
-const defaultOffering = offerings[OFFERING_IDS.DEFAULT];
-const annualOffering = offerings[OFFERING_IDS.ANNUAL_OFFER];
-```
-
-### Handling Errors
-
-```typescript
-import { ERROR_CODES } from './constants';
-
-try {
-  await purchasePackage(pkg);
-} catch (error) {
-  if (error.code === ERROR_CODES.PURCHASE_CANCELLED) {
-    // Handle cancellation
-  } else if (error.code === ERROR_CODES.NETWORK_ERROR) {
-    // Handle network error
-  }
-}
-```
-
-### Configuration
-
-```typescript
-import { CONFIG_DEFAULTS } from './constants';
-
-const config = {
-  apiKey: 'your_api_key',
-  timeout: CONFIG_DEFAULTS.NETWORK_TIMEOUT_MS,
-  enableDebugLogs: CONFIG_DEFAULTS.ENABLE_DEBUG_LOGS,
-};
-```
-
-## Related
-
+## 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

@@ -1,381 +1,41 @@
 # RevenueCat Domain Entities
 
+## Location
 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
-
+## 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)