react-native-ai-hooks 0.3.0 → 0.5.0

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: test
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --include=dev
+
+      - name: Run Jest tests
+        run: npm test -- --config jest.config.cjs --ci

package/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to react-native-ai-hooks
+
+Thank you for your interest in contributing to react-native-ai-hooks.
+
+We are building a practical, provider-agnostic AI hooks toolkit for React Native, and contributions from the community are a big part of making it better. Whether you are fixing a bug, improving docs, adding a new hook, or integrating a new provider, your help is welcome.
+
+## Ways to Contribute
+
+- Report bugs and edge cases
+- Suggest new features or API improvements
+- Improve examples and documentation
+- Add support for new AI providers (for example Groq, Perplexity, or Mistral)
+- Create new hooks for common AI workflows
+- Add or improve tests
+
+## Reporting Bugs
+
+Please report bugs through GitHub Issues:
+
+- https://github.com/nikapkh/react-native-ai-hooks/issues
+
+Before opening an issue:
+
+- Check existing issues to avoid duplicates
+- Confirm the problem on the latest version if possible
+
+When opening a bug report, include:
+
+- A clear title and short summary
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Environment details (OS, React Native version, package version)
+- Minimal code snippet or repo that reproduces the problem
+- Relevant logs, stack traces, or screenshots
+
+## Development Setup
+
+1. Fork the repository on GitHub.
+2. Clone your fork.
+3. Install dependencies:
+
+```bash
+npm install
+```
+
+4. Run tests:
+
+```bash
+npm test
+```
+
+## Git Workflow
+
+Use this workflow for all contributions:
+
+1. Fork repository
+2. Create branch
+3. Commit changes
+4. Push branch
+5. Open pull request
+
+Example commands:
+
+```bash
+git checkout -b feat/add-mistral-provider
+# make changes
+git add .
+git commit -m "feat: add mistral provider adapter"
+git push origin feat/add-mistral-provider
+```
+
+## Pull Request Guidelines
+
+- Keep PRs focused and small when possible
+- Write clear commit messages
+- Describe the problem and solution in the PR description
+- Link related issues when relevant
+- Update docs when behavior or API changes
+
+All pull requests must pass existing tests before they can be merged.
+
+## Testing
+
+We use Jest for testing.
+
+- Test command: `npm test`
+- New functionality should include tests where practical
+- Bug fixes should include a regression test when possible
+
+Relevant test setup files:
+
+- [jest.config.cjs](jest.config.cjs)
+- [jest.setup.ts](jest.setup.ts)
+
+## Adding a New Provider
+
+If you want to add a provider such as Groq, Perplexity, or Mistral, a typical path is:
+
+- Add provider types and interfaces in [src/types/index.ts](src/types/index.ts)
+- Add request/response adapter logic in [src/utils/providerFactory.ts](src/utils/providerFactory.ts)
+- Ensure resilience behavior remains compatible with [src/utils/fetchWithRetry.ts](src/utils/fetchWithRetry.ts)
+- Add tests in [src/utils/__tests__](src/utils/__tests__)
+- Update docs in [README.md](README.md) and [docs/README.md](docs/README.md)
+
+## Adding a New Hook
+
+If you want to add a new hook:
+
+- Create the hook in [src/hooks](src/hooks)
+- Export it from [src/index.ts](src/index.ts)
+- Add or update relevant types in [src/types/index.ts](src/types/index.ts)
+- Add tests and docs for the new behavior
+
+## Communication and Conduct
+
+Please be respectful and constructive in issues and pull requests. Thoughtful feedback and collaboration help everyone ship better software.
+
+## Thank You
+
+Thanks again for helping improve react-native-ai-hooks.
+Your contributions make the library more reliable, more useful, and more accessible for the entire community.

package/README.md

@@ -5,40 +5,93 @@
 
 # react-native-ai-hooks
 
-AI hooks for React Native — add Claude, OpenAI & Gemini to your app in minutes.
+Build AI features in React Native without rebuilding the same plumbing every sprint.
 
-## Installation
+One hooks-first API for Claude, OpenAI, and Gemini.
 
-```bash
-npm install react-native-ai-hooks
-```
+## Why use this?
 
-## Hooks
+Most teams burn time on the same AI integration work:
+
+- Provider-specific request/response wiring
+- Retry, timeout, and error edge cases
+- Streaming token parsing
+- State handling for loading, cancellation, and failures
 
