@umituz/react-native-subscription 2.14.98 → 2.14.99

package/src/domains/config/domain/entities/README.md

@@ -0,0 +1,350 @@
+# Config Domain Entities
+
+Domain entities for configuration management.
+
+## Overview
+
+This directory contains entity classes representing configuration concepts like packages, features, and paywalls.
+
+## Entities
+
+### PackageConfig
+
+Represents a subscription package configuration.
+
+**File**: `PackageConfig.ts`
+
+```typescript
+class PackageConfig {
+  readonly identifier: string;
+  readonly productId: string;
+  readonly period: PackagePeriod;
+  readonly price: Money;
+  readonly features: string[];
+  readonly credits?: number;
+  readonly metadata: PackageMetadata;
+
+  // Methods
+  isAnnual(): boolean;
+  isMonthly(): boolean;
+  isLifetime(): boolean;
+  hasCredits(): boolean;
+  isRecommended(): boolean;
+  isHighlighted(): boolean;
+  getPerMonthPrice(): Money | null;
+  getDiscountPercentage(): number | null;
+  getBadge(): string | null;
+}
+```
+
+**Usage:**
+```typescript
+const pkg = new PackageConfig({
+  identifier: 'premium_annual',
+  productId: 'com.app.premium.annual',
+  period: 'annual',
+  price: 79.99,
+  currency: 'USD',
+  features: ['Unlimited Access', 'Ad-Free'],
+  credits: 1200,
+  metadata: {
+    recommended: true,
+    badge: 'Best Value',
+    discount: { percentage: 20, description: 'Save 20%' },
+  },
+});
+
+console.log(pkg.isAnnual()); // true
+console.log(pkg.getPerMonthPrice()?.format()); // '$6.67'
+console.log(pkg.getDiscountPercentage()); // 20
+```
+
+### FeatureConfig
+
+Represents a feature configuration with gating rules.
+
+**File**: `FeatureConfig.ts`
+
+```typescript
+class FeatureConfig {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly requiresPremium: boolean;
+  readonly requiresCredits: boolean;
+  readonly creditCost?: number;
+  readonly enabled: boolean;
+  readonly gateType: 'premium' | 'credits' | 'both';
+
+  // Methods
+  isAccessible(userHasPremium: boolean, userCredits: number): boolean;
+  getRequiredCredits(): number;
+}
+```
+
+**Usage:**
+```typescript
+const feature = new FeatureConfig({
+  id: 'ai_generation',
+  name: 'AI Generation',
+  requiresPremium: false,
+  requiresCredits: true,
+  creditCost: 5,
+  enabled: true,
+  gateType: 'credits',
+});
+
+console.log(feature.isAccessible(false, 10)); // true
+console.log(feature.isAccessible(false, 3)); // false
+console.log(feature.getRequiredCredits()); // 5
+```
+
+### PaywallConfig
+
+Represents a paywall screen configuration.
+
+**File**: `PaywallConfig.ts`
+
+```typescript
+class PaywallConfig {
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly features: string[];
+  readonly packages: PackageConfig[];
+  readonly highlightPackage?: string;
+  readonly style: PaywallStyle;
+  readonly triggers: PaywallTrigger[];
+
+  // Methods
+  getHighlightedPackage(): PackageConfig | null;
+  getPackageByIdentifier(identifier: string): PackageConfig | null;
+  shouldTrigger(triggerType: string): boolean;
+}
+```
+
+**Usage:**
+```typescript
+const paywall = new PaywallConfig({
+  id: 'premium_upgrade',
+  title: 'Upgrade to Premium',
+  features: ['Unlimited Access', 'Ad-Free'],
+  packages: [monthlyPkg, annualPkg],
+  highlightPackage: 'premium_annual',
+  style: {
+    primaryColor: '#007AFF',
+    backgroundColor: '#FFFFFF',
+  },
+  triggers: [{ type: 'credit_gate', enabled: true }],
+});
+
+const highlighted = paywall.getHighlightedPackage();
+console.log(highlighted?.identifier); // 'premium_annual'
+```
+
+### SubscriptionSettingsConfig
+
+Represents subscription settings configuration.
+
+**File**: `SubscriptionSettingsConfig.ts`
+
+```typescript
+class SubscriptionSettingsConfig {
+  readonly showSubscriptionDetails: boolean;
+  readonly showCreditBalance: boolean;
+  readonly allowRestorePurchases: boolean;
+  readonly showManageSubscriptionButton: boolean;
+  readonly subscriptionManagementURL: string;
+  readonly supportEmail: string;
+
+  // Methods
+  getAvailableActions(): string[];
+  isRestoreAllowed(): boolean;
+}
+```
+
+**Usage:**
+```typescript
+const settings = new SubscriptionSettingsConfig({
+  showSubscriptionDetails: true,
+  showCreditBalance: true,
+  allowRestorePurchases: true,
+  showManageSubscriptionButton: true,
+  subscriptionManagementURL: 'https://apps.apple.com/account/subscriptions',
+  supportEmail: 'support@example.com',
+});
+
+console.log(settings.isRestoreAllowed()); // true
+```
+
+## Supporting Types
+
+### PackageMetadata
+
+```typescript
+interface PackageMetadata {
+  highlight?: boolean;
+  recommended?: boolean;
+  discount?: {
+    percentage: number;
+    description: string;
+  };
+  badge?: string;
+}
+```
+
+### PaywallStyle
+
+```typescript
+interface PaywallStyle {
+  primaryColor: string;
+  backgroundColor: string;
+  textColor?: string;
+  image?: string;
+  logo?: string;
+}
+```
+
+### PaywallTrigger
+
+```typescript
+interface PaywallTrigger {
+  type: string;
+  enabled: boolean;
+  conditions?: Record<string, unknown>;
+}
+```
+
+## Factory Functions
+
+### createDefaultPackages
+
+Create default package configurations.
+
+```typescript
+function createDefaultPackages(): PackageConfig[] {
+  return [
+    new PackageConfig({
+      identifier: 'premium_monthly',
+      productId: 'com.app.premium.monthly',
+      period: 'monthly',
+      price: 9.99,
+      currency: 'USD',
+      features: ['Unlimited Access', 'Ad-Free'],
+      credits: 100,
+    }),
+    new PackageConfig({
+      identifier: 'premium_annual',
+      productId: 'com.app.premium.annual',
+      period: 'annual',
+      price: 79.99,
+      currency: 'USD',
+      features: ['Unlimited Access', 'Ad-Free', 'Save 20%'],
+      credits: 1200,
+      metadata: {
+        recommended: true,
+        badge: 'Best Value',
+        discount: { percentage: 20, description: 'Save 20%' },
+      },
+    }),
+  ];
+}
+```
+
+### createDefaultPaywall
+
+Create default paywall configuration.
+
+```typescript
+function createDefaultPaywall(): PaywallConfig {
+  return new PaywallConfig({
+    id: 'default_paywall',
+    title: 'Upgrade to Premium',
+    subtitle: 'Get unlimited access to all features',
+    features: [
+      'Unlimited Access',
+      'Ad-Free Experience',
+      'Priority Support',
+      'Exclusive Features',
+    ],
+    packages: createDefaultPackages(),
+    highlightPackage: 'premium_annual',
+    style: {
+      primaryColor: '#007AFF',
+      backgroundColor: '#FFFFFF',
+    },
+    triggers: [
+      { type: 'premium_feature', enabled: true },
+      { type: 'credit_gate', enabled: true },
+    ],
+  });
+}
+```
+
+## Usage Examples
+
+### Validating Package Configuration
+
+```typescript
+function validatePackage(config: PackageConfigData): boolean {
+  try {
+    new PackageConfig(config);
+    return true;
+  } catch (error) {
+    console.error('Invalid package config:', error.message);
+    return false;
+  }
+}
+```
+
+### Finding Recommended Package
+
+```typescript
+function findRecommendedPackage(packages: PackageConfig[]): PackageConfig | null {
+  return packages.find(pkg => pkg.isRecommended()) ?? null;
+}
+
+const recommended = findRecommendedPackage(packages);
+console.log('Recommended:', recommended?.identifier);
+```
+
+### Filtering Packages by Period
+
+```typescript
+function getPackagesByPeriod(packages: PackageConfig[], period: 'monthly' | 'annual'): PackageConfig[] {
+  return packages.filter(pkg => {
+    if (period === 'monthly') return pkg.isMonthly();
+    if (period === 'annual') return pkg.isAnnual();
+    return false;
+  });
+}
+
+const monthlyPackages = getPackagesByPeriod(packages, 'monthly');
+```
+
+### Checking Feature Access
+
+```typescript
+function canUserAccessFeature(feature: FeatureConfig, user: User): boolean {
+  return feature.isAccessible(user.isPremium, user.credits);
+}
+
+const aiFeature = new FeatureConfig({ /* ... */ });
+const canAccess = canUserAccessFeature(aiFeature, currentUser);
+```
+
+## Best Practices
+
+1. **Validation**: Always validate configuration in constructor
+2. **Immutability**: Never modify entities after creation
+3. **Business Logic**: Keep business logic in entities
+4. **Type Safety**: Use TypeScript strictly
+5. **Error Messages**: Provide clear error messages
+6. **Defaults**: Provide factory functions for defaults
+7. **Testing**: Test validation logic thoroughly
+
+## Related
+
+- [Config Domain](../README.md)
+- [Config Value Objects](../value-objects/README.md)
+- [Config Utils](../../utils/README.md)

