@umituz/react-native-ai-fal-provider 3.2.52 → 3.2.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-fal-provider",
-  "version": "3.2.52",
+  "version": "3.2.53",
   "description": "FAL AI provider for React Native - implements IAIProvider interface for unified AI generation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domain/services/ErrorClassificationService.ts

@@ -0,0 +1,201 @@
+/**
+ * Domain Service: Error Classification
+ * Pure business logic for categorizing and extracting error information
+ * No infrastructure dependencies (except for @fal-ai/client types)
+ */
+
+import { ApiError, ValidationError } from "@fal-ai/client";
+import type { FalErrorInfo, FalErrorCategory } from "../entities/error.types";
+import { FalErrorType } from "../entities/error.types";
+
+/**
+ * HTTP status code to error type mapping
+ */
+const STATUS_TO_ERROR_TYPE: Record<number, FalErrorType> = {
+  400: FalErrorType.VALIDATION,
+  401: FalErrorType.AUTHENTICATION,
+  402: FalErrorType.QUOTA_EXCEEDED,
+  403: FalErrorType.AUTHENTICATION,
+  404: FalErrorType.MODEL_NOT_FOUND,
+  422: FalErrorType.VALIDATION,
+  429: FalErrorType.RATE_LIMIT,
+  500: FalErrorType.API_ERROR,
+  502: FalErrorType.API_ERROR,
+  503: FalErrorType.API_ERROR,
+  504: FalErrorType.API_ERROR,
+};
+
+const RETRYABLE_TYPES = new Set<FalErrorType>([
+  FalErrorType.NETWORK,
+  FalErrorType.TIMEOUT,
+  FalErrorType.RATE_LIMIT,
+]);
+
+/**
+ * Message-based error type detection (for non-ApiError errors)
+ */
+const MESSAGE_PATTERNS: Array<{ type: FalErrorType; patterns: string[] }> = [
+  {
+    type: FalErrorType.NETWORK,
+    patterns: ["network", "fetch", "econnrefused", "enotfound", "etimedout"],
+  },
+  { type: FalErrorType.TIMEOUT, patterns: ["timeout", "timed out"] },
+  {
+    type: FalErrorType.CONTENT_POLICY,
+    patterns: ["nsfw", "content_policy", "content policy", "policy violation"],
+  },
+  {
+    type: FalErrorType.IMAGE_TOO_SMALL,
+    patterns: [
+      "image_too_small",
+      "image dimensions are too small",
+      "minimum dimensions",
+    ],
+  },
+];
+
+/**
+ * Domain service for error classification
+ * Single responsibility: categorize errors and extract user-friendly messages
+ */
+export class ErrorClassificationService {
+  /**
+   * Categorize error using @fal-ai/client error types
+   * Priority: ApiError status code > message pattern matching
+   *
+   * @param error - Error to categorize
+   * @returns Error category with type, message key, and retryable flag
+   */
+  static categorizeError(error: unknown): FalErrorCategory {
+    // 1. ApiError (includes ValidationError) - use HTTP status code
+    if (error instanceof ApiError) {
+      const typeFromStatus = STATUS_TO_ERROR_TYPE[error.status];
+      if (typeFromStatus) {
+        return {
+          type: typeFromStatus,
+          messageKey: typeFromStatus,
+          retryable: RETRYABLE_TYPES.has(typeFromStatus),
+        };
+      }
+      // Unknown status code - still an API error
+      return {
+        type: FalErrorType.API_ERROR,
+        messageKey: "api_error",
+        retryable: false,
+      };
+    }
+
+    // 2. Standard Error - match message patterns
+    const message = (
+      error instanceof Error
+        ? error.message
+        : error != null
+        ? String(error)
+        : "unknown"
+    ).toLowerCase();
+
+    for (const { type, patterns } of MESSAGE_PATTERNS) {
+      if (patterns.some((p) => message.includes(p))) {
+        return {
+          type,
+          messageKey: type,
+          retryable: RETRYABLE_TYPES.has(type),
+        };
+      }
+    }
+
+    // 3. No match - UNKNOWN, not retryable
+    return {
+      type: FalErrorType.UNKNOWN,
+      messageKey: "unknown",
+      retryable: false,
+    };
+  }
+
+  /**
+   * Extract user-readable message from error
+   * Uses @fal-ai/client types for structured extraction
+   *
+   * @param error - Error to extract message from
+   * @returns User-friendly error message
+   */
+  static extractMessage(error: unknown): string {
+    // ValidationError - extract field-level messages
+    if (error instanceof ValidationError) {
+      const fieldErrors = error.fieldErrors;
+      if (Array.isArray(fieldErrors) && fieldErrors.length > 0) {
+        const messages = fieldErrors
+          .map(
+            (e) =>
+              e && typeof e === "object" && "msg" in e && typeof e.msg === "string"
+                ? e.msg
+                : null
+          )
+          .filter((msg): msg is string => msg !== null);
+        if (messages.length > 0) return messages.join("; ");
+      }
+      return error.message;
+    }
+
+    // ApiError - extract from body or message
+    if (error instanceof ApiError) {
+      const body = error.body as { detail?: Array<{ msg?: string }> } | undefined;
+
+      if (
+        body &&
+        body.detail &&
+        Array.isArray(body.detail) &&
+        body.detail.length > 0
+      ) {
+        const firstItem = body.detail[0];
+        if (
+          firstItem &&
+          typeof firstItem === "object" &&
+          typeof firstItem.msg === "string" &&
+          firstItem.msg
+        ) {
+          return firstItem.msg;
+        }
+      }
+      return error.message;
+    }
+
+    // Standard Error
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return error != null ? String(error) : "Unknown error";
+  }
+
+  /**
+   * Map error to FalErrorInfo with full categorization
+   *
+   * @param error - Error to map
+   * @returns Complete error information
+   */
+  static mapError(error: unknown): FalErrorInfo {
+    const category = this.categorizeError(error);
+    const message = this.extractMessage(error);
+
+    return {
+      type: category.type,
+      messageKey: `fal.errors.${category.messageKey}`,
+      retryable: category.retryable,
+      originalError: message,
+      originalErrorName: error instanceof Error ? error.name : undefined,
+      stack: error instanceof Error ? error.stack : undefined,
+      statusCode: error instanceof ApiError ? error.status : undefined,
+    };
+  }
+
+  /**
+   * Check if error is retryable
+   *
+   * @param error - Error to check
+   * @returns True if error is retryable
+   */
+  static isRetryable(error: unknown): boolean {
+    return this.categorizeError(error).retryable;
+  }
+}

