@umituz/react-native-ai-gemini-provider 1.14.28 → 1.14.30

package/src/infrastructure/interceptors/README.md

@@ -0,0 +1,226 @@
+# Interceptors Module
+
+Middleware system for transforming requests and responses. Manages authentication, logging, transformation, and other cross-cutting concerns from a central location.
+
+## 📍 Import Path
+
+```
+import {
+  requestInterceptors,
+  responseInterceptors
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use interceptors to modify API requests before sending and responses after receiving. Provides centralized middleware for authentication, logging, validation, caching, and data transformation.
+
+**When to use:**
+- Add authentication headers to requests
+- Log and monitor API calls
+- Transform request/response data
+- Implement rate limiting
+- Validate payloads
+- Add custom headers
+- Cache responses
+- Handle errors globally
+- Enrich response data
+
+## 📌 Strategy
+
+Interceptors provide a clean separation of concerns. This system:
+- Executes request interceptors in order (first added runs first)
+- Executes response interceptors in reverse order (last added runs first)
+- Returns unsubscribe functions for cleanup
+- Supports async interceptors
+- Maintains immutability of context
+- Enables composable middleware chains
+
+**Key Decision**: Use interceptors for cross-cutting concerns. Keep business logic in services, use interceptors for operational concerns like logging, auth, and transformation.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** return modified context from interceptors
+- **SHOULD** handle errors in interceptors gracefully
+- **MUST** unsubscribe from interceptors when done
+- **SHOULD NOT** block execution excessively
+- **MUST** maintain execution order dependency
+
+### Request Interceptor Rules
+- **MUST** return RequestContext object
+- **SHOULD** validate inputs in interceptors
+- **MUST NOT** mutate original context directly
+- **SHOULD** handle async operations properly
+- **MUST NOT** throw errors from interceptors
+
+### Response Interceptor Rules
+- **MUST** return ResponseContext object
+- **SHOULD** check for errors in responses
+- **MUST NOT** expose sensitive data
+- **SHOULD** transform data appropriately
+- **MUST** handle undefined responses
+
+### Best Practices Rules
+- **SHOULD** add logging interceptor first
+- **MUST** clean up interceptors on unmount
+- **SHOULD NOT** create circular dependencies
+- **MUST** return new context objects
+- **SHOULD** keep interceptors lightweight
+
+## 🤖 AI Agent Guidelines
+
+### When Adding Interceptors
+1. **READ** existing interceptor patterns first
+2. **UNDERSTAND** execution order (request: FIFO, response: LIFO)
+3. **IMPLEMENT** error handling
+4. **RETURN** modified context
+5. **TEST** interceptor in isolation
+
+### When Removing Interceptors
+1. **CALL** unsubscribe function
+2. **VERIFY** no memory leaks
+3. **UPDATE** dependent code
+4. **TEST** after removal
+5. **DOCUMENT** removal reason
+
+### When Debugging Interceptors
+1. **ADD** debug interceptor at start/end of chain
+2. **LOG** context before/after modifications
+3. **CHECK** execution order
+4. **VERIFY** context immutability
+5. **TEST** with various scenarios
+
+### Code Style Rules
+- **USE** async/await for async operations
+- **RETURN** new context objects (spread operator)
+- **HANDLE** errors with try-catch
+- **LOG** important operations
+- **COMMENT** complex transformation logic
+
+## 📦 Available Interceptors
+
+### Request Interceptors
+
+**Refer to**: [`RequestInterceptors.ts`](./RequestInterceptors.ts)
+
+**Methods:**
+- `use(interceptor)` - Add interceptor
+- `apply(context)` - Apply all interceptors
+- `clear()` - Clear all interceptors
+- `count()` - Get interceptor count
+
+**Execution Order:** First added runs first (FIFO)
+
+### Response Interceptors
+
+**Refer to**: [`ResponseInterceptors.ts`](./ResponseInterceptors.ts)
+
+**Methods:**
+- `use(interceptor)` - Add interceptor
+- `apply(context)` - Apply all interceptors
+- `clear()` - Clear all interceptors
+- `count()` - Get interceptor count
+
+**Execution Order:** Last added runs first (LIFO)
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Telemetry**: [`../telemetry/README.md`](../telemetry/README.md)
+
+## 📋 Interceptor Patterns
+
+### Authentication Pattern
+1. Add interceptor before operations
+2. Inject API key/token into context
+3. Return modified context
+4. Handle missing credentials
+5. Clean up interceptor when done
+
+### Logging Pattern
+1. Add interceptor at start of chain
+2. Log request/response details
+3. Include timing information
+4. Return context unchanged
+5. Avoid logging sensitive data
+
+### Transformation Pattern
+1. Add interceptor for specific transformation
+2. Extract data from context
+3. Apply transformation logic
+4. Return new context with transformed data
+5. Handle transformation errors
+
+### Caching Pattern
+1. Add response interceptor
+2. Check response status
+3. Cache successful responses
+4. Return context unchanged
+5. Handle cache errors gracefully
+
+### Validation Pattern
+1. Add request interceptor
+2. Validate context payload
+3. Check required fields
+4. Throw on validation failure
+5. Return context if valid
+
+## 🎓 Usage Patterns
+
+### Request Interception
+1. Import `requestInterceptors`
+2. Call `use()` with interceptor function
+3. Modify and return RequestContext
+4. Store unsubscribe function
+5. Call unsubscribe on cleanup
+
+### Response Interception
+1. Import `responseInterceptors`
+2. Call `use()` with interceptor function
+3. Modify and return ResponseContext
+4. Store unsubscribe function
+5. Call unsubscribe on cleanup
+
+### Chained Interceptors
+1. Add interceptors in desired order
+2. Request: First added runs first
+3. Response: Last added runs first
+4. Store all unsubscribe functions
+5. Clean up all on unmount
+
+### Conditional Interceptors
+1. Check environment/conditions
+2. Add interceptor only if needed
+3. Return early from interceptor if not applicable
+4. Keep conditional logic simple
+5. Test both conditional paths
+
+### Async Interceptors
+1. Make interceptor function async
+2. Use await for async operations
+3. Handle async errors
+4. Return modified context
+5. Test async behavior
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Mutate original context object
+- Forget to unsubscribe from interceptors
+- Block execution with heavy operations
+- Throw errors from interceptors
+- Create circular dependencies between interceptors
+
+### Do
+- Return new context objects
+- Clean up interceptors when done
+- Keep interceptors lightweight
+- Handle errors gracefully
+- Follow execution order rules
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/interceptors/REQUEST_INTERCEPTORS.md

@@ -0,0 +1,171 @@
+# Request Interceptors
+
+Middleware system for modifying AI requests before they're sent to the API. Allows applications to add custom logic, logging, authentication, and request transformation.
+
+## 📍 Import Path
+
+```
+import { requestInterceptors } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use request interceptors to modify API requests before sending. Provides middleware for authentication, logging, validation, caching, and data transformation.
+
+**When to use:**
+- Add authentication headers to requests
+- Log and monitor API calls
+- Transform request data
+- Implement rate limiting
+- Validate payloads
+- Add custom headers
+
+## 📌 Strategy
+
+Interceptors provide clean separation of concerns. This system:
+- Executes request interceptors in order
+- Returns unsubscribe functions for cleanup
+- Supports async interceptors
+- Maintains immutability of context
+- Enables composable middleware chains
+
+**Key Decision**: Use interceptors for cross-cutting concerns. Keep business logic in services, use interceptors for operational concerns.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** return modified context from interceptors
+- **SHOULD** handle errors in interceptors gracefully
+- **MUST** unsubscribe from interceptors when done
+- **SHOULD NOT** block execution excessively
+- **MUST** maintain execution order dependency
+
+### Request Interceptor Rules
+- **MUST** return RequestContext object
+- **SHOULD** validate inputs in interceptors
+- **MUST NOT** mutate original context directly
+- **SHOULD** handle async operations properly
+- **MUST NOT** throw errors from interceptors
+
+### Best Practices Rules
+- **SHOULD** add logging interceptor first
+- **MUST** clean up interceptors on unmount
+- **SHOULD NOT** create circular dependencies
+- **MUST** return new context objects
+- **SHOULD** keep interceptors lightweight
+
+## 🤖 AI Agent Guidelines
+
+### When Adding Interceptors
+1. **READ** existing interceptor patterns first
+2. **UNDERSTAND** execution order (FIFO)
+3. **IMPLEMENT** error handling
+4. **RETURN** modified context
+5. **TEST** interceptor in isolation
+
+### When Removing Interceptors
+1. **CALL** unsubscribe function
+2. **VERIFY** no memory leaks
+3. **UPDATE** dependent code
+4. **TEST** after removal
+5. **DOCUMENT** removal reason
+
+### When Debugging Interceptors
+1. **ADD** debug interceptor at start/end of chain
+2. **LOG** context before/after modifications
+3. **CHECK** execution order
+4. **VERIFY** context immutability
+5. **TEST** with various scenarios
+
+### Code Style Rules
+- **USE** async/await for async operations
+- **RETURN** new context objects (spread operator)
+- **HANDLE** errors with try-catch
+- **LOG** important operations
+- **COMMENT** complex transformation logic
+
+## 📦 Available Class
+
+### requestInterceptors
+
+**Refer to**: [`RequestInterceptors.ts`](./RequestInterceptors.ts)
+
+**Methods:**
+- `use(interceptor)` - Add interceptor
+- `apply(context)` - Apply all interceptors
+- `clear()` - Clear all interceptors
+- `count()` - Get interceptor count
+
+**Execution Order:** First added runs first (FIFO)
+
+## 🔗 Related Modules
+
+- **Response Interceptors**: [`ResponseInterceptors.ts`](./ResponseInterceptors.ts)
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+
+## 📋 Interceptor Patterns
+
+### Authentication Pattern
+1. Add interceptor before operations
+2. Inject API key/token into context
+3. Return modified context
+4. Handle missing credentials
+5. Clean up interceptor when done
+
+### Logging Pattern
+1. Add interceptor at start of chain
+2. Log request/response details
+3. Include timing information
+4. Return context unchanged
+5. Avoid logging sensitive data
+
+### Transformation Pattern
+1. Add interceptor for specific transformation
+2. Extract data from context
+3. Apply transformation logic
+4. Return new context with transformed data
+5. Handle transformation errors
+
+## 🎓 Usage Patterns
+
+### Request Interception
+1. Import `requestInterceptors`
+2. Call `use()` with interceptor function
+3. Modify and return RequestContext
+4. Store unsubscribe function
+5. Call unsubscribe on cleanup
+
+### Chained Interceptors
+1. Add interceptors in desired order
+2. Request: First added runs first
+3. Store all unsubscribe functions
+4. Clean up all on unmount
+
+### Conditional Interceptors
+1. Check environment/conditions
+2. Add interceptor only if needed
+3. Return early from interceptor if not applicable
+4. Keep conditional logic simple
+5. Test both conditional paths
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Mutate original context object
+- Forget to unsubscribe from interceptors
+- Block execution with heavy operations
+- Throw errors from interceptors
+- Create circular dependencies between interceptors
+
+### Do
+- Return new context objects
+- Clean up interceptors when done
+- Keep interceptors lightweight
+- Handle errors gracefully
+- Follow execution order rules
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/job/JOB_MANAGER.md

