@umituz/react-native-subscription 2.15.3 → 2.15.4

package/src/presentation/README.md.bak

@@ -1,172 +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
-
-## Rules
-
-### Component Structure
-
-**CORRECT**: Proper component structure includes:
-- Define TypeScript interface for props
-- Import and use appropriate hooks for data fetching
-- Return loading indicator when data is fetching
-- Return error display when there's an error
-- Render actual component only when data is available
-
-**INCORRECT**: No loading/error handling
-- Don't render component without checking if data is loading
-- Don't display component without handling potential errors
-- Never assume data is always available immediately
-
-**INCORRECT**: Business logic in component
-- Don't use useEffect to fetch data directly
-- Don't manage complex state with useState for business logic
-- Never include data transformation logic in components
-
-### Hook Usage
-
-**CORRECT**: Use hooks for data fetching
-- Call useCredits to get credit balance with loading and error states
-- Call usePremium to check premium status
-- Always check if loading is true before rendering
-- Always check if error exists before rendering
-
-**INCORRECT**: Direct API calls in component
-- Don't use useEffect with axios or fetch to call APIs
-- Don't manage async operations manually in components
-- Never handle API responses directly in UI components
-
-### Error Boundaries
-
-**CORRECT**: Wrap screens with error boundaries
-- Import ErrorBoundary component
-- Create fallback error screen component
-- Wrap screen content with ErrorBoundary component
-- Pass fallback component to ErrorBoundary
-
-**INCORRECT**: No error boundary
-- Don't export screens without error boundary wrapper
-- Never let errors crash entire application
-- Don't assume components will never throw errors
-
-## 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/components/README.md.bak

