@umituz/react-native-ai-generation-content 1.0.2 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-generation-content",
-  "version": "1.0.2",
+  "version": "1.0.6",
   "description": "Provider-agnostic AI generation orchestration for React Native",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -53,26 +53,50 @@ export { DEFAULT_POLLING_CONFIG, DEFAULT_PROGRESS_STAGES } from "./domain/entiti
 export {
   providerRegistry,
   generationOrchestrator,
+  pollJob,
+  createJobPoller,
 } from "./infrastructure/services";
 
-export type { OrchestratorConfig } from "./infrastructure/services";
+export type {
+  OrchestratorConfig,
+  PollJobOptions,
+  PollJobResult,
+} from "./infrastructure/services";
 
 // =============================================================================
 // INFRASTRUCTURE LAYER - Utils
 // =============================================================================
 
 export {
+  // Error classification
   classifyError,
   isTransientError,
   isPermanentError,
+  // Polling
   calculatePollingInterval,
   createPollingDelay,
+  // Progress
   getProgressForStatus,
   interpolateProgress,
   createProgressTracker,
+  // Status checking
+  checkStatusForErrors,
+  isJobComplete,
+  isJobProcessing,
+  isJobFailed,
+  // Result validation
+  validateResult,
+  extractOutputUrl,
+  extractOutputUrls,
 } from "./infrastructure/utils";
 
-export type { IntervalOptions, ProgressOptions } from "./infrastructure/utils";
+export type {
+  IntervalOptions,
+  ProgressOptions,
+  StatusCheckResult,
+  ResultValidation,
+  ValidateResultOptions,
+} from "./infrastructure/utils";
 
 // =============================================================================
 // PRESENTATION LAYER - Hooks

package/src/infrastructure/services/index.ts

@@ -5,3 +5,5 @@
 export { providerRegistry } from "./provider-registry.service";
 export { generationOrchestrator } from "./generation-orchestrator.service";
 export type { OrchestratorConfig } from "./generation-orchestrator.service";
+export { pollJob, createJobPoller } from "./job-poller.service";
+export type { PollJobOptions, PollJobResult } from "./job-poller.service";

package/src/infrastructure/services/job-poller.service.ts