package/src/domain/services/ImageProcessingService.ts

@@ -0,0 +1,89 @@
+/**
+ * Domain Service: Image Processing
+ * Pure business logic for image data URI manipulation
+ * No infrastructure dependencies
+ */
+
+/**
+ * Domain service for image data processing
+ * Single responsibility: manipulate and validate image data URIs
+ */
+export class ImageProcessingService {
+  /**
+   * Format image as data URI if not already formatted
+   *
+   * @param base64 - Base64 string (with or without data URI prefix)
+   * @returns Data URI formatted string
+   */
+  static formatImageDataUri(base64: string): string {
+    if (base64.startsWith("data:")) {
+      return base64;
+    }
+    return `data:image/jpeg;base64,${base64}`;
+  }
+
+  /**
+   * Extract base64 from data URI
+   * Uses indexOf instead of split to handle edge cases where comma might appear in base64
+   *
+   * @param dataUri - Data URI string
+   * @returns Base64 content
+   * @throws Error if data URI format is invalid
+   */
+  static extractBase64(dataUri: string): string {
+    if (!dataUri.startsWith("data:")) {
+      return dataUri;
+    }
+
+    // Find the first comma which separates header from data
+    const commaIndex = dataUri.indexOf(",");
+    if (commaIndex === -1) {
+      throw new Error(
+        `Invalid data URI format (no comma separator): ${dataUri.substring(0, 50)}...`
+      );
+    }
+
+    // Extract everything after the first comma
+    const base64Part = dataUri.substring(commaIndex + 1);
+
+    if (!base64Part || base64Part.length === 0) {
+      throw new Error(
+        `Empty base64 data in URI: ${dataUri.substring(0, 50)}...`
+      );
+    }
+
+    return base64Part;
+  }
+
+  /**
+   * Get file extension from data URI
+   *
+   * @param dataUri - Data URI string
+   * @returns File extension (e.g., "png", "jpeg") or null
+   */
+  static getDataUriExtension(dataUri: string): string | null {
+    const match = dataUri.match(/^data:image\/(\w+);base64/);
+    return match ? match[1] : null;
+  }
+
+  /**
+   * Extract MIME type from data URI
+   *
+   * @param dataUri - Data URI string
+   * @returns MIME type (e.g., "image/png") or null
+   */
+  static extractMimeType(dataUri: string): string | null {
+    const match = dataUri.match(/^data:([^;,]+)/);
+    return match ? match[1] : null;
+  }
+
+  /**
+   * Check if data URI is base64-encoded
+   *
+   * @param dataUri - Data URI string
+   * @returns True if base64-encoded
+   */
+  static isBase64DataUri(dataUri: string): boolean {
+    return dataUri.startsWith("data:") && dataUri.includes("base64,");
+  }
+}

package/src/domain/services/PricingService.ts

