@umituz/react-native-ai-gemini-provider 3.0.41 → 3.0.43

package/src/infrastructure/external/gemini-sdk.adapter.ts

@@ -0,0 +1,143 @@
+/**
+ * Gemini SDK Adapter
+ * Wrapper around Google Gemini SDK
+ */
+
+import {
+  GoogleGenerativeAI,
+  HarmCategory,
+  HarmBlockThreshold,
+  type GenerativeModel,
+  type SafetySetting,
+} from "@google/generative-ai";
+import { DEFAULT_MODELS } from "../../domain/entities";
+import type { GeminiModelOptions } from "../../domain/entities";
+
+/**
+ * Permissive safety settings (BLOCK_NONE for all categories)
+ */
+const PERMISSIVE_SAFETY: SafetySetting[] = [
+  {
+    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+];
+
+export class GeminiSDKAdapter {
+  private client: GoogleGenerativeAI | null = null;
+  private initialized = false;
+
+  /**
+   * Initialize the SDK with API key
+   */
+  initialize(apiKey: string): void {
+    if (!apiKey || apiKey.length < 10) {
+      throw new Error("API key must be at least 10 characters");
+    }
+
+    if (!apiKey.startsWith("AIza")) {
+      throw new Error('Invalid API key format. Must start with "AIza"');
+    }
+
+    this.client = new GoogleGenerativeAI(apiKey);
+    this.initialized = true;
+  }
+
+  /**
+   * Get a configured GenerativeModel
+   */
+  getModel(options?: string | GeminiModelOptions): GenerativeModel {
+    if (!this.client || !this.initialized) {
+      throw new Error("SDK not initialized. Call initialize() first.");
+    }
+
+    // Normalize options
+    const opts: GeminiModelOptions =
+      typeof options === "string" ? { model: options } : options ?? {};
+
+    const effectiveModel = opts.model || DEFAULT_MODELS.TEXT;
+
+    if (!effectiveModel.startsWith("gemini-")) {
+      throw new Error('Model name must start with "gemini-"');
+    }
+
+    // Map safety settings
+    const sdkSafety = opts.safetySettings
+      ? this.mapSafetySettings(opts.safetySettings)
+      : PERMISSIVE_SAFETY;
+
+    return this.client.getGenerativeModel({
+      model: effectiveModel,
+      ...(opts.systemInstruction && {
+        systemInstruction: opts.systemInstruction,
+      }),
+      safetySettings: sdkSafety,
+    });
+  }
+
+  /**
+   * Map domain safety settings to SDK format
+   */
+  private mapSafetySettings(
+    settings: GeminiModelOptions["safetySettings"]
+  ): SafetySetting[] {
+    if (!settings) return PERMISSIVE_SAFETY;
+
+    return settings.map((s) => {
+      const validCategories = [
+        HarmCategory.HARM_CATEGORY_HARASSMENT,
+        HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+        HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+      ];
+
+      const validThresholds = [
+        HarmBlockThreshold.BLOCK_NONE,
+        HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+        HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
+        HarmBlockThreshold.BLOCK_ONLY_HIGH,
+      ];
+
+      const category = validCategories.includes(
+        s.category as unknown as HarmCategory
+      )
+        ? (s.category as unknown as HarmCategory)
+        : HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT;
+
+      const threshold = validThresholds.includes(
+        s.threshold as unknown as HarmBlockThreshold
+      )
+        ? (s.threshold as unknown as HarmBlockThreshold)
+        : HarmBlockThreshold.BLOCK_NONE;
+
+      return { category, threshold };
+    });
+  }
+
+  /**
+   * Check if SDK is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Reset the SDK
+   */
+  reset(): void {
+    this.client = null;
+    this.initialized = false;
+  }
+}

package/src/infrastructure/external/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure External
+ * SDK adapter and client
+ */
+
+export { GeminiSDKAdapter } from "./gemini-sdk.adapter";
+export { GeminiClient, geminiClient } from "./gemini-client.singleton";

package/src/infrastructure/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Infrastructure Layer
+ * External integrations and repository implementations
+ */
+
+// Mappers
+export * from "./mappers";
+
+// External Services
+export * from "./external";
+
+// Repository Implementations
+export * from "./repositories";
+
+// Utilities
+export { parseJsonResponse } from "./utils/json-parser.util";

package/src/infrastructure/mappers/content.mapper.ts

@@ -0,0 +1,80 @@
+/**
+ * Content Mapper
+ * Transforms between domain and SDK content formats
+ */
+
+import type { Part } from "@google/generative-ai";
+import type { GeminiContent, GeminiPart } from "../../domain/entities";
+
+export class ContentMapper {
+  /**
+   * Convert domain content to SDK format
+   */
+  toSdk(content: GeminiContent): { role: string; parts: Part[] } {
+    return {
+      role: content.role || "user",
+      parts: content.parts.map(this.mapPartToSdk),
+    };
+  }
+
+  /**
+   * Convert domain content array to SDK format
+   */
+  toSdkArray(contents: GeminiContent[]): Array<{ role: string; parts: Part[] }> {
+    return contents.map((c) => this.toSdk(c));
+  }
+
+  /**
+   * Convert SDK content to domain format
+   */
+  toDomain(sdk: { role: string; parts: Part[] }): GeminiContent {
+    return {
+      role: sdk.role as "user" | "model",
+      parts: sdk.parts.map(this.mapSdkPartToDomain),
+    };
+  }
+
+  /**
+   * Map a single domain part to SDK format
+   */
+  private mapPartToSdk(part: GeminiPart): Part {
+    if ("text" in part) {
+      return { text: part.text };
+    }
+    if ("inlineData" in part) {
+      return { inlineData: part.inlineData };
+    }
+    throw new Error("Unknown part type");
+  }
+
+  /**
+   * Map a single SDK part to domain format
+   */
+  private mapSdkPartToDomain(part: Part): GeminiPart {
+    if ("text" in part && typeof part.text === "string") {
+      return { text: part.text };
+    }
+    if ("inlineData" in part) {
+      return { inlineData: part.inlineData };
+    }
+    return { text: "" };
+  }
+
+  /**
+   * Create a simple text content
+   */
+  createTextContent(text: string, role: "user" | "model" = "user"): GeminiContent {
+    return {
+      parts: [{ text }],
+      role,
+    };
+  }
+
+  /**
+   * Extract text from content parts
+   */
+  extractText(parts: GeminiPart[] | undefined): string {
+    if (!parts || parts.length === 0) return "";
+    return parts.map((p) => ("text" in p ? (p.text || "") : "")).join("");
+  }
+}

package/src/infrastructure/mappers/error.mapper.ts

@@ -0,0 +1,152 @@
+/**
+ * Error Mapper
+ * Maps unknown errors to domain GeminiError
+ */
+
+import { GeminiError, GeminiErrorType } from "../../domain/entities";
+
+const ERROR_PATTERNS: Array<{
+  pattern: string[];
+  type: GeminiErrorType;
+  retryable: boolean;
+}> = [
+  {
+    pattern: ["quota", "resource exhausted", "429"],
+    type: GeminiErrorType.QUOTA_EXCEEDED,
+    retryable: true,
+  },
+  {
+    pattern: ["rate limit", "too many requests"],
+    type: GeminiErrorType.RATE_LIMIT,
+    retryable: true,
+  },
+  {
+    pattern: ["unauthorized", "invalid api key", "401", "403", "permission"],
+    type: GeminiErrorType.AUTHENTICATION,
+    retryable: false,
+  },
+  {
+    pattern: ["safety", "safety filter", "harmful", "blocked by safety"],
+    type: GeminiErrorType.SAFETY,
+    retryable: false,
+  },
+  {
+    pattern: ["model not found", "404", "not found"],
+    type: GeminiErrorType.MODEL_NOT_FOUND,
+    retryable: false,
+  },
+  {
+    pattern: ["network", "fetch failed", "connection", "socket"],
+    type: GeminiErrorType.NETWORK,
+    retryable: true,
+  },
+  {
+    pattern: ["timeout", "timed out"],
+    type: GeminiErrorType.TIMEOUT,
+    retryable: true,
+  },
+  {
+    pattern: ["500", "502", "503", "504", "internal server", "unavailable"],
+    type: GeminiErrorType.SERVER,
+    retryable: true,
+  },
+  {
+    pattern: ["invalid", "bad request", "400"],
+    type: GeminiErrorType.VALIDATION,
+    retryable: false,
+  },
+];
+
+const STATUS_CODE_MAP: Record<
+  number,
+  { type: GeminiErrorType; retryable: boolean }
+> = {
+  400: { type: GeminiErrorType.VALIDATION, retryable: false },
+  401: { type: GeminiErrorType.AUTHENTICATION, retryable: false },
+  403: { type: GeminiErrorType.AUTHENTICATION, retryable: false },
+  404: { type: GeminiErrorType.MODEL_NOT_FOUND, retryable: false },
+  429: { type: GeminiErrorType.RATE_LIMIT, retryable: true },
+  500: { type: GeminiErrorType.SERVER, retryable: true },
+  502: { type: GeminiErrorType.SERVER, retryable: true },
+  503: { type: GeminiErrorType.SERVER, retryable: true },
+  504: { type: GeminiErrorType.SERVER, retryable: true },
+};
+
+export class ErrorMapper {
+  /**
+   * Map unknown error to GeminiError
+   */
+  static map(error: unknown, context: string): GeminiError {
+    if (error instanceof GeminiError) {
+      return error;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    const statusCode = ErrorMapper.extractStatusCode(error);
+
+    // Primary: classify by HTTP status code
+    if (statusCode && STATUS_CODE_MAP[statusCode]) {
+      const { type, retryable } = STATUS_CODE_MAP[statusCode];
+      return GeminiError.fromError(error, {
+        type,
+        messageKey: `error.gemini.${type.toLowerCase()}`,
+        retryable,
+        originalError: error,
+        statusCode,
+      });
+    }
+
+    // Secondary: classify by message pattern
+    for (const { pattern, type, retryable } of ERROR_PATTERNS) {
+      if (ErrorMapper.matchesPattern(message, pattern)) {
+        return GeminiError.fromError(error, {
+          type,
+          messageKey: `error.gemini.${type.toLowerCase()}`,
+          retryable,
+          originalError: error,
+          statusCode,
+        });
+      }
+    }
+
+    // Default: unknown error
+    return GeminiError.fromError(error, {
+      type: GeminiErrorType.UNKNOWN,
+      messageKey: "error.gemini.unknown",
+      retryable: false,
+      originalError: error,
+      statusCode,
+    });
+  }
+
+  /**
+   * Extract HTTP status code from error
+   */
+  private static extractStatusCode(error: unknown): number | undefined {
+    if (error && typeof error === "object") {
+      const err = error as Record<string, unknown>;
+      if (typeof err.status === "number") return err.status;
+      if (typeof err.statusCode === "number") return err.statusCode;
+
+      const response = err.response as
+        | { error?: { code?: number } }
+        | undefined;
+      if (response?.error?.code) return response.error.code;
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if message matches any pattern
+   */
+  private static matchesPattern(message: string, patterns: string[]): boolean {
+    const lower = message.toLowerCase();
+    return patterns.some((pattern) => {
+      const words = pattern.toLowerCase().split(/\s+/);
+      return words.every((word) => {
+        const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return new RegExp(`\\b${escaped}\\b`, "i").test(lower);
+      });
+    });
+  }
+}

package/src/infrastructure/mappers/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure Mappers
+ */
+
+export { ContentMapper } from "./content.mapper";
+export { ResponseMapper } from "./response.mapper";
+export { ErrorMapper } from "./error.mapper";

package/src/infrastructure/mappers/response.mapper.ts

@@ -0,0 +1,165 @@
+/**
+ * Response Mapper
+ * Transforms SDK responses to domain format
+ */
+
+import type {
+  GeminiResponse,
+  GeminiCandidate,
+  GeminiContent,
+  GeminiFinishReason,
+  GeminiHarmCategory,
+  GeminiSafetyRating,
+} from "../../domain/entities";
+
+const VALID_FINISH_REASONS = [
+  "FINISH_REASON_UNSPECIFIED",
+  "STOP",
+  "MAX_TOKENS",
+  "SAFETY",
+  "RECITATION",
+  "OTHER",
+] as const;
+
+const VALID_HARM_CATEGORIES = [
+  "HARM_CATEGORY_HARASSMENT",
+  "HARM_CATEGORY_HATE_SPEECH",
+  "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+  "HARM_CATEGORY_DANGEROUS_CONTENT",
+] as const;
+
+const VALID_PROBABILITIES = ["NEGLIGIBLE", "LOW", "MEDIUM", "HIGH"] as const;
+
+export class ResponseMapper {
+  /**
+   * Convert SDK response to domain format
+   */
+  toDomain(response: {
+    candidates?: Array<{
+      content: { parts: Array<{ text?: string }>; role?: string };
+      finishReason?: string;
+      safetyRatings?: Array<{ category: string; probability: string }>;
+    }>;
+    usageMetadata?: {
+      promptTokenCount?: number;
+      candidatesTokenCount?: number;
+      totalTokenCount?: number;
+    };
+  }): GeminiResponse {
+    return {
+      candidates: response.candidates?.map((c) => this.mapCandidate(c)),
+      usageMetadata: response.usageMetadata
+        ? {
+            promptTokenCount: response.usageMetadata.promptTokenCount,
+            candidatesTokenCount: response.usageMetadata.candidatesTokenCount,
+            totalTokenCount: response.usageMetadata.totalTokenCount,
+          }
+        : undefined,
+    };
+  }
+
+  /**
+   * Map a single candidate
+   */
+  private mapCandidate(
+    candidate: {
+      content: { parts: Array<{ text?: string }>; role?: string };
+      finishReason?: string;
+      safetyRatings?: Array<{ category: string; probability: string }>;
+    }
+  ): GeminiCandidate {
+    return {
+      content: this.mapCandidateContent(candidate.content),
+      finishReason: this.mapFinishReason(candidate.finishReason),
+      safetyRatings: this.mapSafetyRatings(candidate.safetyRatings),
+    };
+  }
+
+  /**
+   * Map candidate content
+   */
+  private mapCandidateContent(content: {
+    parts: Array<{ text?: string }>;
+    role?: string;
+  }): GeminiContent {
+    return {
+      parts: content.parts
+        .filter((p) => p.text)
+        .map((p) => ({ text: p.text || "" })),
+      role: content.role === "user" || content.role === "model" ? content.role : "model",
+    };
+  }
+
+  /**
+   * Map finish reason with validation
+   */
+  private mapFinishReason(value: string | undefined): GeminiFinishReason | undefined {
+    if (!value) return undefined;
+    return VALID_FINISH_REASONS.includes(value as GeminiFinishReason)
+      ? (value as GeminiFinishReason)
+      : undefined;
+  }
+
+  /**
+   * Map safety ratings with validation
+   */
+  private mapSafetyRatings(
+    ratings: Array<{ category: string; probability: string }> | undefined
+  ): GeminiSafetyRating[] | undefined {
+    if (!ratings) return undefined;
+
+    return ratings
+      .filter((r) => this.isValidHarmCategory(r.category) && this.isValidProbability(r.probability))
+      .map((r) => ({
+        category: r.category as GeminiHarmCategory,
+        probability: r.probability as GeminiSafetyRating["probability"],
+      }));
+  }
+
+  /**
+   * Validate harm category
+   */
+  private isValidHarmCategory(value: string): value is GeminiHarmCategory {
+    return VALID_HARM_CATEGORIES.includes(value as GeminiHarmCategory);
+  }
+
+  /**
+   * Validate probability
+   */
+  private isValidProbability(value: string): value is GeminiSafetyRating["probability"] {
+    return VALID_PROBABILITIES.includes(value as GeminiSafetyRating["probability"]);
+  }
+
+  /**
+   * Extract text from response
+   */
+  extractText(response: GeminiResponse): string {
+    if (!response.candidates || response.candidates.length === 0) {
+      throw new Error("No response candidates");
+    }
+
+    const candidate = response.candidates[0];
+
+    // Handle finish reasons
+    if (candidate.finishReason === "SAFETY") {
+      throw new Error("Content blocked by safety filters");
+    }
+    if (candidate.finishReason === "RECITATION") {
+      throw new Error("Content blocked due to recitation concerns");
+    }
+
+    if (!candidate.content?.parts) {
+      throw new Error("No content in response candidate");
+    }
+
+    const textPart = candidate.content.parts.find(
+      (p): p is { text: string } => "text" in p && typeof p.text === "string"
+    );
+
+    if (!textPart) {
+      throw new Error("No text in response");
+    }
+
+    return textPart.text;
+  }
+}

package/src/infrastructure/repositories/base-gemini.repository.ts

@@ -0,0 +1,94 @@
+/**
+ * Base Gemini Repository
+ * Common functionality for all Gemini repositories
+ */
+
+import type { GenerativeModel } from "@google/generative-ai";
+import type { GeminiContent, GeminiGenerationConfig } from "../../domain/entities";
+import { ValidationService } from "../../domain/services/validation.service";
+import { ContentMapper } from "../mappers/content.mapper";
+import { ErrorMapper } from "../mappers/error.mapper";
+
+export abstract class BaseGeminiRepository {
+  protected constructor(
+    protected getModel: (name: string) => GenerativeModel,
+    protected readonly validator: ValidationService,
+    protected readonly contentMapper: ContentMapper
+  ) {}
+
+  /**
+   * Prepare request parameters
+   * @returns SDK model and formatted contents
+   */
+  protected prepareRequest(params: {
+    model: string;
+    contents: GeminiContent[];
+    generationConfig?: GeminiGenerationConfig;
+    signal?: AbortSignal;
+  }): {
+    genModel: GenerativeModel;
+    sdkContents: Array<{ role: string; parts: unknown[] }>;
+    config: GeminiGenerationConfig | undefined;
+    signal: AbortSignal | undefined;
+  } {
+    // Validate inputs
+    this.validator.validateModelName(params.model);
+    this.validator.validateContents(params.contents);
+    this.validator.validateConfig(params.generationConfig);
+
+    // Check abort signal
+    if (params.signal?.aborted) {
+      throw new Error("Request was aborted");
+    }
+
+    // Get SDK model
+    const genModel = this.getModel(params.model);
+
+    // Convert contents to SDK format
+    const sdkContents = this.contentMapper.toSdkArray(params.contents);
+
+    return {
+      genModel,
+      sdkContents,
+      config: params.generationConfig,
+      signal: params.signal,
+    };
+  }
+
+  /**
+   * Create request options for SDK
+   */
+  protected createRequestOptions(
+    sdkContents: Array<{ role: string; parts: unknown[] }>,
+    generationConfig?: GeminiGenerationConfig
+  ): {
+    contents: Array<{ role: string; parts: unknown[] }>;
+    generationConfig?: GeminiGenerationConfig;
+  } {
+    return {
+      contents: sdkContents,
+      generationConfig,
+    };
+  }
+
+  /**
+   * Handle errors consistently
+   */
+  protected handleError(error: unknown, context: string): never {
+    throw ErrorMapper.map(error, context);
+  }
+
+  /**
+   * Execute with automatic error handling
+   */
+  protected async executeWithErrorHandling<T>(
+    operation: () => Promise<T>,
+    context: string
+  ): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      this.handleError(error, context);
+    }
+  }
+}