package/src/presentation/hooks/useDeductCredit.md

@@ -2,159 +2,175 @@
 
 Hook for deducting credits from user balance with optimistic updates.
 
-## Import
+## Location
 
-```typescript
-import { useDeductCredit } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useDeductCredit.ts`
 
-```typescript
-function useDeductCredit(params: {
-  userId: string | undefined;
-  onCreditsExhausted?: () => void;
-}): {
-  deductCredit: (cost?: number) => Promise<boolean>;
-  deductCredits: (cost: number) => Promise<boolean>;
-  isDeducting: boolean;
-}
-```
+## 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
 
-## Parameters
+- **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
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `userId` | `string \| undefined` | **Required** | User ID for credit deduction |
-| `onCreditsExhausted` | `() => void` | `undefined` | Callback when credits are exhausted |
+### PROHIBITED
 
-## Returns
+- **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)
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `deductCredit` | `(cost?: number) => Promise<boolean>` | Deduct credits (defaults to 1) |
-| `deductCredits` | `(cost: number) => Promise<boolean>` | Deduct specific amount |
-| `isDeducting` | `boolean` | Mutation is in progress |
+### CRITICAL SAFETY
 
-## Basic Usage
+- **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
+
+## Rules
+
+### Initialization
 
 ```typescript
-function CreditButton() {
-  const { user } = useAuth();
-  const { deductCredit, isDeducting } = useDeductCredit({
-    userId: user?.uid,
-    onCreditsExhausted: () => {
-      Alert.alert('Low Credits', 'Please purchase more credits');
-    },
-  });
-
-  const handleUseFeature = async () => {
-    const success = await deductCredit(1);
-    if (success) {
-      executePremiumFeature();
-    }
-  };
-
-  return (
-    <Button onPress={handleUseFeature} disabled={isDeducting}>
-      Use Feature (1 Credit)
-    </Button>
-  );
-}
+// CORRECT
+const { deductCredit, isDeducting } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => showPaywall(),
+});
+
+// INCORRECT - Missing callback
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+});
+
+// INCORRECT - userId undefined
+const { deductCredit } = useDeductCredit({
+  userId: undefined,
+});
 ```
 
