@umituz/react-native-ai-generation-content 1.60.0 → 1.61.1

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@umituz/react-native-ai-generation-content",
-  "version": "1.60.0",
+  "version": "1.61.1",
   "description": "Provider-agnostic AI generation orchestration for React Native with result preview components",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
     "./prompts": "./src/domains/prompts/index.ts",
     "./content-moderation": "./src/domains/content-moderation/index.ts",
     "./creations": "./src/domains/creations/index.ts",

package/src/core/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @umituz/react-native-ai-generation-content/core
+ *
+ * Core types for AI generation providers.
+ * This module contains ONLY types and utilities - no implementation details.
+ *
+ * Use this subpath for provider implementations:
+ * ```typescript
+ * import type { IAIProvider, AIProviderConfig } from "@umituz/react-native-ai-generation-content/core";
+ * ```
+ *
+ * @module @umituz/react-native-ai-generation-content/core
+ */
+
+// Result Pattern
+export type { Result, Success, Failure } from "./types/result.types";
+export {
+  success,
+  failure,
+  isSuccess,
+  isFailure,
+  mapResult,
+  andThen,
+  unwrap,
+  unwrapOr,
+} from "./types/result.types";
+
+// Error Types
+export { AIErrorType } from "./types/error.types";
+export type { AIErrorInfo, AIErrorMessages } from "./types/error.types";
+
+// Provider Types
+export type {
+  // Feature Types
+  ImageFeatureType,
+  VideoFeatureType,
+  // Config
+  AIProviderConfig,
+  // Status
+  AIJobStatusType,
+  AILogEntry,
+  JobSubmission,
+  JobStatus,
+  // Progress
+  ProviderProgressInfo,
+  SubscribeOptions,
+  RunOptions,
+  // Capabilities
+  ProviderCapabilities,
+  // Input Data
+  ImageFeatureInputData,
+  VideoFeatureInputData,
+  // Provider Interfaces
+  IAIProviderLifecycle,
+  IAIProviderCapabilities,
+  IAIProviderJobManager,
+  IAIProviderExecutor,
+  IAIProviderImageFeatures,
+  IAIProviderVideoFeatures,
+  IAIProvider,
+} from "./types/provider.types";

package/src/core/types/error.types.ts

@@ -0,0 +1,36 @@
+/**
+ * AI Generation Error Types
+ * Provider-agnostic error classification
+ *
+ * @module @umituz/react-native-ai-generation-content/core
+ */
+
+export enum AIErrorType {
+  NETWORK = "NETWORK",
+  RATE_LIMIT = "RATE_LIMIT",
+  AUTHENTICATION = "AUTHENTICATION",
+  VALIDATION = "VALIDATION",
+  CONTENT_POLICY = "CONTENT_POLICY",
+  SERVER = "SERVER",
+  TIMEOUT = "TIMEOUT",
+  UNKNOWN = "UNKNOWN",
+}
+
+export interface AIErrorInfo {
+  type: AIErrorType;
+  messageKey: string;
+  retryable: boolean;
+  originalError?: unknown;
+  statusCode?: number;
+}
+
+export interface AIErrorMessages {
+  [AIErrorType.NETWORK]: string;
+  [AIErrorType.RATE_LIMIT]: string;
+  [AIErrorType.AUTHENTICATION]: string;
+  [AIErrorType.VALIDATION]: string;
+  [AIErrorType.CONTENT_POLICY]: string;
+  [AIErrorType.SERVER]: string;
+  [AIErrorType.TIMEOUT]: string;
+  [AIErrorType.UNKNOWN]: string;
+}

package/src/core/types/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core Types Index
+ * @module @umituz/react-native-ai-generation-content/core
+ */
+
+export * from "./result.types";
+export * from "./error.types";
+export * from "./provider.types";

package/src/core/types/provider.types.ts

