@umituz/react-native-subscription 2.27.91 → 2.27.93

package/src/presentation/README.md

@@ -1,125 +0,0 @@
-# Presentation Layer
-
-UI/UX layer for the subscription system - React hooks, components, and screens.
-
-## Location
-
-**Directory**: `src/presentation/`
-
-**Type**: Layer
-
-## Strategy
-
-### Layer Responsibilities
-
-The Presentation Layer is responsible for:
-
-1. **State Management**
-   - React hooks for data fetching and mutations
-   - TanStack Query for server state management
-   - Local state management for UI state
-
-2. **UI Components**
-   - Reusable subscription components
-   - Feature gating UI elements
-   - Credit display components
-   - Paywall components
-
-3. **User Interaction**
-   - Handle user actions
-   - Display appropriate feedback
-   - Guide users through purchase flows
-   - Show upgrade prompts at right time
-
-### Architecture Pattern
-
-The presentation layer follows a layered architecture where:
-- Hooks manage state and data fetching at the top level
-- Components consume hooks and render UI
-- Screens compose multiple components together
-- All layers communicate with the domain layer for business logic
-
-### Integration Points
-
-- **Domain Layer**: Business logic and data access
-- **TanStack Query**: Server state management
-- **RevenueCat**: Purchase operations
-- **Navigation**: Screen routing
-
-## Restrictions
-
-### REQUIRED
-
-- **Type Safety**: All components MUST be typed with TypeScript
-- **Error Boundaries**: MUST implement error boundaries for all screens
-- **Loading States**: MUST show loading indicators during async operations
-- **User Feedback**: MUST provide feedback for all user actions
-
-### PROHIBITED
-
-- **NEVER** include business logic in components (use hooks instead)
-- **NEVER** make direct API calls from components (use hooks)
-- **DO NOT** store sensitive data in component state
-- **NEVER** hardcode strings (use localization)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** validate props before rendering
-- **ALWAYS** handle loading and error states
-- **NEVER** trust client-side state for security decisions
-- **MUST** implement proper error boundaries
-- **ALWAYS** sanitize user inputs before display
-
-## AI Agent Guidelines
-
-### When Building Presentation Layer
-
-1. **Always** use hooks for data fetching and state management
-2. **Always** handle loading and error states
-3. **Always** provide user feedback for actions
-4. **Always** implement error boundaries
-5. **Never** include business logic in components
-
-### Integration Checklist
-
-- [ ] Use appropriate hooks for data access
-- [ ] Handle loading states
-- [ ] Handle error states
-- [ ] Implement error boundaries
-- [ ] Provide user feedback
-- [ ] Test with various data states
-- [ ] Test error scenarios
-- [ ] Ensure type safety
-- [ ] Use localization for all strings
-- [ ] Test accessibility
-
-### Common Patterns
-
-1. **Compound Components**: Build complex UIs from simple components
-2. **Render Props**: Share stateful logic between components
-3. **Custom Hooks**: Extract reusable stateful logic
-4. **Error Boundaries**: Prevent crashes from propagating
-5. **Loading Skeletons**: Show placeholder during loading
-6. **Optimistic Updates**: Update UI immediately, rollback on failure
-7. **Graceful Degradation**: Show limited version on error
-8. **Responsive Design**: Support different screen sizes
-
-## Related Documentation
-
-- **Hooks**: `hooks/README.md`
-- **Components**: `components/README.md`
-- **Screens**: `screens/README.md`
-- **Wallet Domain**: `../../domains/wallet/README.md`
-- **Paywall Domain**: `../../domains/paywall/README.md`
-- **RevenueCat**: `../../revenuecat/README.md`
-
-## Directory Structure
-
-The presentation layer contains:
-- **hooks/** - React hooks for state management (usePremium, useSubscription, useCredits, useDeductCredit, useFeatureGate)
-- **components/** - UI components organized by functionality
-  - **details/** - Detail cards, badges
-  - **feedback/** - Modals, feedback components
-  - **sections/** - Section components
-  - **paywall/** - Paywall components
-- **screens/** - Full-screen components (SubscriptionDetailScreen)

package/src/presentation/hooks/README.md

@@ -1,156 +0,0 @@
-# Subscription Hooks
-
-Collection of React hooks for subscription, premium, and credits management.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**Directory**: `src/presentation/hooks/`
-
-**Type**: Hooks Collection
-
-## Strategy
-
-### Hook Organization
-
-Hooks are organized by functionality:
-
-1. **Subscription Hooks**: Manage subscription status and details
-2. **Premium Hooks**: Check and manage premium access
-3. **Credits Hooks**: Handle credit balance and operations
-4. **Gate Hooks**: Control feature access based on user state
-5. **Auth Hooks**: Authentication-aware purchase flows
-6. **Paywall Hooks**: Paywall display and management
-
-### Integration Pattern
-
-All hooks follow consistent patterns:
-- Return loading, error, and data states
-- Provide refetch/refresh functions
-- Use TanStack Query for caching
-- Handle optimistic updates
-- Support real-time updates
-
-## Hook Categories
-
-### Subscription Hooks
-
-- **useSubscription**: Core subscription status management
-- **useSubscriptionStatus**: Detailed subscription status
-- **useSubscriptionDetails**: Subscription package and feature details
-- **useSubscriptionSettingsConfig**: Settings and configuration
-
-### Premium Hooks
-
-- **usePremium**: Premium status checker
-- **usePremiumGate**: Premium feature gating
-- **usePremiumWithCredits**: Hybrid premium/credits access
-
-### Credits Hooks
-
-- **useCredits**: Credit balance and transactions
-- **useCreditChecker**: Simple credit validation
-- **useDeductCredit**: Credit deduction with optimistic updates
-- **useInitializeCredits**: Initialize credits after purchase
-
-### Gate Hooks
-
-- **useFeatureGate**: Unified auth, subscription, and credits gating
-- **useSubscriptionGate**: Subscription-only gating
-- **useCreditsGate**: Credits-only gating
-- **usePremiumGate**: Premium-only gating
-- **useAuthGate**: Authentication gating
-
-### Auth Hooks
-
-- **useAuthAwarePurchase**: Authentication-aware purchase flow
-- **useAuthSubscriptionSync**: Auth and subscription synchronization
-
-### Paywall Hooks
-
-- **usePaywall**: Paywall display management
-- **usePaywallOperations**: Paywall show/hide operations
-- **usePaywallVisibility**: Paywall visibility rules
-
-### User Tier Hooks
-
-- **useUserTier**: User tier management
-- **useUserTierWithRepository**: Repository-based tier management
-
-### Development Hooks
-
-- **useDevTestCallbacks**: Development and testing utilities
-
-## Restrictions
-
-### REQUIRED
-
-- **Import Path**: MUST import from `@umituz/react-native-subscription`
-- **Loading States**: MUST handle loading state in UI
-- **Error Handling**: MUST handle error state
-- **User Authentication**: Most hooks require authenticated user
-
-### PROHIBITED
-
-- **NEVER** use hooks outside React components
-- **NEVER** ignore loading states
-- **NEVER** skip error handling
-- **DO NOT** use hook returns for security decisions (server-side validation required)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** handle loading and error states
-- **NEVER** trust client-side state for security
-- **MUST** implement error boundaries
-- **ALWAYS** test with various user states (anonymous, free, premium)
-
-## AI Agent Guidelines
-
-### When Using Subscription Hooks
-
-1. **Always** handle loading and error states
-2. **Always** use appropriate gate hooks for feature access
-3. **Always** provide user feedback for all operations
-4. **Never** trust client-side state for security
-5. **Always** test with different user tiers
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Choose appropriate hook for use case
-- [ ] Handle loading state
-- [ ] Handle error state
-- [ ] Implement error boundaries
-- [ ] Use gate hooks for feature access
-- [ ] Test with all user tiers
-- [ ] Test offline scenarios
-- [ ] Test error scenarios
-
-### Common Patterns
-
-1. **Feature Gating**: Use `useFeatureGate` for unified access control
-2. **Credit Operations**: Check → Deduct → Execute pattern
-3. **Subscription Display**: Show status, expiration, renewal info
-4. **Premium Features**: Gate content, provide upgrade path
-5. **Paywall Integration**: Automatic display on access denial
-6. **Real-time Updates**: Refresh on focus, background sync
-
-## Related Documentation
-
-- **Subscription Domain**: `src/domains/wallet/README.md`
-- **Paywall Domain**: `src/domains/paywall/README.md`
-- **Config Domain**: `src/domains/config/README.md`
-- **RevenueCat Integration**: `src/revenuecat/README.md`
-- **Presentation Components**: `src/presentation/components/README.md`
-
-## Individual Hook Documentation
-
-- [useDeductCredit](./useDeductCredit.md) - Credit deduction with optimistic updates
-- [useCredits](./useCredits.md) - Credit balance access
-- [useCreditChecker](./useCreditChecker.md) - Simple credit validation
-- [useFeatureGate](./useFeatureGate.md) - Unified feature gating
-- [useSubscription](./useSubscription.md) - Subscription status management
-- [usePremium](./usePremium.md) - Premium status checker
-- [useCreditsGate](./useCreditsGate.md) - Credits-based feature gating
-- [useInitializeCredits](./useInitializeCredits.md) - Initialize credits after purchase

package/src/presentation/hooks/useAuthSubscriptionSync.md

@@ -1,94 +0,0 @@
-# useAuthSubscriptionSync Hook
-
-Automatically synchronizes subscription state with authentication changes.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useAuthSubscriptionSync.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Auth-Subscription Synchronization
-
-1. **Auth Listener Setup**: Subscribe to auth state changes via provided callback
-2. **User Change Detection**: Detect when userId changes (including sign out)
-3. **Subscription Initialization**: Initialize subscription when user signs in
-4. **One-Time Init**: Only initialize once per user session (skips duplicates)
-5. **User Switching**: Re-initialize when switching between accounts
-6. **Cleanup**: Unsubscribe from auth listener on unmount
-
-### Integration Points
-
-- **Auth Provider**: Any auth system (Firebase, Auth0, custom)
-- **RevenueCat**: For subscription initialization with logIn
-- **Subscription Service**: Backend subscription sync
-- **Credits System**: Optional credits initialization
-- **App Root**: Should be placed in root App component
-
-## Restrictions
-
-### REQUIRED
-
-- **Auth State Change Callback**: MUST provide onAuthStateChanged function
-- **Subscription Init**: MUST provide initializeSubscription function
-- **App Root Setup**: SHOULD be placed in root App component
-- **Unsubscribe Handling**: Callback MUST return unsubscribe function
-
-### PROHIBITED
-
-- **NEVER** place in individual screen components (use app root)
-- **NEVER** call without proper auth callback
-- **DO NOT** manually call initializeSubscription (hook handles it)
-- **DO NOT** configure multiple times (one-time setup)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** configure at app root level
-- **MUST** handle user switching correctly
-- **ALWAYS** return unsubscribe function from callback
-- **NEVER** rely on manual subscription initialization
-
-## AI Agent Guidelines
-
-### When Implementing Auth-Subscription Sync
-
-1. **Always** place in root App component
-2. **Always** provide onAuthStateChanged that returns unsubscribe
-3. **Always** provide initializeSubscription for user ID
-4. **Always** test user switching scenarios
-5. **Never** place in child components
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Place in root App component
-- [ ] Provide onAuthStateChanged callback
-- [ ] Ensure callback returns unsubscribe function
-- [ ] Provide initializeSubscription function
-- [ ] Test with initial user sign-in
-- [ ] Test with user sign-out
-- [ ] Test with account switching
-- [ ] Verify subscription initializes only once per user
-- [ ] Test cleanup on unmount
-
-### Common Patterns
-
-1. **Firebase + RevenueCat**: Sync Firebase auth with RevenueCat
-2. **Custom Auth + Backend**: Use custom auth with backend sync
-3. **Multi-Service Setup**: Initialize multiple services (RevenueCat, credits, backend)
-4. **Error Handling**: Handle initialization failures gracefully
-5. **Loading State**: Show loading during sync
-6. **Analytics Tracking**: Track auth and subscription events
-
-## Related Documentation
-
-- **useAuth**: For authentication state
-- **usePremium**: For subscription status
-- **useAuthAwarePurchase**: For auth-gated purchases
-- **useUserTier**: For tier determination
-- **Auth Integration Guide**: `src/docs/AUTH_INTEGRATION.md`
-- **RevenueCat Setup**: `src/docs/REVENUECAT_SETUP.md`

package/src/presentation/hooks/useCredits.md

@@ -1,103 +0,0 @@
-# useCredits Hook
-
-Hook for accessing and managing credits balance with real-time updates.
-
-## Location
-
-**Import Path**: `@umituz/react-native-subscription`
-
-**File**: `src/presentation/hooks/useCredits.ts`
-
-**Type**: Hook
-
-## Strategy
-
-### Data Fetching Flow
-
-1. **Initial Load**
-   - Fetch credits from repository on mount
-   - Cache results in TanStack Query
-   - Handle loading/error states
-
-2. **Real-time Updates**
-   - Subscribe to credit changes via repository listener
-   - Auto-update on balance changes
-   - Invalidate query on external modifications
-
-3. **Cache Management**
-   - Use TanStack Query for caching
-   - Background refetch on window focus
-   - Manual refetch capability
-
-### 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 background updates
-- **useFocusEffect**: For refresh on screen focus
-
-## Restrictions
-
-### REQUIRED
-
-- **User Authentication**: User MUST be authenticated to access credits
-- **Error Handling**: MUST handle error state in UI
-- **Loading State**: MUST show loading indicator while fetching
-
-### PROHIBITED
-
-- **NEVER** assume credits are available without checking loading state
-- **NEVER** use this hook for unauthenticated users
-- **DO NOT** mutate credits directly - use `useDeductCredit` instead
-- **DO NOT** call refetch excessively (causes unnecessary network calls)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** check `isLoading` before displaying credits
-- **ALWAYS** handle `error` state to prevent crashes
-- **NEVER** use `credits` value for security decisions (validate on backend)
-- **MUST** implement error boundaries when displaying balance
-
-## AI Agent Guidelines
-
-### When Implementing Credit Displays
-
-1. **Always** handle loading state explicitly
-2. **Always** handle error state gracefully
-3. **Always** provide manual refresh option
-4. **Always** format balance safely (handle undefined/null)
-5. **Never** use credits for security decisions (server-side validation required)
-
-### Integration Checklist
-
-- [ ] Import from correct path: `@umituz/react-native-subscription`
-- [ ] Handle loading state in UI
-- [ ] Handle error state in UI
-- [ ] Provide refresh mechanism
-- [ ] Format balance safely with default values
-- [ ] Implement error boundaries
-- [ ] Test with no credits (zero balance)
-- [ ] Test with loading states
-- [ ] Test with error states
-- [ ] Test refresh functionality
-
-### Common Patterns to Implement
-
-1. **Balance Card**: Display credits with currency conversion
-2. **Transaction List**: Show recent credit activity
-3. **Low Credits Warning**: Alert when balance is low
-4. **Refresh Control**: Pull-to-refresh or button
-5. **Real-time Updates**: Use focus effect for auto-refresh
-6. **Purchase Prompt**: Link to credit packages when low
-7. **Skeletal Loading**: Show skeleton during initial load
-8. **Error Recovery**: Retry mechanism for failed fetches
-
-## Related Documentation
-
-- **useDeductCredit**: Deduct credits from balance
-- **useCreditChecker**: Check credit availability before operations
-- **useInitializeCredits**: Initialize credits after purchase
-- **useCreditsGate**: Gate features behind credit requirements
-- **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/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`