react-native-biometric-verifier 0.0.64 → 0.0.66

package/README.md

@@ -1,116 +1,253 @@
 # React Native Biometric Verifier
-
-A powerful and easy-to-use React Native module for biometric verification, featuring face recognition and QR code scanning capabilities with location validation.
-
-
-## Features
-
-- **Face Recognition**: Capture and verify user identity via face scan.
-- **QR Code Scanning**: specialized mode for location verification using QR codes.
-- **Location Validation**: Verify user presence within a specific geofence.
-- **Liveness Detection**: Configurable liveness and anti-spoofing checks.
-- **Customizable UI**: Animations, countdown timers, and feedback notifications.
-
-## Installation
-
+ 
+A beginner-friendly React Native package for biometric verification with camera-based face recognition, optional QR-based location validation, and liveness checks.
+ 
+This component is built so any React Native app can securely verify a user by combining:
+- Face scan
+- GPS location check
+- QR metadata validation
+- Liveness / anti-spoof detection
+ 
+---
+ 
+## ✅ What this package does
+ 
+- Opens a verification modal with camera preview.
+- Detects and captures a single face using the front camera.
+- Optionally scans a QR code first to validate location.
+- Uses GPS to confirm the user is within a valid radius.
+- Sends face image data to a backend API for recognition.
+- Displays status messages, countdown timer, and success/error feedback.
+ 
+---
+ 
+## 🔧 Features
+ 
+- Face recognition workflow
+- QR-based location verification
+- Distance check using GPS coordinates
+- Liveness and anti-spoof checks
+- Countdown timer for verification sessions
+- Animated notifications and progress state
+ 
+---
+ 
+## 🚀 Installation
+ 
 ```bash
 npm install react-native-biometric-verifier
 ```
-
-### Peer Dependencies
-
-This library relies on several peer dependencies that you must install in your project:
-
+ 
+### Required peer dependencies
+ 
 ```bash
 npm install react-native-vector-icons react-native-geolocation-service react-native-image-resizer react-native-fs prop-types
 ```
-
-### Platform Configuration
-
-#### iOS
-Add the following keys to your `Info.plist` file to request camera and location permissions:
-
+ 
+> The package also depends on native camera and vision packages internally. Make sure your app is configured for camera access.
+ 
+---
+ 
+## 📱 Platform setup
+ 
+### iOS
+Add these keys to `Info.plist`:
+ 
 ```xml
 <key>NSCameraUsageDescription</key>
-<string>We need access to your camera for biometric verification</string>
+<string>We need access to your camera for biometric verification.</string>
 <key>NSLocationWhenInUseUsageDescription</key>
-<string>We need your location to verify your presence at the designated area</string>
+<string>We need your location to verify your presence at the designated area.</string>
 ```
-
-#### Android
-Add the following permissions to your `AndroidManifest.xml`:
-
+ 
+### Android
+Add these permissions to `AndroidManifest.xml`:
+ 
 ```xml
 <uses-permission android:name="android.permission.CAMERA" />
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 ```
-
-## Usage
-
-Import the `BiometricModal` component and standard React hooks.
-
+ 
+---
+ 
+## 📘 Basic Usage
+ 
 ```javascript
 import React, { useState } from 'react';
 import { View, Button } from 'react-native';
 import BiometricModal from 'react-native-biometric-verifier';
-
-const App = () => {
+ 
+const App = ({ navigation }) => {
   const [isVerifierOpen, setIsVerifierOpen] = useState(false);
-
-  const handleVerificationComplete = (data) => {
-    console.log('Verification Success:', data);
-    // Handle success (e.g., navigate to next screen, show success message)
+ 
+  const handleVerificationComplete = (result) => {
+    console.log('Verification successful:', result);
     setIsVerifierOpen(false);
   };
-
+ 
   return (
     <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
       <Button title="Start Verification" onPress={() => setIsVerifierOpen(true)} />
-
+ 
       {isVerifierOpen && (
         <BiometricModal
-          data="USER_UNIQUE_ID" // e.g., Employee ID or Face ID
-          depKey="DEPARTMENT_KEY" // Optional: for QR location validation
+          data="USER_UNIQUE_ID"
           apiurl="https://your-api-endpoint.com/"
-          onclose={(val) => setIsVerifierOpen(val)}
+          navigation={navigation}
+          onclose={(open) => setIsVerifierOpen(open)}
           callback={handleVerificationComplete}
-          // Optional Props
-          qrscan={false} // Set to true to enable QR scan mode first
-          duration={100} // Countdown duration in seconds
-          MaxDistanceMeters={30} // Allowed radius for location verification
+          qrscan={false}
+          duration={100}
+          MaxDistanceMeters={30}
           frameProcessorFps={5}
-          livenessLevel="high"
-          antispooflevel="high"
+          livenessLevel={1}
+          antispooflevel={0.35}
         />
       )}
     </View>
   );
 };
-
+ 
 export default App;
 ```
