@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/revenuecat/infrastructure/config/README.md

@@ -2,39 +2,48 @@
 
 RevenueCat SDK configuration and initialization.
 
-## Overview
+## Location
 
-This directory contains configuration utilities and setup for the RevenueCat SDK.
+`src/revenuecat/infrastructure/config/`
 
-## Contents
+## Strategy
 
-- **revenueCatConfig.ts** - RevenueCat configuration object and setup
+Configuration utilities and setup for the RevenueCat SDK, providing centralized configuration management for the subscription system.
 
-## Configuration
+## Restrictions
 
-```typescript
-interface RevenueCatConfig {
-  apiKey: string;
-  entitlementId: string;
-  [key: string]: any;
-}
-```
+### REQUIRED
 
-## Usage
+- MUST configure RevenueCat at app startup
+- MUST use valid API keys from environment configuration
+- MUST initialize before any purchase operations
+- MUST handle configuration errors gracefully
 
-Configure RevenueCat at app startup:
+### PROHIBITED
 
-```typescript
-import { revenueCatConfig } from './config/revenueCatConfig';
+- MUST NOT expose API keys in source code
+- MUST NOT hardcode configuration values
+- MUST NOT initialize RevenueCat multiple times
+- MUST NOT bypass configuration validation
 
-// In your app initializer
-await Purchases.configure({
-  apiKey: revenueCatConfig.apiKey,
-  appUserID: userId,
-});
-```
+### CRITICAL
 
-## Related
+- Always validate configuration before initialization
+- Never expose sensitive API keys or tokens
+- Handle all configuration errors gracefully
+- Ensure configuration is loaded before any operations
+
+## AI Agent Guidelines
+
+When working with RevenueCat configuration:
+1. Always validate configuration before use
+2. Never hardcode API keys or secrets
+3. Handle all configuration errors gracefully
+4. Ensure proper initialization order
+5. Test with both valid and invalid configurations
+
+## Related Documentation
 
 - [Managers](../managers/README.md)
 - [Services](../services/README.md)
+- [RevenueCat README](../../README.md)

package/src/revenuecat/infrastructure/handlers/README.md

@@ -0,0 +1,41 @@
+# RevenueCat Infrastructure Handlers
+
+## Location
+Event handlers for RevenueCat lifecycle events.
+
+## Strategy
+This directory contains handler implementations for managing RevenueCat events including purchase callbacks, customer info changes, and error handling with proper data validation and recovery.
+
+## Restrictions
+
+### REQUIRED
+- Must handle all events gracefully
+- Must validate incoming data before processing
+- Must log all events for debugging
+- Must invoke callbacks appropriately
+
+### PROHIBITED
+- DO NOT mutate incoming event data
+- DO NOT ignore event handling errors
+- DO NOT skip callback invocation
+- DO NOT process unvalidated data
+
+### CRITICAL SAFETY
+- All incoming data MUST be validated
+- All events MUST be logged for debugging
+- All callbacks MUST be invoked appropriately
+- Recovery options MUST be provided when possible
+
+## AI Agent Guidelines
+1. Never mutate incoming event data
+2. Handle all errors gracefully with proper boundaries
+3. Log all events for debugging and monitoring
+4. Invoke registered callbacks appropriately
+5. Use async/await for asynchronous operations
+6. Validate all incoming data before processing
+7. Provide recovery options when possible
+
+## Related Documentation
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Services](../services/README.md)
+- [RevenueCat Errors](../../domain/errors/README.md)

package/src/revenuecat/infrastructure/managers/README.md

@@ -1,49 +1,41 @@
 # RevenueCat Infrastructure Managers
 
+## Location
 Manager classes for coordinating RevenueCat operations.
 
