@umituz/react-native-ai-fal-provider 2.0.11 → 2.0.15

package/src/infrastructure/services/fal-provider.README.md

@@ -1,474 +0,0 @@
-# FalProvider
-
-FAL AI provider service class implementing IAIProvider interface.
-
-**Location:** `src/infrastructure/services/fal-provider.ts`
-
-## Overview
-
-The `FalProvider` class is the central service for all interactions with FAL AI. It implements the `IAIProvider` interface to provide a provider-agnostic architecture for AI generation operations.
-
-## Purpose
-
-Manages FAL AI API interactions including:
-- Provider initialization and configuration
-- Job submission and status tracking
-- Image and video feature processing
-- Request lifecycle management
-- Error handling and retry logic
-
-## Singleton Instance
-
-**Import:**
-```typescript
-import { falProvider } from '@umituz/react-native-ai-fal-provider';
-```
-
-**Usage:**
-Use the exported `falProvider` singleton instance. Do not create new instances with `new FalProvider()`.
-
-**Implementation:** See `src/infrastructure/services/fal-provider.ts` for complete class definition
-
-## Initialization Methods
-
-### initialize
-
-Initialize provider with API key and configuration.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `configData` | `AIProviderConfig` | ✅ Yes | Configuration object |
-
-**Config Structure:**
-- `apiKey`: FAL API key (required)
-- `maxRetries`: Maximum retry attempts (optional)
-- `baseDelay`: Base delay for retries in ms (optional)
-- `maxDelay`: Maximum delay for retries in ms (optional)
-
-**Usage:**
-Call once at application startup with your FAL API key and optional retry configuration.
-
-### isInitialized
-
-Check if provider has been initialized.
-
-**Returns:** `boolean` - True if provider is initialized
-
-**Usage:**
-Use this check before calling provider methods to ensure initialization.
-
-### reset
-
-Reset provider to initial state.
-
-**Usage:**
-Call this to clear all provider state and configuration. Use for cleanup or reinitialization.
-
-## Capability Methods
-
-### getCapabilities
-
-Get provider capabilities for image and video features.
-
-**Returns:** `ProviderCapabilities` object containing:
-- `imageFeatures`: Array of supported image feature types
-- `videoFeatures`: Array of supported video feature types
-
-**Usage:**
-Use to determine which features are available before attempting to use them.
-
-**Related:**
-- Feature model mappings: `src/domain/constants/feature-models.constants.ts`
-
-### isFeatureSupported
-
-Check if a specific feature is supported.
-
-**Parameters:**
-- `feature`: Image or video feature type to check
-
-**Returns:** `boolean` - True if feature is supported
-
-**Usage:**
-Check feature support before attempting to use image or video features.
-
-### getImageFeatureModel
-
-Get model ID for an image feature.
-
-**Parameters:**
-- `feature`: Image feature type
-
-**Returns:** `string` - FAL model ID
-
-**Usage:**
-Retrieve the appropriate model ID for image processing features.
-
-**Related:**
-- Image feature models: `src/domain/constants/feature-models.constants.ts`
-- Image feature builder: `src/infrastructure/builders/image-feature-builder.ts`
-
-### getVideoFeatureModel
-
-Get model ID for a video feature.
-
-**Parameters:**
-- `feature`: Video feature type
-
-**Returns:** `string` - FAL model ID
-
-**Usage:**
-Retrieve the appropriate model ID for video generation features.
-
-**Related:**
-- Video feature models: `src/domain/constants/feature-models.constants.ts`
-- Video feature builder: `src/infrastructure/builders/video-feature-builder.ts`
-
-### buildImageFeatureInput
-
-Build input object for image feature.
-
-**Parameters:**
-- `feature`: Image feature type
-- `data`: Feature-specific input data
-
-**Returns:** `Record<string, unknown>` - Input object for API
-
-**Usage:**
-Use to construct properly formatted input objects for image features.
-
-**Related:**
-- Input builder utilities: `src/infrastructure/utils/image-feature-builders.util.ts`
-- Input types: `src/domain/types/input-builders.types.ts`
-
-### buildVideoFeatureInput
-
-Build input object for video feature.
-
-**Parameters:**
-- `feature`: Video feature type
-- `data`: Feature-specific input data
-
-**Returns:** `Record<string, unknown>` - Input object for API
-
-**Usage:**
-Use to construct properly formatted input objects for video features.
-
-**Related:**
-- Input builder utilities: `src/infrastructure/utils/video-feature-builders.util.ts`
-- Input types: `src/domain/types/input-builders.types.ts`
-
-## Job Management Methods
-
-### submitJob
-
-Submit job to FAL queue.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `model` | `string` | ✅ Yes | FAL model ID |
-| `input` | `Record<string, unknown>` | ✅ Yes | Job input object |
-
-**Returns:** `JobSubmission` object containing:
-- `requestId`: Unique job identifier
-- `statusUrl`: URL to check job status
-- `responseUrl`: URL to get job result
-
-**Usage:**
-Use for non-blocking job submission. Combine with status polling for async workflows.
-
-### getJobStatus
-
-Check job status.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `model` | `string` | ✅ Yes | FAL model ID |
-| `requestId` | `string` | ✅ Yes | Job request ID |
-
-**Returns:** `JobStatus` object with current status and queue position
-
-**Usage:**
-Poll this method to track job progress after submission.
-
-**Related:**
-- Status mapper: `src/infrastructure/services/fal-status-mapper.ts`
-- Queue status types: `src/domain/entities/fal.types.ts`
-
-### getJobResult
-
-Get completed job result.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `model` | `string` | ✅ Yes | FAL model ID |
-| `requestId` | `string` | ✅ Yes | Job request ID |
-
-**Returns:** Job result object (type parameter available for typing)
-
-**Usage:**
-Call this after job completes to retrieve the final result.
-
-### subscribe
-
-Submit job and wait for completion with automatic polling.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `model` | `string` | ✅ Yes | FAL model ID |
-| `input` | `Record<string, unknown>` | ✅ Yes | Job input object |
-| `options` | `SubscribeOptions<T>` | ❌ No | Optional configuration |
-
-**Options Structure:**
-- `timeoutMs`: Maximum time to wait for completion
-- `onQueueUpdate`: Callback for status updates during polling
-
-**Returns:** Job result object (type parameter available for typing)
-
-**Usage:**
-Use for most common use case - submit job and wait for result with automatic retry and polling logic.
-
-**Related:**
-- Subscription handler: `src/infrastructure/services/fal-provider-subscription.ts`
-
-### run
-
-Run job synchronously.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `model` | `string` | ✅ Yes | FAL model ID |
-| `input` | `Record<string, unknown>` | ✅ Yes | Job input object |
-| `options` | `RunOptions` | ❌ No | Optional configuration |
-
-**Returns:** Job result object
-
-**Usage:**
-Use for models that support synchronous execution. Faster than subscribe for supported models.
-
-## Request Control Methods
-
-### cancelCurrentRequest
-
-Cancel currently running request.
-
-**Usage:**
-Call to abort in-progress requests. Useful for cleanup and user cancellation.
-
-### hasRunningRequest
-
-Check if there's a running request.
-
-**Returns:** `boolean` - True if request is in progress
-
-**Usage:**
-Check before starting new requests to prevent conflicts. Use with `cancelCurrentRequest()` for request management.
-
-## Usage Guidelines
-
-### For Application Setup
-
-**Initialization:**
-1. Import `falProvider` singleton
-2. Call `initialize()` at app startup with API key
-3. Check `isInitialized()` before use
-4. Configure retry options as needed
-
-**Best Practices:**
-- Initialize once at application startup
-- Store API key securely (environment variable, secure storage)
-- Check initialization status before operations
-- Handle initialization errors gracefully
-
-### For Feature Detection
-
-**Capability Checking:**
-1. Use `getCapabilities()` to list available features
-2. Use `isFeatureSupported()` before using features
-3. Check specific feature types for UI display
-4. Handle unsupported features gracefully
-
-**Feature Models:**
-1. Use `getImageFeatureModel()` for image features
-2. Use `getVideoFeatureModel()` for video features
-3. Build inputs with `buildImageFeatureInput()` or `buildVideoFeatureInput()`
-4. Pass model ID and input to subscribe/run methods
-
-**Related:**
-- Feature constants: `src/domain/constants/feature-models.constants.ts`
-- Builder utilities: `src/infrastructure/utils/image-feature-builders.util.ts`
-
-### For Job Execution
-
-**Standard Flow:**
-1. Build input object for model
-2. Call `subscribe()` with model ID and input
-3. Handle result or error
-4. Update UI with result
-
-**Advanced Flow:**
-1. Use `submitJob()` for non-blocking submission
-2. Poll `getJobStatus()` for progress updates
-3. Call `getJobResult()` when status is COMPLETED
-4. Handle errors and timeouts appropriately
-
-**Related:**
-- Job metadata: `src/infrastructure/utils/job-metadata/index.ts`
-- Status types: `src/domain/entities/fal.types.ts`
-
-### For Request Management
-
-**Cancellation:**
-1. Check `hasRunningRequest()` before new requests
-2. Call `cancelCurrentRequest()` to abort
-3. Wait briefly before starting new request
-4. Handle cleanup appropriately
-
-**Cleanup:**
-1. Cancel running requests on unmount
-2. Call `reset()` if needed to clear state
-3. Release resources appropriately
-4. Handle state reset errors
-
-## Best Practices
-
-### 1. Use Singleton Instance
-
-Always use the exported `falProvider` singleton:
-- Import from package root
-- Don't create new instances
-- Initialize once at startup
-- Share across application
-
-### 2. Validate Before Operations
-
-Check initialization and feature support:
-- Use `isInitialized()` before operations
-- Use `isFeatureSupported()` before features
-- Handle unsupported features gracefully
-- Provide user feedback for limitations
-
-### 3. Handle Request Lifecycle
-
-Manage requests properly:
-- Check `hasRunningRequest()` before starting
-- Cancel requests when appropriate
-- Clean up on unmount/exit
-- Handle timeouts and errors
-
-### 4. Build Inputs Correctly
-
-Use provided builder functions:
-- Use `buildImageFeatureInput()` for images
-- Use `buildVideoFeatureInput()` for videos
-- Follow input type definitions
-- Validate input data structure
-
-**Related:**
-- Input types: `src/domain/types/input-builders.types.ts`
-- Builder utilities: `src/infrastructure/utils/image-feature-builders.util.ts`
-
-### 5. Handle Errors Appropriately
-
-Implement comprehensive error handling:
-- Catch and categorize errors
-- Retry when appropriate
-- Display user-friendly messages
-- Log for debugging
-
-**Related:**
-- Error mapper: `src/infrastructure/utils/error-mapper.ts`
-- Error categorizer: `src/infrastructure/utils/error-categorizer.ts`
-
-## For AI Agents
-
-### When Using FalProvider
-
-**DO:**
-- Use the singleton `falProvider` instance
-- Initialize at application startup
-- Check `isInitialized()` before operations
-- Use builder functions for inputs
-- Handle errors appropriately
-- Cancel running requests when needed
-- Use `subscribe()` for most operations
-
-**DON'T:**
-- Create new instances with `new FalProvider()`
-- Skip initialization check
-- Build input objects manually
-- Ignore running requests
-- Forget error handling
-- Use deprecated methods
-
-### When Adding Features
-
-**For New Image Features:**
-1. Add feature to `ImageFeatureType` in types
-2. Add model mapping to `feature-models.constants.ts`
-3. Add builder function to `image-feature-builders.util.ts`
-4. Update `buildImageFeatureInput()` if needed
-5. Document feature in this README
-
-**For New Video Features:**
-1. Add feature to `VideoFeatureType` in types
-2. Add model mapping to `feature-models.constants.ts`
-3. Add builder function to `video-feature-builders.util.ts`
-4. Update `buildVideoFeatureInput()` if needed
-5. Document feature in this README
-
-**For New Provider Methods:**
-1. Add method to `FalProvider` class
-2. Update `IAIProvider` interface if needed
-3. Add error handling and validation
-4. Update this README with usage guidelines
-5. Test with all feature types
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/services/fal-provider.ts`
-
-**Key Methods:**
-- `initialize(config: AIProviderConfig): void`
-- `isInitialized(): boolean`
-- `getCapabilities(): ProviderCapabilities`
-- `subscribe<T>(model, input, options?): Promise<T>`
-- `run<T>(model, input, options?): Promise<T>`
-- `submitJob(model, input): Promise<JobSubmission>`
-- `getJobStatus(model, requestId): Promise<JobStatus>`
-- `getJobResult<T>(model, requestId): Promise<T>`
-- `cancelCurrentRequest(): void`
-- `hasRunningRequest(): boolean`
-- `reset(): void`
-
-**Dependencies:**
-- Implements `IAIProvider` interface
-- Uses `@fal-ai/client` for API calls
-- Integrates with error handling utilities
-- Uses job metadata for tracking
-
-**Related:**
-- Subscription handler: `src/infrastructure/services/fal-provider-subscription.ts`
-- Provider constants: `src/infrastructure/services/fal-provider.constants.ts`
-- Status mapper: `src/infrastructure/services/fal-status-mapper.ts`
-- Provider types: `src/domain/entities/fal.types.ts`
-
-## Related Documentation
-
-- [FalProvider Subscription](./fal-provider-subscription.README.md)
-- [FalProvider Constants](./fal-provider.constants.README.md)
-- [Fal Status Mapper](./fal-status-mapper.README.md)
-- [Image Feature Builder](../builders/image-feature-builder.README.md)
-- [Video Feature Builder](../builders/video-feature-builder.README.md)

package/src/infrastructure/services/fal-status-mapper.README.md

@@ -1,246 +0,0 @@
-# FAL Status Mapper
-
-Maps FAL queue status to standard job status format.
-
-**Location:** `src/infrastructure/services/fal-status-mapper.ts`
-
-## Overview
-
-This module converts status objects from the FAL API into the standard `JobStatus` format, providing consistency across different AI providers.
-
-## Purpose
-
-Provides status mapping by:
-- Converting FAL status to standard format
-- Normalizing log entries
-- Providing safe defaults
-- Maintaining consistency
-- Supporting status tracking
-
-## Import
-
-```typescript
-import {
-  mapFalStatusToJobStatus
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-## Functions
-
-### mapFalStatusToJobStatus
-
-Converts FAL queue status to JobStatus format.
-
-**Parameters:**
-- `status`: FAL queue status object
-
-**Returns:** Standardized job status object
-
-**Input Structure (FalQueueStatus):**
-- `status`: FAL status string
-- `requestId`: Request identifier
-- `logs`: Array of log entries (optional)
-- `queuePosition`: Position in queue (optional)
-
-**Output Structure (JobStatus):**
-- `status`: Standardized status enum
-- `logs`: Array of standardized log entries
-- `queuePosition`: Position in queue (optional)
-
-## Status Mapping
-
-### Mapping Table
-
-| FAL Status | JobStatus | Description |
-|------------|-----------|-------------|
-| `IN_QUEUE` | `IN_QUEUE` | Job is queued |
-| `IN_PROGRESS` | `IN_PROGRESS` | Job is processing |
-| `COMPLETED` | `COMPLETED` | Job completed successfully |
-| `FAILED` | `FAILED` | Job failed |
-| *(invalid)* | `IN_PROGRESS` | Default fallback |
-
-## Log Mapping
-
-FAL log entries are mapped to JobLogEntry format:
-
-**Transformation:**
-- `message`: Preserved as-is
-- `level`: Defaults to 'info' if missing
-- `timestamp`: Defaults to current time if missing
-
-**Safe Defaults:**
-- Missing level → 'info'
-- Missing timestamp → current ISO time
-- Missing logs → empty array
-- Invalid status → 'IN_PROGRESS'
-
-## Usage Guidelines
-
-### For Status Conversion
-
-**Conversion Pattern:**
-1. Receive FAL status from API
-2. Call mapFalStatusToJobStatus
-3. Use standardized status
-4. Display in UI components
-5. Track status changes
-
-**Best Practices:**
-- Always map FAL status before use
-- Handle missing log fields
-- Check for invalid status
-- Use safe defaults
-- Validate output if needed
-
-### For Status Tracking
-
-**Tracking Pattern:**
-1. Map status on each update
-2. Compare with previous status
-3. Detect status changes
-4. Update UI accordingly
-5. Track transitions
-
-**Best Practices:**
-- Store mapped status
-- Compare for changes
-- Track status history
-- Calculate durations
-- Update state appropriately
-
-## Best Practices
-
-### 1. Always Map Status
-
-Convert FAL status immediately:
-- Map before storing in state
-- Map before displaying in UI
-- Map before comparing
-- Use mapped status consistently
-- Don't use raw FAL status
-
-### 2. Handle Missing Fields
-
-Account for optional fields:
-- Check for missing logs
-- Handle missing timestamps
-- Validate log levels
-- Provide safe defaults
-- Don't assume fields exist
-
-### 3. Validate Status
-
-Check for invalid values:
-- Handle unknown status strings
-- Use fallback for invalid status
-- Log validation failures
-- Provide safe defaults
-- Don't crash on bad data
-
-### 4. Track Changes
-
-Monitor status transitions:
-- Compare current with previous
-- Detect status changes
-- Calculate transition times
-- Update UI on changes
-- Maintain status history
-
-### 5. Use Type Safety
-
-Leverage TypeScript types:
-- Use proper type definitions
-- Check instanceof for errors
-- Use type guards
-- Validate input types
-- Maintain type safety
-
-## For AI Agents
-
-### When Mapping Status
-
-**DO:**
-- Map all FAL status objects
-- Handle missing log fields
-- Provide safe defaults
-- Validate output status
-- Use mapped status consistently
-- Check for invalid values
-- Handle errors gracefully
-
-**DON'T:**
-- Use raw FAL status
-- Assume all fields exist
-- Skip validation
-- Ignore missing data
-- Use inconsistent formats
-- Create type mismatches
-- Crash on bad data
-
-### When Tracking Status
-
-**DO:**
-- Store mapped status
-- Compare for changes
-- Track transitions
-- Update UI appropriately
-- Calculate durations
-- Maintain history
-- Handle updates properly
-
-**DON'T:**
-- Store raw FAL status
-- Skip comparison logic
-- Ignore transitions
-- Update UI inconsistently
-- Lose status information
-- Create memory leaks
-- Handle updates poorly
-
-### When Processing Logs
-
-**DO:**
-- Handle missing logs array
-- Provide default timestamps
-- Default log level to 'info'
-- Validate log structure
-- Process logs safely
-- Display log information
-- Handle empty logs
-
-**DON'T:**
-- Assume logs exist
-- Skip log processing
-- Ignore missing fields
-- Create unsafe defaults
-- Process logs inconsistently
-- Hide log information
-- Crash on bad logs
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/services/fal-status-mapper.ts`
-
-**Dependencies:**
-- FAL types
-- Job status types
-- No external dependencies
-
-**Mapping Logic:**
-- Status string mapping
-- Log entry transformation
-- Safe defaults
-- Fallback handling
-- Type validation
-
-**Import:**
-```typescript
-import {
-  mapFalStatusToJobStatus
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-**Related:**
-- FAL types: `src/domain/entities/fal.types.ts`
-- Job status: Provider-agnostic job status types
-- Subscription handler: `src/infrastructure/services/fal-provider-subscription.ts`