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

package/src/shared/helpers.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared Helper Utilities
+ * Consolidated helpers for error handling, object manipulation, timing, and calculations
+ *
+ * This file consolidates functionality from:
+ * - error-helpers.util.ts
+ * - object-helpers.util.ts
+ * - timing-helpers.util.ts
+ * - calculation-helpers.util.ts
+ */
+
+// ─── Error Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Extract error message from any error type
+ * Handles Error instances, strings, and unknown types
+ *
+ * @param error - The error to extract message from
+ * @returns The error message as a string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   console.error('Operation failed:', getErrorMessage(error));
+ * }
+ * ```
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Extract error message with fallback
+ * Returns fallback if error message is empty or whitespace-only
+ *
+ * @param error - The error to extract message from
+ * @param fallback - Fallback message if error message is empty
+ * @returns The error message or fallback
+ */
+export function getErrorMessageOr(error: unknown, fallback: string): string {
+  const message = getErrorMessage(error);
+  return message && message.trim().length > 0 ? message : fallback;
+}
+
+/**
+ * Create error message with context prefix
+ * Useful for adding operation context to error messages
+ *
+ * @param error - The error to extract message from
+ * @param context - Context to prepend to the error message
+ * @returns Formatted error message with context
+ */
+export function formatErrorMessage(error: unknown, context: string): string {
+  return `${context}: ${getErrorMessage(error)}`;
+}
+
+// ─── Object Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Build error message with context
+ *
+ * @param type - Error type or category
+ * @param context - Object containing key-value pairs for context
+ * @returns Formatted error message string
+ */
+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)
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating value is not null/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
+ *
+ * @param obj - Object to filter
+ * @returns New object with null/undefined values removed
+ */
+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>;
+}
+
+/**
+ * Generate unique ID with optional prefix
+ *
+ * @param prefix - Optional prefix for the ID
+ * @returns Unique identifier string
+ */
+export function generateUniqueId(prefix: string = ""): string {
+  const timestamp = Date.now().toString(36);
+  const randomStr = Math.random().toString(36).substring(2, 9);
+  return prefix ? `${prefix}_${timestamp}${randomStr}` : `${timestamp}${randomStr}`;
+}
+
+// ─── Timing Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after delay
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Calculation Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Calculate elapsed time in milliseconds from a start timestamp
+ *
+ * @param startTime - Start timestamp in milliseconds
+ * @returns Elapsed time in milliseconds
+ */
+export function getElapsedTime(startTime: number): number {
+  return Date.now() - startTime;
+}
+
+/**
+ * Calculate actual file size from base64 string
+ * Base64 encoding inflates size by ~33%, so actual size is ~75% of base64 length
+ *
+ * @param base64String - Base64 encoded string
+ * @returns Actual size in kilobytes
+ */
+export function getActualSizeKB(base64String: string): number {
+  const base64SizeKB = Math.round(base64String.length / 1024);
+  // Base64 inflates by ~33%, so actual size is ~75%
+  return Math.round(base64SizeKB * 0.75);
+}

package/src/shared/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared Utilities - Public API
+ * Consolidated helpers, validators, and type guards
+ */
+
+export * from "./helpers";
+export * from "./validators";
+export * from "./type-guards";

package/src/shared/type-guards.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared Type Guards
+ * Runtime type checking for model types, error types, and other domain types
+ *
+ * This file consolidates functionality from:
+ * - model-type-guards.util.ts
+ * - validation-guards.util.ts (type guard portions)
+ */
+
+import type { FalModelType } from "../domain/entities/fal.types";
+import type { ModelType } from "../domain/types/model-selection.types";
+import { FalErrorType } from "../domain/entities/error.types";
+
+// ─── Model Type Guards ─────────────────────────────────────────────────────────
+
+/**
+ * Check if a string is a valid FalModelType
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a 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
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a 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);
+}
+
+// ─── Error Type Guards ────────────────────────────────────────────────────────
+
+/**
+ * Check if error is a FalErrorType
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value 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.IMAGE_TOO_SMALL,
+    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);
+}
+
+// ─── API Error Type Guards ────────────────────────────────────────────────────
+
+/**
+ * Check if error is retryable based on error type
+ *
+ * @param error - Error to check
+ * @returns True if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("network") ||
+      message.includes("timeout") ||
+      message.includes("timed out") ||
+      message.includes("econnrefused") ||
+      message.includes("enotfound") ||
+      message.includes("fetch")
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if value is a local file URI
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a local file URI
+ */
+export function isLocalFileUri(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value.startsWith("file://") || value.startsWith("content://"))
+  );
+}
+
+/**
+ * Check if value is an HTTP/HTTPS URL
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is an HTTP/HTTPS URL
+ */
+export function isHttpUrl(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value.startsWith("http://") || value.startsWith("https://"))
+  );
+}

package/src/shared/validators.ts

@@ -0,0 +1,281 @@
+/**
+ * Shared Validation Utilities
+ * Consolidated validators for strings, data URIs, and business rules
+ *
+ * This file consolidates functionality from:
+ * - data-uri-validator.util.ts
+ * - string-validator.util.ts
+ * - validation-guards.util.ts
+ */
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const MIN_BASE64_IMAGE_LENGTH = 100;
+const MIN_MODEL_ID_LENGTH = 3;
+const MAX_PROMPT_LENGTH = 5000;
+const MAX_TIMEOUT_MS = 300000; // 5 minutes
+const MAX_RETRY_COUNT = 5;
+
+const SUSPICIOUS_PATTERNS = [
+  /<script/i,
+  /javascript:/i,
+  /on\w+\s*=/i,
+  /<iframe/i,
+  /<embed/i,
+  /<object/i,
+  /data:(?!image\/)/i,
+  /vbscript:/i,
+] as const;
+
+const MODEL_ID_PATTERN = /^[a-zA-Z0-9-_]+\/[a-zA-Z0-9-_.]+(\/[a-zA-Z0-9-_.]+)*$/;
+
+// ─── String Validators ─────────────────────────────────────────────────────────
+
+/**
+ * Check if string is empty or whitespace-only
+ *
+ * @param value - Value to check
+ * @returns True if the value is an empty string or contains only whitespace
+ */
+export function isEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length === 0;
+}
+
+/**
+ * Check if value is a non-empty string
+ * Type guard version for better TypeScript inference
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a non-empty string
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Check if value is a string (empty or non-empty)
+ * Basic type guard for string validation
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a string
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+/**
+ * Check if string contains suspicious content
+ *
+ * @param value - String to check
+ * @returns True if suspicious patterns are found
+ */
+function hasSuspiciousContent(value: string): boolean {
+  return SUSPICIOUS_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+// ─── Data URI Validators ──────────────────────────────────────────────────────
+
+/**
+ * Check if value is a data URI (any type)
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a data URI string
+ */
+export function isDataUri(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("data:");
+}
+
+/**
+ * Check if value is an image data URI
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is an image data URI string
+ */
+export function isImageDataUri(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("data:image/");
+}
+
+/**
+ * Check if value is a base64-encoded data URI
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value contains base64 encoding
+ */
+export function isBase64DataUri(value: unknown): value is string {
+  return isDataUri(value) && typeof value === "string" && value.includes("base64,");
+}
+
+/**
+ * Extract MIME type from data URI
+ *
+ * @param dataUri - Data URI string
+ * @returns MIME type or null if not found
+ */
+export function extractMimeType(dataUri: string): string | null {
+  const match = dataUri.match(/^data:([^;,]+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract base64 content from data URI
+ *
+ * @param dataUri - Data URI string
+ * @returns Base64 content or null if not base64-encoded
+ */
+export function extractBase64Content(dataUri: string): string | null {
+  const parts = dataUri.split("base64,");
+  return parts.length === 2 ? parts[1] : null;
+}
+
+// ─── Business Validators ───────────────────────────────────────────────────────
+
+/**
+ * Validate base64 image string
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid base64 image
+ */
+export function isValidBase64Image(value: unknown): boolean {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  // Check data URI prefix
+  if (value.startsWith("data:image/")) {
+    const parts = value.split("base64,");
+    if (parts.length < 2) return false;
+    const base64Part = parts[1];
+    if (!base64Part) return false;
+    return base64Part.length >= MIN_BASE64_IMAGE_LENGTH;
+  }
+
+  // Check if it's a valid base64 string with minimum length
+  const base64Pattern = /^[A-Za-z0-9+/]+=*$/;
+  return base64Pattern.test(value) && value.length >= MIN_BASE64_IMAGE_LENGTH;
+}
+
+/**
+ * Validate API key format
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid API key
+ */
+export function isValidApiKey(value: unknown): boolean {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Validate model ID format
+ * Pattern: org/model or org/model/sub1/sub2/... (multiple path segments)
+ * Allows dots for versions (e.g., v1.5) but prevents path traversal (..)
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid model ID
+ */
+export function isValidModelId(value: unknown): boolean {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  // Prevent path traversal attacks
+  if (value.includes("..")) {
+    return false;
+  }
+
+  // Ensure it doesn't start or end with dots
+  if (value.startsWith(".") || value.endsWith(".")) {
+    return false;
+  }
+
+  return (
+    MODEL_ID_PATTERN.test(value) && value.length >= MIN_MODEL_ID_LENGTH
+  );
+}
+
+/**
+ * Validate prompt string
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid prompt
+ */
+export function isValidPrompt(value: unknown): boolean {
+  if (!isNonEmptyString(value)) return false;
+  return value.length <= MAX_PROMPT_LENGTH && !hasSuspiciousContent(value);
+}
+
+/**
+ * Validate timeout value
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid timeout
+ */
+export function isValidTimeout(value: unknown): boolean {
+  return (
+    typeof value === "number" &&
+    !isNaN(value) &&
+    isFinite(value) &&
+    value > 0 &&
+    value <= MAX_TIMEOUT_MS
+  );
+}
+
+/**
+ * Validate retry count
+ *
+ * @param value - Value to validate
+ * @returns True if value is a valid retry count
+ */
+export function isValidRetryCount(value: unknown): boolean {
+  return (
+    typeof value === "number" &&
+    !isNaN(value) &&
+    isFinite(value) &&
+    Number.isInteger(value) &&
+    value >= 0 &&
+    value <= MAX_RETRY_COUNT
+  );
+}
+
+/**
+ * Validate URL format and protocol
+ * Rejects malicious URLs and unsafe protocols
+ *
+ * @param value - URL string to validate
+ * @returns True if URL is valid and safe
+ */
+export function isValidAndSafeUrl(value: string): boolean {
+  // Allow http/https URLs
+  if (value.startsWith("http://") || value.startsWith("https://")) {
+    try {
+      const url = new URL(value);
+      // Reject URLs with @ (potential auth bypass)
+      if (url.href.includes("@") && url.username) {
+        return false;
+      }
+      // Ensure domain exists
+      if (!url.hostname || url.hostname.length === 0) {
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Allow local file URIs
+  if (value.startsWith("file://") || value.startsWith("content://")) {
+    return true;
+  }
+
+  // Allow base64 image data URIs only
+  if (isImageDataUri(value)) {
+    // Check for suspicious content in data URI
+    const dataContent = value.substring(0, 200);
+    if (hasSuspiciousContent(dataContent)) {
+      return false;
+    }
+    return true;
+  }
+
+  return false;
+}