@umituz/react-native-subscription 2.26.13 → 2.26.15

package/src/presentation/hooks/useAuthAwarePurchase.md

@@ -1,92 +0,0 @@
-# useAuthAwarePurchase Hook
-
-Security-focused purchase hook that requires authentication before any transaction.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useAuthAwarePurchase.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Auth-Gated Purchase Flow
-
-1. **Auth Provider Validation**: Verify auth provider is configured at app startup
-2. **Authentication Check**: Block purchases for unauthenticated users
-3. **Auth Flow Trigger**: Show auth modal when guest attempts purchase
-4. **Purchase Blocking**: Prevent all transactions without valid authentication
-5. **Post-Auth Purchase**: Allow purchase after user completes authentication
-6. **Security Enforcement**: Server-side validation required for final verification
-
-### Integration Points
-
-- **Auth Provider Configuration**: Must be configured once at app initialization
-- **Auth Context**: User authentication state
-- **Paywall Domain**: For subscription upgrade flow
-- **Auth UI**: For sign-in/sign-up flows
-- **RevenueCat**: For purchase transactions
-
-## Restrictions
-
-### REQUIRED
-
-- **Auth Provider Configuration**: MUST call `configureAuthProvider()` once at app startup
-- **isAuthenticated Function**: MUST provide function to check auth status
-- **showAuthModal Function**: MUST provide function to show auth UI
-- **Error Handling**: MUST handle purchase failures appropriately
-
-### PROHIBITED
-
-- **NEVER** use without configuring auth provider first
-- **NEVER** bypass auth checks for convenience
-- **NEVER** allow anonymous/guest purchases
-- **DO NOT** call handlePurchase/handleRestore without auth provider setup
-
-### CRITICAL SAFETY
-
-- **ALWAYS** configure auth provider at app initialization
-- **NEVER** allow purchases for anonymous users
-- **MUST** implement proper auth flow with pending purchase preservation
-- **ALWAYS** verify auth status in production
-
-## AI Agent Guidelines
-
-### When Implementing Auth-Gated Purchases
-
-1. **Always** configure auth provider at app startup
-2. **Always** implement isAuthenticated function
-3. **Always** implement showAuthModal function
-4. **Never** bypass auth checks
-5. **Always** test purchase flow with authenticated and unauthenticated users
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Call `configureAuthProvider()` once at app startup
-- [ ] Provide `isAuthenticated()` function
-- [ ] Provide `showAuthModal()` function
-- [ ] Test purchase flow with authenticated user
-- [ ] Test purchase flow with unauthenticated user
-- [ ] Verify auth modal appears for guests
-- [ ] Verify purchase proceeds after authentication
-- [ ] Check development logs for auth verification
-- [ ] Verify purchases are blocked without auth provider
-
-### Common Patterns
-
-1. **App-Level Config**: Configure once in root App component
-2. **Pending Purchase**: Store package for post-auth completion
-3. **Auth Integration**: Use with Firebase, Auth0, or custom auth
-4. **Error Handling**: Handle auth failures and purchase failures
-5. **Development Testing**: Use dev logs to verify auth checks
-
-## Related Documentation
-
-- **usePremium**: For purchase and restore operations
-- **usePaywallOperations**: For complete paywall purchase handling
-- **useAuthGate**: For authentication gating
-- **useAuthSubscriptionSync**: For syncing auth with subscription
-- **Security Best Practices**: `src/docs/SECURITY.md`

package/src/presentation/hooks/useAuthAwarePurchase.ts

