@umituz/react-native-ai-fal-provider 2.0.28 → 2.0.30

package/src/infrastructure/utils/fal-error-handler.util.ts

@@ -0,0 +1,153 @@
+/**
+ * FAL Error Handler
+ * Unified error handling for FAL AI operations
+ */
+
+import type { FalErrorInfo, FalErrorCategory, FalErrorType } from "../../domain/entities/error.types";
+import { FalErrorType as ErrorTypeEnum } from "../../domain/entities/error.types";
+import { safeJsonParseOrNull } from "./data-parsers.util";
+
+const STATUS_CODES = ["400", "401", "402", "403", "404", "422", "429", "500", "502", "503", "504"];
+
+interface FalApiErrorDetail {
+  msg?: string;
+  type?: string;
+  loc?: string[];
+}
+
+interface FalApiError {
+  body?: { detail?: FalApiErrorDetail[] } | string;
+  message?: string;
+}
+
+const ERROR_PATTERNS: Record<FalErrorType, string[]> = {
+  [ErrorTypeEnum.NETWORK]: ["network", "fetch", "connection", "econnrefused", "enotfound", "etimedout"],
+  [ErrorTypeEnum.TIMEOUT]: ["timeout", "timed out"],
+  [ErrorTypeEnum.IMAGE_TOO_SMALL]: ["image_too_small", "image dimensions are too small", "minimum dimensions"],
+  [ErrorTypeEnum.VALIDATION]: ["validation", "invalid", "unprocessable", "422", "bad request", "400"],
+  [ErrorTypeEnum.CONTENT_POLICY]: ["content_policy", "content policy", "policy violation", "nsfw", "inappropriate"],
+  [ErrorTypeEnum.RATE_LIMIT]: ["rate limit", "too many requests", "429"],
+  [ErrorTypeEnum.AUTHENTICATION]: ["unauthorized", "401", "forbidden", "403", "api key", "authentication"],
+  [ErrorTypeEnum.QUOTA_EXCEEDED]: ["quota exceeded", "insufficient credits", "billing", "payment required", "402"],
+  [ErrorTypeEnum.MODEL_NOT_FOUND]: ["model not found", "endpoint not found", "404", "not found"],
+  [ErrorTypeEnum.API_ERROR]: ["api error", "502", "503", "504", "500", "internal server error"],
+  [ErrorTypeEnum.UNKNOWN]: [],
+};
+
+const RETRYABLE_TYPES = new Set([
+  ErrorTypeEnum.NETWORK,
+  ErrorTypeEnum.TIMEOUT,
+  ErrorTypeEnum.RATE_LIMIT,
+]);
+
+/**
+ * Extract HTTP status code from error message
+ */
+function extractStatusCode(errorString: string): number | undefined {
+  const code = STATUS_CODES.find((c) => errorString.includes(c));
+  return code ? parseInt(code, 10) : undefined;
+}
+
+/**
+ * Parse FAL API error and extract user-friendly message
+ */
+function parseFalApiError(error: unknown): string {
+  const fallback = error instanceof Error ? error.message : String(error);
+
+  const falError = error as FalApiError;
+  if (!falError?.body) return fallback;
+
+  const body = typeof falError.body === "string"
+    ? safeJsonParseOrNull<{ detail?: FalApiErrorDetail[] }>(falError.body)
+    : falError.body;
+
+  const detail = body?.detail?.[0];
+  return detail?.msg ?? falError.message ?? fallback;
+}
+
+/**
+ * Check if error string matches any of the provided patterns
+ */
+function matchesPatterns(errorString: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => errorString.includes(pattern));
+}
+
+/**
+ * Categorize FAL error based on error message patterns
+ */
+function categorizeError(error: unknown): FalErrorCategory {
+  const message = error instanceof Error ? error.message : String(error);
+  const errorString = message.toLowerCase();
+
+  for (const [type, patterns] of Object.entries(ERROR_PATTERNS)) {
+    if (patterns.length > 0 && matchesPatterns(errorString, patterns)) {
+      const errorType = type as FalErrorType;
+      return {
+        type: errorType,
+        messageKey: errorType,
+        retryable: RETRYABLE_TYPES.has(errorType),
+      };
+    }
+  }
+
+  return { type: ErrorTypeEnum.UNKNOWN, messageKey: "unknown", retryable: false };
+}
+
+/**
+ * Map error to FalErrorInfo with full error details
+ */
+export function mapFalError(error: unknown): FalErrorInfo {
+  const category = categorizeError(error);
+
+  if (error instanceof Error) {
+    return {
+      type: category.type,
+      messageKey: `fal.errors.${category.messageKey}`,
+      retryable: category.retryable,
+      originalError: error.message,
+      originalErrorName: error.name,
+      stack: error.stack,
+      statusCode: extractStatusCode(error.message),
+    };
+  }
+
+  const errorString = String(error);
+
+  return {
+    type: category.type,
+    messageKey: `fal.errors.${category.messageKey}`,
+    retryable: category.retryable,
+    originalError: errorString,
+    statusCode: extractStatusCode(errorString),
+  };
+}
+
+/**
+ * Parse FAL error and return user-friendly message
+ */
+export function parseFalError(error: unknown): string {
+  const userMessage = parseFalApiError(error);
+  if (!userMessage || userMessage.trim().length === 0) {
+    return "An unknown error occurred. Please try again.";
+  }
+  return userMessage;
+}
+
+/**
+ * Categorize FAL error
+ */
+export function categorizeFalError(error: unknown): FalErrorCategory {
+  return categorizeError(error);
+}
+
+/**
+ * Check if FAL error is retryable
+ */
+export function isFalErrorRetryable(error: unknown): boolean {
+  return categorizeFalError(error).retryable;
+}
+
+/**
+ * Extract status code from error
+ */
+export { extractStatusCode };

