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

package/package.json

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

package/src/index.ts

@@ -1,20 +1,9 @@
 /**
  * @umituz/react-native-ai-gemini-provider
  * Google Gemini AI provider for React Native applications
- *
- * Usage:
- *   import {
- *     geminiClientService,
- *     geminiProviderService,
- *     useGemini,
- *     mapGeminiError,
- *   } from '@umituz/react-native-ai-gemini-provider';
  */
 
-// =============================================================================
-// DOMAIN LAYER - Types
-// =============================================================================
-
+// Domain Types
 export type {
   GeminiConfig,
   GeminiGenerationConfig,
@@ -42,30 +31,14 @@ export type {
   VideoResolution,
   VideoOperationStatus,
   VeoOperation,
-} from "./domain/entities";
-
-export { GeminiErrorType } from "./domain/entities";
-
-export type {
   GeminiErrorInfo,
   GeminiApiError,
+  ResponseModality,
 } from "./domain/entities";
 
-export { GeminiError } from "./domain/entities";
-
-// Model Constants
-export {
-  GEMINI_MODELS,
-  DEFAULT_MODELS,
-  RESPONSE_MODALITIES,
-} from "./domain/entities";
-
-export type { ResponseModality } from "./domain/entities";
-
-// =============================================================================
-// DOMAIN LAYER - Feature Models
-// =============================================================================
+export { GeminiErrorType, GeminiError, GEMINI_MODELS, DEFAULT_MODELS, RESPONSE_MODALITIES } from "./domain/entities";
 
+// Feature Models
 export {
   GEMINI_IMAGE_FEATURE_MODELS,
   GEMINI_VIDEO_FEATURE_MODELS,
@@ -74,14 +47,9 @@ export {
   getAllFeatureModels,
 } from "./domain/constants";
 
-export type {
-  FeatureModelConfig,
-} from "./domain/constants";
-
-// =============================================================================
-// INFRASTRUCTURE LAYER - Services
-// =============================================================================
+export type { FeatureModelConfig } from "./domain/constants";
 
+// Services
 export {
   geminiClientCoreService,
   geminiRetryService,
@@ -106,18 +74,31 @@ export type {
   GenerationInput,
   GenerationResult,
   ExecutionOptions,
+  RetryOptions,
 } from "./infrastructure/services";
 
-// =============================================================================
-// INFRASTRUCTURE LAYER - Utils
-// =============================================================================
-
+// Utils
 export {
   mapGeminiError,
   isGeminiErrorRetryable,
   categorizeGeminiError,
   createGeminiError,
-  // Input builders
+  isValidModel,
+  validateModel,
+  getSafeModel,
+  isTextModel,
+  isImageModel,
+  isImageEditModel,
+  isVideoGenerationModel,
+  getModelCategory,
+  getAllValidModels,
+  measureAsync,
+  measureSync,
+  debounce,
+  throttle,
+  PerformanceTimer,
+  PerformanceTracker,
+  performanceTracker,
   buildSingleImageInput,
   buildDualImageInput,
   buildUpscaleInput,
@@ -134,31 +115,41 @@ export {
 } from "./infrastructure/utils";
 
 export type {
-  UpscaleOptions as GeminiUpscaleOptions,
-  PhotoRestoreOptions as GeminiPhotoRestoreOptions,
-  FaceSwapOptions as GeminiFaceSwapOptions,
-  AnimeSelfieOptions as GeminiAnimeSelfieOptions,
-  RemoveBackgroundOptions as GeminiRemoveBackgroundOptions,
-  RemoveObjectOptions as GeminiRemoveObjectOptions,
-  ReplaceBackgroundOptions as GeminiReplaceBackgroundOptions,
-  VideoFromImageOptions as GeminiVideoFromImageOptions,
+  PreparedImage,
+  UpscaleOptions,
+  PhotoRestoreOptions,
+  FaceSwapOptions,
+  AnimeSelfieOptions,
+  RemoveBackgroundOptions,
+  RemoveObjectOptions,
+  ReplaceBackgroundOptions,
+  VideoFromImageOptions,
+  PerformanceMetrics,
 } from "./infrastructure/utils";
 
-// =============================================================================
-// PRESENTATION LAYER - Hooks
-// =============================================================================
-
+// Hooks
 export { useGemini } from "./presentation/hooks";
 
+export type { UseGeminiOptions, UseGeminiReturn } from "./presentation/hooks";
+
+// Telemetry
+export { telemetryHooks } from "./infrastructure/telemetry";
+export type { TelemetryEvent, TelemetryListener } from "./infrastructure/telemetry";
+
+// Interceptors
+export { requestInterceptors, responseInterceptors } from "./infrastructure/interceptors";
 export type {
-  UseGeminiOptions,
-  UseGeminiReturn,
-} from "./presentation/hooks";
+  RequestContext,
+  RequestInterceptor,
+  ResponseContext,
+  ResponseInterceptor,
+} from "./infrastructure/interceptors";
 
-// =============================================================================
-// PROVIDER CONFIGURATION - Tier-based Setup
-// =============================================================================
+// Cache
+export { SimpleCache, modelSelectionCache } from "./infrastructure/cache";
+export type { CacheOptions } from "./infrastructure/cache";
 
+// Provider Config
 export {
   providerFactory,
   resolveProviderConfig,

package/src/infrastructure/cache/SimpleCache.ts

@@ -0,0 +1,173 @@
+/**
+ * Simple LRU Cache
+ * Least Recently Used cache for performance optimization
+ */
+
+declare const __DEV__: boolean;
+
+interface CacheEntry<V> {
+  value: V;
+  expiresAt: number;
+}
+
+export interface CacheOptions {
+  maxSize?: number;
+  ttl?: number; // Time to live in milliseconds
+}
+
+export class SimpleCache<K, V> {
+  private cache = new Map<K, CacheEntry<V>>();
+  private maxSize: number;
+  private ttl: number;
+
+  constructor(options: CacheOptions = {}) {
+    this.maxSize = options.maxSize ?? 100;
+    this.ttl = options.ttl ?? 5 * 60 * 1000; // 5 minutes default
+  }
+
+  /**
+   * Set a value in the cache
+   */
+  set(key: K, value: V, customTtl?: number): void {
+    // Remove oldest entry if at capacity
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    const ttl = customTtl ?? this.ttl;
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + ttl,
+    });
+  }
+
+  /**
+   * Get a value from the cache
+   * Returns undefined if not found or expired
+   */
+  get(key: K): V | undefined {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.value;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key: K): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  /**
+   * Delete a specific key
+   */
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get current cache size
+   */
+  size(): number {
+    // Clean expired entries first
+    this.cleanExpired();
+    return this.cache.size;
+  }
+
+  /**
+   * Remove all expired entries
+   */
+  private cleanExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Get all valid keys (not expired)
+   */
+  keys(): K[] {
+    this.cleanExpired();
+    return Array.from(this.cache.keys());
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    maxSize: number;
+    keys: K[];
+  } {
+    return {
+      size: this.size(),
+      maxSize: this.maxSize,
+      keys: this.keys(),
+    };
+  }
+}
+
+/**
+ * Global model selection cache
+ * Caches model IDs for features to avoid repeated lookups
+ */
+class ModelSelectionCache {
+  private cache = new SimpleCache<string, string>({
+    maxSize: 50,
+    ttl: 10 * 60 * 1000, // 10 minutes
+  });
+
+  set(feature: string, model: string): void {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[ModelSelectionCache] Caching model:", { feature, model });
+    }
+    this.cache.set(feature, model);
+  }
+
+  get(feature: string): string | undefined {
+    const model = this.cache.get(feature);
+    if (model && typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[ModelSelectionCache] Cache hit:", { feature, model });
+    }
+    return model;
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  getStats(): ReturnType<SimpleCache<string, string>["getStats"]> {
+    return this.cache.getStats();
+  }
+}
+
+export const modelSelectionCache = new ModelSelectionCache();

package/src/infrastructure/cache/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Cache Module
+ * Simple LRU cache for performance optimization
+ */
+
+export { SimpleCache, modelSelectionCache } from "./SimpleCache";
+export type { CacheOptions } from "./SimpleCache";

package/src/infrastructure/interceptors/RequestInterceptors.ts

@@ -0,0 +1,67 @@
+/**
+ * Request Interceptors
+ * Allows applications to modify requests before they're sent
+ */
+
+export interface RequestContext {
+  model: string;
+  feature?: string;
+  payload: Record<string, unknown>;
+  timestamp: number;
+}
+
+export type RequestInterceptor = (context: RequestContext) => RequestContext | Promise<RequestContext>;
+
+class RequestInterceptors {
+  private interceptors: RequestInterceptor[] = [];
+
+  /**
+   * Register a request interceptor
+   * Interceptors are called in order (first registered = first called)
+   */
+  use(interceptor: RequestInterceptor): () => void {
+    this.interceptors.push(interceptor);
+
+    // Return unsubscribe function
+    return () => {
+      const index = this.interceptors.indexOf(interceptor);
+      if (index > -1) {
+        this.interceptors.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Apply all interceptors to a request context
+   */
+  async apply(context: RequestContext): Promise<RequestContext> {
+    let result = context;
+
+    for (const interceptor of this.interceptors) {
+      try {
+        result = await interceptor(result);
+      } catch (error) {
+        // Interceptor error should fail the request
+        throw new Error(`Request interceptor failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all interceptors
+   */
+  clear(): void {
+    this.interceptors = [];
+  }
+
+  /**
+   * Get interceptor count
+   */
+  count(): number {
+    return this.interceptors.length;
+  }
+}
+
+export const requestInterceptors = new RequestInterceptors();

package/src/infrastructure/interceptors/ResponseInterceptors.ts

@@ -0,0 +1,72 @@
+/**
+ * Response Interceptors
+ * Allows applications to modify responses after they're received
+ */
+
+export interface ResponseContext<T = unknown> {
+  model: string;
+  feature?: string;
+  data: T;
+  duration: number;
+  timestamp: number;
+}
+
+export type ResponseInterceptor<T = unknown> = (
+  context: ResponseContext<T>,
+) => ResponseContext<T> | Promise<ResponseContext<T>>;
+
+class ResponseInterceptors {
+  private interceptors: Array<ResponseInterceptor<unknown>> = [];
+
+  /**
+   * Register a response interceptor
+   * Interceptors are called in reverse order (last registered = first called)
+   */
+  use<T = unknown>(interceptor: ResponseInterceptor<T>): () => void {
+    this.interceptors.push(interceptor as ResponseInterceptor<unknown>);
+
+    // Return unsubscribe function
+    return () => {
+      const index = this.interceptors.indexOf(interceptor as ResponseInterceptor<unknown>);
+      if (index > -1) {
+        this.interceptors.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Apply all interceptors to a response context
+   */
+  async apply<T>(context: ResponseContext<T>): Promise<ResponseContext<T>> {
+    let result: ResponseContext<unknown> = context;
+
+    // Apply in reverse order (last added = first processed)
+    for (let i = this.interceptors.length - 1; i >= 0; i--) {
+      const interceptor = this.interceptors[i];
+      try {
+        result = await interceptor(result);
+      } catch (error) {
+        // Interceptor error should fail the response processing
+        throw new Error(`Response interceptor failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    return result as ResponseContext<T>;
+  }
+
+  /**
+   * Clear all interceptors
+   */
+  clear(): void {
+    this.interceptors = [];
+  }
+
+  /**
+   * Get interceptor count
+   */
+  count(): number {
+    return this.interceptors.length;
+  }
+}
+
+export const responseInterceptors = new ResponseInterceptors();

package/src/infrastructure/interceptors/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Interceptors Module
+ * Allows applications to modify requests and responses
+ */
+
+export { requestInterceptors } from "./RequestInterceptors";
+export { responseInterceptors } from "./ResponseInterceptors";
+
+export type {
+  RequestContext,
+  RequestInterceptor,
+} from "./RequestInterceptors";
+
+export type {
+  ResponseContext,
+  ResponseInterceptor,
+} from "./ResponseInterceptors";

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,29 @@ 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";
+
+export {
+  measureAsync,
+  measureSync,
+  debounce,
+  throttle,
+  PerformanceTimer,
+  PerformanceTracker,
+  performanceTracker,
+} from "./performance.util";
+export type { PerformanceMetrics } from "./performance.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);
+}

package/src/infrastructure/utils/performance.util.ts

@@ -0,0 +1,145 @@
+/**
+ * Performance Utilities
+ * Tools for measuring and optimizing performance
+ */
+
+declare const __DEV__: boolean;
+
+export interface PerformanceMetrics {
+  duration: number;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export class PerformanceTimer {
+  private startTime: number;
+  private endTime?: number;
+  private metadata?: Record<string, unknown>;
+
+  constructor(metadata?: Record<string, unknown>) {
+    this.startTime = Date.now();
+    this.metadata = metadata;
+  }
+
+  stop(): number {
+    this.endTime = Date.now();
+    return this.duration;
+  }
+
+  get duration(): number {
+    const end = this.endTime ?? Date.now();
+    return end - this.startTime;
+  }
+
+  getMetrics(): PerformanceMetrics {
+    return { duration: this.duration, timestamp: this.startTime, metadata: this.metadata };
+  }
+
+  get isRunning(): boolean {
+    return this.endTime === undefined;
+  }
+}
+
+export async function measureAsync<T>(
+  operation: () => Promise<T>,
+  metadata?: Record<string, unknown>,
+): Promise<{ result: T; duration: number }> {
+  const timer = new PerformanceTimer(metadata);
+  try {
+    const result = await operation();
+    const duration = timer.stop();
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[Performance] Operation completed:", { duration: `${duration}ms`, metadata });
+    }
+    return { result, duration };
+  } catch (error) {
+    timer.stop();
+    throw error;
+  }
+}
+
+export function measureSync<T>(
+  operation: () => T,
+  metadata?: Record<string, unknown>,
+): { result: T; duration: number } {
+  const timer = new PerformanceTimer(metadata);
+  try {
+    const result = operation();
+    const duration = timer.stop();
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[Performance] Operation completed:", { duration: `${duration}ms`, metadata });
+    }
+    return { result, duration };
+  } catch (error) {
+    timer.stop();
+    throw error;
+  }
+}
+
+export function debounce<T extends (...args: never[]) => unknown>(
+  func: T,
+  wait: number,
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  return (...args: Parameters<T>) => {
+    const later = () => {
+      clearTimeout(timeout);
+      func(...args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  };
+}
+
+export function throttle<T extends (...args: never[]) => unknown>(
+  func: T,
+  limit: number,
+): (...args: Parameters<T>) => void {
+  let inThrottle: boolean;
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      func(...args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}
+
+export class PerformanceTracker {
+  private metrics = new Map<string, number[]>();
+
+  record(operation: string, duration: number): void {
+    if (!this.metrics.has(operation)) {
+      this.metrics.set(operation, []);
+    }
+    this.metrics.get(operation)!.push(duration);
+  }
+
+  getStats(operation: string): { count: number; avg: number; min: number; max: number } | null {
+    const durations = this.metrics.get(operation);
+    if (!durations || durations.length === 0) return null;
+    return {
+      count: durations.length,
+      avg: durations.reduce((a, b) => a + b, 0) / durations.length,
+      min: Math.min(...durations),
+      max: Math.max(...durations),
+    };
+  }
+
+  getAllStats(): Record<string, ReturnType<PerformanceTracker["getStats"]>> {
+    const stats: Record<string, ReturnType<PerformanceTracker["getStats"]>> = {};
+    for (const operation of this.metrics.keys()) {
+      stats[operation] = this.getStats(operation);
+    }
+    return stats;
+  }
+
+  clear(): void {
+    this.metrics.clear();
+  }
+}
+
+export const performanceTracker = new PerformanceTracker();
+