@umituz/react-native-subscription 2.14.99 → 2.14.100

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

@@ -1,122 +1,41 @@
 # Wallet Domain Entities
 
+## Location
 Core entities for credits and transaction management.
 
-## Overview
-
-This directory contains domain entities representing credits, transactions, and wallet-related business concepts.
-
-## Entities
-
-### UserCredits
-Represents user's credit balance and metadata.
-
-```typescript
-interface UserCredits {
-  credits: number;           // Current credit balance
-  purchasedAt: Date;         // When credits were purchased
-  lastUpdatedAt: Date;      // Last update timestamp
-}
-
-interface CreditsResult {
-  success: boolean;
-  data?: UserCredits;
-  error?: {
-    code: string;
-    message: string;
-  };
-  duplicate?: boolean;       // If this was a duplicate operation
-}
-```
-
-**Usage:**
-```typescript
-const credits: UserCredits = {
-  credits: 100,
-  purchasedAt: new Date('2024-01-01'),
-  lastUpdatedAt: new Date('2024-01-15'),
-};
-```
-
-### Transaction
-Represents a credit transaction record.
-
-```typescript
-interface Transaction {
-  id: string;
-  amount: number;           // Positive for additions, negative for deductions
-  reason: string;           // Description of transaction
-  timestamp: Date;          // When transaction occurred
-  type: TransactionType;    // Transaction category
-}
-
-type TransactionType =
-  | 'purchase'      // Initial purchase
-  | 'deduction'     // Feature usage
-  | 'bonus'         // Bonus credits
-  | 'renewal'       // Subscription renewal
-  | 'adjustment';   // Manual adjustment
-```
-
-**Usage:**
-```typescript
-const transaction: Transaction = {
-  id: 'tx_123',
-  amount: -5,
-  reason: 'ai_generation',
-  timestamp: new Date(),
-  type: 'deduction',
-};
-```
-
-### CreditPackage
-Represents a credit package for purchase.
-
-```typescript
-interface CreditPackage {
-  id: string;
-  amount: number;           // Number of credits
-  price: number;            // Price in currency units
-  currency: string;         // Currency code (USD, EUR, etc.)
-  description?: string;
-}
-```
-
-## Key Operations
-
-### Check Balance
-```typescript
-function hasEnoughCredits(credits: UserCredits, required: number): boolean {
-  return credits.credits >= required;
-}
-```
-
-### Calculate Remaining
-```typescript
-function calculateRemaining(credits: UserCredits, spent: number): number {
-  return Math.max(0, credits.credits - spent);
-}
-```
-
-### Validate Credits
-```typescript
-function validateCredits(amount: number): void {
-  if (amount < 0) {
-    throw new Error('Credits cannot be negative');
-  }
-}
-```
-
-## Best Practices
-
-1. **Immutability**: Treat entities as immutable values
-2. **Validation**: Validate in entity methods
-3. **Type Safety**: Use strict TypeScript types
-4. **Business Rules**: Keep business logic in entities
-5. **Serialization**: Handle date serialization properly
-
-## Related
-
+## Strategy
+This directory contains domain entities representing credits, transactions, and wallet-related business concepts with strict immutability and validation.
+
+## Restrictions
+
+### REQUIRED
+- Must treat entities as immutable values
+- Must validate in entity methods
+- Must use strict TypeScript types
+- Must keep business logic in entities
+
+### PROHIBITED
+- DO NOT mutate entities after creation
+- DO NOT bypass validation methods
+- DO NOT leak entity internals
+- DO NOT allow invalid state
+
+### CRITICAL SAFETY
+- All entities MUST be immutable
+- Validation MUST be performed in entity methods
+- Date serialization MUST be handled properly
+- Business rules MUST be enforced in entities
+
+## AI Agent Guidelines
+1. Treat all entities as immutable values
+2. Perform validation within entity methods
+3. Use strict TypeScript types for all properties
+4. Keep business logic encapsulated in entities
+5. Handle date serialization properly for transactions
+6. Implement proper equality methods
+7. Provide clear validation error messages
+
+## Related Documentation
 - [Wallet Domain](../README.md)
 - [Credits Repository](../../infrastructure/repositories/README.md)
 - [useCredits Hook](../../../../presentation/hooks/useCredits.md)

package/src/domains/wallet/domain/errors/README.md

@@ -1,157 +1,40 @@
 # Wallet Domain Errors
 
+## Location
 Domain-specific errors for wallet and credit operations.
 
