@umituz/react-native-subscription 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Subscription management system for React Native apps - Database-first approach with secure validation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.ts

@@ -60,38 +60,69 @@ export {
 export { useSubscription } from './presentation/hooks/useSubscription';
 export type { UseSubscriptionResult } from './presentation/hooks/useSubscription';
 
+export {
+  usePremiumGate,
+  type UsePremiumGateParams,
+  type UsePremiumGateResult,
+} from './presentation/hooks/usePremiumGate';
+
+export {
+  useUserTier,
+  type UseUserTierParams,
+  type UseUserTierResult,
+} from './presentation/hooks/useUserTier';
+
+export {
+  useUserTierWithRepository,
+  type UseUserTierWithRepositoryParams,
+  type UseUserTierWithRepositoryResult,
+  type AuthProvider,
+} from './presentation/hooks/useUserTierWithRepository';
+
 // =============================================================================
 // UTILS
 // =============================================================================
 
 // Date utilities
-export {
-  formatExpirationDate,
-  calculateExpirationDate,
-} from './utils/dateUtils';
-
 export {
   isSubscriptionExpired,
   getDaysUntilExpiration,
 } from './utils/dateValidationUtils';
 
+
+// =============================================================================
+// USER TIER - Types & Utilities
+// =============================================================================
+
+export type {
+  UserTier,
+  UserTierInfo,
+  PremiumStatusFetcher,
+} from './utils/types';
+
 export {
-  extractPlanFromProductId,
-} from './utils/planDetectionUtils';
+  getUserTierInfo,
+  checkPremiumAccess,
+} from './utils/tierUtils';
 
-// Price utilities
-export { formatPrice } from './utils/priceUtils';
+export {
+  hasTierAccess,
+  isTierPremium,
+  isTierFreemium,
+  isTierGuest,
+} from './utils/userTierUtils';
 
-// Period utilities
-export { getPeriodText } from './utils/periodUtils';
+export {
+  isAuthenticated,
+  isGuest,
+} from './utils/authUtils';
 
 export {
-  SUBSCRIPTION_PLAN_TYPES,
-  MIN_SUBSCRIPTION_DURATIONS_DAYS,
-  SUBSCRIPTION_PERIOD_DAYS,
-  DATE_CONSTANTS,
-  SUBSCRIPTION_PERIOD_UNITS,
-  PRODUCT_ID_KEYWORDS,
-  type SubscriptionPlanType,
-} from './utils/subscriptionConstants';
+  isValidUserTier,
+  isUserTierInfo,
+  validateUserId,
+  validateIsGuest,
+  validateIsPremium,
+  validateFetcher,
+} from './utils/validation';
 

package/src/presentation/hooks/__tests__/useUserTier.authenticated.test.ts

@@ -0,0 +1,79 @@
+/**
+ * useUserTier Hook Tests - Authenticated Users
+ * 
+ * Tests for authenticated user scenarios
+ */
+
+import React from 'react';
+import { create } from 'react-test-renderer';
+import { useUserTier, type UseUserTierParams } from '../useUserTier';
+
+// Test component that uses hook
+function TestComponent({ params }: { params: UseUserTierParams }) {
+  const tierInfo = useUserTier(params);
+  return React.createElement('div', { 'data-testid': 'tier-info' }, JSON.stringify(tierInfo));
+}
+
+describe('useUserTier - Authenticated Users', () => {
+  it('should return premium tier for authenticated premium users', () => {
+    const params: UseUserTierParams = {
+      isGuest: false,
+      userId: 'user123',
+      isPremium: true,
+    };
+
+    const component = create(React.createElement(TestComponent, { params }));
+    const tree = component.toJSON();
+    const tierInfo = JSON.parse((tree as any).children[0]);
+
+    expect(tierInfo.tier).toBe('premium');
+    expect(tierInfo.isPremium).toBe(true);
+    expect(tierInfo.isGuest).toBe(false);
+    expect(tierInfo.isAuthenticated).toBe(true);
+    expect(tierInfo.userId).toBe('user123');
+  });
+
+  it('should return freemium tier for authenticated non-premium users', () => {
+    const params: UseUserTierParams = {
+      isGuest: false,
+      userId: 'user123',
+      isPremium: false,
+    };
+
+    const component = create(React.createElement(TestComponent, { params }));
+    const tree = component.toJSON();
+    const tierInfo = JSON.parse((tree as any).children[0]);
+
+    expect(tierInfo.tier).toBe('freemium');
+    expect(tierInfo.isPremium).toBe(false);
+    expect(tierInfo.isGuest).toBe(false);
+    expect(tierInfo.isAuthenticated).toBe(true);
+    expect(tierInfo.userId).toBe('user123');
+  });
+
+  it('should handle different userId formats', () => {
+    const testCases = [
+      'user123',
+      'user-with-dashes',
+      'user_with_underscores',
+      'user@example.com',
+      '1234567890',
+    ];
+
+    testCases.forEach(userId => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId,
+        isPremium: false,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree = component.toJSON();
+      const tierInfo = JSON.parse((tree as any).children[0]);
+
+      expect(tierInfo.userId).toBe(userId);
+      expect(tierInfo.isAuthenticated).toBe(true);
+      expect(tierInfo.isGuest).toBe(false);
+    });
+  });
+});

