@umituz/react-native-subscription 2.26.14 → 2.26.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.26.14",
+  "version": "2.26.16",
   "description": "Complete subscription management with RevenueCat, paywall UI, and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domains/paywall/components/PaywallModal.tsx

@@ -16,6 +16,14 @@ import { usePurchaseLoadingStore, selectIsPurchasing } from "../../../presentati
 
 declare const __DEV__: boolean;
 
+/** Trial eligibility info per product */
+export interface TrialEligibilityInfo {
+  /** Whether eligible for trial */
+  eligible: boolean;
+  /** Trial duration in days */
+  durationDays?: number;
+}
+
 export interface PaywallModalProps {
   visible: boolean;
   onClose: () => void;
@@ -30,10 +38,12 @@ export interface PaywallModalProps {
   heroImage?: ImageSourcePropType;
   onPurchase?: (pkg: PurchasesPackage) => Promise<void | boolean>;
   onRestore?: () => Promise<void | boolean>;
+  /** Trial eligibility map per product ID */
+  trialEligibility?: Record<string, TrialEligibilityInfo>;
 }
 
 export const PaywallModal: React.FC<PaywallModalProps> = React.memo((props) => {
-  const { visible, onClose, translations, packages = [], features = [], isLoading = false, legalUrls = {}, bestValueIdentifier, creditAmounts, creditsLabel, heroImage, onPurchase, onRestore } = props;
+  const { visible, onClose, translations, packages = [], features = [], isLoading = false, legalUrls = {}, bestValueIdentifier, creditAmounts, creditsLabel, heroImage, onPurchase, onRestore, trialEligibility = {} } = props;
   const tokens = useAppDesignTokens();
   const [selectedPlanId, setSelectedPlanId] = useState<string | null>(null);
   const [isLocalProcessing, setIsLocalProcessing] = useState(false);
@@ -114,7 +124,11 @@ export const PaywallModal: React.FC<PaywallModalProps> = React.memo((props) => {
 
           <View style={styles.header}>
             <AtomicText type="headlineMedium" style={[styles.title, { color: tokens.colors.textPrimary }]}>{translations.title}</AtomicText>
-            {translations.subtitle && <AtomicText type="bodyMedium" style={[styles.subtitle, { color: tokens.colors.textSecondary }]}>{translations.subtitle}</AtomicText>}
+            {(translations.trialSubtitle || translations.subtitle) && (
+              <AtomicText type="bodyMedium" style={[styles.subtitle, { color: tokens.colors.textSecondary }]}>
+                {translations.trialSubtitle ?? translations.subtitle}
+              </AtomicText>
+            )}
           </View>
 
           <PaywallFeatures features={features} />
@@ -123,17 +137,26 @@ export const PaywallModal: React.FC<PaywallModalProps> = React.memo((props) => {
             <View style={styles.loading}><AtomicSpinner size="lg" color="primary" text={translations.loadingText} /></View>
           ) : (
             <View style={styles.plans}>
-              {packages.map((pkg) => (
-                <PlanCard
-                  key={pkg.product.identifier}
-                  pkg={pkg}
-                  isSelected={selectedPlanId === pkg.product.identifier}
-                  onSelect={() => setSelectedPlanId(pkg.product.identifier)}
-                  badge={pkg.product.identifier === bestValueIdentifier ? translations.bestValueBadgeText : undefined}
-                  creditAmount={creditAmounts?.[pkg.product.identifier]}
-                  creditsLabel={creditsLabel}
-                />
-              ))}
+              {packages.map((pkg) => {
+                const productId = pkg.product.identifier;
+                const eligibility = trialEligibility[productId];
+                const hasFreeTrial = eligibility?.eligible ?? false;
+
+                return (
+                  <PlanCard
+                    key={productId}
+                    pkg={pkg}
+                    isSelected={selectedPlanId === productId}
+                    onSelect={() => setSelectedPlanId(productId)}
+                    badge={productId === bestValueIdentifier ? translations.bestValueBadgeText : undefined}
+                    creditAmount={creditAmounts?.[productId]}
+                    creditsLabel={creditsLabel}
+                    hasFreeTrial={hasFreeTrial}
+                    trialDurationDays={eligibility?.durationDays}
+                    trialBadgeText={hasFreeTrial ? translations.trialBadgeText : undefined}
+                  />
+                );
+              })}
             </View>
           )}
 

package/src/domains/paywall/components/PlanCard.tsx

@@ -17,14 +17,23 @@ interface PlanCardProps {
     badge?: string;
     creditAmount?: number;
     creditsLabel?: string;
+    /** Whether this plan has a free trial */
+    hasFreeTrial?: boolean;
+    /** Trial duration in days */
+    trialDurationDays?: number;
+    /** Trial badge text (e.g., "7 days free") */
+    trialBadgeText?: string;
 }
 
 export const PlanCard: React.FC<PlanCardProps> = React.memo(
-    ({ pkg, isSelected, onSelect, badge, creditAmount, creditsLabel }) => {
+    ({ pkg, isSelected, onSelect, badge, creditAmount, creditsLabel, hasFreeTrial, trialBadgeText }) => {
         const tokens = useAppDesignTokens();
         const title = pkg.product.title;
         const price = formatPrice(pkg.product.price, pkg.product.currencyCode);
 
+        // Determine which badge to show (trial badge takes priority if eligible)
+        const displayBadge = hasFreeTrial && trialBadgeText ? trialBadgeText : badge;
+
         return (
             <TouchableOpacity onPress={onSelect} activeOpacity={0.7} style={styles.touchable}>
                 <View
@@ -37,9 +46,13 @@ export const PlanCard: React.FC<PlanCardProps> = React.memo(
                         },
                     ]}
                 >
-                    {badge && (
+                    {displayBadge && (
                         <View style={styles.badgeContainer}>
-                            <AtomicBadge text={badge} variant="primary" size="sm" />
+                            <AtomicBadge
+                                text={displayBadge}
+                                variant={hasFreeTrial ? "success" : "primary"}
+                                size="sm"
+                            />
                         </View>
                     )}
 

package/src/domains/paywall/entities/types.ts

@@ -41,6 +41,10 @@ export interface PaywallTranslations {
     privacyText?: string;
     termsOfServiceText?: string;
     bestValueBadgeText?: string;
+    /** Trial-related translations */
+    trialBadgeText?: string;
+    /** Trial subtitle (e.g., "Try free for 7 days, then $X/year") */
+    trialSubtitle?: string;
 }
 
 export interface PaywallLegalUrls {

package/src/domains/paywall/hooks/usePaywallTranslations.ts

@@ -13,6 +13,10 @@ interface PaywallTranslationKeys {
   processingText: string;
   privacyText: string;
   termsOfServiceText: string;
+  /** Trial badge text key */
+  trialBadgeText?: string;
+  /** Trial subtitle key */
+  trialSubtitle?: string;
 }
 
 interface UsePaywallTranslationsParams {
@@ -38,6 +42,8 @@ const DEFAULT_KEYS: PaywallTranslationKeys = {
   processingText: "paywall.processing",
   privacyText: "auth.privacyPolicy",
   termsOfServiceText: "auth.termsOfService",
+  trialBadgeText: "paywall.trial.badge",
+  trialSubtitle: "paywall.trial.subtitle",
 };
 
 export const usePaywallTranslations = ({
@@ -62,6 +68,8 @@ export const usePaywallTranslations = ({
       processingText: t(mergedKeys.processingText),
       privacyText: t(mergedKeys.privacyText),
       termsOfServiceText: t(mergedKeys.termsOfServiceText),
+      trialBadgeText: mergedKeys.trialBadgeText ? t(mergedKeys.trialBadgeText) : undefined,
+      trialSubtitle: mergedKeys.trialSubtitle ? t(mergedKeys.trialSubtitle) : undefined,
     }),
     [t, mergedKeys],
   );

package/src/presentation/hooks/index.ts

@@ -1,25 +1,12 @@
 export * from "./useAuthAwarePurchase";
-export * from "./useAuthGate";
 export * from "./useAuthSubscriptionSync";
 export * from "./useSavedPurchaseAutoExecution";
-export * from "./useCreditChecker";
 export * from "./useCredits";
-export * from "./useCreditsGate";
 export * from "./useDeductCredit";
-export * from "./useInitializeCredits";
-export * from "./useDevTestCallbacks";
 export * from "./useFeatureGate";
 export * from "./usePaywallVisibility";
 export * from "./usePremium";
-export * from "./usePremiumGate";
-export * from "./usePremiumWithCredits";
-export * from "./useSubscription";
-export * from "./useSubscriptionDetails";
-export * from "./useSubscriptionGate";
 export * from "./useSubscriptionSettingsConfig";
 export * from "./useSubscriptionStatus";
-export * from "./useUserTier";
-export * from "./useUserTierWithRepository";
-export * from "./useTrialEligibility";
 export * from "./feedback/usePaywallFeedback";
 export * from "./feedback/useFeedbackSubmit";

package/src/presentation/hooks/useFeatureGate.ts

@@ -1,13 +1,10 @@
 /**
  * useFeatureGate Hook
- * Combines auth, subscription, and credits gates into a unified feature gate.
+ * Unified feature gate: Auth → Subscription → Credits
  * Uses ref pattern to avoid stale closure issues.
  */
 
 import { useCallback, useRef, useEffect } from "react";
-import { useAuthGate } from "./useAuthGate";
-import { useSubscriptionGate } from "./useSubscriptionGate";
-import { useCreditsGate } from "./useCreditsGate";
 
 declare const __DEV__: boolean;
 
@@ -29,9 +26,7 @@ export interface UseFeatureGateResult {
   readonly canAccess: boolean;
 }
 
-export function useFeatureGate(
-  params: UseFeatureGateParams
-): UseFeatureGateResult {
+export function useFeatureGate(params: UseFeatureGateParams): UseFeatureGateResult {
   const {
     isAuthenticated,
     onShowAuthModal,
@@ -79,22 +74,6 @@ export function useFeatureGate(
     prevCreditBalanceRef.current = creditBalance;
   }, [creditBalance]);
 
-  const authGate = useAuthGate({
-    isAuthenticated,
-    onAuthRequired: onShowAuthModal,
-  });
-
-  const subscriptionGate = useSubscriptionGate({
-    hasSubscription,
-    onSubscriptionRequired: () => onShowPaywall(requiredCredits),
-  });
-
-  const creditsGate = useCreditsGate({
-    creditBalance,
-    requiredCredits,
-    onCreditsRequired: onShowPaywall,
-  });
-
   const requireFeature = useCallback(
     (action: () => void | Promise<void>) => {
       if (typeof __DEV__ !== "undefined" && __DEV__) {
@@ -106,7 +85,7 @@ export function useFeatureGate(
         });
       }
 
-      if (!authGate.requireAuth(() => {})) {
+      if (!isAuthenticated) {
         const postAuthAction = () => {
           if (hasSubscriptionRef.current) {
             action();
@@ -132,30 +111,30 @@ export function useFeatureGate(
         return;
       }
 
-      if (!creditsGate.requireCredits()) {
+      const currentBalance = creditBalanceRef.current;
+      if (currentBalance < requiredCredits) {
+        if (typeof __DEV__ !== "undefined" && __DEV__) {
+          console.log("[useFeatureGate] No credits, showing paywall");
+        }
         pendingActionRef.current = action;
         isWaitingForPurchaseRef.current = true;
+        onShowPaywall(requiredCredits);
         return;
       }
 
       action();
     },
-    [authGate, creditsGate, hasSubscription, requiredCredits, isAuthenticated, onShowAuthModal]
+    [isAuthenticated, hasSubscription, requiredCredits, onShowAuthModal, onShowPaywall]
   );
 
   const hasCredits = creditBalance >= requiredCredits;
 
   return {
     requireFeature,
-    isAuthenticated: authGate.isAuthenticated,
-    hasSubscription: subscriptionGate.hasSubscription,
+    isAuthenticated,
+    hasSubscription,
     hasCredits,
     creditBalance,
     canAccess: isAuthenticated && (hasSubscription || hasCredits),
   };
 }
-
-export { useAuthGate, useSubscriptionGate, useCreditsGate };
-export type { UseAuthGateParams, UseAuthGateResult } from "./useAuthGate";
-export type { UseSubscriptionGateParams, UseSubscriptionGateResult } from "./useSubscriptionGate";
-export type { UseCreditsGateParams, UseCreditsGateResult } from "./useCreditsGate";

package/src/revenuecat/domain/types/RevenueCatTypes.ts

@@ -75,3 +75,35 @@ export function getErrorMessage(error: unknown, fallback: string): string {
   }
   return fallback;
 }
+
+/**
+ * Trial Eligibility Types
+ * For RevenueCat introductory offer (free trial) support
+ */
+
+/** Trial info for a subscription product */
+export interface TrialInfo {
+  /** Whether user is eligible for trial */
+  eligible: boolean;
+  /** Trial duration in days */
+  durationDays: number;
+  /** Product identifier */
+  productId: string;
+}
+
+/** Configuration for trial display */
+export interface TrialDisplayConfig {
+  /** Product IDs that have trial offers */
+  trialProductIds: string[];
+  /** Default trial duration in days */
+  defaultTrialDays: number;
+  /** Whether to show trial badge */
+  showTrialBadge: boolean;
+}
+
+/** Default trial configuration */
+export const DEFAULT_TRIAL_CONFIG: TrialDisplayConfig = {
+  trialProductIds: [],
+  defaultTrialDays: 7,
+  showTrialBadge: true,
+};

package/src/revenuecat/index.ts

@@ -10,3 +10,4 @@ export * from "./presentation/hooks/useRevenueCat";
 export * from "./presentation/hooks/useCustomerInfo";
 export * from "./presentation/hooks/usePaywallFlow";
 export * from "./presentation/hooks/useSubscriptionQueries";
+export * from "./presentation/hooks/useRevenueCatTrialEligibility";

package/src/revenuecat/presentation/hooks/useRevenueCatTrialEligibility.ts

@@ -0,0 +1,179 @@
+/**
+ * useRevenueCatTrialEligibility Hook
+ * Checks if user is eligible for introductory offers via RevenueCat
+ * Uses Apple's native mechanism for trial eligibility
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import Purchases, {
+  type IntroEligibility,
+  INTRO_ELIGIBILITY_STATUS,
+} from "react-native-purchases";
+import { getRevenueCatService } from "../../infrastructure/services/RevenueCatService";
+
+declare const __DEV__: boolean;
+
+/** Trial eligibility info for a single product */
+export interface ProductTrialEligibility {
+  /** Product identifier */
+  productId: string;
+  /** Whether eligible for introductory offer (free trial) */
+  eligible: boolean;
+  /** Trial duration in days (if available from product) */
+  trialDurationDays?: number;
+}
+
+/** Map of product ID to eligibility */
+export type TrialEligibilityMap = Record<string, ProductTrialEligibility>;
+
+export interface UseRevenueCatTrialEligibilityResult {
+  /** Map of product IDs to their trial eligibility */
+  eligibilityMap: TrialEligibilityMap;
+  /** Whether eligibility check is in progress */
+  isLoading: boolean;
+  /** Whether any product has an eligible trial */
+  hasEligibleTrial: boolean;
+  /** Check eligibility for specific product IDs */
+  checkEligibility: (productIds: string[]) => Promise<void>;
+  /** Get eligibility for a specific product */
+  getProductEligibility: (productId: string) => ProductTrialEligibility | null;
+}
+
+/** Cache duration in milliseconds (5 minutes) */
+const CACHE_DURATION_MS = 5 * 60 * 1000;
+
+/** Cached eligibility result */
+interface CachedEligibility {
+  data: TrialEligibilityMap;
+  timestamp: number;
+}
+
+let eligibilityCache: CachedEligibility | null = null;
+
+/**
+ * Hook to check trial eligibility via RevenueCat
+ * Uses Apple's introductory offer eligibility system
+ */
+export function useRevenueCatTrialEligibility(): UseRevenueCatTrialEligibilityResult {
+  const [eligibilityMap, setEligibilityMap] = useState<TrialEligibilityMap>({});
+  const [isLoading, setIsLoading] = useState(false);
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  const checkEligibility = useCallback(async (productIds: string[]) => {
+    if (productIds.length === 0) {
+      return;
+    }
+
+    // Check cache validity
+    if (
+      eligibilityCache &&
+      Date.now() - eligibilityCache.timestamp < CACHE_DURATION_MS
+    ) {
+      const allCached = productIds.every(
+        (id) => eligibilityCache?.data[id] !== undefined
+      );
+      if (allCached && isMountedRef.current) {
+        setEligibilityMap(eligibilityCache.data);
+        return;
+      }
+    }
+
+    const service = getRevenueCatService();
+    if (!service || !service.isInitialized()) {
+      if (__DEV__) {
+        console.log("[TrialEligibility] RevenueCat not initialized");
+      }
+      return;
+    }
+
+    setIsLoading(true);
+
+    try {
+      const eligibilities: Record<string, IntroEligibility> =
+        await Purchases.checkTrialOrIntroDiscountEligibility(productIds);
+
+      const newMap: TrialEligibilityMap = {};
+
+      for (const productId of productIds) {
+        const eligibility = eligibilities[productId];
+        const isEligible =
+          eligibility?.status === INTRO_ELIGIBILITY_STATUS.INTRO_ELIGIBILITY_STATUS_ELIGIBLE;
+
+        newMap[productId] = {
+          productId,
+          eligible: isEligible,
+          trialDurationDays: 7, // Default to 7 days as configured in App Store Connect
+        };
+
+        if (__DEV__) {
+          console.log(
+            `[TrialEligibility] ${productId}: ${isEligible ? "ELIGIBLE" : "NOT_ELIGIBLE"}`
+          );
+        }
+      }
+
+      // Update cache
+      eligibilityCache = {
+        data: { ...eligibilityCache?.data, ...newMap },
+        timestamp: Date.now(),
+      };
+
+      if (isMountedRef.current) {
+        setEligibilityMap((prev) => ({ ...prev, ...newMap }));
+      }
+    } catch (error) {
+      if (__DEV__) {
+        console.log("[TrialEligibility] Error checking eligibility:", error);
+      }
+      // On error, default to eligible (better UX)
+      const fallbackMap: TrialEligibilityMap = {};
+      for (const productId of productIds) {
+        fallbackMap[productId] = {
+          productId,
+          eligible: true,
+          trialDurationDays: 7,
+        };
+      }
+      if (isMountedRef.current) {
+        setEligibilityMap((prev) => ({ ...prev, ...fallbackMap }));
+      }
+    } finally {
+      if (isMountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, []);
+
+  const getProductEligibility = useCallback(
+    (productId: string): ProductTrialEligibility | null => {
+      return eligibilityMap[productId] ?? null;
+    },
+    [eligibilityMap]
+  );
+
+  const hasEligibleTrial = Object.values(eligibilityMap).some(
+    (e) => e.eligible
+  );
+
+  return {
+    eligibilityMap,
+    isLoading,
+    hasEligibleTrial,
+    checkEligibility,
+    getProductEligibility,
+  };
+}
+
+/**
+ * Clear eligibility cache (useful for testing)
+ */
+export function clearTrialEligibilityCache(): void {
+  eligibilityCache = null;
+}

package/src/presentation/hooks/useAuthAwarePurchase.md

@@ -1,92 +0,0 @@
-# useAuthAwarePurchase Hook
-
-Security-focused purchase hook that requires authentication before any transaction.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useAuthAwarePurchase.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Auth-Gated Purchase Flow
-
-1. **Auth Provider Validation**: Verify auth provider is configured at app startup
-2. **Authentication Check**: Block purchases for unauthenticated users
-3. **Auth Flow Trigger**: Show auth modal when guest attempts purchase
-4. **Purchase Blocking**: Prevent all transactions without valid authentication
-5. **Post-Auth Purchase**: Allow purchase after user completes authentication
-6. **Security Enforcement**: Server-side validation required for final verification
-
-### Integration Points
-
-- **Auth Provider Configuration**: Must be configured once at app initialization
-- **Auth Context**: User authentication state
-- **Paywall Domain**: For subscription upgrade flow
-- **Auth UI**: For sign-in/sign-up flows
-- **RevenueCat**: For purchase transactions
-
-## Restrictions
-
-### REQUIRED
-
-- **Auth Provider Configuration**: MUST call `configureAuthProvider()` once at app startup
-- **isAuthenticated Function**: MUST provide function to check auth status
-- **showAuthModal Function**: MUST provide function to show auth UI
-- **Error Handling**: MUST handle purchase failures appropriately
-
-### PROHIBITED
-
-- **NEVER** use without configuring auth provider first
-- **NEVER** bypass auth checks for convenience
-- **NEVER** allow anonymous/guest purchases
-- **DO NOT** call handlePurchase/handleRestore without auth provider setup
-
-### CRITICAL SAFETY
-
-- **ALWAYS** configure auth provider at app initialization
-- **NEVER** allow purchases for anonymous users
-- **MUST** implement proper auth flow with pending purchase preservation
-- **ALWAYS** verify auth status in production
-
-## AI Agent Guidelines
-
-### When Implementing Auth-Gated Purchases
-
-1. **Always** configure auth provider at app startup
-2. **Always** implement isAuthenticated function
-3. **Always** implement showAuthModal function
-4. **Never** bypass auth checks
-5. **Always** test purchase flow with authenticated and unauthenticated users
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Call `configureAuthProvider()` once at app startup
-- [ ] Provide `isAuthenticated()` function
-- [ ] Provide `showAuthModal()` function
-- [ ] Test purchase flow with authenticated user
-- [ ] Test purchase flow with unauthenticated user
-- [ ] Verify auth modal appears for guests
-- [ ] Verify purchase proceeds after authentication
-- [ ] Check development logs for auth verification
-- [ ] Verify purchases are blocked without auth provider
-
-### Common Patterns
-
-1. **App-Level Config**: Configure once in root App component
-2. **Pending Purchase**: Store package for post-auth completion
-3. **Auth Integration**: Use with Firebase, Auth0, or custom auth
-4. **Error Handling**: Handle auth failures and purchase failures
-5. **Development Testing**: Use dev logs to verify auth checks
-
-## Related Documentation
-
-- **usePremium**: For purchase and restore operations
-- **usePaywallOperations**: For complete paywall purchase handling
-- **useAuthGate**: For authentication gating
-- **useAuthSubscriptionSync**: For syncing auth with subscription
-- **Security Best Practices**: `src/docs/SECURITY.md`