@@ -1,138 +0,0 @@
-/**
- * Auth-Aware Purchase Hook
- * Handles purchase flow with authentication requirement
- */
-
-import { useCallback } from "react";
-import type { PurchasesPackage } from "react-native-purchases";
-import { usePremium } from "./usePremium";
-import type { PurchaseSource } from "../../domain/entities/Credits";
-
-declare const __DEV__: boolean;
-
-export interface PurchaseAuthProvider {
-  isAuthenticated: () => boolean;
-  showAuthModal: () => void;
-}
-
-let globalAuthProvider: PurchaseAuthProvider | null = null;
-let savedPackage: PurchasesPackage | null = null;
-let savedSource: PurchaseSource | null = null;
-
-export const configureAuthProvider = (provider: PurchaseAuthProvider): void => {
-  globalAuthProvider = provider;
-};
-
-export const getSavedPurchase = (): { pkg: PurchasesPackage; source: PurchaseSource } | null => {
-  if (savedPackage && savedSource) {
-    return { pkg: savedPackage, source: savedSource };
-  }
-  return null;
-};
-
-export const clearSavedPurchase = (): void => {
-  savedPackage = null;
-  savedSource = null;
-};
-
-export interface UseAuthAwarePurchaseParams {
-  source?: PurchaseSource;
-  userId?: string;
-}
-
-export interface UseAuthAwarePurchaseResult {
-  handlePurchase: (pkg: PurchasesPackage, source?: PurchaseSource) => Promise<boolean>;
-  handleRestore: () => Promise<boolean>;
-  executeSavedPurchase: () => Promise<boolean>;
-}
-
-export const useAuthAwarePurchase = (
-  params?: UseAuthAwarePurchaseParams
-): UseAuthAwarePurchaseResult => {
-  const { purchasePackage, restorePurchase } = usePremium(params?.userId);
-
-  const handlePurchase = useCallback(
-    async (pkg: PurchasesPackage, source?: PurchaseSource): Promise<boolean> => {
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] handlePurchase called:", {
-          productId: pkg.product.identifier,
-          hasAuthProvider: !!globalAuthProvider,
-        });
-      }
-
-      if (!globalAuthProvider) {
-        if (__DEV__) {
-          console.error("[useAuthAwarePurchase] Auth provider not configured");
-        }
-        return false;
-      }
-
-      const isAuth = globalAuthProvider.isAuthenticated();
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] Auth check:", { isAuthenticated: isAuth });
-      }
-
-      if (!isAuth) {
-        if (__DEV__) {
-          console.log("[useAuthAwarePurchase] Not authenticated, saving and showing auth");
-        }
-        savedPackage = pkg;
-        savedSource = source || params?.source || "settings";
-        globalAuthProvider.showAuthModal();
-        return false;
-      }
-
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] Calling purchasePackage");
-      }
-      const result = await purchasePackage(pkg);
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] purchasePackage returned:", result);
-      }
-      return result;
-    },
-    [purchasePackage, params?.source]
-  );
-
-  const handleRestore = useCallback(async (): Promise<boolean> => {
-    if (!globalAuthProvider) {
-      if (__DEV__) {
-        console.error("[useAuthAwarePurchase] Auth provider not configured");
-      }
-      return false;
-    }
-
-    if (!globalAuthProvider.isAuthenticated()) {
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] Not authenticated for restore");
-      }
-      globalAuthProvider.showAuthModal();
-      return false;
-    }
-
-    return restorePurchase();
-  }, [restorePurchase]);
-
-  const executeSavedPurchase = useCallback(async (): Promise<boolean> => {
-    const saved = getSavedPurchase();
-    if (!saved) {
-      if (__DEV__) {
-        console.log("[useAuthAwarePurchase] No saved purchase to execute");
-      }
-      return false;
-    }
-
-    if (__DEV__) {
-      console.log("[useAuthAwarePurchase] Executing saved purchase:", saved.pkg.product.identifier);
-    }
-
-    clearSavedPurchase();
-    return purchasePackage(saved.pkg);
-  }, [purchasePackage]);
-
-  return {
-    handlePurchase,
-    handleRestore,
-    executeSavedPurchase,
-  };
-};

package/src/presentation/hooks/useAuthGate.md