@@ -0,0 +1,101 @@
+/**
+ * Domain Service: Pricing
+ * Pure business logic for credit calculations
+ * No infrastructure dependencies
+ */
+
+import type { VideoModelConfig } from "@umituz/react-native-ai-generation-content";
+
+/**
+ * Pricing constants
+ * FAL AI pricing with markup and credit conversion
+ */
+const COSTS = {
+  VIDEO_480P_PER_SECOND: 0.05,
+  VIDEO_720P_PER_SECOND: 0.07,
+  IMAGE_INPUT: 0.002,
+  IMAGE: 0.03,
+} as const;
+
+const MARKUP = 3.5;
+const CREDIT_PRICE = 0.1;
+
+export type GenerationResolution = "480p" | "720p";
+
+/**
+ * Domain service for pricing calculations
+ * Single responsibility: calculate credit costs for generations
+ */
+export class PricingService {
+  /**
+   * Calculate credits for video generation
+   *
+   * @param duration - Video duration in seconds
+   * @param resolution - Video resolution (480p or 720p)
+   * @param hasImageInput - Whether an image input is provided
+   * @returns Number of credits required
+   */
+  static calculateVideoCredits(
+    duration: number,
+    resolution: GenerationResolution,
+    hasImageInput: boolean = false
+  ): number {
+    const costPerSec =
+      resolution === "480p"
+        ? COSTS.VIDEO_480P_PER_SECOND
+        : COSTS.VIDEO_720P_PER_SECOND;
+    let cost = costPerSec * duration;
+    if (hasImageInput) cost += COSTS.IMAGE_INPUT;
+    return Math.max(1, Math.ceil((cost * MARKUP) / CREDIT_PRICE));
+  }
+
+  /**
+   * Calculate credits for image generation
+   *
+   * @returns Number of credits required
+   */
+  static calculateImageCredits(): number {
+    return Math.max(1, Math.ceil((COSTS.IMAGE * MARKUP) / CREDIT_PRICE));
+  }
+
+  /**
+   * Calculate credits from video model config
+   *
+   * @param config - Video model configuration with pricing info
+   * @param duration - Video duration in seconds
+   * @param resolution - Video resolution string
+   * @returns Number of credits required
+   * @throws Error if config structure is invalid
+   */
+  static calculateCreditsFromConfig(
+    config: VideoModelConfig,
+    duration: number,
+    resolution: string
+  ): number {
+    // Validate config structure
+    if (
+      !config ||
+      typeof config !== "object" ||
+      !config.pricing ||
+      typeof config.pricing !== "object" ||
+      !config.pricing.costPerSecond ||
+      typeof config.pricing.costPerSecond !== "object"
+    ) {
+      throw new Error(
+        "Invalid VideoModelConfig: pricing structure is missing or invalid"
+      );
+    }
+
+    const costPerSecondMap = config.pricing.costPerSecond;
+    const costPerSec = costPerSecondMap[resolution] ?? 0;
+
+    if (typeof costPerSec !== "number" || costPerSec < 0) {
+      throw new Error(
+        `Invalid cost per second for resolution "${resolution}": must be a non-negative number`
+      );
+    }
+
+    const cost = costPerSec * duration;
+    return Math.max(1, Math.ceil((cost * MARKUP) / CREDIT_PRICE));
+  }
+}

package/src/domain/services/ValidationService.ts

