@umituz/react-native-subscription 2.27.28 → 2.27.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.27.28",
+  "version": "2.27.30",
   "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/domain/entities/Credits.ts

@@ -101,4 +101,6 @@ export interface DeductCreditsResult {
 export const DEFAULT_CREDITS_CONFIG: CreditsConfig = {
   collectionName: "user_credits",
   creditLimit: 100,
+  enableFreeCredits: false,
+  freeCredits: 0,
 };

package/src/index.ts

@@ -87,6 +87,8 @@ export type {
   DeductCreditsResult,
   PurchaseSource,
   PurchaseType,
+  CreditAllocation,
+  PackageAllocationMap,
 } from "./domain/entities/Credits";
 export { DEFAULT_CREDITS_CONFIG } from "./domain/entities/Credits";
 export { InsufficientCreditsError } from "./domain/errors/InsufficientCreditsError";

package/src/infrastructure/repositories/CreditsRepository.ts

@@ -136,6 +136,7 @@ export class CreditsRepository extends BaseRepository {
   /**
    * Initialize free credits for new users
    * Creates a credits document with freeCredits amount (no subscription)
+   * Uses transaction to prevent race condition with premium init
    */
   async initializeFreeCredits(userId: string): Promise<CreditsResult> {
     const db = getFirestore();
@@ -148,52 +149,57 @@ export class CreditsRepository extends BaseRepository {
 
     try {
       const ref = this.getRef(db, userId);
-      const snap = await getDoc(ref);
-
-      // Don't overwrite if document already exists
-      if (snap.exists()) {
-        if (__DEV__) console.log("[CreditsRepository] Credits document already exists, skipping free credits init");
-        const existing = snap.data() as UserCreditsDocumentRead;
-        return { success: true, data: CreditsMapper.toEntity(existing) };
-      }
-
-      // Create new document with free credits
-      const { setDoc } = await import("firebase/firestore");
-      const now = serverTimestamp();
 
-      const creditsData = {
-        // Not premium - just free credits
-        isPremium: false,
-        status: "free" as const,
-
-        // Free credits - store initial amount for tracking
-        credits: freeCredits,
-        creditLimit: freeCredits,
-        initialFreeCredits: freeCredits,
-        isFreeCredits: true,
-
-        // Dates
-        createdAt: now,
-        lastUpdatedAt: now,
-      };
+      // Use transaction to atomically check-and-set
+      const result = await runTransaction(db, async (tx: Transaction) => {
+        const snap = await tx.get(ref);
 
-      await setDoc(ref, creditsData);
+        // Don't overwrite if document already exists (premium or previous init)
+        if (snap.exists()) {
+          if (__DEV__) console.log("[CreditsRepository] Credits document already exists, skipping free credits init");
+          const existing = snap.data() as UserCreditsDocumentRead;
+          return { skipped: true, data: CreditsMapper.toEntity(existing) };
+        }
 
-      if (__DEV__) console.log("[CreditsRepository] Initialized free credits:", { userId: userId.slice(0, 8), credits: freeCredits });
+        // Create new document with free credits
+        const now = serverTimestamp();
 
-      return {
-        success: true,
-        data: {
+        const creditsData = {
+          // Not premium - just free credits
           isPremium: false,
-          status: "free",
+          status: "free" as const,
+
+          // Free credits - store initial amount for tracking
           credits: freeCredits,
           creditLimit: freeCredits,
-          purchasedAt: null,
-          expirationDate: null,
-          lastUpdatedAt: null,
-          willRenew: false,
-        }
-      };
+          initialFreeCredits: freeCredits,
+          isFreeCredits: true,
+
+          // Dates
+          createdAt: now,
+          lastUpdatedAt: now,
+        };
+
+        tx.set(ref, creditsData);
+
+        if (__DEV__) console.log("[CreditsRepository] Initialized free credits:", { userId: userId.slice(0, 8), credits: freeCredits });
+
+        return {
+          skipped: false,
+          data: {
+            isPremium: false,
+            status: "free" as const,
+            credits: freeCredits,
+            creditLimit: freeCredits,
+            purchasedAt: null,
+            expirationDate: null,
+            lastUpdatedAt: null,
+            willRenew: false,
+          }
+        };
+      });
+
+      return { success: true, data: result.data };
     } catch (e: any) {
       if (__DEV__) console.error("[CreditsRepository] Free credits init error:", e.message);
       return { success: false, error: { message: e.message, code: "INIT_ERR" } };

package/src/infrastructure/services/CreditsInitializer.ts

@@ -29,6 +29,7 @@ import { getCreditAllocation } from "../../utils/creditMapper";
 
 interface InitializationResult {
     credits: number;
+    alreadyProcessed?: boolean;
 }
 
 export interface InitializeCreditsMetadata {
@@ -58,7 +59,7 @@ export async function initializeCreditsTransaction(
         let processedPurchases: string[] = existingData?.processedPurchases || [];
 
         if (existingData && purchaseId && processedPurchases.includes(purchaseId)) {
-            return { credits: existingData.credits, alreadyProcessed: true } as InitializationResult & { alreadyProcessed: boolean };
+            return { credits: existingData.credits, alreadyProcessed: true };
         }
 
         if (existingData?.purchasedAt) {

package/src/infrastructure/services/SubscriptionInitializer.ts

@@ -2,6 +2,8 @@
  * Subscription Initializer
  */
 
+declare const __DEV__: boolean;
+
 import { Platform } from "react-native";
 import type { CustomerInfo } from "react-native-purchases";
 import type { CreditsConfig } from "../../domain/entities/Credits";
@@ -126,11 +128,36 @@ export const initializeSubscription = async (config: SubscriptionInitConfig): Pr
         return;
       }
 
-      // If premium became false (subscription expired/canceled), sync expired status only
+      // If premium became false, check if actually expired or just canceled
       if (!isPremium && productId) {
-        await getCreditsRepository().syncExpiredStatus(userId);
-        if (__DEV__) {
-          console.log('[SubscriptionInitializer] Subscription expired, synced status');
+        // Check if subscription is truly expired (expiration date in the past)
+        const isActuallyExpired = !expiresAt || new Date(expiresAt) < new Date();
+
+        if (isActuallyExpired) {
+          // Subscription truly expired - zero out credits
+          await getCreditsRepository().syncExpiredStatus(userId);
+          if (__DEV__) {
+            console.log('[SubscriptionInitializer] Subscription expired, synced status');
+          }
+        } else {
+          // Subscription canceled but not expired - preserve credits until expiration
+          if (__DEV__) {
+            console.log('[SubscriptionInitializer] Subscription canceled but not expired, preserving credits until:', expiresAt);
+          }
+          // Update willRenew to false but keep credits
+          const revenueCatData: RevenueCatData = {
+            expirationDate: expiresAt,
+            willRenew: false, // Canceled
+            isPremium: true, // Still has access until expiration
+            periodType,
+          };
+          await getCreditsRepository().initializeCredits(
+            userId,
+            `status_sync_canceled_${Date.now()}`,
+            productId,
+            "settings" as any,
+            revenueCatData
+          );
         }
         onCreditsUpdated?.(userId);
         return;

package/src/infrastructure/services/TrialService.ts

@@ -28,6 +28,7 @@ export const TRIAL_CONFIG = {
 export interface DeviceTrialRecord {
   deviceId: string;
   hasUsedTrial: boolean;
+  trialInProgress?: boolean;
   trialStartedAt?: Date;
   trialEndedAt?: Date;
   trialConvertedAt?: Date;
@@ -80,15 +81,19 @@ export async function checkTrialEligibility(
 
     const data = trialDoc.data();
     const hasUsedTrial = data?.hasUsedTrial === true;
+    const trialInProgress = data?.trialInProgress === true;
 
     if (__DEV__) {
       console.log("[TrialService] Trial record found:", {
         deviceId: effectiveDeviceId.slice(0, 8),
         hasUsedTrial,
+        trialInProgress,
       });
     }
 
-    if (hasUsedTrial) {
+    // Not eligible if trial was already used (converted or ended)
+    // OR if trial is currently in progress
+    if (hasUsedTrial || trialInProgress) {
       return {
         eligible: false,
         reason: "already_used",
@@ -129,7 +134,9 @@ export async function recordTrialStart(
       trialRef,
       {
         deviceId: effectiveDeviceId,
-        hasUsedTrial: true,
+        // Don't set hasUsedTrial here - only set when trial ends or converts
+        // This allows retry if user cancels before trial period ends
+        trialInProgress: true,
         trialStartedAt: serverTimestamp(),
         lastUserId: userId,
         userIds: arrayUnion(userId),
@@ -183,6 +190,9 @@ export async function recordTrialEnd(
     await setDoc(
       trialRef,
       {
+        // Mark trial as used when it ends (prevents retry)
+        hasUsedTrial: true,
+        trialInProgress: false,
         trialEndedAt: serverTimestamp(),
         updatedAt: serverTimestamp(),
       },
@@ -190,7 +200,7 @@ export async function recordTrialEnd(
     );
 
     if (__DEV__) {
-      console.log("[TrialService] Trial end recorded");
+      console.log("[TrialService] Trial end recorded - trial now consumed");
     }
 
     return true;
@@ -221,6 +231,9 @@ export async function recordTrialConversion(
     await setDoc(
       trialRef,
       {
+        // Mark trial as used after conversion (prevents retry)
+        hasUsedTrial: true,
+        trialInProgress: false,
         trialConvertedAt: serverTimestamp(),
         updatedAt: serverTimestamp(),
       },
@@ -228,7 +241,7 @@ export async function recordTrialConversion(
     );
 
     if (__DEV__) {
-      console.log("[TrialService] Trial conversion recorded");
+      console.log("[TrialService] Trial conversion recorded - user converted to paid");
     }
 
     return true;

package/src/presentation/hooks/useAuthAwarePurchase.ts

@@ -16,23 +16,40 @@ export interface PurchaseAuthProvider {
 }
 
 let globalAuthProvider: PurchaseAuthProvider | null = null;
-let savedPackage: PurchasesPackage | null = null;
-let savedSource: PurchaseSource | null = null;
+
+interface SavedPurchaseState {
+  pkg: PurchasesPackage;
+  source: PurchaseSource;
+  timestamp: number;
+}
+
+const SAVED_PURCHASE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+let savedPurchaseState: SavedPurchaseState | null = null;
 
 export const configureAuthProvider = (provider: PurchaseAuthProvider): void => {
   globalAuthProvider = provider;
 };
 
+const savePurchase = (pkg: PurchasesPackage, source: PurchaseSource): void => {
+  savedPurchaseState = { pkg, source, timestamp: Date.now() };
+};
+
 export const getSavedPurchase = (): { pkg: PurchasesPackage; source: PurchaseSource } | null => {
-  if (savedPackage && savedSource) {
-    return { pkg: savedPackage, source: savedSource };
+  if (!savedPurchaseState) {
+    return null;
+  }
+
+  const isExpired = Date.now() - savedPurchaseState.timestamp > SAVED_PURCHASE_EXPIRY_MS;
+  if (isExpired) {
+    savedPurchaseState = null;
+    return null;
   }
-  return null;
+
+  return { pkg: savedPurchaseState.pkg, source: savedPurchaseState.source };
 };
 
 export const clearSavedPurchase = (): void => {
-  savedPackage = null;
-  savedSource = null;
+  savedPurchaseState = null;
 };
 
 export interface UseAuthAwarePurchaseParams {
@@ -69,8 +86,7 @@ export const useAuthAwarePurchase = (
       const isAuth = globalAuthProvider.isAuthenticated();
 
       if (!isAuth) {
-        savedPackage = pkg;
-        savedSource = source || params?.source || "settings";
+        savePurchase(pkg, source || params?.source || "settings");
         globalAuthProvider.showAuthModal();
         return false;
       }
@@ -103,8 +119,20 @@ export const useAuthAwarePurchase = (
       console.log("[useAuthAwarePurchase] Executing saved purchase:", saved.pkg.product.identifier);
     }
 
-    clearSavedPurchase();
-    return purchasePackage(saved.pkg);
+    try {
+      const result = await purchasePackage(saved.pkg);
+      // Only clear after successful purchase
+      if (result) {
+        clearSavedPurchase();
+      }
+      return result;
+    } catch (error) {
+      // Don't clear on error - allow retry
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        console.error("[useAuthAwarePurchase] Saved purchase failed:", error);
+      }
+      throw error;
+    }
   }, [purchasePackage]);
 
   return {

package/src/presentation/hooks/useCredits.ts

@@ -75,20 +75,30 @@ export const useCredits = (): UseCreditsResult => {
         throw new Error(result.error?.message || "Failed to fetch credits");
       }
 
+      // If subscription is expired, immediately return 0 credits
+      // to prevent any window where expired user could deduct
       if (result.data?.status === "expired") {
+        // Sync to Firestore in background
         repository.syncExpiredStatus(userId).catch((syncError) => {
           if (typeof __DEV__ !== "undefined" && __DEV__) {
             console.warn("[useCredits] Background sync failed:", syncError);
           }
         });
+
+        // Return expired data with 0 credits immediately
+        return {
+          ...result.data,
+          credits: 0,
+          isPremium: false,
+        };
       }
 
       return result.data || null;
     },
     enabled: queryEnabled,
-    staleTime: 0,
-    gcTime: 0,
-    refetchOnMount: true,
+    staleTime: 30 * 1000, // 30 seconds - data considered fresh
+    gcTime: 5 * 60 * 1000, // 5 minutes - keep in cache after unmount
+    refetchOnMount: "always",
     refetchOnWindowFocus: true,
     refetchOnReconnect: true,
   });

package/src/presentation/hooks/useDeductCredit.ts

@@ -39,26 +39,37 @@ export const useDeductCredit = ({
       return repository.deductCredit(userId, cost);
     },
     onMutate: async (cost: number) => {
-      if (!userId) return;
+      if (!userId) return { previousCredits: null, skippedOptimistic: true };
+
       await queryClient.cancelQueries({ queryKey: creditsQueryKeys.user(userId) });
       const previousCredits = queryClient.getQueryData<UserCredits>(creditsQueryKeys.user(userId));
+
+      // Skip optimistic update if insufficient credits to prevent showing 0
+      if (!previousCredits || previousCredits.credits < cost) {
+        return { previousCredits, skippedOptimistic: true };
+      }
+
       queryClient.setQueryData<UserCredits | null>(creditsQueryKeys.user(userId), (old) => {
         if (!old) return old;
-        return { 
-          ...old, 
-          credits: Math.max(0, old.credits - cost), 
-          lastUpdatedAt: timezoneService.getNow() 
+        return {
+          ...old,
+          credits: old.credits - cost,
+          lastUpdatedAt: timezoneService.getNow()
         };
       });
-      return { previousCredits };
+      return { previousCredits, skippedOptimistic: false };
     },
     onError: (_err, _cost, context) => {
-      if (userId && context?.previousCredits) {
+      // Always restore previous credits on error if we have them
+      if (userId && context?.previousCredits && !context.skippedOptimistic) {
         queryClient.setQueryData(creditsQueryKeys.user(userId), context.previousCredits);
       }
     },
-    onSettled: () => {
-      if (userId) queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
+    onSuccess: () => {
+      // Only invalidate on success to get fresh server data
+      if (userId) {
+        queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
+      }
     },
   });
 

package/src/presentation/hooks/useFreeCreditsInit.ts

@@ -63,6 +63,13 @@ async function initializeFreeCreditsForUser(
 
   const promise = (async () => {
     try {
+      if (!isCreditsRepositoryConfigured()) {
+        if (typeof __DEV__ !== "undefined" && __DEV__) {
+          console.warn("[useFreeCreditsInit] Credits repository not configured");
+        }
+        return false;
+      }
+
       const repository = getCreditsRepository();
       const result = await repository.initializeFreeCredits(userId);
 
@@ -78,6 +85,11 @@ async function initializeFreeCreditsForUser(
         }
         return false;
       }
+    } catch (error) {
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        console.error("[useFreeCreditsInit] Unexpected error:", error);
+      }
+      return false;
     } finally {
       freeCreditsInitInProgress.delete(userId);
       initPromises.delete(userId);
@@ -142,7 +154,11 @@ export function useFreeCreditsInit(params: UseFreeCreditsInitParams): UseFreeCre
     if (needsInit) {
       // Double-check inside effect to handle race conditions
       if (!freeCreditsInitAttempted.has(userId)) {
-        initializeFreeCreditsForUser(userId, stableOnComplete);
+        initializeFreeCreditsForUser(userId, stableOnComplete).catch((error) => {
+          if (typeof __DEV__ !== "undefined" && __DEV__) {
+            console.error("[useFreeCreditsInit] Init failed:", error);
+          }
+        });
       }
     } else if (querySuccess && isAnonymous && !hasCredits && isFreeCreditsEnabled) {
       if (typeof __DEV__ !== "undefined" && __DEV__) {

package/src/presentation/hooks/useSubscriptionStatus.ts

@@ -37,9 +37,9 @@ export const useSubscriptionStatus = (): SubscriptionStatusResult => {
       return SubscriptionManager.checkPremiumStatus();
     },
     enabled: !!userId && SubscriptionManager.isInitializedForUser(userId),
-    staleTime: 0,
-    gcTime: 0,
-    refetchOnMount: true,
+    staleTime: 30 * 1000, // 30 seconds
+    gcTime: 5 * 60 * 1000, // 5 minutes
+    refetchOnMount: "always",
     refetchOnWindowFocus: true,
     refetchOnReconnect: true,
   });

package/src/revenuecat/domain/value-objects/RevenueCatConfig.ts

@@ -44,6 +44,14 @@ export interface RevenueCatConfig {
     newExpirationDate: string,
     customerInfo: CustomerInfo
   ) => Promise<void> | void;
+  /** Callback when subscription plan changes (upgrade/downgrade) */
+  onPlanChanged?: (
+    userId: string,
+    newProductId: string,
+    previousProductId: string,
+    isUpgrade: boolean,
+    customerInfo: CustomerInfo
+  ) => Promise<void> | void;
   /** Callback after credits are successfully updated (for cache invalidation) */
   onCreditsUpdated?: (userId: string) => void;
 }

package/src/revenuecat/infrastructure/handlers/PackageHandler.ts

@@ -7,6 +7,8 @@ import type { PurchasesPackage, CustomerInfo } from "react-native-purchases";
 import type { IRevenueCatService } from "../../application/ports/IRevenueCatService";
 import { getPremiumEntitlement } from "../../domain/types/RevenueCatTypes";
 
+declare const __DEV__: boolean;
+
 export interface PremiumStatus {
   isPremium: boolean;
   expirationDate: Date | null;

package/src/revenuecat/infrastructure/services/CustomerInfoListenerManager.ts

@@ -26,6 +26,13 @@ export class CustomerInfoListenerManager {
     };
 
     setUserId(userId: string): void {
+        // Reset renewal state when user changes to prevent state leak between users
+        if (this.currentUserId && this.currentUserId !== userId) {
+            this.renewalState = {
+                previousExpirationDate: null,
+                previousProductId: null,
+            };
+        }
         this.currentUserId = userId;
     }
 
@@ -51,6 +58,7 @@ export class CustomerInfoListenerManager {
                 config.entitlementIdentifier
             );
 
+            // Handle renewal (same product, extended expiration)
             if (renewalResult.isRenewal && config.onRenewalDetected) {
                 if (__DEV__) {
                     console.log("[CustomerInfoListener] Renewal detected:", {
@@ -74,9 +82,46 @@ export class CustomerInfoListenerManager {
                 }
             }
 
+            // Handle plan change (upgrade/downgrade)
+            if (renewalResult.isPlanChange && config.onPlanChanged) {
+                if (__DEV__) {
+                    console.log("[CustomerInfoListener] Plan change detected:", {
+                        userId: this.currentUserId,
+                        previousProductId: renewalResult.previousProductId,
+                        newProductId: renewalResult.productId,
+                        isUpgrade: renewalResult.isUpgrade,
+                        isDowngrade: renewalResult.isDowngrade,
+                    });
+                }
+
+                try {
+                    await config.onPlanChanged(
+                        this.currentUserId,
+                        renewalResult.productId!,
+                        renewalResult.previousProductId!,
+                        renewalResult.isUpgrade,
+                        customerInfo
+                    );
+                } catch (error) {
+                    if (__DEV__) {
+                        console.error("[CustomerInfoListener] Plan change callback failed:", error);
+                    }
+                }
+            }
+
             this.renewalState = updateRenewalState(this.renewalState, renewalResult);
 
-            syncPremiumStatus(config, this.currentUserId, customerInfo);
+            // Only sync premium status if NOT a renewal or plan change
+            // This prevents double credit initialization
+            if (!renewalResult.isRenewal && !renewalResult.isPlanChange) {
+                try {
+                    await syncPremiumStatus(config, this.currentUserId, customerInfo);
+                } catch (error) {
+                    if (__DEV__) {
+                        console.error("[CustomerInfoListener] syncPremiumStatus failed:", error);
+                    }
+                }
+            }
         };
 
         Purchases.addCustomerInfoUpdateListener(this.listener);

package/src/revenuecat/infrastructure/utils/PremiumStatusSyncer.ts

@@ -7,6 +7,8 @@ import type { CustomerInfo } from "react-native-purchases";
 import type { RevenueCatConfig } from "../../domain/value-objects/RevenueCatConfig";
 import { getPremiumEntitlement } from "../../domain/types/RevenueCatTypes";
 
+declare const __DEV__: boolean;
+
 export async function syncPremiumStatus(
     config: RevenueCatConfig,
     userId: string,
@@ -34,13 +36,13 @@ export async function syncPremiumStatus(
         } else {
             await config.onPremiumStatusChanged(userId, false, undefined, undefined, undefined, undefined);
         }
-    } catch {
-        // Silent error handling
+    } catch (error) {
+        if (__DEV__) {
+            console.error('[PremiumStatusSyncer] syncPremiumStatus failed:', error);
+        }
     }
 }
 
-declare const __DEV__: boolean;
-
 export async function notifyPurchaseCompleted(
     config: RevenueCatConfig,
     userId: string,
@@ -88,7 +90,9 @@ export async function notifyRestoreCompleted(
 
     try {
         await config.onRestoreCompleted(userId, isPremium, customerInfo);
-    } catch {
-        // Silent error handling
+    } catch (error) {
+        if (__DEV__) {
+            console.error('[PremiumStatusSyncer] notifyRestoreCompleted failed:', error);
+        }
     }
 }

package/src/revenuecat/infrastructure/utils/RenewalDetector.ts

@@ -5,6 +5,7 @@
  */
 
 import type { CustomerInfo } from "react-native-purchases";
+import { detectPackageType, type SubscriptionPackageType } from "../../../utils/packageTypeDetector";
 
 export interface RenewalState {
   previousExpirationDate: string | null;
@@ -13,17 +14,35 @@ export interface RenewalState {
 
 export interface RenewalDetectionResult {
   isRenewal: boolean;
+  isPlanChange: boolean;
+  isUpgrade: boolean;
+  isDowngrade: boolean;
   productId: string | null;
+  previousProductId: string | null;
   newExpirationDate: string | null;
 }
 
+const PACKAGE_TIER_ORDER: Record<SubscriptionPackageType, number> = {
+  weekly: 1,
+  monthly: 2,
+  yearly: 3,
+  unknown: 0,
+};
+
+function getPackageTier(productId: string | null): number {
+  if (!productId) return 0;
+  const packageType = detectPackageType(productId);
+  return PACKAGE_TIER_ORDER[packageType] ?? 0;
+}
+
 /**
- * Detects if a subscription renewal occurred
+ * Detects if a subscription renewal or plan change occurred
  *
  * Best Practice (RevenueCat):
  * - Track previous expiration date
  * - If new expiration > previous → Renewal detected
- * - Reset credits on renewal (industry standard)
+ * - If productId changed → Plan change (upgrade/downgrade)
+ * - Reset credits on renewal or plan change (industry standard)
  *
  * @param state Previous state (expiration date, product ID)
  * @param customerInfo Current CustomerInfo from RevenueCat
@@ -37,34 +56,65 @@ export function detectRenewal(
 ): RenewalDetectionResult {
   const entitlement = customerInfo.entitlements.active[entitlementId];
 
+  const baseResult: RenewalDetectionResult = {
+    isRenewal: false,
+    isPlanChange: false,
+    isUpgrade: false,
+    isDowngrade: false,
+    productId: null,
+    previousProductId: state.previousProductId,
+    newExpirationDate: null,
+  };
+
   if (!entitlement) {
-    return {
-      isRenewal: false,
-      productId: null,
-      newExpirationDate: null,
-    };
+    return baseResult;
   }
 
   const newExpirationDate = entitlement.expirationDate;
   const productId = entitlement.productIdentifier;
 
-  if (!newExpirationDate || !state.previousExpirationDate) {
+  // First time seeing this subscription - not a renewal
+  if (!state.previousExpirationDate || !state.previousProductId) {
     return {
-      isRenewal: false,
+      ...baseResult,
       productId,
       newExpirationDate,
     };
   }
 
-  const newExpiration = new Date(newExpirationDate);
+  const newExpiration = new Date(newExpirationDate ?? 0);
   const previousExpiration = new Date(state.previousExpirationDate);
+  const productChanged = productId !== state.previousProductId;
+  const expirationExtended = newExpiration > previousExpiration;
+
+  // Plan change detection (upgrade/downgrade)
+  if (productChanged) {
+    const oldTier = getPackageTier(state.previousProductId);
+    const newTier = getPackageTier(productId);
+    const isUpgrade = newTier > oldTier;
+    const isDowngrade = newTier < oldTier;
+
+    return {
+      isRenewal: false,
+      isPlanChange: true,
+      isUpgrade,
+      isDowngrade,
+      productId,
+      previousProductId: state.previousProductId,
+      newExpirationDate,
+    };
+  }
 
-  const isRenewal = newExpiration > previousExpiration &&
-                    productId === state.previousProductId;
+  // Same product renewal
+  const isRenewal = expirationExtended;
 
   return {
     isRenewal,
+    isPlanChange: false,
+    isUpgrade: false,
+    isDowngrade: false,
     productId,
+    previousProductId: state.previousProductId,
     newExpirationDate,
   };
 }