-## Advanced Usage
-
-### With Custom Cost
+### Deduction Execution
 
 ```typescript
-function FeatureWithCost() {
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-  });
-
-  const features = {
-    basic: { cost: 1, name: 'Basic Generation' },
-    advanced: { cost: 5, name: 'Advanced Generation' },
-    premium: { cost: 10, name: 'Premium Generation' },
-  };
-
-  const handleFeature = async (cost: number) => {
-    const success = await deductCredit(cost);
-    if (success) {
-      console.log('Feature used');
-    }
-  };
-
-  return (
-    <View>
-      {Object.entries(features).map(([key, { cost, name }]) => (
-        <Button
-          key={key}
-          onPress={() => handleFeature(cost)}
-          title={`${name} (${cost} credits)`}
-        />
-      ))}
-    </View>
-  );
+// CORRECT - Check return value
+const success = await deductCredit(5);
+if (success) {
+  executeFeature();
 }
+
+// INCORRECT - No return value check
+await deductCredit(5);
+executeFeature(); // May execute even if deduction failed
+
+// INCORRECT - Multiple simultaneous calls
+Promise.all([
+  deductCredit(5),
+  deductCredit(3), // Race condition!
+]);
 ```
 
-### With Confirmation
+### Loading States
 
 ```typescript
-function CreditDeductionWithConfirmation() {
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-  });
-
-  const handleActionWithConfirmation = async (cost: number, action: string) => {
-    Alert.alert(
-      'Confirm Action',
-      `This will cost ${cost} credit${cost > 1 ? 's' : ''}. Continue?`,
-      [
-        { text: 'Cancel', style: 'cancel' },
-        {
-          text: 'Confirm',
-          onPress: async () => {
-            const success = await deductCredit(cost);
-            if (success) {
-              await performAction(action);
-            }
-          },
-        },
-      ]
-    );
-  };
-
-  return (
-    <Button
-      onPress={() => handleActionWithConfirmation(5, 'export')}
-      title="Export Data (5 Credits)"
-    />
-  );
-}
+// CORRECT - Respect loading state
+<Button onPress={handleDeduct} disabled={isDeducting}>
+  {isDeducting ? 'Deducting...' : 'Use Feature'}
+</Button>
+
+// INCORRECT - Ignore loading state
+<Button onPress={handleDeduct}>
+  Use Feature
+</Button>
 ```
 
