@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/domain/entities/README.md

@@ -2,175 +2,49 @@
 
 Core domain entities for subscription management.
 
-## Purpose
-
-Domain entities represent the core business concepts and rules of the subscription system. They are framework-agnostic and contain only business logic.
-
-## Entities
-
-### SubscriptionStatus
-
-Represents the subscription state of a user.
-
-```typescript
-interface SubscriptionStatus {
-  type: SubscriptionStatusType;
-  isActive: boolean;
-  isPremium: boolean;
-  expirationDate: string | null;
-  willRenew: boolean;
-  productId?: string;
-}
-
-type SubscriptionStatusType =
-  | 'unknown'
-  | 'guest'
-  | 'free'
-  | 'premium';
-```
-
-**Usage:**
-```typescript
-import { SubscriptionStatus } from '@umituz/react-native-subscription/domain';
-
-const status = SubscriptionStatus.create({
-  type: 'premium',
-  isActive: true,
-  isPremium: true,
-  expirationDate: '2025-12-31',
-  willRenew: true,
-});
-```
-
-## Design Principles
-
-### 1. Self-Validation
-
-Entities validate themselves on creation:
-
-```typescript
-class SubscriptionStatus {
-  private constructor(data: SubscriptionStatusData) {
-    this.validate(data);
-    // ...
-  }
-
-  private validate(data: SubscriptionStatusData): void {
-    if (data.isPremium && !data.isActive) {
-      throw new ValidationError('Premium users must be active');
-    }
-  }
-}
-```
-
-### 2. Immutable State
-
-Entities cannot be modified after creation:
-
-```typescript
-const status = SubscriptionStatus.create({...});
-// status.isActive = false; // Error: Cannot assign to read-only property
-```
-
-### 3. Business Rules
-
-Business logic is encapsulated in entities:
-
-```typescript
-class SubscriptionStatus {
-  isExpired(): boolean {
-    if (!this.expirationDate) return false;
-    return new Date(this.expirationDate) < new Date();
-  }
-
-  requiresRenewal(): boolean {
-    return this.isPremium && this.expirationDate && this.willRenew;
-  }
-}
-```
-
-## Creating Entities
-
-### Factory Method
-
-```typescript
-const status = SubscriptionStatus.create({
-  type: 'premium',
-  isActive: true,
-  isPremium: true,
-  expirationDate: null,
-  willRenew: false,
-});
-```
-
-### Validation
-
-```typescript
-try {
-  const status = SubscriptionStatus.create({
-    type: 'premium',
-    isActive: false, // Invalid!
-    isPremium: true,
-  });
-} catch (error) {
-  console.error('Validation failed:', error.message);
-}
-```
-
-## Domain Services
-
-Business operations that don't naturally fit in entities:
-
-```typescript
-class SubscriptionDomainService {
-  canUpgrade(currentStatus: SubscriptionStatus): boolean {
-    return !currentStatus.isPremium;
-  }
-
-  calculateDaysUntilExpiry(status: SubscriptionStatus): number | null {
-    if (!status.expirationDate) return null;
-    const diff = new Date(status.expirationDate).getTime() - Date.now();
-    return Math.ceil(diff / (1000 * 60 * 60 * 24));
-  }
-}
-```
-
-## Best Practices
-
-1. **Keep entities pure** - No framework dependencies
-2. **Validate invariants** - Ensure valid state
-3. **Use value objects** - For complex attributes
-4. **Encapsulate logic** - Keep business rules inside entities
-5. **Make immutable** - Prevent direct state modification
-
-## Testing
-
-```typescript
-describe('SubscriptionStatus', () => {
-  it('should create valid premium status', () => {
-    const status = SubscriptionStatus.create({
-      type: 'premium',
-      isActive: true,
-      isPremium: true,
-    });
-
-    expect(status.isPremium).toBe(true);
-  });
-
-  it('should reject invalid premium status', () => {
-    expect(() => {
-      SubscriptionStatus.create({
-        type: 'premium',
-        isActive: false,
-        isPremium: true,
-      });
-    }).toThrow();
-  });
-});
-```
-
-## Related
+## Location
+
+`src/domain/entities/`
+
+## Strategy
+
+Domain entities represent the core business concepts and rules of the subscription system. They are framework-agnostic and contain only business logic, ensuring pure domain modeling.
+
+## Restrictions
+
+### REQUIRED
+
+- MUST validate themselves on creation
+- MUST remain immutable after creation
+- MUST encapsulate business logic internally
+- MUST use value objects for complex attributes
+- MUST be framework-agnostic
+
+### PROHIBITED
+
+- MUST NOT have framework dependencies
+- MUST NOT expose internal state directly
+- MUST NOT allow direct state modification
+- MUST NOT contain infrastructure concerns
+
+### CRITICAL
+
+- Always validate invariants to ensure valid state
+- Prevent direct state modification through immutability
+- Keep business rules encapsulated within entities
+- Maintain purity - no external dependencies
+
+## AI Agent Guidelines
+
+When working with domain entities:
+1. Keep entities pure - no framework dependencies
+2. Validate invariants - ensure valid state
+3. Use value objects - for complex attributes
+4. Encapsulate logic - keep business rules inside entities
+5. Make immutable - prevent direct state modification
+
+## Related Documentation
 
 - [Value Objects](../value-objects/README.md)
 - [Domain Errors](../errors/README.md)