@@ -0,0 +1,201 @@
+/**
+ * AI Provider Types
+ * Core interfaces for AI generation providers
+ *
+ * @module @umituz/react-native-ai-generation-content/core
+ */
+
+// =============================================================================
+// Feature Types
+// =============================================================================
+
+/**
+ * Feature types for image processing (output: image)
+ */
+export type ImageFeatureType =
+  | "upscale"
+  | "photo-restore"
+  | "face-swap"
+  | "anime-selfie"
+  | "remove-background"
+  | "remove-object"
+  | "hd-touch-up"
+  | "replace-background";
+
+/**
+ * Feature types for video generation (output: video)
+ */
+export type VideoFeatureType = "image-to-video" | "text-to-video";
+
+// =============================================================================
+// Provider Configuration
+// =============================================================================
+
+export interface AIProviderConfig {
+  apiKey: string;
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  defaultTimeoutMs?: number;
+  textModel?: string;
+  textToImageModel?: string;
+  imageEditModel?: string;
+  videoGenerationModel?: string;
+  videoFeatureModels?: Partial<Record<VideoFeatureType, string>>;
+  imageFeatureModels?: Partial<Record<ImageFeatureType, string>>;
+}
+
+// =============================================================================
+// Status Types
+// =============================================================================
+
+export type AIJobStatusType =
+  | "IN_QUEUE"
+  | "IN_PROGRESS"
+  | "COMPLETED"
+  | "FAILED";
+
+export interface AILogEntry {
+  message: string;
+  level: "info" | "warn" | "error";
+  timestamp?: string;
+}
+
+export interface JobSubmission {
+  requestId: string;
+  statusUrl?: string;
+  responseUrl?: string;
+}
+
+export interface JobStatus {
+  status: AIJobStatusType;
+  logs?: AILogEntry[];
+  queuePosition?: number;
+  eta?: number;
+}
+
+// =============================================================================
+// Progress & Options
+// =============================================================================
+
+export interface ProviderProgressInfo {
+  progress: number;
+  status?: AIJobStatusType;
+  message?: string;
+  estimatedTimeRemaining?: number;
+}
+
+export interface SubscribeOptions<T = unknown> {
+  timeoutMs?: number;
+  onQueueUpdate?: (status: JobStatus) => void;
+  onProgress?: (progress: ProviderProgressInfo) => void;
+  onResult?: (result: T) => void;
+}
+
+export interface RunOptions {
+  onProgress?: (progress: ProviderProgressInfo) => void;
+}
+
+// =============================================================================
+// Capabilities
+// =============================================================================
+
+export interface ProviderCapabilities {
+  imageFeatures: readonly ImageFeatureType[];
+  videoFeatures: readonly VideoFeatureType[];
+  textToImage: boolean;
+  textToVideo: boolean;
+  imageToVideo: boolean;
+  textToVoice: boolean;
+  textToText: boolean;
+}
+
+// =============================================================================
+// Feature Input Data
+// =============================================================================
+
+export interface ImageFeatureInputData {
+  imageBase64: string;
+  targetImageBase64?: string;
+  prompt?: string;
+  options?: Record<string, unknown>;
+}
+
+export interface VideoFeatureInputData {
+  sourceImageBase64?: string;
+  targetImageBase64?: string;
+  prompt?: string;
+  options?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Provider Sub-Interfaces (Interface Segregation Principle)
+// =============================================================================
+
+export interface IAIProviderLifecycle {
+  initialize(config: AIProviderConfig): void;
+  isInitialized(): boolean;
+  reset(): void;
+}
+
+export interface IAIProviderCapabilities {
+  getCapabilities(): ProviderCapabilities;
+  isFeatureSupported(feature: ImageFeatureType | VideoFeatureType): boolean;
+}
+
+export interface IAIProviderJobManager {
+  submitJob(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<JobSubmission>;
+  getJobStatus(model: string, requestId: string): Promise<JobStatus>;
+  getJobResult<T = unknown>(model: string, requestId: string): Promise<T>;
+}
+
+export interface IAIProviderExecutor {
+  subscribe<T = unknown>(
+    model: string,
+    input: Record<string, unknown>,
+    options?: SubscribeOptions<T>,
+  ): Promise<T>;
+  run<T = unknown>(
+    model: string,
+    input: Record<string, unknown>,
+    options?: RunOptions,
+  ): Promise<T>;
+}
+
+export interface IAIProviderImageFeatures {
+  getImageFeatureModel(feature: ImageFeatureType): string;
+  buildImageFeatureInput(
+    feature: ImageFeatureType,
+    data: ImageFeatureInputData,
+  ): Record<string, unknown>;
+}
+
+export interface IAIProviderVideoFeatures {
+  getVideoFeatureModel(feature: VideoFeatureType): string;
+  buildVideoFeatureInput(
+    feature: VideoFeatureType,
+    data: VideoFeatureInputData,
+  ): Record<string, unknown>;
+}
+
+// =============================================================================
+// Main Provider Interface
+// =============================================================================
+
+/**
+ * Main AI Provider Interface
+ * Composition of segregated interfaces following SOLID principles
+ */
+export interface IAIProvider
+  extends IAIProviderLifecycle,
+    IAIProviderCapabilities,
+    IAIProviderJobManager,
+    IAIProviderExecutor,
+    IAIProviderImageFeatures,
+    IAIProviderVideoFeatures {
+  readonly providerId: string;
+  readonly providerName: string;
+}

package/src/core/types/result.types.ts

@@ -0,0 +1,102 @@
+/**
+ * Result Type Pattern for Functional Error Handling
+ * Inspired by Rust's Result<T, E> type
+ *
+ * @module @umituz/react-native-ai-generation-content/core
+ */
+
+/**
+ * Success result containing a value of type T
+ */
+export interface Success<T> {
+  success: true;
+  value: T;
+}
+
+/**
+ * Failure result containing an error of type E
+ */
+export interface Failure<E> {
+  success: false;
+  error: E;
+}
+
+/**
+ * Result type that can be either Success or Failure
+ * Forces explicit error handling at compile time
+ */
+export type Result<T, E = string> = Success<T> | Failure<E>;
+
+/**
+ * Create a successful result
+ */
+export function success<T>(value: T): Success<T> {
+  return { success: true, value };
+}
+
+/**
+ * Create a failed result
+ */
+export function failure<E>(error: E): Failure<E> {
+  return { success: false, error };
+}
+
+/**
+ * Type guard to check if result is successful
+ */
+export function isSuccess<T, E>(result: Result<T, E>): result is Success<T> {
+  return result.success === true;
+}
+
+/**
+ * Type guard to check if result is a failure
+ */
+export function isFailure<T, E>(result: Result<T, E>): result is Failure<E> {
+  return result.success === false;
+}
+
+/**
+ * Map a successful result to a new value
+ */
+export function mapResult<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => U,
+): Result<U, E> {
+  if (isSuccess(result)) {
+    return success(fn(result.value));
+  }
+  return result;
+}
+
+/**
+ * Chain async operations on Result types
+ */
+export async function andThen<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => Promise<Result<U, E>>,
+): Promise<Result<U, E>> {
+  if (isSuccess(result)) {
+    return fn(result.value);
+  }
+  return result;
+}
+
+/**
+ * Unwrap a result, throwing if it's a failure
+ */
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (isSuccess(result)) {
+    return result.value;
+  }
+  throw new Error(`Called unwrap on a failure: ${String(result.error)}`);
+}
+
+/**
+ * Unwrap a result or return a default value
+ */
+export function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T {
+  if (isSuccess(result)) {
+    return result.value;
+  }
+  return defaultValue;
+}

