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

package/src/infrastructure/services/nsfw-content-error.README.md

@@ -1,215 +0,0 @@
-# NSFW Content Error
-
-Error class for NSFW (Not Safe For Work) content detection.
-
-**Location:** `src/infrastructure/services/nsfw-content-error.ts`
-
-## Overview
-
-`NSFWContentError` is a custom error class thrown when AI-generated content violates NSFW or content policy guidelines.
-
-## Purpose
-
-Provides NSFW error handling by:
-- Identifying NSFW content violations
-- Supporting error categorization
-- Enabling specific error handling
-- Facilitating user feedback
-- Preventing inappropriate content
-
-## Import
-
-```typescript
-import {
-  NSFWContentError
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-## Class
-
-### NSFWContentError
-
-Custom error class for NSFW content detection.
-
-**Inheritance:**
-- Extends: `Error`
-- Name: `'NSFWContentError'`
-- Default message: `'NSFW content detected'`
-
-**Constructor:**
-- `message`: Optional custom error message
-
-**Properties:**
-- `name`: Error class name
-- `message`: Error description
-- `stack`: Call stack (inherited from Error)
-
-## Usage Guidelines
-
-### For Error Throwing
-
-**Throw Pattern:**
-1. Detect NSFW content
-2. Throw NSFWContentError
-3. Provide descriptive message
-4. Let error propagate
-5. Handle at appropriate level
-
-**Best Practices:**
-- Use specific, clear messages
-- Explain what was detected
-- Guide users to fix issue
-- Don't use vague messages
-- Be consistent in messaging
-
-### For Error Handling
-
-**Handling Pattern:**
-1. Catch errors from generation
-2. Check instanceof NSFWContentError
-3. Display user-friendly message
-4. Suggest corrective action
-5. Prevent retry for NSFW
-
-**Best Practices:**
-- Check type specifically
-- Show clear error messages
-- Block inappropriate content
-- Don't allow retry
-- Guide user behavior
-
-## Best Practices
-
-### 1. Use Descriptive Messages
-
-Provide clear error messages:
-- Explain what was detected
-- Be specific about violation
-- Use user-friendly language
-- Suggest alternatives
-- Maintain consistent messaging
-
-### 2. Handle Separately
-
-Treat NSFW errors differently:
-- Catch NSFWContentError specifically
-- Use different UI for NSFW
-- Prevent retry attempts
-- Track NSFW occurrences
-- Inform content policy
-
-### 3. Guide Users
-
-Help users understand:
-- Explain why content was blocked
-- Describe what violates policy
-- Suggest acceptable alternatives
-- Provide clear guidance
-- Enable quick correction
-
-### 4. Track Occurrences
-
-Monitor NSFW detection:
-- Log NSFW occurrences
-- Track frequency
-- Identify patterns
-- Implement rate limiting
-- Prevent abuse
-
-### 5. Prevent Retry
-
-Block NSFW retry attempts:
-- Mark errors as non-retryable
-- Disable retry buttons
-- Show appropriate messaging
-- Enforce content policy
-- Protect service integrity
-
-## For AI Agents
-
-### When Throwing NSFW Errors
-
-**DO:**
-- Throw NSFWContentError for violations
-- Use descriptive messages
-- Explain what was detected
-- Guide users to fix
-- Be specific and clear
-- Maintain consistency
-- Follow content policy
-
-**DON'T:**
-- Use generic error types
-- Provide vague messages
-- Skip explanations
-- Leave users confused
-- Use inconsistent messaging
-- Ignore policy guidelines
-- Allow inappropriate content
-
-### When Handling NSFW Errors
-
-**DO:**
-- Check instanceof NSFWContentError
-- Display user-friendly messages
-- Block retry attempts
-- Track occurrences
-- Inform users clearly
-- Suggest alternatives
-- Follow content policy
-
-**DON'T:**
-- Handle like other errors
-- Show technical details
-- Allow retry
-- Skip tracking
-- Confuse users
-- Hide the issue
-- Ignore violations
-
-### When Validating Content
-
-**DO:**
-- Validate all generated content
-- Check NSFW concepts array
-- Throw error for violations
-- Be consistent in checking
-- Log violations
-- Prevent inappropriate content
-- Update validation regularly
-
-**DON'T:**
-- Skip validation
-- Ignore NSFW concepts
-- Allow violations through
-- Be inconsistent
-- Forget logging
-- Allow inappropriate content
-- Use outdated rules
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/services/nsfw-content-error.ts`
-
-**Dependencies:**
-- No external dependencies
-- Extends built-in Error class
-
-**Error Characteristics:**
-- Named error class
-- Default and custom messages
-- Stack trace support
-- Type-checkable with instanceof
-- Compatible with try-catch
-
-**Import:**
-```typescript
-import {
-  NSFWContentError
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-**Related:**
-- NSFW validator: `src/infrastructure/validators/nsfw-validator.ts`
-- Error types: `src/domain/entities/error.types.ts`
-- Error mapper: `src/infrastructure/utils/error-mapper.ts`

package/src/infrastructure/utils/base-builders.util.README.md

@@ -1,313 +0,0 @@
-# Base Builders
-
-Base input builder functions for FAL API operations.
-
-**Location:** `src/infrastructure/utils/base-builders.util.ts`
-
-## Overview
-
-Base builders create standardized input objects for image processing operations. These functions convert raw base64 strings to data URI format and add necessary parameters for FAL API requests.
-
-## Purpose
-
-Simplifies input construction by:
-- Standardizing image input format across operations
-- Converting base64 to data URI automatically
-- Supporting single and dual image inputs
-- Merging optional parameters
-- Providing consistent input structure
-
-## Import
-
-```typescript
-import {
-  buildSingleImageInput,
-  buildDualImageInput
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-## Functions
-
-### buildSingleImageInput
-
-Create input object with single image.
-
-**Parameters:**
-- `base64`: Base64 format image (data URI or raw string)
-- `extraParams`: Optional additional parameters
-
-**Returns:**
-Input object with:
-- `image_url`: Data URI formatted image
-- `...extraParams`: Additional parameters merged in
-
-**Usage:**
-Use to build input for single-image operations. Automatically converts raw base64 to data URI. Preserves existing data URI format. Merges optional parameters into result.
-
-**Implementation:** See complete implementation in `src/infrastructure/utils/base-builders.util.ts`
-
-**Related:**
-- Image feature builders: `src/infrastructure/utils/image-feature-builders.util.ts`
-- Helper utilities: `src/infrastructure/utils/helpers.util.ts`
-
-### buildDualImageInput
-
-Create input object with two images.
-
-**Parameters:**
-- `sourceBase64`: Source image (base64)
-- `targetBase64`: Target image (base64)
-- `extraParams`: Optional additional parameters
-
-**Returns:**
-Input object with:
-- `image_url`: Source image as data URI
-- `second_image_url`: Target image as data URI
-- `...extraParams`: Additional parameters merged in
-
-**Usage:**
-Use to build input for dual-image operations like face swap. Both images automatically converted to data URI format. Preserves existing data URI format. Merges optional parameters.
-
-## Usage Guidelines
-
-### For Single Image Operations
-
-**Building Pattern:**
-1. Prepare base64 image data or data URI
-2. Call `buildSingleImageInput()` with image
-3. Add optional parameters if needed
-4. Pass result to FAL provider
-5. Handle response appropriately
-
-**Best Practices:**
-- Validate image format before building
-- Use data URI format for consistency
-- Add model-specific parameters in extraParams
-- Check model documentation for required parameters
-- Handle optional parameters appropriately
-
-**Related:**
-- Image feature builders: `src/infrastructure/utils/image-feature-builders.util.ts`
-- Type guards: `src/infrastructure/utils/type-guards.util.ts`
-
-### For Dual Image Operations
-
-**Building Pattern:**
-1. Prepare both source and target images
-2. Call `buildDualImageInput()` with both images
-3. Add optional parameters if needed
-4. Pass result to FAL provider
-5. Handle response appropriately
-
-**Parameter Order:**
-- First parameter: source/target image (depends on model)
-- Second parameter: second image
-- Check model documentation for correct order
-
-**Related:**
-- Image feature builders: `src/infrastructure/utils/image-feature-builders.util.ts`
-
-### For Parameter Configuration
-
-**Optional Parameters:**
-- Define in extraParams object
-- Model-specific parameters
-- Type-safe parameter objects recommended
-- Check model documentation for available options
-
-**Parameter Merging:**
-- ExtraParams shallow merged into result
-- Image properties not overwritten
-- Use specific parameter names from model docs
-- Test with different parameter combinations
-
-### For Pipeline Operations
-
-**Sequential Processing:**
-1. Build input for first operation
-2. Get result from first operation
-3. Extract image URL from result
-4. Convert to base64 if needed for next operation
-5. Build input for next operation
-6. Continue through pipeline
-
-**Parallel Processing:**
-1. Build inputs for multiple operations
-2. Execute operations in parallel
-3. Wait for all operations to complete
-4. Combine results as needed
-
-## Best Practices
-
-### 1. Validate Before Building
-
-Check image data:
-- Validate base64 format
-- Check image data is not corrupted
-- Ensure minimum resolution requirements
-- Verify image format (JPEG/PNG)
-- Use type guards for validation
-
-**Related:**
-- Type guards: `src/infrastructure/utils/type-guards.util.ts`
-- Helper utilities: `src/infrastructure/utils/helpers.util.ts`
-
-### 2. Use Data URI Format
-
-Maintain consistent format:
-- Builders automatically convert to data URI
-- Use data URI format for all images
-- Preserve existing data URI format
-- Don't double-format images
-- Check format before building
-
-### 3. Handle Parameters Correctly
-
-Configure model parameters:
-- Add model-specific parameters in extraParams
-- Check documentation for parameter names
-- Use typed parameter objects
-- Provide required parameters
-- Set appropriate defaults
-
-### 4. Build Reusable Wrappers
-
-Create specialized builders:
-- Wrap base builders for specific operations
-- Add validation in wrapper
-- Set default parameters
-- Simplify common operations
-- Maintain type safety
-
-### 5. Test Image Inputs
-
-Verify inputs work:
-- Test with real images
-- Check parameter combinations
-- Validate output format
-- Handle edge cases
-- Test with various image sizes
-
-## For AI Agents
-
-### When Using Base Builders
-
-**DO:**
-- Import from package root
-- Validate image data before building
-- Use appropriate builder for image count
-- Add model-specific parameters
-- Check model documentation
-- Handle data URI format correctly
-- Test with sample images
-
-**DON'T:**
-- Skip image validation
-- Use wrong builder for image count
-- Ignore model parameter requirements
-- Forget data URI conversion
-- Manually format data URIs
-- Mix up source/target order
-- Skip parameter documentation
-
-### When Building Inputs
-
-**DO:**
-- Use `buildSingleImageInput()` for single images
-- Use `buildDualImageInput()` for two images
-- Provide base64 or data URI format
-- Add optional parameters in extraParams
-- Validate before building
-- Check model requirements
-- Test output format
-
-**DON'T:**
-- Manually construct input objects
-- Skip data URI formatting
-- Forget required parameters
-- Use wrong parameter names
-- Ignore validation
-- Mix up parameter order
-- Create duplicate builders
-
-### When Handling Results
-
-**DO:**
-- Validate input format
-- Handle image URLs appropriately
-- Extract results correctly
-- Process returned data
-- Handle errors gracefully
-- Log issues for debugging
-- Test with real API
-
-**DON'T:**
-- Assume input format
-- Ignore image URLs
-- Skip result validation
-- Process data incorrectly
-- Forget error handling
-- Lose image data
-- Skip API testing
-
-### When Adding Builders
-
-**For New Base Builders:**
-1. Add function to base builders file
-2. Follow existing patterns
-3. Handle data URI formatting
-4. Support optional parameters
-5. Update exports
-6. Document in this README
-
-**For Enhanced Builders:**
-1. Review existing builders
-2. Add validation if needed
-3. Improve error handling
-4. Support new formats
-5. Update TypeScript types
-6. Test with various inputs
-
-**For Specialized Builders:**
-1. Wrap base builders appropriately
-2. Add domain-specific logic
-3. Set default parameters
-4. Validate inputs
-5. Export from appropriate module
-6. Document usage patterns
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/utils/base-builders.util.ts`
-
-**Dependencies:**
-- Uses helper utilities from `src/infrastructure/utils/helpers.util.ts`
-- No external dependencies
-- Pure builder functions
-
-**Builder Categories:**
-- Single image input builders
-- Dual image input builders
-- Parameter merging utilities
-- Data URI formatting
-
-**Import:**
-```typescript
-import {
-  buildSingleImageInput,
-  buildDualImageInput
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-**Related:**
-- Image feature builders: `src/infrastructure/utils/image-feature-builders.util.ts`
-- Video feature builders: `src/infrastructure/utils/video-feature-builders.util.ts`
-- Helper utilities: `src/infrastructure/utils/helpers.util.ts`
-- Type guards: `src/infrastructure/utils/type-guards.util.ts`
-
-## Related Documentation
-
-- [Image Feature Builders](./image-feature-builders.util.README.md)
-- [Video Feature Builders](./video-feature-builders.util.README.md)
-- [Helper Utilities](./helpers.util.README.md)
-- [Type Guards](./type-guards.util.README.md)

package/src/infrastructure/utils/cost-tracker-queries.ts

@@ -1,67 +0,0 @@
-/**
- * Cost Tracker Queries
- * Query functions for cost history analysis
- */
-
-import type { GenerationCost, CostSummary } from "../../domain/entities/cost-tracking.types";
-
-/**
- * Calculate cost summary from history
- */
-export function calculateCostSummary(
-  costHistory: readonly GenerationCost[],
-  currency: string
-): CostSummary {
-  const completedCosts = costHistory.filter((c) => c.actualCost > 0);
-  const totalCost = completedCosts.reduce((sum, c) => sum + c.actualCost, 0);
-  const totalGenerations = completedCosts.length;
-  const averageCost = totalGenerations > 0 ? totalCost / totalGenerations : 0;
-
-  const modelBreakdown: Record<string, number> = {};
-  const operationBreakdown: Record<string, number> = {};
-
-  for (const cost of completedCosts) {
-    modelBreakdown[cost.model] = (modelBreakdown[cost.model] ?? 0) + cost.actualCost;
-    operationBreakdown[cost.operation] = (operationBreakdown[cost.operation] ?? 0) + cost.actualCost;
-  }
-
-  return {
-    totalCost,
-    totalGenerations,
-    averageCost,
-    currency,
-    modelBreakdown,
-    operationBreakdown,
-  };
-}
-
-/**
- * Filter costs by model
- */
-export function filterCostsByModel(
-  costHistory: readonly GenerationCost[],
-  modelId: string
-): GenerationCost[] {
-  return costHistory.filter((c) => c.model === modelId);
-}
-
-/**
- * Filter costs by operation type
- */
-export function filterCostsByOperation(
-  costHistory: readonly GenerationCost[],
-  operation: string
-): GenerationCost[] {
-  return costHistory.filter((c) => c.operation === operation);
-}
-
-/**
- * Filter costs by time range
- */
-export function filterCostsByTimeRange(
-  costHistory: readonly GenerationCost[],
-  startTime: number,
-  endTime: number
-): GenerationCost[] {
-  return costHistory.filter((c) => c.timestamp >= startTime && c.timestamp <= endTime);
-}