@umituz/react-native-subscription 2.26.13 → 2.26.15

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,
-  };
-};

package/src/presentation/hooks/useInitializeCredits.md

@@ -1,92 +0,0 @@
-# useInitializeCredits Hook
-
-TanStack Query mutation hook for initializing credits after purchase.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useInitializeCredits.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Credit Initialization Flow
-
-1. **User Validation**: Verify user is authenticated before initialization
-2. **Repository Call**: Call credits repository to initialize credits
-3. **Duplicate Protection**: Repository prevents duplicate initialization with same purchase ID
-4. **Loading State**: Track initialization progress with isInitializing flag
-5. **Error Handling**: Handle and report initialization failures
-6. **Success Tracking**: Return success boolean for caller to handle
-
-### Integration Points
-
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
-- **TanStack Query**: For mutation and optimistic updates
-- **Purchase Flow**: Called after successful subscription purchase
-
-## Restrictions
-
-### REQUIRED
-
-- **User ID**: MUST provide valid userId parameter
-- **Authentication**: User MUST be authenticated
-- **Error Handling**: MUST handle initialization failures
-- **Loading State**: MUST show loading indicator during initialization
-
-### PROHIBITED
-
-- **NEVER** initialize credits without valid userId
-- **NEVER** call for unauthenticated users
-- **DO NOT** assume successful initialization (check return value)
-- **DO NOT** call excessively (repository handles duplicates)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** validate userId before initialization
-- **MUST** handle errors gracefully
-- **ALWAYS** check return value
-- **NEVER** rely on side effects without checking success
-
-## AI Agent Guidelines
-
-### When Implementing Credit Initialization
-
-1. **Always** validate userId before calling initializeCredits
-2. **Always** handle loading state
-3. **Always** check return value
-4. **Always** provide purchaseId and productId when available
-5. **Never** initialize credits for unauthenticated users
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Validate userId is not undefined
-- [ ] Handle isInitializing state
-- [ ] Check return value from initializeCredits
-- [ ] Provide purchaseId when available
-- [ ] Provide productId when available
-- [ ] Test with premium user (no existing credits)
-- [ ] Test with premium user (existing credits)
-- [ ] Test duplicate protection
-- [ ] Test error scenarios
-
-### Common Patterns
-
-1. **Post-Purchase Init**: Initialize after successful purchase
-2. **Auto-Init for Premium**: Automatically initialize for premium users without credits
-3. **Product-Specific Allocation**: Different products provide different credit amounts
-4. **Retry Logic**: Implement retry mechanism on failure
-5. **Admin Init**: Manual initialization for admin users
-
-## Related Documentation
-
-- **useCredits**: For accessing credits balance
-- **useDeductCredit**: For deducting credits
-- **usePremiumWithCredits**: For premium + credits integration
-- **useDevTestCallbacks**: For testing credit initialization
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
-- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useInitializeCredits.ts

@@ -1,57 +0,0 @@
-/**
- * useInitializeCredits Hook
- * TanStack Query mutation hook for initializing credits after purchase.
- */
-
-import { useCallback } from "react";
-import { useMutation, useQueryClient } from "@umituz/react-native-design-system";
-import { getCreditsRepository } from "../../infrastructure/repositories/CreditsRepositoryProvider";
-import { creditsQueryKeys } from "./useCredits";
-
-declare const __DEV__: boolean;
-
-export interface UseInitializeCreditsParams {
-  userId: string | undefined;
-}
-
-export interface InitializeCreditsOptions {
-  purchaseId?: string;
-  productId?: string;
-}
-
-export interface UseInitializeCreditsResult {
-  initializeCredits: (options?: InitializeCreditsOptions) => Promise<boolean>;
-  isInitializing: boolean;
-}
-
-export const useInitializeCredits = ({
-  userId,
-}: UseInitializeCreditsParams): UseInitializeCreditsResult => {
-  const repository = getCreditsRepository();
-  const queryClient = useQueryClient();
-
-  const mutation = useMutation({
-    mutationFn: async (options?: InitializeCreditsOptions) => {
-      if (!userId) throw new Error("User not authenticated");
-      if (__DEV__) console.log("[useInitializeCredits] Initializing:", { userId, ...options });
-      return repository.initializeCredits(userId, options?.purchaseId, options?.productId);
-    },
-    onSuccess: (result) => {
-      if (userId && result.success && result.data) {
-        if (__DEV__) console.log("[useInitializeCredits] Success:", result.data);
-        queryClient.setQueryData(creditsQueryKeys.user(userId), result.data);
-        queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
-      }
-    },
-    onError: (error) => { if (__DEV__) console.error("[useInitializeCredits] Error:", error); },
-  });
-
-  const initializeCredits = useCallback(async (opts?: InitializeCreditsOptions): Promise<boolean> => {
-    try {
-      const res = await mutation.mutateAsync(opts);
-      return res.success;
-    } catch { return false; }
-  }, [mutation]);
-
-  return { initializeCredits, isInitializing: mutation.isPending };
-};

package/src/presentation/hooks/usePremiumGate.md