-## Overview
-
-This directory contains high-level manager classes that coordinate between different RevenueCat services and handle complex operations.
-
-## Contents
-
-- **SubscriptionManager.ts** - Manages RevenueCat configuration and entitlement access
-
-## SubscriptionManager
-
-Manages RevenueCat SDK configuration and provides access to entitlement IDs.
-
-### Key Methods
-
-```typescript
-class SubscriptionManager {
-  static configure(config: RevenueCatConfig): void;
-  static getEntitlementId(): string | null;
-  static getOfferings(): Promise<Offerings>;
-}
-```
-
-### Usage
-
-```typescript
-import { SubscriptionManager } from './managers/SubscriptionManager';
-
-// Configure at app startup
-SubscriptionManager.configure({
-  apiKey: 'your_api_key',
-  entitlementId: 'premium',
-});
-
-// Get entitlement ID
-const entitlementId = SubscriptionManager.getEntitlementId();
-
-// Get offerings
-const offerings = await SubscriptionManager.getOfferings();
-```
-
-## Related
-
+## Strategy
+This directory contains high-level manager classes that coordinate between different RevenueCat services and handle complex operations like SDK configuration and entitlement access.
+
+## Restrictions
+
+### REQUIRED
+- Must coordinate between services properly
+- Must manage SDK configuration correctly
+- Must provide access to entitlement IDs
+- Must handle complex operations safely
+
+### PROHIBITED
+- DO NOT bypass service coordination
+- DO NOT misconfigure SDK
+- DO NOT expose invalid entitlement IDs
+- DO NOT oversimplify complex operations
+
+### CRITICAL SAFETY
+- Service coordination MUST be correct
+- SDK configuration MUST be valid
+- Entitlement access MUST be safe
+- Complex operations MUST be handled properly
+
+## AI Agent Guidelines
+1. Coordinate properly between RevenueCat services
+2. Manage SDK configuration with correct parameters
+3. Provide safe access to entitlement IDs
+4. Handle complex operations with proper error handling
+5. Test coordination logic thoroughly
+6. Document manager responsibilities clearly
+7. Maintain separation of concerns
+
+## Related Documentation
 - [Services](../services/README.md)
 - [Config](../config/README.md)
 - [Domain](../../domain/README.md)

package/src/revenuecat/infrastructure/services/README.md

@@ -0,0 +1,42 @@
+# RevenueCat Infrastructure Services
+
+## Location
+Service implementations for RevenueCat operations.
+
+## Strategy
+This directory contains concrete implementations of RevenueCat interfaces, providing the actual integration with the RevenueCat SDK using singleton pattern with proper error handling and caching.
+
+## Restrictions
+
+### REQUIRED
+- Must use singleton pattern for service instance
+- Must wrap all service calls in try-catch
+- Must use TypeScript types for all operations
+- Must log all RevenueCat operations
+
+### PROHIBITED
+- DO NOT create multiple service instances
+- DO NOT skip error handling
+- DO NOT bypass type safety
+- DO NOT skip logging operations
+
+### CRITICAL SAFETY
+- Service MUST be configured only once
+- All calls MUST be wrapped in error handling
+- All operations MUST be type-safe
+- All operations MUST be logged
+
+## AI Agent Guidelines
+1. Use singleton pattern for service instance
+2. Wrap all service calls in try-catch blocks
+3. Use TypeScript types for all operations
+4. Log all RevenueCat operations for debugging
+5. Cache customer info and offerings appropriately
+6. Validate parameters before calling SDK
+7. Configure service only once at startup
+8. Use mock implementations for testing
+
+## Related Documentation
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Handlers](../handlers/README.md)
+- [RevenueCat Application Ports](../../application/ports/README.md)

package/src/revenuecat/infrastructure/utils/README.md

@@ -0,0 +1,41 @@
+# RevenueCat Infrastructure Utils
+
+## Location
+Utility functions for RevenueCat operations.
+
+## Strategy
+This directory contains utility functions for common RevenueCat operations including error mapping, data transformation, validation, and formatting with proper type safety.
+
+## Restrictions
+
+### REQUIRED
+- Must use error mapping for user-facing messages
+- Must ensure types are validated before use
+- Must respect user locale for formatting
+- Must check for null/undefined values
+
+### PROHIBITED
+- DO NOT show SDK errors directly to users
+- DO NOT use data without type validation
+- DO NOT ignore locale settings
+- DO NOT skip null checks
+
+### CRITICAL SAFETY
+- All errors MUST be mapped to domain errors
+- All types MUST be validated before use
+- Locale MUST be respected for formatting
+- Null checks MUST be performed consistently
+
+## AI Agent Guidelines
+1. Always map SDK errors to domain errors for user-facing messages
+2. Ensure type safety by validating types before use
+3. Respect user locale when formatting prices and periods
+4. Always check for null/undefined values before processing
+5. Use debug helpers in development for troubleshooting
+6. Validate all data before processing
+7. Test utility functions with edge cases
+
+## Related Documentation
+- [RevenueCat Infrastructure](../README.md)
+- [RevenueCat Domain Types](../../domain/types/README.md)
+- [RevenueCat Errors](../../domain/errors/README.md)

