@umituz/react-native-subscription 2.26.14 → 2.26.16

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,67 +0,0 @@
-/**
- * useCreditsGate Hook
- *
- * Single responsibility: Credits gating
- * Uses ref pattern to avoid stale closure issues.
- */
-
-import { useCallback, useRef, useEffect } from "react";
-
-declare const __DEV__: boolean;
-
-export interface UseCreditsGateParams {
-  readonly creditBalance: number;
-  readonly requiredCredits?: number;
-  readonly onCreditsRequired: (requiredCredits?: number) => void;
-}
-
-export interface UseCreditsGateResult {
-  readonly hasCredits: boolean;
-  readonly creditBalance: number;
-  readonly requireCredits: () => boolean;
-}
-
-export function useCreditsGate(
-  params: UseCreditsGateParams
-): UseCreditsGateResult {
-  const { creditBalance, requiredCredits = 1, onCreditsRequired } = params;
-
-  const creditBalanceRef = useRef(creditBalance);
-  const onCreditsRequiredRef = useRef(onCreditsRequired);
-
-  useEffect(() => {
-    creditBalanceRef.current = creditBalance;
-  }, [creditBalance]);
-
-  useEffect(() => {
-    onCreditsRequiredRef.current = onCreditsRequired;
-  }, [onCreditsRequired]);
-
-  const hasCredits = creditBalance >= requiredCredits;
-
-  const requireCredits = useCallback((): boolean => {
-    const currentBalance = creditBalanceRef.current;
-    const canAfford = currentBalance >= requiredCredits;
-
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.log("[useCreditsGate] requireCredits", {
-        currentBalance,
-        requiredCredits,
-        canAfford,
-      });
-    }
-
-    if (!canAfford) {
-      onCreditsRequiredRef.current(requiredCredits);
-      return false;
-    }
-
-    return true;
-  }, [requiredCredits]);
-
-  return {
-    hasCredits,
-    creditBalance,
-    requireCredits,
-  };
-}

package/src/presentation/hooks/useDevTestCallbacks.md

@@ -1,91 +0,0 @@
-# useDevTestCallbacks Hook
-
-**Development-only** hook for testing subscription renewal and credit operations.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useDevTestCallbacks.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Development Testing Utilities
-
-1. **Renewal Simulation**: Simulate subscription renewal with credit allocation
-2. **Credits Inspection**: Display current credit balance and purchase date
-3. **Duplicate Protection Testing**: Test that duplicate renewals are prevented
-4. **Development Mode Guard**: Only available in `__DEV__` mode
-5. **Production Safety**: Returns `undefined` in production builds
-6. **Alert-Based Feedback**: Show test results in alert dialogs
-
-### Integration Points
-
-- **useInitializeCredits**: For credit initialization testing
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-- **Development Tools**: For testing and debugging
-- **Alert API**: For displaying test results
-
-## Restrictions
-
-### REQUIRED
-
-- **Development Only**: MUST only use in `__DEV__` mode
-- **Guard Checks**: MUST check if hook returns undefined
-- **Visual Distinction**: SHOULD make dev tools visually distinct
-- **Documentation**: MUST document behavior for other developers
-
-### PROHIBITED
-
-- **NEVER** use in production code paths
-- **NEVER** ship dev UI to production
-- **DO NOT** rely on dev tools for production features
-- **DO NOT** expose dev functionality to end users
-
-### CRITICAL SAFETY
-
-- **ALWAYS** guard with `__DEV__` checks
-- **NEVER** call hook functions in production
-- **MUST** remove or disable before release
-- **ALWAYS** test that dev tools don't affect production
-
-## AI Agent Guidelines
-
-### When Implementing Development Testing
-
-1. **Always** guard with `__DEV__` checks
-2. **Always** check if hook returns undefined
-3. **Always** make dev tools visually distinct
-4. **Never** expose dev tools to production users
-5. **Always** document development-only behavior
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Guard with `__DEV__` check
-- [ ] Check if hook returns undefined
-- [ ] Make dev UI visually distinct
-- [ ] Test renewal simulation
-- [ ] Test credits inspection
-- [ ] Test duplicate protection
-- [ ] Verify undefined returned in production
-- [ ] Remove or disable before release
-
-### Common Patterns
-
-1. **Dev Test Panel**: Dedicated screen for testing
-2. **Settings Integration**: Add dev tools to settings screen
-3. **Debug Menu**: Hidden menu for testing
-4. **Flow Testing**: Test complete renewal flows
-5. **Edge Case Testing**: Test duplicate handling and errors
-
-## Related Documentation
-
-- **useCredits**: For accessing credits balance
-- **useInitializeCredits**: For credit initialization
-- **usePremiumWithCredits**: For premium + credits integration
-- **Credits README**: `src/domains/wallet/README.md`
-- **Renewal Testing Guide**: `src/docs/RENEWAL_TESTING.md`
-- **Development Tools**: `src/docs/DEV_TOOLS.md`

