@richard.fadiora/liveness-detection 3.0.2 → 3.1.0

package/README.md

@@ -2,129 +2,104 @@
 
 A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.
 
-This latest version introduces **headless mode**, **render-prop customization**, and robust **challenge sequencing**, allowing developers to fully control the UI while keeping the verification logic encapsulated.
+This version introduces **headless mode**, **render-prop customization**, and robust **challenge sequencing**, **configurable thresholds** for `Smile`, `Blink`, and `Turn_Head` challenges
+
+Pause between steps for user feedback
+
+Sequential challenge execution with strict timeout handling allowing you to fully control the UI while keeping the verification logic encapsulated.
 
 ---
 
-## Overview
+## 📌 Overview
 
 This component strengthens identity verification by combining:
 
-- Randomized challenge-response validation
-- Strict timeout enforcement
-- Backend spoof detection
-- Callback-based integration for easy usage
+- Randomized challenge-response validation  
+- Strict timeout enforcement  
+- Backend spoof detection  
+- Callback-based integration for easy usage  
 - Headless / fully customizable UI via render props
+- Configurable challenge thresholds to adapt difficulty  
 
 It protects against:
 
-- Presentation (photo) attacks
-- Screen glare attacks
-- Video replay/injection attacks
+- Presentation (photo) attacks  
+- Screen glare attacks  
+- Video replay/injection attacks  
 
 ---
 
-## How It Works
+## ⚙️ How It Works
 
-### Challenge Initialization
+### 1️⃣ Challenge Initialization
 
-- When the user starts verification, the system randomly selects **3 challenges** from a pool of 4 (`Smile`, `Blink`, `Turn_Head`, `Thumbs_Up`).
-- A timer starts immediately (default **60 seconds**, configurable via `duration`).
-- Each challenge is verified sequentially, with a brief pause between steps for user feedback.
-- The next challenge only begins after the current one is successfully completed.
+- Randomly selects **3 challenges** from the pool: `Smile`, `Blink`, `Turn_Head`, `Thumbs_Up`.  
+- Timer starts immediately (default **60 seconds**, configurable via `duration`).  
+- Each challenge is verified sequentially, with a brief pause between steps for feedback.  
 - If the timer expires, the session terminates and no frames are sent to the backend.
 
-### Challenge Execution
+### 2️⃣ Challenge Execution
 
-- Challenges are validated in real-time using webcam input and MediaPipe models.
-- Sequential verification ensures no steps are skipped.
-- Developers can use **headless mode** to render a fully custom UI while leveraging the verification logic.
+- Real-time validation using webcam input and MediaPipe models.  
+- Sequential verification ensures **no steps are skipped**.  
+- Developers can render custom UI via the **render prop** while using the same underlying logic.
+- Challenge thresholds are configurable through props:
 
-### Backend Liveness Verification
+| Prop Name             | Default | Description                              |
+|-----------------------|---------|------------------------------------------|
+| `smileThreshold`      | 0.20    | Minimum smile width to count as valid    |
+| `blinkThreshold`      | 0.01    | Maximum eye aspect ratio to count as blink |
+| `minturnHeadThreshold`| 0.15    | Minimum yaw for right head turn detection      |
+| `maxturnHeadThreshold`| 0.85    | Maximum yaw for left head turn detection      |
 
-- After all challenges are completed, the component captures **5 frames** from the webcam.
-- Frames are sent to the backend API defined by the `apiUrl` prop.
-- The backend performs:
-  - Spoof detection
-  - Glare detection
-  - Video injection detection
+### 3️⃣ Backend Liveness Verification
 
----
+- Captures **5 frames** from the webcam after all challenges are complete.  
+- Frames sent to backend API (`apiUrl` prop).  
+- Backend performs spoof detection, glare detection, and video injection detection.
 
-## Success & Failure Behavior
-
-### If verification succeeds
+---
 
-- The UI (or custom render-prop component) can display success feedback.
-- The `onComplete` callback is triggered:
+## ✅ Success & Failure Behavior
 
