@umituz/react-native-ai-gemini-provider 1.0.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@umituz/react-native-ai-gemini-provider",
+  "version": "1.0.0",
+  "description": "Google Gemini AI provider for React Native applications",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix"
+  },
+  "keywords": [
+    "react-native",
+    "ai",
+    "gemini",
+    "google",
+    "generation",
+    "llm"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/react-native-ai-gemini-provider.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.3.0"
+  }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Gemini Error Types
+ * Error classification for Gemini API
+ */
+
+export enum GeminiErrorType {
+  NETWORK = "NETWORK",
+  RATE_LIMIT = "RATE_LIMIT",
+  AUTHENTICATION = "AUTHENTICATION",
+  VALIDATION = "VALIDATION",
+  SAFETY = "SAFETY",
+  SERVER = "SERVER",
+  TIMEOUT = "TIMEOUT",
+  QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+  MODEL_NOT_FOUND = "MODEL_NOT_FOUND",
+  UNKNOWN = "UNKNOWN",
+}
+
+export interface GeminiErrorInfo {
+  type: GeminiErrorType;
+  messageKey: string;
+  retryable: boolean;
+  originalError?: unknown;
+  statusCode?: number;
+}
+
+export interface GeminiApiError {
+  error?: {
+    code?: number;
+    message?: string;
+    status?: string;
+    details?: Array<{
+      "@type"?: string;
+      reason?: string;
+      domain?: string;
+      metadata?: Record<string, string>;
+    }>;
+  };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Gemini Provider Types
+ * Configuration and response types for Google Gemini AI
+ */
+
+export interface GeminiConfig {
+  apiKey: string;
+  baseUrl?: string;
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  defaultTimeoutMs?: number;
+  defaultModel?: string;
+}
+
+export interface GeminiGenerationConfig {
+  temperature?: number;
+  topK?: number;
+  topP?: number;
+  maxOutputTokens?: number;
+  stopSequences?: string[];
+}
+
+export interface GeminiSafetySettings {
+  category: GeminiHarmCategory;
+  threshold: GeminiHarmBlockThreshold;
+}
+
+export type GeminiHarmCategory =
+  | "HARM_CATEGORY_HARASSMENT"
+  | "HARM_CATEGORY_HATE_SPEECH"
+  | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
+  | "HARM_CATEGORY_DANGEROUS_CONTENT";
+
+export type GeminiHarmBlockThreshold =
+  | "BLOCK_NONE"
+  | "BLOCK_LOW_AND_ABOVE"
+  | "BLOCK_MEDIUM_AND_ABOVE"
+  | "BLOCK_ONLY_HIGH";
+
+export interface GeminiContent {
+  parts: GeminiPart[];
+  role?: "user" | "model";
+}
+
+export type GeminiPart =
+  | { text: string }
+  | { inlineData: { mimeType: string; data: string } }
+  | { fileData: { mimeType: string; fileUri: string } };
+
+export interface GeminiRequest {
+  contents: GeminiContent[];
+  generationConfig?: GeminiGenerationConfig;
+  safetySettings?: GeminiSafetySettings[];
+}
+
+export interface GeminiResponse {
+  candidates?: GeminiCandidate[];
+  promptFeedback?: GeminiPromptFeedback;
+  usageMetadata?: GeminiUsageMetadata;
+}
+
+export interface GeminiCandidate {
+  content: GeminiContent;
+  finishReason?: GeminiFinishReason;
+  safetyRatings?: GeminiSafetyRating[];
+  index?: number;
+}
+
+export type GeminiFinishReason =
+  | "FINISH_REASON_UNSPECIFIED"
+  | "STOP"
+  | "MAX_TOKENS"
+  | "SAFETY"
+  | "RECITATION"
+  | "OTHER";
+
+export interface GeminiSafetyRating {
+  category: GeminiHarmCategory;
+  probability: "NEGLIGIBLE" | "LOW" | "MEDIUM" | "HIGH";
+  blocked?: boolean;
+}
+
+export interface GeminiPromptFeedback {
+  blockReason?: "BLOCK_REASON_UNSPECIFIED" | "SAFETY" | "OTHER";
+  safetyRatings?: GeminiSafetyRating[];
+}
+
+export interface GeminiUsageMetadata {
+  promptTokenCount?: number;
+  candidatesTokenCount?: number;
+  totalTokenCount?: number;
+}
+
+export interface GeminiModel {
+  id: string;
+  name: string;
+  displayName: string;
+  description?: string;
+  inputTokenLimit?: number;
+  outputTokenLimit?: number;
+  supportedCapabilities?: string[];
+}

package/src/domain/entities/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Domain Entities
+ */
+
+export * from "./gemini.types";
+export * from "./error.types";

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @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
+// =============================================================================
+
+export type {
+  GeminiConfig,
+  GeminiGenerationConfig,
+  GeminiSafetySettings,
+  GeminiHarmCategory,
+  GeminiHarmBlockThreshold,
+  GeminiContent,
+  GeminiPart,
+  GeminiRequest,
+  GeminiResponse,
+  GeminiCandidate,
+  GeminiFinishReason,
+  GeminiSafetyRating,
+  GeminiPromptFeedback,
+  GeminiUsageMetadata,
+  GeminiModel,
+} from "./domain/entities";
+
+export { GeminiErrorType } from "./domain/entities";
+
+export type {
+  GeminiErrorInfo,
+  GeminiApiError,
+} from "./domain/entities";
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Services
+// =============================================================================
+
+export {
+  geminiClientService,
+  geminiProviderService,
+} from "./infrastructure/services";
+
+export type {
+  AIProviderConfig,
+  JobSubmission,
+  JobStatus,
+  SubscribeOptions,
+} from "./infrastructure/services";
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Utils
+// =============================================================================
+
+export {
+  mapGeminiError,
+  isGeminiErrorRetryable,
+  categorizeGeminiError,
+} from "./infrastructure/utils";
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export { useGemini } from "./presentation/hooks";
+
+export type {
+  UseGeminiOptions,
+  UseGeminiReturn,
+} from "./presentation/hooks";

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

@@ -0,0 +1,276 @@
+/**
+ * Gemini Client Service
+ * Google Gemini AI client wrapper
+ */
+
+import type {
+  GeminiConfig,
+  GeminiRequest,
+  GeminiResponse,
+  GeminiContent,
+  GeminiGenerationConfig,
+} from "../../domain/entities";
+
+declare const __DEV__: boolean;
+
+const DEFAULT_CONFIG: Partial<GeminiConfig> = {
+  baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+  maxRetries: 3,
+  baseDelay: 1000,
+  maxDelay: 10000,
+  defaultTimeoutMs: 60000,
+  defaultModel: "gemini-1.5-flash",
+};
+
+class GeminiClientService {
+  private apiKey: string | null = null;
+  private config: GeminiConfig | null = null;
+  private initialized = false;
+
+  initialize(config: GeminiConfig): void {
+    this.apiKey = config.apiKey;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.initialized = true;
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[Gemini] Client initialized");
+    }
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  getConfig(): GeminiConfig | null {
+    return this.config;
+  }
+
+  private validateInitialization(): void {
+    if (!this.apiKey || !this.initialized) {
+      throw new Error(
+        "Gemini client not initialized. Call initialize() first.",
+      );
+    }
+  }
+
+  private getEndpoint(model: string, action: string): string {
+    const baseUrl = this.config?.baseUrl ?? DEFAULT_CONFIG.baseUrl;
+    return `${baseUrl}/models/${model}:${action}?key=${this.apiKey}`;
+  }
+
+  private async request<T>(
+    endpoint: string,
+    body: unknown,
+    timeoutMs?: number,
+  ): Promise<T> {
+    const timeout = timeoutMs ?? this.config?.defaultTimeoutMs ?? 60000;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        let errorData: { error?: { message?: string } } = {};
+        try {
+          errorData = (await response.json()) as { error?: { message?: string } };
+        } catch {
+          // Ignore JSON parse errors for error responses
+        }
+        const errorMessage = errorData?.error?.message ?? `HTTP ${response.status}`;
+        const error = new Error(errorMessage);
+        (error as unknown as Record<string, unknown>).status = response.status;
+        (error as unknown as Record<string, unknown>).response = errorData;
+        throw error;
+      }
+
+      return response.json() as Promise<T>;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  async generateContent(
+    model: string,
+    contents: GeminiContent[],
+    generationConfig?: GeminiGenerationConfig,
+  ): Promise<GeminiResponse> {
+    this.validateInitialization();
+
+    const effectiveModel = model || this.config?.defaultModel || "gemini-1.5-flash";
+    const endpoint = this.getEndpoint(effectiveModel, "generateContent");
+
+    const body: GeminiRequest = {
+      contents,
+      generationConfig,
+    };
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[Gemini] Generate content:", { model: effectiveModel });
+    }
+
+    return this.request<GeminiResponse>(endpoint, body);
+  }
+
+  async generateText(
+    model: string,
+    prompt: string,
+    config?: GeminiGenerationConfig,
+  ): Promise<string> {
+    const contents: GeminiContent[] = [
+      { parts: [{ text: prompt }], role: "user" },
+    ];
+
+    const response = await this.generateContent(model, contents, config);
+    return this.extractTextFromResponse(response);
+  }
+
+  async generateWithImage(
+    model: string,
+    prompt: string,
+    imageBase64: string,
+    mimeType: string,
+    config?: GeminiGenerationConfig,
+  ): Promise<string> {
+    const contents: GeminiContent[] = [
+      {
+        parts: [
+          { text: prompt },
+          { inlineData: { mimeType, data: imageBase64 } },
+        ],
+        role: "user",
+      },
+    ];
+
+    const response = await this.generateContent(model, contents, config);
+    return this.extractTextFromResponse(response);
+  }
+
+  private extractTextFromResponse(response: GeminiResponse): string {
+    const candidate = response.candidates?.[0];
+
+    if (!candidate) {
+      throw new Error("No response candidates");
+    }
+
+    if (candidate.finishReason === "SAFETY") {
+      throw new Error("Content blocked by safety filters");
+    }
+
+    const textPart = candidate.content.parts.find(
+      (p): p is { text: string } => "text" in p,
+    );
+
+    if (!textPart) {
+      throw new Error("No text in response");
+    }
+
+    return textPart.text;
+  }
+
+  async streamContent(
+    model: string,
+    contents: GeminiContent[],
+    onChunk: (text: string) => void,
+    generationConfig?: GeminiGenerationConfig,
+  ): Promise<string> {
+    this.validateInitialization();
+
+    const effectiveModel = model || this.config?.defaultModel || "gemini-1.5-flash";
+    const endpoint = this.getEndpoint(effectiveModel, "streamGenerateContent");
+
+    const body: GeminiRequest = {
+      contents,
+      generationConfig,
+    };
+
+    const timeout = this.config?.defaultTimeoutMs ?? 60000;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const reader = response.body?.getReader();
+      if (!reader) {
+        throw new Error("No response body");
+      }
+
+      const decoder = new TextDecoder();
+      let fullText = "";
+      let reading = true;
+
+      while (reading) {
+        const { done, value } = await reader.read();
+
+        if (done) {
+          reading = false;
+          continue;
+        }
+
+        const chunk = decoder.decode(value, { stream: true });
+        const text = this.parseStreamChunk(chunk);
+
+        if (text) {
+          fullText += text;
+          onChunk(text);
+        }
+      }
+
+      return fullText;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private parseStreamChunk(chunk: string): string {
+    try {
+      const lines = chunk.split("\n").filter((l) => l.trim());
+      let text = "";
+
+      for (const line of lines) {
+        if (line.startsWith("data: ")) {
+          const data = JSON.parse(line.slice(6)) as GeminiResponse;
+          const candidate = data.candidates?.[0];
+          const textPart = candidate?.content.parts.find(
+            (p): p is { text: string } => "text" in p,
+          );
+          if (textPart) {
+            text += textPart.text;
+          }
+        }
+      }
+
+      return text;
+    } catch {
+      return "";
+    }
+  }
+
+  reset(): void {
+    this.apiKey = null;
+    this.config = null;
+    this.initialized = false;
+  }
+}
+
+export const geminiClientService = new GeminiClientService();

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

@@ -0,0 +1,250 @@
+/**
+ * Gemini Provider Service
+ * IAIProvider implementation for Google Gemini
+ */
+
+import type { GeminiConfig, GeminiContent } from "../../domain/entities";
+import { geminiClientService } from "./gemini-client.service";
+
+declare const __DEV__: boolean;
+
+export interface AIProviderConfig {
+  apiKey: string;
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  defaultTimeoutMs?: number;
+}
+
+export interface JobSubmission {
+  requestId: string;
+  statusUrl?: string;
+  responseUrl?: string;
+}
+
+export interface JobStatus {
+  status: "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED" | "FAILED";
+  logs?: Array<{ message: string; level: string; timestamp?: string }>;
+  queuePosition?: number;
+  eta?: number;
+}
+
+export interface SubscribeOptions<T = unknown> {
+  timeoutMs?: number;
+  onQueueUpdate?: (status: JobStatus) => void;
+  onProgress?: (progress: number) => void;
+  onResult?: (result: T) => void;
+}
+
+interface PendingJob {
+  model: string;
+  input: Record<string, unknown>;
+  status: JobStatus["status"];
+  result?: unknown;
+  error?: string;
+}
+
+class GeminiProviderService {
+  readonly providerId = "gemini";
+  readonly providerName = "Google Gemini";
+
+  private pendingJobs: Map<string, PendingJob> = new Map();
+  private jobCounter = 0;
+
+  initialize(config: AIProviderConfig): void {
+    const geminiConfig: GeminiConfig = {
+      apiKey: config.apiKey,
+      maxRetries: config.maxRetries,
+      baseDelay: config.baseDelay,
+      maxDelay: config.maxDelay,
+      defaultTimeoutMs: config.defaultTimeoutMs,
+    };
+
+    geminiClientService.initialize(geminiConfig);
+  }
+
+  isInitialized(): boolean {
+    return geminiClientService.isInitialized();
+  }
+
+  submitJob(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<JobSubmission> {
+    const requestId = this.generateRequestId();
+
+    this.pendingJobs.set(requestId, {
+      model,
+      input,
+      status: "IN_QUEUE",
+    });
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.log("[GeminiProvider] Job submitted:", { requestId, model });
+    }
+
+    this.processJobAsync(requestId).catch((error) => {
+      if (typeof __DEV__ !== "undefined" && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.error("[GeminiProvider] Job failed:", error);
+      }
+    });
+
+    return Promise.resolve({
+      requestId,
+      statusUrl: undefined,
+      responseUrl: undefined,
+    });
+  }
+
+  getJobStatus(_model: string, requestId: string): Promise<JobStatus> {
+    const job = this.pendingJobs.get(requestId);
+
+    if (!job) {
+      return Promise.resolve({ status: "FAILED" });
+    }
+
+    return Promise.resolve({ status: job.status });
+  }
+
+  getJobResult<T = unknown>(_model: string, requestId: string): Promise<T> {
+    const job = this.pendingJobs.get(requestId);
+
+    if (!job) {
+      return Promise.reject(new Error(`Job ${requestId} not found`));
+    }
+
+    if (job.status !== "COMPLETED") {
+      return Promise.reject(new Error(`Job ${requestId} not completed`));
+    }
+
+    if (job.error) {
+      return Promise.reject(new Error(job.error));
+    }
+
+    this.pendingJobs.delete(requestId);
+
+    return Promise.resolve(job.result as T);
+  }
+
+  async subscribe<T = unknown>(
+    model: string,
+    input: Record<string, unknown>,
+    options?: SubscribeOptions<T>,
+  ): Promise<T> {
+    options?.onQueueUpdate?.({ status: "IN_QUEUE" });
+
+    const result = await this.executeGeneration<T>(model, input);
+
+    options?.onQueueUpdate?.({ status: "COMPLETED" });
+    options?.onResult?.(result);
+
+    return result;
+  }
+
+  async run<T = unknown>(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<T> {
+    return this.executeGeneration<T>(model, input);
+  }
+
+  reset(): void {
+    geminiClientService.reset();
+    this.pendingJobs.clear();
+    this.jobCounter = 0;
+  }
+
+  private generateRequestId(): string {
+    this.jobCounter++;
+    return `gemini-${Date.now()}-${this.jobCounter}`;
+  }
+
+  private async processJobAsync(requestId: string): Promise<void> {
+    const job = this.pendingJobs.get(requestId);
+
+    if (!job) return;
+
+    job.status = "IN_PROGRESS";
+
+    try {
+      const result = await this.executeGeneration(job.model, job.input);
+      job.result = result;
+      job.status = "COMPLETED";
+    } catch (error) {
+      job.status = "FAILED";
+      job.error = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  private async executeGeneration<T>(
+    model: string,
+    input: Record<string, unknown>,
+  ): Promise<T> {
+    const contents = this.buildContents(input);
+
+    const response = await geminiClientService.generateContent(
+      model,
+      contents,
+      input.generationConfig as undefined,
+    );
+
+    return this.formatResponse<T>(response, input);
+  }
+
+  private buildContents(input: Record<string, unknown>): GeminiContent[] {
+    const contents: GeminiContent[] = [];
+
+    if (typeof input.prompt === "string") {
+      const parts: GeminiContent["parts"] = [{ text: input.prompt }];
+
+      if (input.image_url && typeof input.image_url === "string") {
+        const base64Match = input.image_url.match(
+          /^data:([^;]+);base64,(.+)$/,
+        );
+
+        if (base64Match) {
+          parts.push({
+            inlineData: {
+              mimeType: base64Match[1],
+              data: base64Match[2],
+            },
+          });
+        }
+      }
+
+      contents.push({ parts, role: "user" });
+    }
+
+    if (Array.isArray(input.contents)) {
+      contents.push(...(input.contents as GeminiContent[]));
+    }
+
+    return contents;
+  }
+
+  private formatResponse<T>(
+    response: unknown,
+    input: Record<string, unknown>,
+  ): T {
+    const resp = response as {
+      candidates?: Array<{
+        content: { parts: Array<{ text?: string }> };
+      }>;
+    };
+
+    const text = resp.candidates?.[0]?.content.parts.find((p) => p.text)?.text;
+
+    if (input.outputFormat === "text") {
+      return text as T;
+    }
+
+    return {
+      text,
+      response,
+    } as T;
+  }
+}
+
+export const geminiProviderService = new GeminiProviderService();

package/src/infrastructure/services/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Infrastructure Services
+ */
+
+export { geminiClientService } from "./gemini-client.service";
+export { geminiProviderService } from "./gemini-provider.service";
+export type {
+  AIProviderConfig,
+  JobSubmission,
+  JobStatus,
+  SubscribeOptions,
+} from "./gemini-provider.service";

package/src/infrastructure/utils/error-mapper.util.ts

@@ -0,0 +1,114 @@
+/**
+ * Gemini Error Mapper
+ * Maps Gemini API errors to standardized format
+ */
+
+import {
+  GeminiErrorType,
+  type GeminiErrorInfo,
+  type GeminiApiError,
+} from "../../domain/entities";
+
+const ERROR_PATTERNS: Array<{
+  pattern: RegExp | 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", "blocked", "harmful"],
+    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,
+  },
+];
+
+function getStatusCode(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 GeminiApiError | undefined;
+    if (response?.error?.code) return response.error.code;
+  }
+  return undefined;
+}
+
+function matchesPattern(message: string, patterns: string[]): boolean {
+  const lower = message.toLowerCase();
+  return patterns.some((p) => lower.includes(p.toLowerCase()));
+}
+
+export function mapGeminiError(error: unknown): GeminiErrorInfo {
+  const message = error instanceof Error ? error.message : String(error);
+  const statusCode = getStatusCode(error);
+
+  for (const { pattern, type, retryable } of ERROR_PATTERNS) {
+    const patterns = Array.isArray(pattern) ? pattern : [pattern.source];
+
+    if (matchesPattern(message, patterns)) {
+      return {
+        type,
+        messageKey: `error.gemini.${type.toLowerCase()}`,
+        retryable,
+        originalError: error,
+        statusCode,
+      };
+    }
+  }
+
+  return {
+    type: GeminiErrorType.UNKNOWN,
+    messageKey: "error.gemini.unknown",
+    retryable: false,
+    originalError: error,
+    statusCode,
+  };
+}
+
+export function isGeminiErrorRetryable(error: unknown): boolean {
+  return mapGeminiError(error).retryable;
+}
+
+export function categorizeGeminiError(error: unknown): GeminiErrorType {
+  return mapGeminiError(error).type;
+}

package/src/infrastructure/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Infrastructure Utils
+ */
+
+export {
+  mapGeminiError,
+  isGeminiErrorRetryable,
+  categorizeGeminiError,
+} from "./error-mapper.util";

package/src/presentation/hooks/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Presentation Hooks
+ */
+
+export { useGemini } from "./use-gemini";
+export type { UseGeminiOptions, UseGeminiReturn } from "./use-gemini";

package/src/presentation/hooks/use-gemini.ts

@@ -0,0 +1,124 @@
+/**
+ * useGemini Hook
+ * React hook for Gemini AI generation
+ */
+
+import { useState, useCallback, useRef } from "react";
+import type { GeminiGenerationConfig } from "../../domain/entities";
+import { geminiClientService } from "../../infrastructure/services";
+
+export interface UseGeminiOptions {
+  model?: string;
+  generationConfig?: GeminiGenerationConfig;
+  onSuccess?: (result: string) => void;
+  onError?: (error: string) => void;
+}
+
+export interface UseGeminiReturn {
+  generate: (prompt: string) => Promise<void>;
+  generateWithImage: (
+    prompt: string,
+    imageBase64: string,
+    mimeType: string,
+  ) => Promise<void>;
+  result: string | null;
+  isGenerating: boolean;
+  error: string | null;
+  reset: () => void;
+}
+
+export function useGemini(options: UseGeminiOptions = {}): UseGeminiReturn {
+  const [result, setResult] = useState<string | null>(null);
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const abortRef = useRef(false);
+
+  const generate = useCallback(
+    async (prompt: string) => {
+      abortRef.current = false;
+      setIsGenerating(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        const model = options.model ?? "gemini-1.5-flash";
+        const text = await geminiClientService.generateText(
+          model,
+          prompt,
+          options.generationConfig,
+        );
+
+        if (abortRef.current) return;
+
+        setResult(text);
+        options.onSuccess?.(text);
+      } catch (err) {
+        if (abortRef.current) return;
+
+        const errorMessage =
+          err instanceof Error ? err.message : "Generation failed";
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+      } finally {
+        if (!abortRef.current) {
+          setIsGenerating(false);
+        }
+      }
+    },
+    [options],
+  );
+
+  const generateWithImage = useCallback(
+    async (prompt: string, imageBase64: string, mimeType: string) => {
+      abortRef.current = false;
+      setIsGenerating(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        const model = options.model ?? "gemini-1.5-flash";
+        const text = await geminiClientService.generateWithImage(
+          model,
+          prompt,
+          imageBase64,
+          mimeType,
+          options.generationConfig,
+        );
+
+        if (abortRef.current) return;
+
+        setResult(text);
+        options.onSuccess?.(text);
+      } catch (err) {
+        if (abortRef.current) return;
+
+        const errorMessage =
+          err instanceof Error ? err.message : "Generation failed";
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+      } finally {
+        if (!abortRef.current) {
+          setIsGenerating(false);
+        }
+      }
+    },
+    [options],
+  );
+
+  const reset = useCallback(() => {
+    abortRef.current = true;
+    setResult(null);
+    setIsGenerating(false);
+    setError(null);
+  }, []);
+
+  return {
+    generate,
+    generateWithImage,
+    result,
+    isGenerating,
+    error,
+    reset,
+  };
+}