@@ -0,0 +1,132 @@
+/**
+ * Domain Service: Validation
+ * Pure business logic for input validation
+ * No infrastructure dependencies
+ */
+
+import { IMAGE_URL_FIELDS } from "../../infrastructure/utils/constants/image-fields.constants";
+import {
+  isValidPrompt,
+  isNonEmptyString,
+  isValidAndSafeUrl,
+  isImageDataUri,
+} from "../../shared/validators";
+
+const SUSPICIOUS_PATTERNS = [
+  /<script/i,
+  /javascript:/i,
+  /on\w+\s*=/i,
+  /<iframe/i,
+  /<embed/i,
+  /<object/i,
+  /data:(?!image\/)/i,
+  /vbscript:/i,
+] as const;
+
+function hasSuspiciousContent(value: string): boolean {
+  return SUSPICIOUS_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+export class InputValidationError extends Error {
+  public readonly errors: readonly ValidationError[];
+
+  constructor(errors: ValidationError[]) {
+    const message = errors.map((e) => `${e.field}: ${e.message}`).join("; ");
+    super(`Input validation failed: ${message}`);
+    this.name = "InputValidationError";
+    this.errors = errors;
+  }
+}
+
+/**
+ * Domain service for input validation
+ * Single responsibility: validate all inputs before API calls
+ */
+export class ValidationService {
+  /**
+   * Validate model and input parameters
+   *
+   * @param model - Model ID (unused in validation but kept for API compatibility)
+   * @param input - Input parameters to validate
+   * @throws InputValidationError if validation fails
+   */
+  static validateInput(_model: string, input: Record<string, unknown>): void {
+    const errors: ValidationError[] = [];
+
+    // Validate input is not empty
+    if (!input || typeof input !== "object" || Object.keys(input).length === 0) {
+      errors.push({ field: "input", message: "Input must be a non-empty object" });
+    }
+
+    // BLOCK sync_mode:true
+    if (input.sync_mode === true) {
+      errors.push({
+        field: "sync_mode",
+        message:
+          "sync_mode:true is forbidden. It returns base64 data URIs instead of HTTPS CDN URLs.",
+      });
+    }
+
+    // Validate prompt
+    if (input.prompt !== undefined) {
+      if (!isValidPrompt(input.prompt)) {
+        errors.push({
+          field: "prompt",
+          message: "Prompt must be a non-empty string (max 5000 characters)",
+        });
+      } else if (typeof input.prompt === "string" && hasSuspiciousContent(input.prompt)) {
+        errors.push({
+          field: "prompt",
+          message: "Prompt contains potentially unsafe content",
+        });
+      }
+    }
+
+    // Validate negative_prompt
+    if (input.negative_prompt !== undefined) {
+      if (!isValidPrompt(input.negative_prompt)) {
+        errors.push({
+          field: "negative_prompt",
+          message: "Negative prompt must be a non-empty string (max 5000 characters)",
+        });
+      } else if (typeof input.negative_prompt === "string" && hasSuspiciousContent(input.negative_prompt)) {
+        errors.push({
+          field: "negative_prompt",
+          message: "Negative prompt contains potentially unsafe content",
+        });
+      }
+    }
+
+    // Validate all image_url fields
+    for (const field of IMAGE_URL_FIELDS) {
+      const value = input[field];
+      if (value !== undefined) {
+        if (typeof value !== "string") {
+          errors.push({
+            field,
+            message: `${field} must be a string`,
+          });
+        } else if (!isNonEmptyString(value)) {
+          errors.push({
+            field,
+            message: `${field} cannot be empty`,
+          });
+        } else if (!isValidAndSafeUrl(value)) {
+          errors.push({
+            field,
+            message: `${field} must be a valid URL or image data URI`,
+          });
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new InputValidationError(errors);
+    }
+  }
+}

package/src/domain/services/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Domain Services - Public API
+ * Pure business logic services with no infrastructure dependencies
+ */
+
+export { ValidationService, InputValidationError } from "./ValidationService";
+export type { ValidationError } from "./ValidationService";
+
+export { PricingService } from "./PricingService";
+
+export { ImageProcessingService } from "./ImageProcessingService";
+
+export { ErrorClassificationService } from "./ErrorClassificationService";

package/src/index.ts

@@ -43,11 +43,19 @@ export type {
 } from "./domain/entities/error.types";
 
 // ─── Utilities (public API) ────────────────────────────────────────────────────
+// Shared utilities (consolidated)
 export {
   getErrorMessage,
   getErrorMessageOr,
   formatErrorMessage,
-} from "./infrastructure/utils/helpers/error-helpers.util";
+  buildErrorMessage,
+  isDefined,
+  removeNullish,
+  generateUniqueId,
+  sleep,
+  getElapsedTime,
+  getActualSizeKB,
+} from "./shared/helpers";
 
 export {
   IMAGE_URL_FIELDS,
@@ -56,29 +64,31 @@ export {
 export type { ImageUrlField } from "./infrastructure/utils/constants/image-fields.constants";
 
 export {
+  isEmptyString,
+  isNonEmptyString,
+  isString,
   isDataUri,
+  isImageDataUri,
   isBase64DataUri,
   extractMimeType,
   extractBase64Content,
-} from "./infrastructure/utils/validators/data-uri-validator.util";
-
-export {
-  isEmptyString,
-  isNonEmptyString,
-  isString,
-} from "./infrastructure/utils/validators/string-validator.util";
-
-export {
-  isFalModelType,
-  isModelType,
-  isFalErrorType,
   isValidBase64Image,
   isValidApiKey,
   isValidModelId,
   isValidPrompt,
   isValidTimeout,
   isValidRetryCount,
-} from "./infrastructure/utils/type-guards";
+  isValidAndSafeUrl,
+} from "./shared/validators";
+
+export {
+  isFalModelType,
+  isModelType,
+  isFalErrorType,
+  isRetryableError,
+  isLocalFileUri,
+  isHttpUrl,
+} from "./shared/type-guards";
 
 export {
   formatImageDataUri,
@@ -91,14 +101,6 @@ export {
   uploadMultipleToFalStorage,
 } from "./infrastructure/utils/fal-storage.util";
 
-export {
-  buildErrorMessage,
-  isDefined,
-  removeNullish,
-  generateUniqueId,
-  sleep,
-} from "./infrastructure/utils/helpers";
-
 export { preprocessInput } from "./infrastructure/utils/input-preprocessor.util";
 
 export {