-## Best Practices
+### Credit Exhaustion Handling
+
+```typescript
+// CORRECT - Implement callback
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => {
+    navigation.navigate('CreditPackages');
+  },
+});
+
+// MINIMUM - Show alert
+const { deductCredit } = useDeductCredit({
+  userId: user?.uid,
+  onCreditsExhausted: () => {
+    Alert.alert('No Credits', 'Please purchase more credits');
+  },
+});
+```
+
+## 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
 
-1. **Check balance first** - Show user if they have enough credits
-2. **Handle exhausted credits** - Provide purchase option
-3. **Show loading state** - Disable button during deduction
-4. **Optimistic updates** - UI updates automatically
-5. **Error handling** - Handle deduction failures gracefully
-6. **Confirm expensive actions** - Ask before large deductions
-7. **Clear messaging** - Tell users cost before deducting
+- [ ] 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
 
-## Related Hooks
+### Common Patterns to Implement
 
-- **useCredits** - For accessing credits balance
-- **useCreditsGate** - For gating features with credits
-- **useInitializeCredits** - For initializing credits after purchase
-- **useCreditChecker** - For checking credit availability
+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
 
-## See Also
+## Related Documentation
 
-- [Credits README](../../../domains/wallet/README.md)
-- [Credits Entity](../../../domains/wallet/domain/entities/Credits.md)
-- [Credits Repository](../../../infrastructure/repositories/CreditsRepository.md)
+- **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`