@umituz/react-native-ai-fal-provider 1.0.58 → 1.0.60

package/package.json

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

package/src/index.ts

@@ -36,6 +36,27 @@ export {
   buildReplaceBackgroundInput, buildHDTouchUpInput,
 } from "./infrastructure/utils";
 
+export {
+  isFalModelType, isModelType, isFalErrorType,
+  isValidBase64Image, isValidApiKey, isValidModelId, isValidPrompt,
+  isValidTimeout, isValidRetryCount,
+} from "./infrastructure/utils";
+
+export {
+  formatImageDataUri, extractBase64, getDataUriExtension, isImageDataUri,
+  calculateTimeoutWithJitter, formatCreditCost, truncatePrompt, sanitizePrompt,
+  buildErrorMessage, isDefined, removeNullish, debounce, throttle,
+} from "./infrastructure/utils";
+
+export {
+  createJobMetadata, updateJobMetadata, isJobCompleted, isJobRunning,
+  isJobStale, getJobDuration, formatJobDuration, calculateJobProgress,
+  serializeJobMetadata, deserializeJobMetadata, filterValidJobs,
+  sortJobsByCreation, getActiveJobs, getCompletedJobs,
+} from "./infrastructure/utils";
+
+export type { FalJobMetadata } from "./infrastructure/utils";
+
 export type {
   UpscaleOptions, PhotoRestoreOptions, FaceSwapOptions, ImageToImagePromptConfig,
   RemoveBackgroundOptions, RemoveObjectOptions, ReplaceBackgroundOptions,

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

@@ -106,6 +106,7 @@ export class FalProvider implements IAIProvider {
     this.validateInitialization();
     const timeoutMs = options?.timeoutMs ?? this.config?.defaultTimeoutMs ?? DEFAULT_FAL_CONFIG.defaultTimeoutMs;
     let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    let currentRequestId: string | null = null;
 
     if (typeof __DEV__ !== "undefined" && __DEV__) {
       console.log("[FalProvider] Subscribe started:", { model, timeoutMs });
@@ -119,12 +120,16 @@ export class FalProvider implements IAIProvider {
           input,
           logs: false,
           pollInterval: DEFAULT_FAL_CONFIG.pollInterval,
-          onQueueUpdate: (update: { status: string; logs?: unknown[] }) => {
-            const jobStatus = mapFalStatusToJobStatus(update as unknown as FalQueueStatus);
+          onQueueUpdate: (update: { status: string; logs?: unknown[]; request_id?: string }) => {
+            currentRequestId = update.request_id ?? null;
+            const jobStatus = mapFalStatusToJobStatus({
+              ...update as unknown as FalQueueStatus,
+              requestId: currentRequestId ?? "",
+            });
             if (jobStatus.status !== lastStatus) {
               lastStatus = jobStatus.status;
               if (typeof __DEV__ !== "undefined" && __DEV__) {
-                console.log("[FalProvider] Status:", jobStatus.status);
+                console.log("[FalProvider] Status:", jobStatus.status, "RequestId:", currentRequestId);
               }
             }
             options?.onQueueUpdate?.(jobStatus);
@@ -136,7 +141,7 @@ export class FalProvider implements IAIProvider {
       ]);
 
       if (typeof __DEV__ !== "undefined" && __DEV__) {
-        console.log("[FalProvider] Subscribe completed:", { model });
+        console.log("[FalProvider] Subscribe completed:", { model, requestId: currentRequestId });
       }
 
       validateNSFWContent(result as Record<string, unknown>);

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

@@ -6,21 +6,29 @@
 import type { JobStatus, AIJobStatusType } from "@umituz/react-native-ai-generation-content";
 import type { FalQueueStatus, FalLogEntry } from "../../domain/entities/fal.types";
 
-const STATUS_MAP: Record<string, AIJobStatusType> = {
-  IN_QUEUE: "IN_QUEUE",
-  IN_PROGRESS: "IN_PROGRESS",
-  COMPLETED: "COMPLETED",
-  FAILED: "FAILED",
-};
+const STATUS_MAP = {
+  IN_QUEUE: "IN_QUEUE" as const,
+  IN_PROGRESS: "IN_PROGRESS" as const,
+  COMPLETED: "COMPLETED" as const,
+  FAILED: "FAILED" as const,
+} as const 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
+ */
 export function mapFalStatusToJobStatus(status: FalQueueStatus): JobStatus {
+  const mappedStatus = STATUS_MAP[status.status] ?? DEFAULT_STATUS;
+
   return {
-    status: STATUS_MAP[status.status] ?? "IN_PROGRESS",
+    status: mappedStatus,
     logs: status.logs?.map((log: FalLogEntry) => ({
       message: log.message,
       level: log.level ?? "info",
-      timestamp: log.timestamp,
-    })),
-    queuePosition: status.queuePosition,
+      timestamp: log.timestamp ?? new Date().toISOString(),
+    })) ?? [],
+    queuePosition: status.queuePosition ?? undefined,
   };
 }

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

@@ -0,0 +1,151 @@
+/**
+ * Helper Utilities
+ * Common helper functions for FAL operations
+ */
+
+/**
+ * Format image as data URI if not already formatted
+ */
+export function formatImageDataUri(base64: string): string {
+  if (base64.startsWith("data:")) {
+    return base64;
+  }
+  return `data:image/jpeg;base64,${base64}`;
+}
+
+/**
+ * Extract base64 from data URI
+ */
+export function extractBase64(dataUri: string): string {
+  if (!dataUri.startsWith("data:")) {
+    return dataUri;
+  }
+
+  const parts = dataUri.split(",");
+  return parts.length > 1 ? parts[1] : dataUri;
+}
+
+/**
+ * Get file extension from data URI
+ */
+export function getDataUriExtension(dataUri: string): string | null {
+  const match = dataUri.match(/^data:image\/(\w+);base64/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if data URI is an image
+ */
+export function isImageDataUri(value: string): boolean {
+  return value.startsWith("data:image/");
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Format credit cost for display
+ */
+export function formatCreditCost(cost: number): string {
+  if (cost % 1 === 0) {
+    return cost.toString();
+  }
+  return cost.toFixed(2);
+}
+
+/**
+ * Truncate prompt to maximum length
+ */
+export function truncatePrompt(prompt: string, maxLength: number = 5000): string {
+  if (prompt.length <= maxLength) {
+    return prompt;
+  }
+  return prompt.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Sanitize prompt by removing excessive whitespace
+ */
+export function sanitizePrompt(prompt: string): string {
+  return prompt.trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Build error message with context
+ */
+export function buildErrorMessage(
+  type: string,
+  context: Record<string, unknown>
+): string {
+  const contextStr = Object.entries(context)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(", ");
+  return `${type}${contextStr ? ` (${contextStr})` : ""}`;
+}
+
+/**
+ * Check if value is defined (not null or undefined)
+ */
+export function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Filter out null and undefined values from object
+ */
+export function removeNullish<T extends Record<string, unknown>>(
+  obj: T
+): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([_, value]) => isDefined(value))
+  ) as Partial<T>;
+}
+
+/**
+ * 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/index.ts

@@ -18,3 +18,50 @@ export {
   buildReplaceBackgroundInput,
   buildHDTouchUpInput,
 } from "./input-builders.util";
+
+export {
+  isFalModelType,
+  isModelType,
+  isFalErrorType,
+  isValidBase64Image,
+  isValidApiKey,
+  isValidModelId,
+  isValidPrompt,
+  isValidTimeout,
+  isValidRetryCount,
+} from "./type-guards.util";
+
+export {
+  formatImageDataUri,
+  extractBase64,
+  getDataUriExtension,
+  isImageDataUri,
+  calculateTimeoutWithJitter,
+  formatCreditCost,
+  truncatePrompt,
+  sanitizePrompt,
+  buildErrorMessage,
+  isDefined,
+  removeNullish,
+  debounce,
+  throttle,
+} from "./helpers.util";
+
+export {
+  createJobMetadata,
+  updateJobMetadata,
+  isJobCompleted,
+  isJobRunning,
+  isJobStale,
+  getJobDuration,
+  formatJobDuration,
+  calculateJobProgress,
+  serializeJobMetadata,
+  deserializeJobMetadata,
+  filterValidJobs,
+  sortJobsByCreation,
+  getActiveJobs,
+  getCompletedJobs,
+} from "./job-metadata.util";
+
+export type { FalJobMetadata } from "./job-metadata.util";

package/src/infrastructure/utils/job-metadata.util.ts

@@ -0,0 +1,176 @@
+/**
+ * Job Metadata Utilities
+ * Helper functions for job metadata and management
+ */
+
+import type { JobStatus } from "@umituz/react-native-ai-generation-content";
+
+/**
+ * Job metadata for tracking and persistence
+ */
+export interface FalJobMetadata {
+  readonly requestId: string;
+  readonly model: string;
+  readonly status: JobStatus["status"];
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly completedAt?: string;
+  readonly timeout?: number;
+  readonly error?: string;
+}
+
+/**
+ * Create job metadata
+ */
+export function createJobMetadata(
+  requestId: string,
+  model: string,
+  timeout?: number
+): FalJobMetadata {
+  const now = new Date().toISOString();
+  return {
+    requestId,
+    model,
+    status: "IN_QUEUE",
+    createdAt: now,
+    updatedAt: now,
+    timeout,
+  };
+}
+
+/**
+ * Update job metadata status
+ */
+export function updateJobMetadata(
+  metadata: FalJobMetadata,
+  status: JobStatus["status"],
+  error?: string
+): FalJobMetadata {
+  return {
+    ...metadata,
+    status,
+    updatedAt: new Date().toISOString(),
+    ...(status === "COMPLETED" || status === "FAILED" ? { completedAt: new Date().toISOString() } : {}),
+    ...(error ? { error } : {}),
+  };
+}
+
+/**
+ * Check if job is completed (success or failure)
+ */
+export function isJobCompleted(metadata: FalJobMetadata): boolean {
+  return metadata.status === "COMPLETED" || metadata.status === "FAILED";
+}
+
+/**
+ * Check if job is running
+ */
+export function isJobRunning(metadata: FalJobMetadata): boolean {
+  return metadata.status === "IN_QUEUE" || metadata.status === "IN_PROGRESS";
+}
+
+/**
+ * Check if job is stale (older than specified minutes)
+ */
+export function isJobStale(metadata: FalJobMetadata, maxAgeMinutes: number = 60): boolean {
+  const age = Date.now() - new Date(metadata.createdAt).getTime();
+  const maxAgeMs = maxAgeMinutes * 60 * 1000;
+  return age > maxAgeMs;
+}
+
+/**
+ * Get job duration in milliseconds
+ */
+export function getJobDuration(metadata: FalJobMetadata): number | null {
+  if (!metadata.completedAt) {
+    return null;
+  }
+  return new Date(metadata.completedAt).getTime() - new Date(metadata.createdAt).getTime();
+}
+
+/**
+ * Format job duration for display
+ */
+export function formatJobDuration(metadata: FalJobMetadata): string {
+  const duration = getJobDuration(metadata);
+  if (!duration) {
+    return "In progress";
+  }
+
+  const seconds = Math.floor(duration / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+}
+
+/**
+ * Calculate job progress percentage
+ */
+export function calculateJobProgress(metadata: FalJobMetadata): number {
+  switch (metadata.status) {
+    case "IN_QUEUE":
+      return 10;
+    case "IN_PROGRESS":
+      return 50;
+    case "COMPLETED":
+      return 100;
+    case "FAILED":
+      return 0;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Serialize job metadata for storage
+ */
+export function serializeJobMetadata(metadata: FalJobMetadata): string {
+  return JSON.stringify(metadata);
+}
+
+/**
+ * Deserialize job metadata from storage
+ */
+export function deserializeJobMetadata(data: string): FalJobMetadata | null {
+  try {
+    return JSON.parse(data) as FalJobMetadata;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Filter valid job metadata from array
+ */
+export function filterValidJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
+  return jobs.filter((job) => !isJobStale(job));
+}
+
+/**
+ * Sort jobs by creation time (newest first)
+ */
+export function sortJobsByCreation(jobs: FalJobMetadata[]): FalJobMetadata[] {
+  return [...jobs].sort((a, b) => {
+    const timeA = new Date(a.createdAt).getTime();
+    const timeB = new Date(b.createdAt).getTime();
+    return timeB - timeA;
+  });
+}
+
+/**
+ * Get active jobs (not completed and not stale)
+ */
+export function getActiveJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
+  return jobs.filter((job) => isJobRunning(job) && !isJobStale(job));
+}
+
+/**
+ * Get completed jobs
+ */
+export function getCompletedJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
+  return jobs.filter((job) => isJobCompleted(job));
+}

package/src/infrastructure/utils/type-guards.util.ts

@@ -0,0 +1,114 @@
+/**
+ * Type Guards and Validation Utilities
+ * Runtime type checking and validation helpers
+ */
+
+import type { FalModelType } from "../../domain/entities/fal.types";
+import type { ModelType } from "../../domain/types/model-selection.types";
+import { FalErrorType } from "../../domain/entities/error.types";
+
+/**
+ * Check if a string is a valid FalModelType
+ */
+export function isFalModelType(value: unknown): value is FalModelType {
+  const validTypes: ReadonlyArray<FalModelType> = [
+    "text-to-image",
+    "text-to-video",
+    "text-to-voice",
+    "image-to-video",
+    "image-to-image",
+    "text-to-text",
+  ];
+  return typeof value === "string" && validTypes.includes(value as FalModelType);
+}
+
+/**
+ * Check if a string is a valid ModelType
+ */
+export function isModelType(value: unknown): value is ModelType {
+  const validTypes: ReadonlyArray<ModelType> = [
+    "text-to-image",
+    "text-to-video",
+    "image-to-video",
+    "text-to-voice",
+  ];
+  return typeof value === "string" && validTypes.includes(value as ModelType);
+}
+
+/**
+ * Check if error is a FalErrorType
+ */
+export function isFalErrorType(value: unknown): value is FalErrorType {
+  const validTypes: ReadonlyArray<FalErrorType> = [
+    FalErrorType.NETWORK,
+    FalErrorType.TIMEOUT,
+    FalErrorType.API_ERROR,
+    FalErrorType.VALIDATION,
+    FalErrorType.CONTENT_POLICY,
+    FalErrorType.RATE_LIMIT,
+    FalErrorType.AUTHENTICATION,
+    FalErrorType.QUOTA_EXCEEDED,
+    FalErrorType.MODEL_NOT_FOUND,
+    FalErrorType.UNKNOWN,
+  ];
+  return typeof value === "string" && validTypes.includes(value as FalErrorType);
+}
+
+/**
+ * Validate base64 image string
+ */
+export function isValidBase64Image(value: unknown): boolean {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  // Check data URI prefix
+  if (value.startsWith("data:image/")) {
+    return value.includes("base64,");
+  }
+
+  // Check if it's a valid base64 string
+  const base64Pattern = /^[A-Za-z0-9+/]+=*$/;
+  return base64Pattern.test(value) && value.length > 0;
+}
+
+/**
+ * Validate API key format
+ */
+export function isValidApiKey(value: unknown): boolean {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Validate model ID format
+ */
+export function isValidModelId(value: unknown): boolean {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  // FAL model IDs typically follow the pattern: "owner/model-name" or "owner/model/version"
+  const modelIdPattern = /^[a-z0-9-]+\/[a-z0-9-]+(\/[a-z0-9.]+)?$/;
+  return modelIdPattern.test(value);
+}
+
+/**
+ * Validate prompt string
+ */
+export function isValidPrompt(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= 5000;
+}
+
+/**
+ * Validate timeout value
+ */
+export function isValidTimeout(value: unknown): boolean {
+  return typeof value === "number" && value > 0 && value <= 600000; // Max 10 minutes
+}
+
+/**
+ * Validate retry count
+ */
+export function isValidRetryCount(value: unknown): boolean {
+  return typeof value === "number" && value >= 0 && value <= 10;
+}

package/src/presentation/hooks/use-fal-generation.ts

@@ -20,6 +20,7 @@ export interface UseFalGenerationResult<T> {
   error: FalErrorInfo | null;
   isLoading: boolean;
   isRetryable: boolean;
+  requestId: string | null;
   generate: (modelEndpoint: string, input: FalJobInput) => Promise<T | null>;
   retry: () => Promise<T | null>;
   reset: () => void;
@@ -33,6 +34,7 @@ export function useFalGeneration<T = unknown>(
   const [isLoading, setIsLoading] = useState(false);
 
   const lastRequestRef = useRef<{ endpoint: string; input: FalJobInput } | null>(null);
+  const currentRequestIdRef = useRef<string | null>(null);
 
   const generate = useCallback(
     async (modelEndpoint: string, input: FalJobInput): Promise<T | null> => {
@@ -40,15 +42,18 @@ export function useFalGeneration<T = unknown>(
       setIsLoading(true);
       setError(null);
       setData(null);
+      currentRequestIdRef.current = null;
 
       try {
         const result = await falProvider.subscribe<T>(modelEndpoint, input, {
           timeoutMs: options?.timeoutMs,
           onQueueUpdate: (status) => {
+            // Note: requestId is tracked internally by falProvider subscribe
+            // and exposed via the requestId ref, not from status object
             // Map JobStatus to FalQueueStatus for backward compatibility
             options?.onProgress?.({
               status: status.status,
-              requestId: "",
+              requestId: currentRequestIdRef.current ?? "",
               logs: status.logs?.map((log: FalLogEntry) => ({
                 message: log.message,
                 level: log.level,
@@ -84,6 +89,7 @@ export function useFalGeneration<T = unknown>(
     setError(null);
     setIsLoading(false);
     lastRequestRef.current = null;
+    currentRequestIdRef.current = null;
   }, []);
 
   return {
@@ -91,6 +97,7 @@ export function useFalGeneration<T = unknown>(
     error,
     isLoading,
     isRetryable: error ? isFalErrorRetryable(error.originalError) : false,
+    requestId: currentRequestIdRef.current,
     generate,
     retry,
     reset,