@umituz/react-native-ai-gemini-provider 1.14.25 → 1.14.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-gemini-provider",
-  "version": "1.14.25",
+  "version": "1.14.26",
   "description": "Google Gemini AI provider for React Native applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.ts

@@ -106,6 +106,7 @@ export type {
   GenerationInput,
   GenerationResult,
   ExecutionOptions,
+  RetryOptions,
 } from "./infrastructure/services";
 
 // =============================================================================
@@ -117,6 +118,16 @@ export {
   isGeminiErrorRetryable,
   categorizeGeminiError,
   createGeminiError,
+  // Model validation
+  isValidModel,
+  validateModel,
+  getSafeModel,
+  isTextModel,
+  isImageModel,
+  isImageEditModel,
+  isVideoGenerationModel,
+  getModelCategory,
+  getAllValidModels,
   // Input builders
   buildSingleImageInput,
   buildDualImageInput,
@@ -155,6 +166,17 @@ export type {
   UseGeminiReturn,
 } from "./presentation/hooks";
 
+// =============================================================================
+// TELEMETRY - Monitoring and Observability
+// =============================================================================
+
+export { telemetryHooks } from "./infrastructure/telemetry";
+
+export type {
+  TelemetryEvent,
+  TelemetryListener,
+} from "./infrastructure/telemetry";
+
 // =============================================================================
 // PROVIDER CONFIGURATION - Tier-based Setup
 // =============================================================================

package/src/infrastructure/services/gemini-retry.service.ts

@@ -1,6 +1,7 @@
 /**
  * Gemini Retry Service
- * Handles retry logic with exponential backoff
+ * Handles retry logic with exponential backoff and jitter
+ * Jitter helps prevent thundering herd problem in distributed systems
  */
 
 import { geminiClientCoreService } from "./gemini-client-core.service";
@@ -26,19 +27,46 @@ function isRetryableError(error: unknown): boolean {
   return RETRYABLE_ERROR_PATTERNS.some((pattern) => message.includes(pattern));
 }
 
+/**
+ * Add random jitter to delay to prevent synchronized retries
+ * Uses full jitter strategy: random between 0 and base_delay * 2^attempt
+ */
+function calculateDelayWithJitter(
+  baseDelay: number,
+  retryCount: number,
+  maxDelay: number,
+): number {
+  const exponentialDelay = baseDelay * Math.pow(2, retryCount);
+  const cappedDelay = Math.min(exponentialDelay, maxDelay);
+  const jitter = Math.random() * cappedDelay;
+  return Math.floor(jitter);
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  enableJitter?: boolean;
+}
+
 class GeminiRetryService {
+  /**
+   * Execute operation with retry logic
+   */
   async executeWithRetry<T>(
     operation: () => Promise<T>,
     retryCount = 0,
+    options?: RetryOptions,
   ): Promise<T> {
     const config = geminiClientCoreService.getConfig();
-    const maxRetries = config?.maxRetries ?? 3;
-    const baseDelay = config?.baseDelay ?? 1000;
-    const maxDelay = config?.maxDelay ?? 10000;
+    const maxRetries = options?.maxRetries ?? config?.maxRetries ?? 3;
+    const baseDelay = options?.baseDelay ?? config?.baseDelay ?? 1000;
+    const maxDelay = options?.maxDelay ?? config?.maxDelay ?? 10000;
+    const enableJitter = options?.enableJitter ?? true;
 
     try {
       return await operation();
@@ -47,17 +75,28 @@ class GeminiRetryService {
         throw error;
       }
 
-      const delay = Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
+      const delay = enableJitter
+        ? calculateDelayWithJitter(baseDelay, retryCount, maxDelay)
+        : Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
 
       if (typeof __DEV__ !== "undefined" && __DEV__) {
         // eslint-disable-next-line no-console
-        console.log(`[Gemini] Retry ${retryCount + 1}/${maxRetries} after ${delay}ms`);
+        console.log(`[Gemini] Retry ${retryCount + 1}/${maxRetries} after ${delay}ms`, {
+          jitter: enableJitter,
+        });
       }
 
       await sleep(delay);
-      return this.executeWithRetry(operation, retryCount + 1);
+      return this.executeWithRetry(operation, retryCount + 1, options);
     }
   }
+
+  /**
+   * Check if an error is retryable
+   */
+  isRetryableError(error: unknown): boolean {
+    return isRetryableError(error);
+  }
 }
 
 export const geminiRetryService = new GeminiRetryService();

package/src/infrastructure/services/index.ts

@@ -34,6 +34,9 @@ export type {
   ExecutionOptions,
 } from "./generation-executor";
 
+// Retry service types
+export type { RetryOptions } from "./gemini-retry.service";
+
 // Re-export types from generation-content for convenience
 export type {
   IAIProvider,

package/src/infrastructure/telemetry/TelemetryHooks.ts

@@ -0,0 +1,125 @@
+/**
+ * Telemetry Hooks
+ * Allows applications to monitor and log AI operations
+ */
+
+declare const __DEV__: boolean;
+
+export interface TelemetryEvent {
+  type: "request" | "response" | "error" | "retry";
+  timestamp: number;
+  model?: string;
+  feature?: string;
+  duration?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export type TelemetryListener = (event: TelemetryEvent) => void;
+
+class TelemetryHooks {
+  private listeners: TelemetryListener[] = [];
+
+  /**
+   * Register a telemetry listener
+   */
+  subscribe(listener: TelemetryListener): () => void {
+    this.listeners.push(listener);
+
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index > -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Emit a telemetry event to all listeners
+   */
+  emit(event: TelemetryEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        // Prevent telemetry errors from breaking the app
+        if (typeof __DEV__ !== "undefined" && __DEV__) {
+          // eslint-disable-next-line no-console
+          console.error("[Telemetry] Listener error:", error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Log request start
+   */
+  logRequest(model: string, feature?: string): number {
+    const timestamp = Date.now();
+    this.emit({
+      type: "request",
+      timestamp,
+      model,
+      feature,
+    });
+    return timestamp;
+  }
+
+  /**
+   * Log response received
+   */
+  logResponse(model: string, startTime: number, feature?: string, metadata?: Record<string, unknown>): void {
+    this.emit({
+      type: "response",
+      timestamp: Date.now(),
+      model,
+      feature,
+      duration: Date.now() - startTime,
+      metadata,
+    });
+  }
+
+  /**
+   * Log error
+   */
+  logError(model: string, error: Error, feature?: string): void {
+    this.emit({
+      type: "error",
+      timestamp: Date.now(),
+      model,
+      feature,
+      metadata: {
+        error: error.message,
+        errorType: error.name,
+      },
+    });
+  }
+
+  /**
+   * Log retry attempt
+   */
+  logRetry(model: string, attempt: number, feature?: string): void {
+    this.emit({
+      type: "retry",
+      timestamp: Date.now(),
+      model,
+      feature,
+      metadata: { attempt },
+    });
+  }
+
+  /**
+   * Clear all listeners
+   */
+  clear(): void {
+    this.listeners = [];
+  }
+
+  /**
+   * Get current listener count
+   */
+  getListenerCount(): number {
+    return this.listeners.length;
+  }
+}
+
+export const telemetryHooks = new TelemetryHooks();

package/src/infrastructure/telemetry/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Telemetry Module
+ */
+
+export { telemetryHooks } from "./TelemetryHooks";
+export type { TelemetryEvent, TelemetryListener } from "./TelemetryHooks";

package/src/infrastructure/utils/index.ts

@@ -21,6 +21,18 @@ export {
 } from "./image-preparer.util";
 export type { PreparedImage } from "./image-preparer.util";
 
+export {
+  isValidModel,
+  validateModel,
+  getSafeModel,
+  isTextModel,
+  isImageModel,
+  isImageEditModel,
+  isVideoGenerationModel,
+  getModelCategory,
+  getAllValidModels,
+} from "./model-validation.util";
+
 // Input builders
 export {
   buildSingleImageInput,

package/src/infrastructure/utils/model-validation.util.ts

@@ -0,0 +1,107 @@
+/**
+ * Model Validation Utilities
+ * Validates model IDs and configurations
+ */
+
+import { GEMINI_MODELS, DEFAULT_MODELS } from "../../domain/entities";
+
+declare const __DEV__: boolean;
+
+/**
+ * Known valid model IDs
+ */
+const VALID_MODELS = new Set<string>(
+  Object.values(GEMINI_MODELS).flatMap((category) => Object.values(category)),
+);
+
+/**
+ * Check if a model ID is valid
+ */
+export function isValidModel(model: string): boolean {
+  return VALID_MODELS.has(model);
+}
+
+/**
+ * Validate model ID and throw if invalid
+ */
+export function validateModel(model: string): void {
+  if (!model) {
+    throw new Error("Model ID cannot be empty");
+  }
+
+  if (!isValidModel(model)) {
+    throw new Error(
+      `Invalid model ID: ${model}. Valid models: ${Array.from(VALID_MODELS).join(", ")}`,
+    );
+  }
+
+  if (typeof __DEV__ !== "undefined" && __DEV__) {
+    // eslint-disable-next-line no-console
+    console.log("[ModelValidation] Model validated:", model);
+  }
+}
+
+/**
+ * Get a safe model ID (fallback to default if invalid)
+ */
+export function getSafeModel(model: string | undefined, defaultType: keyof typeof DEFAULT_MODELS): string {
+  if (!model) {
+    return DEFAULT_MODELS[defaultType];
+  }
+
+  if (!isValidModel(model)) {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn(`[ModelValidation] Invalid model "${model}", falling back to ${DEFAULT_MODELS[defaultType]}`);
+    }
+    return DEFAULT_MODELS[defaultType];
+  }
+
+  return model;
+}
+
+/**
+ * Check if model is a text generation model
+ */
+export function isTextModel(model: string): boolean {
+  return Object.values(GEMINI_MODELS.TEXT).includes(model as (typeof GEMINI_MODELS.TEXT)[keyof typeof GEMINI_MODELS.TEXT]);
+}
+
+/**
+ * Check if model is an image generation model
+ */
+export function isImageModel(model: string): boolean {
+  return Object.values(GEMINI_MODELS.TEXT_TO_IMAGE).includes(model as (typeof GEMINI_MODELS.TEXT_TO_IMAGE)[keyof typeof GEMINI_MODELS.TEXT_TO_IMAGE]);
+}
+
+/**
+ * Check if model is an image editing model
+ */
+export function isImageEditModel(model: string): boolean {
+  return Object.values(GEMINI_MODELS.IMAGE_EDIT).includes(model as (typeof GEMINI_MODELS.IMAGE_EDIT)[keyof typeof GEMINI_MODELS.IMAGE_EDIT]);
+}
+
+/**
+ * Check if model is a video generation model
+ */
+export function isVideoGenerationModel(model: string): boolean {
+  return Object.values(GEMINI_MODELS.VIDEO_GENERATION).includes(model as (typeof GEMINI_MODELS.VIDEO_GENERATION)[keyof typeof GEMINI_MODELS.VIDEO_GENERATION]);
+}
+
+/**
+ * Get model category
+ */
+export function getModelCategory(model: string): string | null {
+  if (isTextModel(model)) return "text";
+  if (isImageModel(model)) return "text-to-image";
+  if (isImageEditModel(model)) return "image-edit";
+  if (isVideoGenerationModel(model)) return "video-generation";
+  return null;
+}
+
+/**
+ * Get all valid model IDs
+ */
+export function getAllValidModels(): readonly string[] {
+  return Array.from(VALID_MODELS);
+}