@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/domains/paywall/entities/README.md

@@ -1,199 +1,40 @@
 # Paywall Entities
 
+## Location
 Domain entities for paywall configuration and state management.
 
-## Overview
-
-This directory contains entities representing paywall configuration, triggers, and display logic.
-
-## Entities
-
-### PaywallTrigger
-Represents an event that triggers paywall display.
-
-```typescript
-interface PaywallTrigger {
-  type: PaywallTriggerType;
-  feature?: string;
-  packageName?: string;
-  context?: Record<string, any>;
-  timestamp: number;
-}
-
-type PaywallTriggerType =
-  | 'premium_feature'     // Premium feature access attempt
-  | 'credit_gate'         // Credit gate failure
-  | 'manual'              // User manually opened
-  | 'onboarding_complete' // Post-onboarding
-  | 'usage_limit'         // Free tier limit reached
-  | 'subscription_expired'; // Subscription expired
-```
-
-**Usage:**
-```typescript
-const trigger: PaywallTrigger = {
-  type: 'premium_feature',
-  feature: 'ai_generation',
-  context: { cost: 5 },
-  timestamp: Date.now(),
-};
-```
-
-### PaywallConfig
-Configuration for paywall display.
-
-```typescript
-interface PaywallConfig {
-  title: string;
-  subtitle: string;
-  description?: string;
-  features: string[];
-  highlightBenefit?: string;  // Main value proposition
-  packages: PaywallPackage[];
-  defaultPackage?: string;    // Pre-selected package
-  dismissible: boolean;
-  showCloseButton: boolean;
-  onUpgrade: (pkg: PaywallPackage) => void;
-  onDismiss: () => void;
-}
-```
-
-**Usage:**
-```typescript
-const config: PaywallConfig = {
-  title: 'Upgrade to Premium',
-  subtitle: 'Unlock all features',
-  features: [
-    'Unlimited access',
-    'Priority support',
-    'Ad-free experience',
-  ],
-  packages: availablePackages,
-  dismissible: true,
-  showCloseButton: true,
-  onUpgrade: (pkg) => purchasePackage(pkg),
-  onDismiss: () => navigation.goBack(),
-};
-```
-
-### PaywallPackage
-Represents a subscription package displayed in paywall.
-
-```typescript
-interface PaywallPackage {
-  identifier: string;         // Unique package ID
-  productIdentifier: string;  // RevenueCat product ID
-  title: string;              // Display title
-  description: string;        // Package description
-  price: number;              // Price in local currency
-  pricePerMonth?: number;     // Monthly equivalent (for annual)
-  currencyCode: string;       // Currency code
-  period: PackagePeriod;      // Billing period
-  features: string[];         // Package features
-  popular?: boolean;          // Highlight as popular
-  savings?: number;           // Savings amount (for annual)
-  badge?: string;             // Custom badge text
-}
-
-type PackagePeriod = 'monthly' | 'annual' | 'lifetime';
-```
-
-**Usage:**
-```typescript
-const premiumPackage: PaywallPackage = {
-  identifier: 'premium_annual',
-  productIdentifier: 'com.app.premium.annual',
-  title: 'Premium Annual',
-  description: 'Best value - Save 50%',
-  price: 99.99,
-  pricePerMonth: 8.33,
-  currencyCode: 'USD',
-  period: 'annual',
-  features: [
-    'Unlimited access',
-    'Priority support',
-    'Ad-free',
-    'Advanced features',
-  ],
-  popular: true,
-  savings: 20.00,
-  badge: 'BEST VALUE',
-};
-```
-
-### PaywallState
-Manages current paywall state and context.
-
-```typescript
-interface PaywallState {
-  visible: boolean;
-  trigger?: PaywallTrigger;
-  selectedPackage?: string;
-  pendingAction?: () => void;  // Execute after upgrade
-  metadata?: {
-    userId?: string;
-    screen?: string;          // Screen where paywall shown
-    previousScreen?: string;  // Screen before paywall
-  };
-}
-```
-
-**Usage:**
-```typescript
-const state: PaywallState = {
-  visible: true,
-  trigger: {
-    type: 'premium_feature',
-    feature: 'ai_generation',
-    timestamp: Date.now(),
-  },
-  selectedPackage: 'premium_annual',
-  pendingAction: () => executeAIGeneration(),
-  metadata: {
-    userId: 'user-123',
-    screen: 'AIGeneration',
-  },
-};
-```
-
-## Key Operations
-
-### Create Trigger
-```typescript
-function createTrigger(
-  type: PaywallTriggerType,
-  context?: Record<string, any>
-): PaywallTrigger {
-  return {
-    type,
-    context,
-    timestamp: Date.now(),
-  };
-}
-```
-
-### Validate Config
-```typescript
-function validatePaywallConfig(config: PaywallConfig): void {
-  if (!config.title) throw new Error('Title is required');
-  if (!config.packages || config.packages.length === 0) {
-    throw new Error('At least one package is required');
-  }
-  if (config.defaultPackage && !config.packages.find(p => p.identifier === config.defaultPackage)) {
-    throw new Error('Default package must be in packages list');
-  }
-}
-```
-
-## Best Practices
-
-1. **Rich Context**: Include context in triggers for analytics
-2. **Validation**: Validate configurations before use
-3. **Immutability**: Treat entities as immutable values
-4. **Type Safety**: Use strict TypeScript types
-5. **Analytics**: Track all paywall events and triggers
-
-## Related
-
+## Strategy
+This directory contains entities representing paywall configuration, triggers, and display logic with rich context for analytics.
+
+## Restrictions
+
+### REQUIRED
+- Must include context in triggers for analytics
+- Must validate configurations before use
+- Must treat entities as immutable values
+- Must use strict TypeScript types
+
+### PROHIBITED
+- DO NOT create triggers without context
+- DO NOT use unvalidated configurations
+- DO NOT mutate entities after creation
+- DO NOT bypass type safety
+
+### CRITICAL SAFETY
+- All triggers MUST include analytics context
+- All configurations MUST be validated before use
+- All entities MUST be immutable
+- Type safety MUST be maintained
+
+## AI Agent Guidelines
+1. Include rich context in triggers for analytics tracking
+2. Validate all configurations before using them
+3. Treat all entities as immutable values
+4. Use strict TypeScript types for all properties
+5. Track all paywall events and triggers
+6. Provide clear validation error messages
+7. Test entity creation and validation thoroughly
+
+## Related Documentation
 - [Paywall README](../README.md)
 - [PaywallVisibility Hook](../../presentation/hooks/usePaywallVisibility.md)