@@ -1,88 +0,0 @@
-# usePremiumGate Hook
-
-Feature gating hook for premium-only features with optional authentication.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePremiumGate.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Premium Gating Flow
-
-1. **Premium Check**: Verify if user has premium access
-2. **Auth Check**: Optionally verify authentication status
-3. **Gate Functions**: Provide requirePremium, requireAuth, requirePremiumWithAuth
-4. **Access Control**: Simple booleans for conditional rendering (canAccess, canAccessWithAuth)
-5. **Callback Triggers**: Execute appropriate callback when requirements not met
-
-### Integration Points
-
-- **usePremium**: For premium status check
-- **useAuth**: For authentication status
-- **Paywall Domain**: For premium upgrade flow
-- **Auth UI**: For authentication flow
-
-## Restrictions
-
-### REQUIRED
-
-- **Premium Status**: MUST provide isPremium parameter
-- **Callback**: MUST implement onPremiumRequired callback
-- **Access Check**: MUST verify canAccess before showing premium content
-
-### PROHIBITED
-
-- **NEVER** show premium content without checking isPremium
-- **NEVER** use for security decisions without server validation
-- **DO NOT** assume premium status (always verify)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** verify canAccess before showing premium features
-- **NEVER** trust client-side state for security
-- **MUST** implement proper upgrade flow
-- **ALWAYS** handle authentication when required
-
-## AI Agent Guidelines
-
-### When Implementing Premium Gates
-
-1. **Always** check canAccess before showing premium content
-2. **Always** provide clear upgrade path in callback
-3. **Always** use requirePremium for action gating
-4. **Always** handle authentication when using requirePremiumWithAuth
-5. **Never** bypass premium checks
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Provide isPremium from usePremium
-- [ ] Implement onPremiumRequired callback
-- [ ] Optionally provide auth status and callback
-- [ ] Use requirePremium for action gating
-- [ ] Check canAccess for conditional rendering
-- [ ] Test with premium user
-- [ ] Test with non-premium user
-- [ ] Test with authenticated user
-- [ ] Test with unauthenticated user
-
-### Common Patterns
-
-1. **Premium Only**: Gate features behind premium only
-2. **Auth + Premium**: Require both authentication and premium
-3. **Conditional Rendering**: Check canAccess for UI
-4. **Button States**: Disable buttons when not premium
-5. **Upgrade Prompts**: Show in callback when not premium
-
-## Related Documentation
-
-- **usePremium**: Premium status check
-- **useAuthGate**: Auth + subscription gating
-- **useSubscriptionGate**: Subscription-only gating
-- **useFeatureGate**: Unified feature gating
-- **Paywall Domain**: `src/domains/paywall/README.md`

package/src/presentation/hooks/usePremiumGate.ts

@@ -1,116 +0,0 @@
-/**
- * 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/usePremiumWithCredits.md

@@ -1,92 +0,0 @@
-# usePremiumWithCredits Hook
-
-Combined hook for premium subscription with credits system integration.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePremiumWithCredits.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Premium + Credits Integration
-
-1. **Credits Access**: Provide all credits data from useCredits hook
-2. **Auto-Initialization**: Automatically initialize credits when user becomes premium
-3. **Premium Check**: Monitor isPremium status to trigger initialization
-4. **Duplicate Prevention**: Skip initialization if credits already exist
-5. **Loading Management**: Handle loading state during initialization
-6. **Error Handling**: Handle initialization failures gracefully
-
-### Integration Points
-
-- **useCredits**: For credits balance and transactions
-- **usePremium**: For premium status check
-- **useInitializeCredits**: For credit initialization
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-
-## Restrictions
-
-### REQUIRED
-
-- **User ID**: MUST provide valid userId parameter
-- **Premium Status**: MUST provide isPremium parameter
-- **Loading State**: MUST handle loading state
-- **Error Handling**: MUST handle initialization errors
-
-### PROHIBITED
-
-- **NEVER** call without valid userId
-- **NEVER** call without isPremium parameter
-- **DO NOT** manually manage credits state (use hook values)
-- **DO NOT** call ensureCreditsInitialized excessively
-
-### CRITICAL SAFETY
-
-- **ALWAYS** validate userId before use
-- **MUST** handle loading state during initialization
-- **ALWAYS** check isPremium before showing premium features
-- **NEVER** trust client-side state for security
-
-## AI Agent Guidelines
-
-### When Implementing Premium + Credits
-
-1. **Always** provide valid userId
-2. **Always** provide isPremium status
-3. **Always** handle loading state
-4. **Always** call ensureCreditsInitialized for premium users
-5. **Never** manually initialize credits without checking isPremium
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Provide valid userId
-- [ ] Provide isPremium from usePremium
-- [ ] Handle loading state
-- [ ] Call ensureCreditsInitialized when isPremium is true
-- [ ] Test with premium user (no credits)
-- [ ] Test with premium user (has credits)
-- [ ] Test with free user
-- [ ] Test subscription upgrade flow
-- [ ] Test error scenarios
-
-### Common Patterns
-
-1. **Auto-Initialization**: Automatically initialize credits for premium users
-2. **Subscription Change Detection**: Detect when user subscribes
-3. **Premium Benefits Display**: Show credits along with premium status
-4. **Subscription Monitor**: Refresh status periodically
-5. **Manual Init**: Provide button for manual initialization
-
-## Related Documentation
-
-- **useCredits**: Credits management
-- **useInitializeCredits**: Manual credit initialization
-- **usePremium**: Premium status
-- **useDeductCredit**: Credit deduction
-- **Credits System**: `src/domains/wallet/README.md`
-- **Premium Integration**: `src/docs/PREMIUM_INTEGRATION.md`