@umituz/react-native-subscription 1.2.0 → 1.3.1

package/src/utils/__tests__/validation.test.ts

@@ -0,0 +1,108 @@
+/**
+ * User Tier Validation Tests
+ * 
+ * Tests for validation functions and type guards
+ */
+
+import {
+  isValidUserTier,
+  isUserTierInfo,
+  validateUserId,
+  validateIsGuest,
+  validateIsPremium,
+  validateFetcher,
+  type UserTier,
+  type UserTierInfo,
+  type PremiumStatusFetcher,
+} from '../validation';
+
+describe('isValidUserTier', () => {
+  it('should return true for valid tiers', () => {
+    expect(isValidUserTier('guest')).toBe(true);
+    expect(isValidUserTier('freemium')).toBe(true);
+    expect(isValidUserTier('premium')).toBe(true);
+  });
+
+  it('should return false for invalid values', () => {
+    expect(isValidUserTier('invalid')).toBe(false);
+    expect(isValidUserTier('')).toBe(false);
+    expect(isValidUserTier(null)).toBe(false);
+    expect(isValidUserTier(undefined)).toBe(false);
+    expect(isValidUserTier(123)).toBe(false);
+    expect(isValidUserTier({})).toBe(false);
+  });
+});
+
+describe('isUserTierInfo', () => {
+  it('should return true for valid UserTierInfo', () => {
+    const validInfo: UserTierInfo = {
+      tier: 'premium',
+      isPremium: true,
+      isGuest: false,
+      isAuthenticated: true,
+      userId: 'user123',
+    };
+    expect(isUserTierInfo(validInfo)).toBe(true);
+  });
+
+  it('should return false for invalid objects', () => {
+    expect(isUserTierInfo(null)).toBe(false);
+    expect(isUserTierInfo(undefined)).toBe(false);
+    expect(isUserTierInfo('string')).toBe(false);
+    expect(isUserTierInfo({})).toBe(false);
+    expect(isUserTierInfo({ tier: 'invalid' })).toBe(false);
+    expect(isUserTierInfo({ tier: 'premium' })).toBe(false);
+  });
+});
+
+describe('validateUserId', () => {
+  it('should not throw for valid userId', () => {
+    expect(() => validateUserId('user123')).not.toThrow();
+    expect(() => validateUserId(null)).not.toThrow();
+  });
+
+  it('should throw for invalid userId', () => {
+    expect(() => validateUserId('')).toThrow(TypeError);
+    expect(() => validateUserId('   ')).toThrow(TypeError);
+    expect(() => validateUserId(123 as any)).toThrow(TypeError);
+  });
+});
+
+describe('validateIsGuest', () => {
+  it('should not throw for valid isGuest', () => {
+    expect(() => validateIsGuest(true)).not.toThrow();
+    expect(() => validateIsGuest(false)).not.toThrow();
+  });
+
+  it('should throw for invalid isGuest', () => {
+    expect(() => validateIsGuest('true' as any)).toThrow(TypeError);
+    expect(() => validateIsGuest(1 as any)).toThrow(TypeError);
+  });
+});
+
+describe('validateIsPremium', () => {
+  it('should not throw for valid isPremium', () => {
+    expect(() => validateIsPremium(true)).not.toThrow();
+    expect(() => validateIsPremium(false)).not.toThrow();
+  });
+
+  it('should throw for invalid isPremium', () => {
+    expect(() => validateIsPremium('true' as any)).toThrow(TypeError);
+    expect(() => validateIsPremium(1 as any)).toThrow(TypeError);
+  });
+});
+
+describe('validateFetcher', () => {
+  it('should not throw for valid fetcher', () => {
+    const validFetcher: PremiumStatusFetcher = {
+      isPremium: async () => true,
+    };
+    expect(() => validateFetcher(validFetcher)).not.toThrow();
+  });
+
+  it('should throw for invalid fetcher', () => {
+    expect(() => validateFetcher(null as any)).toThrow(TypeError);
+    expect(() => validateFetcher({} as any)).toThrow(TypeError);
+    expect(() => validateFetcher({ isPremium: 'not a function' } as any)).toThrow(TypeError);
+  });
+});