package/src/infrastructure/utils/fal-generation-state-manager.util.ts

@@ -0,0 +1,93 @@
+/**
+ * FAL Generation State Manager
+ * Manages state and refs for FAL generation operations
+ */
+
+import type { FalJobInput, FalLogEntry, FalQueueStatus } from "../../domain/entities/fal.types";
+
+export interface GenerationState<T> {
+  data: T | null;
+  error: Error | null;
+  isLoading: boolean;
+  isCancelling: boolean;
+  requestId: string | null;
+  lastRequest: { endpoint: string; input: FalJobInput } | null;
+}
+
+export interface GenerationStateOptions<T> {
+  onQueueUpdate?: (status: FalQueueStatus) => void;
+  onProgress?: (status: FalQueueStatus) => void;
+  onError?: (error: Error) => void;
+  onResult?: (result: T) => void;
+}
+
+export class FalGenerationStateManager<T> {
+  private isMounted = true;
+  private currentRequestId: string | null = null;
+  private lastRequest: { endpoint: string; input: FalJobInput } | null = null;
+
+  constructor(
+    private options?: GenerationStateOptions<T>
+  ) {}
+
+  setIsMounted(mounted: boolean): void {
+    this.isMounted = mounted;
+  }
+
+  checkMounted(): boolean {
+    return this.isMounted;
+  }
+
+  setCurrentRequestId(requestId: string | null): void {
+    this.currentRequestId = requestId;
+  }
+
+  getCurrentRequestId(): string | null {
+    return this.currentRequestId;
+  }
+
+  setLastRequest(endpoint: string, input: FalJobInput): void {
+    this.lastRequest = { endpoint, input };
+  }
+
+  getLastRequest(): { endpoint: string; input: FalJobInput } | null {
+    return this.lastRequest;
+  }
+
+  clearLastRequest(): void {
+    this.lastRequest = null;
+    this.currentRequestId = null;
+  }
+
+  handleQueueUpdate(status: FalQueueStatus): void {
+    if (!this.isMounted) return;
+
+    if (status.requestId) {
+      this.currentRequestId = status.requestId;
+    }
+
+    const normalizedStatus: FalQueueStatus = {
+      status: status.status,
+      requestId: status.requestId ?? this.currentRequestId ?? "",
+      logs: status.logs?.map((log: FalLogEntry) => ({
+        message: log.message,
+        level: log.level,
+        timestamp: log.timestamp,
+      })),
+      queuePosition: status.queuePosition,
+    };
+
+    this.options?.onQueueUpdate?.(normalizedStatus);
+    this.options?.onProgress?.(normalizedStatus);
+  }
+
+  handleResult(result: T): void {
+    if (!this.isMounted) return;
+    this.options?.onResult?.(result);
+  }
+
+  handleError(error: Error): void {
+    if (!this.isMounted) return;
+    this.options?.onError?.(error);
+  }
+}

