@umituz/react-native-ai-fal-provider 3.1.5 → 3.1.7

package/package.json

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

package/src/infrastructure/services/fal-provider-subscription.ts

@@ -3,14 +3,74 @@
  * Handles subscribe, run methods and cancellation logic
  */
 
-import { fal } from "@fal-ai/client";
+import { fal, ApiError, ValidationError } from "@fal-ai/client";
 import type { SubscribeOptions, RunOptions } from "../../domain/types";
-import type { FalQueueStatus } from "../../domain/entities/fal.types";
 import { DEFAULT_FAL_CONFIG } from "./fal-provider.constants";
 import { mapFalStatusToJobStatus } from "./fal-status-mapper";
 import { validateNSFWContent } from "../validators/nsfw-validator";
 import { NSFWContentError } from "./nsfw-content-error";
-import { parseFalError } from "../utils/fal-error-handler.util";
+
+/**
+ * Unwrap fal.subscribe / fal.run Result<T> = { data: T, requestId: string }
+ * Throws if response format is unexpected - no silent fallbacks
+ */
+function unwrapFalResult<T>(rawResult: unknown): { data: T; requestId: string } {
+  if (!rawResult || typeof rawResult !== "object") {
+    throw new Error(
+      `Unexpected fal response: expected object, got ${typeof rawResult}`
+    );
+  }
+
+  const result = rawResult as Record<string, unknown>;
+
+  if (!("data" in result)) {
+    throw new Error(
+      `Unexpected fal response format: missing 'data' property. Keys: ${Object.keys(result).join(", ")}`
+    );
+  }
+
+  if (!("requestId" in result) || typeof result.requestId !== "string") {
+    throw new Error(
+      `Unexpected fal response format: missing or invalid 'requestId'. Keys: ${Object.keys(result).join(", ")}`
+    );
+  }
+
+  return { data: result.data as T, requestId: result.requestId };
+}
+
+/**
+ * Format fal-ai SDK errors into user-readable messages
+ * Uses proper @fal-ai/client error types (ApiError, ValidationError)
+ */
+function formatFalError(error: unknown): string {
+  if (error instanceof ValidationError) {
+    const details = error.fieldErrors;
+    if (details.length > 0) {
+      return details.map((d) => d.msg).filter(Boolean).join("; ") || error.message;
+    }
+    return error.message;
+  }
+
+  if (error instanceof ApiError) {
+    // ApiError has .status, .body, .message
+    if (error.status === 401 || error.status === 403) {
+      return "Authentication failed. Please check your API key.";
+    }
+    if (error.status === 429) {
+      return "Rate limit exceeded. Please wait and try again.";
+    }
+    if (error.status === 402) {
+      return "Insufficient credits. Please check your billing.";
+    }
+    return error.message || `API error (${error.status})`;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
 
 /**
  * Handle FAL subscription with timeout and cancellation
@@ -20,10 +80,9 @@ export async function handleFalSubscription<T = unknown>(
   input: Record<string, unknown>,
   options?: SubscribeOptions<T>,
   signal?: AbortSignal
-): Promise<{ result: T; requestId: string | null }> {
+): Promise<{ result: T; requestId: string }> {
   const timeoutMs = options?.timeoutMs ?? DEFAULT_FAL_CONFIG.defaultTimeoutMs;
 
-  // Validate timeout is a positive integer within reasonable bounds
   if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 3600000) {
     throw new Error(
       `Invalid timeout: ${timeoutMs}ms. Must be a positive integer between 1 and 3600000ms (1 hour)`
@@ -31,14 +90,11 @@ export async function handleFalSubscription<T = unknown>(
   }
 
   let timeoutId: ReturnType<typeof setTimeout> | null = null;
-  let currentRequestId: string | null = null;
   let abortHandler: (() => void) | null = null;
   let listenerAdded = false;
-
   let lastStatus = "";
 
   try {
-    // Check if signal is already aborted BEFORE starting any async work
     if (signal?.aborted) {
       throw new Error("Request cancelled by user");
     }
@@ -49,20 +105,17 @@ export async function handleFalSubscription<T = unknown>(
         logs: false,
         pollInterval: DEFAULT_FAL_CONFIG.pollInterval,
         onQueueUpdate: (update: { status: string; logs?: unknown[]; request_id?: string; queue_position?: number }) => {
-          currentRequestId = update.request_id ?? currentRequestId;
-          const jobStatus = mapFalStatusToJobStatus({
-            status: update.status as FalQueueStatus["status"],
-            requestId: currentRequestId ?? "",
-            logs: update.logs as FalQueueStatus["logs"],
-            queuePosition: update.queue_position,
-          });
+          const jobStatus = mapFalStatusToJobStatus(
+            update.status,
+            update.request_id,
+            update.queue_position,
+            Array.isArray(update.logs) ? update.logs : undefined,
+          );
+
           if (jobStatus.status !== lastStatus) {
             lastStatus = jobStatus.status;
-
-            // Emit status changes without fake progress percentages
             if (options?.onProgress) {
               if (jobStatus.status === "IN_QUEUE" || jobStatus.status === "IN_PROGRESS") {
-                // Indeterminate progress - let UI show spinner/loading
                 options.onProgress({ progress: -1, status: jobStatus.status });
               } else if (jobStatus.status === "COMPLETED") {
                 options.onProgress({ progress: 100, status: "COMPLETED" });
@@ -76,21 +129,17 @@ export async function handleFalSubscription<T = unknown>(
       }),
       new Promise<never>((_, reject) => {
         timeoutId = setTimeout(() => {
-          reject(new Error("FAL subscription timeout"));
+          reject(new Error(`FAL subscription timeout after ${timeoutMs}ms for model ${model}`));
         }, timeoutMs);
       }),
     ];
 
-    // Set up abort listener BEFORE checking aborted state again to avoid race
     if (signal) {
       const abortPromise = new Promise<never>((_, reject) => {
-        abortHandler = () => {
-          reject(new Error("Request cancelled by user"));
-        };
+        abortHandler = () => reject(new Error("Request cancelled by user"));
         signal.addEventListener("abort", abortHandler);
         listenerAdded = true;
-
-        // Check again after adding listener to catch signals that arrived during setup
+        // Re-check after listener to handle race
         if (signal.aborted) {
           abortHandler();
         }
@@ -99,26 +148,19 @@ export async function handleFalSubscription<T = unknown>(
     }
 
     const rawResult = await Promise.race(promises);
+    const { data, requestId } = unwrapFalResult<T>(rawResult);
 
-    // fal.subscribe returns { data: T, requestId: string } - unwrap the data
-    const falResult = rawResult as { data?: unknown; requestId?: string };
-    const actualData = (falResult?.data ?? rawResult) as T;
-    const falRequestId = falResult?.requestId ?? currentRequestId;
-
-    validateNSFWContent(actualData as Record<string, unknown>);
+    validateNSFWContent(data as Record<string, unknown>);
 
-    options?.onResult?.(actualData);
-    return { result: actualData, requestId: falRequestId };
+    options?.onResult?.(data);
+    return { result: data, requestId };
   } catch (error) {
     if (error instanceof NSFWContentError) {
       throw error;
     }
 
-    const userMessage = parseFalError(error);
-    if (!userMessage || userMessage.trim().length === 0) {
-      throw new Error("An unknown error occurred. Please try again.");
-    }
-    throw new Error(userMessage);
+    const message = formatFalError(error);
+    throw new Error(message);
   } finally {
     if (timeoutId) {
       clearTimeout(timeoutId);
@@ -137,26 +179,22 @@ export async function handleFalRun<T = unknown>(
   input: Record<string, unknown>,
   options?: RunOptions
 ): Promise<T> {
-  // Indeterminate progress - no fake percentages
   options?.onProgress?.({ progress: -1, status: "IN_PROGRESS" as const });
 
   try {
     const rawResult = await fal.run(model, { input });
+    const { data } = unwrapFalResult<T>(rawResult);
 
-    // fal.run returns { data: T, requestId: string } - unwrap the data
-    const falResult = rawResult as { data?: unknown; requestId?: string };
-    const actualData = (falResult?.data ?? rawResult) as T;
-
-    validateNSFWContent(actualData as Record<string, unknown>);
+    validateNSFWContent(data as Record<string, unknown>);
 
     options?.onProgress?.({ progress: 100, status: "COMPLETED" as const });
-    return actualData;
+    return data;
   } catch (error) {
     if (error instanceof NSFWContentError) {
       throw error;
     }
 
-    const userMessage = parseFalError(error);
-    throw new Error(userMessage);
+    const message = formatFalError(error);
+    throw new Error(message);
   }
 }

package/src/infrastructure/services/fal-queue-operations.ts

@@ -1,51 +1,29 @@
 /**
  * FAL Queue Operations - Direct FAL API queue interactions
+ * No silent fallbacks - throws descriptive errors on unexpected responses
  */
 
 import { fal } from "@fal-ai/client";
 import type { JobSubmission, JobStatus } from "../../domain/types";
-import type { FalQueueStatus } from "../../domain/entities/fal.types";
-import { mapFalStatusToJobStatus, FAL_QUEUE_STATUSES } from "./fal-status-mapper";
-
-const VALID_STATUSES = Object.values(FAL_QUEUE_STATUSES) as string[];
+import { mapFalStatusToJobStatus } from "./fal-status-mapper";
 
 /**
- * Normalize FAL queue status response from snake_case (SDK) to camelCase (internal)
+ * Submit job to FAL queue
+ * @throws {Error} if response is missing required fields
  */
-function normalizeFalQueueStatus(value: unknown): FalQueueStatus | null {
-  if (!value || typeof value !== "object") {
-    return null;
-  }
-
-  const raw = value as Record<string, unknown>;
-
-  if (typeof raw.status !== "string" || !VALID_STATUSES.includes(raw.status)) {
-    return null;
-  }
-
-  // FAL SDK returns snake_case (request_id, queue_position)
-  const requestId = (raw.request_id ?? raw.requestId) as string | undefined;
-  if (typeof requestId !== "string") {
-    return null;
-  }
-
-  return {
-    status: raw.status as FalQueueStatus["status"],
-    requestId,
-    queuePosition: (raw.queue_position ?? raw.queuePosition) as number | undefined,
-    logs: Array.isArray(raw.logs) ? raw.logs : undefined,
-  };
-}
-
 export async function submitJob(model: string, input: Record<string, unknown>): Promise<JobSubmission> {
   const result = await fal.queue.submit(model, { input });
 
   if (!result?.request_id) {
-    throw new Error(`FAL API response missing request_id for model ${model}`);
+    throw new Error(
+      `FAL queue.submit response missing request_id for model ${model}. Response keys: ${Object.keys(result ?? {}).join(", ")}`
+    );
   }
 
   if (!result?.status_url) {
-    throw new Error(`FAL API response missing status_url for model ${model}`);
+    throw new Error(
+      `FAL queue.submit response missing status_url for model ${model}. Response keys: ${Object.keys(result).join(", ")}`
+    );
   }
 
   return {
@@ -55,31 +33,60 @@ export async function submitJob(model: string, input: Record<string, unknown>):
   };
 }
 
+/**
+ * Get job status from FAL queue
+ * @throws {Error} if response format is invalid or status is unrecognized
+ */
 export async function getJobStatus(model: string, requestId: string): Promise<JobStatus> {
   const raw = await fal.queue.status(model, { requestId, logs: true });
 
-  const status = normalizeFalQueueStatus(raw);
-  if (!status) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error(
+      `FAL queue.status returned non-object for model ${model}, requestId ${requestId}: ${typeof raw}`
+    );
+  }
+
+  const response = raw as Record<string, unknown>;
+
+  if (typeof response.status !== "string") {
     throw new Error(
-      `Invalid FAL queue status response for model ${model}, requestId ${requestId}`
+      `FAL queue.status response missing 'status' field for model ${model}, requestId ${requestId}. Keys: ${Object.keys(response).join(", ")}`
     );
   }
 
-  return mapFalStatusToJobStatus(status);
+  // FAL SDK returns snake_case (request_id, queue_position)
+  const resolvedRequestId = (response.request_id ?? response.requestId) as string | undefined;
+  if (typeof resolvedRequestId !== "string") {
+    throw new Error(
+      `FAL queue.status response missing request_id for model ${model}, requestId ${requestId}. Keys: ${Object.keys(response).join(", ")}`
+    );
+  }
+
+  return mapFalStatusToJobStatus(
+    response.status,
+    resolvedRequestId,
+    (response.queue_position ?? response.queuePosition) as number | undefined,
+    Array.isArray(response.logs) ? response.logs : undefined,
+  );
 }
 
+/**
+ * Get job result from FAL queue
+ * fal.queue.result returns Result<T> = { data: T, requestId: string }
+ * @throws {Error} if response format is unexpected
+ */
 export async function getJobResult<T = unknown>(model: string, requestId: string): Promise<T> {
   const result = await fal.queue.result(model, { requestId });
 
   if (!result || typeof result !== 'object') {
     throw new Error(
-      `Invalid FAL queue result for model ${model}, requestId ${requestId}: Result is not an object`
+      `FAL queue.result returned non-object for model ${model}, requestId ${requestId}: ${typeof result}`
     );
   }
 
   if (!('data' in result)) {
     throw new Error(
-      `Invalid FAL queue result for model ${model}, requestId ${requestId}: Missing 'data' property`
+      `FAL queue.result response missing 'data' property for model ${model}, requestId ${requestId}. Keys: ${Object.keys(result).join(", ")}`
     );
   }
 

package/src/infrastructure/services/fal-status-mapper.ts

@@ -1,41 +1,51 @@
 /**
  * FAL Status Mapper
  * Maps FAL queue status to standardized job status
+ * Validates status values - throws on unknown status instead of silent fallback
  */
 
 import type { JobStatus, AIJobStatusType } from "../../domain/types";
-import type { FalQueueStatus, FalLogEntry } from "../../domain/entities/fal.types";
+import type { FalLogEntry } from "../../domain/entities/fal.types";
 
-export const FAL_QUEUE_STATUSES = {
+const VALID_STATUSES: Record<string, AIJobStatusType> = {
   IN_QUEUE: "IN_QUEUE",
   IN_PROGRESS: "IN_PROGRESS",
   COMPLETED: "COMPLETED",
   FAILED: "FAILED",
-} as const;
-
-export type FalQueueStatusKey = keyof typeof FAL_QUEUE_STATUSES;
-
-const STATUS_MAP = FAL_QUEUE_STATUSES satisfies Record<string, AIJobStatusType>;
-
-const DEFAULT_STATUS: AIJobStatusType = "IN_PROGRESS";
+};
 
 /**
- * Map FAL queue status to standardized job status
- * Provides safe defaults for missing or invalid values
+ * Map raw FAL status values to standardized JobStatus
+ * Validates all inputs - no unsafe casts
+ *
+ * @throws {Error} if status is not a recognized FAL queue status
  */
-export function mapFalStatusToJobStatus(status: FalQueueStatus): JobStatus {
-  const mappedStatus = STATUS_MAP[status.status] ?? DEFAULT_STATUS;
+export function mapFalStatusToJobStatus(
+  rawStatus: string,
+  requestId?: string,
+  queuePosition?: number,
+  logs?: unknown[],
+): JobStatus {
+  const mappedStatus = VALID_STATUSES[rawStatus];
+  if (!mappedStatus) {
+    throw new Error(
+      `Unknown FAL queue status: "${rawStatus}". Expected one of: ${Object.keys(VALID_STATUSES).join(", ")}`
+    );
+  }
 
   return {
     status: mappedStatus,
-    logs: Array.isArray(status.logs)
-      ? status.logs.map((log: FalLogEntry) => ({
-          message: log.message,
-          level: log.level ?? "info",
-          timestamp: log.timestamp ?? new Date().toISOString(),
-        }))
+    logs: Array.isArray(logs)
+      ? logs.map((log) => {
+          const entry = log as FalLogEntry;
+          return {
+            message: typeof entry?.message === "string" ? entry.message : String(log),
+            level: typeof entry?.level === "string" ? entry.level : "info",
+            timestamp: typeof entry?.timestamp === "string" ? entry.timestamp : new Date().toISOString(),
+          };
+        })
       : [],
-    queuePosition: status.queuePosition ?? undefined,
-    requestId: status.requestId,
+    queuePosition: typeof queuePosition === "number" ? queuePosition : undefined,
+    requestId: typeof requestId === "string" ? requestId : "",
   };
 }

package/src/infrastructure/services/request-store.ts

@@ -1,6 +1,9 @@
 /**
  * Request Store - Promise Deduplication with globalThis
  * Survives hot reloads for React Native development
+ *
+ * React Native is single-threaded - no lock mechanism needed.
+ * Direct Map operations are atomic in JS event loop.
  */
 
 export interface ActiveRequest<T = unknown> {
@@ -10,47 +13,22 @@ export interface ActiveRequest<T = unknown> {
 }
 
 const STORE_KEY = "__FAL_PROVIDER_REQUESTS__";
-const LOCK_KEY = "__FAL_PROVIDER_REQUESTS_LOCK__";
 const TIMER_KEY = "__FAL_PROVIDER_CLEANUP_TIMER__";
 type RequestStore = Map<string, ActiveRequest>;
 
 const CLEANUP_INTERVAL = 60000; // 1 minute
 const MAX_REQUEST_AGE = 300000; // 5 minutes
 
-/**
- * Get cleanup timer from globalThis to survive hot reloads
- */
 function getCleanupTimer(): ReturnType<typeof setInterval> | null {
   const globalObj = globalThis as Record<string, unknown>;
   return (globalObj[TIMER_KEY] as ReturnType<typeof setInterval>) ?? null;
 }
 
-/**
- * Set cleanup timer in globalThis to survive hot reloads
- */
 function setCleanupTimer(timer: ReturnType<typeof setInterval> | null): void {
   const globalObj = globalThis as Record<string, unknown>;
   globalObj[TIMER_KEY] = timer;
 }
 
-/**
- * Simple lock mechanism to prevent concurrent access issues
- * NOTE: This is not a true mutex but provides basic protection for React Native
- */
-function acquireLock(): boolean {
-  const globalObj = globalThis as Record<string, unknown>;
-  if (globalObj[LOCK_KEY]) {
-    return false; // Lock already held
-  }
-  globalObj[LOCK_KEY] = true;
-  return true;
-}
-
-function releaseLock(): void {
-  const globalObj = globalThis as Record<string, unknown>;
-  globalObj[LOCK_KEY] = false;
-}
-
 export function getRequestStore(): RequestStore {
   const globalObj = globalThis as Record<string, unknown>;
   if (!globalObj[STORE_KEY]) {
@@ -61,18 +39,14 @@ export function getRequestStore(): RequestStore {
 
 /**
  * Create a deterministic request key using model and input hash
- * Same model + input will always produce the same key for deduplication
  */
 export function createRequestKey(model: string, input: Record<string, unknown>): string {
   const inputStr = JSON.stringify(input, Object.keys(input).sort());
-  // Use DJB2 hash for input fingerprinting
   let hash = 0;
   for (let i = 0; i < inputStr.length; i++) {
     const char = inputStr.charCodeAt(i);
     hash = ((hash << 5) - hash + char) | 0;
   }
-  // Return deterministic key without unique ID
-  // This allows proper deduplication: same model + input = same key
   return `${model}:${hash.toString(36)}`;
 }
 
@@ -80,56 +54,23 @@ export function getExistingRequest<T>(key: string): ActiveRequest<T> | undefined
   return getRequestStore().get(key) as ActiveRequest<T> | undefined;
 }
 
+/**
+ * Store a request for deduplication
+ * RN is single-threaded - no lock needed, Map.set is synchronous
+ */
 export function storeRequest<T>(key: string, request: ActiveRequest<T>): void {
-  // Acquire lock for consistent operation
-  // React Native is single-threaded, but this prevents re-entrancy issues
-  const maxRetries = 10;
-  let retries = 0;
-
-  // Spin-wait loop (synchronous)
-  // Note: Does NOT yield to event loop - tight loop
-  // In practice, this rarely loops due to single-threaded nature of React Native
-  while (!acquireLock() && retries < maxRetries) {
-    retries++;
-  }
-
-  if (retries >= maxRetries) {
-    // Lock acquisition failed - this shouldn't happen in normal operation
-    // Log warning but proceed anyway since RN is single-threaded
-    console.warn(
-      `[request-store] Failed to acquire lock after ${maxRetries} attempts for key: ${key}. ` +
-      'Proceeding anyway (safe in single-threaded environment)'
-    );
-  }
-
-  try {
-    const requestWithTimestamp = {
-      ...request,
-      createdAt: request.createdAt ?? Date.now(),
-    };
-    getRequestStore().set(key, requestWithTimestamp);
-
-    // Start automatic cleanup if not already running
-    startAutomaticCleanup();
-  } finally {
-    // Always release lock, even if we didn't successfully acquire it
-    // to prevent deadlocks
-    releaseLock();
-  }
+  getRequestStore().set(key, {
+    ...request,
+    createdAt: request.createdAt ?? Date.now(),
+  });
+  ensureCleanupRunning();
 }
 
 export function removeRequest(key: string): void {
   const store = getRequestStore();
   store.delete(key);
-
-  // Stop cleanup timer if store is empty
-  if (store.size === 0) {
-    const timer = getCleanupTimer();
-    if (timer) {
-      clearInterval(timer);
-      setCleanupTimer(null);
-    }
-  }
+  // Don't stop timer here - let the cleanup interval handle it
+  // This prevents the race where a new request arrives right after we stop
 }
 
 export function cancelAllRequests(): void {
@@ -138,13 +79,7 @@ export function cancelAllRequests(): void {
     req.abortController.abort();
   });
   store.clear();
-
-  // Stop cleanup timer
-  const timer = getCleanupTimer();
-  if (timer) {
-    clearInterval(timer);
-    setCleanupTimer(null);
-  }
+  stopCleanupTimer();
 }
 
 export function hasActiveRequests(): boolean {
@@ -152,10 +87,7 @@ export function hasActiveRequests(): boolean {
 }
 
 /**
- * Clean up completed/stale requests from the store
- * Should be called periodically to prevent memory leaks
- *
- * @param maxAge - Maximum age in milliseconds (default: 5 minutes)
+ * Clean up stale requests from the store
  * @returns Number of requests cleaned up
  */
 export function cleanupRequestStore(maxAge: number = MAX_REQUEST_AGE): number {
@@ -163,77 +95,36 @@ export function cleanupRequestStore(maxAge: number = MAX_REQUEST_AGE): number {
   const now = Date.now();
   let cleanedCount = 0;
 
-  // Track stale requests
-  const staleKeys: string[] = [];
-
   for (const [key, request] of store.entries()) {
-    const requestAge = now - request.createdAt;
-
-    // Clean up stale requests that exceed max age
-    if (requestAge > maxAge) {
-      staleKeys.push(key);
-    }
-  }
-
-  // Remove stale requests
-  for (const key of staleKeys) {
-    const request = store.get(key);
-    if (request) {
+    if (now - request.createdAt > maxAge) {
       request.abortController.abort();
       store.delete(key);
       cleanedCount++;
     }
   }
 
-  // Stop cleanup timer if store is empty
+  // Stop timer only inside the interval callback when store is truly empty
   if (store.size === 0) {
-    const timer = getCleanupTimer();
-    if (timer) {
-      clearInterval(timer);
-      setCleanupTimer(null);
-    }
+    stopCleanupTimer();
   }
 
   return cleanedCount;
 }
 
 /**
- * Start automatic cleanup of stale requests
- * Runs periodically to prevent memory leaks
- * Uses globalThis to survive hot reloads in React Native
+ * Ensure cleanup timer is running (idempotent)
  */
-function startAutomaticCleanup(): void {
-  const existingTimer = getCleanupTimer();
-  if (existingTimer) {
-    return; // Already running
-  }
+function ensureCleanupRunning(): void {
+  if (getCleanupTimer()) return;
 
   const timer = setInterval(() => {
-    const cleanedCount = cleanupRequestStore(MAX_REQUEST_AGE);
-    const store = getRequestStore();
-
-    // Stop timer if no more requests in store (prevents indefinite timer)
-    if (store.size === 0) {
-      const currentTimer = getCleanupTimer();
-      if (currentTimer) {
-        clearInterval(currentTimer);
-        setCleanupTimer(null);
-      }
-    }
-
-    if (cleanedCount > 0) {
-      console.log(`[request-store] Cleaned up ${cleanedCount} stale request(s)`);
-    }
+    cleanupRequestStore(MAX_REQUEST_AGE);
   }, CLEANUP_INTERVAL);
 
   setCleanupTimer(timer);
 }
 
-/**
- * Stop automatic cleanup (typically on app shutdown or hot reload)
- * Clears the global timer to prevent memory leaks
- */
-export function stopAutomaticCleanup(): void {
+function stopCleanupTimer(): void {
   const timer = getCleanupTimer();
   if (timer) {
     clearInterval(timer);
@@ -241,8 +132,14 @@ export function stopAutomaticCleanup(): void {
   }
 }
 
-// Clean up any existing timer on module load to prevent leaks during hot reload
-// This ensures old timers are cleared when the module is reloaded in development
+/**
+ * Stop automatic cleanup (for app shutdown)
+ */
+export function stopAutomaticCleanup(): void {
+  stopCleanupTimer();
+}
+
+// Clear any leftover timer on module load (hot reload safety)
 if (typeof globalThis !== "undefined") {
   const existingTimer = getCleanupTimer();
   if (existingTimer) {

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

@@ -1,140 +1,134 @@
 /**
  * FAL Error Handler
- * Unified error handling for FAL AI operations
+ * Uses @fal-ai/client error types (ApiError, ValidationError) for proper error handling
+ * No silent fallbacks - errors are categorized explicitly
  */
 
-import type { FalErrorInfo, FalErrorCategory, FalErrorType } from "../../domain/entities/error.types";
-import { FalErrorType as ErrorTypeEnum } from "../../domain/entities/error.types";
-import { safeJsonParseOrNull } from "./parsers";
-import { isNonEmptyString } from './validators/string-validator.util';
+import { ApiError, ValidationError } from "@fal-ai/client";
+import type { FalErrorInfo, FalErrorCategory } from "../../domain/entities/error.types";
+import { FalErrorType } from "../../domain/entities/error.types";
 
-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]: [],
+/**
+ * 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([
-  ErrorTypeEnum.NETWORK,
-  ErrorTypeEnum.TIMEOUT,
-  ErrorTypeEnum.RATE_LIMIT,
+const RETRYABLE_TYPES = new Set<FalErrorType>([
+  FalErrorType.NETWORK,
+  FalErrorType.TIMEOUT,
+  FalErrorType.RATE_LIMIT,
 ]);
 
 /**
- * Extract HTTP status code from error message
+ * Message-based error type detection (for non-ApiError errors)
  */
-function extractStatusCode(errorString: string): number | undefined {
-  const code = STATUS_CODES.find((c) => errorString.includes(c));
-  return code ? parseInt(code, 10) : undefined;
-}
+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"] },
+];
 
 /**
- * Parse FAL API error and extract user-friendly message
+ * Categorize error using @fal-ai/client error types
+ * Priority: ApiError status code > message pattern matching
  */
-function parseFalApiError(error: unknown): string {
-  const fallback = error instanceof Error ? error.message : String(error);
-
-  const falError = error as FalApiError;
-  if (!falError?.body) return fallback;
+function 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 };
+  }
 
-  const body = typeof falError.body === "string"
-    ? safeJsonParseOrNull<{ detail?: FalApiErrorDetail[] }>(falError.body)
-    : falError.body;
+  // 2. Standard Error - match message patterns
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
 
-  const detail = body?.detail?.[0];
-  return detail?.msg ?? falError.message ?? fallback;
-}
+  for (const { type, patterns } of MESSAGE_PATTERNS) {
+    if (patterns.some((p) => message.includes(p))) {
+      return { type, messageKey: type, retryable: RETRYABLE_TYPES.has(type) };
+    }
+  }
 
-/**
- * Check if error string matches any of the provided patterns
- */
-function matchesPatterns(errorString: string, patterns: string[]): boolean {
-  return patterns.some((pattern) => errorString.includes(pattern));
+  // 3. No match - UNKNOWN, not retryable
+  return { type: FalErrorType.UNKNOWN, messageKey: "unknown", retryable: false };
 }
 
 /**
- * Categorize FAL error based on error message patterns
+ * Extract user-readable message from error
+ * Uses @fal-ai/client types for structured extraction
  */
-function categorizeError(error: unknown): FalErrorCategory {
-  const message = error instanceof Error ? error.message : String(error);
-  const errorString = message.toLowerCase();
+function extractMessage(error: unknown): string {
+  // ValidationError - extract field-level messages
+  if (error instanceof ValidationError) {
+    const fieldErrors = error.fieldErrors;
+    if (fieldErrors.length > 0) {
+      const messages = fieldErrors.map((e) => e.msg).filter(Boolean);
+      if (messages.length > 0) return messages.join("; ");
+    }
+    return error.message;
+  }
 
-  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),
-      };
+  // ApiError - extract from body or message
+  if (error instanceof ApiError) {
+    // body may contain detail array
+    const body = error.body as { detail?: Array<{ msg?: string }> } | undefined;
+    if (body?.detail?.[0]?.msg) {
+      return body.detail[0].msg;
     }
+    return error.message;
+  }
+
+  // Standard Error
+  if (error instanceof Error) {
+    return error.message;
   }
 
-  return { type: ErrorTypeEnum.UNKNOWN, messageKey: "unknown", retryable: false };
+  return String(error);
 }
 
 /**
- * Build FalErrorInfo from error string and category
+ * Map error to FalErrorInfo with full categorization
  */
-function buildErrorInfo(
-  category: FalErrorCategory,
-  errorString: string,
-  errorInstance?: Error
-): FalErrorInfo {
+export function mapFalError(error: unknown): FalErrorInfo {
+  const category = categorizeError(error);
+  const message = extractMessage(error);
+
   return {
     type: category.type,
     messageKey: `fal.errors.${category.messageKey}`,
     retryable: category.retryable,
-    originalError: errorString,
-    originalErrorName: errorInstance?.name,
-    stack: errorInstance?.stack,
-    statusCode: extractStatusCode(errorString),
+    originalError: message,
+    originalErrorName: error instanceof Error ? error.name : undefined,
+    stack: error instanceof Error ? error.stack : undefined,
+    statusCode: error instanceof ApiError ? error.status : undefined,
   };
 }
 
-/**
- * Map error to FalErrorInfo with full error details
- */
-export function mapFalError(error: unknown): FalErrorInfo {
-  const category = categorizeError(error);
-
-  if (error instanceof Error) {
-    return buildErrorInfo(category, error.message, error);
-  }
-
-  return buildErrorInfo(category, String(error));
-}
-
 /**
  * Parse FAL error and return user-friendly message
  */
 export function parseFalError(error: unknown): string {
-  const userMessage = parseFalApiError(error);
-  if (!isNonEmptyString(userMessage)) {
-    return "An unknown error occurred. Please try again.";
-  }
-  return userMessage;
+  return extractMessage(error);
 }
 
 /**
@@ -148,10 +142,5 @@ export function categorizeFalError(error: unknown): FalErrorCategory {
  * Check if FAL error is retryable
  */
 export function isFalErrorRetryable(error: unknown): boolean {
-  return categorizeFalError(error).retryable;
+  return categorizeError(error).retryable;
 }
-
-/**
- * Extract status code from error
- */
-export { extractStatusCode };

package/src/infrastructure/utils/index.ts

@@ -26,7 +26,6 @@ export {
   mapFalError,
   parseFalError,
   isFalErrorRetryable,
-  extractStatusCode,
 } from "./fal-error-handler.util";
 
 export { formatDate } from "./date-format.util";

package/src/infrastructure/utils/parsers/object-transformers.util.ts

@@ -3,30 +3,14 @@
  * Clone, merge, pick, and omit operations
  */
 
-import { getErrorMessage } from '../helpers/error-helpers.util';
-
 /**
  * Deep clone object using JSON serialization
- * NOTE: This has limitations:
- * - Functions are not cloned
- * - Dates become strings
- * - Circular references will cause errors
- * For complex objects, consider a dedicated cloning library
+ * Throws on failure (circular references, non-serializable values)
+ * No silent fallback - caller must handle errors explicitly
  */
 export function deepClone<T>(data: T): T {
-  try {
-    // Try JSON clone first (fast path)
-    const serialized = JSON.stringify(data);
-    return JSON.parse(serialized) as T;
-  } catch (error) {
-    // Fallback for circular references or other JSON errors
-    console.warn(
-      '[object-transformers] deepClone failed, returning original:',
-      getErrorMessage(error)
-    );
-    // Return original data if cloning fails
-    return data;
-  }
+  const serialized = JSON.stringify(data);
+  return JSON.parse(serialized) as T;
 }
 
 /**