react-native-usesense 1.0.0 → 2.1.0

package/README.md

@@ -1,22 +1,36 @@
 # UseSense React Native
 
-React Native plugin for human presence verification. Wraps the native UseSense iOS and Android SDKs into a single cross-platform package.
-
-UseSense verifies that a real human — not a bot, deepfake, or replay attack — is behind the camera during identity verification sessions. Three independent pillars run in parallel on every session:
-
-- **DeepSense** (Channel & Device Integrity): Platform attestation, runtime integrity, capture pipeline analysis. Produces a `channelTrustScore` (0-100).
-- **LiveSense** (Multimodal Proof-of-Life): Facial dynamics, visual integrity, presentation attack detection, audio deepfake detection. Produces a `livenessScore` (0-100).
-- **MatchSense** (Identity Collision Detection): 1:N face search (enrollment), 1:1 face verification (authentication), cross-identity risk scoring. Produces a `matchSenseRiskScore` (0-100).
-
-A fused `presenceConfidence` score and a final `decision` (`approved` / `rejected` / `manual_review`) are returned. The definitive verdict is delivered via HMAC-SHA256 signed webhook to your backend. **The SDK result is for UI feedback only and must never be trusted for access-control decisions.**
+React Native plugin for human presence verification. Wraps the native
+UseSense iOS and Android SDKs into a single cross-platform package.
+
+UseSense verifies that a real human — not a bot, deepfake, or replay
+attack — is behind the camera during identity verification sessions.
+Three independent pillars run in parallel on every session:
+
+- **DeepSense** (Channel & Device Integrity): platform attestation,
+  runtime integrity, capture pipeline analysis.
+- **LiveSense** (Multimodal Proof-of-Life): facial dynamics, visual
+  integrity, presentation attack detection, audio deepfake detection.
+- **MatchSense** (Identity Collision Detection): 1:N face search
+  on enrollment, 1:1 face verification on authentication,
+  cross-identity risk scoring.
+
+A final `decision` (`APPROVE` / `REJECT` / `MANUAL_REVIEW`) is
+returned to the React Native side. **The SDK result is intentionally
+redacted — pillar scores, the session signature, and the full verdict
+metadata are NOT exposed to the client.** Those fields are delivered
+to your backend via an HMAC-SHA256 signed webhook. Never trust the
+client-side decision for access-control decisions; it's for UI
+feedback only.
 
 ## Requirements
 
-- React Native 0.73+ (New Architecture supported; Old Architecture via interop layer)
-- iOS 14.0+
-- Android API 24+ (Android 7.0)
-- Xcode 15.0+
-- Node.js 18+
+- React Native **0.73+** (New Architecture supported; Old
+  Architecture via interop layer)
+- iOS **15.0+** (native SDK requires iOS 15)
+- Android **API 28+** (Android 9.0; native SDK requires API 28)
+- Xcode **15.0+**
+- Node.js **18+**
 - Device with front-facing camera (required on both platforms)
 
 ## Installation
@@ -27,167 +41,191 @@ npm install react-native-usesense
 yarn add react-native-usesense
 ```
 
-### iOS Setup
+### iOS setup
 
 ```bash
 cd ios && pod install
 ```
 
-The native UseSense iOS SDK is installed automatically as a CocoaPod dependency.
-
-Add required permissions to your `Info.plist`:
+The native UseSense iOS SDK is installed automatically as a CocoaPod
+dependency from the public CocoaPods trunk (`UseSenseSDK`, pinned to
+`~> 4.2`). Add required permissions to your `Info.plist`:
 
 ```xml
 <key>NSCameraUsageDescription</key>
 <string>UseSense needs camera access to verify your identity.</string>
 
-<!-- Only if enableAudio is true -->
+<!-- Only if your verification flow includes audio challenges -->
 <key>NSMicrophoneUsageDescription</key>
 <string>UseSense needs microphone access for voice verification.</string>
