@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/domains/paywall/README.md

@@ -1,371 +1,101 @@
 # Paywall Domain
 
-Abonelik ve kredi satın alımı için kullanıcı dostu ödeme duvarı (paywall) bileşenleri ve hooks.
-
-## Özellikler
-
-- **Hazır Paywall Bileşenleri**: Önceden tasarlanmış, özelleştirilebilir paywall UI'ları
-- **Modal ve Full-Screen Desteği**: Modal veya tam ekran paywall seçenekleri
-- **Çoklu Dil Desteği**: Built-in i18n desteği
-- **A/B Test Hazır**: Farklı paywall varyantları kolayca oluşturulabilir
-- **Analytics Entegrasyonu**: Kullanıcı davranışlarını takip edin
-
-## Kurulum
-
-### Temel Konfigürasyon
-
-```typescript
-import { SubscriptionProvider } from '@umituz/react-native-subscription';
-
-function App() {
-  return (
-    <SubscriptionProvider
-      config={{
-        revenueCatApiKey: 'your_api_key',
-        entitlementId: 'premium',
-      }}
-    >
-      {/* Your app */}
-    </SubscriptionProvider>
-  );
-}
-```
-
-## Kullanım
-
-### PaywallModal
-
-Modal paywall gösterimi için:
-
-```typescript
-import { PaywallModal } from '@umituz/react-native-subscription';
-
-function MyComponent() {
-  const [isVisible, setIsVisible] = useState(false);
-
-  return (
-    <>
-      <Button onPress={() => setIsVisible(true)} title="Upgrade to Premium" />
-
-      <PaywallModal
-        isVisible={isVisible}
-        onClose={() => setIsVisible(false)}
-        config={{
-          title: 'Unlock Premium Features',
-          description: 'Get unlimited access to all features',
-          features: [
-            { icon: 'star', text: 'Unlimited credits' },
-            { icon: 'zap', text: 'AI-powered tools' },
-            { icon: 'shield', text: 'Ad-free experience' },
-          ],
-        }}
-      />
-    </>
-  );
-}
-```
-
-### usePaywall Hook
-
-Paywall görünürlüğünü ve davranışlarını kontrol etmek için:
-
-```typescript
-import { usePaywall } from '@umituz/react-native-subscription';
-
-function PremiumFeature() {
-  const { showPaywall, hidePaywall, isPaywallVisible } = usePaywall();
-
-  const handleUpgradeClick = () => {
-    showPaywall({
-      trigger: 'premium_button',
-      featureId: 'ai_tools',
-    });
-  };
-
-  return (
-    <View>
-      <Text>Premium Feature</Text>
-      <Button onPress={handleUpgradeClick} title="Unlock" />
-    </View>
-  );
-}
-```
-
-### usePaywallActions Hook
-
-Paywall aksiyonları için:
-
-```typescript
-import { usePaywallActions } from '@umituz/react-native-subscription';
-
-function PaywallHandler() {
-  const { handlePurchase, handleRestore, isLoading } = usePaywallActions();
-
-  return (
-    <View>
-      <Button
-        onPress={handlePurchase}
-        disabled={isLoading}
-        title="Subscribe Now"
-      />
-      <Button onPress={handleRestore} title="Restore Purchase" />
-    </View>
-  );
-}
-```
-
-### useSubscriptionModal Hook
-
-Subscription modal yönetimi için:
-
-```typescript
-import { useSubscriptionModal } from '@umituz/react-native-subscription';
-
-function SubscriptionButton() {
-  const { openModal, closeModal, isModalOpen } = useSubscriptionModal();
-
-  return (
-    <>
-      <Button onPress={openModal} title="View Plans" />
-      <SubscriptionModal
-        isOpen={isModalOpen}
-        onClose={closeModal}
-      />
-    </>
-  );
-}
-```
-
-## Bileşenler
-
-### PaywallContainer
-
-Paywall içerik wrapper'ı:
-
-```typescript
-import { PaywallContainer } from '@umituz/react-native-subscription';
-
-<PaywallContainer
-  config={{
-    theme: 'dark',
-    showCloseButton: true,
-    closeOnBackdropPress: false,
-  }}
->
-  {/* Paywall content */}
-</PaywallContainer>
-```
-
-### PaywallScreen
-
-Tam ekran paywall:
-
-```typescript
-import { PaywallScreen } from '@umituz/react-native-subscription';
-
-<PaywallScreen
-  packages={subscriptionPackages}
-  onPackageSelect={handlePackageSelect}
-  config={{
-    highlightPackage: 'annual',
-    showPerks: true,
-    showTerms: true,
-  }}
-  translations={{
-    title: 'Choose Your Plan',
-    subtitle: 'Cancel anytime',
-    terms: 'Terms & Privacy Policy',
-  }}
-/>
-```
-
-## Hooks Referansı
-
-### usePaywall
-
-```typescript
-const {
-  showPaywall,      // Paywall göster
-  hidePaywall,      // Paywall gizle
-  isPaywallVisible, // Paywall görünürlük durumu
-  paywallConfig,    // Mevcut konfigürasyon
-} = usePaywall();
-```
-
-### usePaywallActions
-
-```typescript
-const {
-  handlePurchase,     // Satın alma işlemi
-  handleRestore,      // Satın alma geri yükleme
-  isLoading,          // Yüklenme durumu
-  error,             // Hata mesajı
-  selectedPackage,   // Seçili paket
-} = usePaywallActions();
-```
-
-### usePaywallTranslations
-
-```typescript
-const {
-  translations,      // Çeviri objeleri
-  t,                // Çeviri fonksiyonu
-  isLoading,        // Yüklenme durumu
-} = usePaywallTranslations({
-  language: 'tr',
-  fallbackLanguage: 'en',
-});
-```
-
-## Özelleştirme
-
-### Tema Konfigürasyonu
-
-```typescript
-const customTheme = {
-  colors: {
-    primary: '#FF6B6B',
-    background: '#1A1A1A',
-    text: '#FFFFFF',
-    textSecondary: '#A0A0A0',
-  },
-  fonts: {
-    title: { fontSize: 28, fontWeight: 'bold' },
-    body: { fontSize: 16, fontWeight: 'normal' },
-  },
-};
-
-<PaywallModal theme={customTheme} />
-```
-
-### Özel Feature Listesi
-
-```typescript
-const customFeatures = [
-  {
-    id: 'feature1',
-    icon: 'rocket',
-    title: 'AI-Powered Tools',
-    description: 'Advanced AI features',
-    highlight: true,
-  },
-  {
-    id: 'feature2',
-    icon: 'infinity',
-    title: 'Unlimited Credits',
-    description: 'Never run out of credits',
-  },
-];
-
-<PaywallScreen features={customFeatures} />
-```
-
-## Event Tracking
-
-Analytics entegrasyonu için:
-
-```typescript
-import { usePaywallFeedback } from '@umituz/react-native-subscription';
-
-function PaywallWithTracking() {
-  const { trackEvent, trackPurchase, trackDismiss } = usePaywallFeedback();
-
-  useEffect(() => {
-    trackEvent('paywall_impression', {
-      source: 'home_screen',
-    });
-  }, []);
-
-  const handlePurchase = async () => {
-    await purchasePackage();
-    trackPurchase('premium_monthly', {
-      revenue: 9.99,
-      currency: 'USD',
-    });
-  };
-
-  const handleClose = () => {
-    trackDismiss('paywall_closed', {
-      duration: 30, // seconds
-    });
-    closeModal();
-  };
-}
-```
-
-## Best Practices
-
-1. **Trigger Bazlı Gösterim**: Farklı trigger'lar için farklı paywall'lar kullanın
-2. **A/B Test**: Farklı varyasyonları test edin
-3. **Analytics**: Kullanıcı davranışlarını takip edin
-4. **Copywriting**: Farklı dillerde optimize edilmiş copy kullanın
-5. **Loading States**: Satın alma sırasında loading gösterin
-6. **Error Handling**: Hataları kullanıcı dostu mesajlarla gösterin
-
-## Örnek Uygulama
-
-```typescript
-import React, { useState } from 'react';
-import { View, Button } from 'react-native';
-import {
-  PaywallModal,
-  usePaywall,
-  usePaywallActions,
-} from '@umituz/react-native-subscription';
-
-export default function PaywallExample() {
-  const { isPaywallVisible, showPaywall, hidePaywall } = usePaywall();
-  const { handlePurchase, isLoading } = usePaywallActions();
-
-  return (
-    <View>
-      <Button
-        onPress={() => showPaywall({ trigger: 'upgrade_button' })}
-        title="Upgrade to Premium"
-      />
-
-      <PaywallModal
-        isVisible={isPaywallVisible}
-        onClose={hidePaywall}
-        config={{
-          title: 'Go Premium',
-          description: 'Unlock all features',
-          features: [
-            { icon: 'star', text: 'Unlimited access' },
-            { icon: 'zap', text: 'AI features' },
-            { icon: 'shield', text: 'No ads' },
-          ],
-        }}
-        onPurchase={handlePurchase}
-        isLoading={isLoading}
-      />
-    </View>
-  );
-}
-```
-
-## Tip Tanımlamaları
-
-```typescript
-interface PaywallConfig {
-  title?: string;
-  description?: string;
-  features?: PaywallFeature[];
-  theme?: 'light' | 'dark';
-  showCloseButton?: boolean;
-  closeOnBackdropPress?: boolean;
-}
-
-interface PaywallFeature {
-  icon: string;
-  text: string;
-  description?: string;
-  highlight?: boolean;
-}
-
-interface PaywallTrigger {
-  trigger: string;
-  featureId?: string;
-  source?: string;
-}
-```
+Subscription and credit purchase flow with user-friendly payment wall components and hooks.
+
+## Location
+
+- **Base Path**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/domains/paywall/`
+- **Entities**: `src/domains/paywall/entities/`
+- **Components**: `src/domains/paywall/components/`
+- **Hooks**: `src/domains/paywall/hooks/`
+
+## Strategy
+
+### Paywall Management
+
+Centralized paywall system for subscription and credit purchase flows.
+
+- **Modal and Full-Screen Support**: Flexible paywall display options
+- **Multi-language Support**: Built-in i18n capabilities
+- **A/B Test Ready**: Easy creation of different paywall variants
+- **Analytics Integration**: User behavior tracking capabilities
+
+### Component Architecture
+
+Ready-to-use paywall components with customization support.
+
+- **PaywallModal**: Modal-based paywall display
+- **PaywallContainer**: Paywall content wrapper
+- **PaywallScreen**: Full-screen paywall implementation
+- **Feature Lists**: Customizable feature display components
+
+### Hook Integration
+
+Hooks for paywall state and behavior management.
+
+- **usePaywall**: Paywall visibility and state control
+- **usePaywallActions**: Purchase and restore action handling
+- **usePaywallTranslations**: Translation management
+- **useSubscriptionModal**: Subscription modal management
+
+### Configuration Strategy
+
+Theme and content customization system.
+
+- **Theme Configuration**: Custom color schemes and styling
+- **Feature Lists**: Customizable feature display
+- **Translation Support**: Multi-language copy management
+- **Event Tracking**: Analytics integration points
+
+## Restrictions
+
+### REQUIRED
+
+- **Paywall Context**: All paywall components must be used within SubscriptionProvider
+- **Config Validation**: Paywall configuration must be validated before use
+- **Error Handling**: All paywall actions must have error handling
+- **Loading States**: Purchase operations must show loading indicators
+
+### PROHIBITED
+
+- **Hardcoded Strings**: All text must support translations
+- **Direct RevenueCat Calls**: Use paywall hooks instead of direct SDK calls
+- **Missing Analytics**: All paywall interactions must be tracked
+- **Blocking UI**: Never block app flow without escape options
+
+### CRITICAL
+
+- **User Experience**: Paywalls must be dismissible
+- **Purchase Flow**: Complete purchase flow must be handled
+- **Error Recovery**: Graceful error handling required
+- **State Management**: Paywall state must be properly managed
+
+## AI Agent Guidelines
+
+### When Modifying Paywall Components
+
+1. **Maintain UX Standards**: Keep user experience consistent
+2. **Test All States**: Test loading, success, and error states
+3. **Analytics Integration**: Add tracking for new interactions
+4. **Translation Support**: All new text must be translatable
+
+### When Adding New Paywall Features
+
+1. **Hook Pattern**: Create corresponding hook for new features
+2. **Type Safety**: Define proper TypeScript types
+3. **Documentation**: Document all props and usage
+4. **Testing**: Test with different subscription states
+
+### When Fixing Paywall Bugs
+
+1. **RevenueCat Integration**: Check RevenueCat SDK integration
+2. **State Management**: Verify state transitions
+3. **Edge Cases**: Test with null/undefined states
+4. **User Flows**: Test complete purchase flows
+
+## Related Documentation
+
+- [RevenueCat Integration](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/revenuecat/README.md)
+- [Config Domain](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/domains/config/README.md)
+- [Wallet Domain](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/domains/wallet/README.md)
+- [Presentation Components](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/presentation/components/README.md)

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

@@ -1,185 +1,41 @@
 # Paywall Components
 
+## Location
 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
-
+## Strategy
+This directory contains React Native components for rendering paywall screens and upgrade prompts with clear value communication and smooth purchase flow.
+
+## Restrictions
+
+### REQUIRED
+- Must communicate premium benefits clearly
+- Must highlight recommended package
+- Must allow dismissal when appropriate
+- Must show appropriate loading indicators
+
+### PROHIBITED
+- DO NOT obscure purchase flow
+- DO NOT hide pricing information
+- DO NOT prevent appropriate dismissal
+- DO NOT show technical errors to users
+
+### CRITICAL SAFETY
+- Pricing information MUST be clear and accurate
+- Purchase flow MUST be simple and straightforward
+- Loading states MUST be visible during operations
+- Purchase failures MUST be handled gracefully
+
+## AI Agent Guidelines
+1. Communicate premium benefits clearly to users
+2. Highlight recommended package with visual hierarchy
+3. Show social proof (user counts, testimonials) when available
+4. Allow users to dismiss paywall when appropriate
+5. Make purchase flow simple and straightforward
+6. Show loading indicators during async operations
+7. Handle purchase failures with user-friendly messages
+
+## Related Documentation
 - [Paywall README](../README.md)
 - [PaywallVisibility Hook](../../hooks/usePaywallVisibility.md)
 - [Premium Components](../../components/details/README.md)