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

package/src/infrastructure/utils/timing-helpers.util.ts

@@ -1,56 +0,0 @@
-/**
- * Timing Helper Utilities
- * Functions for timing, debouncing, and throttling
- */
-
-/**
- * Calculate timeout with jitter to avoid thundering herd
- */
-export function calculateTimeoutWithJitter(
-  baseTimeout: number,
-  jitterPercent: number = 0.1
-): number {
-  const jitter = baseTimeout * jitterPercent;
-  const randomJitter = Math.random() * jitter - jitter / 2;
-  return Math.max(1000, baseTimeout + randomJitter);
-}
-
-/**
- * Debounce function (for rate limiting)
- */
-export function debounce<T extends (...args: never[]) => unknown>(
-  func: T,
-  wait: number
-): (...args: Parameters<T>) => void {
-  let timeout: ReturnType<typeof setTimeout> | null = null;
-
-  return function executedFunction(...args: Parameters<T>) {
-    const later = () => {
-      timeout = null;
-      func(...args);
-    };
-
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-    timeout = setTimeout(later, wait);
-  };
-}
-
-/**
- * Simple throttle function
- */
-export function throttle<T extends (...args: never[]) => unknown>(
-  func: T,
-  limit: number
-): (...args: Parameters<T>) => void {
-  let inThrottle = false;
-
-  return function executedFunction(...args: Parameters<T>) {
-    if (!inThrottle) {
-      func(...args);
-      inThrottle = true;
-      setTimeout(() => (inThrottle = false), limit);
-    }
-  };
-}

package/src/infrastructure/utils/type-guards.util.README.md