-
-<!-- Optional, improves DeepSense accuracy -->
-<key>NSMotionUsageDescription</key>
-<string>UseSense uses motion data to improve verification accuracy.</string>
 ```
 
-### Android Setup
+### Android setup
 
-The native UseSense Android SDK is pulled automatically via Maven Central.
+The native UseSense Android SDK is pulled automatically from Maven
+Central (`ai.usesense:sdk:4.2.1`). `mavenCentral()` is in every
+Android project by default, so no custom repository declaration is
+needed.
 
 Add required permissions to your `AndroidManifest.xml`:
 
 ```xml
 <uses-permission android:name="android.permission.CAMERA" />
 <uses-permission android:name="android.permission.INTERNET" />
-<!-- Only if enableAudio is true -->
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 ```
 
-No additional Gradle configuration needed. Auto-linking handles registration.
+Auto-linking handles registration; no additional Gradle configuration
+needed.
 
 ### New Architecture
 
-The plugin supports React Native's New Architecture (Turbo Modules) out of the box. If your project has the New Architecture enabled, the plugin uses the Turbo Module path automatically. No configuration needed.
+The plugin supports React Native's New Architecture (Turbo Modules)
+out of the box. If your project has the New Architecture enabled, the
+plugin uses the Turbo Module path automatically. For projects still on
+the Old Architecture (Bridge), the plugin works unchanged.
 
-For projects still on the Old Architecture (Bridge), the plugin includes an interop layer and works without changes.
-
-## Quick Start
+## Quick start
 
 ```typescript
 import { UseSense } from 'react-native-usesense';
 
-// 1. Initialize (once, e.g. in App.tsx or app entry)
+// 1. Initialize once, e.g. in your app entry point or the screen
+//    that renders verification.
 await UseSense.initialize({
-  apiKey: 'your_sandbox_api_key',
-  environment: 'sandbox',
+  apiKey: 'sk_sandbox_your_key_here',
+  environment: 'sandbox', // or 'production' or 'auto'
+});
+
+// 2. (Optional) Subscribe to lifecycle events for a progress UI.
+const sub = UseSense.addListener((event) => {
+  console.log(event.type, event.data);
 });
 