package/src/infrastructure/utils/fal-storage.util.ts

@@ -17,21 +17,21 @@ export async function uploadToFalStorage(base64: string): Promise<string> {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment
   const tempUri = (await base64ToTempFile(base64));
 
+  if (!tempUri) {
+    throw new Error("Failed to create temporary file from base64 data");
+  }
+
   try {
     const response = await fetch(tempUri);
     const blob = await response.blob();
     const url = await fal.storage.upload(blob);
     return url;
   } finally {
-    if (tempUri) {
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-        await deleteTempFile(tempUri);
-      } catch (cleanupError) {
-        // Log cleanup failure but don't throw
-        // eslint-disable-next-line no-console
-        console.warn(`Failed to cleanup temp file ${tempUri}:`, cleanupError);
-      }
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      await deleteTempFile(tempUri);
+    } catch {
+      // Silently ignore cleanup errors
     }
   }
 }

package/src/infrastructure/utils/formatting.util.ts

@@ -1,208 +1,31 @@
 /**
  * Formatting Utilities
  * Common formatting functions for display and data presentation
- */
-
-/**
- * Format number with decimal places
- */
-export function formatNumber(value: number, decimals: number = 2): string {
-  if (Number.isNaN(value) || !Number.isFinite(value)) {
-    return "0";
-  }
-
-  // Return integer if no decimal part
-  if (value % 1 === 0) {
-    return value.toString();
-  }
-
-  return value.toFixed(decimals);
-}
-
-/**
- * Format currency amount
- */
-export function formatCurrency(amount: number, currency: string = "USD"): string {
-  const formatted = formatNumber(amount, 2);
-  return `${currency} ${formatted}`;
-}
-
-/**
- * Format bytes to human-readable size
- */
-export function formatBytes(bytes: number, decimals: number = 2): string {
-  if (bytes === 0) return "0 Bytes";
-
-  const k = 1024;
-  const dm = decimals < 0 ? 0 : decimals;
-  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-
-  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
-}
-
-/**
- * Format duration in milliseconds to human-readable string
- */
-export function formatDuration(milliseconds: number): string {
-  if (milliseconds < 1000) {
-    return `${milliseconds}ms`;
-  }
-
-  const seconds = Math.floor(milliseconds / 1000);
-  if (seconds < 60) {
-    return `${seconds}s`;
-  }
-
-  const minutes = Math.floor(seconds / 60);
-  const remainingSeconds = seconds % 60;
-  if (minutes < 60) {
-    return remainingSeconds > 0
-      ? `${minutes}m ${remainingSeconds}s`
-      : `${minutes}m`;
-  }
-
-  const hours = Math.floor(minutes / 60);
-  const remainingMinutes = minutes % 60;
-  return remainingMinutes > 0
-    ? `${hours}h ${remainingMinutes}m`
-    : `${hours}h`;
-}
-
-/**
- * Format percentage
- */
-export function formatPercentage(value: number, decimals: number = 1): string {
-  if (value < 0) return "0%";
-  if (value > 100) return "100%";
-  return `${formatNumber(value, decimals)}%`;
-}
-
-/**
- * Format date to locale string
- */
-export function formatDate(date: Date | string, locale: string = "en-US"): string {
-  const dateObj = typeof date === "string" ? new Date(date) : date;
-  return dateObj.toLocaleDateString(locale, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  });
-}
-
-/**
- * Format date and time to locale string
- */
-export function formatDateTime(date: Date | string, locale: string = "en-US"): string {
-  const dateObj = typeof date === "string" ? new Date(date) : date;
-  return dateObj.toLocaleString(locale, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-    hour: "2-digit",
-    minute: "2-digit",
-  });
-}
-
-/**
- * Format relative time (e.g., "2 hours ago")
- */
-export function formatRelativeTime(date: Date | string, locale: string = "en-US"): string {
-  const dateObj = typeof date === "string" ? new Date(date) : date;
-  const now = new Date();
-  const diffMs = now.getTime() - dateObj.getTime();
-  const diffSec = Math.floor(diffMs / 1000);
-  const diffMin = Math.floor(diffSec / 60);
-  const diffHour = Math.floor(diffMin / 60);
-  const diffDay = Math.floor(diffHour / 24);
-
-  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
-
-  if (diffSec < 60) {
-    return rtf.format(-diffSec, "second");
-  }
-  if (diffMin < 60) {
-    return rtf.format(-diffMin, "minute");
-  }
-  if (diffHour < 24) {
-    return rtf.format(-diffHour, "hour");
-  }
-  if (diffDay < 30) {
-    return rtf.format(-diffDay, "day");
-  }
-  if (diffDay < 365) {
-    const months = Math.floor(diffDay / 30);
-    return rtf.format(-months, "month");
-  }
-  const years = Math.floor(diffDay / 365);
-  return rtf.format(-years, "year");
-}
-
-/**
- * Truncate text with ellipsis
- */
-export function truncateText(text: string, maxLength: number): string {
-  if (text.length <= maxLength) {
-    return text;
-  }
-  return text.slice(0, maxLength - 3) + "...";
-}
-
-/**
- * Capitalize first letter of string
- */
-export function capitalize(text: string): string {
-  if (!text) return text;
-  return text.charAt(0).toUpperCase() + text.slice(1);
-}
-
-/**
- * Convert string to title case
- */
-export function toTitleCase(text: string): string {
-  return text
-    .toLowerCase()
-    .split(" ")
-    .map((word) => capitalize(word))
-    .join(" ");
-}
-
-/**
- * Convert string to slug
- */
-export function toSlug(text: string): string {
-  return text
-    .toLowerCase()
-    .trim()
-    .replace(/[^\w\s-]/g, "")
-    .replace(/[\s_-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-/**
- * Format list of items with conjunction
- */
-export function formatList(items: readonly string[], conjunction: string = "and"): string {
-  if (items.length === 0) return "";
-  if (items.length === 1) return items[0] ?? "";
-  if (items.length === 2) return items.join(` ${conjunction} `);
-
-  const allButLast = items.slice(0, -1);
-  const last = items[items.length - 1];
-  return `${allButLast.join(", ")}, ${conjunction} ${last}`;
-}
-
-/**
- * Pluralize word based on count
- */
-export function pluralize(word: string, count: number): string {
-  if (count === 1) return word;
-  return `${word}s`;
-}
-
-/**
- * Format count with plural word
- */
-export function formatCount(word: string, count: number): string {
-  return `${count} ${pluralize(word, count)}`;
-}
+ *
+ * This module re-exports formatting utilities from specialized modules
+ * for better organization and maintainability.
+ */
+
+export {
+  formatDate,
+  formatDateTime,
+  formatRelativeTime,
+} from "./date-format.util";
+
+export {
+  formatNumber,
+  formatCurrency,
+  formatBytes,
+  formatDuration,
+  formatPercentage,
+} from "./number-format.util";
+
+export {
+  truncateText,
+  capitalize,
+  toTitleCase,
+  toSlug,
+  formatList,
+  pluralize,
+  formatCount,
+} from "./string-format.util";

package/src/infrastructure/utils/index.ts

@@ -39,6 +39,7 @@ export {
   mapFalError,
   parseFalError,
   isFalErrorRetryable,
+  extractStatusCode,
 } from "./error-mapper";
 
 export {
@@ -151,3 +152,9 @@ export {
   type ValidationError,
 } from "./input-validator.util";
 
+// FAL generation state manager
+export {
+  FalGenerationStateManager,
+  type GenerationState,
+  type GenerationStateOptions,
+} from "./fal-generation-state-manager.util";

package/src/infrastructure/utils/input-preprocessor.util.ts

@@ -29,7 +29,7 @@ export async function preprocessInput(
   input: Record<string, unknown>,
 ): Promise<Record<string, unknown>> {
   const result = { ...input };
-  const uploadPromises: Promise<void>[] = [];
+  const uploadPromises: Promise<unknown>[] = [];
 
   // Handle individual image URL keys
   for (const key of IMAGE_URL_KEYS) {
@@ -50,7 +50,7 @@ export async function preprocessInput(
   // Handle image_urls array (for multi-person generation)
   if (Array.isArray(result.image_urls) && result.image_urls.length > 0) {
     const imageUrls = result.image_urls as unknown[];
-    const processedUrls: string[] = [];
+    const uploadTasks: Array<{ index: number; url: string | Promise<string> }> = [];
     const errors: string[] = [];
 
     for (let i = 0; i < imageUrls.length; i++) {
@@ -62,19 +62,14 @@ export async function preprocessInput(
       }
 
       if (isBase64DataUri(imageUrl)) {
-        const index = i;
-        const uploadPromise = uploadToFalStorage(imageUrl)
-          .then((url) => {
-            processedUrls[index] = url;
-          })
-          .catch((error) => {
-            errors.push(`Failed to upload image_urls[${index}]: ${error instanceof Error ? error.message : "Unknown error"}`);
-            throw new Error(`Failed to upload image_urls[${index}]: ${error instanceof Error ? error.message : "Unknown error"}`);
-          });
-
-        uploadPromises.push(uploadPromise);
+        const uploadPromise = uploadToFalStorage(imageUrl).catch((error) => {
+          const errorMessage = `Failed to upload image_urls[${i}]: ${error instanceof Error ? error.message : "Unknown error"}`;
+          errors.push(errorMessage);
+          throw new Error(errorMessage);
+        });
+        uploadTasks.push({ index: i, url: uploadPromise });
       } else if (typeof imageUrl === "string") {
-        processedUrls[i] = imageUrl;
+        uploadTasks.push({ index: i, url: imageUrl });
       } else {
         errors.push(`image_urls[${i}] has invalid type: ${typeof imageUrl}`);
       }
@@ -84,6 +79,13 @@ export async function preprocessInput(
       throw new Error(`Image URL validation failed:\n${errors.join('\n')}`);
     }
 
+    // Wait for all uploads and build the final array without sparse elements
+    const processedUrls = await Promise.all(
+      uploadTasks
+        .sort((a, b) => a.index - b.index)
+        .map((task) => Promise.resolve(task.url))
+    );
+
     result.image_urls = processedUrls;
   }
 

package/src/infrastructure/utils/number-format.util.ts

@@ -0,0 +1,79 @@
+/**
+ * Number Formatting Utilities
+ * Functions for formatting numbers and quantities
+ */
+
+/**
+ * Format number with decimal places
+ */
+export function formatNumber(value: number, decimals: number = 2): string {
+  if (Number.isNaN(value) || !Number.isFinite(value)) {
+    return "0";
+  }
+
+  // Return integer if no decimal part
+  if (value % 1 === 0) {
+    return value.toString();
+  }
+
+  return value.toFixed(decimals);
+}
+
+/**
+ * Format currency amount
+ */
+export function formatCurrency(amount: number, currency: string = "USD"): string {
+  const formatted = formatNumber(amount, 2);
+  return `${currency} ${formatted}`;
+}
+
+/**
+ * Format bytes to human-readable size
+ */
+export function formatBytes(bytes: number, decimals: number = 2): string {
+  if (bytes === 0) return "0 Bytes";
+
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string
+ */
+export function formatDuration(milliseconds: number): string {
+  if (milliseconds < 1000) {
+    return `${milliseconds}ms`;
+  }
+
+  const seconds = Math.floor(milliseconds / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return remainingSeconds > 0
+      ? `${minutes}m ${remainingSeconds}s`
+      : `${minutes}m`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes > 0
+    ? `${hours}h ${remainingMinutes}m`
+    : `${hours}h`;
+}
+
+/**
+ * Format percentage
+ */
+export function formatPercentage(value: number, decimals: number = 1): string {
+  if (value < 0) return "0%";
+  if (value > 100) return "100%";
+  return `${formatNumber(value, decimals)}%`;
+}