@@ -0,0 +1,174 @@
+# Job Manager
+
+Handles async job submission, tracking, and status management for AI generation tasks.
+
+## 📍 Import Path
+
+```
+import { JobManager } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use job manager to handle long-running AI operations asynchronously. Manages job lifecycle, status tracking, and result retrieval.
+
+**When to use:**
+- Submit long-running AI operations
+- Track job status over time
+- Implement polling for completion
+- Manage async job lifecycles
+- Retrieve results when ready
+
+## 📌 Strategy
+
+Job manager abstracts async operation complexity. This system:
+- Generates unique job IDs
+- Tracks job status through lifecycle
+- Stores results for retrieval
+- Handles errors gracefully
+- Supports status polling
+
+**Key Decision**: Use job manager for video generation and other long-running operations. Poll for status instead of blocking.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** save job ID after submission
+- **SHOULD** check job status before getting result
+- **MUST** handle job completion and failure
+- **SHOULD** implement polling for long operations
+- **MUST NOT** lose job IDs
+
+### Job Lifecycle Rules
+- **JOBS** start as IN_QUEUE
+- **MUST** update status through lifecycle
+- **SHOULD** set result or error on completion
+- **MUST** handle all status transitions
+- **SHOULD** clean up completed jobs
+
+### Error Handling Rules
+- **MUST** set job error on failure
+- **SHOULD** propagate errors to callers
+- **MUST** handle timeout scenarios
+- **SHOULD** log job failures
+- **MUST NOT** leave jobs in invalid state
+
+### Polling Rules
+- **SHOULD** poll with appropriate intervals
+- **MUST** implement timeout for polling
+- **SHOULD** handle polling errors
+- **MUST** stop polling on completion
+- **SHOULD NOT** poll too frequently
+
+## 🤖 AI Agent Guidelines
+
+### When Submitting Jobs
+1. **CALL** submitJob() with model and input
+2. **SAVE** returned job ID
+3. **TRACK** job status
+4. **HANDLE** completion/error
+5. **RETRIEVE** result when ready
+
+### When Polling Jobs
+1. **IMPLEMENT** polling loop with timeout
+2. **CHECK** job status each iteration
+3. **WAIT** between polls (exponential backoff)
+4. **RETURN** result on completion
+5. **THROW** on timeout or failure
+
+### When Managing Job Lifecycle
+1. **UPDATE** status appropriately
+2. **SET** result on success
+3. **SET** error on failure
+4. **VERIFY** state transitions
+5. **CLEAN UP** old jobs
+
+### Code Style Rules
+- **USE** descriptive job inputs
+- **HANDLE** all job status cases
+- **IMPLEMENT** polling with timeout
+- **LOG** job state changes
+- **VALIDATE** job IDs
+
+## 📦 Available Class
+
+### JobManager
+
+**Refer to**: [`JobManager.ts`](./JobManager.ts)
+
+**Methods:**
+- `submitJob(model, input)` - Submit new job
+- `getJobStatus(requestId)` - Get job status
+- `getJobResult(requestId)` - Get job result
+- `updateJobStatus(requestId, status)` - Update job status
+- `setJobResult(requestId, result)` - Set job result
+- `setJobError(requestId, error)` - Set job error
+- `getJob(requestId)` - Get job details
+- `clear()` - Clear all jobs
+
+## 🔗 Related Modules
+
+- **Video Generation Service**: [`../services/VIDEO_GENERATION_SERVICE.md`](../services/VIDEO_GENERATION_SERVICE.md)
+- **Job Processor**: [`../services/JOB_PROCESSOR_SERVICE.md`](../services/JOB_PROCESSOR_SERVICE.md)
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+
+## 📋 Job Status Types
+
+### IN_QUEUE
+Job is queued, waiting to start.
+
+### PROCESSING
+Job is currently being processed.
+
+### COMPLETED
+Job finished successfully with result.
+
+### FAILED
+Job failed with error.
+
+### CANCELLED
+Job was cancelled before completion.
+
+## 🎓 Usage Patterns
+
+### Job Submission
+1. Create JobManager instance
+2. Call submitJob() with model and input
+3. Store returned job ID
+4. Monitor job status
+5. Retrieve result when complete
+
+### Status Polling
+1. Submit job and get ID
+2. Poll job status periodically
+3. Check for COMPLETED or FAILED
+4. Implement timeout
+5. Return result or throw error
+
+### Job Lifecycle Management
+1. Submit job to manager
+2. Update status to PROCESSING
+3. Perform operation
+4. Set result or error
+5. Handle completion
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Lose job ID after submission
+- Call getJobResult() without checking status
+- Poll too frequently
+- Forget to implement timeout
+- Leave completed jobs in queue
+
+### Do
+- Always save job ID
+- Check status before getting result
+- Use exponential backoff for polling
+- Implement timeout for polling
+- Clean up completed jobs
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)