@umituz/react-native-subscription 2.26.14 → 2.26.16

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`

package/src/presentation/hooks/usePremiumWithCredits.ts

@@ -1,48 +0,0 @@
-/**
- * usePremiumWithCredits Hook
- *
- * Combined hook for premium subscription with credits system.
- * Ensures premium users always have credits initialized.
- */
-
-import { useEffect, useCallback } from "react";
-import { useCredits, type UseCreditsResult } from "./useCredits";
-import { useInitializeCredits } from "./useInitializeCredits";
-
-export interface UsePremiumWithCreditsParams {
-  userId: string | undefined;
-  isPremium: boolean;
-}
-
-export interface UsePremiumWithCreditsResult extends UseCreditsResult {
-  ensureCreditsInitialized: () => Promise<void>;
-}
-
-export const usePremiumWithCredits = ({
-  userId,
-  isPremium,
-}: UsePremiumWithCreditsParams): UsePremiumWithCreditsResult => {
-  const creditsResult = useCredits({ userId });
-  const { initializeCredits, isInitializing } = useInitializeCredits({
-    userId,
-  });
-
-  const ensureCreditsInitialized = useCallback(async () => {
-    if (!userId || !isPremium) return;
-    if (creditsResult.credits) return;
-    if (isInitializing) return;
-
-    await initializeCredits();
-  }, [userId, isPremium, creditsResult.credits, isInitializing, initializeCredits]);
-
-  useEffect(() => {
-    if (isPremium && userId && !creditsResult.credits && !creditsResult.isLoading) {
-      ensureCreditsInitialized();
-    }
-  }, [isPremium, userId, creditsResult.credits, creditsResult.isLoading, ensureCreditsInitialized]);
-
-  return {
-    ...creditsResult,
-    ensureCreditsInitialized,
-  };
-};

package/src/presentation/hooks/useSubscription.md

@@ -1,94 +0,0 @@
-# useSubscription Hook
-
-Core hook for subscription status management and operations.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useSubscription.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Subscription Management Flow
-
-1. **Status Retrieval**: Fetch current subscription status from repository
-2. **State Caching**: Cache status for 5 minutes using TanStack Query
-3. **Real-time Updates**: Auto-refresh when user auth state changes
-4. **Manual Operations**: Provide functions for manual activation/deactivation
-5. **Loading States**: Handle loading and error states properly
-6. **Refresh Mechanisms**: Support both load and refresh operations
-
-### Integration Points
-
-- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
-- **TanStack Query**: For caching and background updates
-- **Auth Context**: Sync with user authentication state
-- **RevenueCat**: For subscription data source
-
-## Restrictions
-
-### REQUIRED
-
-- **User ID**: MUST provide valid userId for operations
-- **Loading State**: MUST handle loading state in UI
-- **Error Handling**: MUST handle error state
-- **Status Check**: MUST verify isPremium before showing premium features
-
-### PROHIBITED
-
-- **NEVER** assume instant data availability (always check loading state)
-- **NEVER** use for security decisions without server validation
-- **DO NOT** call loadStatus/refreshStatus without userId
-- **DO NOT** activate/deactivate subscriptions without proper validation
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check loading state before accessing status
-- **NEVER** trust client-side state for security enforcement
-- **MUST** validate userId before all operations
-- **ALWAYS** handle errors gracefully
-
-## AI Agent Guidelines
-
-### When Implementing Subscription Features
-
-1. **Always** check loading state before rendering subscription data
-2. **Always** handle error state
-3. **Always** verify isPremium before showing premium features
-4. **Always** validate userId before operations
-5. **Never** use for security decisions without server validation
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Handle loading state
-- [ ] Handle error state
-- [ ] Check isPremium before rendering premium content
-- [ ] Validate userId before operations
-- [ ] Implement refresh mechanism
-- [ ] Test with premium user
-- [ ] Test with free user
-- [ ] Test with guest user
-- [ ] Test offline scenario
-
-### Common Patterns
-
-1. **Status Display**: Show current subscription status
-2. **Conditional Rendering**: Show/hide features based on isPremium
-3. **Manual Refresh**: Provide refresh button for users
-4. **Auto-refresh**: Refresh on screen focus or app foreground
-5. **Status Polling**: Periodic refresh for real-time updates
-6. **Purchase Completion**: Refresh after successful purchase
-7. **Error Recovery**: Provide retry mechanism on failure
-
-## Related Documentation
-
-- **usePremium**: Simplified premium checking
-- **useSubscriptionStatus**: Detailed subscription status
-- **useSubscriptionDetails**: Package and pricing info
-- **useUserTier**: Tier information
-- **Subscription Repository**: `src/infrastructure/repositories/README.md`
-- **Domain Layer**: `src/domain/README.md`