-## Overview
-
-This directory contains custom error classes representing wallet-related error conditions.
-
-## Error Types
-
-### CreditsExhaustedError
-Thrown when user doesn't have enough credits for an operation.
-
-```typescript
-class CreditsExhaustedError extends Error {
-  constructor(
-    public currentBalance: number,
-    public required: number
-  ) {
-    super(
-      `Insufficient credits: ${currentBalance}/${required} required`,
-      'CREDITS_EXHAUSTED'
-    );
-    this.name = 'CreditsExhaustedError';
-  }
-}
-```
-
-**Usage:**
-```typescript
-import { CreditsExhaustedError } from './errors/CreditsExhaustedError';
-
-function deductCredits(credits: UserCredits, amount: number) {
-  if (credits.credits < amount) {
-    throw new CreditsExhaustedError(credits.credits, amount);
-  }
-  // Proceed with deduction
-}
-```
-
-### DuplicatePurchaseError
-Thrown when attempting to add credits for a duplicate purchase ID.
-
-```typescript
-class DuplicatePurchaseError extends Error {
-  constructor(
-    public purchaseId: string,
-    public existingCredits: UserCredits
-  ) {
-    super(
-      `Duplicate purchase ID: ${purchaseId}`,
-      'DUPLICATE_PURCHASE'
-    );
-    this.name = 'DuplicatePurchaseError';
-  }
-}
-```
-
-**Usage:**
-```typescript
-try {
-  await repository.initializeCredits(userId, purchaseId);
-} catch (error) {
-  if (error instanceof DuplicatePurchaseError) {
-    console.log('Credits already added for this purchase');
-  }
-}
-```
-
-### CreditsValidationError
-Thrown when credit validation fails.
-
-```typescript
-class CreditsValidationError extends Error {
-  constructor(
-    message: string,
-    public code: string
-  ) {
-    super(message, code);
-    this.name = 'CreditsValidationError';
-  }
-}
-```
-
-**Usage:**
-```typescript
-function validateCreditAmount(amount: number) {
-  if (amount < 0) {
-    throw new CreditsValidationError(
-      'Credit amount cannot be negative',
-      'INVALID_AMOUNT'
-    );
-  }
-  if (amount > 10000) {
-    throw new CreditsValidationError(
-      'Credit amount exceeds maximum',
-      'EXCEEDS_MAXIMUM'
-    );
-  }
-}
-```
-
-## Error Handling Pattern
-
-```typescript
-import {
-  CreditsExhaustedError,
-  DuplicatePurchaseError,
-  CreditsValidationError
-} from './errors';
-
-async function handleCreditOperation(userId: string, cost: number) {
-  try {
-    const result = await repository.deductCredit(userId, cost);
-    return result;
-  } catch (error) {
-    if (error instanceof CreditsExhaustedError) {
-      // Show paywall or upgrade prompt
-      showPaywall({ required: cost, current: error.currentBalance });
-    } else if (error instanceof DuplicatePurchaseError) {
-      // Log and continue (not a critical error)
-      console.warn('Duplicate purchase detected');
-    } else if (error instanceof CreditsValidationError) {
-      // Log validation error
-      console.error('Validation failed:', error.message);
-    } else {
-      // Unexpected error
-      console.error('Unexpected error:', error);
-    }
-    throw error;
-  }
-}
-```
-
-## Error Codes Reference
-
-| Code | Description | Recovery |
-|------|-------------|----------|
-| `CREDITS_EXHAUSTED` | Not enough credits | Show paywall/upgrade |
-| `DUPLICATE_PURCHASE` | Duplicate purchase ID | Ignore (idempotent) |
-| `INVALID_AMOUNT` | Invalid credit amount | Validate input |
-| `EXCEEDS_MAXIMUM` | Amount too large | Cap at maximum |
-| `USER_NOT_FOUND` | User doesn't exist | Create user record |
-| `INITIALIZATION_FAILED` | Credit init failed | Retry operation |
-
-## Best Practices
-
-1. **Specific Errors**: Use specific error types for different scenarios
-2. **Error Context**: Include relevant data in error properties
-3. **Graceful Handling**: Handle errors appropriately at boundaries
-4. **Logging**: Log errors for debugging
-5. **User Feedback**: Convert errors to user-friendly messages
-
-## Related
-
+## Strategy
+This directory contains custom error classes representing wallet-related error conditions with specific error types and recovery strategies.
+
+## Restrictions
+
+### REQUIRED
+- Must use specific error types for different scenarios
+- Must include relevant context in error properties
+- Must handle errors gracefully at boundaries
+- Must log errors for debugging
+
+### PROHIBITED
+- DO NOT use generic error types
+- DO NOT throw errors without context
+- DO NOT ignore error conditions
+- DO NOT expose technical errors to users
+
+### CRITICAL SAFETY
+- All errors MUST be handled appropriately
+- Error context MUST be sufficient for recovery
+- Technical errors MUST be converted to user-friendly messages
+- Error codes MUST be actionable
+
+## AI Agent Guidelines
+1. Use specific error types for different scenarios (CreditsExhaustedError, DuplicatePurchaseError, etc.)
+2. Include relevant data in error properties for recovery
+3. Handle errors gracefully at layer boundaries
+4. Log all errors with sufficient context for debugging
+5. Convert technical errors to user-friendly messages
+6. Follow error code reference for recovery strategies
+7. Test error handling paths thoroughly
+
+## Related Documentation
 - [Wallet Entities](../entities/README.md)
 - [Credits Repository](../../infrastructure/repositories/README.md)

