@umituz/react-native-ai-gemini-provider 3.0.21 → 3.0.23

package/dist/domain/entities/error.types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Categories of errors that can occur with Gemini API
+ */
+export declare 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;
+            domain?: string;
+            metadata?: Record<string, string>;
+        }>;
+    };
+}
+/**
+ * Custom error class for Gemini API errors
+ * Provides structured error information and retry capability
+ */
+export declare 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);
+    /**
+     * Check if this error is retryable
+     * @returns true if the operation can be retried
+     */
+    isRetryable(): boolean;
+    /**
+     * Get the error type
+     * @returns The error category
+     */
+    getErrorType(): GeminiErrorType;
+    /**
+     * 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;
+}

package/dist/domain/entities/gemini.types.d.ts

@@ -0,0 +1,133 @@
+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" | "MAX_TOKENS" | "SAFETY" | "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;
+}
+/**
+ * Safety setting for a single harm category
+ */
+export interface GeminiSafetySetting {
+    category: GeminiHarmCategory;
+    threshold: GeminiHarmBlockThreshold;
+}
+/**
+ * Inline data part for binary content (images, audio)
+ */
+export interface GeminiInlineDataPart {
+    inlineData: {
+        mimeType: string;
+        data: string;
+    };
+}
+/**
+ * A message part that can be text or inline data
+ */
+export type GeminiMessagePart = GeminiPart | GeminiInlineDataPart;
+/**
+ * Options for creating a generative model instance
+ */
+export interface GeminiModelOptions {
+    model?: string;
+    systemInstruction?: string;
+    safetySettings?: GeminiSafetySetting[];
+}
+/**
+ * Configuration for a chat session
+ */
+export interface GeminiChatConfig {
+    /** Model name override */
+    model?: string;
+    /** System instruction for the model */
+    systemInstruction?: string;
+    /** Safety settings (defaults to BLOCK_NONE for all categories) */
+    safetySettings?: GeminiSafetySetting[];
+    /** Generation config (temperature, maxOutputTokens, etc.) */
+    generationConfig?: GeminiGenerationConfig;
+    /** Initial conversation history */
+    history?: GeminiContent[];
+}

package/dist/domain/entities/index.d.ts

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