package/src/presentation/hooks/__tests__/useUserTier.guest.test.ts

@@ -0,0 +1,70 @@
+/**
+ * useUserTier Hook Tests - Guest Users
+ * 
+ * Tests for guest user scenarios
+ */
+
+import React from 'react';
+import { create } from 'react-test-renderer';
+import { useUserTier, type UseUserTierParams } from '../useUserTier';
+
+// Test component that uses the hook
+function TestComponent({ params }: { params: UseUserTierParams }) {
+  const tierInfo = useUserTier(params);
+  return React.createElement('div', { 'data-testid': 'tier-info' }, JSON.stringify(tierInfo));
+}
+
+describe('useUserTier - Guest Users', () => {
+  it('should return guest tier for guest users', () => {
+    const params: UseUserTierParams = {
+      isGuest: true,
+      userId: null,
+      isPremium: false,
+    };
+
+    const component = create(React.createElement(TestComponent, { params }));
+    const tree = component.toJSON();
+    const tierInfo = JSON.parse((tree as any).children[0]);
+
+    expect(tierInfo.tier).toBe('guest');
+    expect(tierInfo.isPremium).toBe(false);
+    expect(tierInfo.isGuest).toBe(true);
+    expect(tierInfo.isAuthenticated).toBe(false);
+    expect(tierInfo.userId).toBe(null);
+    expect(tierInfo.isLoading).toBe(false);
+    expect(tierInfo.error).toBe(null);
+  });
+
+  it('should ignore isPremium for guest users', () => {
+    const params: UseUserTierParams = {
+      isGuest: true,
+      userId: null,
+      isPremium: true, // Even if true, guest should be false
+    };
+
+    const component = create(React.createElement(TestComponent, { params }));
+    const tree = component.toJSON();
+    const tierInfo = JSON.parse((tree as any).children[0]);
+
+    expect(tierInfo.tier).toBe('guest');
+    expect(tierInfo.isPremium).toBe(false); // Guest users NEVER have premium
+  });
+
+  it('should handle guest user with userId provided', () => {
+    const params: UseUserTierParams = {
+      isGuest: true,
+      userId: 'user123', // Even with userId, isGuest=true takes precedence
+      isPremium: true,
+    };
+
+    const component = create(React.createElement(TestComponent, { params }));
+    const tree = component.toJSON();
+    const tierInfo = JSON.parse((tree as any).children[0]);
+
+    expect(tierInfo.tier).toBe('guest');
+    expect(tierInfo.isPremium).toBe(false);
+    expect(tierInfo.isGuest).toBe(true);
+    expect(tierInfo.isAuthenticated).toBe(false);
+    expect(tierInfo.userId).toBe(null); // Should be null for guests
+  });
+});

package/src/presentation/hooks/__tests__/useUserTier.states.test.ts

