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

package/package.json

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

package/src/domain/entities/error.types.ts

@@ -37,3 +37,48 @@ export interface GeminiApiError {
     }>;
   };
 }
+
+/**
+ * Custom error class for Gemini API errors
+ */
+export class GeminiError extends Error {
+  readonly type: GeminiErrorType;
+  readonly retryable: boolean;
+  readonly statusCode?: number;
+  readonly originalError?: unknown;
+
+  constructor(info: GeminiErrorInfo) {
+    super(info.messageKey);
+    this.name = "GeminiError";
+    this.type = info.type;
+    this.retryable = info.retryable;
+    this.statusCode = info.statusCode;
+    this.originalError = info.originalError;
+
+    // Maintains proper stack trace (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, GeminiError);
+    }
+  }
+
+  /**
+   * Check if error is retryable
+   */
+  isRetryable(): boolean {
+    return this.retryable;
+  }
+
+  /**
+   * Get error type
+   */
+  getErrorType(): GeminiErrorType {
+    return this.type;
+  }
+
+  /**
+   * Create GeminiError from unknown error
+   */
+  static fromError(_error: unknown, info: GeminiErrorInfo): GeminiError {
+    return new GeminiError(info);
+  }
+}

package/src/index.ts

@@ -51,6 +51,8 @@ export type {
   GeminiApiError,
 } from "./domain/entities";
 