package/src/utils/authUtils.ts

@@ -0,0 +1,65 @@
+/**
+ * Authentication Utilities
+ *
+ * Centralized logic for authentication checks
+ */
+
+import { validateIsGuest, validateUserId } from './validation';
+
+/**
+ * Check if user is authenticated
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for authentication check.
+ * All apps should use this function for consistent authentication logic.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @returns Whether user is authenticated
+ * 
+ * @example
+ * ```typescript
+ * // Guest user
+ * isAuthenticated(true, null); // false
+ * 
+ * // Authenticated user
+ * isAuthenticated(false, 'user123'); // true
+ * ```
+ */
+export function isAuthenticated(
+  isGuest: boolean,
+  userId: string | null,
+): boolean {
+  validateIsGuest(isGuest);
+  validateUserId(userId);
+  
+  return !isGuest && userId !== null;
+}
+
+/**
+ * Check if user is guest
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for guest check.
+ * All apps should use this function for consistent guest logic.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @returns Whether user is a guest
+ * 
+ * @example
+ * ```typescript
+ * // Guest user
+ * isGuest(true, null); // true
+ * 
+ * // Authenticated user
+ * isGuest(false, 'user123'); // false
+ * ```
+ */
+export function isGuest(
+  isGuestFlag: boolean,
+  userId: string | null,
+): boolean {
+  validateIsGuest(isGuestFlag);
+  validateUserId(userId);
+  
+  return isGuestFlag || userId === null;
+}

package/src/utils/premiumAsyncUtils.ts

@@ -0,0 +1,60 @@
+/**
+ * Async Premium Utilities
+ *
+ * Async premium status fetching and tier determination
+ */
+
+import { getIsPremium } from './premiumStatusUtils';
+import type { PremiumStatusFetcher } from './types';
+
+/**
+ * Get user tier info asynchronously with fetcher
+ * 
+ * This function combines getUserTierInfo and getIsPremium logic.
+ * All tier determination logic is centralized here.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @param fetcher - Premium status fetcher (app-specific implementation)
+ * @returns Promise<UserTierInfo> - User tier information
+ */
+export async function getUserTierInfoAsync(
+  isGuestFlag: boolean,
+  userId: string | null,
+  fetcher: PremiumStatusFetcher,
+): Promise<import('./types').UserTierInfo> {
+  // Import here to avoid circular dependency
+  const { getUserTierInfo } = await import('./tierUtils');
+  
+  // Get isPremium using centralized logic (async mode)
+  const isPremium = await getIsPremium(isGuestFlag, userId, fetcher);
+  
+  // Get tier info using centralized logic
+  return getUserTierInfo(isGuestFlag, userId, isPremium);
+}
+
+/**
+ * Check if user has premium access (async version with fetcher)
+ * 
+ * This function combines getIsPremium and checkPremiumAccess logic.
+ * Guest users NEVER have premium access.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @param fetcher - Premium status fetcher (app-specific implementation)
+ * @returns Promise<boolean> - Whether user has premium access
+ */
+export async function checkPremiumAccessAsync(
+  isGuestFlag: boolean,
+  userId: string | null,
+  fetcher: PremiumStatusFetcher,
+): Promise<boolean> {
+  // Import here to avoid circular dependency
+  const { checkPremiumAccess } = await import('./tierUtils');
+  
+  // Get isPremium using centralized logic (async mode)
+  const isPremium = await getIsPremium(isGuestFlag, userId, fetcher);
+  
+  // Apply premium access check logic
+  return checkPremiumAccess(isGuestFlag, userId, isPremium);
+}

package/src/utils/premiumStatusUtils.ts