package/src/presentation/hooks/useDevTestCallbacks.ts

@@ -1,142 +0,0 @@
-/**
- * Dev Test Callbacks Hook
- * Provides test functions for subscription renewal testing
- * Only used in __DEV__ mode
- */
-
-import { useCallback } from "react";
-import { Alert } from "react-native";
-import { useAuth } from "@umituz/react-native-auth";
-import { getCreditsRepository } from "../../infrastructure/repositories/CreditsRepositoryProvider";
-import { useCredits } from "./useCredits";
-import type { DevTestActions } from "../screens/components/DevTestSection";
-
-export const useDevTestCallbacks = (): DevTestActions | undefined => {
-  const { user } = useAuth();
-  const { credits, refetch } = useCredits({ userId: user?.uid });
-
-  const onTestRenewal = useCallback(async () => {
-    if (!user?.uid) {
-      Alert.alert("Error", "No user logged in");
-      return;
-    }
-
-    try {
-      const repository = getCreditsRepository();
-      const renewalId = `dev_renewal_${Date.now()}`;
-      const productId = "test_yearly_subscription";
-
-      if (__DEV__) {
-        console.log("🧪 [Dev Test] Simulating auto-renewal...", {
-          userId: user.uid,
-          renewalId,
-        });
-      }
-
-      const result = await repository.initializeCredits(
-        user.uid,
-        renewalId,
-        productId,
-      );
-
-      if (__DEV__) {
-        console.log("✅ [Dev Test] Renewal completed:", {
-          success: result.success,
-          credits: result.data?.credits,
-        });
-      }
-
-      await refetch();
-
-      Alert.alert(
-        "✅ Test Renewal Success",
-        `Credits Updated!\n\nNew Balance: ${result.data?.credits || 0}\n\n(ACCUMULATE mode - credits added to existing)`,
-        [{ text: "OK" }],
-      );
-    } catch (error) {
-      if (__DEV__) {
-        console.error("❌ [Dev Test] Renewal failed:", error);
-      }
-      Alert.alert(
-        "Test Failed",
-        error instanceof Error ? error.message : "Unknown error",
-      );
-    }
-  }, [user?.uid, refetch]);
-
-  const onCheckCredits = useCallback(() => {
-    if (!credits) {
-      Alert.alert("Credits", "No credits data available");
-      return;
-    }
-
-    Alert.alert(
-      "📊 Current Credits",
-      `Credits: ${credits.credits}\n\nPurchased: ${credits.purchasedAt?.toLocaleDateString() || "N/A"}`,
-      [{ text: "OK" }],
-    );
-  }, [credits]);
-
-  const onTestDuplicate = useCallback(async () => {
-    if (!user?.uid) {
-      Alert.alert("Error", "No user logged in");
-      return;
-    }
-
-    try {
-      const repository = getCreditsRepository();
-      const sameRenewalId = "dev_duplicate_test_12345";
-
-      if (__DEV__) {
-        console.log("🧪 [Dev Test] Testing duplicate protection...");
-      }
-
-      const result1 = await repository.initializeCredits(
-        user.uid,
-        sameRenewalId,
-        "test_product",
-      );
-      if (__DEV__) {
-        console.log("First call:", result1.data);
-      }
-
-      const result2 = await repository.initializeCredits(
-        user.uid,
-        sameRenewalId,
-        "test_product",
-      );
-      if (__DEV__) {
-        console.log("Second call:", result2.data);
-      }
-
-      await refetch();
-
-      const duplicateProtectionWorks =
-        result2.data?.credits === result1.data?.credits;
-
-      Alert.alert(
-        "Duplicate Test",
-        `First call: ${result1.success ? "✅ Added credits" : "❌ Failed"}\n\nSecond call: ${duplicateProtectionWorks ? "✅ Skipped (protection works!)" : "❌ Added again (protection failed!)"}`,
-        [{ text: "OK" }],
-      );
-    } catch (error) {
-      if (__DEV__) {
-        console.error("❌ [Dev Test] Duplicate test failed:", error);
-      }
-      Alert.alert(
-        "Test Failed",
-        error instanceof Error ? error.message : "Unknown error",
-      );
-    }
-  }, [user?.uid, refetch]);
-
-  if (!__DEV__) {
-    return undefined;
-  }
-
-  return {
-    onTestRenewal,
-    onCheckCredits,
-    onTestDuplicate,
-  };
-};