@richard.fadiora/liveness-detection 4.3.7 → 4.3.9

package/README.md

@@ -1,294 +1,409 @@
 # Liveness Detection SDK
 
-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** 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)  
+A cross-framework **liveness detection SDK** that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.  
+This package provides a **framework-agnostic core** with optimized wrappers for **React ⚛️** and **Angular 🅰️**.
 
----
+* * *
+
+## 🚀 Key Features in v4.3.9
+
+
+
+*   📦 **Multi-Entry Support**: Dedicated subpaths for React and Angular to prevent framework leakage.
+    
+*   🎨 **Prop-Driven Styling**: Fully customizable UI using class name injection (Tailwind/Bootstrap friendly).
+    
+*   🧠 **Headless Mode**: Access core logic via hooks (React) or services (Angular) for 100% custom UI.
+    
+*   🅰️ **Standalone Angular Support**: Angular wrapper uses standalone components; no NgModules needed.
+    
+*   🔒 **Improved Security**: Enhanced challenge sequencing with strict timeout handling and backend frame verification.
+    
+
+* * *
 
 ## 📌 Overview
 
+
+
 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 (React)  
-- Configurable challenge thresholds  
+*   🎲 Randomized challenge-response validation
+    
+*   📋 Sequential challenge execution (Smile, Blink, Turn\_Head, Thumbs\_Up)
+    
+*   🧠 Real-time MediaPipe face & hand landmark detection
+    
+*   🛡️ Protection against presentation attacks (photo/video), glare, and replay attacks
+    
 
-Protects against:
+* * *
 
-- Presentation (photo) attacks  
-- Screen glare attacks  
-- Video replay/injection attacks  
+## 📦 Installation & Imports
 
----
 
-## ⚙️ Architecture
 
-### Core Engine
+`npm install @richard.fadiora/liveness-detection`
 
