@umituz/react-native-ai-gemini-provider 2.0.23 → 2.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-gemini-provider",
-  "version": "2.0.23",
+  "version": "2.0.24",
   "description": "Google Gemini AI text generation provider for React Native applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -72,8 +72,7 @@
     "react-native-gesture-handler": "^2.30.0",
     "react-native-safe-area-context": "^5.6.2",
     "react-native-svg": "^15.15.1",
-    "typescript": "^5.3.0",
-    "zustand": "^5.0.9"
+    "typescript": "^5.3.0"
   },
   "publishConfig": {
     "access": "public"

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

@@ -1,29 +1,57 @@
+/**
+ * Categories of errors that can occur with Gemini API
+ */
 export enum GeminiErrorType {
+  /** Network connectivity issues */
   NETWORK = "NETWORK",
+  /** API rate limit exceeded */
   RATE_LIMIT = "RATE_LIMIT",
+  /** Authentication/authorization failures */
   AUTHENTICATION = "AUTHENTICATION",
+  /** Invalid input data or parameters */
   VALIDATION = "VALIDATION",
+  /** Content blocked by safety filters */
   SAFETY = "SAFETY",
+  /** Server-side errors */
   SERVER = "SERVER",
+  /** Request timeout */
   TIMEOUT = "TIMEOUT",
+  /** API quota exceeded */
   QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+  /** Requested model not found */
   MODEL_NOT_FOUND = "MODEL_NOT_FOUND",
+  /** Unknown/unclassified error */
   UNKNOWN = "UNKNOWN",
 }
 
+/**
+ * Detailed error information for Gemini API errors
+ */
 export interface GeminiErrorInfo {
+  /** Category of the error */
   type: GeminiErrorType;
+  /** Message key for i18n translation */
   messageKey: string;
+  /** Whether the request can be retried */
   retryable: boolean;
+  /** Original error that caused this error */
   originalError?: unknown;
+  /** HTTP status code if applicable */
   statusCode?: number;
 }
 
+/**
+ * Structure of Gemini API error responses
+ */
 export interface GeminiApiError {
   error?: {
+    /** Error code */
     code?: number;
+    /** Error message */
     message?: string;
+    /** Error status */
     status?: string;
+    /** Additional error details */
     details?: Array<{
       "@type"?: string;
       reason?: string;
@@ -33,12 +61,24 @@ export interface GeminiApiError {
   };
 }
 
+/**
+ * Custom error class for Gemini API errors
+ * Provides structured error information and retry capability
+ */
 export class GeminiError extends Error {
+  /** Error category */
   readonly type: GeminiErrorType;
+  /** Whether the operation can be retried */
   readonly retryable: boolean;
+  /** HTTP status code if applicable */
   readonly statusCode?: number;
+  /** Original error that caused this error */
   readonly originalError?: unknown;
 
+  /**
+   * Create a new GeminiError
+   * @param info - Error information
+   */
   constructor(info: GeminiErrorInfo) {
     super(info.messageKey);
     this.name = "GeminiError";
@@ -53,14 +93,28 @@ export class GeminiError extends Error {
     }
   }
 
+  /**
+   * Check if this error is retryable
+   * @returns true if the operation can be retried
+   */
   isRetryable(): boolean {
     return this.retryable;
   }
 
+  /**
+   * Get the error type
+   * @returns The error category
+   */
   getErrorType(): GeminiErrorType {
     return this.type;
   }
 
+  /**
+   * Create a GeminiError from an unknown error
+   * @param error - The original error
+   * @param info - Error information
+   * @returns A new GeminiError instance
+   */
   static fromError(error: unknown, info: GeminiErrorInfo): GeminiError {
     const geminiError = new GeminiError(info);
 

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

@@ -1,46 +1,85 @@
 import type { GenerationConfig } from "@google/generative-ai";
 
+/**
+ * Configuration for Gemini AI client initialization
+ */
 export interface GeminiConfig {
+  /** API key for authentication */
   apiKey: string;
+  /** Optional base URL for API requests */
   baseUrl?: string;
+  /** Default timeout in milliseconds */
   defaultTimeoutMs?: number;
+  /** Default model to use for text generation */
   textModel?: string;
 }
 
+/**
+ * Generation configuration for AI requests
+ * Extends the SDK's GenerationConfig with proper schema typing
+ */
 export type GeminiGenerationConfig = Omit<GenerationConfig, "responseSchema"> & {
   responseSchema?: GenerationConfig["responseSchema"];
 };
 
+/**
+ * Harm categories for content safety filtering
+ */
 export type GeminiHarmCategory =
   | "HARM_CATEGORY_HARASSMENT"
   | "HARM_CATEGORY_HATE_SPEECH"
   | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
   | "HARM_CATEGORY_DANGEROUS_CONTENT";
 
+/**
+ * Threshold levels for blocking harmful content
+ */
 export type GeminiHarmBlockThreshold =
   | "BLOCK_NONE"
   | "BLOCK_LOW_AND_ABOVE"
   | "BLOCK_MEDIUM_AND_ABOVE"
   | "BLOCK_ONLY_HIGH";
 
+/**
+ * Content structure for Gemini API requests
+ */
 export interface GeminiContent {
+  /** Array of content parts (text, images, etc.) */
   parts: GeminiPart[];
+  /** Role of the content creator (user or model) */
   role?: "user" | "model";
 }
 
+/**
+ * Individual content part
+ */
 export type GeminiPart = { text: string };
 
+/**
+ * Response structure from Gemini API
+ */
 export interface GeminiResponse {
+  /** Array of response candidates */
   candidates?: GeminiCandidate[];
+  /** Token usage information */
   usageMetadata?: GeminiUsageMetadata;
 }
 
+/**
+ * Individual response candidate
+ */
 export interface GeminiCandidate {
+  /** Generated content */
   content: GeminiContent;
+  /** Reason for generation completion */
   finishReason?: GeminiFinishReason;
+  /** Safety ratings for the content */
   safetyRatings?: GeminiSafetyRating[];
 }
 
+/**
+ * Reasons why generation finished
+ */
 export type GeminiFinishReason =
   | "FINISH_REASON_UNSPECIFIED"
   | "STOP"
@@ -49,15 +88,26 @@ export type GeminiFinishReason =
   | "RECITATION"
   | "OTHER";
 
+/**
+ * Safety rating for generated content
+ */
 export interface GeminiSafetyRating {
+  /** Category of safety check */
   category: GeminiHarmCategory;
+  /** Probability of content being unsafe */
   probability: "NEGLIGIBLE" | "LOW" | "MEDIUM" | "HIGH";
+  /** Whether the content was blocked */
   blocked?: boolean;
 }
 
+/**
+ * Token usage metadata for the request
+ */
 export interface GeminiUsageMetadata {
+  /** Number of tokens in the prompt */
   promptTokenCount?: number;
+  /** Number of tokens in the response candidates */
   candidatesTokenCount?: number;
+  /** Total number of tokens used */
   totalTokenCount?: number;
 }
-

package/src/domain/entities/models.ts

@@ -1,13 +1,26 @@
+/**
+ * Available Gemini AI models
+ */
 export const GEMINI_MODELS = {
+  /** Text generation models */
   TEXT: {
+    /** Lightweight flash model for fast text generation */
     FLASH_LITE: "gemini-2.5-flash-lite",
   },
 } as const;
 
+/**
+ * Default models to use for each category
+ */
 export const DEFAULT_MODELS = {
+  /** Default model for text generation */
   TEXT: GEMINI_MODELS.TEXT.FLASH_LITE,
 } as const;
 
+/**
+ * Pricing information for Gemini models
+ * Prices are per 1M tokens (USD)
+ */
 export const MODEL_PRICING = {
   [GEMINI_MODELS.TEXT.FLASH_LITE]: { input: 0.10, output: 0.40, freePerDay: 1000 },
 } as const;

package/src/index.ts

@@ -37,22 +37,70 @@ export type { GeminiProviderConfig } from "./infrastructure/services";
 
 // Utils
 export {
+  // Error handling
   mapGeminiError,
   isGeminiErrorRetryable,
   categorizeGeminiError,
   createGeminiError,
+  // Data transformation
   extractTextFromResponse,
+  cleanJsonText,
+  parseJsonResponse,
+  safeParseJson,
+  extractJsonFromText,
+  toSdkContent,
+  createTextContent,
+  transformCandidate,
+  transformResponse,
+  extractTextFromParts,
+  // Performance
   measureAsync,
   measureSync,
   debounce,
   throttle,
   PerformanceTimer,
+  // Rate limiting
   RateLimiter,
+  // Retry logic
+  retryWithBackoff,
+  retryIf,
+  retryWithFixedDelay,
+  shouldRetryNetworkError,
+  createRetryPredicate,
+  // Validation
+  validateModelName,
+  validateApiKey,
+  validateSchema,
+  validatePrompt,
+  validateTimeout,
+  isValidObject,
+  validateRequiredFields,
+  // Environment
+  getRequiredEnv,
+  getOptionalEnv,
+  getEnvNumber,
+  getEnvBoolean,
+  loadGeminiEnv,
+  getApiKeyFromEnv,
+  isDevelopment,
+  isDebugEnabled,
+  validateEnv,
+  getGeminiConfigFromEnv,
+  // Async state management
+  executeWithState,
+  createDebouncedAsync,
+  createMemoizedAsync,
 } from "./infrastructure/utils";
 
 export type {
   PerformanceMetrics,
   RateLimiterOptions,
+  RetryOptions,
+  RetryResult,
+  EnvConfig,
+  AsyncStateCallbacks,
+  AsyncStateSetters,
+  AsyncStateConfig,
 } from "./infrastructure/utils";
 
 // Hooks

package/src/infrastructure/services/gemini-client-core.service.ts

@@ -1,6 +1,7 @@
 import { GoogleGenerativeAI, type GenerativeModel } from "@google/generative-ai";
 import { DEFAULT_MODELS } from "../../domain/entities";
 import type { GeminiConfig } from "../../domain/entities";
+import { validateModelName, validateApiKey } from "../utils/validation.util";
 
 const DEFAULT_CONFIG: Partial<GeminiConfig> = {
   textModel: DEFAULT_MODELS.TEXT,
@@ -11,11 +12,19 @@ class GeminiClientCoreService {
   private config: GeminiConfig | null = null;
   private initialized = false;
 
+  /**
+   * Initialize the Gemini client with configuration
+   *
+   * @throws {Error} If already initialized or API key is invalid
+   */
   initialize(config: GeminiConfig): void {
     if (this.initialized) {
       throw new Error("Gemini client already initialized. Call reset() before re-initializing with new config.");
     }
 
+    // Validate API key
+    validateApiKey(config.apiKey);
+
     this.client = new GoogleGenerativeAI(config.apiKey);
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.initialized = true;
@@ -39,19 +48,6 @@ class GeminiClientCoreService {
     }
   }
 
-  /**
-   * Validate model name format (allows any valid model string)
-   */
-  private validateModel(modelName: string): void {
-    if (!modelName || typeof modelName !== "string" || modelName.trim().length === 0) {
-      throw new Error(`Invalid model name: "${modelName}". Model name must be a non-empty string.`);
-    }
-
-    // Check for valid model format (starts with gemini-)
-    if (!modelName.startsWith("gemini-")) {
-      throw new Error(`Invalid model name: "${modelName}". Gemini models should start with "gemini-".`);
-    }
-  }
 
   getModel(modelName?: string): GenerativeModel {
     this.validateInitialization();
@@ -62,8 +58,8 @@ class GeminiClientCoreService {
 
     const effectiveModel = modelName || this.config?.textModel || DEFAULT_MODELS.TEXT;
 
-    // Validate model name format (not against hardcoded list)
-    this.validateModel(effectiveModel);
+    // Validate model name format
+    validateModelName(effectiveModel);
 
     return this.client.getGenerativeModel({ model: effectiveModel });
   }

package/src/infrastructure/services/gemini-provider.ts

@@ -2,6 +2,7 @@
 import type { GeminiConfig } from "../../domain/entities";
 import { geminiClientCoreService } from "./gemini-client-core.service";
 import { geminiStructuredTextService } from "./gemini-structured-text.service";
+import { validatePrompt } from "../utils/validation.util";
 
 export type GeminiProviderConfig = GeminiConfig;
 
@@ -9,6 +10,11 @@ export class GeminiProvider {
   readonly providerId = "gemini";
   readonly providerName = "Google Gemini";
 
+  /**
+   * Initialize the Gemini provider
+   *
+   * @throws {Error} If already initialized or configuration is invalid
+   */
   initialize(config: GeminiProviderConfig): void {
     if (geminiClientCoreService.isInitialized()) {
       throw new Error("Provider already initialized. Call reset() before re-initializing with new config.");
@@ -16,22 +22,39 @@ export class GeminiProvider {
     geminiClientCoreService.initialize(config);
   }
 
+  /**
+   * Check if provider is initialized
+   */
   isInitialized(): boolean {
     return geminiClientCoreService.isInitialized();
   }
 
+  /**
+   * Reset the provider to uninitialized state
+   */
   reset(): void {
     geminiClientCoreService.reset();
   }
 
   /**
    * Generate structured JSON response
+   *
+   * @throws {GeminiError} For API-specific errors
+   * @throws {Error} For validation or network errors
    */
   async generateStructuredText<T>(
     prompt: string,
     schema: Record<string, unknown>,
     model: string,
   ): Promise<T> {
+    // Validate inputs
+    validatePrompt(prompt);
+
+    // Check if initialized
+    if (!this.isInitialized()) {
+      throw new Error("Provider not initialized. Call initialize() first.");
+    }
+
     return geminiStructuredTextService.generateStructuredText<T>(model, prompt, schema);
   }
 }

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

@@ -1,5 +1,8 @@
 
 import { geminiClientCoreService } from "./gemini-client-core.service";
+import { toSdkContent } from "../utils/content-mapper.util";
+import { createGeminiError } from "../utils/error-mapper.util";
+import { telemetryHooks } from "../telemetry";
 import type {
   GeminiContent,
   GeminiGenerationConfig,
@@ -8,6 +11,18 @@ import type {
 class GeminiStreamingService {
   /**
    * Stream content generation
+   *
+   * @throws {GeminiError} For API-specific errors
+   * @throws {Error} For validation or network errors
+   *
+   * @example
+   * ```ts
+   * const fullText = await streamContent(
+   *   "gemini-2.5-flash-lite",
+   *   [{ parts: [{ text: "Hello" }], role: "user" }],
+   *   (chunk) => console.log(chunk)
+   * );
+   * ```
    */
   async streamContent(
     model: string,
@@ -16,33 +31,76 @@ class GeminiStreamingService {
     generationConfig?: GeminiGenerationConfig,
     signal?: AbortSignal,
   ): Promise<string> {
-    const genModel = geminiClientCoreService.getModel(model);
+    // Validate input
+    if (!contents || contents.length === 0) {
+      throw new Error("Contents array cannot be empty");
+    }
+
+    if (typeof onChunk !== "function") {
+      throw new Error("onChunk must be a function");
+    }
 
-    const sdkContents = contents.map((content) => ({
-      role: content.role || "user",
-      parts: content.parts.map((part) => ({ text: part.text })),
-    }));
+    // Check for early abort
+    if (signal?.aborted) {
+      throw new Error("Stream generation was aborted");
+    }
+
+    try {
+      const genModel = geminiClientCoreService.getModel(model);
+      const sdkContents = toSdkContent(contents);
 
-    const requestOptions = {
-      contents: sdkContents as Parameters<typeof genModel.generateContentStream>[0] extends { contents: infer C } ? C : never,
-      generationConfig,
-    };
+      const requestOptions = {
+        contents: sdkContents as Parameters<typeof genModel.generateContentStream>[0] extends { contents: infer C } ? C : never,
+        generationConfig,
+      };
 
-    const result = signal
-      ? await genModel.generateContentStream(requestOptions, { signal })
-      : await genModel.generateContentStream(requestOptions);
+      const result = signal
+        ? await genModel.generateContentStream(requestOptions, { signal })
+        : await genModel.generateContentStream(requestOptions);
 
-    let fullText = "";
+      let fullText = "";
 
-    for await (const chunk of result.stream) {
-      const chunkText = chunk.text();
-      if (chunkText) {
-        fullText += chunkText;
-        onChunk(chunkText);
+      for await (const chunk of result.stream) {
+        try {
+          const chunkText = chunk.text();
+          if (chunkText) {
+            fullText += chunkText;
+            // Safely call onChunk - errors in callback won't break the stream
+            try {
+              onChunk(chunkText);
+            } catch (callbackError) {
+              try {
+                telemetryHooks.logError(model, callbackError instanceof Error ? callbackError : new Error(String(callbackError)), "stream-callback");
+              } catch {
+                // Silently ignore telemetry errors to prevent breaking the stream
+              }
+            }
+          }
+        } catch (chunkError) {
+          // Log chunk error via telemetry, but don't let telemetry errors break the stream
+          try {
+            telemetryHooks.logError(model, chunkError instanceof Error ? chunkError : new Error(String(chunkError)), "stream-chunk");
+          } catch {
+            // Silently ignore telemetry errors
+          }
+        }
       }
-    }
 
-    return fullText;
+      return fullText;
+    } catch (error) {
+      // Re-throw as GeminiError if it's an API error
+      if (error instanceof Error && error.name === "GeminiError") {
+        throw error;
+      }
+
+      // Check for abort error
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Stream generation was aborted");
+      }
+
+      // Wrap other errors
+      throw createGeminiError(error);
+    }
   }
 }
 

package/src/infrastructure/services/gemini-structured-text.service.ts

@@ -1,5 +1,8 @@
 
 import { geminiTextGenerationService } from "./gemini-text-generation.service";
+import { parseJsonResponse } from "../utils/json-parser.util";
+import { extractTextFromParts } from "../utils/content-mapper.util";
+import { validateSchema } from "../utils/validation.util";
 import type { GenerationConfig } from "@google/generative-ai";
 import type {
   GeminiContent,
@@ -19,15 +22,11 @@ class GeminiStructuredTextService {
     config?: Omit<GeminiGenerationConfig, "responseMimeType" | "responseSchema">,
     signal?: AbortSignal,
   ): Promise<T> {
-    // Validate schema structure before passing to SDK
-    if (!schema || typeof schema !== "object" || Object.keys(schema).length === 0) {
-      throw new Error("Schema must be a non-empty object");
-    }
+    validateSchema(schema);
 
     const generationConfig: GeminiGenerationConfig = {
       ...config,
       responseMimeType: "application/json",
-      // Pass schema directly - Google SDK will validate it
       responseSchema: schema as GenerationConfig["responseSchema"],
     };
 
@@ -55,26 +54,13 @@ class GeminiStructuredTextService {
       throw new Error("No candidates in response");
     }
 
-    let text = "";
-
-    if (candidates[0]?.content?.parts) {
-      text = candidates[0].content.parts
-        .map((part) => "text" in part ? (part.text || "") : "")
-        .join("");
-    }
+    const text = extractTextFromParts(candidates[0].content.parts);
 
     if (!text || text.trim().length === 0) {
       throw new Error("Empty response received from Gemini");
     }
 
-    // Clean and parse JSON (remove markdown code blocks if present)
-    const cleanedText = text.replace(/```json\n?/g, "").replace(/```\n?/g, "").trim();
-
-    try {
-      return JSON.parse(cleanedText) as T;
-    } catch (error) {
-      throw new Error(`Failed to parse structured response: ${error instanceof Error ? error.message : String(error)}. Cleaned text: ${cleanedText.substring(0, 200)}...`);
-    }
+    return parseJsonResponse<T>(text);
   }
 }