@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/infrastructure/repositories/README.md

@@ -2,384 +2,98 @@
 
 Repository implementations for data persistence.
 
-## Purpose
+## Location
 
-Repositories handle data access and persistence, abstracting away the details of storage mechanisms.
+- **Base Path**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/infrastructure/repositories/`
+- **Repositories**: `src/infrastructure/repositories/`
 
-## Available Repositories
+## Strategy
 
-### CreditsRepository
+### Repository Pattern
 
-Manages credits data in Firestore.
+Data access abstraction layer.
 
-```typescript
-import {
-  configureCreditsRepository,
-  getCreditsRepository,
-  type CreditsRepository,
-} from '@umituz/react-native-subscription/infrastructure';
+- **CreditsRepository**: Credits data management
+- **TransactionRepository**: Transaction history
+- **SubscriptionRepository**: Subscription status management
+- **Custom Repositories**: Extensible repository architecture
 
-// Configure
-configureCreditsRepository({
-  firebase: { firestore: db },
-  config: creditsConfig,
-});
+### Data Access Patterns
 
-// Get instance
-const repository = getCreditsRepository();
+Structured data access implementations.
 
-// Use
-const credits = await repository.getCredits('user-123');
-```
+- **Active Record**: Entity-based data management
+- **Data Mapper**: Separation of entities and data
+- **Repository with Caching**: Performance optimization
+- **Transaction Support**: Atomic operations
 
-### TransactionRepository
+### Storage Implementations
 
-Manages transaction history.
+Multiple storage backend support.
 
-```typescript
-import {
-  createTransactionRepository,
-  type TransactionRepository,
-} from '@umituz/react-native-subscription/wallet';
+- **Firestore**: Cloud Firestore implementation
+- **In-Memory**: Testing and development
+- **HTTP**: REST API integration
+- **Redis**: Redis cache implementation
 
-const repository = createTransactionRepository({
-  firebase: { firestore: db },
-  userId: 'user-123',
-});
+### Advanced Features
 
-const transactions = await repository.getTransactions({ limit: 20 });
-```
+Enterprise-level repository capabilities.
 
-## Custom Repositories
+- **Real-Time Updates**: Firestore real-time listeners
+- **Transaction Support**: Multi-document transactions
+- **Caching**: Performance optimization
+- **Mocking**: Testing support
 
-### Creating a Custom Repository
+## Restrictions
 
-```typescript
-import type { ISubscriptionRepository } from '@umituz/react-native-subscription/application';
+### REQUIRED
 