-
-## Props
-
+ 
+> `navigation` is required because the component may call `navigation.goBack()` when the verification timer expires.
+ 
+---
+ 
+## 🧠 How the verification flow works
+ 
+The component supports two main flows:
+ 
+1. **Face verification only** (`qrscan={false}`)
+   - Open the front camera.
+   - Detect a single centered face.
+   - Optionally perform liveness checks.
+   - Capture the face image.
+   - Send the image to the backend API.
+ 
+2. **QR + face verification** (`qrscan={true}`)
+   - Open the back camera.
+   - Scan a QR code containing `latitude,longitude,depKey`.
+   - Request current device GPS location.
+   - Verify the device is within `MaxDistanceMeters`.
+   - Verify the QR `depKey` matches the `depKey` prop.
+   - Continue to face verification after location validation.
+ 
+---
+ 
+## 🌐 Workflow diagram
+ 
+```mermaid
+flowchart TD
+  A[Start Verification] --> B{qrscan === true?}
+  B -- Yes --> C[Scan QR Code]
+  B -- No --> F[Start Face Scan]
+  C --> D[Request Device Location]
+  D --> E[Compare distance and depKey]
+  E -- Valid --> F
+  E -- Invalid --> G[Show location error]
+  F --> H[Detect stable face & liveness]
+  H --> I[Capture photo]
+  I --> J[Upload to API]
+  J --> K{API response}
+  K -- Success --> L[Show success and callback]
+  K -- Fail --> M[Show failure message]
+```
+ 
+---
+ 
+## 📌 Props reference
+ 
 | Prop | Type | Required | Description | Default |
 |------|------|----------|-------------|---------|
-| `apiurl` | string | Yes | Base URL for the verification backend API. | - |
-| `data` | string | Yes | Unique identifier for the user (e.g., Face ID, User ID). | - |
-| `onclose` | function | Yes | Callback function to close the modal. | - |
-| `callback` | function | Yes | Callback function returning successful verification data. | - |
-| `qrscan` | boolean | No | If `true`, starts with QR code scanning mode. | `false` |
-| `depKey` | string | No | Key used to validate the QR code content. | - |
-| `duration` | number | No | Timeout duration for the session in seconds. | `100` |
-| `MaxDistanceMeters` | number | No | Maximum allowed distance (meters) for location check. | `30` |
-| `frameProcessorFps` | number | No | Frames per second for image processing. | - |
-| `livenessLevel` | string | No | Liveness detection strictness. | - |
-| `antispooflevel` | string | No | Anti-spoofing strictness. | - |
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request for any bugs or improvements.
-
-## License
-
+| `apiurl` | string | Yes | Base URL for the verification backend request. | - |
+| `data` | string | Yes | Unique user identifier (employee ID, face ID, etc.). | - |
+| `navigation` | object | Yes | React Navigation prop used for timeout navigation. | - |
+| `onclose` | function | Yes | Called when the modal closes. Receives `false`. | - |
+| `callback` | function | Yes | Called after successful verification with result data. | - |
+| `qrscan` | boolean | No | Start with QR scan mode. | `false` |
+| `depKey` | string | No | Expected key inside the scanned QR payload. | - |
+| `duration` | number | No | Countdown length in seconds. | `100` |
+| `MaxDistanceMeters` | number | No | Allowed GPS distance radius in meters. | `30` |
+| `frameProcessorFps` | number | No | Camera frame processor FPS. | `5` |
+| `livenessLevel` | number | No | Liveness check mode: `0` or `1`. | `0` |
+| `antispooflevel` | number | No | Anti-spoof threshold used internally. | `0.35` |
+| `fileurl` | string | No | Optional file URL for displaying employee data. | - |
+| `imageurl` | string | No | Optional image URL for display. | - |
+ 
+---
+ 
+## 🧩 Example: face-only verification
+ 
+```javascript
+<BiometricModal
+  data="EMPLOYEE_123"
+  apiurl="https://your-api-endpoint.com/"
+  navigation={navigation}
+  onclose={(open) => setIsVerifierOpen(open)}
+  callback={handleVerificationComplete}
+  qrscan={false}
+  duration={90}
+  frameProcessorFps={4}
+  livenessLevel={0}
+/>
+```
+ 
+## 🧭 Example: QR + face verification
+ 
+```javascript
+<BiometricModal
+  data="EMPLOYEE_123"
+  depKey="OFFICE_A"
+  apiurl="https://your-api-endpoint.com/"
+  navigation={navigation}
+  onclose={(open) => setIsVerifierOpen(open)}
+  callback={handleVerificationComplete}
+  qrscan={true}
+  duration={120}
+  MaxDistanceMeters={50}
+  frameProcessorFps={3}
+  livenessLevel={1}
+  antispooflevel={0.35}
+/>
+```
+ 
+---
+ 
+## 🧱 Internal architecture
+ 
+- `src/index.js` – Main `BiometricModal` component and verification flow.
+- `src/components/CaptureImageWithoutEdit.js` – Camera capture, face detection, and QR scanning.
+- `src/hooks/useFaceDetectionFrameProcessor.js` – Face liveness and anti-spoof frame processor.
+- `src/hooks/useGeolocation.js` – Location permission and GPS fetch.
+- `src/hooks/useImageProcessing.js` – Image resize and Base64 conversion.
+- `src/hooks/useCountdown.js` – Countdown timer logic.
+- `src/hooks/useNotifyMessage.js` – Animated notification messages.
+- `src/utils/NetworkServiceCall.js` – API request helper.
+- `src/utils/distanceCalculator.js` – Geolocation distance calculation.
+- `src/utils/Global.js` – Shared constants and theme values.
+ 
+---
+ 
+## 💡 Interview talking points
+ 
+- Explain the dual modes: face-only and QR-first.
+- Describe how location validation prevents spoofing of presence.
+- Mention the use of `use*` hooks for clean and reusable code.
+- Highlight the flow from camera capture → Base64 conversion → API request → callback.
+- Note the user-friendly UI with timer, notifications, and step indicator.
+ 
+---
+ 
+## 🤝 Contribution
+ 
+Contributions are welcome. Open an issue or submit a pull request for bug fixes and improvements.
+ 
+---
+ 
+## 📄 License
+ 
 JESCON TECHNOLOGIES PVT LTD
