@richard.fadiora/liveness-detection 3.0.0 → 3.0.1

package/README.md

@@ -1,28 +1,26 @@
-# Liveness Detection SDK
+# Liveness Detection Component
 
 A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.
 
-This version introduces headless mode, render-prop customization, robust sequential challenge handling, and timeout enforcement, giving developers full control over the UI while keeping the core verification logic encapsulated.
+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
 
-The component strengthens identity verification using:
+This component strengthens identity verification by combining:
 
 - Randomized challenge-response validation
-- Real-time gesture detection via MediaPipe
-- Sequential verification to ensure no challenges are skipped
 - Strict timeout enforcement
 - Backend spoof detection
-- Callback-based integration for success/failure handling
-- Optional headless mode for fully custom UI
+- Callback-based integration for easy usage
+- Headless / fully customizable UI via render props
 
 It protects against:
 
 - Presentation (photo) attacks
 - Screen glare attacks
-- Video replay or injection attacks
+- Video replay/injection attacks
 
 ---
 
@@ -30,35 +28,50 @@ It protects against:
 
 ### Challenge Initialization
 
-- Randomly selects 3 challenges from 4: Smile, Blink, Turn_Head, Thumbs_Up
-- Timer starts immediately (default 60s, configurable)
-- Challenges verified sequentially with brief pause between steps
-- Timer expiry terminates session and stops backend verification
+- 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.
+- If the timer expires, the session terminates and no frames are sent to the backend.
 
 ### Challenge Execution
 
-- Validates challenges in real-time using MediaPipe
-- Sequential logic ensures no challenge is skipped
-- Optional render prop allows fully custom UI
+- 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.
 
 ### Backend Liveness Verification
 
-- Captures 5 frames from webcam after all challenges
-- Sends frames to backend API for verification
-- Backend performs spoof, glare, and video injection 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
 
 ---
 
 ## Success & Failure Behavior
 
-**Success:**
-- UI displays success message
-- onComplete callback triggered with frame and skin confidence
+### If verification succeeds
 
-**Failure:**
-- UI displays error message
-- onError callback triggered with reason
-- Component resets for new session
+- The UI (or custom render-prop component) can display success feedback.
+- The `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:
+
+```js
+onError({ success: false, reason, skinConfidence: null });
+```
+
+- The component resets, requiring the user to start a new session.
 
 ---
 
@@ -75,21 +88,62 @@ It protects against:
 
 ---
 
-## Usage Example
+## Styling with `classNames`
 
-**Default UI:**
-```jsx
-import { LivenessSDK } from '@richard.fadiora/liveness-detection';
+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={(result) => console.log(result)}
-  onError={(error) => console.log(error.reason)}
-  duration={60}
+  onComplete={handleComplete}
+  onError={handleError}
+  classNames={{
+    container: "my-liveness-container",
+    webcam: "my-webcam",
+    button: "my-button",
+    timer: "my-timer",
+    error: "my-error",
+    success: "my-success"
+  }}
 />
 ```
 
-**Headless / Custom UI:**
+---
+
+## Usage Examples
+
+### Default UI
+
+```jsx
+import { LivenessSDK } from "@richard.fadiora/liveness-detection";
+
+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)}
+      duration={60}
+    />
+  );
+}
+
+export default App;
+```
+
+### Headless / Custom UI
+
 ```jsx
 <LivenessSDK
   apiUrl="https://your-backend-api.com/liveness-check"
@@ -98,7 +152,7 @@ import { LivenessSDK } from '@richard.fadiora/liveness-detection';
   render={(sdk) => (
     <div>
       <video ref={sdk.webcamRef} autoPlay playsInline muted />
-      <div>Step {sdk.currentStep + 1} of {sdk.sequence.length}: {sdk.sequence[sdk.currentStep]}</div>
+      <div>Step {sdk.currentStep + 1}: {sdk.sequence[sdk.currentStep]}</div>
       <div>Time left: {sdk.timeLeft}s</div>
       <button onClick={sdk.start}>Start</button>
     </div>
@@ -110,46 +164,59 @@ import { LivenessSDK } from '@richard.fadiora/liveness-detection';
 
 ## Timeout Rules
 
-- Max session duration: `duration` prop (default 60s)
-- Expiry stops challenge, resets state, requires restart, no backend call
+- 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
 
 ---
 
 ## Security Architecture
 
-1. Client-side: randomized challenges, real-time gesture detection
-2. Server-side: frame-based spoof, glare, and injection detection
-3. Strict session control: timeout enforcement, restart requirement
+- **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
+
+This layered approach reduces false positives and prevents replay-based attacks.
 
 ---
 
 ## Verification Criteria
 
-- All 3 challenges completed
-- All 5 frames sent to backend
-- Backend confirms no spoofing, no glare, human skin, no video injection
+Verification is considered successful only if:
+
+- 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
 
 ---
 
 ## Integration Notes
 
-- Webcam permissions required
-- Backend must accept 5 frames
-- apiUrl must be reachable and CORS-enabled
+- 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.
 
 ---
 
 ## Ideal Use Cases
 
 - KYC verification flows
-- Identity onboarding
-- Account recovery
+- Identity onboarding systems
+- Account recovery flows
 - Secure login systems
-- Financial/compliance applications
+- Financial or compliance-based applications
 
 ---
 
 ## Maintainer
 
-Fadiora Richard.
+Fadiora Richard
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@richard.fadiora/liveness-detection",
   "private": false,
-  "version": "3.0.0",
+  "version": "3.0.1",
   "type": "module",
   "files": [
     "dist"