@vanira/sdk-react-native 0.0.2

package/README.md

@@ -0,0 +1,239 @@
+# @vanira/sdk-react-native
+
+React Native SDK for Vanira voice AI + interactive preset protocol (calendar, forms, upload, camera, navigation, live vision, etc.).
+
+Separate from the web package [`@vanira/sdk`](https://www.npmjs.com/package/@vanira/sdk).
+
+---
+
+## Install
+
+```bash
+npm install @vanira/sdk-react-native \
+  react-native-webrtc \
+  react-native-permissions \
+  react-native-incall-manager \
+  react-native-image-picker \
+  @react-native-documents/picker \
+  react-native-view-shot \
+  react-native-vision-camera
+```
+
+**iOS** — add permission pods, then rebuild:
+
+```ruby
+# ios/Podfile
+require_relative '../node_modules/react-native-permissions/scripts/setup'
+
+setup_permissions([
+  'Camera',
+  'Microphone',
+  'PhotoLibrary',
+])
+```
+
+```bash
+cd ios && pod install
+```
+
+**Android** — add to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+```
+
+**App entry** — call `registerGlobals()` once before any SDK import:
+
+```js
+// index.js
+import {AppRegistry} from 'react-native';
+import {registerGlobals} from 'react-native-webrtc';
+
+registerGlobals();
+
+import App from './App';
+import {name as appName} from './app.json';
+
+AppRegistry.registerComponent(appName, () => App);
+```
+
+---
+
+## Quick start
+
+### 1. Wrap your app with `PresetHostProvider`
+
+The SDK renders preset modals (upload, calendar, camera, etc.) at the root.
+
+```tsx
+// App.tsx
+import {PresetHostProvider} from '@vanira/sdk-react-native';
+
+export default function App() {
+  return (
+    <PresetHostProvider>
+      {/* your navigation / screens */}
+    </PresetHostProvider>
+  );
+}
+```
+
+### 2. Start a voice session with `createReactNativeAI`
+
+```tsx
+import {
+  createReactNativeAI,
+  usePresetHost,
+  type ClientToolCall,
+  type VaniraAI,
+} from '@vanira/sdk-react-native';
+
+function VoiceScreen() {
+  const {setAiClient, setActiveToolCall} = usePresetHost();
+  const aiRef = useRef<VaniraAI | null>(null);
+
+  const startCall = async () => {
+    const ai = createReactNativeAI({
+      agentId: 'YOUR_AGENT_ID',
+      apiKey: 'pk_live_...',           // or sk_live_...
+      backendUrl: 'https://api.vanira.io',
+    });
+
+    // Route preset + tool calls to the SDK renderer
+    ai.on('preset', ({toolCall}) => setActiveToolCall(toolCall));
+    ai.on('tool_call', (toolCall: ClientToolCall) => setActiveToolCall(toolCall));
+
+    ai.on('connected', () => console.log('connected'));
+    ai.on('disconnected', () => {
+      aiRef.current = null;
+      setAiClient(null);
+    });
+
+    aiRef.current = ai;
+    setAiClient(ai);   // required — presets use ai.uploadMedia(), sendToolResult(), etc.
+    await ai.start();
+  };
+
+  const stopCall = () => {
+    aiRef.current?.stop();
+    aiRef.current = null;
+    setAiClient(null);
+  };
+
+  // render start/stop UI…
+}
+```
+
+### 3. Handle blocking tool results (optional)
+
+For tools with `execution_mode: 'blocking'`, send a result when your UI completes:
+
+```ts
+ai.sendToolResult(toolCall.tool_call_id, {success: true, data: {...}});
+```
+
+Preset modals in the SDK call this automatically when the user submits or cancels.
+
+---
+
+## Main exports
+
+| Export | Purpose |
+|--------|---------|
+| `createReactNativeAI()` | **Recommended** — voice client with RN adapters wired in |
+| `createReactNativeClient()` | Lower-level WebRTC client (same adapters) |
+| `PresetHostProvider` | App root — mounts preset UI overlay |
+| `usePresetHost()` | `{setAiClient, setActiveToolCall, clearPreset}` |
+| `VaniraAI` / `WebRTCClient` | Core classes (usually via factories above) |
+| `extractPresetId()` | Parse preset id from a tool call payload |
+| `hasContinueSession()` / `loadContinueSession()` | Resume last call (needs storage adapter) |
+| `createSyncStorageAdapter()` | Plug AsyncStorage (or similar) into the runtime |
+
+Legacy aliases `createVaniraAI` / `createVaniraClient` still work but are deprecated.
+
+---
+
+## Continue / resume calls
+
+Pass a storage backend on the runtime to persist `prospect_id` + `call_id` between sessions:
+
+```ts
+import {
+  createReactNativeAI,
+  createSyncStorageAdapter,
+  reactNativeRuntime,
+} from '@vanira/sdk-react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const runtime = {
+  ...reactNativeRuntime,
+  storage: createSyncStorageAdapter(AsyncStorage),
+};
+
+const ai = createReactNativeAI({
+  agentId: 'YOUR_AGENT_ID',
+  apiKey: 'pk_live_...',
+  backendUrl: 'https://api.vanira.io',
+  sessionBehavior: 'continue',  // or 'new'
+  runtime,
+});
+```
+
+---
+
+## Metro (npm install)
+
+When installed from npm (not a local `file:` path), Metro must transpile the SDK’s TypeScript source:
+
+```js
+// metro.config.js
+const path = require('path');
+const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), {
+  resolver: {unstable_enablePackageExports: true},
+  watchFolders: [
+    path.resolve(__dirname, 'node_modules/@vanira/sdk-react-native'),
+  ],
+});
+```
+
+For monorepo local dev with `"file:../vanira-sdk-rn"`, point Metro at the sibling folder (see `MyApp/metro.config.js` in this repo).
+
+---
+
+## Presets included
+
+| Preset | Description |
+|--------|-------------|
+| `vanira_upload` | File picker — JPEG, PNG, PDF, TXT, CSV |
+| `vanira_calendar` | Date / booking picker |
+| `vanira_form` | Dynamic form modal |
+| `vanira_camera` | Camera capture + upload |
+| `vanira_navigate` | In-app or external navigation |
+| `vanira_live_vision` | Live camera frames (requires `react-native-vision-camera`) |
+| Chalkboard | Type / erase text overlays |
+
+The app only needs to call `setActiveToolCall()` — the SDK renders the UI and sends results back to the agent.
+
+---
+
+## Platform notes
+
+- Import from **`@vanira/sdk-react-native`** only — do not use `@vanira/sdk` (web) in RN apps.
+- `registerGlobals()` from `react-native-webrtc` is **required** at app entry.
+- Live vision uses Vision Camera (not `RTCView` + ViewShot — black frames on iOS).
+- Upload uses gallery + document picker; iOS needs Photo Library permission in Podfile + Info.plist.
+
+---
+
+## Relationship to web SDK
+
+| Package | Platform |
+|---------|----------|
+| `@vanira/sdk` | Browser / web widget |
+| `@vanira/sdk-react-native` | React Native |
+
+Same voice protocol and preset IDs; different adapters and UI layer.

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@vanira/sdk-react-native",
+    "version": "0.0.2",
+    "description": "Vanira Voice SDK for React Native — WebRTC, presets protocol, RN adapters",
+    "author": "Vanira <developers@vanira.io>",
+    "license": "MIT",
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": {
+            "import": "./src/index.ts",
+            "types": "./src/index.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "scripts": {
+        "test": "vitest run --config vitest.config.ts",
+        "test:watch": "vitest --config vitest.config.ts",
+        "prepublishOnly": "npm test"
+    },
+    "react-native": "./src/index.ts",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vanira-ai/sdk"
+    },
+    "keywords": [
+        "react-native",
+        "voice-ai",
+        "webrtc",
+        "vanira",
+        "sdk"
+    ],
+    "peerDependencies": {
+        "react": ">=18",
+        "react-native": ">=0.74",
+        "react-native-webrtc": ">=124",
+        "react-native-image-picker": ">=8",
+        "@react-native-documents/picker": ">=10",
+        "react-native-view-shot": ">=4",
+        "react-native-incall-manager": ">=4",
+        "react-native-permissions": ">=5",
+        "react-native-vision-camera": ">=4.0.0"
+    },
+    "devDependencies": {
+        "@vitest/coverage-v8": "^4.1.6",
+        "typescript": "^5.0.0",
+        "vite": "^5.0.0",
+        "vitest": "^4.1.6"
+    }
+}

package/src/__tests__/WebRTCClient.integration.test.ts

@@ -0,0 +1,396 @@
+/**
+ * WebRTCClient adapter wiring integration tests (Task 0.2)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const TEST_ICE_SERVERS = [{ urls: 'stun:stun.test.example:3478' }] as RTCIceServer[];
+const TEST_WORKER_URL = 'https://worker.example.com/webrtc?token=abc';
+
+function mockFetchResponse(body: unknown): Response {
+    return {
+        ok: true,
+        text: () => Promise.resolve(JSON.stringify(body)),
+    } as Response;
+}
+
+function makeMockRTCPeerConnection() {
+    return {
+        addTrack: vi.fn(),
+        createDataChannel: vi.fn(() => makeMockRTCDataChannel()),
+        createOffer: vi.fn(() => Promise.resolve({ type: 'offer', sdp: 'mock-sdp' })),
+        setLocalDescription: vi.fn(() => Promise.resolve()),
+        setRemoteDescription: vi.fn(() => Promise.resolve()),
+        getSenders: vi.fn(() => []),
+        close: vi.fn(),
+        iceGatheringState: 'complete',
+        connectionState: 'new',
+        iceConnectionState: 'new',
+        localDescription: { type: 'offer', sdp: 'mock-sdp' },
+        ontrack: null as ((event: RTCTrackEvent) => void) | null,
+        onconnectionstatechange: null as (() => void) | null,
+        oniceconnectionstatechange: null as (() => void) | null,
+        onicecandidate: null as ((event: RTCPeerConnectionIceEvent) => void) | null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+    };
+}
+
+function makeMockRTCDataChannel() {
+    return {
+        send: vi.fn(),
+        close: vi.fn(),
+        readyState: 'open' as RTCDataChannelState,
+        onopen: null as (() => void) | null,
+        onmessage: null as ((e: MessageEvent) => void) | null,
+        onerror: null as ((e: Event) => void) | null,
+    };
+}
+
+describe('WebRTCClient constructor storage', () => {
+    it('reads prospect and call id from storage when sessionBehavior is continue', async () => {
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        const storage = new MemoryStorageAdapter();
+        storage.setItem('vanira_prospect_id', 'prospect_stored');
+        storage.setItem('vanira_latest_call_id', 'call_stored');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            sessionBehavior: 'continue',
+            storageAdapter: storage,
+        });
+
+        expect(client.prospectId).toBe('prospect_stored');
+        expect(client.callId).toBe('call_stored');
+    });
+
+    it('does not read call id from storage when sessionBehavior is not continue', async () => {
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        const storage = new MemoryStorageAdapter();
+        storage.setItem('vanira_latest_call_id', 'call_stored');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            storageAdapter: storage,
+        });
+
+        expect(client.callId).toBeUndefined();
+    });
+});
+
+describe('WebRTCClient generateCallId', () => {
+    it('uses web_ prefix for bare web client', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+        });
+        const id = client.generateCallId();
+        expect(id.startsWith('web_')).toBe(true);
+    });
+
+    it('uses rn_ prefix for react-native runtime', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { reactNativeRuntime } = await import('../runtime/reactNativeRuntime');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            runtime: reactNativeRuntime,
+        });
+        const id = client.generateCallId();
+        expect(id.startsWith('rn_')).toBe(true);
+    });
+});
+
+describe('WebRTCClient createCall body', () => {
+    beforeEach(() => {
+        Object.defineProperty(globalThis, 'navigator', {
+            value: { product: 'Gecko', mediaDevices: { getUserMedia: vi.fn() } },
+            configurable: true,
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('includes runtime browser for bare web client', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+            mockFetchResponse({
+                call_id: 'c1',
+                worker_url: TEST_WORKER_URL,
+                ice_servers: [{ urls: 'stun:stun.test.example:3478' }],
+            }),
+        );
+
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            apiKey: 'sk_test',
+        });
+
+        try {
+            await client.createCall();
+        } catch {
+            // connect may fail in test env
+        }
+
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+        expect(body.type).toBe('web');
+        expect(body.runtime).toBe('browser');
+        expect(body.mode).toBeUndefined();
+    });
+
+    it('includes mode continue only when sessionBehavior is continue', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+            mockFetchResponse({
+                call_id: 'c1',
+                worker_url: TEST_WORKER_URL,
+                ice_servers: [{ urls: 'stun:stun.test.example:3478' }],
+            }),
+        );
+
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            apiKey: 'sk_test',
+            sessionBehavior: 'continue',
+        });
+
+        try {
+            await client.createCall();
+        } catch {
+            // connect may fail
+        }
+
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+        expect(body.mode).toBe('continue');
+    });
+
+    it('persists ids via storage after createCall', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+            mockFetchResponse({
+                call_id: 'call_new',
+                prospect_id: 'prospect_new',
+                worker_url: TEST_WORKER_URL,
+                ice_servers: [{ urls: 'stun:stun.test.example:3478' }],
+            }),
+        );
+
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        const storage = new MemoryStorageAdapter();
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            apiKey: 'sk_test',
+            storageAdapter: storage,
+        });
+
+        try {
+            await client.createCall();
+        } catch {
+            // connect may fail
+        }
+
+        expect(storage.getItem('vanira_prospect_id')).toBe('prospect_new');
+        expect(storage.getItem('vanira_latest_call_id')).toBe('call_new');
+        expect(fetchSpy).toHaveBeenCalled();
+    });
+});
+
+describe('WebRTCClient adapter wiring in connect', () => {
+    let mockPc: ReturnType<typeof makeMockRTCPeerConnection>;
+    let mockChannel: ReturnType<typeof makeMockRTCDataChannel>;
+
+    beforeEach(() => {
+        mockPc = makeMockRTCPeerConnection();
+        mockChannel = makeMockRTCDataChannel();
+        mockPc.createDataChannel.mockReturnValue(mockChannel);
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        function MockRTC(this: any) {
+            Object.assign(this, mockPc);
+        }
+        (globalThis as unknown as Record<string, unknown>).RTCPeerConnection = MockRTC;
+
+        Object.defineProperty(globalThis, 'navigator', {
+            value: {
+                product: 'Gecko',
+                userAgent: 'Mozilla/5.0',
+                platform: 'MacIntel',
+                maxTouchPoints: 0,
+                mediaDevices: {
+                    getUserMedia: vi.fn(() => Promise.resolve({
+                        getTracks: () => [{ kind: 'audio', stop: vi.fn() }],
+                    })),
+                },
+            },
+            configurable: true,
+        });
+
+        vi.spyOn(globalThis, 'fetch').mockImplementation((input: RequestInfo | URL) => {
+            const url = String(input);
+            if (url.includes('/webrtc/ice')) {
+                return Promise.resolve({
+                    ok: true,
+                    text: () => Promise.resolve(JSON.stringify({ candidates: [] })),
+                } as Response);
+            }
+            return Promise.resolve({
+                ok: true,
+                text: () =>
+                    Promise.resolve(
+                        JSON.stringify({ answer: { type: 'answer', sdp: 'answer-sdp' } }),
+                    ),
+            } as Response);
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('calls peerAdapter.create with configured iceServers', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+
+        const createSpy = vi.spyOn(browserRuntime.peer, 'create');
+
+        const customIce = [{ urls: 'stun:custom.example.com:3478' }];
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: TEST_WORKER_URL,
+            callId: 'call_1',
+            prospectId: 'p_1',
+            runtime: browserRuntime,
+            iceServers: customIce as RTCIceServer[],
+        });
+
+        await client.connect();
+
+        expect(createSpy).toHaveBeenCalledWith({
+            iceServers: customIce,
+            iceTransportPolicy: 'all',
+        });
+    });
+
+    it('calls mediaAdapter.getUserAudio with audio constraints', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+
+        const getUserSpy = vi.spyOn(browserRuntime.media, 'getUserAudio');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: TEST_WORKER_URL,
+            callId: 'call_1',
+            runtime: browserRuntime,
+            iceServers: TEST_ICE_SERVERS,
+        });
+
+        await client.connect();
+
+        expect(getUserSpy).toHaveBeenCalledWith({
+            echoCancellation: true,
+            noiseSuppression: true,
+            autoGainControl: true,
+            sampleRate: { ideal: 16000 },
+            channelCount: 1,
+        });
+    });
+
+    it('binds dataChannelAdapter and routes string messages to handleControlEvent', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+
+        const onTranscription = vi.fn();
+        const bindSpy = vi.spyOn(browserRuntime.dataChannel, 'bind');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com/webrtc?token=abc',
+            callId: 'call_1',
+            runtime: browserRuntime,
+            iceServers: TEST_ICE_SERVERS,
+            onTranscription,
+        });
+
+        await client.connect();
+
+        expect(bindSpy).toHaveBeenCalled();
+        const handlers = bindSpy.mock.calls[0][1];
+        handlers.onMessage({
+            text: JSON.stringify({ event: 'transcription', text: 'hello', isFinal: true }),
+        });
+        expect(onTranscription).toHaveBeenCalledWith('hello', true);
+    });
+
+    it('sendEvent uses dcController when channel is open', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+
+        const bindSpy = vi.spyOn(browserRuntime.dataChannel, 'bind');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: TEST_WORKER_URL,
+            callId: 'call_1',
+            runtime: browserRuntime,
+            iceServers: TEST_ICE_SERVERS,
+        });
+
+        await client.connect();
+
+        const handlers = bindSpy.mock.calls[0][1];
+        handlers.onOpen();
+
+        client.sendEvent('test_event', { foo: 'bar' });
+        expect(mockChannel.send).toHaveBeenCalledWith(
+            JSON.stringify({ event: 'test_event', foo: 'bar' })
+        );
+    });
+});
+
+describe('WebRTCClient handleControlEvent ack ordering', () => {
+    it('sendToolAck fires before onClientToolCall for preset tools', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+
+        const order: string[] = [];
+        const onClientToolCall = vi.fn(() => order.push('callback'));
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            callId: 'call_1',
+            runtime: browserRuntime,
+            onPreset: () => order.push('onPreset'),
+            onClientToolCall,
+        });
+
+        const sendToolAckSpy = vi.spyOn(client, 'sendToolAck').mockImplementation(() => {
+            order.push('ack');
+        });
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (client as any).handleControlEvent({
+            event: 'client_tool_call',
+            tool_call: {
+                tool_call_id: 'tc_1',
+                arguments: { preset_id: 'demo' },
+            },
+        });
+
+        expect(sendToolAckSpy).toHaveBeenCalledWith('tc_1');
+        expect(onClientToolCall).toHaveBeenCalled();
+        expect(order).toEqual(['ack', 'onPreset', 'callback']);
+    });
+});