@umituz/react-native-subscription 2.14.98 → 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

@@ -0,0 +1,52 @@
+# Domains
+
+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)

package/src/domains/README.md.bak

@@ -0,0 +1,274 @@
+# Domains
+
+Specialized domain modules implementing specific business logic and features.
+
+## Location
+
+**Directory**: `src/domains/`
+
+**Type**: Domain Collection
+
+## Strategy
+
+### Domain-Driven Design
+
+This directory implements Domain-Driven Design (DDD) principles:
+
+1. **Wallet Domain**: Credit balance, transactions, and purchase flow
+2. **Paywall Domain**: Upgrade prompts, subscription management
+3. **Config Domain**: Feature flags, subscription configuration
+
+Each domain is self-contained with:
+- **Domain Layer**: Business logic, entities, value objects
+- **Infrastructure Layer**: External integrations, repositories
+- **Presentation Layer**: Domain-specific hooks and components
+
+### Architecture Pattern
+
+```
+┌─────────────────────────────────────┐
+│         Application Layer           │
+│    (Use Cases, Orchestration)       │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────┴────────┐
+       │                │
+┌──────▼──────┐  ┌─────▼──────┐
+│ Wallet      │  │ Paywall    │
+│ Domain      │  │ Domain     │
+├─────────────┤  ├────────────┤
+│ Domain      │  │ Domain     │
+│ Infra       │  │ Infra      │
+│ Presentation│  │ Presentation│
+└──────┬──────┘  └─────┬──────┘
+       │                │
+       └────────┬───────┘
+                │
+       ┌────────▼──────────┐
+       │ Shared Infra      │
+       │ (Firebase, etc)   │
+       └───────────────────┘
+```
+
+## Domain Modules
+
+### Wallet Domain (`wallet/`)
+
+**Responsibility**: Credit balance and transaction management
+
+**Key Features**:
+- Credit balance tracking
+- Transaction history
+- Purchase initialization
+- Real-time updates
+
+**Documentation**: `wallet/README.md`
+
+### Paywall Domain (`paywall/`)
+
+**Responsibility**: Subscription upgrade flows and paywall UI
+
+**Key Features**:
+- Paywall display logic
+- Subscription management
+- Feature gating
+- Upgrade prompts
+
+**Documentation**: `paywall/README.md`
+
+### Config Domain (`config/`)
+
+**Responsibility**: Subscription configuration and feature flags
+
+**Key Features**:
+- Subscription tiers
+- Feature configuration
+- Pricing rules
+- Feature flags
+
+**Documentation**: `config/README.md`
+
+## Restrictions
+
+### REQUIRED
+
+- **Domain Isolation**: Domains MUST NOT directly depend on each other
+- **Interface Segregation**: Use well-defined interfaces between layers
+- **Dependency Inversion**: Depend on abstractions, not concretions
+- **Testability**: All domains MUST be testable in isolation
+
+### PROHIBITED
+
+- **NEVER** share domain logic between domains (use shared kernel if needed)
+- **NEVER** create circular dependencies between domains
+- **DO NOT** bypass domain layer from presentation
+- **NEVER** expose infrastructure details to other domains
+
+### CRITICAL SAFETY
+
+- **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
+
+## Rules
+
+### Domain Boundaries
+
+```typescript
+// CORRECT - Respecting domain boundaries
+// Wallet domain handles credits
+const { credits } = useCredits(); // From wallet domain
+
+// Paywall domain handles upgrades
+const { showPaywall } = usePaywallOperations(); // From paywall domain
+
+// INCORRECT - Crossing domain boundaries
+const walletRepository = new WalletRepository();
+// Directly using wallet repo in paywall component
+```
+
+### Domain Errors
+
+```typescript
+// CORRECT - Domain-specific errors
+class InsufficientCreditsError extends DomainError {
+  constructor(required: number, available: number) {
+    super(`Insufficient credits: need ${required}, have ${available}`);
+  }
+}
+
+// INCORRECT - Generic errors
+throw new Error('Not enough credits'); // Loses domain context
+```
+
+### Dependency Direction
+
+```typescript
+// CORRECT - Dependency inversion
+interface ICreditsRepository {
+  getBalance(userId: string): Promise<number>;
+  deductCredits(userId: string, amount: number): Promise<void>;
+}
+
+// Domain depends on interface, not implementation
+class CreditService {
+  constructor(private repo: ICreditsRepository) {}
+}
+
+// INCORRECT - Concrete dependency
+class CreditService {
+  constructor(private repo: FirebaseCreditsRepository) {}
+  // Tightly coupled to Firebase
+}
+```
+
+## 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
+
+### Integration Checklist
+
+- [ ] Identify correct domain for feature
+- [ ] Respect domain boundaries
+- [ ] Use appropriate interfaces
+- [ ] Handle domain errors
+- [ ] Test domain in isolation
+- [ ] Document domain interactions
+- [ ] Validate invariants
+- [ ] Implement transaction boundaries
+- [ ] Test cross-domain scenarios
+- [ ] Verify no circular dependencies
+
+### Common Patterns
+
+1. **Aggregate Root**: Single entry point for aggregate
+2. **Value Objects**: Immutable values with no identity
+3. **Domain Events**: Publish domain events for side effects
+4. **Repositories**: Abstract data access
+5. **Factories**: Complex object creation
+6. **Domain Services**: Business logic that doesn't fit entities
+7. **Specification**: Business rule encapsulation
+8. **Anti-Corruption Layer**: Isolate from external systems
+
+## 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`
+
+## Domain Structure
+
+```
+src/domains/
+├── wallet/                # Wallet and credits domain
+│   ├── domain/           # Business logic
+│   ├── infrastructure/   # External integrations
+│   └── presentation/     # UI hooks and components
+├── paywall/              # Paywall and upgrades domain
+│   ├── domain/
+│   ├── infrastructure/
+│   └── presentation/
+└── config/               # Configuration domain
+    ├── domain/
+    ├── infrastructure/
+    └── presentation/
+```
+
+## Creating a New Domain
+
+When creating a new domain:
+
+1. **Define Boundaries**: What is the domain's responsibility?
+2. **Identify Entities**: What are the core business objects?
+3. **Define Invariants**: What rules must always be true?
+4. **Design Interfaces**: How will other layers interact?
+5. **Implement Repository**: Abstract data access
+6. **Create Presentation Layer**: Hooks and components
+7. **Write Tests**: Test domain logic in isolation
+8. **Document**: Provide comprehensive README
+
+Example:
+
+```typescript
+// Domain entity
+export class FeatureFlag {
+  constructor(
+    public readonly id: string,
+    public readonly name: string,
+    private _isEnabled: boolean
+  ) {}
+
+  get isEnabled(): boolean {
+    return this._isEnabled;
+  }
+
+  enable(): void {
+    this._isEnabled = true;
+  }
+
+  disable(): void {
+    this._isEnabled = false;
+  }
+}
+
+// Repository interface
+export interface IFeatureFlagRepository {
+  findById(id: string): Promise<FeatureFlag | null>;
+  save(flag: FeatureFlag): Promise<void>;
+}
+
+// Presentation hook
+export function useFeatureFlag(featureId: string) {
+  // Hook implementation
+}
+```