-- `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
+### Import Paths
 
-### 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. Must be imported with "@richard.fadiora/liveness-detection/angular |
+| Target | Import Path |
+| --- | --- |
+| Pure Logic (Core) | @richard.fadiora/liveness-detection |
+| React Wrapper ⚛️ | @richard.fadiora/liveness-detection/react |
+| Angular Wrapper 🅰️ | @richard.fadiora/liveness-detection/angular |
 
----
+These entry points ensure framework-specific code stays isolated and bundles remain small.
 
-## ⚙️ How It Works
+* * *
 
-### 1️⃣ Challenge Initialization
+## 🧩 Framework Usage
 
-- 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.
+### 🅰️ Angular Implementation (Standalone)
 
-### 2️⃣ Challenge Execution
+# 
 
-- 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:
+The Angular wrapper is now **standalone**. Import it directly into your component’s `imports` array without using a module:
 
-| 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      |
+import { Component } from '@angular/core';  
+import { LivenessComponent } from '@richard.fadiora/liveness-detection/angular';  
+  
+@Component({  
+  selector: 'app-verify',  
+  standalone: true,  
+  imports: \[LivenessComponent\],  
+  template: \`  
+    <LivenessCheck  
+      \[apiUrl\]="'https://api.yoursite.com/verify'"  
+      \[containerClass\]="'my-custom-container'"  
+      \[buttonClass\]="'btn-primary'"  
+      (onComplete)="handleSuccess($event)"  
+      (onError)="handleError($event)">  
+    </LivenessCheck>  
+  \`  
+})  
+export class VerifyComponent {  
+  
+  handleSuccess(result: any) {  
+    console.log("Image Captured:", result.image);  
+  }  
+  
+  handleError(error: any) {  
+    console.error(error.reason);  
+  }  
+  
+}
 
-### 3️⃣ Backend Liveness Verification
+⚠️ **Important Rule:** Standalone components **must not** be declared in an NgModule. Doing so disables standalone behavior and can cause runtime errors.
 
-- 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.
+* * *
 
----
+### ⚛️ React Implementation
 
-## ✅ Success & Failure Behavior
+# 
 
-### Success
-- UI (or custom component) shows success feedback.  
-- `onComplete` callback is triggered:
-```js
-onComplete({ success: true, image: frame, skinConfidence });
-```
+import { LivenessSDK } from "@richard.fadiora/liveness-detection/react";  
+  
+function App() {  
+  return (  
+    <LivenessSDK  
+      apiUrl\="https://api.yoursite.com/verify"  
+      classNames\={{ container: "p-4 bg-dark", video: "rounded-lg" }}  
+      onComplete\={(res) => console.log("Success:", res.image)}  
+      onError\={(err) => console.error(err.reason)}  
+    />  
+  );  
+}
 
-### Failure
-- UI shows failure message.  
-- `onError` callback is triggered:
-```js
-onError({ success: false, reason, skinConfidence: null });
-```
-- Component resets; user must start a new session.
+* * *
 
----
+## 🎨 Prop-Driven Styling
 
-## 📦 Props
 
-| 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                      |
 
+| Angular Input | React Prop | Description |
+| --- | --- | --- |
+| `containerClass` | classNames.container | Main wrapper div |
+| `videoClass` | classNames.webcam | The video element |
+| `buttonClass` | classNames.button | The Start button |
+| `timerClass` | classNames.timer | Countdown timer text |
+| `instructionBoxClass` | classNames.challenge | Challenge instruction box |
+| `statusOverlayClass` | classNames.overlay | Overlay during verification |
+| `errorMessageClass` | classNames.error | Wrapper for error messages |
 
----
+* * *
+## Customizing Challenge Labels
 
-## 🧩 Usage Example
 
-### 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("Success:", result)}
-      onError={(error) => console.log("Failed:", error.reason)}
-      duration={60}
-    />
-  );
-}
+You can override the default technical strings (e.g., `Thumbs_Up`) with user-friendly text or different languages using the `challengeMapping` input.
 
-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>
-  )}
-/>
-```
-## 📤 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. |
-
-
-
-
----
-
-## 🎨 Styling with `classNames`
-
-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;
+| Technical ID | Default Display |
+| --- | --- |
+| `Smile` | "Smile" |
+| `Blink` | "Blink" |
+| `Turn_Head` | "Turn Head" |
+| `Thumbs_Up` | "Thumbs Up" |
+
+**Example: Localization (French)**
+
+TypeScript
+
+    // app.component.ts
+    challengeLabels = {
+      'Smile': 'Souriez',
+      'Blink': 'Clignez des yeux',
+      'Turn_Head': 'Tournez la tête',
+      'Thumbs_Up': 'Levez le pouce'
+    };
+HTML
+
+    <LivenessCheck [challengeMapping]="challengeLabels"></LivenessCheck>
+
+###   
+
+### 📥 Text & Label Customization
+
+### 
+
+Customize all user-facing strings to match your app's tone or language.
+
+| Input Property | Default Value |
+| --- | --- |
+| `successMessage` | "Verification Successful!" |
+| `errorMessage` | "Verification failed. Please try again." |
+| `startButtonLabel` | "Start Verification" |
+| `retryButtonLabel` | "Try Again" |
+
+**Example Usage:**
+
+HTML
+
+    <LivenessCheck
+      [successMessage]="'Identity Confirmed!'"
+      [errorMessage]="'We couldn\'t verify you. Move to a brighter room.'"
+      [startButtonLabel]="'Begin Scan'"
+    >
+    </LivenessCheck>
+
+## 🔄 State Synchronization
+
+### 
+
+The `onStateChange` event provides a real-time stream of the SDK's internal engine. This is useful for building custom instruction overlays or logging telemetry.
+
+### The `LivenessState` Object
+
+### 
+
+When the state changes, the SDK emits an object with the following structure:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `status` | enum | The current phase of the SDK (see Status Flow below). |
+| `sequence` | Challenge[] | The array of 3 randomized challenges (e.g., ['Smile', 'Blink', 'Turn_Head']). |
+| `currentStep` | number | The index (0-2) of the challenge the user is currently performing. |
+| `timeLeft` | number | The countdown timer in seconds before the session expires. |
+| `isStepTransitioning` | boolean | true during the 1.5s pause after a successful challenge. |
+| `errorMsg` | string | Contains the technical error code (e.g., SPOOF_BLUR_DETECTED) when status is 'error'. |
+
+* * *
+
+### Implementation: Custom Error Mapping
+
+### 
+
+You can use the `onStateChange` handler to "intercept" technical error codes and map them to user-friendly instructions in your local UI.
+
+**Example: Reactive Instructions**
+
+TypeScript
+
+    // app.component.ts
+    handleStateUpdate(state: LivenessState) {
+      if (state.status === 'error' && state.errorMsg) {
+        
+        // Pattern matching for specific error prefixes
+        switch (true) {
+          case state.errorMsg.startsWith('FACE_'):
+            this.myLocalStatus = "Center your face in the circle";
+            break;
+          case state.errorMsg.startsWith('LIGHT_'):
+            this.myLocalStatus = "Find a brighter spot";
+            break;
+          case state.errorMsg.startsWith('TIMEOUT'):
+            this.myLocalStatus = "Session expired. Tap retry.";
+            break;
+          default:
+            this.myLocalStatus = state.errorMsg;
+        }
+      }
+    }
+HTML
+
+    <LivenessCheck 
+      (onStateChange)="handleStateUpdate($event)"
+      [errorMessage]="myLocalStatus">
+    </LivenessCheck>
+
+* * *
+
+### Why use the State Handler?
+
+### 
+
+*   **Decoupled Logic:** You can keep the SDK's UI simple while handling complex business logic (like analytics or redirecting users) in your main app.
+    
+*   **Dynamic UI:** Change your app's background color, show a progress bar, or trigger haptic feedback based on the `status` transitions.
+    
+*   **Error Interception:** Translate technical backend codes into the specific "voice" of your brand.
+
+## 🚨 Error Reference Guide
+
+
+
+When the SDK emits a `status: 'error'`, the `errorMsg` will contain one of the following technical codes. You can use these to provide contextual hints (e.g., "Too much light") in your UI.
+
+| Error Code | Meaning | Recommended User Hint |
+| --- | --- | --- |
+| `SCREEN_REFLECTION_DETECTED` | Excessive glare or light bouncing off the screen. | "Move away from direct light or windows." |
+| `SPOOF_BLUR_DETECTED` | Image is too dark or out of focus. | "Ensure your face is well-lit and clear." |
+| `SCREEN_MOIRE_PATTERN_DETECTED` | Digital pixel patterns detected (indicates a photo/screen). | "Please use your physical device camera." |
+| `STATIC_IMAGE_OR_SCREEN` | Natural micro-movements not detected. | "Blink or move slightly during the scan." |
+| `NO_IMAGE_DATA` | Camera permissions denied or stream interrupted. | "Enable camera access in your settings." |
+| `AI_SPOOF_DETECTION` | Low skin-texture confidence from the AI model. | "Verification failed. Please try again." |
+| `Network Error` | The backend API could not be reached. | "Check your internet connection." |
+| `Liveness Check Failed` | Generic fallback for unspecified validation errors. | "Please try again in a different environment." |
+
+* * *
+
+### Pro-Tip: Implementing a User Hint System
+
+## 
+
+Instead of showing the raw code (which might confuse a non-technical user), use the `onStateChange` handler to map these codes to your friendly "Recommended User Hint" column.
+
+TypeScript
+
+    // Example: Mapping technical codes to friendly messages
+    handleStateUpdate(state: LivenessState) {
+      const errorMap: Record<string, string> = {
+        'SCREEN_REFLECTION_DETECTED': 'Too much light! Please move to a shaded area.',
+        'SPOOF_BLUR_DETECTED': 'It’s a bit dark. Try increasing your screen brightness.',
+        'NO_IMAGE_DATA': 'We can’t see you! Please check your camera permissions.'
+      };
+    
+      if (state.status === 'error') {
+        this.friendlyMessage = errorMap[state.errorMsg] || "Something went wrong. Let's try again.";
+      }
+    }
+
+* * *
+
+### 📦 Latest Changes Summary
+
+## 
+
+*   **Zero-CSS Architecture:** All default styles removed; fully styleable via `[ngClass]` inputs.
+    
+*   **Label Mapping:** Added `[challengeMapping]` to allow custom text for "Smile", "Blink", etc.
+    
+*   **State Hook:** New `(onStateChange)` event for advanced lifecycle management.
+    
+*   **Encapsulation:** Set to `ViewEncapsulation.None` for seamless Tailwind and Global CSS integration.
+
+
+## ⚙️ Configuration & Thresholds
+
+
+
+| Prop Name | Default | Description |
+| --- | --- | --- |
+| `duration` | 60 | Total session time in seconds |
+| `smileThreshold` | 0.20 | Minimum width for smile detection |
+| `blinkThreshold` | 0.01 | Sensitivity for eye-closure detection |
+| `minturnHeadThreshold` | 0.15 | Minimum yaw for right-turn detection |
+| `maxturnHeadThreshold` | 0.85 | Maximum yaw for left-turn detection |
+
+* * *
+
+## ✅ Success & Failure Payload
+
+### onComplete Result
+
+# 
+
+{  
+  success: true,  
+  image: string,        // Base64 encoded capture frame  
+  skinConfidence: number // AI model confidence score  
 }