@@ -0,0 +1,167 @@
+/**
+ * useUserTier Hook Tests - States and Memoization
+ * 
+ * Tests for loading/error states and memoization
+ */
+
+import React from 'react';
+import { create } from 'react-test-renderer';
+import { useUserTier, type UseUserTierParams } from '../useUserTier';
+
+// Test component that uses hook
+function TestComponent({ params }: { params: UseUserTierParams }) {
+  const tierInfo = useUserTier(params);
+  return React.createElement('div', { 'data-testid': 'tier-info' }, JSON.stringify(tierInfo));
+}
+
+describe('useUserTier - States and Memoization', () => {
+  describe('Loading and error states', () => {
+    it('should pass through loading state', () => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: false,
+        isLoading: true,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree = component.toJSON();
+      const tierInfo = JSON.parse((tree as any).children[0]);
+
+      expect(tierInfo.isLoading).toBe(true);
+    });
+
+    it('should pass through error state', () => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: false,
+        error: 'Failed to fetch premium status',
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree = component.toJSON();
+      const tierInfo = JSON.parse((tree as any).children[0]);
+
+      expect(tierInfo.error).toBe('Failed to fetch premium status');
+    });
+
+    it('should default loading to false', () => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: false,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree = component.toJSON();
+      const tierInfo = JSON.parse((tree as any).children[0]);
+
+      expect(tierInfo.isLoading).toBe(false);
+    });
+
+    it('should default error to null', () => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: false,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree = component.toJSON();
+      const tierInfo = JSON.parse((tree as any).children[0]);
+
+      expect(tierInfo.error).toBe(null);
+    });
+  });
+
+  describe('Memoization', () => {
+    it('should recalculate when isGuest changes', () => {
+      let params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: true,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      let tree = component.toJSON();
+      let tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.tier).toBe('premium');
+
+      params = {
+        isGuest: true,
+        userId: null,
+        isPremium: true,
+      };
+      component.update(React.createElement(TestComponent, { params }));
+      tree = component.toJSON();
+      tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.tier).toBe('guest');
+    });
+
+    it('should recalculate when userId changes', () => {
+      let params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: true,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      let tree = component.toJSON();
+      let tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.userId).toBe('user123');
+
+      params = {
+        isGuest: false,
+        userId: 'user456',
+        isPremium: true,
+      };
+      component.update(React.createElement(TestComponent, { params }));
+      tree = component.toJSON();
+      tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.userId).toBe('user456');
+    });
+
+    it('should recalculate when isPremium changes', () => {
+      let params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: false,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      let tree = component.toJSON();
+      let tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.tier).toBe('freemium');
+
+      params = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: true,
+      };
+      component.update(React.createElement(TestComponent, { params }));
+      tree = component.toJSON();
+      tierInfo = JSON.parse((tree as any).children[0]);
+      expect(tierInfo.tier).toBe('premium');
+    });
+
+    it('should not recalculate when params are the same', () => {
+      const params: UseUserTierParams = {
+        isGuest: false,
+        userId: 'user123',
+        isPremium: true,
+      };
+
+      const component = create(React.createElement(TestComponent, { params }));
+      const tree1 = component.toJSON();
+      const tierInfo1 = JSON.parse((tree1 as any).children[0]);
+
+      // Update with same params
+      component.update(React.createElement(TestComponent, { params }));
+      const tree2 = component.toJSON();
+      const tierInfo2 = JSON.parse((tree2 as any).children[0]);
+
+      expect(tierInfo1).toEqual(tierInfo2);
+    });
+  });
+});

package/src/presentation/hooks/usePremiumGate.ts