@@ -1,217 +0,0 @@
-# Presentation Components
-
-React Native UI components for subscription and paywall features.
-
-## Location
-
-**Directory**: `src/presentation/components/`
-
-**Type**: Component Library
-
-## Strategy
-
-### Component Categories
-
-Components are organized by functionality:
-
-1. **Details Components**
-   - CreditRow: Display credit balance and info
-   - DetailRow: Generic detail display row
-   - PremiumStatusBadge: Visual premium indicator
-   - PremiumDetailsCard: Premium subscription details
-
-2. **Feedback Components**
-   - PaywallFeedbackModal: User feedback collection
-   - Alert components: Warning and info displays
-
-3. **Section Components**
-   - SubscriptionSection: Subscription info section
-   - CreditsSection: Credits balance section
-
-4. **Paywall Components**
-   - PaywallModal: Upgrade/purchase modal
-   - Purchase options: Subscription and credit packages
-
-### Design Principles
-
-All components follow these principles:
-- **Reusable**: Composable and configurable
-- **Typed**: Full TypeScript support
-- **Accessible**: WCAG compliant where possible
-- **Testable**: Easy to test in isolation
-- **Themeable**: Support custom styling
-
-### Integration Points
-
-- **React Native**: Core UI framework
-- **Design System**: Shared UI components
-- **Localization**: i18n string support
-- **Theme**: Custom styling support
-
-## Restrictions
-
-### REQUIRED
-
-- **Props Typing**: All components MUST have TypeScript interfaces
-- **Default Props**: MUST provide sensible defaults
-- **Accessibility**: MUST implement accessibility labels
-- **Responsive**: MUST handle different screen sizes
-
-### PROHIBITED
-
-- **NEVER** hardcode colors or sizes (use theme)
-- **NEVER** include business logic in components
-- **DO NOT** make direct API calls
-- **NEVER** hardcode strings (use localization)
-
-### CRITICAL SAFETY
-
-- **ALWAYS** validate props before rendering
-- **ALWAYS** handle loading and error states
-- **NEVER** trust user input for security decisions
-- **MUST** implement proper error boundaries
-- **ALWAYS** sanitize user-provided content
-
-## Rules
-
-### Component Structure
-
-**CORRECT**: Proper component structure
-- Define TypeScript interface for component props
-- List all required props (amount, isLoading, onPress)
-- List optional props with question marks
-- Destructure props in function signature
-- Check loading state and return SkeletonLoader
-- Render TouchableOpacity with conditional disabled
-- Display text content
-
-**INCORRECT**: No props interface
-- Don't create components without TypeScript interfaces
-- Never omit type definitions for props
-- Don't use any type or skip type checking
-
-### Theme Usage
-
-**CORRECT**: Use theme for styling
-- Import and use useTheme hook
-- Access colors from theme object
-- Apply theme colors to styles
-- Use semantic color names (primary, onPrimary)
-
-**INCORRECT**: Hardcoded colors
-- Don't use hex color codes directly in styles
-- Never hardcode values like '#007AFF' or '#FFFFFF'
-- Don't skip theme integration
-- Avoid inline color values
-
-### Accessibility
-
-**CORRECT**: Accessibility support
-- Define accessibilityLabel prop for Button
-- Define accessibilityHint for additional context
-- Set accessibilityState with disabled condition
-- Provide clear, descriptive labels
-- Include hints for complex interactions
-
-**INCORRECT**: No accessibility
-- Don't create components without a11y labels
-- Never skip accessibilityHint for complex UI
-- Don't omit accessibilityState for interactive elements
-- Avoid non-descriptive labels
-
-### Conditional Rendering
-
-**CORRECT**: Handle all states
-- Check if loading and return SkeletonLoader
-- Check if error and return ErrorDisplay
-- Check if credits is undefined and return Placeholder
-- Render content only when all states are valid
-- Handle all possible state combinations
-
-**INCORRECT**: Incomplete state handling
-- Don't render content without checking error state
-- Never assume data is always defined
-- Don't skip placeholder for undefined data
-- Avoid incomplete conditional chains
-
-## AI Agent Guidelines
-
-### When Building Components
-
-1. **Always** define TypeScript interfaces for props
-2. **Always** use theme for styling (no hardcoded values)
-3. **Always** implement accessibility labels
-4. **Always** handle loading and error states
-5. **Never** include business logic in components
-
-### Integration Checklist
-
-- [ ] Define TypeScript interface for props
-- [ ] Use theme for all styling
-- [ ] Implement accessibility labels
-- [ ] Handle loading state
-- [ ] Handle error state
-- [ ] Provide sensible defaults
-- [ ] Test with different screen sizes
-- [ ] Test accessibility
-- [ ] Test with various prop combinations
-- [ ] Document component usage
-
-### Common Patterns
-
-1. **Compound Components**: Build complex UIs from simple parts
-2. **Render Props**: Share stateful logic
-3. **Slot Pattern**: Allow content injection
-4. **Control Props**: Make components controlled or uncontrolled
-5. **Asynchronous States**: Handle loading, error, success states
-6. **Responsive Design**: Adapt to different screen sizes
-7. **Theme Integration**: Use design system tokens
-8. **Accessibility First**: Include a11y from the start
-
-## Related Documentation
-
-- **Details Components**: `details/README.md`
-- **Feedback Components**: `feedback/README.md`
-- **Section Components**: `sections/README.md`
-- **Paywall Components**: `paywall/README.md`
-- **Design System**: External design system documentation
-- **Hooks**: `../hooks/README.md`
-
-## Component Examples
-
-### CreditRow
-
-Display user's credit balance with optional actions.
-
-Usage:
-- Set amount prop to number of credits
-- Set isLoading to true during data fetch
-- Provide onPress callback for navigation
-- Component displays credit count and handles tap
-
-### PremiumStatusBadge
-
-Visual indicator for premium subscription status.
-
-Usage:
-- Set isPremium to boolean status
-- Set tier to subscription level (gold, silver, etc.)
-- Component renders styled badge
-
-### PaywallModal
-
-Modal for subscription and credit purchase.
-
-Usage:
-- Set isVisible to boolean for show/hide
-- Provide onClose callback
-- Pass features array for premium features list
-- Modal handles purchase flow
-
-## Directory Structure
-
-The components directory contains:
-- **details/** - Detail display components (CreditRow, DetailRow, PremiumStatusBadge, PremiumDetailsCard)
-- **feedback/** - Feedback and alert components (PaywallFeedbackModal)
-- **sections/** - Section components (SubscriptionSection)
-- **paywall/** - Paywall components (PaywallModal)

package/src/presentation/hooks/useCredits.md.bak

@@ -1,231 +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
-
-## Rules
-
-### Basic Usage
-
-```typescript
-// CORRECT - Handle all states
-function CreditsDisplay() {
-  const { credits, isLoading, error } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-  if (error) return <ErrorDisplay error={error} />;
-
-  return <Text>Credits: {credits}</Text>;
-}
-
-// INCORRECT - No loading check
-function CreditsDisplay() {
-  const { credits } = useCredits();
-  return <Text>Credits: {credits}</Text>; // May show undefined
-}
-
-// INCORRECT - No error handling
-function CreditsDisplay() {
-  const { credits, isLoading, error } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-  return <Text>Credits: {credits}</Text>; // Crashes if error
-}
-```
-
-### Manual Refresh
-
-```typescript
-// CORRECT - Manual refetch with loading state
-function CreditsWithRefresh() {
-  const { credits, refetch, isLoading } = useCredits();
-
-  const handleRefresh = async () => {
-    await refetch();
-  };
-
-  return (
-    <Button onPress={handleRefresh} disabled={isLoading}>
-      Refresh
-    </Button>
-  );
-}
-
-// INCORRECT - Ignore loading state during refresh
-const handleRefresh = () => {
-  refetch(); // No loading indication
-};
-```
-
-### Transaction History
-
-```typescript
-// CORRECT - Display transactions with safety checks
-function CreditsWithHistory() {
-  const { credits, transactions, isLoading } = useCredits();
-
-  if (isLoading) return <ActivityIndicator />;
-
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
-      <FlatList
-        data={transactions || []}
-        keyExtractor={(item) => item.id}
-        renderItem={({ item }) => <TransactionItem {...item} />}
-      />
-    </View>
-  );
-}
-
-// INCORRECT - Assume transactions exist
-<FlatList
-  data={transactions} // Crashes if undefined
-  keyExtractor={(item) => item.id}
-  renderItem={({ item }) => <TransactionItem {...item} />}
-/>
-```
-
-### Auto-Refresh Patterns
-
-```typescript
-// CORRECT - Refresh on focus with effect cleanup
-function AutoRefreshCredits() {
-  const { credits, refetch } = useCredits();
-
-  useFocusEffect(
-    useCallback(() => {
-      refetch();
-    }, [refetch])
-  );
-
-  return <Text>Credits: {credits}</Text>;
-}
-
-// INCORRECT - Missing dependency
-useFocusEffect(
-  useCallback(() => {
-    refetch();
-  }, []) // Missing refetch dependency
-);
-```
-
-### Balance Display
-
-```typescript
-// CORRECT - Safe balance display with formatting
-function BalanceDisplay() {
-  const { credits, balance, isLoading } = useCredits();
-
-  if (isLoading) return <Skeleton />;
-
-  return (
-    <View>
-      <Text>{credits} Credits</Text>
-      <Text>Value: ${(balance || 0).toFixed(2)}</Text>
-    </View>
-  );
-}
-
-// INCORRECT - Unsafe balance access
-<Text>Value: ${balance.toFixed(2)}</Text> // Crashes if undefined
-```
-
-## 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`