@richard.fadiora/liveness-detection 2.1.0 → 3.0.1

package/README.md

@@ -2,9 +2,11 @@
 
 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.
+
 ---
 
-## 📌 Overview
+## Overview
 
 This component strengthens identity verification by combining:
 
@@ -12,6 +14,7 @@ This component strengthens identity verification by combining:
 - Strict timeout enforcement
 - Backend spoof detection
 - Callback-based integration for easy usage
+- Headless / fully customizable UI via render props
 
 It protects against:
 
@@ -21,45 +24,26 @@ It protects against:
 
 ---
 
-## ⚙️ How It Works
-
-### 1️⃣ Challenge Initialization
-
-When the user clicks the **"Start Challenge"** button:
-
-- The system randomly selects **3 challenges**
-- The challenges are chosen from a fixed pool of 4:
-
-  - `Smile`
-  - `Blink`
-  - `Turn_Head`
-  - `Thumbs_Up`
-
-- A timer starts immediately. If you do not pass the **duration** property, it will default to 60 seconds.
-
-If the timer expires before completion:
-- The session is terminated
-- The user must restart the process manually
-- No frames are sent to the backend
-
----
+## How It Works
 
-### 2️⃣ Challenge Execution
+### Challenge Initialization
 
-- Challenges are validated in real-time using webcam input.
+- 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.
-- All 3 challenges must be completed within the 60-second window.
+- If the timer expires, the session terminates and no frames are sent to the backend.
 
-If successful, the component proceeds to backend verification.
+### Challenge Execution
 
----
-
-### 3️⃣ Backend Liveness Verification
+- 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.
 
-After all challenges are completed:
+### Backend Liveness Verification
 
-- The component captures **5 frames** from the webcam.
-- These frames are sent to the backend API defined by the `apiUrl` prop.
+- 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
@@ -67,39 +51,79 @@ After all challenges are completed:
 
 ---
 
-## ✅ Success & Failure Behavior
+## Success & Failure Behavior
 
-### If verification succeeds:
-- The UI displays: **"Verification Passed"**
-- The component triggers:
+### If verification succeeds
+
+- The UI (or custom render-prop component) can display success feedback.
+- The `onComplete` callback is triggered:
 
 ```js
-onComplete(true)
+onComplete({ success: true, image: frame, skinConfidence });
 ```
 
-### If verification fails:
-- The UI displays a failure message
-- The component triggers:
+### If verification fails
+
+- The UI displays a failure message.
+- The `onError` callback is triggered:
 
 ```js
-onError(false)
+onError({ success: false, reason, skinConfidence: null });
 ```
-This is because the parameters being passed for both completion and Error are the same: success, result, and skinConfidence.
+
+- The component resets, requiring the user to start a new session.
 
 ---
 
-## 📦 Props
+## Props
 
 | Prop Name  | Type                       | Required | Description |
 |------------|----------------------------|----------|-------------|
-| `apiUrl`   | `string`                   | Yes      | Backend endpoint used for liveness verification |
-| `onComplete` | `(result: boolean) => void` | Yes      | Callback fired after verification completes |
-| `onError` | `(result: boolean) => void` | Yes      | Callback fired after verification flags error |
-| `duration` | `int` | No      | Used for setting maximum time for the challenges to be completed |
+| `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 |
 
 ---
 
-## 🧩 Usage Example
+## 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
+
+### Default UI
 
 ```jsx
 import { LivenessSDK } from "@richard.fadiora/liveness-detection";
@@ -108,13 +132,9 @@ function App() {
   return (
     <LivenessSDK
       apiUrl="https://your-backend-api.com/liveness-check"
-      onComplete={(result) => {
-        if (result) {
-          console.log("User verified successfully");
-        } else {
-          console.log("Liveness verification failed");
-        }
-      }}
+      onComplete={(result) => console.log("Verification success:", result)}
+      onError={(error) => console.log("Verification failed:", error.reason)}
+      duration={60}
     />
   );
 }
@@ -122,56 +142,62 @@ function App() {
 export default App;
 ```
 
+### Headless / Custom UI
+
+```jsx
+<LivenessSDK
+  apiUrl="https://your-backend-api.com/liveness-check"
+  onComplete={handleComplete}
+  onError={handleError}
+  render={(sdk) => (
+    <div>
+      <video ref={sdk.webcamRef} autoPlay playsInline muted />
+      <div>Step {sdk.currentStep + 1}: {sdk.sequence[sdk.currentStep]}</div>
+      <div>Time left: {sdk.timeLeft}s</div>
+      <button onClick={sdk.start}>Start</button>
+    </div>
+  )}
+/>
+```
+
 ---
 
-## ⏳ Timeout Rules
+## Timeout Rules
 
-- Maximum session duration: Set in the **duration** property, else **60 seconds**
+- Maximum session duration: set via the `duration` property (default 60 seconds)
 - If time expires:
   - The challenge stops immediately
-  - The verification state resets
-  - User must click **Start Challenge** again
-  - Backend verification will NOT be triggered
+  - Verification state resets
+  - User must click Start Challenge again
+  - Backend verification is NOT triggered
 
 ---
 
-## 🔐 Security Architecture
-
-This component uses a layered approach:
+## Security Architecture
 
-1. **Client-side active verification**
-   - Randomized challenge selection
-   - Real-time gesture detection
+- **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
 
-2. **Server-side passive verification**
-   - Frame-based spoof analysis
-   - Glare detection
-   - Video injection detection
-
-3. **Strict session control**
-   - Timeout enforcement
-   - Restart requirement on failure
-
-This multi-layer strategy reduces false positives and prevents replay-based attacks.
+This layered approach reduces false positives and prevents replay-based attacks.
 
 ---
 
-## 📊 Verification Criteria
+## Verification Criteria
 
-A verification is considered successful only if:
+Verification is considered successful only if:
 
-- 3 randomly selected challenges are completed
-- All 5 frames are successfully sent to the backend
+- 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
+  - Skin texture is human
   - No video injection detected
 
-
 ---
 
-## 🏗️ Integration Notes
+## Integration Notes
 
 - The component assumes webcam permissions are granted.
 - The backend must accept 5 frames in the expected format.
@@ -180,7 +206,7 @@ A verification is considered successful only if:
 
 ---
 
-## 🚀 Ideal Use Cases
+## Ideal Use Cases
 
 - KYC verification flows
 - Identity onboarding systems
@@ -190,6 +216,7 @@ A verification is considered successful only if:
 
 ---
 
-## 👨‍💻 Maintainer
+## Maintainer
+
+Fadiora Richard
 
-Maintained by Princeps Credit Systems Limited.