package/src/infrastructure/services/video-feature-executor.service.ts

@@ -4,137 +4,53 @@
  * Output: video URL
  */
 
-import { providerRegistry } from "./provider-registry.service";
-import { cleanBase64, extractErrorMessage, checkFalApiError } from "../utils";
+import { extractErrorMessage, checkFalApiError, validateProvider, prepareVideoInputData } from "../utils";
 import { extractVideoResult } from "../utils/url-extractor";
 import { VIDEO_TIMEOUT_MS } from "../constants";
-import type { VideoFeatureType, VideoFeatureInputData } from "../../domain/interfaces";
-import type {
-  ExecuteVideoFeatureOptions,
-  VideoFeatureResult,
-  VideoFeatureRequest,
-} from "./video-feature-executor.types";
+import type { VideoFeatureType } from "../../domain/interfaces";
+import type { ExecuteVideoFeatureOptions, VideoFeatureResult, VideoFeatureRequest } from "./video-feature-executor.types";
 
 declare const __DEV__: boolean;
 
 /**
  * Execute any video feature using the active provider
- * Uses subscribe for video features to handle long-running generation with progress updates
  */
 export async function executeVideoFeature(
   featureType: VideoFeatureType,
   request: VideoFeatureRequest,
   options?: ExecuteVideoFeatureOptions,
 ): Promise<VideoFeatureResult> {
-  if (__DEV__) {
-    console.log(`[VideoExecutor:${featureType}] START`, {
-      hasSource: !!request.sourceImageBase64,
-      hasTarget: !!request.targetImageBase64,
-      promptLength: request.prompt?.length ?? 0,
-      options: request.options,
-    });
-  }
-
-  const provider = providerRegistry.getActiveProvider();
-
-  if (!provider) {
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] ERROR: No provider`);
-    }
-    return { success: false, error: "No AI provider configured" };
-  }
-
-  if (!provider.isInitialized()) {
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] ERROR: Provider not initialized`);
-    }
-    return { success: false, error: "AI provider not initialized" };
+  const validation = validateProvider(`VideoExecutor:${featureType}`);
+  if (!validation.success) {
+    return { success: false, error: validation.error };
   }
 