@@ -0,0 +1,208 @@
+/**
+ * Job Poller Service
+ * Provider-agnostic job polling with exponential backoff
+ */
+
+import type { IAIProvider, JobStatus } from "../../domain/interfaces";
+import type { PollingConfig } from "../../domain/entities";
+import { DEFAULT_POLLING_CONFIG } from "../../domain/entities";
+import { calculatePollingInterval } from "../utils/polling-interval.util";
+import { checkStatusForErrors, isJobComplete } from "../utils/status-checker.util";
+import { validateResult } from "../utils/result-validator.util";
+import { isTransientError } from "../utils/error-classifier.util";
+
+declare const __DEV__: boolean;
+
+export interface PollJobOptions {
+  provider: IAIProvider;
+  model: string;
+  requestId: string;
+  config?: Partial<PollingConfig>;
+  onProgress?: (progress: number) => void;
+  onStatusChange?: (status: JobStatus) => void;
+  signal?: AbortSignal;
+}
+
+export interface PollJobResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: Error;
+  attempts: number;
+  elapsedMs: number;
+}
+
+const MAX_CONSECUTIVE_TRANSIENT_ERRORS = 5;
+
+/**
+ * Poll job until completion with exponential backoff
+ */
+export async function pollJob<T = unknown>(
+  options: PollJobOptions,
+): Promise<PollJobResult<T>> {
+  const {
+    provider,
+    model,
+    requestId,
+    config,
+    onProgress,
+    onStatusChange,
+    signal,
+  } = options;
+
+  const pollingConfig = { ...DEFAULT_POLLING_CONFIG, ...config };
+  const { maxAttempts } = pollingConfig;
+
+  const startTime = Date.now();
+  let consecutiveTransientErrors = 0;
+  let lastProgress = 0;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    // Check for abort
+    if (signal?.aborted) {
+      return {
+        success: false,
+        error: new Error("Polling aborted"),
+        attempts: attempt + 1,
+        elapsedMs: Date.now() - startTime,
+      };
+    }
+
+    // Wait for polling interval (skip first attempt)
+    if (attempt > 0) {
+      const interval = calculatePollingInterval({ attempt, config: pollingConfig });
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+
+    try {
+      // Get job status
+      const status = await provider.getJobStatus(model, requestId);
+      onStatusChange?.(status);
+
+      // Check for errors in status
+      const statusCheck = checkStatusForErrors(status);
+
+      if (statusCheck.shouldStop && statusCheck.hasError) {
+        return {
+          success: false,
+          error: new Error(statusCheck.errorMessage || "Job failed"),
+          attempts: attempt + 1,
+          elapsedMs: Date.now() - startTime,
+        };
+      }
+
+      // Reset transient error counter on success
+      consecutiveTransientErrors = 0;
+
+      // Update progress
+      const progress = calculateProgressFromStatus(status, attempt, maxAttempts);
+      if (progress > lastProgress) {
+        lastProgress = progress;
+        onProgress?.(progress);
+      }
+
+      // Check if complete
+      if (isJobComplete(status)) {
+        onProgress?.(90);
+
+        // Fetch result
+        const result = await provider.getJobResult<T>(model, requestId);
+
+        // Validate result
+        const validation = validateResult(result);
+        if (!validation.isValid) {
+          return {
+            success: false,
+            error: new Error(validation.errorMessage || "Invalid result"),
+            attempts: attempt + 1,
+            elapsedMs: Date.now() - startTime,
+          };
+        }
+
+        onProgress?.(100);
+
+        return {
+          success: true,
+          data: result,
+          attempts: attempt + 1,
+          elapsedMs: Date.now() - startTime,
+        };
+      }
+    } catch (error) {
+      if (isTransientError(error)) {
+        consecutiveTransientErrors++;
+
+        // Too many consecutive transient errors
+        if (consecutiveTransientErrors >= MAX_CONSECUTIVE_TRANSIENT_ERRORS) {
+          return {
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error)),
+            attempts: attempt + 1,
+            elapsedMs: Date.now() - startTime,
+          };
+        }
+
+        // Continue retrying
+        if (attempt < maxAttempts - 1) {
+          if (typeof __DEV__ !== "undefined" && __DEV__) {
+            // eslint-disable-next-line no-console
+            console.log(
+              `[JobPoller] Transient error, retrying (${attempt + 1}/${maxAttempts})`,
+            );
+          }
+          continue;
+        }
+      }
+
+      // Permanent error or max retries reached
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+        attempts: attempt + 1,
+        elapsedMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  // Max attempts reached
+  return {
+    success: false,
+    error: new Error(`Polling timeout after ${maxAttempts} attempts`),
+    attempts: maxAttempts,
+    elapsedMs: Date.now() - startTime,
+  };
+}
+
+/**
+ * Calculate progress percentage from job status
+ */
+function calculateProgressFromStatus(
+  status: JobStatus,
+  attempt: number,
+  maxAttempts: number,
+): number {
+  const statusString = String(status.status).toUpperCase();
+
+  switch (statusString) {
+    case "IN_QUEUE":
+      return 30 + Math.min(attempt * 2, 10);
+    case "IN_PROGRESS":
+      return 50 + Math.min(attempt * 3, 30);
+    case "COMPLETED":
+      return 90;
+    case "FAILED":
+      return 0;
+    default:
+      return 20 + Math.min((attempt / maxAttempts) * 30, 30);
+  }
+}
+
+/**
+ * Create a job poller with preset configuration
+ */
+export function createJobPoller(defaultConfig?: Partial<PollingConfig>) {
+  return {
+    poll<T = unknown>(options: Omit<PollJobOptions, "config">) {
+      return pollJob<T>({ ...options, config: defaultConfig });
+    },
+  };
+}

package/src/infrastructure/utils/index.ts

@@ -5,3 +5,5 @@
 export * from "./error-classifier.util";
 export * from "./polling-interval.util";
 export * from "./progress-calculator.util";
+export * from "./status-checker.util";
+export * from "./result-validator.util";

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