@@ -1,89 +0,0 @@
-# useAuthGate Hook
-
-Hook for combining authentication and subscription gating.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useAuthGate.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Auth Gate Flow
-
-1. **Authentication Check**: Verify if user is authenticated
-2. **Subscription Check**: Verify if user has required subscription
-3. **Authorization Evaluation**: Combine auth + subscription status
-4. **Gate Actions**: Provide functions to gate features
-5. **Sign In Flow**: Trigger authentication when required
-6. **Upgrade Flow**: Trigger subscription when required
-
-### Integration Points
-
-- **Auth Context**: User authentication state
-- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
-- **Paywall Domain**: For subscription upgrade flow
-- **Auth UI**: For sign-in/sign-up flows
-
-## Restrictions
-
-### REQUIRED
-
-- **Loading State**: MUST handle loading state
-- **Authorization Check**: MUST verify isAuthorized before showing protected content
-- **Callback Implementation**: MUST implement onAuthRequired/onSubscriptionRequired callbacks
-
-### PROHIBITED
-
-- **NEVER** show protected content without checking isAuthorized
-- **NEVER** use for security decisions without server validation
-- **DO NOT** assume user is authenticated or subscribed
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check isAuthorized before showing protected features
-- **NEVER** trust client-side state for security
-- **MUST** implement proper auth flow
-- **ALWAYS** handle all states (loading, authorized, unauthorized)
-
-## AI Agent Guidelines
-
-### When Implementing Auth Gates
-
-1. **Always** check loading state first
-2. **Always** verify isAuthorized before showing content
-3. **Always** provide sign-in option for unauthenticated users
-4. **Always** provide upgrade option for non-subscribed users
-5. **Never** bypass auth checks for convenience
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Configure requireAuth and requireSubscription
-- [ ] Handle loading state
-- [ ] Check isAuthorized before showing content
-- [ ] Implement sign-in callback
-- [ ] Implement subscription upgrade callback
-- [ ] Test with unauthenticated user
-- [ ] Test with authenticated non-subscribed user
-- [ ] Test with authenticated subscribed user
-- [ ] Test loading states
-
-### Common Patterns
-
-1. **Auth Only**: Require authentication only
-2. **Subscription Only**: Require subscription only (auth handled internally)
-3. **Both**: Require both auth and subscription
-4. **Conditional Gates**: Different requirements per feature
-5. **Nested Gates**: Layer multiple gate conditions
-
-## Related Documentation
-
-- **useAuth**: Authentication state
-- **usePremiumGate**: Premium-only gating
-- **useSubscriptionGate**: Subscription-only gating
-- **useFeatureGate**: Unified feature gating
-- **Auth Domain**: `src/domains/config/README.md`

package/src/presentation/hooks/useAuthGate.ts

@@ -1,65 +0,0 @@
-/**
- * useAuthGate Hook
- *
- * Single responsibility: Authentication gating
- * Checks if user is authenticated before allowing actions.
- *
- * @example
- * ```typescript
- * const { requireAuth, isAuthenticated } = useAuthGate({
- *   isAuthenticated: !!user && !user.isAnonymous,
- *   onAuthRequired: (callback) => showAuthModal(callback),
- * });
- *
- * const handleAction = () => {
- *   requireAuth(() => doSomething());
- * };
- * ```
- */
-
-import { useCallback } from "react";
-
-declare const __DEV__: boolean;
-
-export interface UseAuthGateParams {
-  /** Whether user is authenticated (not guest/anonymous) */
-  isAuthenticated: boolean;
-  /** Callback when auth is required - receives pending action callback */
-  onAuthRequired: (pendingCallback: () => void | Promise<void>) => void;
-}
-
-export interface UseAuthGateResult {
-  /** Whether user is authenticated */
-  isAuthenticated: boolean;
-  /** Gate action behind auth - executes if authenticated, else shows auth modal */
-  requireAuth: (action: () => void | Promise<void>) => boolean;
-}
-
-export function useAuthGate(params: UseAuthGateParams): UseAuthGateResult {
-  const { isAuthenticated, onAuthRequired } = params;
-
-  const requireAuth = useCallback(
-    (action: () => void | Promise<void>): boolean => {
-      if (!isAuthenticated) {
-        if (__DEV__) {
-           
-          console.log("[useAuthGate] Not authenticated, showing auth modal");
-        }
-        onAuthRequired(action);
-        return false;
-      }
-
-      if (__DEV__) {
-         
-        console.log("[useAuthGate] Authenticated, proceeding");
-      }
-      return true;
-    },
-    [isAuthenticated, onAuthRequired]
-  );
-
-  return {
-    isAuthenticated,
-    requireAuth,
-  };
-}

package/src/presentation/hooks/useCreditChecker.md