package/src/domains/wallet/infrastructure/README.md

@@ -1,96 +1,41 @@
 # Wallet Infrastructure
 
+## Location
 Infrastructure layer for wallet and credits functionality.
 
-## Overview
-
-This directory contains implementations for credit persistence, transactions, and credit operations.
-
-## Structure
-
-```
-infrastructure/
-├── repositories/    # Data persistence implementations
-│   └── CreditsRepository.ts
-└── services/         # External service integrations
-    └── CreditsService.ts
-```
-
-## Credits Repository
-
-Handles credit data persistence with duplicate protection.
-
-### Key Features
-
-- **Duplicate Protection**: Prevents duplicate credit allocations
-- **Optimistic Updates**: Immediate UI updates with rollback
-- **Transactional**: Atomic credit operations
-- **ACCUMULATE Mode**: Adds credits on renewal
-
-### Core Methods
-
-```typescript
-class CreditsRepository implements ICreditsRepository {
-  async getCredits(userId: string): Promise<UserCredits | null>;
-  async initializeCredits(
-    userId: string,
-    purchaseId?: string,
-    productId?: string
-  ): Promise<CreditsResult>;
-  async deductCredit(userId: string, amount: number): Promise<CreditsResult>;
-  async addCredits(userId: string, amount: number): Promise<CreditsResult>;
-}
-```
-
-### Usage
-
-```typescript
-import { CreditsRepository } from './repositories/CreditsRepository';
-import { getCreditsRepository } from './repositories/CreditsRepositoryProvider';
-
-const repository = getCreditsRepository();
-
-// Initialize credits
-const result = await repository.initializeCredits('user-123', 'purchase-456', 'premium_monthly');
-if (result.success) {
-  console.log('Credits:', result.data.credits);
-}
-
-// Deduct credits
-const deductResult = await repository.deductCredit('user-123', 5);
-if (deductResult.success) {
-  console.log('Credits deducted successfully');
-} else if (deductResult.error?.code === 'CREDITS_EXHAUSTED') {
-  console.log('Not enough credits');
-}
-```
-
-## Duplicate Protection
-
-The repository prevents duplicate credit allocations based on `purchaseId`:
-
-```typescript
-// First call
-await repository.initializeCredits(userId, 'renewal-123', 'premium');
-// Returns: { success: true, data: { credits: 100 } }
-
-// Second call with same purchaseId
-await repository.initializeCredits(userId, 'renewal-123', 'premium');
-// Returns: { success: true, duplicate: true, data: { credits: 100 } }
-// Credits not added again
-```
-
-## Best Practices
-
-1. **Check Before Deduct**: Always verify credit balance
-2. **Handle Errors**: Catch and handle credit errors appropriately
-3. **Use Transactions**: Ensure data consistency
-4. **Log Operations**: Track credit operations for debugging
-5. **Test Edge Cases**: Zero credits, max credits, duplicates
-6. **Validate Input**: Validate all input parameters
-
-## Related
-
+## Strategy
+This directory contains implementations for credit persistence, transactions, and credit operations with duplicate protection and optimistic updates.
+
+## Restrictions
+
+### REQUIRED
+- Must check credit balance before deducting
+- Must handle errors appropriately
+- Must use transactions for data consistency
+- Must log all credit operations
+
+### PROHIBITED
+- DO NOT deduct credits without balance check
+- DO NOT allow duplicate credit allocations
+- DO NOT skip transaction boundaries
+- DO NOT ignore credit operation errors
+
+### CRITICAL SAFETY
+- Duplicate allocations MUST be prevented based on purchaseId
+- Credit operations MUST be atomic
+- All operations MUST be logged for debugging
+- Input validation MUST be performed
+
+## AI Agent Guidelines
+1. Always verify credit balance before deduction operations
+2. Implement comprehensive error handling for credit operations
+3. Use transactions to ensure data consistency
+4. Track all credit operations with detailed logging
+5. Test edge cases: zero credits, max credits, duplicates
+6. Validate all input parameters before processing
+7. Implement duplicate protection based on purchaseId
+
+## Related Documentation
 - [Wallet Domain](../domain/README.md)
 - [Credits Entity](../domain/entities/README.md)
 - [useCredits Hook](../../presentation/hooks/useCredits.md)