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

package/src/infrastructure/services/VEO_HTTP_CLIENT_SERVICE.md

@@ -0,0 +1,179 @@
+# Veo HTTP Client Service
+
+Makes HTTP requests to Google Veo API for video generation. Initiates video generation operations and queries status.
+
+## 📍 Import Path
+
+```
+import { veoHttpClient } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to communicate directly with Veo API for video generation operations. Handles HTTP requests for starting and polling video generation.
+
+**When to use:**
+- Start video generation operations
+- Query operation status
+- Access raw Veo API responses
+- Implement custom polling logic
+- Debug video generation issues
+
+## 📌 Strategy
+
+Veo API uses asynchronous operations with polling. This service:
+- Sends HTTP requests to Veo API endpoints
+- Initiates video generation operations
+- Queries operation status
+- Returns raw API responses
+- Implements retry logic for network failures
+
+**Key Decision**: Use `veo-polling.service.ts` for automatic polling instead of manually polling with this service. This service is for advanced use cases requiring custom polling logic.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** provide valid API key
+- **MUST** use valid Veo model IDs
+- **SHOULD** save operation names for polling
+- **MUST** handle network errors appropriately
+- **SHOULD NOT** poll manually (use polling service)
+
+### Request Rules
+- **MUST** provide prompt in instances array
+- **SHOULD** set appropriate aspect ratio
+- **MUST** use supported parameters
+- **SHOULD** include negative prompt when needed
+- **MUST NOT** exceed request size limits
+
+### Error Handling Rules
+- **MUST** catch and handle HTTP errors
+- **SHOULD** check operation error field
+- **MUST** validate operation responses
+- **SHOULD** implement retry logic for failures
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** Veo API structure
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if feature exists in Veo API
+2. **FOLLOW** existing request patterns
+3. **USE** established error handling
+4. **DOCUMENT** in type definitions
+5. **ADD** examples to tests (not docs)
+
+### When Fixing Bugs
+1. **REPRODUCE** bug locally first
+2. **IDENTIFY** root cause
+3. **FIX** with minimal changes
+4. **ADD** regression test
+5. **VERIFY** all tests pass
+
+### Code Style Rules
+- **USE** async/await (no callbacks)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** HTTP requests in development
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `startOperation(model, apiKey, instances, parameters)`
+
+Initiate video generation operation.
+
+**Refer to**: [`veo-http-client.service.ts`](./veo-http-client.service.ts)
+
+### `getOperation(operationName, apiKey, model)`
+
+Query operation status.
+
+**Refer to**: [`veo-http-client.service.ts`](./veo-http-client.service.ts)
+
+## 🔗 Related Modules
+
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### VeoOperation
+
+Operation response structure defined in: [`domain/entities/README.md`](../domain/entities/README.md)
+
+**Fields:**
+- `name`: string - Operation full path
+- `done`: boolean - Completion status
+- `response`: object - Video data (when complete)
+- `metadata`: object - Progress information
+- `error`: object - Error details (if failed)
+
+### API Endpoints
+
+**Start Operation:**
+- Method: POST
+- URL: `https://generativelanguage.googleapis.com/v1beta/models/{model}:predict`
+- Body: `{ instances: [{ prompt: string }], parameters: { aspectRatio: string } }`
+
+**Get Operation:**
+- Method: GET
+- URL: `https://generativelanguage.googleapis.com/v1beta/{operationName}`
+
+### Model IDs
+
+Supported Veo models: `veo-3.1-fast-generate-preview`, `veo-3.0-generate-001`
+
+See: [`domain/constants/README.md`](../domain/constants/README.md)
+
+## 🎓 Usage Patterns
+
+### Start Video Generation
+1. Import service
+2. Call `startOperation()` with model, API key, and prompt
+3. Save returned operation name
+4. Use operation name for polling
+5. Handle network errors
+
+### Query Operation Status
+1. Import service
+2. Call `getOperation()` with operation name
+3. Check `done` field for completion
+4. Check `error` field for failures
+5. Extract video URL from response when complete
+
+### Custom Polling Logic
+1. Start operation with `startOperation()`
+2. Poll with `getOperation()` in loop
+3. Check completion status each iteration
+4. Handle progress updates
+5. Exit when complete or failed
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Poll manually (use veo-polling.service.ts)
+- Forget to save operation name
+- Ignore operation error field
+- Expose API keys in logs
+- Poll too frequently (rate limits)
+
+### Do
+- Save operation name immediately
+- Use polling service for automatic polling
+- Check error field in responses
+- Implement backoff between polls
+- Handle network errors gracefully
+- Validate API responses
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/VEO_POLLING_SERVICE.md

