@umituz/react-native-subscription 2.27.92 → 2.27.94

package/src/presentation/hooks/useDeductCredit.md

@@ -1,100 +0,0 @@
-# useDeductCredit Hook
-
-Hook for deducting credits from user balance with optimistic updates.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useDeductCredit.ts`
-
-## Strategy
-
-### Credit Deduction Flow
-
-1. **Pre-deduction Validation**
-   - Verify user is authenticated (userId must be defined)
-   - Check if sufficient credits exist
-   - Validate deduction amount is positive
-
-2. **Optimistic Update**
-   - Immediately update UI with new balance
-   - Store previous state for potential rollback
-   - Update TanStack Query cache
-
-3. **Server Synchronization**
-   - Send deduction request to backend
-   - Handle success/failure responses
-   - Rollback on failure
-
-4. **Post-deduction Handling**
-   - Trigger `onCreditsExhausted` callback if balance reaches zero
-   - Return success/failure boolean
-   - Reset loading state
-
-### Integration Points
-
-- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
-- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
-- **TanStack Query**: For cache management and optimistic updates
-
-## Restrictions
-
-### REQUIRED
-
-- **User Authentication**: `userId` parameter MUST be provided and cannot be undefined
-- **Positive Amount**: Credit cost MUST be greater than zero
-- **Callback Implementation**: `onCreditsExhausted` callback SHOULD be implemented to handle zero balance scenarios
-
-### PROHIBITED
-
-- **NEVER** call `deductCredit` or `deductCredits` without checking `isDeducting` state first
-- **NEVER** allow multiple simultaneous deduction calls for the same user
-- **NEVER** deduce credits when balance is insufficient (should check with `useCreditChecker` first)
-- **DO NOT** use this hook for guest users (userId undefined)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check return value before proceeding with feature execution
-- **ALWAYS** handle the case where deduction returns `false`
-- **NEVER** assume deduction succeeded without checking return value
-- **MUST** implement error boundaries when using this hook
-
-## AI Agent Guidelines
-
-### When Implementing Features
-
-1. **Always** check if user has sufficient credits BEFORE allowing action
-2. **Always** show the credit cost to user before deducting
-3. **Always** disable buttons while `isDeducting` is true
-4. **Always** handle the case where deduction returns false
-5. **Never** allow zero or negative credit costs
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Provide valid `userId` from authentication context
-- [ ] Implement `onCreditsExhausted` callback
-- [ ] Check `isDeducting` before calling deduct functions
-- [ ] Validate return value before proceeding
-- [ ] Show credit cost to user before action
-- [ ] Handle error cases gracefully
-- [ ] Test with insufficient credits
-- [ ] Test with zero balance
-
-### Common Patterns to Implement
-
-1. **Pre-check**: Use `useCreditChecker` before showing feature button
-2. **Confirmation Dialog**: Ask user before expensive operations (>5 credits)
-3. **Success Feedback**: Show success message after deduction
-4. **Failure Handling**: Show appropriate error message on failure
-5. **Purchase Flow**: Navigate to purchase screen on exhaustion
-
-## Related Documentation
-
-- **useCredits**: Access current credit balance
-- **useCreditChecker**: Check credit availability before operations
-- **useInitializeCredits**: Initialize credits after purchase
-- **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/useFeatureGate.md

@@ -1,112 +0,0 @@
-# useFeatureGate Hook
-
-Unified feature gate combining authentication, subscription, and credits checks.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useFeatureGate.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Progressive Access Control
-
-1. **Authentication Check**
-   - Verify user is authenticated
-   - Show auth modal if not authenticated
-   - Queue pending action for post-auth execution
-
-2. **Subscription Check**
-   - Verify user has required subscription tier
-   - Show paywall if subscription insufficient
-   - Bypass credit check for premium users
-
-3. **Credit Check**
-   - Verify sufficient credit balance
-   - Show purchase prompt if insufficient
-   - Deduct credits only after all checks pass
-
-4. **Action Execution**
-   - Execute gated action only if all checks pass
-   - Handle failures gracefully
-   - Update UI state appropriately
-
-### Integration Points
-
-- **useAuth**: For authentication state
-- **usePremium**: For subscription status
-- **useCredits**: For credit balance
-- **useDeductCredit**: For credit deduction
-- **Auth Modals**: Custom authentication UI
-- **Paywall Components**: Upgrade prompts
-
-## Restrictions
-
-### REQUIRED
-
-- **Authentication Check**: MUST implement `onShowAuthModal` callback
-- **Paywall Handler**: MUST implement `onShowPaywall` callback
-- **Credit Validation**: MUST check `hasCredits` before allowing actions
-- **State Management**: MUST respect `canAccess` boolean
-
-### PROHIBITED
-
-- **NEVER** bypass authentication check for sensitive features
-- **NEVER** show feature gate if user has access (confusing UX)
-- **NEVER** execute action without checking all gates first
-- **DO NOT** hardcode gate logic (use hook parameters)
-- **NEVER** deduct credits without checking subscription status first
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check gates in order: Auth → Subscription → Credits
-- **ALWAYS** provide clear messaging about why access is denied
-- **ALWAYS** preserve user intent through auth/purchase flows
-- **NEVER** trust client-side gate for security (server-side validation required)
-- **MUST** implement proper error boundaries around gated actions
-
-## AI Agent Guidelines
-
-### When Implementing Feature Gates
-
-1. **Always** check gates in order: Auth → Subscription → Credits
-2. **Always** provide clear, specific messaging for each gate
-3. **Always** preserve user intent through auth/purchase flows
-4. **Always** bypass credit check for premium users (if applicable)
-5. **Never** trust client-side gates for security (server validation required)
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Implement `onShowAuthModal` with pending action preservation
-- [ ] Implement `onShowPaywall` with context-aware messaging
-- [ ] Check `canAccess` before showing feature
-- [ ] Provide appropriate messaging for each gate state
-- [ ] Respect premium status (bypass credit check if needed)
-- [ ] Test all gate combinations (auth, subscription, credits)
-- [ ] Test pending action execution after auth/purchase
-- [ ] Implement error boundaries around gated actions
-
-### Common Patterns to Implement
-
-1. **Progressive Unlocking**: Show upgrade path for each gate
-2. **Smart Paywalls**: Show subscription OR credits based on user state
-3. **Intent Preservation**: Queue actions through auth/purchase flows
-4. **Clear Messaging**: Tell users exactly what's required
-5. **Premium Bypass**: Skip credit check for premium users
-6. **Access Indicators**: Show lock/unlock status in UI
-7. **Graceful Degradation**: Show limited version for free users
-8. **Analytics Tracking**: Monitor gate triggers and conversions
-
-## Related Documentation
-
-- **useAuthGate**: Authentication gating only
-- **useSubscriptionGate**: Subscription gating only
-- **useCreditsGate**: Credits gating only
-- **usePremiumGate**: Premium feature gating
-- **useDeductCredit**: Credit deduction after gate passes
-- **Feature Gating**: `../../../docs/FEATURE_GATING.md`
-- **Access Control**: `../../../docs/ACCESS_PATTERNS.md`

package/src/presentation/hooks/usePaywall.md

@@ -1,89 +0,0 @@
-# usePaywall Hook
-
-Hook for controlling paywall visibility and state.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePaywall.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Paywall State Management
-
-1. **Visibility Control**: Show/hide paywall on demand
-2. **Trigger Tracking**: Record what triggered paywall display
-3. **Context Management**: Store paywall context and metadata
-4. **Dynamic Configuration**: Support custom paywall configs per trigger
-5. **State Persistence**: Maintain paywall state across component renders
-6. **Event Tracking**: Enable analytics for paywall interactions
-
-### Integration Points
-
-- **Paywall Context**: Global paywall state management
-- **Paywall Domain**: `src/domains/paywall/README.md`
-- **Analytics**: For tracking paywall impressions and conversions
-- **Navigation**: For paywall screen routing
-
-## Restrictions
-
-### REQUIRED
-
-- **State Management**: MUST use showPaywall/hidePaywall functions
-- **Trigger Tracking**: SHOULD include trigger information for analytics
-- **Context**: SHOULD provide relevant context for paywall display
-
-### PROHIBITED
-
-- **NEVER** manage paywall state locally (use this hook instead)
-- **NEVER** show paywall without user action or clear trigger
-- **DO NOT** show paywall too frequently (respect user experience)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** hide paywall on successful purchase
-- **NEVER** trap users in paywall (provide clear exit)
-- **MUST** track paywall triggers for analytics
-- **ALWAYS** provide close/dismiss option
-
-## AI Agent Guidelines
-
-### When Implementing Paywall Triggers
-
-1. **Always** include trigger source/context
-2. **Always** track paywall impressions
-3. **Always** provide clear close button
-4. **Never** show paywall without clear reason
-5. **Always** hide paywall after successful purchase
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Use showPaywall with trigger information
-- [ ] Implement hidePaywall callback
-- [ ] Track paywall impressions in analytics
-- [ ] Track paywall dismissals
-- [ ] Provide clear close button
-- [ ] Test manual trigger
-- [ ] Test automatic trigger (usage limit, etc.)
-- [ ] Test purchase flow completion
-- [ ] Verify paywall hides after purchase
-
-### Common Patterns
-
-1. **Manual Trigger**: User clicks upgrade button
-2. **Usage Limit**: Show after N free uses
-3. **Feature Gate**: Show when accessing premium feature
-4. **Time-based**: Show after certain time/usage
-5. **Event-driven**: Show on specific app events
-
-## Related Documentation
-
-- **usePaywallActions**: Paywall purchase actions
-- **usePaywallVisibility**: Conditional paywall display logic
-- **usePaywallOperations**: Complete paywall operations
-- **Paywall Domain**: `src/domains/paywall/README.md`
-- **Paywall Components**: `src/presentation/components/paywall/README.md`

package/src/presentation/hooks/usePaywallOperations.md

@@ -1,92 +0,0 @@
-# usePaywallOperations Hook
-
-Complete paywall purchase operations with authentication handling.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePaywallOperations.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Paywall Purchase Flow with Auth
-
-1. **Auth Check**: Verify if user is authenticated before purchase
-2. **Pending Package Management**: Store package when auth is required
-3. **Auth Flow Trigger**: Show auth modal for unauthenticated users
-4. **Purchase Execution**: Complete purchase after authentication
-5. **Restore Support**: Handle purchase restoration with auth check
-6. **Callback Handling**: Execute appropriate callbacks at each stage
-
-### Integration Points
-
-- **usePremium**: For purchase and restore operations
-- **Auth Context**: User authentication state
-- **Paywall Domain**: For paywall display and management
-- **Auth UI**: For authentication modal
-- **RevenueCat**: For purchase transactions
-
-## Restrictions
-
-### REQUIRED
-
-- **User ID**: MUST provide valid userId parameter
-- **Anonymous Check**: MUST provide isAnonymous parameter
-- **Auth Required Callback**: MUST implement onAuthRequired callback
-- **Error Handling**: MUST handle purchase failures
-
-### PROHIBITED
-
-- **NEVER** call without valid userId
-- **NEVER** call without isAnonymous parameter
-- **DO NOT** proceed with purchase without auth check
-- **DO NOT** ignore pending package state
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check authentication status before purchase
-- **MUST** handle pending package after auth
-- **ALWAYS** provide clear auth flow for users
-- **NEVER** allow anonymous purchases without auth
-
-## AI Agent Guidelines
-
-### When Implementing Paywall Operations
-
-1. **Always** provide valid userId
-2. **Always** provide isAnonymous status
-3. **Always** implement onAuthRequired with pending package handling
-4. **Always** implement onPurchaseSuccess callback
-5. **Always** handle purchase and restore failures
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Provide valid userId
-- [ ] Provide isAnonymous status
-- [ ] Implement onAuthRequired callback
-- [ ] Implement onPurchaseSuccess callback
-- [ ] Implement onPaywallClose callback
-- [ ] Handle pending package state
-- [ ] Test purchase with authenticated user
-- [ ] Test purchase with anonymous user
-- [ ] Test purchase flow after authentication
-
-### Common Patterns
-
-1. **Pending Purchase Flow**: Store package, show auth, complete purchase
-2. **In-App Purchases**: Use handleInAppPurchase for modal paywalls
-3. **Purchase Analytics**: Track purchase attempts and completions
-4. **Error Recovery**: Handle failures and provide retry options
-5. **Post-Onboarding**: Handle purchases after onboarding flow
-
-## Related Documentation
-
-- **usePremium**: For purchase and restore operations
-- **useAuthAwarePurchase**: For auth-gated purchases
-- **usePaywallVisibility**: For paywall visibility control
-- **Paywall Screen**: `src/presentation/screens/README.md`
-- **Purchase Flow**: `src/docs/PURCHASE_FLOW.md`

package/src/presentation/hooks/usePaywallVisibility.md

@@ -1,95 +0,0 @@
-# usePaywallVisibility Hook
-
-Simple global state management for paywall visibility using external store.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePaywallVisibility.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Global Paywall State Management
-
-1. **External Store**: Use Zustand or similar for global state
-2. **Visibility Control**: Simple boolean for show/hide
-3. **Global Access**: Available from any component
-4. **Direct Control**: Provide paywallControl for non-React contexts
-5. **Single Instance**: One paywall modal at app root
-6. **State Persistence**: Maintain visibility across component unmounts
-
-### Integration Points
-
-- **App Root**: Paywall modal should be placed at app root
-- **Any Component**: Can trigger paywall from anywhere
-- **Deep Links**: Can open paywall from URLs
-- **Push Notifications**: Can open paywall from notifications
-- **usePremium**: For conditional display based on status
-
-## Restrictions
-
-### REQUIRED
-
-- **Single Modal**: MUST place paywall modal once at app root
-- **Close Handler**: MUST provide close button in paywall
-- **Premium Check**: SHOULD hide paywall when user becomes premium
-- **Back Handler**: SHOULD handle Android back button
-
-### PROHIBITED
-
-- **NEVER** place multiple paywall modals in component tree
-- **NEVER** manage visibility locally (use this hook instead)
-- **DO NOT** show paywall too frequently
-- **DO NOT** trap users without exit option
-
-### CRITICAL SAFETY
-
-- **ALWAYS** provide close button
-- **NEVER** trap users in paywall
-- **MUST** handle back button on Android
-- **ALWAYS** hide paywall after successful purchase
-
-## AI Agent Guidelines
-
-### When Implementing Paywall Visibility
-
-1. **Always** place paywall modal once at app root
-2. **Always** provide close button
-3. **Always** use openPaywall/closePaywall functions
-4. **Always** hide paywall after successful purchase
-5. **Never** manage visibility locally in components
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Place paywall modal once at app root
-- [ ] Use openPaywall to show paywall
-- [ ] Use closePaywall to hide paywall
-- [ ] Provide close button in paywall
-- [ ] Handle Android back button
-- [ ] Hide paywall when user becomes premium
-- [ ] Test paywall opens from any component
-- [ ] Test paywallControl for non-React contexts
-- [ ] Test deep link integration
-
-### Common Patterns
-
-1. **App Root Setup**: Single modal instance at app root
-2. **Trigger Button**: Any component can open paywall
-3. **Direct Control**: Use paywallControl in non-React code
-4. **Conditional Display**: Auto-show based on user status
-5. **History/Navigation**: Handle navigation with paywall
-6. **Timeout/Auto-Close**: Auto-close after timeout
-7. **Deep Links**: Open from URL schemes
-
-## Related Documentation
-
-- **usePaywallOperations**: For paywall purchase operations
-- **usePremium**: For subscription status
-- **usePaywall**: For complete paywall management
-- **Paywall Screen**: `src/presentation/screens/README.md`
-- **Paywall Components**: `src/presentation/components/paywall/README.md`
-- **Modal Integration**: `src/docs/MODAL_INTEGRATION.md`

package/src/presentation/hooks/usePremium.md

@@ -1,88 +0,0 @@
-# usePremium Hook
-
-Hook for checking and managing premium subscription status.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/usePremium.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Premium Status Flow
-
-1. **Initial Check**: Fetch current subscription status from repository
-2. **Status Evaluation**: Determine if user has active premium subscription
-3. **Real-time Updates**: Automatically update when user logs in/out or subscription changes
-4. **Caching**: Cache status for 5 minutes (configurable) to reduce API calls
-5. **Loading States**: Provide loading indicators during data fetch
-6. **Error Handling**: Handle fetch errors gracefully
-
-### Integration Points
-
-- **Subscription Repository**: `src/infrastructure/repositories/SubscriptionRepository.ts`
-- **TanStack Query**: For caching and real-time updates
-- **Auth Context**: Sync with user authentication state
-- **RevenueCat**: For subscription data source
-
-## Restrictions
-
-### REQUIRED
-
-- **Loading State**: MUST handle loading state in UI
-- **Error Handling**: MUST handle error state
-- **Check Before Access**: MUST verify isPremium before showing premium features
-
-### PROHIBITED
-
-- **NEVER** use for security decisions (server-side validation required)
-- **NEVER** assume instant data availability (always check loading state)
-- **DO NOT** use for anonymous users without proper handling
-
-### CRITICAL SAFETY
-
-- **ALWAYS** handle loading state before rendering premium content
-- **NEVER** trust client-side state for security enforcement
-- **MUST** implement error boundaries when using this hook
-
-## AI Agent Guidelines
-
-### When Implementing Premium Features
-
-1. **Always** check loading state first
-2. **Always** handle error state
-3. **Always** verify isPremium before showing premium content
-4. **Never** use for security decisions without server validation
-5. **Always** provide upgrade path for non-premium users
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Handle loading state (show ActivityIndicator or skeleton)
-- [ ] Handle error state (show error message)
-- [ ] Check isPremium before rendering premium content
-- [ ] Provide upgrade path for free users
-- [ ] Test with premium user
-- [ ] Test with free user
-- [ ] Test with anonymous user
-- [ ] Test offline scenario
-
-### Common Patterns
-
-1. **Conditional Rendering**: Show/hide features based on isPremium
-2. **Premium Badge**: Display premium status badge
-3. **Feature Gating**: Use usePremiumGate instead of manual checks
-4. **Status Display**: Show subscription details with useSubscriptionDetails
-5. **Upgrade Prompts**: Guide free users to paywall
-
-## Related Documentation
-
-- **usePremiumGate**: Gating premium features
-- **useSubscription**: Detailed subscription status
-- **useSubscriptionStatus**: Subscription status details
-- **usePremiumWithCredits**: Hybrid premium/credits access
-- **Subscription Repository**: `src/infrastructure/repositories/README.md`
-- **Domain Layer**: `src/domain/README.md`

package/src/presentation/hooks/useSubscriptionSettingsConfig.md

@@ -1,94 +0,0 @@
-# useSubscriptionSettingsConfig Hook
-
-Returns ready-to-use configuration for subscription settings screens.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useSubscriptionSettingsConfig.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Settings Configuration Generation
-
-1. **Data Aggregation**: Combine subscription, credits, and tier information
-2. **Status Determination**: Calculate status type (active/expired/free/canceled)
-3. **Date Formatting**: Format expiration and purchase dates
-4. **Credit Items**: Generate credit item list with optional limit
-5. **Translation Support**: Apply provided translations to all strings
-6. **Upgrade Prompt**: Optional upgrade prompt configuration
-
-### Integration Points
-
-- **useSubscriptionStatus**: For subscription status details
-- **useCredits**: For credits information
-- **useUserTier**: For tier determination
-- **Settings UI**: For settings screen integration
-- **Translation System**: For localization support
-
-## Restrictions
-
-### REQUIRED
-
-- **User ID**: MUST provide valid userId parameter
-- **Translations**: MUST provide all translation strings
-- **Null Handling**: MUST handle null dates and values
-- **Enabled Check**: MUST check config.enabled before use
-
-### PROHIBITED
-
-- **NEVER** use without providing all translations
-- **NEVER** assume config is enabled (check enabled flag)
-- **DO NOT** hardcode translation strings
-- **DO NOT** use without userId
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check config.enabled before rendering
-- **MUST** provide complete translation objects
-- **ALWAYS** handle null dates gracefully
-- **NEVER** trust client-side config for security
-
-## AI Agent Guidelines
-
-### When Implementing Settings Config
-
-1. **Always** provide complete translations
-2. **Always** check config.enabled
-3. **Always** handle null dates
-4. **Always** format dates appropriately
-5. **Never** use for security decisions without server validation
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Provide valid userId
-- [ ] Provide complete translations
-- [ ] Check config.enabled
-- [ ] Handle null dates
-- [ ] Format dates appropriately
-- [ ] Apply credit limit if needed
-- [ ] Configure upgrade prompt if needed
-- [ ] Test with active subscription
-- [ ] Test with expired subscription
-- [ ] Test with free user
-- [ ] Test with lifetime subscription
-
-### Common Patterns
-
-1. **Settings List Item**: Quick access item in settings
-2. **Detailed Section**: Comprehensive subscription section
-3. **Localized Settings**: Use with translation libraries
-4. **Credit Limit**: Limit displayed credit items
-5. **Upgrade Prompt**: Show upgrade prompt for free users
-
-## Related Documentation
-
-- **useSubscriptionStatus**: For subscription status details
-- **useCredits**: For credits information
-- **useSubscriptionDetails**: For package and pricing info
-- **Settings Screen**: `src/presentation/screens/README.md`
-- **Subscription Utilities**: `src/utils/subscriptionDateUtils.md`