@@ -0,0 +1,218 @@
+/**
+ * Result Validator Utility
+ * Validates AI generation job results
+ */
+
+export interface ResultValidation {
+  isValid: boolean;
+  hasError: boolean;
+  errorMessage?: string;
+  hasOutput: boolean;
+}
+
+export interface ValidateResultOptions {
+  /** Custom output field names to check */
+  outputFields?: string[];
+  /** Whether empty results are allowed */
+  allowEmpty?: boolean;
+}
+
+const DEFAULT_OUTPUT_FIELDS = [
+  "data",
+  "output",
+  "image",
+  "image_url",
+  "images",
+  "video",
+  "video_url",
+  "url",
+  "result",
+  "text",
+  "content",
+];
+
+/**
+ * Validate job result and detect errors
+ * Checks for error fields even if job status was COMPLETED
+ */
+export function validateResult(
+  result: unknown,
+  options?: ValidateResultOptions,
+): ResultValidation {
+  const { outputFields = DEFAULT_OUTPUT_FIELDS, allowEmpty = false } =
+    options ?? {};
+
+  // Handle null/undefined
+  if (result === null || result === undefined) {
+    return {
+      isValid: allowEmpty,
+      hasError: !allowEmpty,
+      errorMessage: allowEmpty ? undefined : "Result is empty",
+      hasOutput: false,
+    };
+  }
+
+  // Handle non-object results
+  if (typeof result !== "object") {
+    return {
+      isValid: true,
+      hasError: false,
+      hasOutput: true,
+    };
+  }
+
+  const resultObj = result as Record<string, unknown>;
+
+  // Check for error fields
+  const errorValue = resultObj.error || resultObj.detail;
+  const errorString = errorValue ? String(errorValue).toLowerCase() : "";
+
+  const hasInternalServerError =
+    errorString.includes("internal server error") ||
+    errorString.includes("500") ||
+    errorString === "internal server error";
+
+  // Check for empty object
+  const isEmpty = Object.keys(resultObj).length === 0;
+
+  // Check for output in expected fields
+  const hasOutput = outputFields.some((field) => {
+    const value = resultObj[field];
+    if (!value) return false;
+
+    // Handle nested output structures
+    if (typeof value === "object" && value !== null) {
+      const nested = value as Record<string, unknown>;
+      return !!(
+        nested.url ||
+        nested.image_url ||
+        nested.video_url ||
+        Object.keys(nested).length > 0
+      );
+    }
+
+    return true;
+  });
+
+  // Determine if result has error
+  const hasError =
+    hasInternalServerError || (isEmpty && !hasOutput && !allowEmpty);
+
+  return {
+    isValid: !hasError && (hasOutput || allowEmpty),
+    hasError,
+    errorMessage: hasError && errorValue ? String(errorValue) : undefined,
+    hasOutput,
+  };
+}
+
+/**
+ * Extract output URL from result
+ * Supports various AI provider response formats
+ */
+export function extractOutputUrl(
+  result: unknown,
+  urlFields?: string[],
+): string | undefined {
+  if (!result || typeof result !== "object") {
+    return undefined;
+  }
+
+  const fields = urlFields ?? [
+    "url",
+    "image_url",
+    "video_url",
+    "output_url",
+    "result_url",
+  ];
+
+  const resultObj = result as Record<string, unknown>;
+
+  // Check top-level fields
+  for (const field of fields) {
+    const value = resultObj[field];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  // Check nested data/output objects
+  const nested =
+    (resultObj.data as Record<string, unknown>) ||
+    (resultObj.output as Record<string, unknown>) ||
+    (resultObj.result as Record<string, unknown>);
+
+  if (nested && typeof nested === "object") {
+    for (const field of fields) {
+      const value = nested[field];
+      if (typeof value === "string" && value.length > 0) {
+        return value;
+      }
+    }
+
+    // Check for nested image/video objects
+    const media =
+      (nested.image as Record<string, unknown>) ||
+      (nested.video as Record<string, unknown>);
+    if (media && typeof media === "object" && typeof media.url === "string") {
+      return media.url;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract multiple output URLs from result
+ */
+export function extractOutputUrls(
+  result: unknown,
+  urlFields?: string[],
+): string[] {
+  if (!result || typeof result !== "object") {
+    return [];
+  }
+
+  const urls: string[] = [];
+  const resultObj = result as Record<string, unknown>;
+
+  // Check for arrays
+  const arrayFields = ["images", "videos", "outputs", "results", "urls"];
+  for (const field of arrayFields) {
+    const arr = resultObj[field];
+    if (Array.isArray(arr)) {
+      for (const item of arr) {
+        const url = extractOutputUrl(item, urlFields);
+        if (url) {
+          urls.push(url);
+        }
+      }
+    }
+  }
+
+  // Check nested data/output
+  const nested = resultObj.data || resultObj.output;
+  if (nested && typeof nested === "object") {
+    for (const field of arrayFields) {
+      const arr = (nested as Record<string, unknown>)[field];
+      if (Array.isArray(arr)) {
+        for (const item of arr) {
+          const url = extractOutputUrl(item, urlFields);
+          if (url) {
+            urls.push(url);
+          }
+        }
+      }
+    }
+  }
+
+  // If no array found, try single URL
+  if (urls.length === 0) {
+    const singleUrl = extractOutputUrl(result, urlFields);
+    if (singleUrl) {
+      urls.push(singleUrl);
+    }
+  }
+
+  return urls;
+}

package/src/infrastructure/utils/status-checker.util.ts

@@ -0,0 +1,101 @@
+/**
+ * Status Checker Utility
+ * Checks job status responses for errors
+ */
+
+import type { JobStatus, AILogEntry } from "../../domain/interfaces";
+
+export interface StatusCheckResult {
+  status: string;
+  hasError: boolean;
+  errorMessage?: string;
+  shouldStop: boolean;
+}
+
+/**
+ * Check job status response for errors
+ * Detects errors even if status is not explicitly FAILED
+ */
+export function checkStatusForErrors(
+  status: JobStatus | Record<string, unknown>,
+): StatusCheckResult {
+  const statusString = String(
+    (status as Record<string, unknown>)?.status || "",
+  ).toUpperCase();
+
+  // Check for error in status response fields
+  const statusError =
+    (status as Record<string, unknown>)?.error ||
+    (status as Record<string, unknown>)?.detail ||
+    (status as Record<string, unknown>)?.message;
+  const hasStatusError = !!statusError;
+
+  // Check logs array for ERROR/FATAL level logs
+  const logs = Array.isArray((status as JobStatus)?.logs)
+    ? (status as JobStatus).logs
+    : [];
+  const errorLogs = (logs as AILogEntry[]).filter((log) => {
+    const level = String(log?.level || "").toUpperCase();
+    return level === "ERROR" || level === "FATAL";
+  });
+  const hasErrorLog = errorLogs.length > 0;
+
+  // Extract error message from logs
+  const errorLogMessage =
+    errorLogs.length > 0
+      ? (errorLogs[0] as AILogEntry & { text?: string; content?: string })
+          ?.message ||
+        (errorLogs[0] as AILogEntry & { text?: string })?.text ||
+        (errorLogs[0] as AILogEntry & { content?: string })?.content
+      : undefined;
+
+  // Combine error messages
+  const errorMessage = statusError || errorLogMessage;
+
+  // Determine if we should stop immediately
+  const shouldStop =
+    statusString === "FAILED" || hasStatusError || hasErrorLog;
+
+  return {
+    status: statusString,
+    hasError: hasStatusError || hasErrorLog,
+    errorMessage: errorMessage ? String(errorMessage) : undefined,
+    shouldStop,
+  };
+}
+
+/**
+ * Check if status indicates job is complete
+ */
+export function isJobComplete(status: JobStatus | string): boolean {
+  const statusString =
+    typeof status === "string"
+      ? status.toUpperCase()
+      : String(status?.status || "").toUpperCase();
+
+  return statusString === "COMPLETED";
+}
+
+/**
+ * Check if status indicates job is still processing
+ */
+export function isJobProcessing(status: JobStatus | string): boolean {
+  const statusString =
+    typeof status === "string"
+      ? status.toUpperCase()
+      : String(status?.status || "").toUpperCase();
+
+  return statusString === "IN_QUEUE" || statusString === "IN_PROGRESS";
+}
+
+/**
+ * Check if status indicates job has failed
+ */
+export function isJobFailed(status: JobStatus | string): boolean {
+  const statusString =
+    typeof status === "string"
+      ? status.toUpperCase()
+      : String(status?.status || "").toUpperCase();
+
+  return statusString === "FAILED";
+}