biometry-sdk 1.0.4 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2024] [BIOMETRY]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,16 @@
 # biometry-web-sdk
 
 ## Overview
-The `biometry-web-sdk` is a software development kit (SDK) designed to facilitate the integration of Biometry's API services.
+The **Biometry Web SDK** is a software development kit (SDK) designed to facilitate the integration of Biometry's API services.
 
 ## Features
-- Consent management (For storing facial and audio biometric data)
-- Voice onboarding
-- Face onboarding
-- Face match
-- Process video
+- **Consent management**: Ask a permission to store their biometric data for authentication using Biometry.
+- **Voice onboarding**: Onboard voice for Voice Recognition.
+- **Face onboarding**: Onboard face for face recognition.
+  - Includes a customizable **Face Onboarding UI Component** for streamlined user interactions.
+- **Face match**: Compares extracted image from user’s personal document with the frame from the `/process-video.`
+- **Process video**: Process the video through Biometry services to check liveness and authorize user.
+  - (UI Component for this feature coming soon)
 
 ## Installation
 ```bash
@@ -28,3 +30,58 @@ const userFullName = "John Doe";
 const response = await sdk.processVideo(videoFile, phrase, userFullName);
 console.log(response);
 ```
+
+## Example
+
+You can find an example in the example/ directory. The example demonstrates how to integrate the SDK into a React app.
+
+## UI Components
+The **Biometry Web SDK** includes reusable and customizable web components for key features. These components make it simple to add biometric functionalities to your application.
+
+### Face Onboarding Component
+The `Face Onboarding` component provides an intuitive interface for onboarding users with their camera. It integrates with the `BiometrySDK` to handle backend communication and error states.
+
+#### Usage
+Here's how to integrate the `Face Onboarding` component into your application:
+
+**Import in your html component:**
+```html
+<script type="module" src="node_modules/biometry-sdk/dist/components/biometry-onboarding.js"></script>
+```
+
+**Basic Usage**
+```html
+<biometry-onboarding
+  api-key="your-api-key"
+  user-fullname="John Doe">
+</biometry-onboarding>
+```
+
+**Advanced Usage**
+```html
+<biometry-onboarding
+  api-key="your-api-key"
+  user-fullname="Jane Doe">
+  
+  <video slot="video" autoplay playsinline style="width: 100%; border-radius: 10px;"></video>
+  <button slot="button" style="padding: 10px 20px; font-size: 16px;">Capture</button>
+  
+  <!-- Custom Status Messages -->
+  <div slot="loading">Please wait while we process your photo...</div>
+  <div slot="success">Congratulations! You have been onboarded.</div>
+  <div slot="error-no-face">No face detected. Make sure your face is visible.</div>
+  <div slot="error-multiple-faces">Multiple faces detected. Please try again alone.</div>
+  <div slot="error-not-centered">Align your face with the center of the screen.</div>
+  <div slot="error-other">Oops! Something went wrong. Please try again.</div>
+</biometry-onboarding>
+```
+
+### Process Video Component
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+## More Information
+
+For more detailed documentation on the Biometry API, visit the [official documentation](https://developer.biometrysolutions.com/overview/).

package/dist/components/biometry-onboarding.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/biometry-onboarding.js

@@ -0,0 +1,233 @@
+import { BiometrySDK } from "../sdk.js";
+import { BiometryAttributes, BiometryOnboardingState } from "../types.js";
+class BiometryOnboarding extends HTMLElement {
+    constructor() {
+        super();
+        this.videoElement = null;
+        this.canvasElement = null;
+        this.captureButton = null;
+        this.shadow = this.attachShadow({ mode: "open" });
+        this.sdk = null;
+        this.toggleState = this.toggleState.bind(this);
+        this.capturePhoto = this.capturePhoto.bind(this);
+    }
+    static get observedAttributes() {
+        return Object.values(BiometryAttributes);
+    }
+    get apiKey() {
+        return this.getAttribute("api-key");
+    }
+    set apiKey(value) {
+        if (value) {
+            this.setAttribute("api-key", value);
+        }
+        else {
+            this.removeAttribute("api-key");
+        }
+    }
+    get userFullname() {
+        return this.getAttribute("user-fullname");
+    }
+    set userFullname(value) {
+        if (value) {
+            this.setAttribute("user-fullname", value);
+        }
+        else {
+            this.removeAttribute("user-fullname");
+        }
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "api-key" || name === "user-fullname") {
+            this.validateAttributes();
+        }
+    }
+    connectedCallback() {
+        this.validateAttributes();
+        this.init();
+    }
+    disconnectedCallback() {
+        this.cleanup();
+    }
+    validateAttributes() {
+        if (!this.apiKey) {
+            console.error("API key is required.");
+            this.toggleState(BiometryOnboardingState.ErrorOther);
+            return;
+        }
+        if (!this.userFullname) {
+            console.error("User fullname is required.");
+            this.toggleState(BiometryOnboardingState.ErrorOther);
+            return;
+        }
+    }
+    init() {
+        this.shadow.innerHTML = `
+    <style>
+      .wrapper {
+        position: relative;
+      }
+      video {
+        transform: scaleX(-1); /* Flip video for preview */
+        max-width: 100%;
+        border-radius: var(--border-radius, 8px);
+      }
+      canvas {
+        display: none;
+      }
+    </style>
+    <div class="wrapper">
+      <slot name="video">
+        <video id="video" autoplay playsinline></video>
+      </slot>
+      <slot name="canvas">
+        <canvas id="canvas" style="display: none;"></canvas>
+      </slot>
+      <slot name="button">
+        <button id="button">Capture Photo</button>
+      </slot>
+      <div class="status">
+        <slot name="loading" class="loading"></slot>
+        <slot name="success" class="success"></slot>
+        <slot name="error-no-face" class="error-no-face"></slot>
+        <slot name="error-multiple-faces" class="error-multiple-faces"></slot>
+        <slot name="error-not-centered" class="error-not-centered"></slot>
+        <slot name="error-other" class="error-other"></slot>
+      </div>
+    </div>
+  `;
+        this.initializeSDK();
+        this.attachSlotListeners();
+        this.setupCamera();
+        this.toggleState("");
+    }
+    cleanup() {
+        var _a;
+        if ((_a = this.videoElement) === null || _a === void 0 ? void 0 : _a.srcObject) {
+            const tracks = this.videoElement.srcObject.getTracks();
+            tracks.forEach((track) => track.stop());
+        }
+        if (this.videoElement) {
+            this.videoElement.srcObject = null;
+        }
+    }
+    initializeSDK() {
+        if (this.apiKey) {
+            this.sdk = new BiometrySDK(this.apiKey);
+        }
+        else {
+            this.toggleState(BiometryOnboardingState.ErrorOther);
+            console.error("API key is required to initialize the SDK.");
+        }
+    }
+    toggleState(state) {
+        const slots = [
+            BiometryOnboardingState.Loading,
+            BiometryOnboardingState.Success,
+            BiometryOnboardingState.ErrorNoFace,
+            BiometryOnboardingState.ErrorMultipleFaces,
+            BiometryOnboardingState.ErrorNotCentered,
+            BiometryOnboardingState.ErrorOther,
+        ];
+        slots.forEach((slotName) => {
+            const slot = this.shadow.querySelector(`slot[name="${slotName}"]`);
+            if (slot) {
+                slot.style.display = slotName === state ? "block" : "none";
+            }
+        });
+    }
+    attachSlotListeners() {
+        const videoSlot = this.shadow.querySelector('slot[name="video"]');
+        const canvasSlot = this.shadow.querySelector('slot[name="canvas"]');
+        const buttonSlot = this.shadow.querySelector('slot[name="button"]');
+        const assignedVideoElements = videoSlot.assignedElements();
+        this.videoElement = (assignedVideoElements.length > 0 ? assignedVideoElements[0] : null) || this.shadow.querySelector("#video");
+        const assignedCanvasElements = canvasSlot.assignedElements();
+        this.canvasElement = (assignedCanvasElements.length > 0 ? assignedCanvasElements[0] : null) || this.shadow.querySelector("#canvas");
+        const assignedButtonElements = buttonSlot.assignedElements();
+        this.captureButton = (assignedButtonElements.length > 0 ? assignedButtonElements[0] : null) || this.shadow.querySelector("#button");
+        if (!this.videoElement) {
+            console.error("Video element is missing.");
+            return;
+        }
+        if (!this.captureButton) {
+            console.error("Capture button is missing.");
+            return;
+        }
+        else {
+            this.captureButton.addEventListener("click", this.capturePhoto);
+        }
+    }
+    setupCamera() {
+        if (!this.videoElement) {
+            console.error("Video element is missing.");
+            return;
+        }
+        navigator.mediaDevices
+            .getUserMedia({ video: true })
+            .then((stream) => {
+            this.videoElement.srcObject = stream;
+        })
+            .catch((error) => {
+            console.error("Error accessing camera:", error);
+        });
+    }
+    async capturePhoto() {
+        try {
+            if (!this.videoElement || !this.canvasElement || !this.sdk) {
+                console.error("Essential elements or SDK are not initialized.");
+                return;
+            }
+            const context = this.canvasElement.getContext("2d");
+            this.canvasElement.width = this.videoElement.videoWidth;
+            this.canvasElement.height = this.videoElement.videoHeight;
+            context.drawImage(this.videoElement, 0, 0, this.canvasElement.width, this.canvasElement.height);
+            this.toggleState("loading");
+            this.canvasElement.toBlob(async (blob) => {
+                try {
+                    if (!blob) {
+                        console.error("Failed to capture photo.");
+                        this.toggleState(BiometryOnboardingState.ErrorOther);
+                        return;
+                    }
+                    const file = new File([blob], "onboard-face.jpg", { type: "image/jpeg" });
+                    try {
+                        const response = await this.sdk.onboardFace(file, this.userFullname);
+                        const result = response.data.onboard_result;
+                        this.resultCode = result === null || result === void 0 ? void 0 : result.code;
+                        this.description = (result === null || result === void 0 ? void 0 : result.description) || "Unknown error occurred.";
+                        switch (this.resultCode) {
+                            case 0:
+                                this.toggleState(BiometryOnboardingState.Success);
+                                break;
+                            case 1:
+                                this.toggleState(BiometryOnboardingState.ErrorNoFace);
+                                break;
+                            case 2:
+                                this.toggleState(BiometryOnboardingState.ErrorMultipleFaces);
+                                break;
+                            case 3:
+                                this.toggleState(BiometryOnboardingState.ErrorNotCentered);
+                                break;
+                            default:
+                                this.toggleState(BiometryOnboardingState.ErrorOther);
+                        }
+                        console.log("Onboarding result:", result);
+                    }
+                    catch (error) {
+                        console.error("Error onboarding face:", error);
+                        this.toggleState(BiometryOnboardingState.ErrorOther);
+                    }
+                }
+                catch (error) {
+                    console.error("Error in toBlob callback:", error);
+                    this.toggleState(BiometryOnboardingState.ErrorOther);
+                }
+            }, "image/jpeg");
+        }
+        catch (error) {
+            console.error("Error capturing photo:", error);
+            this.toggleState(BiometryOnboardingState.ErrorOther);
+        }
+    }
+}
+customElements.define("biometry-onboarding", BiometryOnboarding);