-class HttpSubscriptionRepository implements ISubscriptionRepository {
-  private baseUrl: string;
+- **Interface Implementation**: Implement required interfaces
+- **Error Handling**: Transform storage errors to domain errors
+- **Validation**: Validate data before saving
+- **Logging**: Log repository operations
 
-  constructor(baseUrl: string) {
-    this.baseUrl = baseUrl;
-  }
+### PROHIBITED
 
-  async getSubscriptionStatus(userId: string): Promise<SubscriptionStatus | null> {
-    const response = await fetch(`${this.baseUrl}/subscriptions/${userId}`);
+- **Business Logic**: Keep business logic in services
+- **Direct Exposure**: Never expose storage-specific types
+- **Missing Validation**: Never save invalid data
+- **Swallowed Errors**: Always handle or propagate errors
 
-    if (!response.ok) {
-      throw new SubscriptionRepositoryError('Failed to fetch subscription');
-    }
+### CRITICAL
 
-    return await response.json();
-  }
-
-  async saveSubscriptionStatus(
-    userId: string,
-    status: SubscriptionStatus
-  ): Promise<void> {
-    const response = await fetch(`${this.baseUrl}/subscriptions/${userId}`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(status),
-    });
-
-    if (!response.ok) {
-      throw new SubscriptionRepositoryError('Failed to save subscription');
-    }
-  }
-
-  async deleteSubscriptionStatus(userId: string): Promise<void> {
-    const response = await fetch(`${this.baseUrl}/subscriptions/${userId}`, {
-      method: 'DELETE',
-    });
-
-    if (!response.ok) {
-      throw new SubscriptionRepositoryError('Failed to delete subscription');
-    }
-  }
-
-  isSubscriptionValid(status: SubscriptionStatus): boolean {
-    return status.isActive && !isExpired(status.expirationDate);
-  }
-}
-```
-
-### In-Memory Repository (for testing)
-
-```typescript
-class InMemorySubscriptionRepository implements ISubscriptionRepository {
-  private storage = new Map<string, SubscriptionStatus>();
-
-  async getSubscriptionStatus(userId: string): Promise<SubscriptionStatus | null> {
-    return this.storage.get(userId) || null;
-  }
-
-  async saveSubscriptionStatus(
-    userId: string,
-    status: SubscriptionStatus
-  ): Promise<void> {
-    this.storage.set(userId, status);
-  }
-
-  async deleteSubscriptionStatus(userId: string): Promise<void> {
-    this.storage.delete(userId);
-  }
-
-  isSubscriptionValid(status: SubscriptionStatus): boolean {
-    return status.isActive && !isExpired(status.expirationDate);
-  }
-
-  // Test helpers
-  __reset() {
-    this.storage.clear();
-  }
-}
-```
-
-### Redis Repository
-
-```typescript
-import Redis from 'ioredis';
-
-class RedisCreditsRepository {
-  private redis: Redis;
-  private prefix = 'credits:';
-
-  constructor(redis: Redis) {
-    this.redis = redis;
-  }
-
-  async getCredits(userId: string): Promise<UserCredits> {
-    const key = `${this.prefix}${userId}`;
-    const data = await this.redis.get(key);
-
-    if (!data) {
-      return {
-        balance: 0,
-        lastUpdated: new Date().toISOString(),
-      };
-    }
-
-    return JSON.parse(data);
-  }
-
-  async setCredits(userId: string, credits: UserCredits): Promise<void> {
-    const key = `${this.prefix}${userId}`;
-    await this.redis.set(key, JSON.stringify(credits));
-  }
-
-  async addCredits(
-    userId: string,
-    amount: number
-  ): Promise<UserCredits> {
-    const current = await this.getCredits(userId);
-    const updated = {
-      ...current,
-      balance: current.balance + amount,
-      lastUpdated: new Date().toISOString(),
-    };
-
-    await this.setCredits(userId, updated);
-    return updated;
-  }
-}
-```
-
-## Repository Patterns
-
-### 1. Active Record Pattern
-
-```typescript
-class Subscription {
-  constructor(private data: SubscriptionData) {}
-
-  async save(): Promise<void> {
-    await db.collection('subscriptions').doc(this.data.id).set(this.data);
-  }
-
-  async delete(): Promise<void> {
-    await db.collection('subscriptions').doc(this.data.id).delete();
-  }
-
-  static async find(id: string): Promise<Subscription | null> {
-    const doc = await db.collection('subscriptions').doc(id).get();
-    if (!doc.exists) return null;
-    return new Subscription(doc.data());
-  }
-}
-```
-
-### 2. Data Mapper Pattern
-
-```typescript
-class SubscriptionMapper {
-  toEntity(doc: FirebaseFirestore.DocumentSnapshot): Subscription {
-    const data = doc.data();
-    return Subscription.create({
-      id: doc.id,
-      ...data,
-    });
-  }
-
-  toData(entity: Subscription): Record<string, any> {
-    return {
-      type: entity.type,
-      isActive: entity.isActive,
-      isPremium: entity.isPremium,
-      expirationDate: entity.expirationDate,
-      willRenew: entity.willRenew,
-    };
-  }
-}
-```
-
-### 3. Repository with Caching
-
-```typescript
-class CachedSubscriptionRepository {
-  private cache = new Map<string, { data: SubscriptionStatus; expiry: number }>();
-  private ttl = 5 * 60 * 1000; // 5 minutes
-
-  constructor(private repository: ISubscriptionRepository) {}
-
-  async getSubscriptionStatus(userId: string): Promise<SubscriptionStatus | null> {
-    // Check cache
-    const cached = this.cache.get(userId);
-    if (cached && cached.expiry > Date.now()) {
-      return cached.data;
-    }
-
-    // Fetch from source
-    const status = await this.repository.getSubscriptionStatus(userId);
-
-    // Update cache
-    if (status) {
-      this.cache.set(userId, {
-        data: status,
-        expiry: Date.now() + this.ttl,
-      });
-    }
-
-    return status;
-  }
-
-  invalidate(userId: string): void {
-    this.cache.delete(userId);
-  }
-
-  invalidateAll(): void {
-    this.cache.clear();
-  }
-}
-```
-
-## Transaction Support
-
-### Firestore Transactions
-
-```typescript
-class TransactionalCreditsRepository {
-  async transferCredits(
-    fromUserId: string,
-    toUserId: string,
-    amount: number
-  ): Promise<void> {
-    await db.runTransaction(async (transaction) => {
-      const fromRef = db.collection('credits').doc(fromUserId);
-      const toRef = db.collection('credits').doc(toUserId);
-
-      const fromDoc = await transaction.get(fromRef);
-      const toDoc = await transaction.get(toRef);
-
-      const fromBalance = fromDoc.data()?.balance || 0;
-      const toBalance = toDoc.data()?.balance || 0;
-
-      if (fromBalance < amount) {
-        throw new InsufficientCreditsError('Insufficient credits');
-      }
-
-      transaction.update(fromRef, { balance: fromBalance - amount });
-      transaction.update(toRef, { balance: toBalance + amount });
-    });
-  }
-}
-```
-
-## Real-Time Updates
-
-### Firestore Realtime Listener
-
-```typescript
-class RealtimeSubscriptionRepository {
-  subscribeToStatus(
-    userId: string,
-    callback: (status: SubscriptionStatus) => void
-  ): () => void {
-    const unsubscribe = db
-      .collection('subscriptions')
-      .doc(userId)
-      .onSnapshot((doc) => {
-        if (doc.exists) {
-          callback(doc.data() as SubscriptionStatus);
-        }
-      });
-
-    return unsubscribe;
-  }
-}
-```
-
-## Testing Repositories
-
-### Mock Repository Factory
-
-```typescript
-function createMockRepository(options?: {
-  initialData?: Map<string, SubscriptionStatus>;
-  latency?: number;
-}): ISubscriptionRepository {
-  const data = options?.initialData || new Map();
-  const latency = options?.latency || 0;
-
-  return {
-    async getSubscriptionStatus(userId: string) {
-      if (latency > 0) {
-        await sleep(latency);
-      }
-      return data.get(userId) || null;
-    },
-
-    async saveSubscriptionStatus(userId: string, status: SubscriptionStatus) {
-      if (latency > 0) {
-        await sleep(latency);
-      }
-      data.set(userId, status);
-    },
-
-    async deleteSubscriptionStatus(userId: string) {
-      data.delete(userId);
-    },
-
-    isSubscriptionValid(status: SubscriptionStatus) {
-      return status.isActive && !isExpired(status.expirationDate);
-    },
-  };
-}
-```
-
-## Best Practices
-
-1. **Interface Segregation** - Keep interfaces focused
-2. **Error Handling** - Transform storage errors to domain errors
-3. **Logging** - Log repository operations
-4. **Validation** - Validate data before saving
-5. **Performance** - Use caching and batching
-6. **Testing** - Mock repositories for unit tests
-7. **Transactions** - Use transactions for multi-document updates
-
-## Related
-
-- [Infrastructure Layer](../../README.md)
-- [Infrastructure Services](../services/README.md)
-- [Application Ports](../../application/ports/README.md)
+- **Error Transformation**: Transform storage errors appropriately
+- **Data Integrity**: Maintain data integrity
+- **Performance**: Optimize with caching and batching
+- **Testing**: Support mock implementations
+
+## AI Agent Guidelines
+
+### When Modifying Repositories
+
+1. **Interface Compliance**: Maintain interface contracts
+2. **Error Handling**: Transform errors appropriately
+3. **Validation**: Validate all data
+4. **Logging**: Log operations for debugging
+
+### When Creating Custom Repositories
+
+1. **Interface Implementation**: Implement required interfaces
+2. **Error Transformation**: Transform storage errors
+3. **Validation**: Add data validation
+4. **Testing**: Create mock implementations
+
+### When Fixing Repository Bugs
+
+1. **Data Access**: Check data access logic
+2. **Error Handling**: Verify error transformation
+3. **Validation**: Check validation rules
+4. **Edge Cases**: Test with null/undefined values
+
+## Related Documentation
+
+- [Infrastructure Services](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/infrastructure/services/README.md)
+- [Infrastructure Layer](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/infrastructure/README.md)
+- [Application Ports](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/application/ports/README.md)
+- [Domain Layer](/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-subscription/src/domain/README.md)