+export { GeminiError } from "./domain/entities";
+
 // Model Constants
 export {
   GEMINI_MODELS,
@@ -90,6 +92,7 @@ export {
   geminiVideoGenerationService,
   geminiProviderService,
   createGeminiProvider,
+  featureModelSelector,
 } from "./infrastructure/services";
 
 export type {
@@ -100,6 +103,10 @@ export type {
   JobStatus,
   SubscribeOptions,
   AIJobStatusType,
+  GenerationInput,
+  GenerationResult,
+  ExecutionOptions,
+  RetryOptions,
 } from "./infrastructure/services";
 
 // =============================================================================
@@ -110,6 +117,17 @@ export {
   mapGeminiError,
   isGeminiErrorRetryable,
   categorizeGeminiError,
+  createGeminiError,
+  // Model validation
+  isValidModel,
+  validateModel,
+  getSafeModel,
+  isTextModel,
+  isImageModel,
+  isImageEditModel,
+  isVideoGenerationModel,
+  getModelCategory,
+  getAllValidModels,
   // Input builders
   buildSingleImageInput,
   buildDualImageInput,
@@ -148,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/feature-model-selector.ts

@@ -1,6 +1,7 @@
 /**
  * Feature Model Selector
  * Returns the appropriate model ID for a given feature
+ * Supports runtime model overrides for flexibility
  */
 
 import type {
@@ -12,19 +13,64 @@ import {
   GEMINI_VIDEO_FEATURE_MODELS,
 } from "../../domain/constants/feature-models.constants";
 
+declare const __DEV__: boolean;
+
+type ModelOverrideMap = Partial<Record<ImageFeatureType | VideoFeatureType, string>>;
+
 class FeatureModelSelector {
+  private overrides: ModelOverrideMap = {};
+
+  /**
+   * Set model override for a specific feature
+   * This allows runtime configuration without modifying constants
+   */
+  setModelOverride(feature: ImageFeatureType | VideoFeatureType, model: string): void {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[FeatureModelSelector] Model override set:", { feature, model });
+    }
+    this.overrides[feature] = model;
+  }
+
+  /**
+   * Clear all model overrides
+   */
+  clearOverrides(): void {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[FeatureModelSelector] All model overrides cleared");
+    }
+    this.overrides = {};
+  }
+
   /**
    * Get model ID for an IMAGE feature
+   * Returns override if set, otherwise returns default model
    */
   getImageFeatureModel(feature: ImageFeatureType): string {
-    return GEMINI_IMAGE_FEATURE_MODELS[feature];
+    return this.overrides[feature] ?? GEMINI_IMAGE_FEATURE_MODELS[feature];
   }
 
   /**
    * Get model ID for a VIDEO feature
+   * Returns override if set, otherwise returns default model
    */
   getVideoFeatureModel(feature: VideoFeatureType): string {
-    return GEMINI_VIDEO_FEATURE_MODELS[feature];
+    return this.overrides[feature] ?? GEMINI_VIDEO_FEATURE_MODELS[feature];
+  }
+
+  /**
+   * Check if a feature has a custom override
+   */
+  hasOverride(feature: ImageFeatureType | VideoFeatureType): boolean {
+    return feature in this.overrides;
+  }
+
+  /**
+   * Get all current overrides
+   */
+  getOverrides(): ModelOverrideMap {
+    return { ...this.overrides };
   }
 }
 

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/generation-executor.ts

@@ -5,7 +5,9 @@
 
 import type {
     GeminiImageInput,
+    GeminiImageGenerationResult,
     VideoGenerationInput,
+    VideoGenerationResult,
     VideoGenerationProgress,
 } from "../../domain/entities";
 import { geminiTextGenerationService } from "./gemini-text-generation.service";
@@ -20,13 +22,29 @@ export interface ExecutionOptions {
     onProgress?: (progress: number) => void;
 }
 
+export type GenerationInput = {
+    type?: "text" | "image" | "video";
+    generateImage?: boolean;
+    prompt?: string;
+    images?: GeminiImageInput[];
+    generationConfig?: unknown;
+    image?: string;
+    negativePrompt?: string;
+    aspect_ratio?: string;
+};
+
+export type GenerationResult =
+    | string
+    | GeminiImageGenerationResult
+    | VideoGenerationResult;
+
 export class GenerationExecutor {
     private contentBuilder = new ContentBuilder();
     private responseFormatter = new ResponseFormatter();
 
-    async executeGeneration<T>(
+    async executeGeneration<T = GenerationResult>(
         model: string,
-        input: Record<string, unknown>,
+        input: GenerationInput,
         options?: ExecutionOptions,
     ): Promise<T> {
         if (typeof __DEV__ !== "undefined" && __DEV__) {
@@ -43,14 +61,13 @@ export class GenerationExecutor {
         }
 
         if (isVideoGeneration) {
-            return this.executeVideoGeneration<T>(input, options);
+            return this.executeVideoGeneration(input, options) as T;
         }
 
         if (isImageGeneration) {
-            const prompt = String(input.prompt || "");
-            const images = input.images as GeminiImageInput[] | undefined;
-            const result = await geminiImageGenerationService.generateImage(prompt, images);
-            return result as T;
+            const prompt = String(input.prompt ?? "");
+            const images = input.images;
+            return geminiImageGenerationService.generateImage(prompt, images) as T;
         }
 
         const contents = this.contentBuilder.buildContents(input);
@@ -73,21 +90,21 @@ export class GenerationExecutor {
     /**
      * Execute video generation using Veo API
      */
-    private async executeVideoGeneration<T>(
-        input: Record<string, unknown>,
+    private async executeVideoGeneration(
+        input: GenerationInput,
         options?: ExecutionOptions,
-    ): Promise<T> {
+    ): Promise<VideoGenerationResult> {
         if (typeof __DEV__ !== "undefined" && __DEV__) {
             // eslint-disable-next-line no-console
             console.log("[GenerationExecutor] executeVideoGeneration() called");
         }
 
         const videoInput: VideoGenerationInput = {
-            prompt: String(input.prompt || ""),
-            image: input.image as string | undefined,
-            negativePrompt: input.negativePrompt as string | undefined,
+            prompt: String(input.prompt ?? ""),
+            image: input.image,
+            negativePrompt: input.negativePrompt,
             options: {
-                aspectRatio: this.normalizeAspectRatio(input.aspect_ratio as string),
+                aspectRatio: this.normalizeAspectRatio(input.aspect_ratio),
             },
         };
 
@@ -109,10 +126,9 @@ export class GenerationExecutor {
         }
 
         return {
-            video: { url: result.videoUrl },
             videoUrl: result.videoUrl,
             metadata: result.metadata,
-        } as T;
+        };
     }
 
     /**

package/src/infrastructure/services/index.ts

@@ -15,6 +15,7 @@ export { geminiVideoGenerationService } from "./gemini-video-generation.service"
 export { providerInitializer } from "./provider-initializer";
 export { jobProcessor } from "./job-processor";
 export { generationExecutor } from "./generation-executor";
+export { featureModelSelector } from "./feature-model-selector";
 
 // Public provider API
 export {
@@ -26,6 +27,16 @@ export {
 export type { GeminiProviderConfig } from "./gemini-provider";
 export type { GeminiProviderConfig as AIProviderConfig } from "./provider-initializer";
 
+// Generation executor types
+export type {
+  GenerationInput,
+  GenerationResult,
+  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/error-mapper.util.ts

@@ -7,6 +7,7 @@ import {
   GeminiErrorType,
   type GeminiErrorInfo,
   type GeminiApiError,
+  GeminiError,
 } from "../../domain/entities";
 
 const ERROR_PATTERNS: Array<{
@@ -112,3 +113,11 @@ export function isGeminiErrorRetryable(error: unknown): boolean {
 export function categorizeGeminiError(error: unknown): GeminiErrorType {
   return mapGeminiError(error).type;
 }
+
+/**
+ * Create a GeminiError instance from an unknown error
+ */
+export function createGeminiError(error: unknown): GeminiError {
+  const errorInfo = mapGeminiError(error);
+  return GeminiError.fromError(error, errorInfo);
+}

package/src/infrastructure/utils/index.ts

@@ -6,6 +6,7 @@ export {
   mapGeminiError,
   isGeminiErrorRetryable,
   categorizeGeminiError,
+  createGeminiError,
 } from "./error-mapper.util";
 
 export {
@@ -20,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);
+}