+### Success
+- UI (or custom component) shows success feedback.  
+- `onComplete` callback is triggered:
 ```js
 onComplete({ success: true, image: frame, skinConfidence });
 ```
 
-### If verification fails
-
-- The UI displays a failure message.
-- The `onError` callback is triggered:
-
+### Failure
+- UI shows failure message.  
+- `onError` callback is triggered:
 ```js
 onError({ success: false, reason, skinConfidence: null });
 ```
-
-- The component resets, requiring the user to start a new session.
+- Component resets; user must start a new session.
 
 ---
 
-## Props
+## 📦 Props
 
-| Prop Name  | Type                       | Required | Description |
-|------------|----------------------------|----------|-------------|
-| `apiUrl` | `string` | Yes | Backend endpoint for verification |
-| `onComplete` | `(result: boolean) => void` | Yes | Callback on success |
-| `onError` | `(result: boolean) => void` | Yes | Callback on failure |
-| `duration` | `int` | No | Max time for challenges (default 60s) |
-| render` | `(result: boolean) => void` | No | Optional custom UI render prop |
-| `classNames` | `object` | No | Optional CSS classes for default UI |
-
----
+| Prop Name   | Type                         | Required | Description |
+|------------|-----------------------------|----------|-------------|
+| `apiUrl`   | `string`                     | Yes      | Backend endpoint used for liveness verification |
+| `onComplete` | `(result: object) => void`  | Yes      | Callback fired after verification succeeds |
+| `onError`  | `(result: object) => void`   | Yes      | Callback fired after verification fails |
+| `duration` | `number`                     | No       | Maximum time for all challenges (default: 60s) |
+| `render`   | `(sdk: object) => JSX.Element` | No      | Optional render prop for full UI customization |
+| `classNames` | `object`                   | No       | Optional CSS class names to customize default UI |
+| `smileThreshold`       | `number`     | No       | Minimum smile width for Smile challenge                  |
+| `blinkThreshold`       | `number`     | No       | Maximum eye aspect ratio for Blink challenge             |
+| `minturnHeadThreshold` | `number`     | No       | Minimum yaw for Turn_Head challenge                      |
+| `maxturnHeadThreshold` | `number`     | No       | Maximum yaw for Turn_Head challenge                      |
 
-## Styling with `classNames`
-
-The `classNames` object allows partial styling of the default UI without fully overriding it. Supported keys:
-
-| Key        | Element                     |
-|------------|-----------------------------|
-| `container` | The root wrapper div        |
-| `webcam`    | The webcam video element   |
-| `button`    | Start / Retry button       |
-| `timer`     | Timer display             |
-| `error`     | Error message display     |
-| `success`   | Success message display   |
-
-### Example Usage
-
-```jsx
-<LivenessSDK
-  apiUrl="https://your-backend-api.com/liveness-check"
-  onComplete={handleComplete}
-  onError={handleError}
-  classNames={{
-    container: "my-liveness-container",
-    webcam: "my-webcam",
-    button: "my-button",
-    timer: "my-timer",
-    error: "my-error",
-    success: "my-success"
-  }}
-/>
-```
 
 ---
 
-## Usage Examples
+## 🧩 Usage Example
 
 ### Default UI
-
 ```jsx
 import { LivenessSDK } from "@richard.fadiora/liveness-detection";
 