-- [Domain Layer](../../README.md)
+- [Domain Layer](../README.md)

package/src/domain/errors/README.md

@@ -2,306 +2,52 @@
 
 Domain-specific error types for subscription system.
 
-## Purpose
+## Location
 
-Domain errors provide typed, contextual error handling for business logic failures. They make error handling explicit and type-safe.
+`src/domain/errors/`
 
-## Error Hierarchy
+## Strategy
 
-```
-Error (JavaScript)
-└── SubscriptionError (Domain base)
-    ├── SubscriptionValidationError
-    ├── SubscriptionRepositoryError
-    ├── SubscriptionOperationError
-    └── InsufficientCreditsError
-```
+Domain errors provide typed, contextual error handling for business logic failures. They make error handling explicit and type-safe, enabling precise error management.
 
-## Error Types
+## Restrictions
 
-### SubscriptionError
+### REQUIRED
 
-Base error for all subscription-related errors.
+- MUST use specific error types (not generic Error)
+- MUST include contextual information
+- MUST document all error codes
+- MUST handle errors gracefully with user-friendly messages
+- MUST log errors for debugging
+- MUST use type guards for type-safe error handling
 
-```typescript
-class SubscriptionError extends Error {
-  constructor(
-    message: string,
-    public readonly code: string,
-    public readonly context?: Record<string, any>
-  ) {
-    super(message);
-    this.name = 'SubscriptionError';
-  }
-}
-```
+### PROHIBITED
 
-### SubscriptionValidationError
+- MUST NOT swallow errors without handling
+- MUST NOT use generic Error class
+- MUST NOT expose sensitive information in error messages
+- MUST NOT ignore error conditions
 
-Thrown when validation fails.
+### CRITICAL
 
-```typescript
-throw new SubscriptionValidationError('Invalid user ID');
-```
+- Always handle or rethrow errors
+- Include relevant context in error objects
+- Use type guards to enable type-safe error handling
+- Show user-friendly messages while logging technical details
 
-### SubscriptionRepositoryError
+## AI Agent Guidelines
 
-Thrown when repository operations fail.
+When working with domain errors:
+1. Use specific error types - don't use generic Error
+2. Include context - add relevant data to errors
+3. Document error codes - list all possible errors
+4. Handle gracefully - show user-friendly messages
+5. Log errors - track for debugging
+6. Don't swallow errors - always handle or rethrow
+7. Use type guards - enable type-safe error handling
 
