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

package/src/infrastructure/content/CONTENT_BUILDER.md

@@ -0,0 +1,175 @@
+# Content Builder
+
+Builder class for creating Gemini API content structures. Provides type-safe methods for building text, image, and file content parts.
+
+## 📍 Import Path
+
+```
+import { ContentBuilder } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use ContentBuilder to create properly formatted Gemini content objects. Handles text, images, and file data for multimodal inputs.
+
+**When to use:**
+- Build content for text generation
+- Create multimodal content (text + images)
+- Format chat messages
+- Add file data to requests
+- Build conversation history
+
+## 📌 Strategy
+
+ContentBuilder ensures correct API format. This class:
+- Creates properly structured content objects
+- Handles different content types (text, images, files)
+- Simplifies multimodal content creation
+- Provides consistent formatting
+- Validates content structure
+
+**Key Decision**: Use ContentBuilder for all content creation. Ensures compatibility with Gemini API format.
+
+## ⚠️ Rules
+
+### Content Creation Rules
+- **MUST** specify role (user or model)
+- **SHOULD** use builder methods
+- **MUST** provide valid parts array
+- **SHOULD** validate content structure
+- **MUST NOT** create malformed content
+
+### Content Part Rules
+- **MUST** use correct MIME types
+- **SHOULD** provide valid base64 data
+- **MUST** handle encoding properly
+- **SHOULD** validate image data
+- **MUST NOT** use invalid formats
+
+### Multimodal Rules
+- **SHOULD** include text with images
+- **MUST** order parts appropriately
+- **SHOULD** limit image count
+- **MUST** handle mixed content types
+- **SHOULD NOT** exceed size limits
+
+### Best Practices Rules
+- **SHOULD** use builder for consistency
+- **MUST** validate content before sending
+- **SHOULD** handle build errors
+- **MUST** use appropriate MIME types
+- **SHOULD** test content structures
+
+## 🤖 AI Agent Guidelines
+
+### When Building Text Content
+1. **CREATE** ContentBuilder instance
+2. **BUILD** text part
+3. **CREATE** content with role
+4. **VALIDATE** structure
+5. **RETURN** content object
+
+### When Building Multimodal Content
+1. **CREATE** ContentBuilder instance
+2. **BUILD** text part
+3. **BUILD** image data parts
+4. **COMBINE** parts in array
+5. **CREATE** content object
+
+### When Building Chat History
+1. **CREATE** ContentBuilder instance
+2. **BUILD** user messages
+3. **BUILD** model responses
+4. **COMBINE** in array
+5. **RETURN** conversation array
+
+### Code Style Rules
+- **USE** builder methods
+- **VALIDATE** inputs
+- **HANDLE** errors gracefully
+- **COMMENT** complex content
+- **TEST** content structures
+
+## 📦 Available Class
+
+### ContentBuilder
+
+**Refer to**: [`ContentBuilder.ts`](./ContentBuilder.ts)
+
+**Methods:**
+- `buildContent(role, parts)` - Build GeminiContent object
+- `buildTextPart(text)` - Build text part
+- `buildImageDataPart(mimeType, data)` - Build image data part
+- `buildFileDataPart(mimeType, fileUri)` - Build file data part
+
+## 🔗 Related Modules
+
+- **Domain Entities**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+- **Text Generation**: [`../services/TEXT_GENERATION_SERVICE.md`](../services/TEXT_GENERATION_SERVICE.md)
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+
+## 📋 Supported MIME Types
+
+### Image Formats
+- `image/png` - PNG images
+- `image/jpeg` - JPEG images
+- `image/webp` - WebP images
+- `image/heic` - HEIC images
+- `image/heif` - HEIF images
+
+### Document Formats
+- `application/pdf` - PDF documents
+- `text/plain` - Plain text
+- `text/html` - HTML documents
+- `application/json` - JSON data
+
+## 🎓 Usage Patterns
+
+### Basic Text Content
+1. Create ContentBuilder instance
+2. Build text part
+3. Create content with role
+4. Use in service call
+5. Handle response
+
+### Multimodal Content
+1. Create ContentBuilder instance
+2. Build text part
+3. Build image data parts
+4. Combine all parts
+5. Create content with role
+
+### Chat Conversation
+1. Create ContentBuilder instance
+2. Build user message content
+3. Build model response content
+4. Repeat for conversation
+5. Return content array
+
+### File-Based Content
+1. Create ContentBuilder instance
+2. Build text instruction
+3. Build file data part
+4. Create content with role
+5. Process file
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Create content objects manually
+- Skip role specification
+- Use invalid MIME types
+- Forget to validate content
+- Mix up part order
+
+### Do
+- Use ContentBuilder for all content
+- Always specify role
+- Validate MIME types
+- Test content structure
+- Follow API format
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/content/README.md

@@ -0,0 +1,175 @@
+# Content Builder
+
+Helper class for building content structures for Gemini API. Creates properly formatted content objects with text, images, and files.
+
+## 📍 Import Path
+
+```
+import { ContentBuilder } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use ContentBuilder to create properly formatted Gemini content objects. Handles text, images, and file data for multimodal inputs.
+
+**When to use:**
+- Build content for text generation
+- Create multimodal content (text + images)
+- Format chat messages
+- Add file data to requests
+- Build conversation history
+
+## 📌 Strategy
+
+ContentBuilder ensures correct API format. This class:
+- Creates properly structured content objects
+- Handles different content types (text, images, files)
+- Simplifies multimodal content creation
+- Provides consistent formatting
+- Validates content structure
+
+**Key Decision**: Use ContentBuilder for all content creation. Ensures compatibility with Gemini API format.
+
+## ⚠️ Rules
+
+### Content Creation Rules
+- **MUST** specify role (user or model)
+- **SHOULD** use builder methods
+- **MUST** provide valid parts array
+- **SHOULD** validate content structure
+- **MUST NOT** create malformed content
+
+### Content Part Rules
+- **MUST** use correct MIME types
+- **SHOULD** provide valid base64 data
+- **MUST** handle encoding properly
+- **SHOULD** validate image data
+- **MUST NOT** use invalid formats
+
+### Multimodal Rules
+- **SHOULD** include text with images
+- **MUST** order parts appropriately
+- **SHOULD** limit image count
+- **MUST** handle mixed content types
+- **SHOULD NOT** exceed size limits
+
+### Best Practices Rules
+- **SHOULD** use builder for consistency
+- **MUST** validate content before sending
+- **SHOULD** handle build errors
+- **MUST** use appropriate MIME types
+- **SHOULD** test content structures
+
+## 🤖 AI Agent Guidelines
+
+### When Building Text Content
+1. **CREATE** ContentBuilder instance
+2. **BUILD** text part
+3. **CREATE** content with role
+4. **VALIDATE** structure
+5. **RETURN** content object
+
+### When Building Multimodal Content
+1. **CREATE** ContentBuilder instance
+2. **BUILD** text part
+3. **BUILD** image data parts
+4. **COMBINE** parts in array
+5. **CREATE** content object
+
+### When Building Chat History
+1. **CREATE** ContentBuilder instance
+2. **BUILD** user messages
+3. **BUILD** model responses
+4. **COMBINE** in array
+5. **RETURN** conversation array
+
+### Code Style Rules
+- **USE** builder methods
+- **VALIDATE** inputs
+- **HANDLE** errors gracefully
+- **COMMENT** complex content
+- **TEST** content structures
+
+## 📦 Available Class
+
+### ContentBuilder
+
+**Refer to**: [`ContentBuilder.ts`](./ContentBuilder.ts)
+
+**Methods:**
+- `buildContent(role, parts)` - Build GeminiContent object
+- `buildTextPart(text)` - Build text part
+- `buildImageDataPart(mimeType, data)` - Build image data part
+- `buildFileDataPart(mimeType, fileUri)` - Build file data part
+
+## 🔗 Related Modules
+
+- **Domain Entities**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+- **Text Generation**: [`../services/TEXT_GENERATION_SERVICE.md`](../services/TEXT_GENERATION_SERVICE.md)
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+
+## 📋 Supported MIME Types
+
+### Image Formats
+- `image/png` - PNG images
+- `image/jpeg` - JPEG images
+- `image/webp` - WebP images
+- `image/heic` - HEIC images
+- `image/heif` - HEIF images
+
+### Document Formats
+- `application/pdf` - PDF documents
+- `text/plain` - Plain text
+- `text/html` - HTML documents
+- `application/json` - JSON data
+
+## 🎓 Usage Patterns
+
+### Basic Text Content
+1. Create ContentBuilder instance
+2. Build text part
+3. Create content with role
+4. Use in service call
+5. Handle response
+
+### Multimodal Content
+1. Create ContentBuilder instance
+2. Build text part
+3. Build image data parts
+4. Combine all parts
+5. Create content with role
+
+### Chat Conversation
+1. Create ContentBuilder instance
+2. Build user message content
+3. Build model response content
+4. Repeat for conversation
+5. Return content array
+
+### File-Based Content
+1. Create ContentBuilder instance
+2. Build text instruction
+3. Build file data part
+4. Create content with role
+5. Process file
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Create content objects manually
+- Skip role specification
+- Use invalid MIME types
+- Forget to validate content
+- Mix up part order
+
+### Do
+- Use ContentBuilder for all content
+- Always specify role
+- Validate MIME types
+- Test content structure
+- Follow API format
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

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)