@@ -0,0 +1,79 @@
+/**
+ * Premium Status Utilities
+ *
+ * Core premium status determination logic
+ */
+
+import { validateIsGuest, validateUserId, validateFetcher } from './validation';
+import type { PremiumStatusFetcher } from './types';
+
+/**
+ * Get isPremium value with centralized logic
+ * 
+ * This function handles the complete logic for determining premium status:
+ * - Guest users NEVER have premium (returns false immediately)
+ * - Authenticated users: uses provided isPremium value OR fetches using fetcher
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for isPremium determination.
+ * All apps should use this function instead of directly calling their premium service.
+ * 
+ * Two usage modes:
+ * 1. Sync mode: If you already have isPremium value, pass it directly
+ * 2. Async mode: If you need to fetch from database, pass a fetcher function
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @param isPremiumOrFetcher - Either boolean (sync) or PremiumStatusFetcher (async)
+ * @returns boolean (sync) or Promise<boolean> (async) - Whether user has premium subscription
+ */
+// Sync overload: when isPremium value is already known
+export function getIsPremium(
+  isGuestFlag: boolean,
+  userId: string | null,
+  isPremium: boolean,
+): boolean;
+
+// Async overload: when fetcher is provided
+export function getIsPremium(
+  isGuestFlag: boolean,
+  userId: string | null,
+  fetcher: PremiumStatusFetcher,
+): Promise<boolean>;
+
+// Implementation
+export function getIsPremium(
+  isGuestFlag: boolean,
+  userId: string | null,
+  isPremiumOrFetcher: boolean | PremiumStatusFetcher,
+): boolean | Promise<boolean> {
+  validateIsGuest(isGuestFlag);
+  validateUserId(userId);
+
+  // Guest users NEVER have premium - this is centralized logic
+  if (isGuestFlag || userId === null) {
+    return false;
+  }
+
+  // Check if it's a boolean (sync mode) or fetcher (async mode)
+  if (typeof isPremiumOrFetcher === 'boolean') {
+    // Sync mode: return the provided isPremium value
+    return isPremiumOrFetcher;
+  }
+
+  // Async mode: validate fetcher and fetch premium status
+  validateFetcher(isPremiumOrFetcher);
+
+  // Authenticated users: fetch premium status using app's fetcher
+  // Package handles the logic, app handles the database operation
+  return (async () => {
+    try {
+      return await isPremiumOrFetcher.isPremium(userId);
+    } catch (error) {
+      // If fetcher throws, assume not premium (fail-safe)
+      // Apps should handle errors in their fetcher implementation
+      throw new Error(
+        `Failed to fetch premium status: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  })();
+}

package/src/utils/premiumUtils.ts

@@ -0,0 +1,9 @@
+/**
+ * Premium Utilities
+ *
+ * Re-export of premium status utilities for backward compatibility
+ */
+
+// Re-export for backward compatibility
+export { getIsPremium } from './premiumStatusUtils';
+export { getUserTierInfoAsync, checkPremiumAccessAsync } from './premiumAsyncUtils';

package/src/utils/tierUtils.ts

@@ -0,0 +1,97 @@
+/**
+ * User Tier Core Utilities
+ *
+ * Core logic for determining user tier and premium status
+ */
+
+import { validateIsGuest, validateUserId, validateIsPremium } from './validation';
+import type { UserTierInfo } from './types';
+
+/**
+ * Determine user tier from auth state and premium status
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for tier determination.
+ * All apps should use this function for consistent tier logic.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @param isPremium - Whether user has active premium subscription
+ * @returns User tier information
+ * 
+ * @example
+ * ```typescript
+ * const tierInfo = getUserTierInfo(false, 'user123', true);
+ * // Returns: { tier: 'premium', isPremium: true, isGuest: false, isAuthenticated: true, userId: 'user123' }
+ * 
+ * const guestInfo = getUserTierInfo(true, null, false);
+ * // Returns: { tier: 'guest', isPremium: false, isGuest: true, isAuthenticated: false, userId: null }
+ * ```
+ */
+export function getUserTierInfo(
+  isGuestFlag: boolean,
+  userId: string | null,
+  isPremium: boolean,
+): UserTierInfo {
+  validateIsGuest(isGuestFlag);
+  validateUserId(userId);
+  validateIsPremium(isPremium);
+
+  // Guest users are always freemium, never premium
+  if (isGuestFlag || userId === null) {
+    return {
+      tier: 'guest',
+      isPremium: false,
+      isGuest: true,
+      isAuthenticated: false,
+      userId: null,
+    };
+  }
+
+  // Authenticated users: premium or freemium
+  return {
+    tier: isPremium ? 'premium' : 'freemium',
+    isPremium,
+    isGuest: false,
+    isAuthenticated: true,
+    userId,
+  };
+}
+
+/**
+ * Check if user has premium access (synchronous version)
+ * 
+ * Guest users NEVER have premium access, regardless of isPremium value.
+ *
+ * @param isGuest - Whether user is a guest
+ * @param userId - User ID (null for guests)
+ * @param isPremium - Whether user has active premium subscription
+ * @returns Whether user has premium access
+ * 
+ * @example
+ * ```typescript
+ * // Guest user - always false
+ * checkPremiumAccess(true, null, true); // false
+ * 
+ * // Authenticated premium user
+ * checkPremiumAccess(false, 'user123', true); // true
+ * 
+ * // Authenticated freemium user
+ * checkPremiumAccess(false, 'user123', false); // false
+ * ```
+ */
+export function checkPremiumAccess(
+  isGuestFlag: boolean,
+  userId: string | null,
+  isPremium: boolean,
+): boolean {
+  validateIsGuest(isGuestFlag);
+  validateUserId(userId);
+  validateIsPremium(isPremium);
+
+  // Guest users never have premium access
+  if (isGuestFlag || userId === null) {
+    return false;
+  }
+
+  return isPremium;
+}

package/src/utils/types.ts

@@ -0,0 +1,37 @@
+/**
+ * User Tier Types
+ *
+ * Type definitions for user tier system
+ */
+
+export type UserTier = 'guest' | 'freemium' | 'premium';
+
+export interface UserTierInfo {
+  /** User tier classification */
+  tier: UserTier;
+
+  /** Whether user has premium access */
+  isPremium: boolean;
+
+  /** Whether user is a guest (not authenticated) */
+  isGuest: boolean;
+
+  /** Whether user is authenticated */
+  isAuthenticated: boolean;
+
+  /** User ID (null for guests) */
+  userId: string | null;
+}
+
+/**
+ * Premium status fetcher interface
+ * Apps should implement this to provide premium status from their database
+ */
+export interface PremiumStatusFetcher {
+  /**
+   * Check if user has active premium subscription
+   * @param userId - User ID (never null, this is only called for authenticated users)
+   * @returns Promise<boolean> - Whether user has premium subscription
+   */
+  isPremium(userId: string): Promise<boolean>;
+}

package/src/utils/userTierUtils.ts

@@ -0,0 +1,81 @@
+/**
+ * Tier Comparison Utilities
+ *
+ * Utilities for comparing and checking user tiers
+ */
+
+import type { UserTier } from './types';
+
+/**
+ * Compare two tiers to determine if first tier has higher or equal access than second
+ * 
+ * Tier hierarchy: guest < freemium < premium
+ * 
+ * @param tier1 - First tier to compare
+ * @param tier2 - Second tier to compare
+ * @returns Whether tier1 has higher or equal access than tier2
+ * 
+ * @example
+ * ```typescript
+ * hasTierAccess('premium', 'freemium'); // true
+ * hasTierAccess('freemium', 'premium'); // false
+ * hasTierAccess('premium', 'premium'); // true
+ * ```
+ */
+export function hasTierAccess(tier1: UserTier, tier2: UserTier): boolean {
+  const tierLevels: Record<UserTier, number> = {
+    guest: 0,
+    freemium: 1,
+    premium: 2,
+  };
+
+  return tierLevels[tier1] >= tierLevels[tier2];
+}
+
+/**
+ * Check if tier is premium
+ * 
+ * @param tier - Tier to check
+ * @returns Whether tier is premium
+ * 
+ * @example
+ * ```typescript
+ * isTierPremium('premium'); // true
+ * isTierPremium('freemium'); // false
+ * ```
+ */
+export function isTierPremium(tier: UserTier): boolean {
+  return tier === 'premium';
+}
+
+/**
+ * Check if tier is freemium
+ * 
+ * @param tier - Tier to check
+ * @returns Whether tier is freemium
+ * 
+ * @example
+ * ```typescript
+ * isTierFreemium('freemium'); // true
+ * isTierFreemium('premium'); // false
+ * ```
+ */
+export function isTierFreemium(tier: UserTier): boolean {
+  return tier === 'freemium';
+}
+
+/**
+ * Check if tier is guest
+ * 
+ * @param tier - Tier to check
+ * @returns Whether tier is guest
+ * 
+ * @example
+ * ```typescript
+ * isTierGuest('guest'); // true
+ * isTierGuest('premium'); // false
+ * ```
+ */
+export function isTierGuest(tier: UserTier): boolean {
+  return tier === 'guest';
+}

package/src/utils/validation.ts

@@ -0,0 +1,119 @@
+/**
+ * User Tier Validation Utilities
+ *
+ * Type guards and validation functions for user tier system
+ */
+
+import type { UserTier, UserTierInfo } from './types';
+
+/**
+ * Type guard to check if a value is a valid UserTier
+ * 
+ * @param value - Value to check
+ * @returns Whether value is a valid UserTier
+ * 
+ * @example
+ * ```typescript
+ * if (isValidUserTier(someValue)) {
+ *   // TypeScript knows someValue is UserTier
+ * }
+ * ```
+ */
+export function isValidUserTier(value: unknown): value is UserTier {
+  return value === 'guest' || value === 'freemium' || value === 'premium';
+}
+
+/**
+ * Type guard to check if an object is a valid UserTierInfo
+ * 
+ * @param value - Value to check
+ * @returns Whether value is a valid UserTierInfo
+ * 
+ * @example
+ * ```typescript
+ * if (isUserTierInfo(someValue)) {
+ *   // TypeScript knows someValue is UserTierInfo
+ * }
+ * ```
+ */
+export function isUserTierInfo(value: unknown): value is UserTierInfo {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  return (
+    isValidUserTier(obj.tier) &&
+    typeof obj.isPremium === 'boolean' &&
+    typeof obj.isGuest === 'boolean' &&
+    typeof obj.isAuthenticated === 'boolean' &&
+    (obj.userId === null || typeof obj.userId === 'string')
+  );
+}
+
+/**
+ * Validate userId parameter
+ * 
+ * @param userId - User ID to validate
+ * @throws {TypeError} If userId is invalid
+ */
+export function validateUserId(userId: string | null): void {
+  if (userId !== null && typeof userId !== 'string') {
+    throw new TypeError(
+      `Invalid userId: expected string or null, got ${typeof userId}`
+    );
+  }
+
+  if (userId !== null && userId.trim() === '') {
+    throw new TypeError('Invalid userId: cannot be empty string');
+  }
+}
+
+/**
+ * Validate isGuest parameter
+ * 
+ * @param isGuest - isGuest flag to validate
+ * @throws {TypeError} If isGuest is invalid
+ */
+export function validateIsGuest(isGuest: boolean): void {
+  if (typeof isGuest !== 'boolean') {
+    throw new TypeError(
+      `Invalid isGuest: expected boolean, got ${typeof isGuest}`
+    );
+  }
+}
+
+/**
+ * Validate isPremium parameter
+ * 
+ * @param isPremium - isPremium flag to validate
+ * @throws {TypeError} If isPremium is invalid
+ */
+export function validateIsPremium(isPremium: boolean): void {
+  if (typeof isPremium !== 'boolean') {
+    throw new TypeError(
+      `Invalid isPremium: expected boolean, got ${typeof isPremium}`
+    );
+  }
+}
+
+/**
+ * Validate PremiumStatusFetcher
+ * 
+ * @param fetcher - Fetcher to validate
+ * @throws {TypeError} If fetcher is invalid
+ */
+export function validateFetcher(fetcher: import('./types').PremiumStatusFetcher): void {
+  if (typeof fetcher !== 'object' || fetcher === null) {
+    throw new TypeError(
+      `Invalid fetcher: expected object, got ${typeof fetcher}`
+    );
+  }
+
+  if (typeof fetcher.isPremium !== 'function') {
+    throw new TypeError(
+      'Invalid fetcher: isPremium must be a function'
+    );
+  }
+}