@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/domain/value-objects/README.md

@@ -2,185 +2,49 @@
 
 Value objects for the subscription domain.
 
-## Purpose
-
-Value objects are immutable objects that represent concepts by their attributes rather than identity. They are used to ensure validity and prevent primitive obsession.
-
-## Value Objects
-
-### SubscriptionConfig
-
-Configuration object for subscription system.
-
-```typescript
-interface SubscriptionConfig {
-  revenueCatApiKey: string;
-  revenueCatEntitlementId: string;
-  plans: Record<string, Plan>;
-  defaultPlan: string;
-  features: ConfigFeatures;
-  ui?: ConfigUI;
-  onStatusChanged?: (userId: string, status: SubscriptionStatus) => void;
-  onError?: (error: Error) => void;
-}
-```
-
-**Usage:**
-```typescript
-import { SubscriptionConfig } from '@umituz/react-native-subscription/domain';
-
-const config: SubscriptionConfig = {
-  revenueCatApiKey: 'your_key',
-  revenueCatEntitlementId: 'premium',
-  plans: {
-    monthly: monthlyPlan,
-    annual: annualPlan,
-  },
-  defaultPlan: 'monthly',
-  features: {
-    requireAuth: true,
-    allowRestore: true,
-  },
-};
-```
-
-## Characteristics
-
-### 1. Immutable
-
-```typescript
-const config = SubscriptionConfig.create({...});
-// config.apiKey = 'new_key'; // Error: Cannot assign
-```
-
-### 2. Value-Based Equality
-
-```typescript
-const config1 = SubscriptionConfig.create({...});
-const config2 = SubscriptionConfig.create({...});
-
-config1.equals(config2); // true (if same values)
-```
-
-### 3. Self-Validating
-
-```typescript
-const config = SubscriptionConfig.create({
-  apiKey: '', // Invalid!
-  entitlementId: 'premium',
-});
-// Throws ValidationError
-```
-
-## Creating Value Objects
-
-### Factory Method
-
-```typescript
-const config = SubscriptionConfig.create({
-  apiKey: 'your_key',
-  entitlementId: 'premium',
-});
-```
-
-### Builder Pattern
-
-```typescript
-const config = SubscriptionConfig.builder()
-  .apiKey('your_key')
-  .entitlementId('premium')
-  .addPlan('monthly', monthlyPlan)
-  .addPlan('annual', annualPlan)
-  .build();
-```
-
-## Common Value Objects
-
-### Money
-
-```typescript
-class Money {
-  private constructor(
-    private amount: number,
-    private currency: string
-  ) {}
-
-  static create(amount: number, currency: string): Money {
-    if (amount < 0) throw new Error('Amount cannot be negative');
-    return new Money(amount, currency);
-  }
-
-  format(): string {
-    return new Intl.NumberFormat('en-US', {
-      style: 'currency',
-      currency: this.currency,
-    }).format(this.amount);
-  }
-
-  add(other: Money): Money {
-    if (this.currency !== other.currency) {
-      throw new Error('Cannot add different currencies');
-    }
-    return new Money(this.amount + other.amount, this.currency);
-  }
-}
-```
-
-### DateRange
-
-```typescript
-class DateRange {
-  constructor(
-    private start: Date,
-    private end: Date
-  ) {}
-
-  includes(date: Date): boolean {
-    return date >= this.start && date <= this.end;
-  }
-
-  durationInDays(): number {
-    return Math.ceil(
-      (this.end.getTime() - this.start.getTime()) / (1000 * 60 * 60 * 24)
-    );
-  }
-}
-```
-
-## Best Practices
-
-1. **Make immutable** - All properties readonly
-2. **Validate on creation** - Fail fast
-3. **Override equality** - Compare by value, not reference
-4. **Use for complex attributes** - Don't use for simple primitives
-5. **Keep small** - Value objects should be focused
-
-## Testing
-
-```typescript
-describe('SubscriptionConfig', () => {
-  it('should create valid config', () => {
-    const config = SubscriptionConfig.create({
-      apiKey: 'test_key',
-      entitlementId: 'premium',
-    });
-
-    expect(config.apiKey).toBe('test_key');
-  });
-
-  it('should reject invalid config', () => {
-    expect(() => {
-      SubscriptionConfig.create({
-        apiKey: '',
-        entitlementId: 'premium',
-      });
-    }).toThrow();
-  });
-});
-```
-
-## Related
+## Location
+
+`src/domain/value-objects/`
+
+## Strategy
+
+Value objects are immutable objects that represent concepts by their attributes rather than identity. They ensure validity and prevent primitive obsession by providing type-safe, validated representations.
+
+## Restrictions
+
+### REQUIRED
+
+- MUST be immutable (all properties readonly)
+- MUST validate on creation (fail fast)
+- MUST override equality (compare by value, not reference)
+- MUST use for complex attributes (not simple primitives)
+- MUST be small and focused
+
+### PROHIBITED
+
+- MUST NOT allow mutation after creation
+- MUST NOT use reference equality for comparison
+- MUST NOT contain invalid states
+- MUST NOT have identity-based equality
+
+### CRITICAL
+
+- Always validate on creation
+- Implement value-based equality comparison
+- Keep value objects small and focused
+- Use only for complex attributes, not simple primitives
+
+## AI Agent Guidelines
+
+When working with value objects:
+1. Make immutable - all properties readonly
+2. Validate on creation - fail fast
+3. Override equality - compare by value, not reference
+4. Use for complex attributes - don't use for simple primitives
+5. Keep small - value objects should be focused
+
+## Related Documentation
 
 - [Domain Entities](../entities/README.md)
 - [Domain Errors](../errors/README.md)
