@umituz/react-native-subscription 2.40.13 → 2.40.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.40.13",
+  "version": "2.40.14",
   "description": "Complete subscription management with RevenueCat, paywall UI, and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -38,6 +38,7 @@
     "url": "git+https://github.com/umituz/react-native-subscription.git"
   },
   "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=2.0.0",
     "@tanstack/react-query": ">=5.0.0",
     "@umituz/react-native-auth": "*",
     "expo": ">=54.0.0",

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

@@ -0,0 +1,155 @@
+import { useEffect, useCallback, useRef } from "react";
+import { usePremium } from "../../subscription/presentation/usePremium";
+import { useSubscriptionFlow } from "../../subscription/presentation/useSubscriptionFlow";
+import { usePaywallVisibility } from "../../subscription/presentation/usePaywallVisibility";
+import { PaywallTranslations, PaywallLegalUrls, SubscriptionFeature } from "../entities/types";
+
+export interface PaywallOrchestratorOptions {
+  navigation: any;
+  translations: PaywallTranslations;
+  features: SubscriptionFeature[];
+  legalUrls: PaywallLegalUrls;
+  heroImage: any;
+  isNavReady?: boolean;
+  isLocalizationReady?: boolean;
+  onAuthRequired?: () => void;
+  onPurchaseSuccess?: () => void;
+  bestValueIdentifier?: string;
+  creditsLabel?: string;
+}
+
+/**
+ * High-level orchestrator for Paywall navigation.
+ * Handles automatic triggers (post-onboarding) and manual triggers (showPaywall state).
+ * Centralizes handlers for success, close, and feedback triggers.
+ */
+export function usePaywallOrchestrator({
+  navigation,
+  translations,
+  features,
+  legalUrls,
+  heroImage,
+  isNavReady = true,
+  isLocalizationReady = true,
+  onAuthRequired,
+  onPurchaseSuccess,
+  bestValueIdentifier = "yearly",
+  creditsLabel,
+}: PaywallOrchestratorOptions) {
+  const { 
+    isPremium, 
+    packages, 
+    purchasePackage, 
+    restorePurchase 
+  } = usePremium();
+  
+  const { 
+    state, 
+    markPaywallShown, 
+    closePostOnboardingPaywall, 
+    setShowFeedback 
+  } = useSubscriptionFlow();
+  
+  const { showPaywall, closePaywall } = usePaywallVisibility();
+  const purchasedRef = useRef(false);
+
+  const handleClose = useCallback(async () => {
+    await closePostOnboardingPaywall();
+    closePaywall();
+    
+    // Trigger feedback if user declined and isn't premium
+    if (!isPremium && !purchasedRef.current) {
+      setTimeout(() => setShowFeedback(true), 300);
+    }
+    
+    purchasedRef.current = false;
+    
+    if (navigation.canGoBack()) {
+      navigation.goBack();
+    }
+  }, [closePostOnboardingPaywall, closePaywall, isPremium, navigation, setShowFeedback]);
+
+  const handleSuccess = useCallback(async () => {
+    purchasedRef.current = true;
+    await markPaywallShown();
+    await closePostOnboardingPaywall();
+    
+    onPurchaseSuccess?.();
+    
+    if (navigation.canGoBack()) {
+      navigation.goBack();
+    }
+  }, [markPaywallShown, closePostOnboardingPaywall, onPurchaseSuccess, navigation]);
+
+  useEffect(() => {
+    if (!isNavReady || !isLocalizationReady) return;
+
+    const shouldShowPostOnboarding = 
+      state.isOnboardingComplete && 
+      state.showPostOnboardingPaywall && 
+      !state.paywallShown && 
+      !state.isAuthModalOpen && 
+      !isPremium;
+
+    const shouldShowManual = showPaywall && !isPremium && !state.isAuthModalOpen;
+
+    if (shouldShowPostOnboarding || shouldShowManual) {
+      navigation.navigate("PaywallScreen", {
+        onClose: handleClose,
+        translations,
+        legalUrls,
+        features,
+        bestValueIdentifier,
+        creditsLabel,
+        onAuthRequired,
+        onPurchaseSuccess: handleSuccess,
+        heroImage,
+        source: shouldShowPostOnboarding ? "onboarding" : "manual",
+        packages,
+        onPurchase: purchasePackage,
+        onRestore: restorePurchase,
+      });
+
+      if (shouldShowPostOnboarding) {
+        markPaywallShown();
+      }
+      
+      if (showPaywall) {
+        closePaywall();
+      }
+    }
+  }, [
+    isNavReady,
+    isLocalizationReady,
+    state.isOnboardingComplete,
+    state.showPostOnboardingPaywall,
+    state.paywallShown,
+    state.isAuthModalOpen,
+    isPremium,
+    showPaywall,
+    navigation,
+    handleClose,
+    handleSuccess,
+    translations,
+    legalUrls,
+    features,
+    heroImage,
+    packages,
+    purchasePackage,
+    restorePurchase,
+    markPaywallShown,
+    closePaywall,
+    bestValueIdentifier,
+    creditsLabel,
+    onAuthRequired
+  ]);
+
+  return { 
+    isPremium, 
+    packages, 
+    flowState: state,
+    markPaywallShown,
+    closePostOnboardingPaywall,
+    setShowFeedback
+  };
+}