@@ -132,8 +107,8 @@ function App() {
   return (
     <LivenessSDK
       apiUrl="https://your-backend-api.com/liveness-check"
-      onComplete={(result) => console.log("Verification success:", result)}
-      onError={(error) => console.log("Verification failed:", error.reason)}
+      onComplete={(result) => console.log("Success:", result)}
+      onError={(error) => console.log("Failed:", error.reason)}
       duration={60}
     />
   );
@@ -143,7 +118,6 @@ export default App;
 ```
 
 ### Headless / Custom UI
-
 ```jsx
 <LivenessSDK
   apiUrl="https://your-backend-api.com/liveness-check"
@@ -162,61 +136,113 @@ export default App;
 
 ---
 
-## Timeout Rules
+## 🎨 Styling with `classNames`
 
-- Maximum session duration: set via the `duration` property (default 60 seconds)
-- If time expires:
-  - The challenge stops immediately
-  - Verification state resets
-  - User must click Start Challenge again
-  - Backend verification is NOT triggered
+You can pass a `classNames` object to override the default UI classes:
+```js
+classNames={{
+  container: "liveness-container",
+  webcam: "liveness-webcam",
+  button: "liveness-button",
+  challenge: "liveness-challenge",
+  timer: "liveness-timer",
+  error: "liveness-error",
+  success: "liveness-success",
+}}
+```
 
----
+### CSS Example
+```css
+.liveness-container {
+  text-align: center;
+  background: #121212;
+  padding: 24px;
+  border-radius: 20px;
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.5);
+  color: white;
+}
+.liveness-webcam {
+  border-radius: 20px;
+  border: 2px solid #007bff;
+  width: 100%;
+}
+.liveness-button {
+  padding: 12px 30px;
+  font-size: 16px;
+  font-weight: bold;
+  border-radius: 10px;
+  background: #28a745;
+  color: white;
+  border: none;
+  cursor: pointer;
+  margin-top: 10px;
+}
+.liveness-challenge {
+  margin: 5px 0;
+  font-weight: bold;
+  font-size: 40px;
+}
+.liveness-timer {
+  margin: 10px 0;
+  font-weight: bold;
+  font-size: 18px;
+}
+.liveness-error {
+  color: #ff4d4d;
+  margin-top: 20px;
+}
+.liveness-success {
+  color: #4caf50;
+  margin-top: 20px;
+}
+```
 
-## Security Architecture
+---
 
-- **Client-side active verification**: randomized challenges, real-time gesture detection
-- **Server-side passive verification**: frame-based spoof analysis, glare detection, video injection detection
-- **Strict session control**: timeout enforcement, restart requirement on failure
+## ⏳ Timeout Rules
 
-This layered approach reduces false positives and prevents replay-based attacks.
+- Maximum session duration: set via `duration` prop (default 60s).  
+- On timeout: challenge stops, state resets, backend verification is not triggered.
 
 ---
 
-## Verification Criteria
+## 🔐 Security Architecture
+
+- **Client-side**: Randomized challenges, real-time gesture detection  
+- **Server-side**: Frame-based spoof analysis, glare detection, video injection detection  
+- **Session control**: Timeout enforcement, manual restart on failure  
+- Reduces false positives and prevents replay attacks.
+
+---
 
-Verification is considered successful only if:
+## 📊 Verification Criteria
 
-- All 3 randomly selected challenges are completed
-- All 5 frames are sent to the backend
-- Backend confirms:
-  - No spoofing detected
-  - No glare detected
-  - Skin texture is human
-  - No video injection detected
+- All 3 challenges completed  
+- All 5 frames successfully sent to backend  
+- Backend confirms: no spoofing, no glare, human skin texture, no video injection
 
 ---
 
-## Integration Notes
+## 🏗️ Integration Notes
 
-- The component assumes webcam permissions are granted.
-- The backend must accept 5 frames in the expected format.
-- The `apiUrl` must be reachable from the client environment.
-- Ensure CORS is properly configured on the backend.
+- Webcam permissions required  
+- Backend must accept 5 frames in expected format  
+- `apiUrl` must be reachable and have an endpoint `/v1/verify` 
+- CORS must be configured properly
 
 ---
 
-## Ideal Use Cases
+## 🚀 Ideal Use Cases
 
-- KYC verification flows
-- Identity onboarding systems
-- Account recovery flows
-- Secure login systems
-- Financial or compliance-based applications
+- KYC verification flows  
+- Identity onboarding  
+- Account recovery  
+- Secure login  
+- Financial / compliance apps
 
 ---
 
-## Maintainer
+## 👨‍💻 Maintainer
 
-Fadiora Richard
+Fadiora Richard.