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

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@umituz/react-native-ai-generation-content",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "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;
+}