@umituz/react-native-subscription 2.27.92 → 2.27.93

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`