@umituz/react-native-subscription 2.14.99 → 2.14.100

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

@@ -1,382 +1,41 @@
 # RevenueCat Infrastructure Utils
 
+## Location
 Utility functions for RevenueCat operations.
 
-## Overview
-
-This directory contains utility functions for common RevenueCat operations including error mapping, data transformation, and validation.
-
-## Utilities
-
-### Error Mapping
-
-Convert RevenueCat SDK errors to domain errors.
-
-```typescript
-function mapRevenueCatError(error: PurchasesError): DomainError {
-  switch (error.code) {
-    case 'PURCHASE_CANCELLED':
-      return {
-        code: 'PURCHASE_CANCELLED',
-        message: 'Purchase was cancelled',
-        userMessage: 'You cancelled the purchase',
-      };
-
-    case 'NETWORK_ERROR':
-      return {
-        code: 'NETWORK_ERROR',
-        message: 'Network error occurred',
-        userMessage: 'Please check your internet connection',
-      };
-
-    case 'INVALID_CREDENTIALS_ERROR':
-      return {
-        code: 'CONFIGURATION_ERROR',
-        message: 'Invalid RevenueCat credentials',
-        userMessage: 'Configuration error. Please contact support.',
-      };
-
-    case 'PRODUCT_NOT_AVAILABLE_FOR_PURCHASE':
-      return {
-        code: 'PRODUCT_NOT_AVAILABLE',
-        message: 'Product not available',
-        userMessage: 'This product is currently unavailable',
-      };
-
-    default:
-      return {
-        code: 'UNKNOWN_ERROR',
-        message: error.message || 'Unknown error',
-        userMessage: 'An error occurred. Please try again.',
-      };
-  }
-}
-```
-
-### Entitlement Extraction
-
-Extract entitlement information from customer info.
-
-```typescript
-function extractEntitlementInfo(
-  customerInfo: CustomerInfo,
-  entitlementId: string
-): EntitlementInfo | null {
-  const entitlement = customerInfo.entitlements[entitlementId];
-
-  if (!entitlement) {
-    return null;
-  }
-
-  return {
-    identifier: entitlementId,
-    isActive: entitlement.isActive,
-    willRenew: entitlement.willRenew,
-    periodType: entitlement.periodType,
-    productId: entitlement.productId,
-    latestPurchaseDate: entitlement.latestPurchaseDate,
-    originalPurchaseDate: entitlement.originalPurchaseDate,
-    expirationDate: entitlement.expirationDate,
-    renewAt: entitlement.renewAt,
-    isSandbox: entitlement.isSandbox,
-    billingIssueDetectedAt: entitlement.billingIssueDetectedAt,
-    unsubscribeDetectedAt: entitlement.unsubscribeDetectedAt,
-    store: entitlement.store,
-  };
-}
-```
-
-### Package Filtering
-
-Filter packages by type or criteria.
-
-```typescript
-function filterPackagesByType(
-  offering: Offering,
-  packageType: PackageType
-): Package[] {
-  return offering.availablePackages.filter(
-    pkg => pkg.packageType === packageType
-  );
-}
-
-function getSubscriptionPackages(offering: Offering): Package[] {
-  return offering.availablePackages.filter(pkg =>
-    ['monthly', 'annual', 'weekly'].includes(pkg.packageType)
-  );
-}
-
-function getLifetimePackages(offering: Offering): Package[] {
-  return offering.availablePackages.filter(pkg =>
-    pkg.packageType === 'lifetime'
-  );
-}
-
-function getSinglePurchasePackages(offering: Offering): Package[] {
-  return offering.availablePackages.filter(pkg =>
-    pkg.packageType === 'single_purchase'
-  );
-}
-```
-
-### Price Formatting
-
-Format prices for display.
-
-```typescript
-function formatPrice(
-  price: Price,
-  locale?: string
-): string {
-  return new Intl.NumberFormat(locale, {
-    style: 'currency',
-    currency: price.currencyCode,
-  }).format(price.amount);
-}
-
-function formatPricePerMonth(
-  package: Package,
-  locale?: string
-): string {
-  const { price, product } = package;
-
-  if (product.subscriptionPeriod) {
-    const { value, unit } = product.subscriptionPeriod;
-
-    // Calculate monthly equivalent
-    let months = 1;
-    if (unit === 'week') months = value / 4;
-    if (unit === 'month') months = value;
-    if (unit === 'year') months = value * 12;
-
-    const monthlyPrice = price.amount / months;
-    return formatPrice(
-      { amount: monthlyPrice, currencyCode: price.currencyCode },
-      locale
-    );
-  }
-
-  return formatPrice(price, locale);
-}
-```
-
-### Period Formatting
-
-Format subscription periods.
-
-```typescript
-function formatPeriod(
-  period: SubscriptionPeriod,
-  locale = 'en-US'
-): string {
-  const formatter = new Intl.RelativeTimeFormat(locale, {
-    numeric: 'always',
-  });
-  return formatter.format(period.value, period.unit);
-}
-
-function getPeriodInMonths(period: SubscriptionPeriod): number {
-  switch (period.unit) {
-    case 'day': return period.value / 30;
-    case 'week': return period.value / 4;
-    case 'month': return period.value;
-    case 'year': return period.value * 12;
-  }
-}
-
-function getPeriodInDays(period: SubscriptionPeriod): number {
-  switch (period.unit) {
-    case 'day': return period.value;
-    case 'week': return period.value * 7;
-    case 'month': return period.value * 30;
-    case 'year': return period.value * 365;
-  }
-}
-```
-
-### Subscription Status
-
-Determine subscription status from entitlement.
-
-```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';
-}
-
-function getSubscriptionStatusType(
-  entitlement: EntitlementInfo | null
-): 'active' | 'expired' | 'canceled' | 'none' {
-  if (!entitlement) {
-    return 'none';
-  }
-
-  if (!entitlement.isActive) {
-    return 'expired';
-  }
-
-  if (entitlement.unsubscribeDetectedAt && !entitlement.willRenew) {
-    return 'canceled';
-  }
-
-  return 'active';
-}
-```
-
-### Validation
-
-Validate RevenueCat data.
-
-```typescript
-function isValidEntitlementId(id: string): boolean {
-  const validIds = ['premium', 'pro', 'lifetime'];
-  return validIds.includes(id);
-}
-
-function isValidOffering(offering: Offering | null): boolean {
-  return (
-    offering !== null &&
-    offering.availablePackages.length > 0
-  );
-}
-
-function isValidPackage(pkg: Package | null): boolean {
-  return (
-    pkg !== null &&
-    !!pkg.identifier &&
-    !!pkg.product &&
-    !!pkg.price
-  );
-}
-```
-
-### Debug Helpers
-
-Helper functions for debugging.
-
-```typescript
-function logCustomerInfo(info: CustomerInfo): void {
-  if (__DEV__) {
-    console.log('[RevenueCat] Customer Info:', {
-      userId: info.originalAppUserId,
-      activeSubscriptions: info.activeSubscriptions,
-      allPurchasedProductIds: info.allPurchasedProductIds,
-      entitlements: Object.keys(info.entitlements),
-    });
-  }
-}
-
-function logPurchaseResult(result: PurchaseResult): void {
-  if (__DEV__) {
-    console.log('[RevenueCat] Purchase Result:', {
-      transactionId: result.transaction?.transactionIdentifier,
-      productId: result.transaction?.productIdentifier,
-      hasPremium: !!result.customerInfo.entitlements.premium?.isActive,
-    });
-  }
-}
-
-function logError(error: PurchasesError): void {
-  if (__DEV__) {
-    console.error('[RevenueCat] Error:', {
-      code: error.code,
-      message: error.message,
-      readableMessage: error.readableErrorMessage,
-    });
-  }
-}
-```
-
-## Usage Examples
-
-### Using Error Mapping
-
-```typescript
-import { mapRevenueCatError } from './utils';
-
-try {
-  const result = await purchasePackage(pkg);
-} catch (error) {
-  const domainError = mapRevenueCatError(error);
-
-  // Show user-friendly message
-  Alert.alert('Error', domainError.userMessage);
-
-  // Log technical details
-  console.error(domainError.message);
-}
-```
-
-### Extracting Entitlement Info
-
-```typescript
-import { extractEntitlementInfo } from './utils';
-
-const customerInfo = await getCustomerInfo();
-const premium = extractEntitlementInfo(customerInfo, 'premium');
-
-if (premium?.isActive) {
-  console.log('Premium active until', premium.expirationDate);
-}
-```
-
-### Filtering Packages
-
-```typescript
-import { filterPackagesByType, getSubscriptionPackages } from './utils';
-
-const offering = await getOfferings();
-const monthlyPackages = filterPackagesByType(offering.current, 'monthly');
-const allSubscriptions = getSubscriptionPackages(offering.current);
-```
-
-### Formatting Prices
-
-```typescript
-import { formatPrice, formatPricePerMonth } from './utils';
-
-// Standard price
-const priceString = formatPrice(pkg.price, 'en-US'); // '$9.99'
-const priceStringTR = formatPrice(pkg.price, 'tr-TR'); // '9,99 $'
-
-// Per month (for annual)
-const perMonth = formatPricePerMonth(annualPackage, 'en-US'); // '$8.33/mo'
-```
-
-### Getting Subscription Status
-
-```typescript
-import { getSubscriptionStatus, getSubscriptionStatusType } from './utils';
-
-const entitlement = customerInfo.entitlements.premium;
-const status = getSubscriptionStatus(entitlement); // 'active'
-const statusType = getSubscriptionStatusType(entitlement); // 'active'
-```
-
-## Best Practices
-
-1. **Error Handling**: Always use error mapping for user-facing messages
-2. **Type Safety**: Ensure types are validated before use
-3. **Locale**: Respect user locale for formatting
-4. **Null Checks**: Always check for null/undefined values
-5. **Logging**: Use debug helpers in development
-6. **Validation**: Validate data before processing
-
-## Related
-
+## Strategy
+This directory contains utility functions for common RevenueCat operations including error mapping, data transformation, validation, and formatting with proper type safety.
+
+## Restrictions
+
+### REQUIRED
+- Must use error mapping for user-facing messages
+- Must ensure types are validated before use
+- Must respect user locale for formatting
+- Must check for null/undefined values
+
+### PROHIBITED
+- DO NOT show SDK errors directly to users
+- DO NOT use data without type validation
+- DO NOT ignore locale settings
+- DO NOT skip null checks
+
+### CRITICAL SAFETY
+- All errors MUST be mapped to domain errors
+- All types MUST be validated before use
+- Locale MUST be respected for formatting
+- Null checks MUST be performed consistently
+
+## AI Agent Guidelines
+1. Always map SDK errors to domain errors for user-facing messages
+2. Ensure type safety by validating types before use
+3. Respect user locale when formatting prices and periods
+4. Always check for null/undefined values before processing
+5. Use debug helpers in development for troubleshooting
+6. Validate all data before processing
+7. Test utility functions with edge cases
+
+## Related Documentation
 - [RevenueCat Infrastructure](../README.md)
 - [RevenueCat Domain Types](../../domain/types/README.md)
 - [RevenueCat Errors](../../domain/errors/README.md)