@@ -0,0 +1,173 @@
+# Veo Polling Service
+
+Tracks video generation operations using polling mechanism. Regularly checks operation status until completion.
+
+## 📍 Import Path
+
+```
+import { veoPollingService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to automatically poll video generation operations until completion. Provides progress updates and handles polling logic.
+
+**When to use:**
+- Wait for video generation to complete
+- Track generation progress
+- Provide progress feedback to users
+- Handle long-running operations
+- Implement video generation UI
+
+## 📌 Strategy
+
+Video generation takes time and requires polling. This service:
+- Implements automatic polling with backoff
+- Provides progress callbacks for UI updates
+- Handles operation completion and errors
+- Manages polling intervals and timeouts
+- Simplifies video generation workflow
+
+**Key Decision**: Use this service instead of manual polling. It handles backoff, timeouts, and progress tracking automatically.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** provide valid operation name
+- **MUST** provide API key and model ID
+- **SHOULD** implement progress callback
+- **MUST** handle polling completion appropriately
+- **SHOULD NOT** implement custom polling logic
+
+### Polling Rules
+- **MUST** wait between polls (automatic backoff)
+- **SHOULD** provide progress updates to users
+- **MUST** handle operation errors
+- **SHOULD** implement timeout for long operations
+- **MUST NOT** poll too frequently
+
+### Error Handling Rules
+- **MUST** check operation error field
+- **SHOULD** handle polling errors
+- **MUST** throw errors on operation failure
+- **SHOULD** provide user-friendly error messages
+- **MUST NOT** ignore timeout errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** polling mechanism
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar feature exists
+2. **FOLLOW** existing polling patterns
+3. **USE** established error handling
+4. **DOCUMENT** in type definitions
+5. **ADD** examples to tests (not docs)
+
+### When Fixing Bugs
+1. **REPRODUCE** bug locally first
+2. **IDENTIFY** root cause
+3. **FIX** with minimal changes
+4. **ADD** regression test
+5. **VERIFY** all tests pass
+
+### Code Style Rules
+- **USE** async/await (no callbacks except onProgress)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** polling operations in development
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `pollOperation(operationName, apiKey, model, onProgress?)`
+
+Poll operation until completion with progress updates.
+
+**Refer to**: [`veo-polling.service.ts`](./veo-polling.service.ts)
+
+## 🔗 Related Modules
+
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Error Handler**: [`VIDEO_ERROR_HANDLER_SERVICE.md`](./VIDEO_ERROR_HANDLER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Polling Strategy
+
+**Polling Intervals:**
+- Initial: Every 2 seconds
+- Backoff: Gradually increases based on progress
+- Maximum: 5 minutes total wait time
+
+**Polling Flow:**
+1. Start → Check status
+2. If not complete → Wait 2s → Check again
+3. If progress update → Call onProgress callback
+4. If complete or error → Return result
+5. If timeout → Throw error
+
+### Progress Callback
+
+Callback receives `VideoGenerationProgress` with:
+- `status`: Operation status (queued, processing, completed, failed)
+- `progress`: Percentage (0-100)
+- `message`: Optional status message
+
+## 🎓 Usage Patterns
+
+### Basic Polling
+1. Import service
+2. Call `pollOperation()` with operation name from HTTP client
+3. Wait for completion promise to resolve
+4. Extract video URL from result
+5. Handle errors appropriately
+
+### With Progress Updates
+1. Import service
+2. Implement `onProgress` callback
+3. Update UI with progress percentage
+4. Display status message to user
+5. Handle completion
+
+### With Timeout
+1. Calculate timeout duration
+2. Implement timeout check in progress callback
+3. Throw error if timeout exceeded
+4. Handle timeout error appropriately
+5. Provide user feedback
+
+### React Native Integration
+1. Create state for progress and video URL
+2. Start polling on user action
+3. Update state in progress callback
+4. Display progress to user
+5. Show video when complete
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Implement manual polling (use this service)
+- Ignore progress updates (bad UX)
+- Forget to handle errors
+- Poll without backoff (rate limits)
+- Block UI during polling
+
+### Do
+- Always use progress callbacks
+- Update UI with progress
+- Handle all error states
+- Implement cancellation support
+- Provide user feedback
+- Use reasonable timeouts
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_DOWNLOADER_SERVICE.md

@@ -0,0 +1,166 @@
+# Video Downloader Service
+
+Utility for downloading videos from authenticated Veo URLs and converting them to base64 data URIs. Veo URLs require authentication via the `x-goog-api-key` header.
+
+## 📍 Import Path
+
+```
+import { downloadVideoFromVeo } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video downloader to fetch generated videos from authenticated Veo URLs. Downloads and converts videos to base64 for local use.
+
+**When to use:**
+- Download generated videos from Veo API
+- Convert videos to base64 format
+- Handle authenticated video URLs
+- Prepare videos for local storage
+- Display videos in React Native apps
+
+## 📌 Strategy
+
+Veo URLs require authentication. This service:
+- Adds authentication headers to requests
+- Downloads video data
+- Converts to base64 format
+- Provides file metadata
+- Handles download errors
+
+**Key Decision**: Always use downloader for Veo video URLs. Direct requests will fail without authentication.
+
+## ⚠️ Rules
+
+### Download Rules
+- **MUST** provide valid API key
+- **SHOULD** validate video URL format
+- **MUST** handle download errors
+- **SHOULD** check file size limits
+- **MUST NOT** expose API key in errors
+
+### Authentication Rules
+- **MUST** include API key in headers
+- **SHOULD** use secure storage for keys
+- **MUST NOT** cache video URLs indefinitely
+- **SHOULD** refresh expired URLs
+- **MUST** handle authentication failures
+
+### File Handling Rules
+- **SHOULD** validate video format
+- **MUST** handle large files
+- **SHOULD** compress if needed
+- **MUST** check available storage
+- **SHOULD NOT** block main thread
+
+### Error Handling Rules
+- **MUST** handle network errors
+- **SHOULD** retry on transient failures
+- **MUST** provide clear error messages
+- **SHOULD** log download failures
+- **MUST NOT** lose download progress
+
+## 🤖 AI Agent Guidelines
+
+### When Downloading Videos
+1. **VALIDATE** video URL
+2. **PROVIDE** API key
+3. **CALL** downloadVideoFromVeo()
+4. **HANDLE** download result
+5. **STORE** or display video
+
+### When Handling Large Videos
+1. **CHECK** file size before download
+2. **WARN** user about large downloads
+3. **IMPLEMENT** progress tracking
+4. **HANDLE** storage constraints
+5. **PROVIDE** cancellation option
+
+### When Handling Errors
+1. **CATCH** download errors
+2. **CHECK** error type
+3. **RETRY** if appropriate
+4. **INFORM** user of failure
+5. **LOG** error details
+
+### Code Style Rules
+- **VALIDATE** inputs before download
+- **HANDLE** all error cases
+- **PROVIDE** progress feedback
+- **CLEAN UP** on failure
+- **SECURE** API keys
+
+## 📦 Available Function
+
+### downloadVideoFromVeo
+
+**Refer to**: [`gemini-video-downloader.ts`](./gemini-video-downloader.ts)
+
+**Parameters:**
+- `videoUrl`: string - Authenticated Veo video URL
+- `apiKey`: string - Google Cloud API key
+
+**Returns:** Promise<VideoDownloadResult>
+- `base64DataUri`: string - Base64 video with data URI prefix
+- `sizeInMB`: number - File size in megabytes
+- `mimeType`: string - Video MIME type
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Video URL Extractor**: [`VIDEO_URL_EXTRACTOR_SERVICE.md`](./VIDEO_URL_EXTRACTOR_SERVICE.md)
+
+## 📋 Return Type
+
+```typescript
+interface VideoDownloadResult {
+  base64DataUri: string;  // data:video/mp4;base64,...
+  sizeInMB: number;       // File size in MB
+  mimeType: string;       // video/mp4 or video/webm
+}
+```
+
+## 🎓 Usage Patterns
+
+### Basic Download
+1. Get video URL from generation response
+2. Call downloadVideoFromVeo()
+3. Get base64 result
+4. Store or display video
+5. Handle errors
+
+### Large File Handling
+1. Check file size before download
+2. Warn user if large
+3. Implement progress tracking
+4. Download with cancellation option
+5. Handle storage constraints
+
+### Error Recovery
+1. Catch download errors
+2. Check if retryable
+3. Retry with backoff
+4. Inform user of failure
+5. Provide alternative options
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use direct fetch for Veo URLs
+- Expose API key in errors
+- Ignore file size limits
+- Block main thread
+- Skip error handling
+
+### Do
+- Always use downloader service
+- Secure API keys properly
+- Check file sizes
+- Handle errors gracefully
+- Provide user feedback
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_ERROR_HANDLER_SERVICE.md