+  const { provider } = validation;
   const { extractResult, onStatusChange } = options ?? {};
-
   const model = provider.getVideoFeatureModel(featureType);
 
-  if (__DEV__) {
-    console.log(`[VideoExecutor:${featureType}] Provider: ${provider.providerId}, Model: ${model}`);
-  }
-
   try {
-    const inputData: VideoFeatureInputData = {
-      sourceImageBase64: cleanBase64(request.sourceImageBase64),
-      targetImageBase64: cleanBase64(request.targetImageBase64),
-      prompt: request.prompt,
-      options: request.options,
-    };
-
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] InputData prepared`, {
-        sourceSize: inputData.sourceImageBase64 ? `${(inputData.sourceImageBase64.length / 1024).toFixed(1)}KB` : "N/A",
-        targetSize: inputData.targetImageBase64 ? `${(inputData.targetImageBase64.length / 1024).toFixed(1)}KB` : "N/A",
-        prompt: inputData.prompt?.substring(0, 50) + "...",
-      });
-    }
-
+    const inputData = prepareVideoInputData(
+      request.sourceImageBase64,
+      request.targetImageBase64,
+      request.prompt,
+      request.options,
+    );
     const input = provider.buildVideoFeatureInput(featureType, inputData);
 
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] Built input for API`, {
-        inputKeys: Object.keys(input),
-        hasImageUrl: !!(input as Record<string, unknown>).image_url,
-        hasPrompt: !!(input as Record<string, unknown>).prompt,
-      });
-    }
-
-    let statusCount = 0;
     const result = await provider.subscribe(model, input, {
       timeoutMs: VIDEO_TIMEOUT_MS,
-      onQueueUpdate: (status) => {
-        statusCount++;
-        // Log every 10th status update to avoid spam
-        if (__DEV__ && statusCount % 10 === 1) {
-          console.log(`[VideoExecutor:${featureType}] Queue #${statusCount}:`, status.status);
-        }
-        onStatusChange?.(status.status);
-      },
+      onQueueUpdate: (status) => onStatusChange?.(status.status),
     });
 
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] API Response received`, {
-        totalStatusUpdates: statusCount,
-        resultKeys: result ? Object.keys(result as object) : "null",
-        resultType: typeof result,
-      });
-    }
-
-    // Check for FAL API error in result (may return with COMPLETED status)
     checkFalApiError(result);
 
-    const extractor = extractResult ?? extractVideoResult;
-    const videoUrl = extractor(result);
-
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] Extracted video URL`, {
-        hasVideoUrl: !!videoUrl,
-        urlPreview: videoUrl ? videoUrl.substring(0, 80) + "..." : "N/A",
-      });
-    }
+    const videoUrl = (extractResult ?? extractVideoResult)(result);
 
     if (!videoUrl) {
-      if (__DEV__) {
-        console.log(`[VideoExecutor:${featureType}] FAILED: No video URL`, {
-          result: JSON.stringify(result).substring(0, 500),
-        });
-      }
       return { success: false, error: "No video in response" };
     }
 
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] SUCCESS`, {
-        videoUrl: videoUrl.substring(0, 80) + "...",
-        requestId: (result as { requestId?: string })?.requestId,
-      });
-    }
-
     return {
       success: true,
       videoUrl,
@@ -142,12 +58,6 @@ export async function executeVideoFeature(
     };
   } catch (error) {
     const message = extractErrorMessage(error, "Processing failed", `Video:${featureType}`);
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] EXCEPTION`, {
-        error: message,
-        originalError: error instanceof Error ? error.message : String(error),
-      });
-    }
     return { success: false, error: message };
   }
 }