-.liveness-success {
-  color: #4caf50;
-  margin-top: 20px;
+
+### onError Result
+
+# 
+
+{  
+  success: false,  
+  reason: string,       // "timeout", "challenge\_failed", "camera\_denied"
 }
-```
 
----
+* * *
+
+## 🛠️ Advanced: Headless Mode
 
-## ⏳ Timeout Rules
 
-- Maximum session duration: set via `duration` prop (default 60s).  
-- On timeout: challenge stops, state resets, backend verification is not triggered.
 
----
+*   **Angular 🅰️**: Inject `LivenessService` to access the `state$` observable.
+    
+*   **React ⚛️**: Use `useLiveness` hook.
+    
 
-## 🔐 Security Architecture
+Allows full custom UI while using the detection engine.
 
-- **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.
+* * *
 
----
+## 🏗️ SDK Architecture
 
-## 📊 Verification Criteria
 
-- All 3 challenges completed  
-- All 5 frames successfully sent to backend  
-- Backend confirms: no spoofing, no glare, human skin texture, no video injection
 
----
+Layered design allows the same core detection engine to support multiple frameworks:
 
-## 🏗️ Integration Notes
+*   **core**: `LivenessEngine.ts` handles webcam, landmark detection, challenge sequencing, frame capture, and backend verification
+    
+*   **react**: React components + hooks handle UI and state
+    
+*   **angular**: Standalone components + services handle UI and state
+    
 
-- 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
+* * *
 
----
+## 🔧 Integration Notes
 
-## 🚀 Ideal Use Cases
 
-- KYC verification flows  
-- Identity onboarding  
-- Account recovery  
-- Secure login  
-- Financial / compliance apps
 
----
+*   **MediaPipe Dependency**: If you see `TS2307: Cannot find module '@mediapipe/tasks-vision'`, run `npm install @mediapipe/tasks-vision`.
+    
+*   **Angular Button Logic**: `[disabled]="!canStart"` — Angular inverts the boolean so button is enabled when `canStart = true`.
+    
+*   **Webcam Permissions**: Required.
+    
+*   **Timeout Rules**: Session resets if challenges aren’t completed within the configured duration.
+    
+*   **Backend**: Accepts multiple frames for final spoof analysis. Endpoint must be `/v1/verify`
+    
+*   **CORS**: Ensure API allows requests from your frontend domain.
+    
+
+* * *
 
 ## 👨‍💻 Maintainer
 
-Fadiora Richard.
 
+
+**Fadiora Richard**  
+Maintained by **Princeps Credit Systems Limited**