@@ -1,102 +0,0 @@
-# useCreditChecker Hook
-
-Simple hook for checking if user has sufficient credits before operations.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useCreditChecker.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Credit Validation Flow
-
-1. **Initial Check**
-   - Compare current balance against required amount
-   - Return boolean result immediately
-   - No network calls required (uses cached balance)
-
-2. **Real-time Updates**
-   - Automatically re-checks when credits change
-   - Updates result via `useCredits` hook
-   - Triggers re-renders on balance changes
-
-3. **Manual Refresh**
-   - Optionally trigger manual credit check
-   - Useful before expensive operations
-   - Validates current state before action
-
-### Integration Points
-
-- **useCredits**: For fetching current credit balance
-- **useDeductCredit**: For deducting credits after check
-- **Credit Checking UI**: Pre-action validation displays
-- **Purchase Flows**: Redirect to credit packages
-
-## Restrictions
-
-### REQUIRED
-
-- **Required Amount**: MUST specify positive credit cost
-- **Balance Check**: MUST verify `hasEnoughCredits` before action
-- **User Feedback**: MUST show credit cost to user
-
-### PROHIBITED
-
-- **NEVER** assume credits are sufficient without checking
-- **NEVER** use for security decisions (server-side validation required)
-- **DO NOT** deduct credits with this hook (use `useDeductCredit`)
-- **NEVER** hardcode credit costs (should be configurable)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check return value before proceeding with action
-- **ALWAYS** show credit cost to user before execution
-- **NEVER** trust client-side check for security (server must validate)
-- **MUST** handle case where credits become insufficient between check and action
-
-## AI Agent Guidelines
-
-### When Implementing Credit Checks
-
-1. **Always** specify positive credit cost
-2. **Always** check `hasEnoughCredits` before action
-3. **Always** show credit cost to user in UI
-4. **Always** provide upgrade path when insufficient
-5. **Never** use for security decisions (server validation required)
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Specify positive credit cost
-- [ ] Check `hasEnoughCredits` before action
-- [ ] Display credit cost to user
-- [ ] Show upgrade/purchase option when insufficient
-- [ ] Validate credit cost is positive number
-- [ ] Test with sufficient credits
-- [ ] Test with insufficient credits
-- [ ] Test with zero credits
-- [ ] Test credit changes between check and action
-
-### Common Patterns to Implement
-
-1. **Pre-action Validation**: Check before showing button
-2. **Cost Display**: Always show credit cost to user
-3. **Upgrade Prompts**: Link to credit packages when low
-4. **Manual Refresh**: Check again before expensive operations
-5. **Credit Deduction**: Use with `useDeductCredit` for complete flow
-6. **Visual Feedback**: Disable buttons when insufficient
-7. **Warning Messages**: Alert user before high-cost operations
-8. **Balance Display**: Show current balance alongside cost
-
-## Related Documentation
-
-- **useCredits**: Access current credit balance
-- **useDeductCredit**: Deduct credits after check passes
-- **useCreditsGate**: Complete credit gating with deduction
-- **useFeatureGate**: Unified feature gating with credits
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
-- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useCreditChecker.ts

@@ -1,41 +0,0 @@
-/**
- * useCreditChecker Hook
- *
- * Provides credit checking utilities using module-level repository.
- */
-
-import { useMemo } from "react";
-import { getCreditsRepository } from "../../infrastructure/repositories/CreditsRepositoryProvider";
-import {
-    createCreditChecker,
-    type CreditCheckResult,
-} from "../../utils/creditChecker";
-
-export interface UseCreditCheckerParams {
-  onCreditDeducted?: (userId: string, cost: number) => void;
-}
-
-export interface UseCreditCheckerResult {
-  checkCreditsAvailable: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<CreditCheckResult>;
-  deductCreditsAfterSuccess: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<void>;
-}
-
-export const useCreditChecker = (
-  params?: UseCreditCheckerParams
-): UseCreditCheckerResult => {
-  const repository = getCreditsRepository();
-  const onCreditDeducted = params?.onCreditDeducted;
-
-  const checker = useMemo(
-    () => createCreditChecker({ repository, onCreditDeducted }),
-    [repository, onCreditDeducted]
-  );
-
-  return checker;
-};

package/src/presentation/hooks/useCreditsGate.md