package/src/domains/paywall/utils/paywallTranslationUtils.ts

@@ -0,0 +1,24 @@
+import { PaywallTranslations } from "../entities/types";
+
+/**
+ * Creates standardized paywall translations from a translation function.
+ * Matches the structure used across the App Factory ecosystem.
+ */
+export const createPaywallTranslations = (
+  t: (key: string) => string,
+  overrides?: Partial<PaywallTranslations>
+): PaywallTranslations => ({
+  title: t("premium.title"),
+  subtitle: t("premium.subtitle"),
+  loadingText: t("paywall.loading"),
+  emptyText: t("paywall.empty"),
+  purchaseButtonText: t("paywall.purchase"),
+  restoreButtonText: t("paywall.restore"),
+  processingText: t("paywall.processing"),
+  privacyText: t("auth.privacyPolicy"),
+  termsOfServiceText: t("auth.termsOfService"),
+  bestValueBadgeText: t("paywall.bestValue"),
+  featuresTitle: t("paywall.featuresTitle"),
+  plansTitle: t("paywall.plansTitle"),
+  ...overrides,
+});

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

@@ -0,0 +1,156 @@
+/**
+ * Subscription Flow Hook
+ * Manages the high-level application flow: Splash -> Onboarding -> Paywall -> Main App.
+ * Centralizing this in the library allows for minimal boilerplate in the main application's navigator.
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import { DeviceEventEmitter } from "react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const PAYWALL_SHOWN_KEY = "post_onboarding_paywall_shown";
+const ONBOARDING_KEY = "onboarding_complete";
+
+export interface SubscriptionFlowState {
+  isInitialized: boolean;
+  isOnboardingComplete: boolean;
+  showPostOnboardingPaywall: boolean;
+  showFeedback: boolean;
+  paywallShown: boolean;
+  isAuthModalOpen: boolean;
+}
+
+export interface UseSubscriptionFlowResult {
+  state: SubscriptionFlowState;
+  completeOnboarding: () => Promise<void>;
+  closePostOnboardingPaywall: () => Promise<void>;
+  closeFeedback: () => void;
+  setAuthModalOpen: (open: boolean) => void;
+  markPaywallShown: () => Promise<void>;
+  setShowFeedback: (show: boolean) => void;
+  resetFlow: () => Promise<void>;
+}
+
+export function useSubscriptionFlow(userId?: string): UseSubscriptionFlowResult {
+  const [state, setState] = useState<SubscriptionFlowState>({
+    isInitialized: false,
+    isOnboardingComplete: false,
+    showPostOnboardingPaywall: false,
+    showFeedback: false,
+    paywallShown: false,
+    isAuthModalOpen: false,
+  });
+
+  // Initialization: Load persisted state
+  useEffect(() => {
+    const init = async () => {
+      try {
+        const [onboardingValue, paywallValue] = await Promise.all([
+          AsyncStorage.getItem(ONBOARDING_KEY),
+          AsyncStorage.getItem(PAYWALL_SHOWN_KEY),
+        ]);
+
+        setState((prev) => ({
+          ...prev,
+          isInitialized: true,
+          isOnboardingComplete: onboardingValue === "true",
+          paywallShown: paywallValue === "true",
+        }));
+      } catch (error) {
+        console.error("[useSubscriptionFlow] Initialization failed:", error);
+        setState((prev) => ({ ...prev, isInitialized: true }));
+      }
+    };
+
+    init();
+
+    // Listen for global onboarding completion events (e.g. from standalone onboarding components)
+    const subscription = DeviceEventEmitter.addListener(
+      "onboarding-complete",
+      () => {
+        setState((prev) => ({ ...prev, isOnboardingComplete: true }));
+        AsyncStorage.setItem(ONBOARDING_KEY, "true");
+      }
+    );
+
+    return () => subscription.remove();
+  }, []);
+
+  const completeOnboarding = useCallback(async () => {
+    try {
+      await AsyncStorage.setItem(ONBOARDING_KEY, "true");
+      setState((prev) => ({
+        ...prev,
+        isOnboardingComplete: true,
+        showPostOnboardingPaywall: true,
+      }));
+      DeviceEventEmitter.emit("onboarding-complete");
+    } catch (e) {
+      console.error("[useSubscriptionFlow] Failed to complete onboarding:", e);
+    }
+  }, []);
+
+  const closePostOnboardingPaywall = useCallback(async () => {
+    try {
+      await AsyncStorage.setItem(PAYWALL_SHOWN_KEY, "true");
+      setState((prev) => ({
+        ...prev,
+        showPostOnboardingPaywall: false,
+        paywallShown: true,
+      }));
+    } catch (e) {
+      console.error("[useSubscriptionFlow] Failed to close paywall:", e);
+    }
+  }, []);
+
+  const closeFeedback = useCallback(() => {
+    setState((prev) => ({ ...prev, showFeedback: false }));
+  }, []);
+
+  const setAuthModalOpen = useCallback((open: boolean) => {
+    setState((prev) => ({ ...prev, isAuthModalOpen: open }));
+  }, []);
+
+  const setShowFeedback = useCallback((show: boolean) => {
+    setState((prev) => ({ ...prev, showFeedback: show }));
+  }, []);
+
+  const markPaywallShown = useCallback(async () => {
+    try {
+      await AsyncStorage.setItem(PAYWALL_SHOWN_KEY, "true");
+      setState((prev) => ({ ...prev, paywallShown: true }));
+    } catch (e) {
+       console.error("[useSubscriptionFlow] Failed to mark paywall shown:", e);
+    }
+  }, []);
+
+  const resetFlow = useCallback(async () => {
+    try {
+      await Promise.all([
+        AsyncStorage.removeItem(ONBOARDING_KEY),
+        AsyncStorage.removeItem(PAYWALL_SHOWN_KEY),
+      ]);
+      setState({
+        isInitialized: true,
+        isOnboardingComplete: false,
+        showPostOnboardingPaywall: false,
+        showFeedback: false,
+        paywallShown: false,
+        isAuthModalOpen: false,
+      });
+    } catch (e) {
+      console.error("[useSubscriptionFlow] Failed to reset flow:", e);
+    }
+  }, []);
+
+  return {
+    state,
+    completeOnboarding,
+    closePostOnboardingPaywall,
+    closeFeedback,
+    setAuthModalOpen,
+    markPaywallShown,
+    setShowFeedback,
+    resetFlow,
+  };
+}

package/src/index.ts

@@ -45,6 +45,8 @@ export { useDeductCredit } from "./domains/credits/presentation/deduct-credit/us
 export { useFeatureGate } from "./domains/subscription/presentation/useFeatureGate";
 export { usePaywallVisibility, paywallControl } from "./domains/subscription/presentation/usePaywallVisibility";
 export { usePremium } from "./domains/subscription/presentation/usePremium";
+export { useSubscriptionFlow } from "./domains/subscription/presentation/useSubscriptionFlow";
+export type { SubscriptionFlowState, UseSubscriptionFlowResult } from "./domains/subscription/presentation/useSubscriptionFlow";
 export { useSubscriptionStatus } from "./domains/subscription/presentation/useSubscriptionStatus";
 export * from "./domains/subscription/presentation/useSubscriptionStatus.types";
 export * from "./presentation/hooks/feedback/usePaywallFeedback";
@@ -65,6 +67,8 @@ export type {
 } from "./domains/subscription/presentation/screens/SubscriptionDetailScreen.types";
 export { PaywallScreen } from "./domains/paywall/components/PaywallScreen";
 export type { PaywallScreenProps } from "./domains/paywall/components/PaywallScreen.types";
+export { usePaywallOrchestrator } from "./domains/paywall/hooks/usePaywallOrchestrator";
+export type { PaywallOrchestratorOptions } from "./domains/paywall/hooks/usePaywallOrchestrator";
 
 export type {
   CreditType,
@@ -86,8 +90,9 @@ export { toDate, toISOString, toTimestamp, getCurrentISOString } from "./shared/
 // Credits Query Keys
 export { creditsQueryKeys } from "./domains/credits/presentation/creditsQueryKeys";
 
-// Paywall Types
-export type { PaywallTranslations, PaywallLegalUrls } from "./domains/paywall/entities/types";
+// Paywall Types & Utils
+export type { PaywallTranslations, PaywallLegalUrls, SubscriptionFeature } from "./domains/paywall/entities/types";
+export { createPaywallTranslations } from "./domains/paywall/utils/paywallTranslationUtils";
 
 // Purchase Loading Overlay
 export { PurchaseLoadingOverlay } from "./domains/subscription/presentation/components/overlay/PurchaseLoadingOverlay";