-// 2. Run a verification session
+// 3. Run a verification session. Presents a full-screen native
+//    camera activity.
 try {
-  const result = await UseSense.startSession({
+  const result = await UseSense.startVerification({
     sessionType: 'enrollment',
   });
-  console.log('Decision:', result.decision);
-  console.log('Liveness:', result.livenessScore);
-  console.log('Channel Trust:', result.channelTrustScore);
-  console.log('MatchSense Risk:', result.matchSenseRiskScore);
+  console.log('Decision:', result.decision); // 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW'
+  console.log('Session ID:', result.sessionId);
 } catch (error) {
   console.error('Verification failed:', error.code, error.message);
+} finally {
+  sub.remove();
 }
 
-// The definitive verdict arrives at your backend via webhook.
-// The SDK result is for UI feedback only.
+// 4. Your backend receives the full signed verdict via webhook.
+//    That's where you read pillar scores and make access decisions.
 ```
 
 ## Configuration
 
-Full reference for `UseSenseConfig`:
+```typescript
+interface UseSenseConfig {
+  apiKey: string;
+  environment?: 'sandbox' | 'production' | 'auto'; // default: 'auto'
+  apiEndpoint?: string;       // default: https://api.usesense.ai/v1
+  branding?: BrandingConfig;  // optional UI customization
+}
+
+interface BrandingConfig {
+  logoUrl?: string;
+  primaryColor?: string;     // hex, e.g. '#4F7CFF'
+  buttonRadius?: number;     // in dp
+  fontFamily?: string;
+  displayName?: string;      // Android only
+  redirectUrl?: string;      // Android only
+}
+```
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `apiKey` | `string` | Yes | — | Your API key from the [UseSense dashboard](https://app.usesense.ai) |
-| `environment` | `'production' \| 'sandbox'` | No | `'sandbox'` | Target environment |
-| `organizationId` | `string` | No | — | Organization ID (inferred from API key) |
-| `sessionType` | `'enrollment' \| 'authentication'` | No | `'enrollment'` | Default session type |
-| `identityId` | `string` | No | — | Identity ID for authentication sessions |
-| `challengePolicy` | `'standard' \| 'enhanced' \| 'adaptive'` | No | `'standard'` | Challenge difficulty policy |
-| `enableAudio` | `boolean` | No | `false` | Enable audio capture for voice deepfake detection |
-| `timeout` | `number` | No | `60000` | Maximum session duration in milliseconds |
-| `metadata` | `Record<string, string>` | No | — | Custom key-value pairs attached to session |
+`environment: 'auto'` (the default) detects the environment from the
+API key prefix: `sk_sandbox_*` / `pk_sandbox_*` → sandbox,
+`sk_prod_*` / `pk_prod_*` → production. Set it explicitly if you want
+to override the auto-detection.
 
-## Session Types
+## Session types
 
 ### Enrollment
 
-First-time face registration. The system indexes the user's face, performs a 1:N duplicate scan via MatchSense, and creates an identity record if approved.
+First-time face registration. The system captures the user's face,
+runs a 1:N duplicate scan via MatchSense, and creates an identity
+record if approved.
 
 ```typescript
-const result = await UseSense.startSession({
+const result = await UseSense.startVerification({
   sessionType: 'enrollment',
+  externalUserId: 'user_12345', // your internal user ID
 });
 
-if (result.decision === 'approved') {
-  // Identity created. Store result.sessionId for reference.
-  console.log('Enrollment approved. Presence confidence:', result.presenceConfidence);
+if (result.isApproved) {
+  // Identity created. Store result.sessionId for reference; the
+  // identity ID arrives on your backend via the webhook.
 }
 ```
 
 ### Authentication
 
-Returning user claims an existing identity. The system performs 1:1 verification against the enrolled template, plus a 1:N cross-identity scan.
+Returning user claims an existing identity. The system performs a
+1:1 verification against the enrolled template, plus a 1:N
+cross-identity scan to detect identity swaps. The `identityId` must
+be an identity that was previously enrolled — your backend persisted
+it when the enrollment webhook fired.
 
 ```typescript
-const result = await UseSense.startSession({
+const result = await UseSense.startVerification({
   sessionType: 'authentication',
-  identityId: 'idn_abc123', // required for authentication
+  identityId: 'idn_abc123',
+  externalUserId: 'user_12345',
 });
 
-if (result.decision === 'approved') {
-  console.log('Identity verified');
+if (result.isApproved) {
+  // Identity verified. Proceed with login / transaction / action.
 }
 ```
 
-## Handling Results
+## Handling results
 
-`UseSenseResult` contains the full verification breakdown:
+`UseSenseResult` is the **only** shape returned to JS. It contains
+five fields and three convenience booleans:
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `sessionId` | `string` | Unique session identifier |
-| `decision` | `'approved' \| 'rejected' \| 'manual_review'` | Verification decision |
-| `channelTrustScore` | `number` | DeepSense channel integrity score (0-100). Higher is more trusted. |
-| `livenessScore` | `number` | LiveSense liveness score (0-100). Higher means more likely live. |
-| `matchSenseRiskScore` | `number` | MatchSense risk score (0-100). Lower is better. |
-| `presenceConfidence` | `number` | Fused presence confidence (0-100). Higher is more confident. |
-| `reasons` | `string[]` | Reasons contributing to the decision |
-| `ruleTriggered` | `string?` | Rule that triggered the decision, if any |
-| `recommendedAction` | `string?` | Recommended action for the integrator |
-| `sessionSignature` | `string` | Cryptographic signature for result verification |
-
-Handle each decision type in your component:
+| `sessionType` | `string \| null` | `'enrollment'` or `'authentication'` |
+| `identityId` | `string \| null` | Assigned identity ID (enrollment) or verified identity (authentication) |
+| `decision` | `'APPROVE' \| 'REJECT' \| 'MANUAL_REVIEW'` | Final decision from the server |
+| `timestamp` | `string` | ISO 8601 timestamp |
+| `isApproved` | `boolean` | Convenience: `decision === 'APPROVE'` |
+| `isRejected` | `boolean` | Convenience: `decision === 'REJECT'` |
+| `isPendingReview` | `boolean` | Convenience: `decision === 'MANUAL_REVIEW'` |
+
+**Pillar scores, the fused confidence value, the session signature,
+and the full verdict metadata are intentionally NOT returned across
+the bridge.** Consume them via the signed webhook delivered to your
+backend. This design prevents client-side reverse-engineering of the
+scoring logic and forces access-control decisions onto the backend
+where they belong.
 
 ```tsx
 import React from 'react';
-import { View, Text, Button } from 'react-native';
+import { View, Button } from 'react-native';
 import { UseSense, UseSenseResult } from 'react-native-usesense';
 
 function VerificationScreen({ navigation }) {
   const handleVerify = async () => {
     try {
-      const result: UseSenseResult = await UseSense.startSession({
+      const result = await UseSense.startVerification({
         sessionType: 'enrollment',
       });
 
-      switch (result.decision) {
-        case 'approved':
-          navigation.navigate('Home');
-          break;
-        case 'rejected':
-          navigation.navigate('Retry', { reasons: result.reasons });
-          break;
-        case 'manual_review':
-          navigation.navigate('PendingReview', { sessionId: result.sessionId });
-          break;
+      if (result.isApproved) {
+        navigation.navigate('Home');
+      } else if (result.isRejected) {
+        navigation.navigate('Retry', { sessionId: result.sessionId });
+      } else if (result.isPendingReview) {
+        navigation.navigate('PendingReview', { sessionId: result.sessionId });
       }
     } catch (error) {
       console.error('Session failed:', error.code);
@@ -202,328 +240,184 @@ function VerificationScreen({ navigation }) {
 }
 ```
 
-## Event Listening
+## Events
 
-Subscribe to real-time events during the verification lifecycle. Call `addListener()` before `startSession()` to receive all events.
-
-```tsx
-import { UseSense, UseSenseEvent } from 'react-native-usesense';
-import { useEffect, useState } from 'react';
-
-function VerificationScreen() {
-  const [events, setEvents] = useState<UseSenseEvent[]>([]);
-
-  useEffect(() => {
-    const listener = UseSense.addListener((event) => {
-      setEvents(prev => [...prev, event]);
-
-      switch (event.type) {
-        case 'session_started':
-          console.log('Session:', event.sessionId);
-          break;
-        case 'challenge_presented':
-          console.log('Challenge:', event.challengeType);
-          break;
-        case 'challenge_completed':
-          console.log('Challenge completed:', event.challengeType);
-          break;
-        case 'processing':
-          console.log('Stage:', event.stage); // 'deepsense' | 'livesense' | 'matchsense' | 'fusion'
-          break;
-        case 'session_completed':
-          console.log('Result:', event.result.decision);
-          break;
-        case 'session_error':
-          console.error('Error:', event.error.code);
-          break;
-      }
-    });
-
-    return () => listener.remove();
-  }, []);
-
-  // render events...
-}
-```
-
-## Error Handling
-
-All errors include a machine-readable `code` and a human-readable `message`.
-
-| Code | Description | Recovery |
-|------|-------------|----------|
-| `camera_permission_denied` | Camera access not granted | Prompt user; link to device Settings via `Linking.openSettings()` |
-| `microphone_permission_denied` | Microphone not granted (audio enabled) | Prompt or disable audio |
-| `session_timeout` | Exceeded configured timeout | Retry with new session |
-| `session_expired` | 15-minute server-side expiry | Start new session |
-| `network_error` | API unreachable | Check connectivity, retry |
-| `sdk_not_initialized` | `startSession()` before `initialize()` | Call `initialize()` at app startup |
-| `invalid_config` | Missing or invalid config | Check `apiKey` and required fields |
-| `invalid_api_key` | Key rejected by server | Verify in dashboard; check environment |
-| `insufficient_credits` | Zero credit balance | Purchase credits in dashboard |
-| `identity_not_found` | `identityId` doesn't exist | Verify identity was enrolled |
-| `camera_unavailable` | No front camera found | Inform user |
-| `device_not_supported` | Fails hardware requirements | Inform user |
-| `session_cancelled` | Cancelled by user or programmatically | Handle gracefully |
-| `play_integrity_unavailable` | (Android) Play Integrity API unavailable | DeepSense uses fallback signals |
-| `server_error` | 5xx from UseSense API | Retry; contact support if persistent |
+Subscribe to real-time lifecycle events via `UseSense.addListener`.
+Events flow from both iOS and Android in the same canonical
+`UPPER_SNAKE_CASE` shape so you can key off `event.type` without any
+platform branching.
 
 ```typescript
-import { UseSense, UseSenseError } from 'react-native-usesense';
-import { Alert, Linking } from 'react-native';
-
-async function verify() {
-  try {
-    const result = await UseSense.startSession({ sessionType: 'enrollment' });
-    // handle result
-  } catch (error) {
-    const err = error as UseSenseError;
-
-    switch (err.code) {
-      case 'camera_permission_denied':
-        Alert.alert(
-          'Camera Required',
-          'UseSense needs camera access to verify your identity.',
-          [
-            { text: 'Cancel', style: 'cancel' },
-            { text: 'Open Settings', onPress: () => Linking.openSettings() },
-          ],
-        );
-        break;
-
-      case 'session_timeout':
-      case 'session_expired':
-      case 'network_error':
-        Alert.alert('Try Again', 'The session could not be completed. Please try again.');
-        break;
-
-      case 'insufficient_credits':
-        console.error('UseSense credit balance is zero');
-        Alert.alert('Service Unavailable', 'Verification is temporarily unavailable.');
-        break;
-
-      case 'session_cancelled':
-        // User cancelled -- no action needed
-        break;
-
-      default:
-        Alert.alert('Error', err.message);
-        break;
-    }
-  }
-}
-```
-
-## Server-Side Webhook Verification
-
-**Never trust the SDK result for access-control decisions.** The SDK response is for UI feedback only — showing the user a success or failure screen. The definitive verdict arrives at your backend via an HMAC-SHA256 signed webhook.
-
-### Webhook Payload
-
-```json
-{
-  "event": "session.completed",
-  "session_id": "ses_abc123",
-  "organization_id": "org_xyz",
-  "timestamp": "2026-03-12T10:30:00Z",
-  "data": {
-    "decision": "approved",
-    "channel_trust_score": 95,
-    "liveness_score": 92,
-    "matchsense_risk_score": 8,
-    "presence_confidence": 94,
-    "session_type": "enrollment",
-    "identity_id": "idn_def456",
-    "reasons": [],
-    "rule_triggered": null,
-    "session_signature": "sig_..."
-  }
-}
-```
-
-### Signature Verification — Node.js (Express)
-
-```javascript
-const crypto = require('crypto');
-
-app.post('/webhooks/usesense', express.raw({ type: 'application/json' }), (req, res) => {
-  const signature = req.headers['x-usesense-signature'];
-  const timestamp = req.headers['x-usesense-timestamp'];
-
-  const payload = `${timestamp}.${req.body}`;
-  const expected = crypto
-    .createHmac('sha256', process.env.USESENSE_WEBHOOK_SECRET)
-    .update(payload)
-    .digest('hex');
-
-  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
-    return res.status(401).send('Invalid signature');
-  }
-
-  const event = JSON.parse(req.body);
+import { UseSense, UseSenseEvent } from 'react-native-usesense';
 
-  if (event.event === 'session.completed') {
-    const { decision, session_id } = event.data;
-    // Update your database based on the definitive decision
+const subscription = UseSense.addListener((event: UseSenseEvent) => {
+  switch (event.type) {
+    case 'SESSION_CREATED':
+      console.log('Session started:', event.data);
+      break;
+    case 'PERMISSIONS_REQUESTED':
+    case 'PERMISSIONS_GRANTED':
+    case 'PERMISSIONS_DENIED':
+      console.log('Permissions:', event.type);
+      break;
+    case 'CAPTURE_STARTED':
+    case 'FRAME_CAPTURED':
+    case 'CAPTURE_COMPLETED':
+      // Update your capture progress UI
+      break;
+    case 'CHALLENGE_STARTED':
+    case 'CHALLENGE_COMPLETED':
+      console.log('Challenge:', event.data);
+      break;
+    case 'UPLOAD_STARTED':
+    case 'UPLOAD_PROGRESS':
+    case 'UPLOAD_COMPLETED':
+      // Show upload spinner
+      break;
+    case 'DECISION_RECEIVED':
+      console.log('Verdict received from server');
+      break;
+    case 'ERROR':
+      console.error('SDK error:', event.data);
+      break;
   }
-
-  res.status(200).send('OK');
 });
-```
-
-### Signature Verification — Python (Flask)
 
-```python
-import hmac
-import hashlib
-
-@app.route('/webhooks/usesense', methods=['POST'])
-def usesense_webhook():
-    signature = request.headers.get('X-UseSense-Signature')
-    timestamp = request.headers.get('X-UseSense-Timestamp')
-
-    payload = f"{timestamp}.{request.data.decode()}"
-    expected = hmac.new(
-        USESENSE_WEBHOOK_SECRET.encode(),
-        payload.encode(),
-        hashlib.sha256
-    ).hexdigest()
-
-    if not hmac.compare_digest(signature, expected):
-        return 'Invalid signature', 401
-
-    event = request.get_json()
-
-    if event['event'] == 'session.completed':
-        decision = event['data']['decision']
-        session_id = event['session_id']
-        # Update your database based on the definitive decision
-
-    return 'OK', 200
+// Later, when the screen unmounts:
+subscription.remove();
 ```
 
-### Signature Verification — Go (net/http)
+Full event list: `SESSION_CREATED`, `PERMISSIONS_REQUESTED`,
+`PERMISSIONS_GRANTED`, `PERMISSIONS_DENIED`, `CAPTURE_STARTED`,
+`FRAME_CAPTURED`, `CAPTURE_COMPLETED`, `AUDIO_RECORD_STARTED`,
+`AUDIO_RECORD_COMPLETED`, `CHALLENGE_STARTED`, `CHALLENGE_COMPLETED`,
+`UPLOAD_STARTED`, `UPLOAD_PROGRESS`, `UPLOAD_COMPLETED`,
+`COMPLETE_STARTED`, `DECISION_RECEIVED`, `IMAGE_QUALITY_CHECK`,
+`ERROR`.
 
-```go
-func useSenseWebhook(w http.ResponseWriter, r *http.Request) {
-    signature := r.Header.Get("X-UseSense-Signature")
-    timestamp := r.Header.Get("X-UseSense-Timestamp")
-
-    body, err := io.ReadAll(r.Body)
-    if err != nil {
-        http.Error(w, "Bad request", http.StatusBadRequest)
-        return
-    }
+## Error handling
 
-    payload := fmt.Sprintf("%s.%s", timestamp, string(body))
-    mac := hmac.New(sha256.New, []byte(os.Getenv("USESENSE_WEBHOOK_SECRET")))
-    mac.Write([]byte(payload))
-    expected := hex.EncodeToString(mac.Sum(nil))
+`UseSense.startVerification` rejects with a `UseSenseError` on
+failure. Codes are uppercase strings matching the native SDK's
+canonical codes, plus a small set of bridge-specific codes
+(`session_cancelled`, `sdk_not_initialized`, `no_view_controller`,
+`invalid_config`).
 
-    if !hmac.Equal([]byte(signature), []byte(expected)) {
-        http.Error(w, "Invalid signature", http.StatusUnauthorized)
-        return
-    }
-
-    var event map[string]interface{}
-    json.Unmarshal(body, &event)
+```typescript
+import { UseSense, UseSenseError } from 'react-native-usesense';
 
-    // Process the event
-    w.WriteHeader(http.StatusOK)
-    w.Write([]byte("OK"))
+try {
+  await UseSense.startVerification({ sessionType: 'enrollment' });
+} catch (err) {
+  const error = err as UseSenseError;
+  switch (error.code) {
+    case 'session_cancelled':
+    case 'USER_CANCELLED':
+      // User tapped cancel / backed out. Silent.
+      break;
+    case 'CAMERA_PERMISSION_DENIED':
+      // Direct the user to app settings.
+      break;
+    case 'NETWORK_ERROR':
+    case 'NETWORK_TIMEOUT':
+      // Retry with exponential backoff.
+      break;
+    case 'SESSION_EXPIRED':
+      // Start a fresh session.
+      break;
+    case 'QUOTA_EXCEEDED':
+    case 'INSUFFICIENT_CREDITS':
+      // Rate-limited or out of credits. Surface to the user.
+      break;
+    case 'INVALID_CONFIG':
+    case 'sdk_not_initialized':
+      // Check your API key and that initialize() ran successfully.
+      break;
+    default:
+      // UNKNOWN_ERROR, SERVER_ERROR, SERVICE_UNAVAILABLE, etc.
+  }
 }
 ```
 
-## Sandbox vs Production
-
-| | Sandbox | Production |
-|---|---------|-----------|
-| Cost | Free, unlimited | Credit-based |
-| API keys | Separate | Separate |
-| Features | All features identical | All features identical |
-| Deduplication | Elevated risk scores (shared face collection) | Isolated per organization |
-
-Switch by changing `environment` in config:
-
-```typescript
-await UseSense.initialize({
-  apiKey: process.env.USESENSE_API_KEY,
-  environment: __DEV__ ? 'sandbox' : 'production',
-});
-```
-
-## Troubleshooting
+Full error code reference: see the [native iOS SDK's
+`UseSenseErrorCode`](https://github.com/qudusadeyemi/usesense-ios-sdk/blob/main/Sources/UseSense/UseSenseError.swift)
+and the [native Android SDK's
+`UseSenseError`](https://github.com/qudusadeyemi/usesense-android-sdk/blob/main/sdk/src/main/java/com/usesense/sdk/UseSenseError.kt).
 
-| Problem | Solution |
-|---------|----------|
-| `Module 'react-native-usesense' not found` | Run `pod install` for iOS; rebuild for Android; verify auto-linking |
-| `Camera permission denied on iOS` | Add `NSCameraUsageDescription` to `Info.plist` |
-| `Build fails on iOS with 'pod not found'` | Run `pod repo update` then `pod install` |
-| `Build fails on Android with dependency resolution error` | Ensure `mavenCentral()` is in your project-level `repositories` |
-| `Session always times out` | Check network connectivity; increase `timeout` in config |
-| `Deduplication always returns high risk on sandbox` | Expected — sandbox uses a shared face collection |
-| `Events not firing` | Ensure `addListener()` is called before `startSession()` |
-| `New Architecture errors` | Ensure codegen ran: `cd android && ./gradlew generateCodegenArtifactsFromSchema` |
-| `App crashes on Android with TransactionTooLargeException` | Update to latest plugin version |
+## Security model: always verify the webhook
 
-## TypeScript Support
+**The most important section in this document.** Repeat after me:
 
-The plugin ships with full TypeScript declarations. All types are exported from the main entry point:
+1. **NEVER** trust the SDK result for access-control decisions. The
+   SDK runs on the user's device and can be tampered with.
+2. The definitive verdict arrives at your backend via an HMAC-SHA256
+   signed webhook at the endpoint you configured in the Watchtower
+   dashboard.
+3. Always verify the webhook signature before acting on it. Reject
+   any webhook whose signature doesn't match — an attacker with the
+   endpoint URL but not the signing secret would otherwise be able
+   to forge approved verdicts.
+4. Use the webhook's pillar scores (`channelTrustScore`,
+   `livenessScore`, `matchSenseRiskScore`, `presenceConfidence`) to
+   make your actual access decision. The client-side `decision`
+   field is a hint, not the source of truth.
 
-```typescript
-import {
-  UseSense,
-  UseSenseConfig,
-  UseSenseResult,
-  UseSenseError,
-  UseSenseEvent,
-  UseSenseDecision,
-  UseSenseEnvironment,
-  SessionType,
-  ChallengePolicy,
-  ProcessingStage,
-  StartSessionOptions,
-  SessionStatus,
-  UseSenseSubscription,
-} from 'react-native-usesense';
-```
+See the native SDKs' READMEs for webhook verification examples in
+Node.js, Python, and Go.
 
-## API Reference
+## Full API reference
 
 ### `UseSense.initialize(config: UseSenseConfig): Promise<void>`
 
-Initialize the plugin. Must be called once before any other method.
+Initializes the plugin. Must be called once before any other method.
+Calling again with a different key or environment replaces the
+previous configuration. Throws if `apiKey` is empty or the native
+side fails to initialize.
 
-### `UseSense.startSession(options?: StartSessionOptions): Promise<UseSenseResult>`
+### `UseSense.startVerification(request: VerificationRequest): Promise<UseSenseResult>`
 
-Start a verification session. Presents a full-screen native camera UI.
+Runs a verification session. Presents a full-screen native camera
+activity. Resolves when the session completes or rejects on failure
+(including user cancellation). The returned `UseSenseResult` is
+always the redacted five-field shape.
 
-### `UseSense.cancelSession(): Promise<void>`
+### `UseSense.addListener(callback: (event) => void): UseSenseSubscription`
 
-Cancel an in-progress verification session.
+Subscribes to lifecycle events. Returns a handle with a `remove()`
+method. Call `addListener` **before** `startVerification` so the
+subscription captures the earliest events.
 
-### `UseSense.getSessionStatus(sessionId: string): Promise<SessionStatus>`
+### `UseSense.reset(): Promise<void>`
 
-Get the status of a verification session by ID.
+Clears all event listeners and releases the native client. Call this
+when you want to re-initialize with a different key, or during test
+teardown. Not required during normal usage.
 
-### `UseSense.addListener(callback: (event: UseSenseEvent) => void): UseSenseSubscription`
+### `UseSense.isInitialized(): Promise<boolean>`
 
-Subscribe to real-time events during the verification lifecycle.
+Returns whether the native plugin has an active SDK client. Use this
+for feature-flagging UI that should only show when the SDK is ready.
 
-### `UseSense.getSdkVersion(): string`
+## Example app
 
-Get the native SDK version string.
+See [example/](./example) for a full-featured demo app. Paste your
+sandbox or production API key into the UI at runtime (persisted
+across launches via AsyncStorage) and run on a physical device. The
+example shows the canonical integration pattern for `initialize`,
+`startVerification`, event subscription, result display, and error
+handling.
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md).
+See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-Proprietary. See [LICENSE](./LICENSE) file.
+Proprietary. See [LICENSE](LICENSE).
 
 ## Support
 
-- Documentation: [https://watch.usesense.ai/developer-docs](https://watchtower.usesense.ai/developer-docs)
-- Dashboard: [https://watchtower.usesense.ai](https://watchtower.usesense.ai)
-- Email: [support@usesense.ai](mailto:support@usesense.ai)
+- Documentation: https://watchtower.usesense.ai/developer-docs
+- Dashboard: https://watchtower.usesense.ai
+- Email: support@usesense.ai
+- Issues: https://github.com/qudusadeyemi/react-native-usesense/issues