-- `useAIChat()` — multi-turn chat with streaming
-- `useAIStream()` — real-time token streaming  
-- `useImageAnalysis()` — camera/gallery → AI description
-- `useAIForm()` — AI-powered form validation
+This library gives you that foundation out of the box so you can ship product features, not infra glue.
+
+| What you want | What this gives you |
+|---|---|
+| Ship chat quickly | Drop-in hooks with minimal setup |
+| Avoid provider lock-in | Unified interface across providers |
+| Handle real-world failures | Built-in retries, backoff, timeout, abort |
+| Keep code clean | Strong TypeScript types and predictable APIs |
 
 ## Quick Start
 
 ```tsx
+// npm install react-native-ai-hooks
+
 import { useAIChat } from 'react-native-ai-hooks';
 
-const { messages, sendMessage, isLoading } = useAIChat({
-  apiKey: 'your-api-key',
-  provider: 'claude',
+export function Assistant() {
+  const { messages, sendMessage, isLoading, error } = useAIChat({
+    provider: 'anthropic',
+    apiKey: process.env.EXPO_PUBLIC_AI_KEY ?? '',
+    model: 'claude-sonnet-4-20250514',
+  });
+
+  // Example action
+  async function onAsk() {
+    await sendMessage('Draft a warm onboarding message for new users.');
+  }
+
+  return null;
+}
+```
+
+## Hooks
+
+- 💬 useAIChat: multi-turn conversation
+- ⚡ useAIStream: token streaming
+- 👁️ useImageAnalysis: image and vision workflows
+- 📝 useAIForm: AI-assisted form validation
+- 🎙️ useAIVoice: speech-to-text plus AI response
+- 🌍 useAITranslate: real-time translation
+- 📄 useAISummarize: concise text summaries
+- 🧠 useAICode: generate and explain code
+
+## Provider Support
+
+| Provider | Chat | Stream | Vision | Voice |
+|---|---|---|---|---|
+| Anthropic Claude | ✅ | ✅ | ✅ | ✅ |
+| OpenAI | ✅ | ✅ | ✅ | ✅ |
+| Gemini | ✅ | ✅ | 🔜 | 🔜 |
+
+## Security
+
+Use a backend proxy in production. Do not ship permanent provider API keys in app binaries.
+
+```tsx
+const { sendMessage } = useAIChat({
+  baseUrl: 'https://your-backend.com/api/ai',
 });
 ```
 
-## Providers
+## Example App
+
+See [example](./example) for a full app with provider switching, API key settings, and streaming chat.
+
+## Deep Technical Docs
+
+Detailed architecture and implementation references now live in [docs](./docs):
 
-| Provider | Status |
-|----------|--------|
-| Claude (Anthropic) | ✅ |
-| OpenAI | ✅ |
-| Gemini | 🔜 |
+- [Architecture Guide](./docs/ARCHITECTURE_GUIDE.md)
+- [Technical Specification](./docs/TECHNICAL_SPECIFICATION.md)
+- [Implementation Summary](./docs/IMPLEMENTATION_COMPLETE.md)
+- [Internal Architecture Notes](./docs/ARCHITECTURE.md)
 
 ## License
 
