@umituz/react-native-ai-pruna-provider 1.0.0

package/src/infrastructure/services/request-store.ts

@@ -0,0 +1,148 @@
+/**
+ * Request Store - Promise Deduplication with globalThis
+ * Survives hot reloads for React Native development
+ *
+ * React Native is single-threaded - no lock mechanism needed.
+ * Direct Map operations are atomic in JS event loop.
+ */
+
+export interface ActiveRequest<T = unknown> {
+  promise: Promise<T>;
+  abortController: AbortController;
+  createdAt: number;
+}
+
+const STORE_KEY = "__PRUNA_PROVIDER_REQUESTS__";
+const TIMER_KEY = "__PRUNA_PROVIDER_CLEANUP_TIMER__";
+type RequestStore = Map<string, ActiveRequest>;
+
+const CLEANUP_INTERVAL = 60000;
+const MAX_REQUEST_AGE = 300000;
+
+function getCleanupTimer(): ReturnType<typeof setInterval> | null {
+  const globalObj = globalThis as Record<string, unknown>;
+  return (globalObj[TIMER_KEY] as ReturnType<typeof setInterval>) ?? null;
+}
+
+function setCleanupTimer(timer: ReturnType<typeof setInterval> | null): void {
+  const globalObj = globalThis as Record<string, unknown>;
+  globalObj[TIMER_KEY] = timer;
+}
+
+export function getRequestStore(): RequestStore {
+  const globalObj = globalThis as Record<string, unknown>;
+  if (!globalObj[STORE_KEY]) {
+    globalObj[STORE_KEY] = new Map();
+  }
+  return globalObj[STORE_KEY] as RequestStore;
+}
+
+function sortKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortKeys);
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeys((obj as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+export function createRequestKey(model: string, input: Record<string, unknown>): string {
+  const inputStr = JSON.stringify(sortKeys(input));
+  let hash = 0;
+  for (let i = 0; i < inputStr.length; i++) {
+    const char = inputStr.charCodeAt(i);
+    hash = ((hash << 5) - hash + char) | 0;
+  }
+  return `${model}:${hash.toString(36)}`;
+}
+
+export function getExistingRequest<T>(key: string): ActiveRequest<T> | undefined {
+  return getRequestStore().get(key) as ActiveRequest<T> | undefined;
+}
+
+export function storeRequest<T>(key: string, request: ActiveRequest<T>): void {
+  getRequestStore().set(key, {
+    ...request,
+    createdAt: request.createdAt ?? Date.now(),
+  });
+  ensureCleanupRunning();
+}
+
+export function removeRequest(key: string): void {
+  getRequestStore().delete(key);
+}
+
+export function cancelRequest(key: string): void {
+  const store = getRequestStore();
+  const req = store.get(key);
+  if (req) {
+    req.abortController.abort();
+    store.delete(key);
+    if (store.size === 0) stopCleanupTimer();
+  }
+}
+
+export function cancelAllRequests(): void {
+  const store = getRequestStore();
+  store.forEach((req) => {
+    req.abortController.abort();
+  });
+  store.clear();
+  stopCleanupTimer();
+}
+
+export function hasActiveRequests(): boolean {
+  return getRequestStore().size > 0;
+}
+
+export function cleanupRequestStore(maxAge: number = MAX_REQUEST_AGE): number {
+  const store = getRequestStore();
+  const now = Date.now();
+  let cleanedCount = 0;
+
+  for (const [key, request] of store.entries()) {
+    if (now - request.createdAt > maxAge) {
+      request.abortController.abort();
+      store.delete(key);
+      cleanedCount++;
+    }
+  }
+
+  if (store.size === 0) {
+    stopCleanupTimer();
+  }
+
+  return cleanedCount;
+}
+
+function ensureCleanupRunning(): void {
+  if (getCleanupTimer()) return;
+
+  const timer = setInterval(() => {
+    cleanupRequestStore(MAX_REQUEST_AGE);
+  }, CLEANUP_INTERVAL);
+
+  setCleanupTimer(timer);
+}
+
+function stopCleanupTimer(): void {
+  const timer = getCleanupTimer();
+  if (timer) {
+    clearInterval(timer);
+    setCleanupTimer(null);
+  }
+}
+
+export function stopAutomaticCleanup(): void {
+  stopCleanupTimer();
+}
+
+// Clear any leftover timer on module load (hot reload safety)
+if (typeof globalThis !== "undefined") {
+  const existingTimer = getCleanupTimer();
+  if (existingTimer) {
+    clearInterval(existingTimer);
+    setCleanupTimer(null);
+  }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Helpers Index
+ */
+
+export function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined;
+}
+
+export function removeNullish<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const result: Partial<T> = {};
+  for (const key of Object.keys(obj) as (keyof T)[]) {
+    if (obj[key] !== null && obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+export function generateUniqueId(prefix = 'pruna'): string {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/infrastructure/utils/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Utils Index
+ */
+
+export {
+  mapPrunaError,
+  isPrunaErrorRetryable,
+  getErrorMessage,
+  getErrorMessageOr,
+  formatErrorMessage,
+} from "./pruna-error-handler.util";
+
+export {
+  isPrunaModelId,
+  isPrunaErrorType,
+  isValidApiKey,
+  isValidModelId,
+  isValidPrompt,
+  isValidTimeout,
+} from "./type-guards";
+
+export {
+  isDefined,
+  removeNullish,
+  generateUniqueId,
+  sleep,
+} from "./helpers";
+
+export { generationLogCollector } from "./log-collector";
+export type { LogEntry } from "./log-collector";

package/src/infrastructure/utils/log-collector.ts

@@ -0,0 +1,96 @@
+/**
+ * Generation Log Collector
+ * Session-scoped log collection — each generation gets its own isolated session.
+ * Supports concurrent generations without data corruption.
+ *
+ * Usage:
+ *   const sessionId = collector.startSession();
+ *   collector.log(sessionId, 'tag', 'message');
+ *   const entries = collector.endSession(sessionId);
+ */
+
+export interface LogEntry {
+  readonly timestamp: number;
+  readonly elapsed: number;
+  readonly level: 'info' | 'warn' | 'error';
+  readonly tag: string;
+  readonly message: string;
+  readonly data?: Record<string, unknown>;
+}
+
+interface Session {
+  readonly startTime: number;
+  entries: LogEntry[];
+}
+
+let sessionCounter = 0;
+
+class GenerationLogCollector {
+  private sessions = new Map<string, Session>();
+
+  startSession(): string {
+    const id = `pruna_session_${++sessionCounter}_${Date.now()}`;
+    this.sessions.set(id, { startTime: Date.now(), entries: [] });
+    return id;
+  }
+
+  log(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'info', tag, message, data);
+  }
+
+  warn(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'warn', tag, message, data);
+  }
+
+  error(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'error', tag, message, data);
+  }
+
+  getEntries(sessionId: string): LogEntry[] {
+    return [...(this.sessions.get(sessionId)?.entries ?? [])];
+  }
+
+  endSession(sessionId: string): LogEntry[] {
+    const session = this.sessions.get(sessionId);
+    if (!session) return [];
+    const entries = [...session.entries];
+    this.sessions.delete(sessionId);
+    return entries;
+  }
+
+  private addEntry(
+    sessionId: string,
+    level: LogEntry['level'],
+    tag: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      this.consoleOutput(level, tag, message, data);
+      return;
+    }
+
+    const now = Date.now();
+    session.entries.push({
+      timestamp: now,
+      elapsed: now - session.startTime,
+      level,
+      tag,
+      message,
+      ...(data && { data }),
+    });
+
+    this.consoleOutput(level, tag, message, data);
+  }
+
+  private consoleOutput(level: LogEntry['level'], tag: string, message: string, data?: Record<string, unknown>): void {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      const fn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
+      fn(`[${tag}] ${message}`, data ?? '');
+    }
+  }
+}
+
+/** Module-level singleton — safe for concurrent sessions via session IDs */
+export const generationLogCollector = new GenerationLogCollector();