@@ -0,0 +1,185 @@
+# Video Error Handler Service
+
+Factory for creating typed video generation errors with retry information. Provides consistent error handling for video generation operations.
+
+## 📍 Import Path
+
+```
+import { createVideoError } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video error handler to create typed errors for video generation failures. Provides consistent error handling with retry information.
+
+**When to use:**
+- Create video generation errors
+- Determine retry behavior
+- Handle video operation failures
+- Provide consistent error messages
+- Categorize error types
+
+## 📌 Strategy
+
+Typed errors improve error handling. This service:
+- Categorizes error types
+- Provides retry information
+- Creates consistent error objects
+- Includes status codes
+- Simplifies error handling
+
+**Key Decision**: Always use createVideoError for video failures. Provides consistent error handling across video operations.
+
+## ⚠️ Rules
+
+### Error Creation Rules
+- **MUST** specify error type
+- **SHOULD** provide clear messages
+- **MUST** include context information
+- **SHOULD** set retry flag correctly
+- **MUST NOT** expose sensitive data
+
+### Error Type Rules
+- **MUST** use appropriate error type
+- **SHOULD** distinguish retryable errors
+- **MUST** match error to situation
+- **SHOULD** provide status codes
+- **MUST NOT** use unknown type unnecessarily
+
+### Retry Rules
+- **SHOULD** retry NETWORK errors
+- **SHOULD** retry TIMEOUT errors
+- **MUST NOT** retry VALIDATION errors
+- **SHOULD NOT** retry QUOTA errors
+- **MUST** implement backoff for retries
+
+### Error Handling Rules
+- **MUST** catch all video errors
+- **SHOULD** log error details
+- **MUST** inform user appropriately
+- **SHOULD** provide recovery options
+- **MUST NOT** suppress errors
+
+## 🤖 AI Agent Guidelines
+
+### When Creating Errors
+1. **IDENTIFY** error type
+2. **CREATE** error with createVideoError()
+3. **INCLUDE** relevant context
+4. **SET** retry flag appropriately
+5. **THROW** or return error
+
+### When Handling Errors
+1. **CATCH** video generation errors
+2. **CHECK** error type
+3. **DETERMINE** retry eligibility
+4. **INFORM** user appropriately
+5. **PROVIDE** recovery options
+
+### When Implementing Retries
+1. **CHECK** error.retryable flag
+2. **IMPLEMENT** exponential backoff
+3. **SET** retry limit
+4. **LOG** retry attempts
+5. **FAIL** after max retries
+
+### Code Style Rules
+- **USE** typed error creation
+- **PROVIDE** clear error messages
+- **INCLUDE** relevant context
+- **HANDLE** all error types
+- **LOG** error information
+
+## 📦 Available Function
+
+### createVideoError
+
+**Refer to**: [`gemini-video-error.ts`](./gemini-video-error.ts)
+
+**Parameters:**
+- `type`: VideoGenerationErrorType - Error category
+- `message`: string - Human-readable error message
+- `statusCode?`: number - HTTP status code
+
+**Returns:** VideoGenerationError
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Error Utilities**: [`../utils/ERROR_UTILITIES.md`](../utils/ERROR_UTILITIES.md)
+- **Retry Service**: [`RETRY_SERVICE.md`](./RETRY_SERVICE.md)
+
+## 📋 Error Types
+
+### NETWORK
+Network-related errors (retryable)
+
+### TIMEOUT
+Request timeout (retryable)
+
+### API
+API-level errors (may be retryable)
+
+### VALIDATION
+Input validation errors (not retryable)
+
+### QUOTA
+Quota/rate limit errors (not retryable)
+
+### UNKNOWN
+Uncategorized errors
+
+### Retry Behavior
+
+| Error Type | Retryable | Description |
+|------------|-----------|-------------|
+| NETWORK | Yes | Transient network issues |
+| TIMEOUT | Yes | Request timeouts |
+| API | Maybe | API-specific errors |
+| VALIDATION | No | Invalid input |
+| QUOTA | No | Rate limit exceeded |
+| UNKNOWN | Maybe | Uncategorized errors |
+
+## 🎓 Usage Patterns
+
+### Error Creation
+1. Identify error type
+2. Call createVideoError()
+3. Provide message and status
+4. Include context
+5. Throw or return error
+
+### Error Handling
+1. Catch video errors
+2. Check error type
+3. Determine retry eligibility
+4. Handle appropriately
+5. Inform user
+
+### Retry Logic
+1. Check error.retryable
+2. Implement backoff
+3. Set retry limit
+4. Log attempts
+5. Fail after max retries
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use generic errors
+- Skip error type specification
+- Ignore retry flag
+- Expose sensitive data
+- Suppress errors
+
+### Do
+- Use typed error creation
+- Specify error type correctly
+- Check retry flag
+- Provide clear messages
+- Handle all error cases
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)