@@ -156,67 +66,38 @@ export async function executeVideoFeature(
  * Check if video features are supported
  */
 export function hasVideoFeatureSupport(): boolean {
-  const provider = providerRegistry.getActiveProvider();
-  return provider !== null && provider.isInitialized();
+  const validation = validateProvider("VideoFeatureSupport");
+  return validation.success;
 }
 
 /**
  * Submit a video feature to the queue for background processing
- * Returns immediately with requestId and model for later status polling
  */
 export async function submitVideoFeatureToQueue(
   featureType: VideoFeatureType,
   request: VideoFeatureRequest,
 ): Promise<{ success: boolean; requestId?: string; model?: string; error?: string }> {
-  if (__DEV__) {
-    console.log(`[VideoExecutor:${featureType}] QUEUE SUBMIT`, {
-      hasSource: !!request.sourceImageBase64,
-      hasTarget: !!request.targetImageBase64,
-      promptLength: request.prompt?.length ?? 0,
-    });
-  }
-
-  const provider = providerRegistry.getActiveProvider();
-
-  if (!provider) {
-    return { success: false, error: "No AI provider configured" };
-  }
-
-  if (!provider.isInitialized()) {
-    return { success: false, error: "AI provider not initialized" };
+  const validation = validateProvider(`VideoExecutor:${featureType}`);
+  if (!validation.success) {
+    return { success: false, error: validation.error };
   }
 
+  const { provider } = validation;
   const model = provider.getVideoFeatureModel(featureType);
 
   try {
-    const inputData: VideoFeatureInputData = {
-      sourceImageBase64: cleanBase64(request.sourceImageBase64),
-      targetImageBase64: cleanBase64(request.targetImageBase64),
-      prompt: request.prompt,
-      options: request.options,
-    };
-
+    const inputData = prepareVideoInputData(
+      request.sourceImageBase64,
+      request.targetImageBase64,
+      request.prompt,
+      request.options,
+    );
     const input = provider.buildVideoFeatureInput(featureType, inputData);
-
     const submission = await provider.submitJob(model, input);
 
-    if (__DEV__) {
-      console.log(`[VideoExecutor:${featureType}] QUEUE SUBMITTED`, {
-        requestId: submission.requestId,
-        model,
-      });
-    }
-
-    return {
-      success: true,
-      requestId: submission.requestId,
-      model,
-    };
+    return { success: true, requestId: submission.requestId, model };
   } catch (error) {
     const message = extractErrorMessage(error, "Queue submission failed", `Video:${featureType}`);
-    if (__DEV__) {
-      console.error(`[VideoExecutor:${featureType}] QUEUE EXCEPTION`, { error: message });
-    }
     return { success: false, error: message };
   }
 }

package/src/infrastructure/utils/index.ts

@@ -13,3 +13,4 @@ export * from "./photo-generation";
 export * from "./feature-utils";
 export * from "./video-helpers";
 export * from "./media-actions.util";
+export * from "./provider-validator.util";

package/src/infrastructure/utils/provider-validator.util.ts

@@ -0,0 +1,71 @@
+/**
+ * Provider Validator Utility
+ * Validates provider state and prepares feature inputs
+ */
+
+import { providerRegistry } from "../services/provider-registry.service";
+import { cleanBase64 } from "./index";
+import type { IAIProvider, VideoFeatureInputData, ImageFeatureInputData } from "../../domain/interfaces";
+
+declare const __DEV__: boolean;
+
+export type ProviderValidationResult =
+  | { success: true; provider: IAIProvider }
+  | { success: false; error: string };
+
+/**
+ * Validate provider is available and initialized
+ */
+export function validateProvider(context: string): ProviderValidationResult {
+  const provider = providerRegistry.getActiveProvider();
+
+  if (!provider) {
+    if (__DEV__) {
+      console.log(`[${context}] ERROR: No provider`);
+    }
+    return { success: false, error: "No AI provider configured" };
+  }
+
+  if (!provider.isInitialized()) {
+    if (__DEV__) {
+      console.log(`[${context}] ERROR: Provider not initialized`);
+    }
+    return { success: false, error: "AI provider not initialized" };
+  }
+
+  return { success: true, provider };
+}
+
+/**
+ * Prepare video feature input data
+ */
+export function prepareVideoInputData(
+  sourceImageBase64?: string,
+  targetImageBase64?: string,
+  prompt?: string,
+  options?: Record<string, unknown>,
+): VideoFeatureInputData {
+  return {
+    sourceImageBase64: cleanBase64(sourceImageBase64),
+    targetImageBase64: cleanBase64(targetImageBase64),
+    prompt,
+    options,
+  };
+}
+
+/**
+ * Prepare image feature input data
+ */
+export function prepareImageInputData(
+  imageBase64: string,
+  targetImageBase64?: string,
+  prompt?: string,
+  options?: Record<string, unknown>,
+): ImageFeatureInputData {
+  return {
+    imageBase64: cleanBase64(imageBase64) ?? "",
+    targetImageBase64: cleanBase64(targetImageBase64),
+    prompt,
+    options,
+  };
+}