@@ -0,0 +1,116 @@
+/**
+ * usePremiumGate Hook
+ *
+ * Feature gating hook for premium-only features
+ * Provides a simple way to gate features behind premium subscription
+ *
+ * @example
+ * ```typescript
+ * const { requirePremium, isPremium } = usePremiumGate({
+ *   isPremium: subscriptionStore.isPremium,
+ *   onPremiumRequired: () => navigation.navigate('Paywall'),
+ * });
+ *
+ * const handleGenerate = () => {
+ *   requirePremium(() => {
+ *     // This only runs if user is premium
+ *     generateContent();
+ *   });
+ * };
+ * ```
+ */
+
+import { useCallback, useMemo } from "react";
+
+export interface UsePremiumGateParams {
+  /** Whether user has premium access */
+  isPremium: boolean;
+  /** Callback when premium is required but user is not premium */
+  onPremiumRequired: () => void;
+  /** Optional: Whether user is authenticated */
+  isAuthenticated?: boolean;
+  /** Optional: Callback when auth is required but user is not authenticated */
+  onAuthRequired?: () => void;
+}
+
+export interface UsePremiumGateResult {
+  /** Whether user has premium access */
+  isPremium: boolean;
+  /** Whether user is authenticated */
+  isAuthenticated: boolean;
+  /** Gate a feature behind premium - executes action if premium, else calls onPremiumRequired */
+  requirePremium: (action: () => void) => void;
+  /** Gate a feature behind auth - executes action if authenticated, else calls onAuthRequired */
+  requireAuth: (action: () => void) => void;
+  /** Gate a feature behind both auth and premium */
+  requirePremiumWithAuth: (action: () => void) => void;
+  /** Check if feature is accessible (premium check only) */
+  canAccess: boolean;
+  /** Check if feature is accessible (auth + premium) */
+  canAccessWithAuth: boolean;
+}
+
+export function usePremiumGate(
+  params: UsePremiumGateParams
+): UsePremiumGateResult {
+  const {
+    isPremium,
+    onPremiumRequired,
+    isAuthenticated = true,
+    onAuthRequired,
+  } = params;
+
+  const requirePremium = useCallback(
+    (action: () => void) => {
+      if (isPremium) {
+        action();
+      } else {
+        onPremiumRequired();
+      }
+    },
+    [isPremium, onPremiumRequired]
+  );
+
+  const requireAuth = useCallback(
+    (action: () => void) => {
+      if (isAuthenticated) {
+        action();
+      } else {
+        onAuthRequired?.();
+      }
+    },
+    [isAuthenticated, onAuthRequired]
+  );
+
+  const requirePremiumWithAuth = useCallback(
+    (action: () => void) => {
+      if (!isAuthenticated) {
+        onAuthRequired?.();
+        return;
+      }
+      if (!isPremium) {
+        onPremiumRequired();
+        return;
+      }
+      action();
+    },
+    [isAuthenticated, isPremium, onAuthRequired, onPremiumRequired]
+  );
+
+  const canAccess = useMemo(() => isPremium, [isPremium]);
+
+  const canAccessWithAuth = useMemo(
+    () => isAuthenticated && isPremium,
+    [isAuthenticated, isPremium]
+  );
+
+  return {
+    isPremium,
+    isAuthenticated,
+    requirePremium,
+    requireAuth,
+    requirePremiumWithAuth,
+    canAccess,
+    canAccessWithAuth,
+  };
+}

package/src/presentation/hooks/useUserTier.ts

@@ -0,0 +1,78 @@
+/**
+ * useUserTier Hook
+ *
+ * Centralized hook for determining user tier (Guest, Freemium, Premium)
+ * Single source of truth for all premium/freemium/guest checks
+ *
+ * This hook only handles LOGICAL tier determination.
+ * Database operations should be handled by the app via PremiumStatusFetcher.
+ *
+ * @example
+ * ```typescript
+ * const { tier, isPremium, isGuest } = useUserTier({
+ *   isGuest: false,
+ *   userId: 'user123',
+ *   isPremium: true, // App should fetch this from database
+ * });
+ *
+ * // Simple, clean checks
+ * if (tier === "guest") {
+ *   // Show guest upgrade card
+ * } else if (tier === "freemium") {
+ *   // Show freemium limits
+ * } else {
+ *   // Premium features
+ * }
+ * ```
+ */
+
+import { useMemo } from 'react';
+import { getUserTierInfo } from '../../utils/tierUtils';
+import type { UserTierInfo } from '../../utils/types';
+
+export interface UseUserTierParams {
+  /** Whether user is a guest */
+  isGuest: boolean;
+  /** User ID (null for guests) */
+  userId: string | null;
+  /** Whether user has active premium subscription (app should fetch from database) */
+  isPremium: boolean;
+  /** Optional: Loading state from app */
+  isLoading?: boolean;
+  /** Optional: Error state from app */
+  error?: string | null;
+}
+
+export interface UseUserTierResult extends UserTierInfo {
+  /** Whether premium status is currently loading */
+  isLoading: boolean;
+  /** Premium status error (if any) */
+  error: string | null;
+}
+
+/**
+ * Hook to get user tier information
+ * Combines auth state and premium status into single source of truth
+ * 
+ * All premium/freemium/guest checks are centralized here:
+ * - Guest: isGuest || !userId → always freemium, never premium
+ * - Freemium: authenticated but !isPremium
+ * - Premium: authenticated && isPremium
+ * 
+ * Note: This hook only handles LOGICAL tier determination.
+ * Database operations (fetching premium status) should be handled by the app.
+ */
+export function useUserTier(params: UseUserTierParams): UseUserTierResult {
+  const { isGuest, userId, isPremium, isLoading = false, error = null } = params;
+
+  // Calculate tier info using centralized logic
+  const tierInfo = useMemo(() => {
+    return getUserTierInfo(isGuest, userId, isPremium);
+  }, [isGuest, userId, isPremium]);
+
+  return {
+    ...tierInfo,
+    isLoading,
+    error,
+  };
+}