package/src/infrastructure/utils/pruna-error-handler.util.ts

@@ -0,0 +1,119 @@
+/**
+ * Pruna Error Handler
+ * Maps raw errors to typed PrunaErrorInfo with retryable classification
+ */
+
+import { PrunaErrorType } from "../../domain/entities/error.types";
+import type { PrunaErrorInfo } from "../../domain/entities/error.types";
+
+/**
+ * Map an error to a typed PrunaErrorInfo
+ */
+export function mapPrunaError(error: unknown): PrunaErrorInfo {
+  const originalError = getErrorMessage(error);
+  const originalErrorName = error instanceof Error ? error.name : undefined;
+  const stack = error instanceof Error ? error.stack : undefined;
+  const statusCode = (error as Error & { statusCode?: number }).statusCode;
+
+  // HTTP status code mapping
+  if (statusCode !== undefined) {
+    return mapStatusCode(statusCode, originalError, originalErrorName, stack);
+  }
+
+  // Message pattern matching
+  const msg = originalError.toLowerCase();
+
+  if (msg.includes("network") || msg.includes("fetch") || msg.includes("econnrefused") || msg.includes("enotfound")) {
+    return buildErrorInfo(PrunaErrorType.NETWORK, "error.pruna.network", true, originalError, originalErrorName, stack);
+  }
+
+  if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("polling attempts reached")) {
+    return buildErrorInfo(PrunaErrorType.POLLING_TIMEOUT, "error.pruna.polling_timeout", true, originalError, originalErrorName, stack);
+  }
+
+  if (msg.includes("file upload")) {
+    return buildErrorInfo(PrunaErrorType.FILE_UPLOAD, "error.pruna.file_upload", true, originalError, originalErrorName, stack);
+  }
+
+  if (msg.includes("invalid image") || msg.includes("invalid character")) {
+    return buildErrorInfo(PrunaErrorType.INVALID_IMAGE, "error.pruna.invalid_image", false, originalError, originalErrorName, stack);
+  }
+
+  if (msg.includes("cancelled by user")) {
+    return buildErrorInfo(PrunaErrorType.UNKNOWN, "error.pruna.cancelled", false, originalError, originalErrorName, stack);
+  }
+
+  if (msg.includes("prompt is required") || msg.includes("image is required")) {
+    return buildErrorInfo(PrunaErrorType.VALIDATION, "error.pruna.validation", false, originalError, originalErrorName, stack);
+  }
+
+  return buildErrorInfo(PrunaErrorType.UNKNOWN, "error.pruna.unknown", false, originalError, originalErrorName, stack);
+}
+
+function mapStatusCode(
+  statusCode: number,
+  originalError: string,
+  originalErrorName: string | undefined,
+  stack: string | undefined,
+): PrunaErrorInfo {
+  if (statusCode === 400 || statusCode === 422) {
+    return buildErrorInfo(PrunaErrorType.VALIDATION, "error.pruna.validation", false, originalError, originalErrorName, stack, statusCode);
+  }
+  if (statusCode === 401 || statusCode === 403) {
+    return buildErrorInfo(PrunaErrorType.AUTHENTICATION, "error.pruna.authentication", false, originalError, originalErrorName, stack, statusCode);
+  }
+  if (statusCode === 402) {
+    return buildErrorInfo(PrunaErrorType.QUOTA_EXCEEDED, "error.pruna.quota_exceeded", false, originalError, originalErrorName, stack, statusCode);
+  }
+  if (statusCode === 404) {
+    return buildErrorInfo(PrunaErrorType.MODEL_NOT_FOUND, "error.pruna.model_not_found", false, originalError, originalErrorName, stack, statusCode);
+  }
+  if (statusCode === 429) {
+    return buildErrorInfo(PrunaErrorType.RATE_LIMIT, "error.pruna.rate_limit", true, originalError, originalErrorName, stack, statusCode);
+  }
+  if (statusCode >= 500 && statusCode <= 504) {
+    return buildErrorInfo(PrunaErrorType.API_ERROR, "error.pruna.api_error", true, originalError, originalErrorName, stack, statusCode);
+  }
+
+  return buildErrorInfo(PrunaErrorType.UNKNOWN, "error.pruna.unknown", false, originalError, originalErrorName, stack, statusCode);
+}
+
+function buildErrorInfo(
+  type: PrunaErrorType,
+  messageKey: string,
+  retryable: boolean,
+  originalError: string,
+  originalErrorName: string | undefined,
+  stack: string | undefined,
+  statusCode?: number,
+): PrunaErrorInfo {
+  return {
+    type,
+    messageKey,
+    retryable,
+    originalError,
+    ...(originalErrorName && { originalErrorName }),
+    ...(stack && { stack }),
+    ...(statusCode !== undefined && { statusCode }),
+  };
+}
+
+export function isPrunaErrorRetryable(error: PrunaErrorInfo): boolean {
+  return error.retryable;
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return String(error);
+}
+
+export function getErrorMessageOr(error: unknown, fallback: string): string {
+  const msg = getErrorMessage(error);
+  return msg || fallback;
+}
+
+export function formatErrorMessage(error: unknown, context: string): string {
+  const msg = getErrorMessage(error);
+  return `[${context}] ${msg}`;
+}