package/dist/domain/entities/models.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Available Gemini AI models
+ */
+export declare const GEMINI_MODELS: {
+    /** Text generation models */
+    readonly TEXT: {
+        /** Lightweight flash model for fast text generation */
+        readonly FLASH_LITE: "gemini-2.5-flash-lite";
+        /** Balanced flash model for general use */
+        readonly FLASH: "gemini-2.5-flash";
+        /** Premium model for complex tasks */
+        readonly PRO: "gemini-2.5-pro";
+    };
+};
+/**
+ * Default models to use for each category
+ */
+export declare const DEFAULT_MODELS: {
+    /** Default model for text generation */
+    readonly TEXT: "gemini-2.5-flash-lite";
+    /** Default model for chat sessions */
+    readonly CHAT: "gemini-2.5-flash";
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @umituz/react-native-ai-gemini-provider
+ * Google Gemini AI provider for React Native applications
+ */
+export type { GeminiConfig, GeminiGenerationConfig, GeminiHarmCategory, GeminiHarmBlockThreshold, GeminiContent, GeminiPart, GeminiInlineDataPart, GeminiMessagePart, GeminiSafetySetting, GeminiModelOptions, GeminiChatConfig, GeminiResponse, GeminiCandidate, GeminiFinishReason, GeminiSafetyRating, GeminiUsageMetadata, GeminiErrorInfo, GeminiApiError, } from "./domain/entities";
+export { GeminiErrorType, GeminiError, GEMINI_MODELS, DEFAULT_MODELS } from "./domain/entities";
+export { geminiClient } from "./infrastructure/services/GeminiClient";
+export { createChatSession, sendChatMessage, buildChatHistory, trimChatHistory, resolveAudioMimeType, resolveImageMimeType, type ChatSendResult, type ChatHistoryMessage, type SendChatMessageOptions, } from "./infrastructure/services/ChatSession";
+export { textGeneration } from "./infrastructure/services/TextGeneration";
+export { structuredText } from "./infrastructure/services/StructuredText";
+export { streaming } from "./infrastructure/services/Streaming";
+export { geminiProvider, GeminiProvider } from "./infrastructure/services/GeminiProvider";
+export { useGemini } from "./presentation/hooks";
+export type { UseGeminiOptions, UseGeminiReturn } from "./presentation/hooks";
+export { ConfigBuilder, providerFactory } from "./providers";
+export type { ProviderConfig, ProviderFactoryOptions, } from "./providers";

package/dist/infrastructure/services/BaseService.d.ts

@@ -0,0 +1,34 @@
+import type { GeminiContent, GeminiGenerationConfig } from "../../domain/entities";
+import type { GenerativeModel } from "@google/generative-ai";
+export interface BaseRequestOptions {
+    model: string;
+    contents: GeminiContent[];
+    generationConfig?: GeminiGenerationConfig;
+    signal?: AbortSignal;
+}
+export declare abstract class BaseGeminiService {
+    protected validateAndPrepare(options: BaseRequestOptions): {
+        genModel: GenerativeModel;
+        sdkContents: Array<{
+            role: string;
+            parts: Array<{
+                text: string;
+            }>;
+        }>;
+    };
+    protected handleError(error: unknown, abortMessage: string): never;
+    protected createRequestOptions(sdkContents: Array<{
+        role: string;
+        parts: Array<{
+            text: string;
+        }>;
+    }>, generationConfig?: GeminiGenerationConfig): {
+        contents: {
+            role: string;
+            parts: Array<{
+                text: string;
+            }>;
+        }[];
+        generationConfig: GeminiGenerationConfig | undefined;
+    };
+}

package/dist/infrastructure/services/ChatSession.d.ts

@@ -0,0 +1,67 @@
+import type { GeminiChatConfig, GeminiGenerationConfig, GeminiContent, GeminiInlineDataPart, GeminiMessagePart, GeminiSafetySetting } from "../../domain/entities";
+export interface ChatSendResult {
+    text: string;
+    finishReason?: string;
+}
+/** A simple chat message (user/assistant/system) */
+export interface ChatHistoryMessage {
+    readonly role: "user" | "assistant" | "system";
+    readonly content: string;
+}
+/** Options for the high-level sendChatMessage() */
+export interface SendChatMessageOptions {
+    /** Conversation history */
+    history: ChatHistoryMessage[];
+    /** Current user message text */
+    message: string;
+    /** System instruction for the model */
+    systemPrompt?: string;
+    /** Model name (defaults to gemini-2.5-flash) */
+    model?: string;
+    /** Generation config (temperature, maxOutputTokens, etc.) */
+    generationConfig?: GeminiGenerationConfig;
+    /** Safety settings (defaults to BLOCK_NONE for all) */
+    safetySettings?: GeminiSafetySetting[];
+    /** Pre-built attachments (base64 inline data parts for images/audio) */
+    attachments?: GeminiInlineDataPart[];
+    /** Max character budget for history trimming (default 12000) */
+    historyMaxChars?: number;
+    /** Min messages to always keep regardless of budget (default 4) */
+    historyMinMessages?: number;
+}
+/** Resolve MIME type for an audio file extension */
+export declare function resolveAudioMimeType(extension: string): string;
+/** Resolve MIME type for an image file extension */
+export declare function resolveImageMimeType(extension: string): string;
+/**
+ * Converts chat messages (user/assistant/system) to Gemini SDK content format.
+ * Skips system messages, merges consecutive same-role messages.
+ */
+export declare function buildChatHistory(history: readonly ChatHistoryMessage[]): GeminiContent[];
+/**
+ * Trims conversation history to fit within a character budget.
+ * Keeps at least `minMessages` entries regardless of budget.
+ */
+export declare function trimChatHistory(history: ChatHistoryMessage[], maxChars?: number, minMessages?: number): ChatHistoryMessage[];
+/**
+ * Creates a Gemini chat session with full support for system instructions,
+ * safety settings, generation config, and multi-turn conversation history.
+ */
+export declare function createChatSession(config?: GeminiChatConfig): {
+    send(parts: GeminiMessagePart[]): Promise<ChatSendResult>;
+};
+/**
+ * All-in-one: trims history, builds session, sends message, handles safety.
+ * Returns the AI response text.
+ *
+ * ```ts
+ * const text = await sendChatMessage({
+ *   history: messages,
+ *   message: "hello",
+ *   systemPrompt: "You are Aria...",
+ *   model: GEMINI_MODELS.TEXT.FLASH,
+ *   generationConfig: { temperature: 0.7, maxOutputTokens: 512 },
+ * });
+ * ```
+ */
+export declare function sendChatMessage(opts: SendChatMessageOptions): Promise<string>;

package/dist/infrastructure/services/GeminiClient.d.ts

@@ -0,0 +1,19 @@
+import { GoogleGenerativeAI, type GenerativeModel } from "@google/generative-ai";
+import type { GeminiConfig, GeminiModelOptions } from "../../domain/entities";
+declare class GeminiClient {
+    private client;
+    private config;
+    private initialized;
+    initialize(config: GeminiConfig): void;
+    isInitialized(): boolean;
+    getConfig(): GeminiConfig | null;
+    getClient(): GoogleGenerativeAI | null;
+    /**
+     * Returns a GenerativeModel configured with optional safety settings and system instruction.
+     * When no safety settings are provided, defaults to BLOCK_NONE for all categories.
+     */
+    getModel(modelNameOrOptions?: string | GeminiModelOptions): GenerativeModel;
+    reset(): void;
+}
+export declare const geminiClient: GeminiClient;
+export {};

package/dist/infrastructure/services/GeminiProvider.d.ts

@@ -0,0 +1,10 @@
+import type { GeminiConfig } from "../../domain/entities";
+export declare class GeminiProvider {
+    readonly providerId = "gemini";
+    readonly providerName = "Google Gemini";
+    initialize(config: GeminiConfig): void;
+    isInitialized(): boolean;
+    reset(): void;
+    generateStructuredText<T>(prompt: string, schema: Record<string, unknown>, model: string): Promise<T>;
+}
+export declare const geminiProvider: GeminiProvider;

package/dist/infrastructure/services/Streaming.d.ts

@@ -0,0 +1,7 @@
+import { BaseGeminiService } from "./BaseService";
+import type { GeminiContent, GeminiGenerationConfig } from "../../domain/entities";
+declare class StreamingService extends BaseGeminiService {
+    streamContent(model: string, contents: GeminiContent[], onChunk: (text: string) => void, generationConfig?: GeminiGenerationConfig, signal?: AbortSignal): Promise<string>;
+}
+export declare const streaming: StreamingService;
+export {};

package/dist/infrastructure/services/StructuredText.d.ts

@@ -0,0 +1,7 @@
+import type { GeminiGenerationConfig } from "../../domain/entities";
+declare class StructuredTextService {
+    generateStructuredText<T>(model: string, prompt: string, schema: Record<string, unknown>, config?: Omit<GeminiGenerationConfig, "responseMimeType" | "responseSchema">, signal?: AbortSignal): Promise<T>;
+    private parseJSONResponse;
+}
+export declare const structuredText: StructuredTextService;
+export {};

package/dist/infrastructure/services/TextGeneration.d.ts

@@ -0,0 +1,8 @@
+import { BaseGeminiService } from "./BaseService";
+import type { GeminiContent, GeminiGenerationConfig, GeminiResponse } from "../../domain/entities";
+declare class TextGenerationService extends BaseGeminiService {
+    generateContent(model: string, contents: GeminiContent[], generationConfig?: GeminiGenerationConfig, signal?: AbortSignal): Promise<GeminiResponse>;
+    generateText(model: string, prompt: string, config?: GeminiGenerationConfig, signal?: AbortSignal): Promise<string>;
+}
+export declare const textGeneration: TextGenerationService;
+export {};

package/dist/infrastructure/services/index.d.ts

@@ -0,0 +1,6 @@
+export { geminiClient } from "./GeminiClient";
+export { textGeneration } from "./TextGeneration";
+export { structuredText } from "./StructuredText";
+export { streaming } from "./Streaming";
+export { geminiProvider, GeminiProvider } from "./GeminiProvider";
+export { createChatSession, sendChatMessage, buildChatHistory, trimChatHistory, resolveAudioMimeType, resolveImageMimeType, type ChatSendResult, type ChatHistoryMessage, type SendChatMessageOptions, } from "./ChatSession";

package/dist/infrastructure/telemetry/TelemetryHooks.d.ts

@@ -0,0 +1,57 @@
+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;
+declare class TelemetryHooks {
+    private listeners;
+    private failedListeners;
+    private readonly MAX_FAILURES;
+    private listenerFailureCounts;
+    /**
+     * Register a telemetry listener
+     */
+    subscribe(listener: TelemetryListener): () => void;
+    /**
+     * Emit a telemetry event to all listeners
+     */
+    emit(event: TelemetryEvent): void;
+    /**
+     * Log request start
+     */
+    logRequest(model: string, feature?: string): number;
+    /**
+     * Log response received
+     */
+    logResponse(model: string, startTime: number, feature?: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log error
+     */
+    logError(model: string, error: Error, feature?: string): void;
+    /**
+     * Log retry attempt
+     */
+    logRetry(model: string, attempt: number, feature?: string): void;
+    /**
+     * Remove a specific listener
+     */
+    unsubscribe(listener: TelemetryListener): void;
+    /**
+     * Reset failure counts for all listeners (clear blacklist)
+     */
+    resetFailures(): void;
+    /**
+     * Clear all listeners
+     */
+    clear(): void;
+    /**
+     * Get current listener count
+     */
+    getListenerCount(): number;
+}
+export declare const telemetryHooks: TelemetryHooks;
+export {};

package/dist/infrastructure/telemetry/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Telemetry Module
+ */
+export { telemetryHooks } from "./TelemetryHooks";

package/dist/infrastructure/utils/async/execute-state.util.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Async State Execution Utilities
+ * Utilities for managing asynchronous operation state
+ */
+/**
+ * Callbacks for async operation outcomes
+ */
+export interface AsyncStateCallbacks<T = string> {
+    onSuccess?: (result: T) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * Setter functions for updating state
+ */
+export interface AsyncStateSetters<T = string, U = unknown> {
+    setIsLoading: (value: boolean) => void;
+    setError: (value: string | null) => void;
+    setResult: (value: T | null) => void;
+    setSecondaryResult?: (value: U | null) => void;
+}
+/**
+ * Configuration for executeWithState
+ */
+export interface AsyncStateConfig<T = string> {
+    resetState?: boolean;
+    throwOnError?: boolean;
+    transformResult?: (result: T) => T;
+}
+/**
+ * Execute an async operation with automatic state management
+ *
+ * @param setters - State setter functions
+ * @param callbacks - Optional callbacks for success/error
+ * @param execute - The async operation to execute
+ * @param onResult - Function to handle successful result
+ * @param config - Optional configuration
+ *
+ * @returns The result or null if failed/aborted
+ *
+ * @example
+ * ```ts
+ * const result = await executeWithState(
+ *   { setIsLoading, setError, setResult },
+ *   { onSuccess: console.log },
+ *   () => apiCall(),
+ *   (data) => setResult(data)
+ * );
+ * ```
+ */
+export declare function executeWithState<T, U = unknown>(setters: AsyncStateSetters<T, U>, callbacks: AsyncStateCallbacks<T>, execute: () => Promise<T>, onResult: (result: T) => void, config?: AsyncStateConfig<T>): Promise<T | null>;

package/dist/infrastructure/utils/async/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Async State Management - Internal Use Only
+ */
+export { executeWithState, type AsyncStateSetters, } from "./execute-state.util";

package/dist/infrastructure/utils/content-mapper.util.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Content Mapper Utilities
+ * Handles transformation between domain content and SDK format
+ */
+import type { GeminiContent, GeminiPart, GeminiResponse } from "../../domain/entities";
+/**
+ * Convert domain content to SDK format
+ */
+export declare function toSdkContent(contents: GeminiContent[]): Array<{
+    role: string;
+    parts: Array<{
+        text: string;
+    }>;
+}>;
+/**
+ * Create a simple text content
+ */
+export declare function createTextContent(text: string, role?: "user" | "model"): GeminiContent;
+/**
+ * Transform SDK response to domain format
+ */
+export declare function transformResponse(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;
+/**
+ * Extract text from content parts
+ */
+export declare function extractTextFromParts(parts: GeminiPart[]): string;

package/dist/infrastructure/utils/error-mapper.util.d.ts

@@ -0,0 +1,2 @@
+import { GeminiError } from "../../domain/entities";
+export declare function createGeminiError(error: unknown): GeminiError;

package/dist/infrastructure/utils/gemini-data-transformer.util.d.ts

@@ -0,0 +1,2 @@
+import type { GeminiResponse } from "../../domain/entities";
+export declare function extractTextFromResponse(response: GeminiResponse): string;

package/dist/infrastructure/utils/json-parser.util.d.ts

@@ -0,0 +1,9 @@
+/**
+ * JSON Parser Utilities
+ * Handles cleaning and parsing JSON responses from AI models
+ */
+/**
+ * Parse JSON response with error handling
+ * @throws Error if parsing fails with detailed error message
+ */
+export declare function parseJsonResponse<T>(text: string): T;

package/dist/infrastructure/utils/stream-processor.util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stream Processing Utilities
+ * Reusable stream handling logic
+ */
+interface StreamChunk {
+    text: () => string;
+}
+type ChunkCallback = (text: string) => void;
+type ErrorLogger = (error: unknown, context?: string) => void;
+/**
+ * Process async stream with chunk callback
+ */
+export declare function processStream(stream: AsyncIterable<StreamChunk>, onChunk: ChunkCallback, onError?: ErrorLogger): Promise<string>;
+export {};

package/dist/presentation/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useGemini, type UseGeminiOptions, type UseGeminiReturn } from "./useGemini";

package/dist/presentation/hooks/useGemini.d.ts

@@ -0,0 +1,17 @@
+import type { GeminiGenerationConfig } from "../../domain/entities";
+export interface UseGeminiOptions {
+    model?: string;
+    generationConfig?: GeminiGenerationConfig;
+    onSuccess?: (result: string) => void;
+    onError?: (error: string) => void;
+}
+export interface UseGeminiReturn {
+    generate: (prompt: string) => Promise<void>;
+    generateJSON: <T>(prompt: string, schema?: Record<string, unknown>) => Promise<T | null>;
+    result: string | null;
+    jsonResult: unknown;
+    isGenerating: boolean;
+    error: string | null;
+    reset: () => void;
+}
+export declare function useGemini(options?: UseGeminiOptions): UseGeminiReturn;

package/dist/presentation/hooks/useOperationManager.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Operation Manager Hook
+ * Reusable abort controller and operation ID management
+ * Eliminates code duplication in hooks
+ */
+export interface OperationManager {
+    /**
+     * Execute an operation with abort support and operation ID tracking
+     */
+    executeOperation: <T>(operation: (signal: AbortSignal, operationId: number) => Promise<T>) => Promise<T>;
+    /**
+     * Abort current operation
+     */
+    abort: () => void;
+    /**
+     * Check if current operation is active
+     */
+    isOperationActive: (operationId: number) => boolean;
+}
+/**
+ * Hook for managing operations with abort control
+ */
+export declare function useOperationManager(): OperationManager;

package/dist/providers/ConfigBuilder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Config Builder Pattern
+ * Fluent API for building provider configuration
+ */
+import type { GeminiConfig } from "../domain/entities";
+export interface ProviderConfig {
+    apiKey: string;
+    textModel: string;
+    timeout: number;
+    strategy?: "cost" | "quality";
+}
+/**
+ * Builder for constructing provider configuration
+ * Provides a fluent API with validation and defaults
+ */
+export declare class ConfigBuilder {
+    private config;
+    /**
+     * Set API key (required)
+     */
+    withApiKey(apiKey: string): this;
+    /**
+     * Set text model
+     */
+    withTextModel(model: string): this;
+    /**
+     * Set request timeout (ms)
+     */
+    withTimeout(timeout: number): this;
+    /**
+     * Set strategy (applies preset timeout)
+     */
+    withStrategy(strategy: "cost" | "quality"): this;
+    /**
+     * Build final configuration
+     */
+    build(): ProviderConfig;
+    /**
+     * Convert to GeminiConfig format
+     */
+    toGeminiConfig(): GeminiConfig;
+    /**
+     * Create a new builder instance
+     */
+    static create(): ConfigBuilder;
+    /**
+     * Create from existing config (for updates)
+     */
+    static from(config: Partial<ProviderConfig>): ConfigBuilder;
+}

package/dist/providers/ProviderFactory.d.ts

@@ -0,0 +1,31 @@
+import { type ProviderConfig } from "./ConfigBuilder";
+export { ConfigBuilder } from "./ConfigBuilder";
+export type { ProviderConfig } from "./ConfigBuilder";
+export interface ProviderFactoryOptions {
+    apiKey: string;
+    timeout?: number;
+    textModel?: string;
+    strategy?: "cost" | "quality";
+}
+declare class ProviderFactory {
+    private currentConfig;
+    private builder;
+    /**
+     * Initialize provider with configuration
+     */
+    initialize(options: ProviderFactoryOptions): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): ProviderConfig | null;
+    /**
+     * Check if provider is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Update configuration
+     * API key changes require re-initialization
+     */
+    updateConfig(updates: Partial<ProviderFactoryOptions>): void;
+}
+export declare const providerFactory: ProviderFactory;

package/dist/providers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Provider Configuration & Factory - Public API
+ */
+export { ConfigBuilder } from "./ConfigBuilder";
+export type { ProviderConfig } from "./ConfigBuilder";
+export { providerFactory } from "./ProviderFactory";
+export type { ProviderFactoryOptions } from "./ProviderFactory";

package/package.json

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

package/src/index.ts

@@ -34,7 +34,17 @@ export {
 
 // Services
 export { geminiClient } from "./infrastructure/services/GeminiClient";
-export { createChatSession } from "./infrastructure/services/ChatSession";
+export {
+  createChatSession,
+  sendChatMessage,
+  buildChatHistory,
+  trimChatHistory,
+  resolveAudioMimeType,
+  resolveImageMimeType,
+  type ChatSendResult,
+  type ChatHistoryMessage,
+  type SendChatMessageOptions,
+} from "./infrastructure/services/ChatSession";
 export { textGeneration } from "./infrastructure/services/TextGeneration";
 export { structuredText } from "./infrastructure/services/StructuredText";
 export { streaming } from "./infrastructure/services/Streaming";

package/src/infrastructure/services/ChatSession.ts

@@ -3,25 +3,133 @@ import { geminiClient } from "./GeminiClient";
 import { DEFAULT_MODELS } from "../../domain/entities";
 import type {
   GeminiChatConfig,
+  GeminiGenerationConfig,
   GeminiContent,
+  GeminiInlineDataPart,
   GeminiMessagePart,
+  GeminiSafetySetting,
 } from "../../domain/entities";
 
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ChatSendResult {
+  text: string;
+  finishReason?: string;
+}
+
+/** A simple chat message (user/assistant/system) */
+export interface ChatHistoryMessage {
+  readonly role: "user" | "assistant" | "system";
+  readonly content: string;
+}
+
+/** Options for the high-level sendChatMessage() */
+export interface SendChatMessageOptions {
+  /** Conversation history */
+  history: ChatHistoryMessage[];
+  /** Current user message text */
+  message: string;
+  /** System instruction for the model */
+  systemPrompt?: string;
+  /** Model name (defaults to gemini-2.5-flash) */
+  model?: string;
+  /** Generation config (temperature, maxOutputTokens, etc.) */
+  generationConfig?: GeminiGenerationConfig;
+  /** Safety settings (defaults to BLOCK_NONE for all) */
+  safetySettings?: GeminiSafetySetting[];
+  /** Pre-built attachments (base64 inline data parts for images/audio) */
+  attachments?: GeminiInlineDataPart[];
+  /** Max character budget for history trimming (default 12000) */
+  historyMaxChars?: number;
+  /** Min messages to always keep regardless of budget (default 4) */
+  historyMinMessages?: number;
+}
+
+// ─── MIME Utilities ──────────────────────────────────────────────────────────
+
+const AUDIO_MIME: Record<string, string> = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+  aac: "audio/aac",
+  mp4: "audio/mp4",
+  m4a: "audio/mp4",
+  caf: "audio/mp4",
+  "3gp": "audio/3gpp",
+};
+
+/** Resolve MIME type for an audio file extension */
+export function resolveAudioMimeType(extension: string): string {
+  return AUDIO_MIME[extension.toLowerCase()] ?? "audio/mp4";
+}
+
+/** Resolve MIME type for an image file extension */
+export function resolveImageMimeType(extension: string): string {
+  return extension.toLowerCase() === "png" ? "image/png" : "image/jpeg";
+}
+
+// ─── History Utilities ───────────────────────────────────────────────────────
+
+/**
+ * Converts chat messages (user/assistant/system) to Gemini SDK content format.
+ * Skips system messages, merges consecutive same-role messages.
+ */
+export function buildChatHistory(
+  history: readonly ChatHistoryMessage[],
+): GeminiContent[] {
+  const result: GeminiContent[] = [];
+  let seenUser = false;
+
+  for (const m of history) {
+    if (m.role === "system") continue;
+    if (!seenUser && m.role !== "user") continue;
+    seenUser = true;
+
+    const role = m.role === "assistant" ? "model" : "user";
+    const last = result[result.length - 1];
+
+    if (last && last.role === role) {
+      const existingText =
+        "text" in last.parts[0] ? (last.parts[0].text ?? "") : "";
+      last.parts[0] = { text: existingText + "\n" + m.content };
+    } else {
+      result.push({ role, parts: [{ text: m.content }] });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Trims conversation history to fit within a character budget.
+ * Keeps at least `minMessages` entries regardless of budget.
+ */
+export function trimChatHistory(
+  history: ChatHistoryMessage[],
+  maxChars = 12000,
+  minMessages = 4,
+): ChatHistoryMessage[] {
+  if (history.length <= minMessages) return history;
+
+  let totalChars = 0;
+  const trimmed: ChatHistoryMessage[] = [];
+
+  for (let i = history.length - 1; i >= 0; i--) {
+    const chars = history[i].content.length;
+    if (trimmed.length >= minMessages && totalChars + chars > maxChars) break;
+    trimmed.unshift(history[i]);
+    totalChars += chars;
+  }
+
+  return trimmed;
+}
+
+// ─── Low-level: createChatSession ────────────────────────────────────────────
+
 /**
  * Creates a Gemini chat session with full support for system instructions,
  * safety settings, generation config, and multi-turn conversation history.
- *
- * Usage:
- * ```ts
- * const session = createChatSession({
- *   model: "gemini-2.5-flash",
- *   systemInstruction: "You are a helpful assistant.",
- *   generationConfig: { temperature: 0.7, maxOutputTokens: 512 },
- *   history: geminiHistory,
- * });
- *
- * const text = await session.send([{ text: "Hello" }]);
- * ```
  */
 export function createChatSession(config: GeminiChatConfig = {}) {
   const model = geminiClient.getModel({
@@ -41,14 +149,63 @@ export function createChatSession(config: GeminiChatConfig = {}) {
   });
 
   return {
-    /**
-     * Send a message and return the full response text.
-     * Accepts text parts and/or inline data parts (images, audio).
-     */
-    async send(parts: GeminiMessagePart[]): Promise<string> {
+    async send(parts: GeminiMessagePart[]): Promise<ChatSendResult> {
       const result = await chat.sendMessage(parts as Part[]);
       if (!result.response) throw new Error("No response from Gemini SDK");
-      return result.response.text();
+      const candidate = result.response.candidates?.[0];
+      return {
+        text: result.response.text(),
+        finishReason: candidate?.finishReason ?? undefined,
+      };
     },
   };
 }
+
+// ─── High-level: sendChatMessage ─────────────────────────────────────────────
+
+/**
+ * All-in-one: trims history, builds session, sends message, handles safety.
+ * Returns the AI response text.
+ *
+ * ```ts
+ * const text = await sendChatMessage({
+ *   history: messages,
+ *   message: "hello",
+ *   systemPrompt: "You are Aria...",
+ *   model: GEMINI_MODELS.TEXT.FLASH,
+ *   generationConfig: { temperature: 0.7, maxOutputTokens: 512 },
+ * });
+ * ```
+ */
+export async function sendChatMessage(
+  opts: SendChatMessageOptions,
+): Promise<string> {
+  const trimmed = trimChatHistory(
+    opts.history,
+    opts.historyMaxChars,
+    opts.historyMinMessages,
+  );
+  const geminiHistory = buildChatHistory(trimmed);
+
+  const session = createChatSession({
+    model: opts.model ?? DEFAULT_MODELS.CHAT,
+    systemInstruction: opts.systemPrompt,
+    safetySettings: opts.safetySettings,
+    generationConfig: opts.generationConfig,
+    history: geminiHistory,
+  });
+
+  const parts: GeminiMessagePart[] = [{ text: opts.message }];
+  if (opts.attachments) {
+    parts.push(...opts.attachments);
+  }
+
+  const result = await session.send(parts);
+
+  if (result.finishReason === "SAFETY") {
+    if (result.text.trim()) return result.text;
+    throw new Error("Response blocked by safety filter.");
+  }
+
+  return result.text;
+}

package/src/infrastructure/services/index.ts

@@ -3,4 +3,14 @@ export { textGeneration } from "./TextGeneration";
 export { structuredText } from "./StructuredText";
 export { streaming } from "./Streaming";
 export { geminiProvider, GeminiProvider } from "./GeminiProvider";
-export { createChatSession } from "./ChatSession";
+export {
+  createChatSession,
+  sendChatMessage,
+  buildChatHistory,
+  trimChatHistory,
+  resolveAudioMimeType,
+  resolveImageMimeType,
+  type ChatSendResult,
+  type ChatHistoryMessage,
+  type SendChatMessageOptions,
+} from "./ChatSession";