package/src/revenuecat/presentation/README.md

@@ -0,0 +1,42 @@
+# RevenueCat Presentation
+
+## Location
+Presentation layer for RevenueCat integration.
+
+## Strategy
+This directory contains React hooks, components, and utilities for integrating RevenueCat functionality into the UI layer with proper loading states, error handling, and caching.
+
+## Restrictions
+
+### REQUIRED
+- Must show loading states during async operations
+- Must handle and display errors appropriately
+- Must cache customer info and offerings
+- Must re-render on entitlement changes
+
+### PROHIBITED
+- DO NOT skip loading states
+- DO NOT show technical errors to users
+- DO NOT ignore cache invalidation
+- DO NOT prevent re-renders on state changes
+
+### CRITICAL SAFETY
+- All async operations MUST show loading states
+- All errors MUST be handled and displayed appropriately
+- Data MUST be cached appropriately
+- UI MUST re-render on entitlement changes
+
+## AI Agent Guidelines
+1. Always show loading states during async operations
+2. Handle and display errors appropriately to users
+3. Update UI optimistically where possible
+4. Cache customer info and offerings appropriately
+5. Re-render on entitlement changes
+6. Provide clear feedback during purchases
+7. Validate data before displaying to users
+
+## Related Documentation
+- [RevenueCat Integration](../README.md)
+- [RevenueCat Application](../application/README.md)
+- [RevenueCat Infrastructure](../infrastructure/README.md)
+- [RevenueCat Domain](../domain/README.md)

package/src/revenuecat/presentation/hooks/README.md

@@ -2,54 +2,48 @@
 
 React hooks for accessing RevenueCat data and operations.
 
-## Overview
+## Location
 
-This directory contains React hooks that expose RevenueCat functionality to the presentation layer.
+`src/revenuecat/presentation/hooks/`
 
-## Contents
+## Strategy
 
-- **useCustomerInfo.ts** - Hook for accessing RevenueCat customer info
-- **useSubscriptionPackages.ts** - Hook for accessing subscription packages/offering
+React hooks that expose RevenueCat functionality to the presentation layer, providing access to customer info, subscription packages, and offerings.
 
-## Key Hooks
+## Restrictions
 
-### useCustomerInfo
+### REQUIRED
 
-Access RevenueCat customer information including entitlements.
+- MUST handle loading states appropriately
+- MUST handle error states gracefully
+- MUST cache responses when appropriate
+- MUST subscribe to real-time updates when needed
+- MUST validate all data before use
 
-```typescript
-function useCustomerInfo() {
-  const { customerInfo, isLoading } = useCustomerInfo();
+### PROHIBITED
 
-  return (
-    <View>
-      <Text>Entitlements: {Object.keys(customerInfo.entitlements.active).join(', ')}</Text>
-    </View>
-  );
-}
-```
+- MUST NOT expose RevenueCat implementation details to components
+- MUST NOT bypass error handling
+- MUST NOT create infinite loops with subscriptions
+- MUST NOT assume data is always available
 
-### useSubscriptionPackages
+### CRITICAL
 
-Access available subscription packages from current offering.
+- Always handle loading and error states
+- Unsubscribe from all listeners on unmount
+- Validate all data before using it in components
+- Handle null/undefined states properly
 
-```typescript
-function PackageList() {
-  const { packages, isLoading } = useSubscriptionPackages();
+## AI Agent Guidelines
 
-  if (isLoading) return <Loading />;
+When working with RevenueCat hooks:
+1. Always handle loading and error states
+2. Unsubscribe from listeners on unmount
+3. Validate all data before use
+4. Cache responses appropriately
+5. Handle null/undefined states gracefully
 
-  return (
-    <View>
-      {packages.map(pkg => (
-        <PackageCard key={pkg.identifier} package={pkg} />
-      ))}
-    </View>
-  );
-}
-```
-
-## Related
+## Related Documentation
 
 - [Main Hooks](../../../presentation/hooks/README.md)
 - [Domain](../../domain/README.md)