-MIT
+MIT © [nikapkh](https://github.com/nikapkh)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,301 @@
+/**
+ * React Native AI Hooks - Production Architecture
+ * 
+ * This file documents the complete internal architecture of the react-native-ai-hooks
+ * library, designed for type-safety, multi-provider support, and optimal performance.
+ */
+
+/**
+ * CORE ARCHITECTURE PRINCIPLES
+ * ============================
+ * 
+ * 1. Provider Abstraction Layer
+ *    - All API calls go through ProviderFactory
+ *    - Supports Anthropic, OpenAI, Gemini with uniform interface
+ *    - Easy to extend with new providers
+ * 
+ * 2. Unified Response Normalization
+ *    - Every provider returns standardized AIResponse object
+ *    - Includes text content, raw response, and token usage
+ *    - Enables seamless provider switching
+ * 
+ * 3. Resilience & Retry Logic
+ *    - fetchWithRetry handles exponential backoff
+ *    - Automatic rate-limit (429) handling with Retry-After header
+ *    - Timeout support using AbortController
+ *    - Configurable max retries and delays
+ * 
+ * 4. Performance Optimization
+ *    - useMemo for provider config to prevent recreations
+ *    - useCallback for all callback functions
+ *    - Proper cleanup for abort controllers and timers
+ *    - Minimal re-renders through optimized dependencies
+ * 
+ * 5. Error Handling Consistency
+ *    - All hooks follow same error pattern
+ *    - Errors caught and stored in hook state
+ *    - Abort errors handled gracefully (no-op vs throw)
+ * 
+ * 
+ * PROVIDER FACTORY ARCHITECTURE
+ * =============================
+ * 
+ * The ProviderFactory class (src/utils/providerFactory.ts) is the central hub
+ * for all API communications. It:
+ * 
+ * - Normalizes request/response formats across providers
+ * - Handles authentication (API keys, OAuth for different providers)
+ * - Manages baseUrl configuration for proxy/backend integration
+ * - Applies consistent rate-limit and timeout handling
+ * 
+ * Usage:
+ *   const provider = createProvider({
+ *     provider: 'anthropic',
+ *     apiKey: 'your-key',
+ *     model: 'claude-sonnet-4-20250514',
+ *     baseUrl: 'https://your-proxy.com', // Optional
+ *     timeout: 30000,
+ *     maxRetries: 3
+ *   });
+ * 
+ *   const response = await provider.makeRequest({
+ *     prompt: 'Hello, world!',
+ *     options: { temperature: 0.7, maxTokens: 1024 },
+ *     context: [] // Previous messages
+ *   });
+ * 
+ * Response Structure:
+ *   {
+ *     text: string,           // The AI response
+ *     raw: object,            // Raw provider response
+ *     usage: {
+ *       inputTokens?: number,
+ *       outputTokens?: number,
+ *       totalTokens?: number
+ *     }
+ *   }
+ * 
+ * 
+ * FETCH WITH RETRY UTILITY
+ * ========================
+ * 
+ * The fetchWithRetry function (src/utils/fetchWithRetry.ts) wraps fetch with:
+ * 
+ * - Exponential backoff: baseDelay * (backoffMultiplier ^ attempt)
+ * - Max delay cap: prevents excessive wait times
+ * - Rate limit handling: respects Retry-After header (429 status)
+ * - Timeout support: AbortController with configurable timeout
+ * - Server error retries: automatic retry on 5xx errors
+ * 
+ * Configuration:
+ *   {
+ *     maxRetries: 3,              // Total attempts
+ *     baseDelay: 1000,            // Initial delay (ms)
+ *     maxDelay: 10000,            // Cap delay (ms)
+ *     timeout: 30000,             // Per-request timeout (ms)
+ *     backoffMultiplier: 2        // Exponential backoff factor
+ *   }
+ * 
+ * 
+ * HOOK ARCHITECTURE
+ * =================
+ * 
+ * All hooks follow a consistent pattern:
+ * 
+ * 1. useAIChat - Multi-turn conversations
+ *    - Manages message history
+ *    - Auto-includes system prompt and context
+ *    - Returns messages array + send/abort/clear functions
+ * 
+ * 2. useAIStream - Real-time token streaming
+ *    - Streams responses token-by-token
+ *    - Handles both Anthropic and OpenAI stream formats
+ *    - Supports abort and cleanup
+ * 
+ * 3. useAIForm - Form validation against AI schema
+ *    - Validates entire form at once
+ *    - Parses AI response into errors object
+ *    - Returns FormValidationResult with isValid flag
+ * 
+ * 4. useImageAnalysis - Vision model integration
+ *    - Accepts URI or base64 image
+ *    - Supports Anthropic and OpenAI vision models
+ *    - Auto-converts URIs to base64
+ * 
+ * 5. useAITranslate - Real-time translation
+ *    - Auto-detects source language
+ *    - Supports configurable target language
+ *    - Debounced auto-translate option
+ * 
+ * 6. useAISummarize - Text summarization
+ *    - Adjustable summary length (short/medium/long)
+ *    - Maintains text accuracy and fidelity
+ * 
+ * 7. useAICode - Code generation and explanation
+ *    - Generate code in any language
+ *    - Explain existing code with focus options
+ * 
+ * 
+ * TYPE DEFINITIONS
+ * ================
+ * 
+ * Core types (src/types/index.ts):
+ * 
+ * - Message: Single message object with role, content, timestamp
+ * - AIProviderType: Union of 'anthropic' | 'openai' | 'gemini'
+ * - ProviderConfig: Configuration for creating providers
+ * - AIResponse: Normalized response structure
+ * - AIRequestOptions: Parameters for AI requests
+ * - UseAI*Options: Hook configuration interfaces
+ * - UseAI*Return: Hook return type interfaces
+ * - FormValidationRequest/Result: Form validation types
+ * - *Response: Provider-specific response interfaces
+ * 
+ * 
+ * MULTI-PROVIDER SUPPORT
+ * ======================
+ * 
+ * Supported Providers:
+ * 
+ * Provider    | Base URL                           | Auth Header
+ * ------------|------------------------------------|-----------------------
+ * Anthropic   | api.anthropic.com/v1/messages      | x-api-key
+ * OpenAI      | api.openai.com/v1/chat/completions | Authorization: Bearer
+ * Gemini      | generativelanguage.googleapis.com   | Key in URL param
+ * 
+ * To use different provider:
+ *   const { sendMessage } = useAIChat({
+ *     apiKey: 'your-key',
+ *     provider: 'openai',  // ← Change provider
+ *     model: 'gpt-4'       // ← Use provider-specific model
+ *   });
+ * 
+ * Router automatically selects matching endpoint and auth method.
+ * 
+ * 
+ * SECURITY BEST PRACTICES
+ * =======================
+ * 
+ * 1. API Key Management
+ *    - Store keys in environment variables, never hardcode
+ *    - Consider passing through backend proxy (baseUrl option)
+ * 
+ * 2. Backend Proxy Pattern
+ *    - Set baseUrl to your backend endpoint
+ *    - Backend validates and authenticates requests
+ *    - Example: https://my-api.com/ai (then /v1/messages appended)
+ * 
+ * 3. Rate Limiting
+ *    - All providers have rate limits
+ *    - fetchWithRetry handles 429 responses automatically
+ *    - Implement customer-side throttling for high-volume apps
+ * 
+ * 4. Timeout Configuration
+ *    - Default: 30 seconds per request
+ *    - Adjust based on model complexity and network
+ *    - Lower timeout for real-time UX requirements
+ * 
+ * 
+ * PERFORMANCE TUNING
+ * ==================
+ * 
+ * 1. Hook Dependencies
+ *    - Memoized provider configs via useMemo
+ *    - Wrapped callbacks with useCallback
+ *    - Deps list carefully curated to prevent recreations
+ * 
+ * 2. Message Management
+ *    - Store message history in component state
+ *    - Consider pagination for large conversations
+ *    - useCallback for sendMessage prevents parent re-renders
+ * 
+ * 3. Streaming Performance
+ *    - Streaming in useAIStream is incremental
+ *    - Response state updates are batched by React
+ *    - Large responses streamed smoothly token-by-token
+ * 
+ * 4. Image Analysis
+ *    - Image conversion to base64 happens async
+ *    - Large images may take time to convert
+ *    - Consider file size limits on client-side
+ * 
+ * 
+ * EXTENDING THE LIBRARY
+ * =====================
+ * 
+ * To add a new AI provider:
+ * 
+ * 1. Add provider type to AIProviderType union
+ * 2. Implement makeXyzRequest method in ProviderFactory
+ * 3. Implement normalizeXyzResponse method
+ * 4. Add default model to DEFAULT_MODEL_MAP in hooks
+ * 5. Test with all hook types
+ * 
+ * To add a new hook:
+ * 
+ * 1. Define UseAIXyzOptions interface in types
+ * 2. Define UseAIXyzReturn interface in types
+ * 3. Create src/hooks/useAIXyz.ts
+ * 4. Use ProviderFactory for all API calls
+ * 5. Follow same error/loading/cleanup patterns
+ * 6. Export from src/index.ts
+ * 
+ * 
+ * ERROR HANDLING PATTERNS
+ * =======================
+ * 
+ * All hooks follow this pattern:
+ * 
+ *   try {
+ *     // API call via ProviderFactory
+ *   } catch (err) {
+ *     if (isMountedRef.current) {
+ *       setError(err.message);
+ *     }
+ *   } finally {
+ *     if (isMountedRef.current) {
+ *       setIsLoading(false);
+ *     }
+ *   }
+ * 
+ * The isMountedRef prevents state updates on unmounted components.
+ * 
+ * 
+ * STREAMING IMPLEMENTATION
+ * ========================
+ * 
+ * Streaming works by parsing newline-delimited JSON from response.body:
+ * 
+ * Anthropic Format:
+ *   data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"hello"}}
+ * 
+ * OpenAI Format:
+ *   data: {"choices":[{"delta":{"content":"hello"}}]}
+ * 
+ * Both formats handled in useAIStream with provider-specific parsing.
+ * 
+ * 
+ * TESTING STRATEGY
+ * ================
+ * 
+ * Unit tests should verify:
+ * - Provider factory normalization for each provider
+ * - Retry logic with mock fetch
+ * - Hook state management (loading, error, data)
+ * - Callback cleanup on unmount
+ * - JSON parsing in form validation
+ * 
+ * Integration tests should verify:
+ * - Multi-turn conversation flow
+ * - Image analysis with different mime types
+ * - Form validation with complex schemas
+ * - Streaming response handling
+ * 
+ * E2E tests should verify:
+ * - Real API calls with live keys
+ * - Provider switching credentials
+ * - Rate limit retry behavior
+ * - Error recovery workflows
+ */
+
+export {};