@richard.fadiora/liveness-detection 3.1.0 → 4.0.0

package/README.md

@@ -1,27 +1,31 @@
-# Liveness Detection Component
+# Liveness Detection SDK
 
-A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.
+A cross-framework **liveness detection SDK** that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API. Works with **React** and **Angular** via framework-specific wrappers while the **core engine is framework-agnostic**.
 
-This version introduces **headless mode**, **render-prop customization**, and robust **challenge sequencing**, **configurable thresholds** for `Smile`, `Blink`, and `Turn_Head` challenges
+This version introduces:
 
-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.
+- **Headless mode** for fully custom UI  
+- Robust **challenge sequencing**  
+- **Configurable thresholds** for `Smile`, `Blink`, and `Turn_Head` challenges  
+- Sequential challenge execution with **strict timeout handling**  
+- Pause between steps for user feedback  
+- Cross-framework integration (React hook & Angular service)  
 
 ---
 
 ## 📌 Overview
 
-This component strengthens identity verification by combining:
+This SDK strengthens identity verification by combining:
 
 - Randomized challenge-response validation  
+- Sequential challenge execution  
 - 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  
+- Headless / fully customizable UI via render props (React)  
+- Configurable challenge thresholds  
 
-It protects against:
+Protects against:
 
 - Presentation (photo) attacks  
 - Screen glare attacks  
@@ -29,6 +33,29 @@ It protects against:
 
 ---
 
+## ⚙️ Architecture
+
+### Core Engine
+
+- `LivenessEngine` (framework-agnostic)  
+- Handles:
+  - Challenge sequence generation
+  - MediaPipe face & hand model detection
+  - Challenge validation (`Smile`, `Blink`, `Turn_Head`, `Thumbs_Up`)
+  - Face cropping
+  - Detection loop
+  - Final frame capture and backend verification
+- Can be used directly or via React/Angular wrappers
+
+### Framework Wrappers
+
+| Framework | Wrapper | Notes |
+|-----------|--------|------|
+| React     | `useLiveness` hook | Uses `webcamRef` and React state, supports render-prop customization |
+| Angular   | `LivenessService`  | Injectable service, exposes engine state and control methods |
+
+---
+
 ## ⚙️ How It Works
 
 ### 1️⃣ Challenge Initialization
@@ -133,6 +160,25 @@ export default App;
   )}
 />
 ```
+## 📤 Hook Return Values
+
+The `useLiveness` hook exposes the following values and control functions for managing the liveness detection session.
+
+| Name | Type | Description |
+|-----|------|-------------|
+| `webcamRef` | `ref` | React ref attached to the webcam component. Provides access to the live video stream used for face and hand detection as well as frame capture for verification. |
+| `status` | `string` | Represents the current state of the liveness session. Possible values include `loading`, `ready`, `capturing`, `verifying`, `success`, `error`, and `expired`. |
+| `errorMsg` | `string` | Contains the error message displayed when the liveness verification fails or when the system encounters an issue. |
+| `sequence` | `string[]` | The randomized sequence of liveness challenges selected for the current session. Three challenges are chosen from the challenge pool. |
+| `currentStep` | `number` | The index of the current challenge being performed within the challenge sequence. |
+| `timeLeft` | `number` | Remaining time (in seconds) before the session expires. The timer runs while the system is in the `capturing` state. |
+| `isStepTransitioning` | `boolean` | Indicates whether the system is currently transitioning between challenges. Used to briefly pause detection and provide UI feedback after a challenge is completed. |
+| `start` | `function` | Starts the liveness challenge session and begins the detection loop. |
+| `reset` | `function` | Resets the entire session, including the timer, challenge sequence, step index, and error state. |
+| `sendFinalProof` | `function` | Sends captured face frames to the backend verification API to perform the final liveness check. Normally triggered automatically after the last challenge is completed. |
+
+
+
 
 ---