@@ -1,371 +0,0 @@
-# Type Guards & Validators
-
-Runtime type checking and validation helper functions for FAL AI operations.
-
-**Location:** `src/infrastructure/utils/type-guards.util.ts`
-
-## Overview
-
-This module provides runtime type checking and validation functions. It brings TypeScript type system to runtime, enabling detection of invalid data and type-safe operations.
-
-## Purpose
-
-Enhances type safety by:
-- Providing runtime type guards for enums
-- Validating data structures
-- Checking image data validity
-- Validating API keys
-- Ensuring prompt safety
-- Preventing invalid data from reaching APIs
-
-## Import
-
-```typescript
-import {
-  isFalModelType,
-  isModelType,
-  isFalErrorType,
-  isValidBase64Image,
-  isValidApiKey,
-  isValidPrompt
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-## Type Guard Functions
-
-### isFalModelType
-
-Check if value is valid FAL model type.
-
-**Parameters:**
-- `value`: Unknown value to check
-
-**Returns:** `boolean` - True if value is valid `FalModelType`
-
-**Valid Values:**
-- `text-to-image`
-- `text-to-video`
-- `text-to-voice`
-- `image-to-video`
-- `image-to-image`
-- `text-to-text`
-
-**Usage:**
-Use before processing model type values. Enables type narrowing in TypeScript. Use in validation logic and user input processing.
-
-**Implementation:** See complete validation in `src/infrastructure/utils/type-guards.util.ts`
-
-### isModelType
-
-Check if value is valid model type for hooks.
-
-**Parameters:**
-- `value`: Unknown value to check
-
-**Returns:** `boolean` - True if value is valid `ModelType`
-
-**Valid Values:**
-- `text-to-image`
-- `text-to-video`
-- `image-to-video`
-- `text-to-voice`
-
-**Usage:**
-Use when validating model type for `useModels` hook. Subset of `FalModelType` for user-facing model selection. Enables type-safe model filtering.
-
-**Related:**
-- Model types: `src/domain/types/model-selection.types.ts`
-- useModels hook: `src/presentation/hooks/use-models.ts`
-
-### isFalErrorType
-
-Check if value is valid FAL error type.
-
-**Parameters:**
-- `value`: Unknown value to check
-
-**Returns:** `boolean` - True if value is valid `FalErrorType`
-
-**Valid Values:**
-- `network`
-- `timeout`
-- `authentication`
-- `quota_exceeded`
-- `rate_limit`
-- `invalid_input`
-- `model_unavailable`
-- `nsfw_content`
-- `validation`
-- `content_policy`
-- `unknown`
-
-**Usage:**
-Use when validating error type values. Enables type-safe error handling. Use in error categorization and user error display.
-
-**Related:**
-- Error types: `src/domain/entities/error.types.ts`
-- Error categorizer: `src/infrastructure/utils/error-categorizer.ts`
-
-## Validation Functions
-
-### isValidBase64Image
-
-Check if base64 image data is valid.
-
-**Parameters:**
-- `data`: Unknown value to check
-
-**Returns:** `boolean` - True if valid base64 image
-
-**Validation Rules:**
-- Checks if string
-- Validates base64 format
-- Checks for valid image headers
-- Ensures non-empty data
-
-**Usage:**
-Use this function before sending image data to FAL API. Validates that image data is properly formatted base64. Prevents API errors from invalid image data.
-
-**Related:**
-- Helper functions: `src/infrastructure/utils/helpers.util.ts`
-
-### isValidApiKey
-
-Check if API key is valid format.
-
-**Parameters:**
-- `key`: API key string to validate
-
-**Returns:** `boolean` - True if API key format is valid
-
-**Validation Rules:**
-- Checks if string
-- Validates minimum length
-- Checks for valid characters
-- Ensures not empty
-
-**Usage:**
-Use this function before setting API key. Validates FAL API key format. Prevents errors from invalid keys.
-
-**Implementation:** See validation logic in `src/infrastructure/utils/type-guards.util.ts`
-
-### isValidPrompt
-
-Check if prompt text is valid.
-
-**Parameters:**
-- `prompt`: Prompt text to validate
-
-**Returns:** `boolean` - True if prompt is valid
-
-**Validation Rules:**
-- Checks if string
-- Ensures not empty
-- Validates length limits
-- Checks for prohibited content
-
-**Usage:**
-Use this function before sending prompt to FAL API. Validates prompt is safe and within limits. Prevents errors from invalid prompts.
-
-**Related:**
-- Helper functions: `src/infrastructure/utils/helpers.util.ts`
-
-## Usage Guidelines
-
-### For Type Safety
-
-**Type Narrowing Pattern:**
-1. Receive unknown value from external source
-2. Use appropriate type guard function
-3. TypeScript narrows type in conditional block
-4. Safely use value with correct type
-
-**Benefits:**
-- Runtime type safety
-- Compile-time type narrowing
-- Prevents type errors
-- Catches invalid data early
-
-### For Data Validation
-
-**Validation Pattern:**
-1. Receive data from user input or API
-2. Use validation function appropriate to data type
-3. Check return value
-4. Handle invalid data appropriately
-
-**Best Practices:**
-- Always validate external data
-- Validate user input before processing
-- Check API responses before use
-- Provide clear error messages for invalid data
-
-### For Image Data
-
-**Image Validation Pattern:**
-1. Receive image data from source
-2. Use `isValidBase64Image()` to validate
-3. Use `formatImageDataUri()` if needed
-4. Pass to FAL API only if valid
-
-**Related:**
-- Helper functions: `src/infrastructure/utils/helpers.util.ts`
-- Image feature builders: `src/infrastructure/utils/image-feature-builders.util.ts`
-
-### For Error Handling
-
-**Error Type Validation:**
-1. Receive error type from unknown source
-2. Use `isFalErrorType()` to validate
-3. Use in switch statement for type-safe handling
-4. Handle all error types
-
-**Related:**
-- Error types: `src/domain/entities/error.types.ts`
-
-## Best Practices
-
-### 1. Always Validate External Data
-
-Validate all data from external sources:
-- User input
-- API responses
-- File uploads
-- Configuration data
-
-### 2. Use Type Guards for Type Safety
-
-Leverage TypeScript type narrowing:
-- Use before processing unknown values
-- Combine with conditional types
-- Enable type-safe operations
-- Prevent type errors
-
-### 3. Validate Before API Calls
-
-Check data before sending to FAL API:
-- Validate image data format
-- Check prompt validity
-- Verify API key format
-- Prevent unnecessary API errors
-
-### 4. Provide Clear Error Messages
-
-Give useful feedback for invalid data:
-- Indicate what failed validation
-- Provide guidance for correction
-- Show format requirements
-- Suggest valid examples
-
-### 5. Handle Invalid Data Gracefully
-
-Respond appropriately to invalid data:
-- Return error to user
-- Log validation failures
-- Don't crash application
-- Provide recovery options
-
-## For AI Agents
-
-### When Using Type Guards
-
-**DO:**
-- Import from package root
-- Use type guards before processing
-- Validate all external data
-- Leverage type narrowing
-- Handle invalid data
-- Provide clear errors
-- Use appropriate guard for data type
-
-**DON'T:**
-- Assume data types
-- Skip type checking
-- Process invalid data
-- Ignore type safety
-- Create duplicate guards
-- Use wrong guard for data
-- Assume validation passes
-
-### When Validating Data
-
-**DO:**
-- Validate user input
-- Check API responses
-- Verify file uploads
-- Validate configuration
-- Use specific validation functions
-- Handle invalid data appropriately
-- Log validation failures
-
-**DON'T:**
-- Skip validation
-- Assume data format
-- Process invalid data
-- Ignore validation results
-- Use generic checks only
-- Allow invalid data through
-- Hide validation errors
-
-### When Adding Guards
-
-**For New Type Guards:**
-1. Add to type guards file
-2. Follow naming convention (`isXxx`)
-3. Return boolean for simple checks
-4. Return detailed info if needed
-5. Update exports
-6. Document in this README
-
-**For New Validators:**
-1. Add validation function
-2. Follow naming convention (`isValidXxx`)
-3. Check all relevant conditions
-4. Provide clear return values
-5. Handle edge cases
-6. Document validation rules
-
-**For Enhanced Validation:**
-1. Review existing validation logic
-2. Add stricter checks if needed
-3. Improve error messages
-4. Update documentation
-5. Test with edge cases
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/utils/type-guards.util.ts`
-
-**Dependencies:**
-- No external dependencies
-- Pure validation functions
-- Used throughout the provider
-
-**Function Categories:**
-- Type guards for enum validation
-- Data validation functions
-- Format validation functions
-- Safety checks
-
-**Import:**
-```typescript
-import {
-  isFalModelType,
-  isModelType,
-  isFalErrorType,
-  isValidBase64Image,
-  isValidApiKey,
-  isValidPrompt
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-**Related:**
-- Helper functions: `src/infrastructure/utils/helpers.util.ts`
-- Error types: `src/domain/entities/error.types.ts`
-- Model types: `src/domain/types/model-selection.types.ts`
-
-## Related Documentation
-
-- [Helper Utilities](./helpers.util.README.md)
-- [Error Types](../../domain/entities/error.types.README.md)
-- [Model Selection Types](../../domain/types/model-selection.types.README.md)

package/src/infrastructure/validators/index.README.md

@@ -1,205 +0,0 @@
-# Validators Module
-
-Central export point for all validator functions.
-
-**Location:** `src/infrastructure/validators/index.ts`
-
-## Overview
-
-The validators module provides content validation utilities to ensure AI-generated content meets safety and quality standards. Currently, it focuses on NSFW (Not Safe For Work) content detection.
-
-## Purpose
-
-Provides validation by:
-- Checking content safety
-- Preventing inappropriate content
-- Enforcing content policies
-- Supporting custom validators
-- Enabling content filtering
-
-## Import
-
-```typescript
-import {
-  validateNSFWContent
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-## Exports
-
-### validateNSFWContent
-
-Validates AI-generated content for NSFW material.
-
-**Path:** `src/infrastructure/validators/nsfw-validator.ts`
-
-**Documentation:** See `nsfw-validator.README.md`
-
-**Usage:**
-Validate content immediately after generation. Throw NSFWContentError if violation detected. Handle error specifically in UI.
-
-## Usage Guidelines
-
-### For Content Validation
-
-**Validation Pattern:**
-1. Receive generation result
-2. Call validateNSFWContent
-3. Catch NSFWContentError
-4. Display user-friendly message
-5. Block inappropriate content
-
-**Best Practices:**
-- Always validate user-facing content
-- Validate immediately after generation
-- Handle NSFW errors specifically
-- Don't retry NSFW requests
-- Track NSFW occurrences
-- Enforce content policies
-
-### For Error Handling
-
-**Error Pattern:**
-1. Catch NSFWContentError specifically
-2. Display clear error messages
-3. Guide users to acceptable content
-4. Block retry attempts
-5. Log violations appropriately
-
-**Best Practices:**
-- Check instanceof NSFWContentError
-- Show specific error messages
-- Prevent content display
-- Inform users clearly
-- Track violation patterns
-
-## Best Practices
-
-### 1. Always Validate User-Facing Content
-
-Validate all generated content before displaying:
-- Call validateNSFWContent after generation
-- Validate before saving to storage
-- Check before displaying in UI
-- Prevent NSFW content display
-- Enforce content policies
-
-### 2. Handle Validation Errors
-
-Process NSFW content errors:
-- Catch NSFWContentError specifically
-- Display user-friendly messages
-- Block inappropriate content display
-- Guide users to corrections
-- Track violation occurrences
-
-### 3. Validate Early
-
-Validate content as early as possible:
-- Validate immediately after generation
-- Check before saving to storage
-- Validate before displaying
-- Prevent NSFW content spread
-- Minimize exposure time
-
-### 4. Provide Context
-
-Track validation with context:
-- Log violation with user ID
-- Include prompt that caused violation
-- Timestamp the occurrence
-- Track violation patterns
-- Enforce rate limiting
-
-### 5. Enforce Consistently
-
-Apply validation uniformly:
-- Validate all user-generated content
-- Don't skip validation for any users
-- Apply same rules consistently
-- Update validation rules regularly
-- Monitor validation effectiveness
-
-## For AI Agents
-
-### When Using Validators
-
-**DO:**
-- Import from package root
-- Validate all user-facing content
-- Handle NSFW errors specifically
-- Display clear error messages
-- Track violation occurrences
-- Enforce content policies
-- Update validation rules
-
-**DON'T:**
-- Skip content validation
-- Display NSFW content
-- Ignore validation errors
-- Hide violation details
-- Allow inappropriate content
-- Forget policy enforcement
-- Create security issues
-
-### When Validating Content
-
-**DO:**
-- Validate immediately after generation
-- Check for NSFW concepts array
-- Throw NSFWContentError for violations
-- Handle validation errors gracefully
-- Log violations appropriately
-- Guide users to corrections
-
-**DON'T:**
-- Skip validation
-- Ignore NSFW concepts
-- Allow violations through
-- Display inappropriate content
-- Forget logging
-- Leave users uninformed
-- Create liability issues
-
-### When Handling Violations
-
-**DO:**
-- Check instanceof NSFWContentError
-- Display user-friendly messages
-- Block inappropriate content
-- Track violation patterns
-- Implement rate limiting
-- Suggest corrections
-
-**DON'T:**
-- Handle like other errors
-- Show technical details
-- Allow content display
-- Skip tracking
-- Enable retry attempts
-- Create policy violations
-
-## Implementation Notes
-
-**Location:** `src/infrastructure/validators/index.ts`
-
-**Dependencies:**
-- NSFW validator: `src/infrastructure/validators/nsfw-validator.ts`
-- NSFW error: `src/infrastructure/services/nsfw-content-error.ts`
-
-**Validation Categories:**
-- Content safety validation
-- Policy enforcement
-- User-facing content checks
-
-**Import:**
-```typescript
-import {
-  validateNSFWContent
-} from '@umituz/react-native-ai-fal-provider';
-```
-
-**Related:**
-- NSFW validator: `src/infrastructure/validators/nsfw-validator.ts`
-- NSFW error: `src/infrastructure/services/nsfw-content-error.ts`
-- Error mapper: `src/infrastructure/utils/error-mapper.ts`