@@ -1,94 +0,0 @@
-# useCreditsGate Hook
-
-Hook for gating features behind credit requirements.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useCreditsGate.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Credit Gating Flow
-
-1. **Credit Check**: Verify user has sufficient credits for feature
-2. **Balance Display**: Show current credit balance to user
-3. **Feature Access Control**: Enable/disable features based on credit availability
-4. **Consumption**: Deduct credits when feature is used
-5. **Purchase Prompt**: Guide users to purchase when insufficient
-6. **Transaction Tracking**: Record all credit transactions
-
-### Integration Points
-
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
-- **TanStack Query**: For optimistic updates and caching
-- **Paywall Domain**: For purchase flow integration
-
-## Restrictions
-
-### REQUIRED
-
-- **Credit Cost**: MUST specify credit cost for feature
-- **Feature ID**: MUST provide unique feature identifier
-- **Balance Check**: MUST verify hasCredits before allowing action
-- **Error Handling**: MUST handle consumption failures
-
-### PROHIBITED
-
-- **NEVER** allow feature access when hasCredits is false
-- **NEVER** consume credits without checking balance first
-- **NEVER** assume credits will be sufficient (always check)
-- **DO NOT** use for security decisions without server validation
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check return value from consumeCredit
-- **NEVER** allow negative credit balance
-- **MUST** handle insufficient credits gracefully
-- **ALWAYS** show credit cost to user before action
-
-## AI Agent Guidelines
-
-### When Implementing Credit Gates
-
-1. **Always** display credit cost to user before action
-2. **Always** check hasCredits before enabling buttons
-3. **Always** handle consumeCredit result
-4. **Never** allow action when credits are insufficient
-5. **Always** provide purchase path for credits
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Specify credit cost in config
-- [ ] Provide unique feature ID
-- [ ] Check hasCredits before enabling feature
-- [ ] Handle consumeCredit result
-- [ ] Show credit cost in UI
-- [ ] Display current balance
-- [ ] Implement purchase prompt for insufficient credits
-- [ ] Test with zero balance
-- [ ] Test with insufficient credits
-- [ ] Test with sufficient credits
-
-### Common Patterns
-
-1. **Pre-check**: Verify balance before showing feature
-2. **Confirmation**: Ask user before expensive operations
-3. **Success Feedback**: Show message after successful consumption
-4. **Failure Handling**: Display appropriate error on failure
-5. **Purchase Flow**: Navigate to purchase screen on exhaustion
-
-## Related Documentation
-
-- **useCredits**: Access current credit balance
-- **useDeductCredit**: Manual credit deduction with optimistic updates
-- **useCreditChecker**: Simple credit validation
-- **usePremiumWithCredits**: Hybrid premium/credits access
-- **useFeatureGate**: Unified feature gating
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
-- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useCreditsGate.ts

@@ -1,81 +0,0 @@
-/**
- * useCreditsGate Hook
- *
- * Single responsibility: Credits gating
- * Checks if user has enough credits before allowing actions.
- *
- * @example
- * ```typescript
- * const { requireCredits, hasCredits } = useCreditsGate({
- *   hasCredits: canAfford(cost),
- *   creditBalance: credits,
- *   requiredCredits: cost,
- *   onCreditsRequired: (required) => showPaywall(required),
- * });
- *
- * const handleGenerate = () => {
- *   requireCredits(() => generate());
- * };
- * ```
- */
-
-import { useCallback } from "react";
-
-export interface UseCreditsGateParams {
-  /** Whether user has enough credits for the action */
-  hasCredits: boolean;
-  /** Current credit balance */
-  creditBalance: number;
-  /** Credits required for this action (optional, for display) */
-  requiredCredits?: number;
-  /** Callback when credits are required - receives required amount */
-  onCreditsRequired: (requiredCredits?: number) => void;
-}
-
-export interface UseCreditsGateResult {
-  /** Whether user has enough credits */
-  hasCredits: boolean;
-  /** Current credit balance */
-  creditBalance: number;
-  /** Gate action behind credits - executes if has credits, else shows paywall */
-  requireCredits: (action: () => void | Promise<void>) => boolean;
-}
-
-declare const __DEV__: boolean;
-
-export function useCreditsGate(
-  params: UseCreditsGateParams
-): UseCreditsGateResult {
-  const { hasCredits, creditBalance, requiredCredits, onCreditsRequired } =
-    params;
-
-  const requireCredits = useCallback(
-    (_action: () => void | Promise<void>): boolean => {
-      if (typeof __DEV__ !== "undefined" && __DEV__) {
-        console.log("[useCreditsGate] requireCredits called", {
-          hasCredits,
-          creditBalance,
-          requiredCredits,
-        });
-      }
-      if (!hasCredits) {
-        if (typeof __DEV__ !== "undefined" && __DEV__) {
-          console.log("[useCreditsGate] No credits, showing paywall");
-        }
-        onCreditsRequired(requiredCredits);
-        return false;
-      }
-      if (typeof __DEV__ !== "undefined" && __DEV__) {
-        console.log("[useCreditsGate] Has credits, allowing action");
-      }
-      return true;
-    },
-    [hasCredits, creditBalance, requiredCredits, onCreditsRequired]
-  );
-
-  return {
-    hasCredits,
-    creditBalance,
-    requireCredits,
-  };
-}