package/dist/sdk.js

@@ -20,8 +20,9 @@ export class BiometrySDK {
             body,
         });
         if (!response.ok) {
-            const error = await response.json();
-            throw new Error(`Error ${response.status}: ${error.message}`);
+            const errorData = await response.json().catch(() => ({}));
+            const errorMessage = (errorData === null || errorData === void 0 ? void 0 : errorData.error) || (errorData === null || errorData === void 0 ? void 0 : errorData.message) || 'Unknown error occurred';
+            throw new Error(`Error ${response.status}: ${errorMessage}`);
         }
         return await response.json();
     }

package/dist/types.d.ts

@@ -1,3 +1,15 @@
+export declare enum BiometryAttributes {
+    ApiKey = "api-key",
+    UserFullname = "user-fullname"
+}
+export declare enum BiometryOnboardingState {
+    Loading = "loading",
+    Success = "success",
+    ErrorNoFace = "error-no-face",
+    ErrorMultipleFaces = "error-multiple-faces",
+    ErrorNotCentered = "error-not-centered",
+    ErrorOther = "error-other"
+}
 export interface ConsentResponse {
     is_consent_given: boolean;
     user_fullname: string;
@@ -5,31 +17,41 @@ export interface ConsentResponse {
 export interface VoiceOnboardingResponse {
     status: "good" | "qafailed" | "enrolled";
 }
+type Base64String = string & {
+    readonly __brand: unique symbol;
+};
+export interface DocAuthInfo {
+    document_type: string;
+    country_code: string;
+    nationality_code: string;
+    nationality_name: string;
+    sex: string;
+    first_name: string;
+    father_name: string;
+    last_name: string;
+    expiry_date: string;
+    document_number: string;
+    birth_date: string;
+    portrait_photo: Base64String;
+    signature: Base64String;
+    document_category: string;
+    issuing_state: string;
+    front_document_type_id: string;
+    contains_rfid: boolean;
+    errors?: string[];
+}
 export interface FaceOnboardingResponse {
-    onboard_result: {
-        code: number;
-        description: string;
-    };
-    document_auth: {
-        document_type: string;
-        country_code: string;
-        nationality_code: string;
-        nationality_name: string;
-        sex: string;
-        first_name: string;
-        father_name: string;
-        last_name: string;
-        expiry_date: string;
-        document_number: string;
-        birth_date: string;
-        portrait_photo: string;
-        signature: string;
-        document_category: string;
-        issuing_state: string;
-        front_document_type_id: string;
-        contains_rfid: boolean;
+    data: {
+        onboard_result: FaceOnboardingResult;
+        document_auth?: DocAuthInfo;
     };
-    message: string;
+    message?: string;
+    error?: string;
+    scoring_result?: string;
+}
+export interface FaceOnboardingResult {
+    code: number;
+    description: string;
 }
 export interface FaceMatchResponse {
     code: number;
@@ -80,3 +102,4 @@ export interface ProcessVideoResponse {
     };
     message: string;
 }
+export {};

package/dist/types.js

@@ -1 +1,14 @@
-export {};
+export var BiometryAttributes;
+(function (BiometryAttributes) {
+    BiometryAttributes["ApiKey"] = "api-key";
+    BiometryAttributes["UserFullname"] = "user-fullname";
+})(BiometryAttributes || (BiometryAttributes = {}));
+export var BiometryOnboardingState;
+(function (BiometryOnboardingState) {
+    BiometryOnboardingState["Loading"] = "loading";
+    BiometryOnboardingState["Success"] = "success";
+    BiometryOnboardingState["ErrorNoFace"] = "error-no-face";
+    BiometryOnboardingState["ErrorMultipleFaces"] = "error-multiple-faces";
+    BiometryOnboardingState["ErrorNotCentered"] = "error-not-centered";
+    BiometryOnboardingState["ErrorOther"] = "error-other";
+})(BiometryOnboardingState || (BiometryOnboardingState = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biometry-sdk",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -8,9 +8,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "jest"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
     "typescript": "^5.0.0"
-  }
-}
+  },
+  "license": "MIT"
+}