package/src/domains/paywall/hooks/README.md

@@ -1,129 +1,41 @@
 # Paywall Hooks
 
+## Location
 React hooks for paywall management and subscription upgrades.
 
-## Overview
-
-This directory contains React hooks specifically for paywall functionality.
-
-## Hooks
-
-### usePaywallVisibility
-Manages paywall visibility state.
-
-```typescript
-function usePaywallVisibility(): {
-  showPaywall: boolean;
-  setShowPaywall: (visible: boolean) => void;
-  openPaywall: () => void;
-  closePaywall: () => void;
-}
-```
-
-**Usage:**
-```typescript
-function PaywallWrapper() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
-
-  return (
-    <>
-      <YourApp />
-      <Modal visible={showPaywall} onRequestClose={closePaywall}>
-        <PaywallScreen onClose={closePaywall} />
-      </Modal>
-    </>
-  );
-}
-```
-
-### usePaywallOperations
-Handles paywall purchase operations.
-
-```typescript
-function usePaywallOperations(config: {
-  userId: string | undefined;
-  isAnonymous: boolean;
-  onPaywallClose?: () => void;
-  onPurchaseSuccess?: () => void;
-  onAuthRequired?: () => void;
-}): {
-  handlePurchase: (pkg: Package) => Promise<boolean>;
-  handleRestore: () => Promise<boolean>;
-  pendingPackage: Package | null;
-}
-```
-
-**Usage:**
-```typescript
-function Paywall() {
-  const { handlePurchase, handleRestore } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous: !user,
-    onPurchaseSuccess: () => navigation.goBack(),
-    onAuthRequired: () => showAuthModal(),
-  });
-
-  return (
-    <View>
-      <PackageList onSelectPackage={handlePurchase} />
-      <Button onPress={handleRestore}>Restore</Button>
-    </View>
-  );
-}
-```
-
-## Usage Patterns
-
-### Feature Gating
-```typescript
-function useFeatureGate(feature: string) {
-  const { openPaywall } = usePaywallVisibility();
-  const { isPremium } = usePremium();
-
-  const gateFeature = useCallback(() => {
-    if (!isPremium) {
-      analytics.track('paywall_triggered', { feature });
-      openPaywall();
-      return false;
-    }
-    return true;
-  }, [isPremium, openPaywall]);
-
-  return gateFeature;
-}
-```
-
-### Trigger-Based Paywall
-```typescript
-function useTriggeredPaywall() {
-  const { openPaywall } = usePaywallVisibility();
-
-  const showPaywallForFeature = (feature: string, context?: any) => {
-    openPaywall();
-    // Store trigger context for analytics
-    PaywallTracker.record({
-      type: 'premium_feature',
-      feature,
-      context,
-      timestamp: Date.now(),
-    });
-  };
-
-  return { showPaywallForFeature };
-}
-```
-
-## Best Practices
-
-1. **Centralized State**: Use global paywall visibility
-2. **Auth Integration**: Handle authentication before purchase
-3. **Pending Actions**: Store pending actions for post-purchase
-4. **Analytics**: Track all paywall interactions
-5. **Error Handling**: Handle purchase failures gracefully
-6. **User Context**: Show relevant paywall based on context
-
-## Related
-
+## Strategy
+This directory contains React hooks specifically for paywall functionality with centralized state management and proper analytics tracking.
+
+## Restrictions
+
+### REQUIRED
+- Must use centralized paywall visibility state
+- Must handle authentication before purchase
+- Must store pending actions for post-purchase
+- Must track all paywall interactions
+
+### PROHIBITED
+- DO NOT use local paywall state
+- DO NOT skip authentication checks
+- DO NOT lose pending actions
+- DO NOT skip analytics tracking
+
+### CRITICAL SAFETY
+- Authentication MUST be checked before purchase
+- Pending actions MUST be preserved through purchase flow
+- All interactions MUST be tracked for analytics
+- Purchase failures MUST be handled gracefully
+
+## AI Agent Guidelines
+1. Use global state for paywall visibility management
+2. Handle authentication before initiating purchase
+3. Store pending actions for execution after purchase
+4. Track all paywall interactions for analytics
+5. Handle purchase failures with graceful recovery
+6. Show relevant paywall based on user context
+7. Test all paywall state transitions thoroughly
+
+## Related Documentation
 - [usePaywallVisibility](../../presentation/hooks/usePaywallVisibility.md)
 - [usePaywallOperations](../../presentation/hooks/usePaywallOperations.md)
 - [PremiumGate Hook](../../presentation/hooks/usePremiumGate.md)