@umituz/react-native-subscription 2.14.97 → 2.14.99

package/src/domains/paywall/components/PaywallHeader.tsx

@@ -1,11 +1,11 @@
 /**
  * Paywall Header
- * Header with gradient, close button, title and subtitle
+ * Header with background, close button, title and subtitle
  */
 
 import React from "react";
 import { View, StyleSheet, TouchableOpacity } from "react-native";
-import { LinearGradient } from "expo-linear-gradient";
+
 import {
     AtomicText,
     AtomicIcon,
@@ -25,16 +25,13 @@ export const PaywallHeader: React.FC<PaywallHeaderProps> = React.memo(
         const { themeMode } = useDesignSystemTheme();
         const isDark = themeMode === "dark";
 
-        const gradientColors: readonly [string, string] = isDark
-            ? [tokens.colors.surface, tokens.colors.surfaceSecondary]
-            : [tokens.colors.primary, tokens.colors.primaryDark];
+        const backgroundColor = isDark
+            ? tokens.colors.surface
+            : tokens.colors.primary;
 
         return (
-            <LinearGradient
-                colors={gradientColors}
-                start={{ x: 0, y: 0 }}
-                end={{ x: 1, y: 1 }}
-                style={styles.container}
+            <View
+                style={[styles.container, { backgroundColor }]}
             >
                 <TouchableOpacity
                     onPress={onClose}
@@ -66,7 +63,7 @@ export const PaywallHeader: React.FC<PaywallHeaderProps> = React.memo(
                 </View>
 
                 <View style={[styles.wave, { backgroundColor: tokens.colors.background }]} />
-            </LinearGradient>
+            </View>
         );
     }
 );

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

@@ -0,0 +1,185 @@
+# Paywall Components
+
+UI components for displaying paywalls and upgrade prompts.
+
+## Overview
+
+This directory contains React Native components for rendering paywall screens and upgrade prompts.
+
+## Components
+
+### PaywallScreen
+Main paywall screen with package selection.
+
+```typescript
+function PaywallScreen() {
+  const { packages, isLoading } = useSubscriptionPackages();
+  const { handlePurchase, handleRestore } = usePaywallOperations({
+    userId: user?.uid,
+    isAnonymous: !user,
+  });
+
+  if (isLoading) return <LoadingScreen />;
+
+  return (
+    <ScrollView>
+      <PaywallHeader />
+
+      {packages.map((pkg) => (
+        <PackageCard
+          key={pkg.identifier}
+          package={pkg}
+          onPress={() => handlePurchase(pkg)}
+        />
+      ))}
+
+      <RestoreButton onPress={handleRestore} />
+    </ScrollView>
+  );
+}
+```
+
+### PackageCard
+Individual subscription package display card.
+
+```typescript
+interface PackageCardProps {
+  package: PaywallPackage;
+  selected?: boolean;
+  onPress: () => void;
+  popular?: boolean;
+}
+```
+
+**Features:**
+- Highlight popular packages
+- Show price and period
+- Display features list
+- Show savings (for annual)
+- Visual selection indicator
+
+### PaywallModal
+Modal-style paywall overlay.
+
+```typescript
+interface PaywallModalProps {
+  visible: boolean;
+  onClose: () => void;
+  onPurchase: (pkg: Package) => void;
+  configuration: PaywallConfig;
+}
+```
+
+**Usage:**
+```typescript
+<PaywallModal
+  visible={showPaywall}
+  onClose={() => setShowPaywall(false)}
+  onPurchase={handlePurchase}
+  configuration={{
+    title: 'Upgrade to Premium',
+    features: ['Unlimited access', 'Ad-free'],
+    packages: packages,
+  }}
+/>
+```
+
+### PremiumFeatureLock
+Locked feature indicator that prompts upgrade.
+
+```typescript
+interface PremiumFeatureLockProps {
+  feature: string;
+  onPress: () => void;
+  icon?: string;
+  message?: string;
+}
+```
+
+**Usage:**
+```typescript
+<PremiumFeatureLock
+  feature="AI Generation"
+  onPress={() => showPaywall({ type: 'premium_feature', feature: 'ai_generation' })}
+  message="Upgrade to generate unlimited content"
+  icon="lock"
+/>
+```
+
+## Usage Patterns
+
+### With Navigation
+```typescript
+function navigateToPaywall(trigger: PaywallTrigger) {
+  navigation.navigate('Paywall', { trigger });
+}
+
+// In paywall screen
+const { trigger } = route.params;
+const config = getPaywallConfig(trigger.type);
+```
+
+### With Inline Paywall
+```typescript
+function InlinePaywall({ onUpgrade, onDismiss }) {
+  return (
+    <Card>
+      <Image source={premiumIllustration} />
+      <Title>Unlock Premium Features</Title>
+      <FeaturesList features={premiumFeatures} />
+      <Button onPress={onUpgrade}>Upgrade Now</Button>
+      <Link onPress={onDismiss}>Maybe Later</Link>
+    </Card>
+  );
+}
+```
+
+### With Context
+```typescript
+function ContextualPaywall({ feature, context }) {
+  const { packages } = useSubscriptionPackages();
+
+  return (
+    <PaywallScreen
+      title={`Unlock ${feature}`}
+      subtitle={`You need Premium to use ${feature}`}
+      highlightPackage={context.recommendedPackage}
+      packages={packages}
+    />
+  );
+}
+```
+
+## Styling
+
+Components use design tokens for consistent styling:
+
+```typescript
+import { useAppDesignTokens } from '@umituz/react-native-design-system';
+
+const tokens = useAppDesignTokens();
+
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: tokens.colors.surface,
+    borderRadius: tokens.radius.lg,
+    padding: tokens.spacing.lg,
+  },
+});
+```
+
+## Best Practices
+
+1. **Clear Value**: Communicate premium benefits clearly
+2. **Visual Hierarchy**: Highlight recommended package
+3. **Social Proof**: Show user counts or testimonials
+4. **Easy Dismissal**: Allow users to close when appropriate
+5. **Smooth Purchase**: Make purchase flow simple
+6. **Loading States**: Show appropriate loading indicators
+7. **Error Handling**: Handle purchase failures gracefully
+
+## Related
+
+- [Paywall README](../README.md)
+- [PaywallVisibility Hook](../../hooks/usePaywallVisibility.md)
+- [Premium Components](../../components/details/README.md)

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

@@ -0,0 +1,199 @@
+# Paywall Entities
+
+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
+
+- [Paywall README](../README.md)
+- [PaywallVisibility Hook](../../presentation/hooks/usePaywallVisibility.md)

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

@@ -0,0 +1,129 @@
+# Paywall Hooks
+
+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
+
+- [usePaywallVisibility](../../presentation/hooks/usePaywallVisibility.md)
+- [usePaywallOperations](../../presentation/hooks/usePaywallOperations.md)
+- [PremiumGate Hook](../../presentation/hooks/usePremiumGate.md)