+  

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "react-native-biometric-verifier",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "description": "A React Native module for biometric verification with face recognition and QR code scanning",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/index.d.ts

@@ -0,0 +1,303 @@
+import React from 'react';
+import { Animated, NavigationProp } from 'react-native';
+
+// ============ COMPONENTS ============
+
+/**
+ * Card component props
+ */
+export interface CardProps {
+  employeeData: {
+    facename: string;
+    faceid: string;
+    imageurl?: string;
+  };
+  apiurl: string;
+  fileurl?: string;
+}
+
+/**
+ * Card component - displays employee information
+ */
+export const Card: React.FC<CardProps>;
+
+/**
+ * Loader component props
+ */
+export interface LoaderProps {
+  state: {
+    isLoading: boolean;
+    loadingType: string;
+    currentStep: string;
+    animationState: string;
+  };
+  gifSource: { uri: string } | null;
+}
+
+/**
+ * Loader component - displays loading animation
+ */
+export const Loader: React.FC<LoaderProps>;
+
+/**
+ * CountdownTimer component props
+ */
+export interface CountdownTimerProps {
+  duration: number;
+  currentTime: number;
+}
+
+/**
+ * CountdownTimer component - displays countdown timer
+ */
+export const CountdownTimer: React.FC<CountdownTimerProps>;
+
+/**
+ * Notification component props
+ */
+export interface NotificationProps {
+  notification: {
+    visible: boolean;
+    message: string;
+    type: 'success' | 'error' | 'info' | 'warning';
+  };
+  fadeAnim: Animated.Value;
+  slideAnim: Animated.Value;
+}
+
+/**
+ * Notification component - displays notifications
+ */
+export const Notification: React.FC<NotificationProps>;
+
+/**
+ * CaptureImageWithoutEdit component props
+ */
+export interface CaptureImageWithoutEditProps {
+  cameraType: 'front' | 'back';
+  onCapture: (capturedData: any) => void;
+  showCodeScanner?: boolean;
+  isLoading?: boolean;
+  frameProcessorFps?: number;
+  livenessLevel?: string;
+  antispooflevel?: string;
+}
+
+/**
+ * CaptureImageWithoutEdit component - captures images from camera
+ */
+export const CaptureImageWithoutEdit: React.FC<CaptureImageWithoutEditProps>;
+
+/**
+ * StepIndicator component props
+ */
+export interface StepIndicatorProps {
+  currentStep: string;
+  qrscan?: boolean;
+}
+
+/**
+ * StepIndicator component - shows current verification step
+ */
+export const StepIndicator: React.FC<StepIndicatorProps>;
+
+// ============ HOOKS ============
+
+/**
+ * useCountdown hook return type
+ */
+export interface UseCountdownReturn {
+  countdown: number;
+  startCountdown: (onExpireCallback?: () => void) => void;
+  resetCountdown: () => void;
+  pauseCountdown: () => void;
+  resumeCountdown: () => void;
+}
+
+/**
+ * Custom hook for countdown timer with pause/resume functionality
+ */
+export function useCountdown(duration: number, onExpire?: () => void): UseCountdownReturn;
+
+/**
+ * useGeolocation hook return type
+ */
+export interface UseGeolocationReturn {
+  requestLocationPermission: () => Promise<boolean>;
+  getCurrentLocation: () => Promise<{
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    altitude?: number;
+    speed?: number;
+    heading?: number;
+  } | null>;
+}
+
+/**
+ * Custom hook for geolocation functionality
+ */
+export function useGeolocation(): UseGeolocationReturn;
+
+/**
+ * useImageProcessing hook return type
+ */
+export interface UseImageProcessingReturn {
+  convertImageToBase64: (imageUri: string) => Promise<string>;
+}
+
+/**
+ * Custom hook for image processing utilities
+ */
+export function useImageProcessing(): UseImageProcessingReturn;
+
+/**
+ * useNotifyMessage hook return type
+ */
+export interface UseNotifyMessageReturn {
+  notification: {
+    visible: boolean;
+    message: string;
+    type: 'success' | 'error' | 'info' | 'warning';
+  };
+  fadeAnim: Animated.Value;
+  slideAnim: Animated.Value;
+  notifyMessage: (message: string, type?: 'success' | 'error' | 'info' | 'warning') => void;
+  clearNotification: () => void;
+}
+
+/**
+ * Custom hook for notification management
+ */
+export function useNotifyMessage(): UseNotifyMessageReturn;
+
+/**
+ * useSafeCallback hook return type
+ */
+export type SafeCallback = (data: any) => void;
+
+/**
+ * Custom hook for safe callback execution
+ */
+export function useSafeCallback(callback: SafeCallback, notifyMessage: (msg: string, type?: string) => void): (data: any) => void;
+
+// ============ UTILITIES ============
+
+/**
+ * Global constants and configuration
+ */
+export class Global {
+  static AppTheme: {
+    primary: string;
+    primaryLight: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    dark: string;
+    light: string;
+    gray: string;
+    background: string;
+    cardBackground: string;
+    textLight: string;
+    shadow: string;
+    modalBackground: string;
+  };
+
+  static LoadingTypes: {
+    none: string;
+    imageProcessing: string;
+    faceRecognition: string;
+    networkRequest: string;
+    locationPermission: string;
+    gettingLocation: string;
+    calculateDistance: string;
+    locationVerification: string;
+  };
+
+  static AnimationStates: {
+    faceScan: string;
+    qrScan: string;
+    processing: string;
+    success: string;
+    error: string;
+  };
+
+  static ImageResize: {
+    width: number;
+    height: number;
+    format: 'JPEG' | 'PNG';
+    quality: number;
+  };
+
+  static CountdownDuration: number;
+}
+
+/**
+ * Calculates distance between two geographical points using Haversine formula
+ */
+export function getDistanceInMeters(lat1: number, lng1: number, lat2: number, lng2: number): number | null;
+
+/**
+ * Network service call options
+ */
+export interface NetworkServiceCallResponse {
+  httpstatus?: number;
+  data?: any;
+  message?: string;
+  [key: string]: any;
+}
+
+/**
+ * Makes HTTP requests with method, URL, headers, and body
+ */
+export function networkServiceCall(
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+  url: string,
+  extraHeaders?: Record<string, string>,
+  body?: Record<string, any>
+): Promise<NetworkServiceCallResponse>;
+
+/**
+ * Helper function for GET API calls
+ */
+export function getApiCall(url: string, extraHeaders?: Record<string, string>): Promise<NetworkServiceCallResponse>;
+
+/**
+ * Get appropriate loader GIF based on animation state
+ */
+export function getLoaderGif(
+  animationState: string,
+  currentStep: string,
+  apiurl: string,
+  imageurl?: string
+): { uri: string } | null;
+
+// ============ MAIN COMPONENT ============
+
+/**
+ * BiometricModal component props
+ */
+export interface BiometricModalProps {
+  data: any;
+  depKey: string;
+  qrscan?: boolean;
+  callback: (result: any) => void;
+  apiurl: string;
+  onclose: () => void;
+  frameProcessorFps?: number;
+  livenessLevel?: string;
+  fileurl?: string;
+  imageurl?: string;
+  navigation: NavigationProp<any>;
+  duration?: number;
+  MaxDistanceMeters?: number;
+  antispooflevel?: string;
+}
+
+/**
+ * Main biometric verification modal component
+ */
+declare const BiometricModal: React.MemoExoticComponent<React.FC<BiometricModalProps>>;
+
+export default BiometricModal;