-```typescript
-throw new SubscriptionRepositoryError('Database connection failed');
-```
-
-### InsufficientCreditsError
-
-Thrown when user doesn't have enough credits.
-
-```typescript
-throw new InsufficientCreditsError(
-  'Not enough credits',
-  {
-    required: 10,
-    available: 5,
-    featureId: 'export',
-  }
-);
-```
-
-## Usage
-
-### Throwing Errors
-
-```typescript
-function deductCredits(amount: number) {
-  if (amount <= 0) {
-    throw new SubscriptionValidationError(
-      'Amount must be positive',
-      'INVALID_AMOUNT',
-      { amount }
-    );
-  }
-
-  if (currentBalance < amount) {
-    throw new InsufficientCreditsError(
-      'Insufficient credits',
-      {
-        required: amount,
-        available: currentBalance,
-      }
-    );
-  }
-}
-```
-
-### Catching Errors
-
-```typescript
-try {
-  await purchasePackage(packageToPurchase);
-} catch (error) {
-  if (error instanceof InsufficientCreditsError) {
-    console.log(`Need ${error.context.required} credits`);
-    showPaywall();
-  } else if (error instanceof SubscriptionValidationError) {
-    console.error('Validation error:', error.message);
-  } else if (error instanceof SubscriptionError) {
-    console.error('Subscription error:', error.code, error.message);
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Type Guards
-
-```typescript
-function isSubscriptionError(error: unknown): error is SubscriptionError {
-  return error instanceof SubscriptionError;
-}
-
-function isInsufficientCreditsError(error: unknown): error is InsufficientCreditsError {
-  return error instanceof InsufficientCreditsError;
-}
-```
-
-## Error Codes
-
-| Code | Description |
-|------|-------------|
-| `INVALID_USER_ID` | User ID is invalid or missing |
-| `INVALID_PRODUCT_ID` | Product ID is not recognized |
-| `INVALID_AMOUNT` | Amount is invalid (e.g., negative) |
-| `INSUFFICIENT_CREDITS` | User doesn't have enough credits |
-| `SUBSCRIPTION_EXPIRED` | Subscription has expired |
-| `SUBSCRIPTION_NOT_FOUND` | Subscription doesn't exist |
-| `REPOSITORY_ERROR` | Database/repository error |
-| `NETWORK_ERROR` | Network connectivity issue |
-| `PURCHASE_CANCELLED` | User cancelled purchase |
-| `PURCHASE_FAILED` | Purchase operation failed |
-
-## Error Context
-
-Errors can include contextual information:
-
-```typescript
-interface InsufficientCreditsContext {
-  required: number;
-  available: number;
-  featureId?: string;
-  currency?: string;
-}
-
-throw new InsufficientCreditsError(
-  'Insufficient credits',
-  {
-    required: 10,
-    available: 5,
-    featureId: 'export',
-    currency: 'credits',
-  }
-);
-```
-
-## Custom Errors
-
-Create your own domain errors:
-
-```typescript
-class FeatureAccessError extends SubscriptionError {
-  constructor(
-    featureId: string,
-    public readonly requiredTier: UserTier,
-    public readonly currentTier: UserTier
-  ) {
-    super(
-      `Feature "${featureId}" requires ${requiredTier} tier`,
-      'FEATURE_ACCESS_DENIED',
-      { featureId, requiredTier, currentTier }
-    );
-    this.name = 'FeatureAccessError';
-  }
-}
-
-// Usage
-if (!canAccessFeature('advanced_analytics')) {
-  throw new FeatureAccessError(
-    'advanced_analytics',
-    'premium',
-    userTier
-  );
-}
-```
-
-## Error Handling Patterns
-
-### 1. Try-Catch with Type Guards
-
-```typescript
-try {
-  await executeOperation();
-} catch (error) {
-  if (error instanceof InsufficientCreditsError) {
-    handleInsufficientCredits(error);
-  } else if (error instanceof SubscriptionError) {
-    handleSubscriptionError(error);
-  } else {
-    handleUnexpectedError(error);
-  }
-}
-```
-
-### 2. Result Type
-
-```typescript
-type Result<T, E extends Error = Error> =
-  | { success: true; data: T }
-  | { success: false; error: E };
-
-async function deductCredits(
-  amount: number
-): Promise<Result<number, InsufficientCreditsError>> {
-  if (currentBalance < amount) {
-    return {
-      success: false,
-      error: new InsufficientCreditsError('...', {...}),
-    };
-  }
-
-  return { success: true, data: newBalance };
-}
-
-// Usage
-const result = await deductCredits(10);
-if (result.success) {
-  console.log('New balance:', result.data);
-} else {
-  console.error('Error:', result.error.message);
-}
-```
-
-### 3. Error Boundary
-
-```typescript
-class SubscriptionErrorBoundary extends React.Component {
-  state = { hasError: false, error: null };
-
-  static getDerivedStateFromError(error: Error) {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: any) {
-    if (error instanceof SubscriptionError) {
-      analytics().logEvent('subscription_error', {
-        code: error.code,
-        message: error.message,
-      });
-    }
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return <ErrorFallback error={this.state.error} />;
-    }
-
-    return this.props.children;
-  }
-}
-```
-
-## Best Practices
-
-1. **Use specific error types** - Don't use generic Error
-2. **Include context** - Add relevant data to errors
-3. **Document error codes** - List all possible errors
-4. **Handle gracefully** - Show user-friendly messages
-5. **Log errors** - Track for debugging
-6. **Don't swallow errors** - Always handle or rethrow
-7. **Use type guards** - Enable type-safe error handling
-
-## Testing
-
-```typescript
-describe('InsufficientCreditsError', () => {
-  it('should create error with context', () => {
-    const error = new InsufficientCreditsError('Not enough credits', {
-      required: 10,
-      available: 5,
-    });
-
-    expect(error.context.required).toBe(10);
-    expect(error.context.available).toBe(5);
-  });
-
-  it('should be instance of SubscriptionError', () => {
-    const error = new InsufficientCreditsError('...', {...});
-
-    expect(error).toBeInstanceOf(SubscriptionError);
-  });
-});
-```
-
-## Related
+## Related Documentation
 
 - [Domain Entities](../entities/README.md)
 - [Value Objects](../value-objects/README.md)
-- [Domain Layer](../../README.md)
+- [Domain Layer](../README.md)