react-native-ai-hooks 0.4.0 → 0.6.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,50 +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;
+}
 ```
-## ⚠️ Security Note
 
-Never expose your API key in client-side code. Use a backend proxy or environment variables:
+## 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.
 
-```bash
-# .env
-ANTHROPIC_API_KEY=your-key-here
+```tsx
+const { sendMessage } = useAIChat({
+  baseUrl: 'https://your-backend.com/api/ai',
+});
 ```
 
-Then fetch responses through your own backend endpoint.
+## Example App
+
+See [example](./example) for a full app with provider switching, API key settings, and streaming chat.
+
+## Deep Technical Docs
 
-## Providers
+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/{IMPLEMENTATION_COMPLETE.md → docs/IMPLEMENTATION_COMPLETE.md}

@@ -88,8 +88,8 @@
 ### Documentation (2)
 | File | Purpose | Status |
 |------|---------|--------|
-| `src/ARCHITECTURE.md` | Internal architecture details | ✅ Complete |
-| `ARCHITECTURE_GUIDE.md` | Developer & maintainer guide | ✅ Complete |
+| `docs/ARCHITECTURE.md` | Internal architecture details | ✅ Complete |
+| `docs/ARCHITECTURE_GUIDE.md` | Developer & maintainer guide | ✅ Complete |
 
 ---
 

package/docs/README.md

@@ -0,0 +1,17 @@
+# Documentation
+
+Deep technical references for react-native-ai-hooks live in this folder.
+
+## Read First
+
+1. [Architecture Guide](./ARCHITECTURE_GUIDE.md)
+2. [Technical Specification](./TECHNICAL_SPECIFICATION.md)
+3. [Implementation Complete](./IMPLEMENTATION_COMPLETE.md)
+4. [Internal Architecture Notes](./ARCHITECTURE.md)
+
+## What This Folder Covers
+
+- Provider abstraction and normalization
+- Retry and timeout strategy
+- Hook design patterns and type system
+- Security and performance considerations

package/jest.config.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  clearMocks: true,
+};

package/jest.setup.ts

@@ -0,0 +1,28 @@
+const originalConsoleError = console.error;
+let consoleErrorSpy: jest.SpyInstance;
+
+beforeAll(() => {
+  global.fetch = jest.fn();
+
+  // Required by React 18+ testing helpers so state updates inside act are tracked correctly.
+  (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+  consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+    const firstArg = args[0];
+    const message = typeof firstArg === 'string' ? firstArg : '';
+
+    if (message.includes('react-test-renderer is deprecated')) {
+      return;
+    }
+
+    originalConsoleError(...(args as Parameters<typeof console.error>));
+  });
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+afterAll(() => {
+  consoleErrorSpy?.mockRestore();
+});

package/package.json

@@ -1,17 +1,31 @@
 {
   "name": "react-native-ai-hooks",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "AI hooks for React Native — useAIChat, useAIStream, useImageAnalysis. Works with Claude, OpenAI & Gemini.",
   "main": "src/index.ts",
   "types": "src/index.ts",
-  "keywords": ["react-native", "ai", "claude", "openai", "hooks", "expo"],
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "react-native",
+    "ai",
+    "claude",
+    "openai",
+    "hooks",
+    "expo"
+  ],
   "author": "nikapkh",
   "license": "MIT",
   "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "react-test-renderer": "^19.2.0",
+    "ts-jest": "^29.4.9",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-native": ">=0.70.0"
   }
-}
+}