-- [Domain Layer](../../README.md)
+- [Domain Layer](../README.md)

package/src/domains/README.md

@@ -1,240 +1,52 @@
 # Domains
 
-This directory contains specialized domain modules that implement specific business logic and features.
-
-## Overview
-
-The `domains` directory organizes business logic into focused, self-contained modules. Each domain follows Domain-Driven Design (DDD) principles and Clean Architecture patterns.
-
-## Domain Modules
-
-### Wallet Domain (`wallet/`)
-
-Manages credits, transactions, and wallet operations.
-
-**Key Features:**
-- Credit balance tracking
-- Transaction history
-- Credit deduction and allocation
-- Purchase initialization
-- Duplicate protection
-
-**Structure:**
-```
-wallet/
-├── domain/              # Business logic and entities
-│   ├── entities/        # UserCredits, Transaction, CreditPackage
-│   ├── types/           # Type definitions
-│   └── mappers/         # Data transformation
-├── infrastructure/      # External integrations
-│   ├── repositories/    # Data persistence
-│   └── services/        # External services
-└── presentation/        # UI layer
-    ├── hooks/           # React hooks
-    ├── components/      # React components
-    └── screens/         # Screen components
-```
-
-**Key Entities:**
-- `UserCredits`: Credit balance and allocations
-- `Transaction`: Credit transaction records
-- `CreditPackage`: Purchasable credit packages
-
-**Allocation Modes:**
-- **ACCUMULATE**: Add credits on renewal (default)
-- **REPLACE**: Replace existing credits with new allocation
-
-**Related:**
-- [Wallet Domain README](./wallet/README.md)
-- [Wallet Entities](./wallet/domain/entities/README.md)
-- [Wallet Hooks](./wallet/presentation/hooks/README.md)
-
-### Paywall Domain (`paywall/`)
-
-Manages paywall display, triggers, and purchase flows.
-
-**Key Features:**
-- Paywall visibility management
-- Trigger-based paywall display
-- Package selection and comparison
-- Purchase operations
-- Feedback collection
-
-**Structure:**
-```
-paywall/
-├── domain/              # Business logic
-│   └── entities/        # PaywallTrigger, PaywallConfig, PaywallState
-├── components/          # UI components
-│   ├── PaywallScreen/
-│   ├── PackageCard/
-│   └── FeatureComparison/
-└── hooks/               # React hooks
-    └── usePaywallOperations/
-```
-
-**Triggers:**
-- `premium_feature`: User attempts premium feature
-- `credit_gate`: Insufficient credits
-- `manual`: Manually triggered
-- `onboarding_complete`: After onboarding
-- `usage_limit`: Reached usage limit
-
-**Related:**
-- [Paywall Domain README](./paywall/README.md)
-- [Paywall Entities](./paywall/entities/README.md)
-- [Paywall Components](./paywall/components/README.md)
-
-### Config Domain (`config/`)
-
-Manages subscription and feature configuration.
-
-**Key Features:**
-- Package configuration
-- Feature flags
-- Subscription settings
-- Paywall customization
-
-**Structure:**
-```
-config/
-├── domain/              # Configuration entities
-│   ├── entities/        # Config entities
-│   └── value-objects/   # Configuration value objects
-└── utils/               # Configuration utilities
-```
-
-**Related:**
-- [Config Domain README](./config/README.md)
-
-## Architecture Principles
-
-### 1. Domain-Driven Design (DDD)
-Each domain represents a distinct business capability with:
-- Clear boundaries
-- Ubiquitous language
-- Domain entities
-- Business rules
-
-### 2. Clean Architecture
-Each domain follows layered architecture:
-- **Domain Layer**: Business logic, entities (pure)
-- **Application Layer**: Use cases, orchestration
-- **Infrastructure Layer**: External integrations (persistence, APIs)
-- **Presentation Layer**: UI components, hooks
-
-### 3. Independence
-Domains are independent and can:
-- Be developed in isolation
-- Have their own data stores
-- Be tested independently
-- Scale independently
-
-### 4. Communication
-Domains communicate through:
-- Well-defined interfaces
-- Events (when needed)
-- Shared kernels (when necessary)
-
-## Usage Patterns
-
-### Using Wallet Domain
-
-```typescript
-import { useCredits } from './wallet/presentation/hooks';
-import { CreditBalanceCard } from './wallet/presentation/components';
-
-function MyComponent() {
-  const { credits, transactions } = useCredits({ userId: user?.uid });
-
-  return (
-    <CreditBalanceCard
-      credits={credits}
-      balance={calculateBalance(credits)}
-    />
-  );
-}
-```
-
-### Using Paywall Domain
-
-```typescript
-import { usePaywallOperations } from './paywall/hooks';
-
-function MyScreen() {
-  const { handlePurchase } = usePaywallOperations({
-    userId: user?.uid,
-    isAnonymous: false,
-  });
-
-  const onBuyPress = () => {
-    handlePurchase(selectedPackage);
-  };
-}
-```
-
-### Using Config Domain
-
-```typescript
-import { getPackageConfiguration } from './config/utils';
-
-const packages = getPackageConfiguration('premium');
-```
-
-## Adding New Domains
-
-When adding a new domain:
-
-1. **Create Domain Structure**
-```bash
-src/domains/your-domain/
-├── domain/
-│   ├── entities/
-│   ├── value-objects/
-│   └── types/
-├── infrastructure/
-│   ├── repositories/
-│   └── services/
-└── presentation/
-    ├── hooks/
-    ├── components/
-    └── screens/
-```
-
-2. **Define Entities**
-   - Create core business entities
-   - Define business rules
-   - Implement validations
-
-3. **Implement Infrastructure**
-   - Create repositories for data persistence
-   - Implement external service integrations
-   - Add mappers for data transformation
-
-4. **Create Presentation Layer**
-   - Implement React hooks
-   - Create UI components
-   - Build screens
-
-5. **Add Documentation**
-   - Create README for domain
-   - Document entities
-   - Provide usage examples
-
-## Best Practices
-
-1. **Encapsulation**: Keep domain logic isolated
-2. **Purity**: Domain layer should have no external dependencies
-3. **Interfaces**: Depend on abstractions, not concretions
-4. **Testing**: Each domain should be independently testable
-5. **Documentation**: Document business rules and entities
-6. **Type Safety**: Use TypeScript for all domain models
-7. **Validation**: Validate at domain boundaries
-8. **Error Handling**: Use domain-specific errors
-
-## Related
-
-- [Domain Layer README](../domain/README.md)
-- [Application Layer README](../application/README.md)
-- [Infrastructure Layer README](../infrastructure/README.md)
-- [RevenueCat Integration README](../revenuecat/README.md)
+Specialized domain modules implementing specific business logic and features.
+
+## Location
+
+`src/domains/`
+
+## Strategy
+
+Implements Domain-Driven Design (DDD) principles with self-contained domains. Each domain includes domain layer (business logic, entities, value objects), infrastructure layer (external integrations, repositories), and presentation layer (domain-specific hooks and components).
+
+## Restrictions
+
+### REQUIRED
+
+- Domains MUST NOT directly depend on each other
+- MUST use well-defined interfaces between layers
+- MUST depend on abstractions, not concretions (Dependency Inversion)
+- All domains MUST be testable in isolation
+
+### PROHIBITED
+
+- MUST NOT share domain logic between domains (use shared kernel if needed)
+- MUST NOT create circular dependencies between domains
+- MUST NOT bypass domain layer from presentation
+- MUST NOT expose infrastructure details to other domains
+
+### CRITICAL
+
+- Always validate invariants at domain boundaries
+- Always implement domain errors for business rule violations
+- Never allow inconsistent domain state
+- Must implement proper transaction boundaries
+- Always sanitize inputs from external sources
+
+## AI Agent Guidelines
+
+When working with domains:
+1. Always respect domain boundaries
+2. Always use dependency inversion
+3. Always implement domain-specific errors
+4. Always validate invariants at boundaries
+5. Never create circular dependencies
+
+## Related Documentation
+
+- [Wallet Domain](wallet/README.md)
+- [Paywall Domain](paywall/README.md)
+- [Config Domain](config/README.md)
+- [Domain Layer](../domain/README.md)
+- [Infrastructure](../infrastructure/README.md)