@umituz/react-native-subscription 2.43.1 → 2.43.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.43.1",
+  "version": "2.43.3",
   "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/PaywallScreen.tsx

@@ -2,7 +2,6 @@
  * Paywall Screen Component
  *
  * Full-screen paywall with optimized FlatList for performance and modern design.
- * This is a "dumb" component that receives all data and actions via props.
  */
 
 import React, { useCallback, useEffect, useMemo } from "react";

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

@@ -22,9 +22,6 @@ export interface PaywallOrchestratorOptions {
  * High-level orchestrator for Paywall navigation.
  * Handles automatic triggers (post-onboarding) and manual triggers (showPaywall state).
  * Centralizes handlers for success, close, and feedback triggers.
- *
- * This orchestrator fetches all subscription data and passes it to PaywallScreen as props.
- * PaywallScreen is now a "dumb" component that doesn't call usePremium internally.
  */
 export function usePaywallOrchestrator({
   navigation,
@@ -86,7 +83,6 @@ export function usePaywallOrchestrator({
         packagesCount: packages.length
       });
 
-      // Pass all data and actions as props - PaywallScreen is now a dumb component
       navigation.navigate("PaywallScreen", {
         // UI Props
         translations,

package/src/domains/subscription/application/SubscriptionSyncProcessor.ts

@@ -1,9 +1,9 @@
 import { PURCHASE_SOURCE, PURCHASE_TYPE } from "../core/SubscriptionConstants";
-import type { PremiumStatusChangedEvent, PurchaseCompletedEvent, RenewalDetectedEvent } from "../core/SubscriptionEvents";
+import { subscriptionEventBus, SUBSCRIPTION_EVENTS } from "../../../shared/infrastructure/SubscriptionEventBus";
+import type { PurchaseCompletedEvent, RenewalDetectedEvent, PremiumStatusChangedEvent } from "../core/SubscriptionEvents";
 import { getCreditsRepository } from "../../credits/infrastructure/CreditsRepositoryManager";
 import { extractRevenueCatData } from "./SubscriptionSyncUtils";
 import { generatePurchaseId, generateRenewalId } from "./syncIdGenerators";
-import { subscriptionEventBus, SUBSCRIPTION_EVENTS } from "../../../shared/infrastructure/SubscriptionEventBus";
 
 /**
  * Central processor for all subscription sync operations.

package/src/domains/subscription/core/events/FlowEvents.ts

@@ -0,0 +1,24 @@
+/**
+ * Application flow events
+ * Events emitted during high-level application flow transitions
+ */
+
+export const FLOW_EVENTS = {
+  ONBOARDING_COMPLETED: "flow_onboarding_completed",
+  PAYWALL_SHOWN: "flow_paywall_shown",
+  PAYWALL_CLOSED: "flow_paywall_closed",
+} as const;
+
+export type FlowEventType = typeof FLOW_EVENTS[keyof typeof FLOW_EVENTS];
+
+export interface OnboardingCompletedEvent {
+  timestamp: number;
+}
+
+export interface PaywallShownEvent {
+  timestamp: number;
+}
+
+export interface PaywallClosedEvent {
+  timestamp: number;
+}

package/src/domains/subscription/core/events/SubscriptionEvents.ts

@@ -0,0 +1,22 @@
+/**
+ * Subscription-related events
+ * Events emitted during subscription lifecycle operations
+ */
+
+export const SUBSCRIPTION_EVENTS = {
+  CREDITS_UPDATED: "credits_updated",
+  PURCHASE_COMPLETED: "purchase_completed",
+  RENEWAL_DETECTED: "renewal_detected",
+  PREMIUM_STATUS_CHANGED: "premium_status_changed",
+  SYNC_STATUS_CHANGED: "sync_status_changed",
+} as const;
+
+export type SubscriptionEventType = typeof SUBSCRIPTION_EVENTS[keyof typeof SUBSCRIPTION_EVENTS];
+
+export interface SyncStatusChangedEvent {
+  status: 'syncing' | 'success' | 'error';
+  phase: 'purchase' | 'renewal';
+  userId?: string;
+  productId?: string;
+  error?: string;
+}

package/src/domains/subscription/infrastructure/hooks/usePurchasePackage.ts

@@ -6,10 +6,8 @@ import {
   selectUserId,
 } from "@umituz/react-native-auth";
 import { SubscriptionManager } from "../../infrastructure/managers/SubscriptionManager";
-import { SUBSCRIPTION_QUERY_KEYS } from "./subscriptionQueryKeys";
-import { subscriptionStatusQueryKeys } from "../../presentation/useSubscriptionStatus";
-import { creditsQueryKeys } from "../../../credits/presentation/creditsQueryKeys";
 import { getErrorMessage } from "../../../revenuecat/core/errors/RevenueCatErrorHandler";
+import { invalidateSubscriptionCaches } from "../../../../shared/infrastructure/react-query/utils";
 
 interface PurchaseMutationResult {
   success: boolean;
@@ -39,17 +37,7 @@ export const usePurchasePackage = () => {
     onSuccess: (result) => {
       if (result.success) {
         showSuccess("Purchase Successful", "Your subscription is now active!");
-        queryClient.invalidateQueries({
-          queryKey: SUBSCRIPTION_QUERY_KEYS.packages,
-        });
-        if (userId) {
-          queryClient.invalidateQueries({
-            queryKey: subscriptionStatusQueryKeys.user(userId),
-          });
-          queryClient.invalidateQueries({
-            queryKey: creditsQueryKeys.user(userId),
-          });
-        }
+        invalidateSubscriptionCaches(queryClient, userId);
       } else {
         showError("Purchase Failed", "Unable to complete purchase. Please try again.");
       }

package/src/domains/subscription/infrastructure/hooks/useRestorePurchase.ts

@@ -5,10 +5,8 @@ import {
   selectUserId,
 } from "@umituz/react-native-auth";
 import { SubscriptionManager } from "../../infrastructure/managers/SubscriptionManager";
-import { SUBSCRIPTION_QUERY_KEYS } from "./subscriptionQueryKeys";
-import { subscriptionStatusQueryKeys } from "../../presentation/useSubscriptionStatus";
-import { creditsQueryKeys } from "../../../credits/presentation/creditsQueryKeys";
 import { getErrorMessage } from "../../../revenuecat/core/errors/RevenueCatErrorHandler";
+import { invalidateSubscriptionCaches } from "../../../../shared/infrastructure/react-query/utils";
 
 interface RestoreResult {
   success: boolean;
@@ -31,17 +29,7 @@ export const useRestorePurchase = () => {
     },
     onSuccess: (result) => {
       if (result.success) {
-        queryClient.invalidateQueries({
-          queryKey: SUBSCRIPTION_QUERY_KEYS.packages,
-        });
-        if (userId) {
-          queryClient.invalidateQueries({
-            queryKey: subscriptionStatusQueryKeys.user(userId),
-          });
-          queryClient.invalidateQueries({
-            queryKey: creditsQueryKeys.user(userId),
-          });
-        }
+        invalidateSubscriptionCaches(queryClient, userId);
 
         if (result.productId) {
           showSuccess("Restore Successful", "Your subscription has been restored!");

package/src/domains/subscription/presentation/featureGateActions.ts

@@ -1,50 +1,53 @@
-import type { MutableRefObject } from "react";
+import type { FeatureGateState } from "./hooks/useFeatureGateState";
 
-export const executeFeatureAction = (
+/**
+ * Executes a feature action with proper auth, subscription, and credit checks.
+ * Queues the action if waiting for auth completion or purchase flow.
+ *
+ * @param action - The action to execute when conditions are met
+ * @param isAuthenticated - Whether user is authenticated
+ * @param onShowAuthModal - Callback to show auth modal
+ * @param state - Feature gate state containing all refs and flags
+ * @returns true if action was executed immediately, false if queued/pending
+ */
+export function executeFeatureAction(
   action: () => void | Promise<void>,
   isAuthenticated: boolean,
   onShowAuthModal: (callback: () => void | Promise<void>) => void,
-  hasSubscriptionRef: MutableRefObject<boolean>,
-  creditBalanceRef: MutableRefObject<number>,
-  requiredCreditsRef: MutableRefObject<number>,
-  onShowPaywallRef: MutableRefObject<(requiredCredits?: number) => void>,
-  pendingActionRef: MutableRefObject<(() => void | Promise<void>) | null>,
-  isWaitingForAuthCreditsRef: MutableRefObject<boolean>,
-  isWaitingForPurchaseRef: MutableRefObject<boolean>,
-  isCreditsLoadedRef: MutableRefObject<boolean>
-): boolean => {
+  state: FeatureGateState
+): boolean {
 
   if (!isAuthenticated) {
     const postAuthAction = () => {
-      if (hasSubscriptionRef.current || creditBalanceRef.current >= requiredCreditsRef.current) {
+      if (state.hasSubscriptionRef.current || state.creditBalanceRef.current >= state.requiredCreditsRef.current) {
         action();
         return;
       }
 
-      if (isCreditsLoadedRef.current) {
-        pendingActionRef.current = action;
-        isWaitingForPurchaseRef.current = true;
-        onShowPaywallRef.current(requiredCreditsRef.current);
+      if (state.isCreditsLoadedRef.current) {
+        state.pendingActionRef.current = action;
+        state.isWaitingForPurchaseRef.current = true;
+        state.onShowPaywallRef.current(state.requiredCreditsRef.current);
         return;
       }
-      pendingActionRef.current = action;
-      isWaitingForAuthCreditsRef.current = true;
+      state.pendingActionRef.current = action;
+      state.isWaitingForAuthCreditsRef.current = true;
     };
     onShowAuthModal(postAuthAction);
     return false;
   }
 
-  if (hasSubscriptionRef.current) {
+  if (state.hasSubscriptionRef.current) {
     action();
     return true;
   }
 
-  if (creditBalanceRef.current < requiredCreditsRef.current) {
-    pendingActionRef.current = action;
-    isWaitingForPurchaseRef.current = true;
-    onShowPaywallRef.current(requiredCreditsRef.current);
+  if (state.creditBalanceRef.current < state.requiredCreditsRef.current) {
+    state.pendingActionRef.current = action;
+    state.isWaitingForPurchaseRef.current = true;
+    state.onShowPaywallRef.current(state.requiredCreditsRef.current);
     return false;
   }
   action();
   return true;
-};
+}

package/src/domains/subscription/presentation/hooks/useFeatureGateState.ts

@@ -0,0 +1,76 @@
+import { useRef } from "react";
+import type { UseFeatureGateParams } from "../useFeatureGate.types";
+
+/**
+ * Internal state management for useFeatureGate hook.
+ * Encapsulates all refs and state to reduce parameter passing.
+ */
+export interface FeatureGateState {
+  // Action queue
+  pendingActionRef: React.MutableRefObject<(() => void | Promise<void>) | null>;
+
+  // Previous values for change detection
+  prevCreditBalanceRef: React.MutableRefObject<number | undefined>;
+  prevHasSubscriptionRef: React.MutableRefObject<boolean>;
+
+  // Waiting flags for async operations
+  isWaitingForAuthCreditsRef: React.MutableRefObject<boolean>;
+  isWaitingForPurchaseRef: React.MutableRefObject<boolean>;
+
+  // Live refs (synced with current values)
+  creditBalanceRef: React.MutableRefObject<number>;
+  hasSubscriptionRef: React.MutableRefObject<boolean>;
+  onShowPaywallRef: React.MutableRefObject<(requiredCredits?: number) => void>;
+  requiredCreditsRef: React.MutableRefObject<number>;
+  isCreditsLoadedRef: React.MutableRefObject<boolean>;
+}
+
+/**
+ * Creates and initializes all refs for useFeatureGate.
+ * This encapsulates ref creation and initialization logic.
+ */
+export function useFeatureGateRefs(params: UseFeatureGateParams): FeatureGateState {
+  const {
+    creditBalance,
+    hasSubscription = false,
+    onShowPaywall,
+    requiredCredits = 1,
+    isCreditsLoaded = true,
+  } = params;
+
+  const pendingActionRef = useRef<(() => void | Promise<void>) | null>(null);
+  const prevCreditBalanceRef = useRef(creditBalance);
+  const prevHasSubscriptionRef = useRef(hasSubscription);
+  const isWaitingForAuthCreditsRef = useRef(false);
+  const isWaitingForPurchaseRef = useRef(false);
+
+  return {
+    pendingActionRef,
+    prevCreditBalanceRef,
+    prevHasSubscriptionRef,
+    isWaitingForAuthCreditsRef,
+    isWaitingForPurchaseRef,
+    creditBalanceRef: useRef(creditBalance),
+    hasSubscriptionRef: useRef(hasSubscription),
+    onShowPaywallRef: useRef(onShowPaywall),
+    requiredCreditsRef: useRef(requiredCredits),
+    isCreditsLoadedRef: useRef(isCreditsLoaded),
+  };
+}
+
+/**
+ * Updates live refs when their source values change.
+ * Call this in a useEffect or when values update.
+ */
+export function updateLiveRefs(
+  state: FeatureGateState,
+  params: Pick<UseFeatureGateParams, 'creditBalance' | 'hasSubscription' | 'onShowPaywall' | 'requiredCredits' | 'isCreditsLoaded'>
+): void {
+  const { creditBalance, hasSubscription, onShowPaywall, requiredCredits, isCreditsLoaded } = params;
+
+  state.creditBalanceRef.current = creditBalance;
+  state.hasSubscriptionRef.current = hasSubscription;
+  state.onShowPaywallRef.current = onShowPaywall;
+  state.requiredCreditsRef.current = requiredCredits;
+  state.isCreditsLoadedRef.current = isCreditsLoaded;
+}

package/src/domains/subscription/presentation/useAuthAwarePurchase.ts

@@ -3,6 +3,7 @@ import type { PurchasesPackage } from "react-native-purchases";
 import { usePremium } from "./usePremium";
 import type { PurchaseSource } from "../core/SubscriptionConstants";
 import { authPurchaseStateManager } from "../infrastructure/utils/authPurchaseState";
+import { requireAuthentication } from "./utils/authCheckUtils";
 
 export const configureAuthProvider = (provider: import("../infrastructure/utils/authPurchaseState").PurchaseAuthProvider): void => {
   authPurchaseStateManager.configure(provider);
@@ -26,6 +27,10 @@ interface UseAuthAwarePurchaseResult {
   executeSavedPurchase: () => Promise<boolean>;
 }
 
+/**
+ * Hook for purchase operations that handle authentication.
+ * Automatically saves pending purchases and shows auth modal when needed.
+ */
 export const useAuthAwarePurchase = (
   params?: UseAuthAwarePurchaseParams
 ): UseAuthAwarePurchaseResult => {
@@ -50,11 +55,10 @@ export const useAuthAwarePurchase = (
     }
   }, [purchasePackage]);
 
+  // Auto-execute saved purchase when user authenticates
   useEffect(() => {
     const authProvider = authPurchaseStateManager.getProvider();
-    if (!authProvider) return;
-
-    const hasUser = authProvider.hasFirebaseUser();
+    const hasUser = authProvider && authProvider.hasFirebaseUser();
     const hasSavedPurchase = !!authPurchaseStateManager.getSavedPurchase();
 
     if (hasUser && hasSavedPurchase && !isExecutingSavedRef.current) {
@@ -69,18 +73,14 @@ export const useAuthAwarePurchase = (
     async (pkg: PurchasesPackage, source?: PurchaseSource): Promise<boolean> => {
       const authProvider = authPurchaseStateManager.getProvider();
 
-      if (!authProvider) {
-        return false;
-      }
-
-      if (!authProvider.hasFirebaseUser()) {
+      if (!requireAuthentication(authProvider)) {
+        // User not authenticated, purchase saved and auth modal shown
         authPurchaseStateManager.savePurchase(pkg, source || params?.source || "settings");
-        authProvider.showAuthModal();
         return false;
       }
 
+      // User authenticated, proceed with purchase
       const result = await purchasePackage(pkg);
-
       return result;
     },
     [purchasePackage, params?.source]
@@ -89,17 +89,11 @@ export const useAuthAwarePurchase = (
   const handleRestore = useCallback(async (): Promise<boolean> => {
     const authProvider = authPurchaseStateManager.getProvider();
 
-    if (!authProvider) {
-      return false;
-    }
-
-    if (!authProvider.hasFirebaseUser()) {
-      authProvider.showAuthModal();
+    if (!requireAuthentication(authProvider)) {
       return false;
     }
 
     const result = await restorePurchase();
-
     return result;
   }, [restorePurchase]);
 

package/src/domains/subscription/presentation/useFeatureGate.ts

@@ -1,8 +1,8 @@
-import { useCallback, useRef, useEffect } from "react";
+import { useCallback, useEffect } from "react";
 import type { UseFeatureGateParams, UseFeatureGateResult } from "./useFeatureGate.types";
 import { DEFAULT_REQUIRED_CREDITS, canExecuteAuthAction, canExecutePurchaseAction } from "../application/featureGate/featureGateBusinessRules";
-import { useSyncedRefs } from "./featureGateRefs";
 import { executeFeatureAction } from "./featureGateActions";
+import { useFeatureGateRefs, updateLiveRefs } from "./hooks/useFeatureGateState";
 
 export function useFeatureGate(params: UseFeatureGateParams): UseFeatureGateResult {
   const {
@@ -11,73 +11,64 @@ export function useFeatureGate(params: UseFeatureGateParams): UseFeatureGateResu
     hasSubscription = false,
     creditBalance,
     requiredCredits = DEFAULT_REQUIRED_CREDITS,
-    onShowPaywall,
     isCreditsLoaded = true,
   } = params;
 
-  const pendingActionRef = useRef<(() => void | Promise<void>) | null>(null);
-  const prevCreditBalanceRef = useRef(creditBalance);
-  // Separate ref to track previous subscription state for canExecutePurchaseAction.
-  // NOTE: Must NOT use hasSubscriptionRef from useSyncedRefs here because useSyncedRefs
-  // effects run BEFORE this effect (React runs effects in definition order), so
-  // hasSubscriptionRef.current would already be the NEW value when we check it.
-  const prevHasSubscriptionRef = useRef(hasSubscription);
-  const isWaitingForPurchaseRef = useRef(false);
-  const isWaitingForAuthCreditsRef = useRef(false);
+  const state = useFeatureGateRefs(params);
 
-  const { creditBalanceRef, hasSubscriptionRef, onShowPaywallRef, requiredCreditsRef, isCreditsLoadedRef } = useSyncedRefs(creditBalance, hasSubscription, onShowPaywall, requiredCredits, isCreditsLoaded);
+  // Update live refs when params change
+  useEffect(() => {
+    updateLiveRefs(state, params);
+  });
 
+  // Handle post-auth credit loading and action execution
   useEffect(() => {
     const shouldExecute = canExecuteAuthAction(
-      isWaitingForAuthCreditsRef.current,
+      state.isWaitingForAuthCreditsRef.current,
       isCreditsLoaded,
-      !!pendingActionRef.current,
+      !!state.pendingActionRef.current,
       hasSubscription,
       creditBalance,
       requiredCredits
     );
 
     if (shouldExecute) {
-      isWaitingForAuthCreditsRef.current = false;
-      const action = pendingActionRef.current!;
-      pendingActionRef.current = null;
+      state.isWaitingForAuthCreditsRef.current = false;
+      const action = state.pendingActionRef.current!;
+      state.pendingActionRef.current = null;
       action();
       return;
     }
 
-    if (isWaitingForAuthCreditsRef.current && isCreditsLoaded && pendingActionRef.current) {
-      isWaitingForAuthCreditsRef.current = false;
-      isWaitingForPurchaseRef.current = true;
-      // Use ref to avoid unstable callback dependency
-      onShowPaywallRef.current(requiredCreditsRef.current);
+    if (state.isWaitingForAuthCreditsRef.current && isCreditsLoaded && state.pendingActionRef.current) {
+      state.isWaitingForAuthCreditsRef.current = false;
+      state.isWaitingForPurchaseRef.current = true;
+      state.onShowPaywallRef.current(state.requiredCreditsRef.current);
     }
-    // Removed onShowPaywall from dependencies - using ref instead
-  }, [isCreditsLoaded, creditBalance, hasSubscription, requiredCredits, onShowPaywallRef, requiredCreditsRef]);
+  }, [isCreditsLoaded, creditBalance, hasSubscription, requiredCredits, state]);
 
+  // Handle post-purchase action execution
   useEffect(() => {
-    // Use prevHasSubscriptionRef (updated AFTER check) not hasSubscriptionRef from useSyncedRefs
-    // (which is already updated to new value before this effect runs - race condition fix)
     const shouldExecute = canExecutePurchaseAction(
-      isWaitingForPurchaseRef.current,
+      state.isWaitingForPurchaseRef.current,
       creditBalance,
-      prevCreditBalanceRef.current ?? 0,
+      state.prevCreditBalanceRef.current ?? 0,
       hasSubscription,
-      prevHasSubscriptionRef.current,
-      !!pendingActionRef.current
+      state.prevHasSubscriptionRef.current,
+      !!state.pendingActionRef.current
     );
 
     if (shouldExecute) {
-      const action = pendingActionRef.current!;
-      pendingActionRef.current = null;
-      isWaitingForPurchaseRef.current = false;
+      const action = state.pendingActionRef.current!;
+      state.pendingActionRef.current = null;
+      state.isWaitingForPurchaseRef.current = false;
       action();
     }
 
-    // Update AFTER check so next render has correct "prev" values
-    prevCreditBalanceRef.current = creditBalance;
-    prevHasSubscriptionRef.current = hasSubscription;
-     
-  }, [creditBalance, hasSubscription]);
+    // Update prev refs AFTER check for next render
+    state.prevCreditBalanceRef.current = creditBalance;
+    state.prevHasSubscriptionRef.current = hasSubscription;
+  }, [creditBalance, hasSubscription, state]);
 
   const requireFeature = useCallback(
     (action: () => void | Promise<void>): boolean => {
@@ -85,17 +76,10 @@ export function useFeatureGate(params: UseFeatureGateParams): UseFeatureGateResu
         action,
         isAuthenticated,
         onShowAuthModal,
-        hasSubscriptionRef,
-        creditBalanceRef,
-        requiredCreditsRef,
-        onShowPaywallRef,
-        pendingActionRef,
-        isWaitingForAuthCreditsRef,
-        isWaitingForPurchaseRef,
-        isCreditsLoadedRef
+        state
       );
     },
-    [isAuthenticated, onShowAuthModal, hasSubscriptionRef, creditBalanceRef, requiredCreditsRef, onShowPaywallRef, isCreditsLoadedRef]
+    [isAuthenticated, onShowAuthModal, state]
   );
 
   return {

package/src/domains/subscription/presentation/usePremium.ts

@@ -7,11 +7,7 @@ import { UsePremiumResult } from './usePremium.types';
 /**
  * Facade hook that combines status, packages, and actions.
  *
- * This provides backward compatibility with existing code while allowing
- * components to use more focused hooks (usePremiumStatus, usePremiumPackages, usePremiumActions)
- * for better performance and testability.
- *
- * For new components, consider using the focused hooks:
+ * Consider using the focused hooks for better performance:
  * - usePremiumStatus() - when you only need premium status
  * - usePremiumPackages() - when you only need package data
  * - usePremiumActions() - when you only need actions
@@ -28,7 +24,6 @@ export const usePremium = (): UsePremiumResult => {
     ...status,
     ...packages,
     ...actions,
-    // Merge loading states for backward compatibility
     isLoading: status.isSyncing || packages.isLoading || actions.isLoading,
   }), [
     status,

package/src/domains/subscription/presentation/utils/authCheckUtils.ts

@@ -0,0 +1,42 @@
+/**
+ * Authentication check utilities for purchase flows.
+ * Extracted to reduce duplication in useAuthAwarePurchase.
+ */
+
+export interface PurchaseAuthProvider {
+  hasFirebaseUser: () => boolean;
+  showAuthModal: () => void;
+}
+
+/**
+ * Checks if auth provider is available and user is authenticated.
+ *
+ * @param authProvider - Auth provider from authPurchaseStateManager
+ * @returns true if user is authenticated, false otherwise
+ */
+export function isUserAuthenticated(authProvider: PurchaseAuthProvider | null): boolean {
+  if (!authProvider) {
+    return false;
+  }
+  return authProvider.hasFirebaseUser();
+}
+
+/**
+ * Ensures user is authenticated before proceeding with an action.
+ * If not authenticated, shows auth modal and returns false.
+ *
+ * @param authProvider - Auth provider from authPurchaseStateManager
+ * @returns true if authenticated, false if auth modal was shown
+ */
+export function requireAuthentication(authProvider: PurchaseAuthProvider | null): boolean {
+  if (!authProvider) {
+    return false;
+  }
+
+  if (!authProvider.hasFirebaseUser()) {
+    authProvider.showAuthModal();
+    return false;
+  }
+
+  return true;
+}

package/src/index.ts

@@ -9,6 +9,13 @@ export {
   PURCHASE_TYPE,
   ANONYMOUS_CACHE_KEY,
 } from "./domains/subscription/core/SubscriptionConstants";
+
+// Domain Events
+export { SUBSCRIPTION_EVENTS } from "./domains/subscription/core/events/SubscriptionEvents";
+export type { SubscriptionEventType, SyncStatusChangedEvent } from "./domains/subscription/core/events/SubscriptionEvents";
+export type { PurchaseCompletedEvent, RenewalDetectedEvent, PremiumStatusChangedEvent } from "./domains/subscription/core/SubscriptionEvents";
+export { FLOW_EVENTS } from "./domains/subscription/core/events/FlowEvents";
+export type { FlowEventType, OnboardingCompletedEvent, PaywallShownEvent, PaywallClosedEvent } from "./domains/subscription/core/events/FlowEvents";
 export type {
   UserTierType,
   SubscriptionStatusType,
@@ -44,6 +51,14 @@ export {
 } from "./shared/utils/Result";
 export type { Result, Success, Failure } from "./shared/utils/Result";
 
+// Cache Invalidation Utilities
+export {
+  invalidateSubscriptionCaches,
+  invalidateSubscriptionStatus,
+  invalidateCredits,
+  invalidateAllUserData,
+} from "./shared/infrastructure/react-query/utils";
+
 // Infrastructure Layer (Services & Repositories)
 export { initializeSubscription } from "./domains/subscription/application/initializer/SubscriptionInitializer";
 export type { SubscriptionInitConfig, CreditPackageConfig } from "./domains/subscription/application/SubscriptionInitializerTypes";
@@ -176,10 +191,6 @@ export type { ManagedSubscriptionFlowProps } from "./domains/subscription/presen
 export { SubscriptionFlowStatus } from "./domains/subscription/presentation/useSubscriptionFlow";
 export { SubscriptionFlowProvider, useSubscriptionFlowStatus } from "./domains/subscription/presentation/providers/SubscriptionFlowProvider";
 
-// Purchase Loading Overlay
-export { PurchaseLoadingOverlay } from "./domains/subscription/presentation/components/overlay/PurchaseLoadingOverlay";
-export type { PurchaseLoadingOverlayProps } from "./domains/subscription/presentation/components/overlay/PurchaseLoadingOverlay";
-
 // Init Module Factory
 export {
   createSubscriptionInitModule,

package/src/shared/infrastructure/SubscriptionEventBus.ts

@@ -17,7 +17,7 @@ class SubscriptionEventBus {
     if (!this.listeners.has(event)) {
       this.listeners.set(event, new Set());
     }
-    
+
     const eventSet = this.listeners.get(event)!;
     eventSet.add(callback as EventCallback);
 
@@ -36,8 +36,6 @@ class SubscriptionEventBus {
     const listeners = this.listeners.get(event);
     if (!listeners || listeners.size === 0) return;
 
-    // Use microtask for async execution to not block main thread
-    // but keep it fast.
     listeners.forEach(callback => {
       queueMicrotask(() => {
         try {
@@ -71,19 +69,9 @@ class SubscriptionEventBus {
 
 export const subscriptionEventBus = SubscriptionEventBus.getInstance();
 
-export const SUBSCRIPTION_EVENTS = {
-  CREDITS_UPDATED: "credits_updated",
-  PURCHASE_COMPLETED: "purchase_completed",
-  RENEWAL_DETECTED: "renewal_detected",
-  PREMIUM_STATUS_CHANGED: "premium_status_changed",
-  SYNC_STATUS_CHANGED: "sync_status_changed",
-} as const;
-
-export const FLOW_EVENTS = {
-  ONBOARDING_COMPLETED: "flow_onboarding_completed",
-  PAYWALL_SHOWN: "flow_paywall_shown",
-  PAYWALL_CLOSED: "flow_paywall_closed",
-} as const;
+// Re-export event constants for external use
+export { SUBSCRIPTION_EVENTS } from "../../domains/subscription/core/events/SubscriptionEvents";
+export { FLOW_EVENTS } from "../../domains/subscription/core/events/FlowEvents";
+export type { SubscriptionEventType } from "../../domains/subscription/core/events/SubscriptionEvents";
+export type { FlowEventType } from "../../domains/subscription/core/events/FlowEvents";
 
-export type SubscriptionEventType = typeof SUBSCRIPTION_EVENTS[keyof typeof SUBSCRIPTION_EVENTS];
-export type FlowEventType = typeof FLOW_EVENTS[keyof typeof FLOW_EVENTS];

package/src/shared/infrastructure/react-query/queryConfig.ts

@@ -36,6 +36,3 @@ export const LONG_CACHE_CONFIG = {
   refetchOnWindowFocus: false,
   refetchOnReconnect: true,
 };
-
-/** @deprecated Use SHORT_CACHE_CONFIG instead */
-export const NO_CACHE_QUERY_CONFIG = SHORT_CACHE_CONFIG;

package/src/shared/infrastructure/react-query/utils/cacheInvalidation.ts

@@ -0,0 +1,97 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { SUBSCRIPTION_QUERY_KEYS } from "../../../../domains/subscription/infrastructure/hooks/subscriptionQueryKeys";
+import { subscriptionStatusQueryKeys } from "../../../../domains/subscription/presentation/useSubscriptionStatus";
+import { creditsQueryKeys } from "../../../../domains/credits/presentation/creditsQueryKeys";
+
+/**
+ * Centralized cache invalidation utilities for subscription-related queries.
+ * This ensures consistent cache invalidation across all mutations and removes code duplication.
+ */
+
+/**
+ * Invalidate all subscription-related caches for a specific user.
+ * This includes:
+ * - Subscription packages
+ * - Subscription status
+ * - Credits
+ *
+ * @param queryClient - TanStack Query client instance
+ * @param userId - User ID to invalidate caches for
+ */
+export function invalidateSubscriptionCaches(
+  queryClient: QueryClient,
+  userId: string | null | undefined
+): void {
+  if (!userId) {
+    return;
+  }
+
+  // Invalidate packages (global, not user-specific)
+  queryClient.invalidateQueries({
+    queryKey: SUBSCRIPTION_QUERY_KEYS.packages,
+  });
+
+  // Invalidate subscription status (user-specific)
+  queryClient.invalidateQueries({
+    queryKey: subscriptionStatusQueryKeys.user(userId),
+  });
+
+  // Invalidate credits (user-specific)
+  queryClient.invalidateQueries({
+    queryKey: creditsQueryKeys.user(userId),
+  });
+}
+
+/**
+ * Invalidate only subscription status cache.
+ * Use this when only subscription status changes, not credits.
+ *
+ * @param queryClient - TanStack Query client instance
+ * @param userId - User ID to invalidate cache for
+ */
+export function invalidateSubscriptionStatus(
+  queryClient: QueryClient,
+  userId: string | null | undefined
+): void {
+  if (!userId) {
+    return;
+  }
+
+  queryClient.invalidateQueries({
+    queryKey: subscriptionStatusQueryKeys.user(userId),
+  });
+}
+
+/**
+ * Invalidate only credits cache.
+ * Use this when only credits change, not subscription status.
+ *
+ * @param queryClient - TanStack Query client instance
+ * @param userId - User ID to invalidate cache for
+ */
+export function invalidateCredits(
+  queryClient: QueryClient,
+  userId: string | null | undefined
+): void {
+  if (!userId) {
+    return;
+  }
+
+  queryClient.invalidateQueries({
+    queryKey: creditsQueryKeys.user(userId),
+  });
+}
+
+/**
+ * Invalidate all caches for a user (subscription + credits).
+ * Alias for invalidateSubscriptionCaches for better semantic clarity.
+ *
+ * @param queryClient - TanStack Query client instance
+ * @param userId - User ID to invalidate caches for
+ */
+export function invalidateAllUserData(
+  queryClient: QueryClient,
+  userId: string | null | undefined
+): void {
+  invalidateSubscriptionCaches(queryClient, userId);
+}

package/src/shared/infrastructure/react-query/utils/index.ts

@@ -0,0 +1,6 @@
+export {
+  invalidateSubscriptionCaches,
+  invalidateSubscriptionStatus,
+  invalidateCredits,
+  invalidateAllUserData,
+} from "./cacheInvalidation";

package/src/domains/subscription/presentation/components/overlay/PurchaseLoadingOverlay.tsx

@@ -1,60 +0,0 @@
-/**
- * Purchase Loading Overlay
- * Full-screen overlay shown during purchase operations
- * Locks the UI and shows a spinner with optional message
- *
- * This is now a props-based component. Pass isLoading from parent component.
- */
-
-import React from "react";
-import { View, Modal, StyleSheet } from "react-native";
-import { AtomicSpinner, AtomicText } from "@umituz/react-native-design-system/atoms";
-import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
-import type { PurchaseLoadingOverlayProps } from "./PurchaseLoadingOverlay.types";
-
-export type { PurchaseLoadingOverlayProps };
-
-export const PurchaseLoadingOverlay: React.FC<PurchaseLoadingOverlayProps> = React.memo(
-  ({ loadingText, isLoading }) => {
-    const tokens = useAppDesignTokens();
-
-    return (
-      <Modal visible={isLoading} transparent animationType="none" statusBarTranslucent>
-        <View style={[styles.container, { backgroundColor: "rgba(0, 0, 0, 0.7)" }]}>
-          <View style={[styles.content, { backgroundColor: tokens.colors.surface }]}>
-            <AtomicSpinner size="lg" color="primary" />
-            {loadingText && (
-              <AtomicText
-                type="bodyLarge"
-                style={[styles.text, { color: tokens.colors.textPrimary }]}
-              >
-                {loadingText}
-              </AtomicText>
-            )}
-          </View>
-        </View>
-      </Modal>
-    );
-  }
-);
-
-PurchaseLoadingOverlay.displayName = "PurchaseLoadingOverlay";
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    justifyContent: "center",
-    alignItems: "center",
-  },
-  content: {
-    paddingHorizontal: 32,
-    paddingVertical: 24,
-    borderRadius: 16,
-    alignItems: "center",
-    minWidth: 200,
-  },
-  text: {
-    marginTop: 16,
-    textAlign: "center",
-  },
-});

package/src/domains/subscription/presentation/components/overlay/PurchaseLoadingOverlay.types.ts

@@ -1,6 +0,0 @@
-export interface PurchaseLoadingOverlayProps {
-  /** Whether the overlay is visible */
-  isLoading: boolean;
-  /** Loading message to display */
-  loadingText?: string;
-}