react-native-ai-hooks 0.3.0 → 0.5.0

package/src/hooks/useImageAnalysis.ts

@@ -1,47 +1,20 @@
-import { useCallback, useState } from 'react';
-
-interface UseImageAnalysisOptions {
-  apiKey: string;
-  model?: string;
-  maxTokens?: number;
-  system?: string;
-  uriToBase64?: (uri: string) => Promise<string>;
-}
-
-interface AnalyzeImageInput {
-  image: string;
-  mediaType?: string;
-  prompt?: string;
-}
+import { useCallback, useState, useRef, useMemo } from 'react';
+import type { UseImageAnalysisOptions, UseImageAnalysisReturn } from '../types';
+import { createProvider } from '../utils/providerFactory';
 
-interface UseImageAnalysisReturn {
-  description: string;
-  isLoading: boolean;
-  error: string | null;
-  analyzeImage: (input: AnalyzeImageInput) => Promise<string | null>;
-  clearDescription: () => void;
-}
-
-interface ParsedImageData {
-  base64: string;
-  mediaType: string;
-}
+const DEFAULT_MODEL_MAP = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4-vision',
+  gemini: 'gemini-pro-vision',
+};
 
 const DATA_URI_REGEX = /^data:(image\/[a-zA-Z0-9.+-]+);base64,(.*)$/;
 
 function getMediaTypeFromUri(uri: string): string {
   const normalized = uri.toLowerCase();
-
-  if (normalized.includes('.png')) {
-    return 'image/png';
-  }
-  if (normalized.includes('.webp')) {
-    return 'image/webp';
-  }
-  if (normalized.includes('.gif')) {
-    return 'image/gif';
-  }
-
+  if (normalized.includes('.png')) return 'image/png';
+  if (normalized.includes('.webp')) return 'image/webp';
+  if (normalized.includes('.gif')) return 'image/gif';
   return 'image/jpeg';
 }
 
@@ -56,7 +29,7 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
   }
 
   if (typeof btoa !== 'function') {
-    throw new Error('Base64 conversion is unavailable. Provide uriToBase64 in hook options.');
+    throw new Error('Base64 conversion unavailable. Provide uriToBase64 in hook options.');
   }
 
   return btoa(binary);
@@ -72,26 +45,44 @@ async function defaultUriToBase64(uri: string): Promise<string> {
   return arrayBufferToBase64(imageBuffer);
 }
 
