@umituz/react-native-subscription 2.14.97 → 2.14.99

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

@@ -0,0 +1,382 @@
+# RevenueCat Infrastructure Utils
+
+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
+
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Domain Types](../../domain/types/README.md)
+- [RevenueCat Errors](../../domain/errors/README.md)

package/src/revenuecat/presentation/README.md

@@ -0,0 +1,184 @@
+# RevenueCat Presentation
+
+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
+
+- [RevenueCat Integration](../README.md)
+- [RevenueCat Application](../application/README.md)
+- [RevenueCat Infrastructure](../infrastructure/README.md)
+- [RevenueCat Domain](../domain/README.md)

package/src/revenuecat/presentation/hooks/README.md

@@ -0,0 +1,56 @@
+# RevenueCat Presentation Hooks
+
+React hooks for accessing RevenueCat data and operations.
+
+## Overview
+
+This directory contains React hooks that expose RevenueCat functionality to the presentation layer.
+
+## Contents
+
+- **useCustomerInfo.ts** - Hook for accessing RevenueCat customer info
+- **useSubscriptionPackages.ts** - Hook for accessing subscription packages/offering
+
+## Key Hooks
+
+### useCustomerInfo
+
+Access RevenueCat customer information including entitlements.
+
+```typescript
+function useCustomerInfo() {
+  const { customerInfo, isLoading } = useCustomerInfo();
+
+  return (
+    <View>
+      <Text>Entitlements: {Object.keys(customerInfo.entitlements.active).join(', ')}</Text>
+    </View>
+  );
+}
+```
+
+### useSubscriptionPackages
+
+Access available subscription packages from current offering.
+
+```typescript
+function PackageList() {
+  const { packages, isLoading } = useSubscriptionPackages();
+
+  if (isLoading) return <Loading />;
+
+  return (
+    <View>
+      {packages.map(pkg => (
+        <PackageCard key={pkg.identifier} package={pkg} />
+      ))}
+    </View>
+  );
+}
+```
+
+## Related
+
+- [Main Hooks](../../../presentation/hooks/README.md)
+- [Domain](../../domain/README.md)
+- [Services](../infrastructure/services/README.md)