package/src/revenuecat/presentation/README.md

@@ -1,183 +1,41 @@
 # RevenueCat Presentation
 
+## Location
 Presentation layer for RevenueCat integration.
 
-## Overview
-
-This directory contains React hooks, components, and utilities for integrating RevenueCat functionality into the UI layer.
-
-## Components
-
-This directory may contain:
-
-### Hooks
-
-Custom React hooks for RevenueCat operations.
-
-**Potential Hooks:**
-- `useRevenueCatCustomerInfo` - Fetch and monitor customer info
-- `useRevenueCatOfferings` - Fetch available offerings
-- `useRevenueCatPurchase` - Handle purchase flow
-- `useRevenueCatEntitlement` - Check entitlement status
-
-**Example:**
-```typescript
-function useRevenueCatOfferings() {
-  const [offerings, setOfferings] = useState<Offerings | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    loadOfferings();
-  }, []);
-
-  const loadOfferings = async () => {
-    try {
-      setLoading(true);
-      const service = getRevenueCatService();
-      const result = await service.getOfferings();
-      setOfferings(result);
-    } catch (err) {
-      setError(err as Error);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return { offerings, loading, error, refetch: loadOfferings };
-}
-```
-
-### Components
-
-React components for displaying RevenueCat data.
-
-**Potential Components:**
-- `PackageList` - Display available packages
-- `PackageCard` - Display individual package
-- `EntitlementBadge` - Show entitlement status
-- `SubscriptionStatus` - Display subscription status
-
-**Example:**
-```typescript
-function PackageCard({
-  package,
-  onPress,
-  highlight = false,
-}: {
-  package: Package;
-  onPress: () => void;
-  highlight?: boolean;
-}) {
-  return (
-    <TouchableOpacity
-      onPress={onPress}
-      style={[styles.card, highlight && styles.highlight]}
-    >
-      <Text style={styles.title}>
-        {package.product.title}
-      </Text>
-      <Text style={styles.price}>
-        {package.localizedPriceString}
-      </Text>
-      {package.product.description && (
-        <Text style={styles.description}>
-          {package.product.description}
-        </Text>
-      )}
-    </TouchableOpacity>
-  );
-}
-```
-
-## Usage Patterns
-
-### Displaying Offerings
-
-```typescript
-import { useRevenueCatOfferings } from './hooks/useRevenueCatOfferings';
-import { PackageCard } from './components/PackageCard';
-
-function PremiumPackages() {
-  const { offerings, loading, error } = useRevenueCatOfferings();
-
-  if (loading) return <LoadingSpinner />;
-  if (error) return <Error message={error.message} />;
-  if (!offerings?.current) return <EmptyState />;
-
-  return (
-    <ScrollView horizontal>
-      {offerings.current.availablePackages.map(pkg => (
-        <PackageCard
-          key={pkg.identifier}
-          package={pkg}
-          onPress={() => handlePurchase(pkg)}
-          highlight={pkg.packageType === 'annual'}
-        />
-      ))}
-    </ScrollView>
-  );
-}
-```
-
-### Checking Entitlements
-
-```typescript
-import { useRevenueCatCustomerInfo } from './hooks/useRevenueCatCustomerInfo';
-
-function PremiumContent() {
-  const { customerInfo, loading } = useRevenueCatCustomerInfo();
-
-  if (loading) return <LoadingSpinner />;
-
-  const hasPremium = customerInfo?.entitlements.premium?.isActive ?? false;
-
-  if (!hasPremium) {
-    return <UpgradePrompt />;
-  }
-
-  return <PremiumFeatures />;
-}
-```
-
-### Purchase Flow
-
-```typescript
-import { useRevenueCatPurchase } from './hooks/useRevenueCatPurchase';
-
-function PurchaseButton({ package }: { package: Package }) {
-  const { purchase, purchasing } = useRevenueCatPurchase();
-
-  const handlePurchase = async () => {
-    const result = await purchase(package);
-
-    if (result.error) {
-      Alert.alert('Purchase Failed', result.error.message);
-    } else {
-      Alert.alert('Success', 'Purchase completed!');
-    }
-  };
-
-  return (
-    <Button onPress={handlePurchase} disabled={purchasing}>
-      {purchasing ? 'Purchasing...' : 'Subscribe'}
-    </Button>
-  );
-}
-```
-
-## Best Practices
-
-1. **Loading States**: Always show loading states during async operations
-2. **Error Handling**: Handle and display errors appropriately
-3. **Optimistic Updates**: Update UI optimistically where possible
-4. **Caching**: Cache customer info and offerings
-5. **Reactivity**: Re-render on entitlement changes
-6. **User Feedback**: Provide clear feedback during purchases
-7. **Validation**: Validate data before displaying
-
-## Related
-
+## Strategy
+This directory contains React hooks, components, and utilities for integrating RevenueCat functionality into the UI layer with proper loading states, error handling, and caching.
+
+## Restrictions
+
+### REQUIRED
+- Must show loading states during async operations
+- Must handle and display errors appropriately
+- Must cache customer info and offerings
+- Must re-render on entitlement changes
+
+### PROHIBITED
+- DO NOT skip loading states
+- DO NOT show technical errors to users
+- DO NOT ignore cache invalidation
+- DO NOT prevent re-renders on state changes
+
+### CRITICAL SAFETY
+- All async operations MUST show loading states
+- All errors MUST be handled and displayed appropriately
+- Data MUST be cached appropriately
+- UI MUST re-render on entitlement changes
+
+## AI Agent Guidelines
+1. Always show loading states during async operations
+2. Handle and display errors appropriately to users
+3. Update UI optimistically where possible
+4. Cache customer info and offerings appropriately
+5. Re-render on entitlement changes
+6. Provide clear feedback during purchases
+7. Validate data before displaying to users
+
+## Related Documentation
 - [RevenueCat Integration](../README.md)
 - [RevenueCat Application](../application/README.md)
 - [RevenueCat Infrastructure](../infrastructure/README.md)