+/**
+ * Analyzes an image with a vision-capable model and stores the generated description.
+ *
+ * @param options Vision configuration including provider credentials, model selection,
+ * request limits, and optional URI-to-base64 conversion for React Native environments.
+ * @returns Image analysis state with the latest description, loading/error flags, and
+ * actions to analyze a new image or clear the stored description.
+ */
 export function useImageAnalysis(options: UseImageAnalysisOptions): UseImageAnalysisReturn {
   const [description, setDescription] = useState('');
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
+  const isMountedRef = useRef(true);
+
+  const providerConfig = useMemo(
+    () => ({
+      provider: (options.provider || 'anthropic') as 'anthropic' | 'openai' | 'gemini',
+      apiKey: options.apiKey,
+      model: options.model || DEFAULT_MODEL_MAP[options.provider || 'anthropic'],
+      baseUrl: options.baseUrl,
+      timeout: options.timeout,
+      maxRetries: options.maxRetries,
+    }),
+    [options],
+  );
+
   const normalizeImage = useCallback(
-    async (image: string, mediaType?: string): Promise<ParsedImageData> => {
+    async (image: string, mediaType?: string): Promise<{ base64: string; mediaType: string }> => {
       const dataUriMatch = image.match(DATA_URI_REGEX);
       if (dataUriMatch) {
-        const matchedMediaType = dataUriMatch[1];
-        const base64Data = dataUriMatch[2];
         return {
-          base64: base64Data,
-          mediaType: mediaType || matchedMediaType,
+          base64: dataUriMatch[2],
+          mediaType: mediaType || dataUriMatch[1],
         };
       }
 
-      const isLikelyUri = /^(https?:\/\/|file:\/\/|content:\/\/|ph:\/\/|assets-library:\/\/)/i.test(
-        image,
-      );
+      const isLikelyUri = /^(https?:\/\/|file:\/\/|content:\/\/|ph:\/\/|assets-library:\/\/)/i.test(image);
 
       if (isLikelyUri) {
         const toBase64 = options.uriToBase64 || defaultUriToBase64;
@@ -116,24 +107,39 @@ export function useImageAnalysis(options: UseImageAnalysisOptions): UseImageAnal
   }, []);
 
   const analyzeImage = useCallback(
-    async (input: AnalyzeImageInput) => {
-      setIsLoading(true);
+    async (uri: string, prompt?: string) => {
+      if (!uri) {
+        setError('Image URI is required');
+        return null;
+      }
+
+      if (!options.apiKey) {
+        setError('Missing API key');
+        return null;
+      }
+
       setError(null);
+      setIsLoading(true);
 
       try {
-        const parsedImage = await normalizeImage(input.image, input.mediaType);
+        const imagData = await normalizeImage(uri);
+        const analysisPrompt = prompt || 'Describe this image in detail.';
 
-        const apiResponse = await fetch('https://api.anthropic.com/v1/messages', {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'x-api-key': options.apiKey,
-            'anthropic-version': '2023-06-01',
-          },
-          body: JSON.stringify({
-            model: options.model || 'claude-sonnet-4-20250514',
+        const base_url = providerConfig.baseUrl || 'https://api.anthropic.com';
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+        };
+
+        let url = '';
+        let body: Record<string, unknown> = {};
+
+        if (providerConfig.provider === 'anthropic') {
+          url = `${base_url}/v1/messages`;
+          headers['x-api-key'] = options.apiKey;
+          headers['anthropic-version'] = '2023-06-01';
+          body = {
+            model: providerConfig.model,
             max_tokens: options.maxTokens ?? 1024,
-            system: options.system,
             messages: [
               {
                 role: 'user',
@@ -142,47 +148,96 @@ export function useImageAnalysis(options: UseImageAnalysisOptions): UseImageAnal
                     type: 'image',
                     source: {
                       type: 'base64',
-                      media_type: parsedImage.mediaType,
-                      data: parsedImage.base64,
+                      media_type: imagData.mediaType,
+                      data: imagData.base64,
                     },
                   },
                   {
                     type: 'text',
-                    text: input.prompt || 'Describe this image in detail.',
+                    text: analysisPrompt,
                   },
                 ],
               },
             ],
-          }),
+          };
+        } else if (providerConfig.provider === 'openai') {
+          url = `${providerConfig.baseUrl || 'https://api.openai.com'}/v1/chat/completions`;
+          headers.Authorization = `Bearer ${options.apiKey}`;
+          body = {
+            model: providerConfig.model,
+            max_tokens: options.maxTokens ?? 1024,
+            messages: [
+              {
+                role: 'user',
+                content: [
+                  {
+                    type: 'image_url',
+                    image_url: {
+                      url: `data:${imagData.mediaType};base64,${imagData.base64}`,
+                    },
+                  },
+                  {
+                    type: 'text',
+                    text: analysisPrompt,
+                  },
+                ],
+              },
+            ],
+          };
+        } else {
+          throw new Error(`Image analysis not supported for provider: ${providerConfig.provider}`);
+        }
+
+        const response = await fetch(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
         });
 
-        if (!apiResponse.ok) {
-          const errorText = await apiResponse.text();
-          throw new Error(errorText || `Claude API error: ${apiResponse.status}`);
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(errorText || `API error: ${response.status}`);
         }
 
-        const data = await apiResponse.json();
-        const textResult = data?.content?.find?.(
-          (item: { type?: string; text?: string }) => item?.type === 'text',
-        )?.text;
+        const data = await response.json();
+        let resultText = '';
+
+        if (providerConfig.provider === 'anthropic') {
+          resultText = data?.content?.[0]?.text || '';
+        } else if (providerConfig.provider === 'openai') {
+          resultText = data?.choices?.[0]?.message?.content || '';
+        }
 
-        if (!textResult) {
-          throw new Error('No description returned from Claude vision API.');
+        if (!resultText) {
+          throw new Error('No description returned by vision API');
         }
 
-        setDescription(textResult);
-        return textResult;
+        if (isMountedRef.current) {
+          setDescription(resultText);
+        }
+        return resultText;
       } catch (err) {
-        const message = (err as Error).message || 'Failed to analyze image';
-        setError(message);
+        if (isMountedRef.current) {
+          const message = err instanceof Error ? err.message : 'Failed to analyze image';
+          setError(message);
+        }
         return null;
       } finally {
-        setIsLoading(false);
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
       }
     },
-    [normalizeImage, options],
+    [normalizeImage, options, providerConfig],
   );
 
+  useState(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
   return {
     description,
     isLoading,

package/src/index.ts

@@ -5,4 +5,28 @@ export { useAIForm } from './hooks/useAIForm';
 export { useAIVoice } from './hooks/useAIVoice';
 export { useAITranslate } from './hooks/useAITranslate';
 export { useAISummarize } from './hooks/useAISummarize';
-export { useAICode } from './hooks/useAICode';
+export { useAICode } from './hooks/useAICode';
+
+// Type exports
+export type {
+  Message,
+  AIProviderType,
+  ProviderConfig,
+  AIResponse,
+  AIRequestOptions,
+  UseAIChatOptions,
+  UseAIChatReturn,
+  UseAIStreamOptions,
+  UseAIStreamReturn,
+  UseImageAnalysisOptions,
+  UseImageAnalysisReturn,
+  UseAIFormOptions,
+  UseAIFormReturn,
+  FormValidationRequest,
+  FormValidationResult,
+} from './types';
+
+// Utility exports for advanced use cases
+export { createProvider, ProviderFactory } from './utils/providerFactory';
+export { fetchWithRetry } from './utils/fetchWithRetry';
+export type { AIResponse, AIRequestOptions } from './utils/providerFactory';

package/src/types/index.ts

@@ -1,15 +1,189 @@
+/**
+ * Core Message Types
+ */
 export interface Message {
   role: 'user' | 'assistant';
   content: string;
+  timestamp?: number;
 }
 
-export interface AIProvider {
+/**
+ * AI Provider Types
+ */
+export type AIProviderType = 'anthropic' | 'openai' | 'gemini';
+
+export interface ProviderConfig {
+  provider: AIProviderType;
   apiKey: string;
-  provider?: 'claude' | 'openai' | 'gemini';
-  model?: string;
+  model: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
 }
 
+/**
+ * Standardized API Response
+ */
 export interface AIResponse {
-  content: string;
+  text: string;
+  raw: Record<string, unknown>;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+  };
   error?: string;
+}
+
+/**
+ * API Request Options
+ */
+export interface AIRequestOptions {
+  system?: string;
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  stopSequences?: string[];
+}
+
+/**
+ * Hook Options Interface
+ */
+export interface UseAIChatOptions {
+  apiKey: string;
+  provider?: AIProviderType;
+  model?: string;
+  system?: string;
+  temperature?: number;
+  maxTokens?: number;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export interface UseAIStreamOptions extends UseAIChatOptions {}
+
+export interface UseAIFormOptions {
+  apiKey: string;
+  provider?: AIProviderType;
+  model?: string;
+  system?: string;
+  temperature?: number;
+  maxTokens?: number;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export interface UseImageAnalysisOptions {
+  apiKey: string;
+  provider?: AIProviderType;
+  model?: string;
+  system?: string;
+  maxTokens?: number;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+  uriToBase64?: (uri: string) => Promise<string>;
+}
+
+/**
+ * Normalized Internal API Structures
+ */
+export interface NormalizedMessage {
+  role: 'user' | 'assistant';
+  content: NormalizedContent;
+}
+
+export type NormalizedContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } }
+  | Array<NormalizedContent>;
+
+/**
+ * Provider-Specific Raw Responses
+ */
+export interface AnthropicResponse {
+  content?: Array<{ type: string; text?: string }>;
+  error?: { type: string; message?: string };
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+  };
+}
+
+export interface OpenAIResponse {
+  choices?: Array<{ message?: { content?: string } }>;
+  error?: { message?: string };
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+}
+
+export interface GeminiResponse {
+  candidates?: Array<{
+    content?: {
+      parts?: Array<{ text?: string }>;
+    };
+  }>;
+  error?: { message?: string };
+  usageMetadata?: {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+  };
+}
+
+/**
+ * Form Validation Input/Output
+ */
+export interface FormValidationRequest {
+  formData: Record<string, unknown>;
+  validationSchema?: Record<string, string>;
+  customInstructions?: string;
+}
+
+export interface FormValidationResult {
+  isValid: boolean;
+  errors: Record<string, string>;
+  raw: unknown;
+}
+
+/**
+ * Generic Hook Return Types
+ */
+export interface UseAIChatReturn {
+  messages: Message[];
+  isLoading: boolean;
+  error: string | null;
+  sendMessage: (content: string) => Promise<void>;
+  abort: () => void;
+  clearMessages: () => void;
+}
+
+export interface UseAIStreamReturn {
+  response: string;
+  isLoading: boolean;
+  error: string | null;
+  streamResponse: (prompt: string) => Promise<void>;
+  abort: () => void;
+  clearResponse: () => void;
+}
+
+export interface UseImageAnalysisReturn {
+  description: string;
+  isLoading: boolean;
+  error: string | null;
+  analyzeImage: (uri: string, prompt?: string) => Promise<string | null>;
+  clearDescription: () => void;
+}
+
+export interface UseAIFormReturn {
+  validationResult: FormValidationResult | null;
+  isLoading: boolean;
+  error: string | null;
+  validateForm: (input: FormValidationRequest) => Promise<FormValidationResult | null>;
+  clearValidation: () => void;
 }

package/src/utils/__tests__/fetchWithRetry.test.ts

@@ -0,0 +1,168 @@
+import { fetchWithRetry } from '../fetchWithRetry';
+
+describe('fetchWithRetry', () => {
+  let fetchSpy: jest.SpyInstance<Promise<Response>, Parameters<typeof fetch>>;
+
+  const createResponse = (status: number, body: unknown, retryAfter?: string): Response => {
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      headers: {
+        get: (name: string) => {
+          if (name.toLowerCase() === 'retry-after') {
+            return retryAfter ?? null;
+          }
+          return null;
+        },
+      },
+      json: async () => body,
+      text: async () => JSON.stringify(body),
+    } as unknown as Response;
+  };
+
+  beforeEach(() => {
+    fetchSpy = jest.spyOn(global, 'fetch');
+    fetchSpy.mockReset();
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it('retries 429 responses with exponential backoff delays', async () => {
+    const allDelays: number[] = [];
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+    const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((callback: TimerHandler, delay?: number) => {
+      allDelays.push(Number(delay));
+      if (typeof callback === 'function') {
+        callback();
+      }
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout);
+
+    fetchSpy
+      .mockResolvedValueOnce(createResponse(429, { error: 'rate_limited' }, '1'))
+      .mockResolvedValueOnce(createResponse(429, { error: 'rate_limited' }))
+      .mockResolvedValueOnce(createResponse(200, { ok: true }));
+
+    const response = await fetchWithRetry(
+      'https://api.example.com/test',
+      { method: 'POST' },
+      { maxRetries: 2, baseDelay: 1000, backoffMultiplier: 2, timeout: 1000 },
+    );
+
+    expect(response.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+    // allDelays contains: [abort_timeout, retry_delay, abort_timeout, retry_delay, abort_timeout]
+    // Extract only the odd-indexed elements (1, 3) which are the retry delays
+    const retryDelays = [allDelays[1], allDelays[3]];
+    expect(retryDelays).toEqual([1000, 2000]);
+
+    randomSpy.mockRestore();
+    setTimeoutSpy.mockRestore();
+  });
+
+  it('uses default retry options when none are provided', async () => {
+    fetchSpy.mockResolvedValueOnce(createResponse(200, { ok: true }));
+
+    const response = await fetchWithRetry('https://api.example.com/default-options');
+
+    expect(response.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries 5xx responses with jittered backoff and then succeeds', async () => {
+    const allDelays: number[] = [];
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+    const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((callback: TimerHandler, delay?: number) => {
+      allDelays.push(Number(delay));
+      if (typeof callback === 'function') {
+        callback();
+      }
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout);
+
+    fetchSpy
+      .mockResolvedValueOnce(createResponse(500, { error: 'server_error' }))
+      .mockResolvedValueOnce(createResponse(200, { ok: true }));
+
+    const response = await fetchWithRetry(
+      'https://api.example.com/test',
+      { method: 'POST' },
+      { maxRetries: 1, baseDelay: 1000, timeout: 30000 },
+    );
+
+    expect(response.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    // [attempt1 timeout, retry delay, attempt2 timeout]
+    expect(allDelays[1]).toBe(1000);
+
+    randomSpy.mockRestore();
+    setTimeoutSpy.mockRestore();
+  });
+
+  it('retries AbortError failures and then succeeds', async () => {
+    const allDelays: number[] = [];
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+    const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((callback: TimerHandler, delay?: number) => {
+      allDelays.push(Number(delay));
+      if (typeof callback === 'function') {
+        callback();
+      }
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout);
+
+    const abortError = Object.assign(new Error('timeout'), { name: 'AbortError' });
+
+    fetchSpy
+      .mockRejectedValueOnce(abortError)
+      .mockResolvedValueOnce(createResponse(200, { ok: true }));
+
+    const response = await fetchWithRetry(
+      'https://api.example.com/test',
+      { method: 'GET' },
+      { maxRetries: 1, baseDelay: 500, timeout: 1234 },
+    );
+
+    expect(response.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    // [attempt1 timeout, retry delay, attempt2 timeout]
+    expect(allDelays[1]).toBe(500);
+
+    randomSpy.mockRestore();
+    setTimeoutSpy.mockRestore();
+  });
+
+  it('throws immediately when an error is explicitly marked non-retryable', async () => {
+    const nonRetryableError = Object.assign(new Error('do not retry'), { isRetryable: false });
+
+    fetchSpy.mockRejectedValueOnce(nonRetryableError);
+
+    await expect(
+      fetchWithRetry('https://api.example.com/test', { method: 'GET' }, { maxRetries: 3 }),
+    ).rejects.toThrow('do not retry');
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries unknown errors until max retries are exhausted', async () => {
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+    const retryError = new Error('network down');
+
+    fetchSpy.mockRejectedValue(retryError);
+
+    await expect(
+      fetchWithRetry('https://api.example.com/test', { method: 'GET' }, { maxRetries: 1, baseDelay: 1, timeout: 1 }),
+    ).rejects.toThrow('network down');
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+    randomSpy.mockRestore();
+  });
+
+  it('throws a fallback error when retries are disabled before entering the loop', async () => {
+    await expect(
+      fetchWithRetry('https://api.example.com/test', { method: 'GET' }, { maxRetries: -1 }),
+    ).rejects.toThrow('Fetch failed after retries');
+  });
+});