package/src/infrastructure/utils/pruna-generation-state-manager.util.ts

@@ -0,0 +1,98 @@
+/**
+ * Pruna Generation State Manager
+ * Manages state and refs for Pruna generation operations
+ */
+
+import type { PrunaJobInput, PrunaLogEntry, PrunaQueueStatus } from "../../domain/entities/pruna.types";
+
+export interface GenerationState<T> {
+  data: T | null;
+  error: Error | null;
+  isLoading: boolean;
+  isCancelling: boolean;
+  requestId: string | null;
+  lastRequest: { endpoint: string; input: PrunaJobInput } | null;
+}
+
+export interface GenerationStateOptions<T> {
+  onQueueUpdate?: (status: PrunaQueueStatus) => void;
+  onProgress?: (status: PrunaQueueStatus) => void;
+  onError?: (error: Error) => void;
+  onResult?: (result: T) => void;
+}
+
+export class PrunaGenerationStateManager<T> {
+  private isMounted = true;
+  private currentRequestId: string | null = null;
+  private lastRequest: { endpoint: string; input: PrunaJobInput } | null = null;
+  private lastNotifiedStatus: string | null = null;
+
+  constructor(
+    private options?: GenerationStateOptions<T>
+  ) {}
+
+  setIsMounted(mounted: boolean): void {
+    this.isMounted = mounted;
+  }
+
+  checkMounted(): boolean {
+    return this.isMounted;
+  }
+
+  setCurrentRequestId(requestId: string | null): void {
+    this.currentRequestId = requestId;
+  }
+
+  getCurrentRequestId(): string | null {
+    return this.currentRequestId;
+  }
+
+  setLastRequest(endpoint: string, input: PrunaJobInput): void {
+    this.lastRequest = { endpoint, input };
+  }
+
+  getLastRequest(): { endpoint: string; input: PrunaJobInput } | null {
+    return this.lastRequest;
+  }
+
+  clearLastRequest(): void {
+    this.lastRequest = null;
+    this.currentRequestId = null;
+    this.lastNotifiedStatus = null;
+  }
+
+  handleQueueUpdate(status: PrunaQueueStatus): void {
+    if (!this.isMounted) return;
+
+    if (status.requestId) {
+      this.currentRequestId = status.requestId;
+    }
+
+    const normalizedStatus: PrunaQueueStatus = {
+      status: status.status,
+      requestId: status.requestId ?? this.currentRequestId ?? "",
+      logs: status.logs?.map((log: PrunaLogEntry) => ({
+        message: log.message,
+        level: log.level,
+        timestamp: log.timestamp,
+      })),
+    };
+
+    const statusKey = `${normalizedStatus.status}-${normalizedStatus.requestId}`;
+    if (this.lastNotifiedStatus !== statusKey) {
+      this.lastNotifiedStatus = statusKey;
+      this.options?.onQueueUpdate?.(normalizedStatus);
+      this.options?.onProgress?.(normalizedStatus);
+    }
+  }
+
+  handleResult(result: T): void {
+    if (!this.isMounted) return;
+    this.options?.onResult?.(result);
+  }
+
+  handleError(error: Error): void {
+    if (!this.isMounted) return;
+    this.options?.onError?.(error);
+  }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Type Guards Index
+ */
+
+import type { PrunaModelId } from "../../../domain/entities/pruna.types";
+import { PrunaErrorType } from "../../../domain/entities/error.types";
+import { VALID_PRUNA_MODELS } from "../../services/pruna-provider.constants";
+
+export function isPrunaModelId(value: unknown): value is PrunaModelId {
+  return typeof value === 'string' && VALID_PRUNA_MODELS.includes(value as PrunaModelId);
+}
+
+export function isPrunaErrorType(value: unknown): value is PrunaErrorType {
+  return typeof value === 'string' && Object.values(PrunaErrorType).includes(value as PrunaErrorType);
+}
+
+export function isValidApiKey(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export function isValidModelId(value: unknown): value is string {
+  return typeof value === 'string' && value.length >= 3;
+}
+
+export function isValidPrompt(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= 5000;
+}
+
+export function isValidTimeout(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 600000;
+}

package/src/init/createAiProviderInitModule.ts

@@ -0,0 +1,87 @@
+/**
+ * AI Provider Init Module Factory
+ * Creates a ready-to-use InitModule for app initialization
+ */
+
+import { providerRegistry } from '@umituz/react-native-ai-generation-content';
+import { prunaProvider } from '../infrastructure/services';
+
+/**
+ * InitModule interface (from @umituz/react-native-design-system)
+ */
+interface InitModule {
+  name: string;
+  init: () => Promise<boolean>;
+  critical?: boolean;
+  dependsOn?: string[];
+}
+
+export interface AiProviderInitModuleConfig {
+  /**
+   * Pruna AI API key getter function
+   * Returns the API key or undefined if not available
+   */
+  getApiKey: () => string | undefined;
+
+  /**
+   * Whether this module is critical for app startup
+   * @default false
+   */
+  critical?: boolean;
+
+  /**
+   * Module dependencies
+   * @default ["firebase"]
+   */
+  dependsOn?: string[];
+
+  /**
+   * Optional callback called after provider is initialized
+   */
+  onInitialized?: () => void;
+}
+
+/**
+ * Creates a Pruna AI Provider initialization module for use with createAppInitializer
+ */
+export function createAiProviderInitModule(
+  config: AiProviderInitModuleConfig
+): InitModule {
+  const {
+    getApiKey,
+    critical = false,
+    dependsOn = ['firebase'],
+    onInitialized,
+  } = config;
+
+  return {
+    name: 'aiProviders',
+    critical,
+    dependsOn,
+    init: () => {
+      try {
+        const apiKey = getApiKey();
+
+        if (!apiKey) {
+          return Promise.resolve(false);
+        }
+
+        prunaProvider.initialize({ apiKey });
+
+        if (!providerRegistry.hasProvider(prunaProvider.providerId)) {
+          providerRegistry.register(prunaProvider);
+        }
+        providerRegistry.setActiveProvider(prunaProvider.providerId);
+
+        if (onInitialized) {
+          onInitialized();
+        }
+
+        return Promise.resolve(true);
+      } catch (error) {
+        console.error('[AiProviderInitModule] Pruna initialization failed:', error);
+        throw error;
+      }
+    },
+  };
+}

package/src/init/initializePrunaProvider.ts

@@ -0,0 +1,35 @@
+/**
+ * Direct Pruna Provider Initialization
+ * Synchronous initialization for simple app startup
+ */
+
+import { providerRegistry } from '@umituz/react-native-ai-generation-content';
+import { prunaProvider } from '../infrastructure/services';
+
+/**
+ * Initializes Pruna provider and registers it with providerRegistry in one call.
+ * Use this for simple synchronous registration at app startup.
+ */
+export function initializePrunaProvider(config: {
+  apiKey: string | undefined;
+}): boolean {
+  try {
+    const { apiKey } = config;
+
+    if (!apiKey) {
+      return false;
+    }
+
+    prunaProvider.initialize({ apiKey });
+
+    if (!providerRegistry.hasProvider(prunaProvider.providerId)) {
+      providerRegistry.register(prunaProvider);
+    }
+    providerRegistry.setActiveProvider(prunaProvider.providerId);
+
+    return true;
+  } catch (error) {
+    console.error('[initializePrunaProvider] Initialization failed:', error);
+    throw error;
+  }
+}

package/src/presentation/hooks/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Presentation Layer Hooks Index
+ */
+
+export { usePrunaGeneration } from "./use-pruna-generation";
+export type { UsePrunaGenerationOptions, UsePrunaGenerationResult } from "./use-pruna-generation";