smartcomply-web-sdk 1.0.68 → 1.0.70

package/dist/esm/flow/SmartComplyFlow.js

@@ -3,8 +3,35 @@ import { getTheme, TYPE, RADIUS } from "./theme";
 import { DocumentCapture } from "./DocumentCapture";
 import { collectDeviceMetadata } from "../utils/device";
 import { requiresBackSide } from "../utils/documentRules";
+import { DEFAULT_CHALLENGE_ACTIONS } from "../utils/constants";
 import { icon } from "./icons";
 import { renderSpinner, renderInlineSpinner } from "./spinner";
+// A dropped camera/network/upload error is not the user's fault and must not
+// cost them a retry attempt — only a genuine verification outcome should.
+// Classified by message rather than a typed error class since the errors
+// originate from several independent layers (CameraManager, VideoRecorder,
+// LivenessUploader) that don't share a common error type today.
+const _INFRASTRUCTURE_ERROR_PATTERNS = [
+    "camera connection was lost",
+    "network error",
+    "failed after all retries",
+    "camera access is not supported",
+    "camera access failed",
+    "recording failed unexpectedly",
+];
+function _isInfrastructureError(err) {
+    const msg = String(err?.message || "").toLowerCase();
+    return _INFRASTRUCTURE_ERROR_PATTERNS.some((p) => msg.includes(p));
+}
+// Keep this plain-language and reassuring for infrastructure hiccups — the
+// user did nothing wrong, so the copy should say so rather than sound like
+// a rejection.
+function _userFacingLivenessError(err) {
+    if (_isInfrastructureError(err)) {
+        return "We lost connection during your scan — this wasn't anything you did. Please check your camera and internet connection, then try again.";
+    }
+    return err?.message || "We couldn't verify your face. Please try again.";
+}
 const STEP_ORDER = [
     "loading",
     "welcome",
@@ -49,15 +76,17 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
         return { icon: "🏦", desc: "Enter your 11-digit Bank Verification Number (BVN)", requiresBack: false };
     }
     // NIN — always 11 digits (covers nin_with_face, NIN slip, etc.). Not every
-    // physical NIN card in circulation has meaningful back-side content, so
-    // the back photo is offered but optional rather than required — the
-    // plain data-verification flow (just typing the 11-digit number, no
-    // document) never captures a photo at all, so requiresBack stays false there.
+    // NIN document in circulation has a back side — a NIN slip typically
+    // doesn't, while a NIN card does — so the back photo is offered for
+    // either, but optional rather than required: add it if your document
+    // has one, skip it if it doesn't. The plain data-verification flow (just
+    // typing the 11-digit number, no document) never captures a photo at
+    // all, so requiresBack stays false there.
     if (u.includes("NIN") || u.includes("NATIONAL IDENTITY NUMBER")) {
         return {
             icon: "🆔",
             desc: isDocumentFlow
-                ? "Capture or upload your NIN card (back optional)"
+                ? "Capture or upload your NIN (slip or card) — add the back if your document has one"
                 : "Enter your 11-digit National Identification Number (NIN)",
             requiresBack: isDocumentFlow ? "optional" : false,
         };
@@ -273,9 +302,14 @@ export class SmartComplyFlow {
         this.isDestroyed = false;
         this.headerBackBtn = null;
         this._keydownHandler = null;
+        this._visibilityHandler = null;
+        this._hiddenAtMs = null;
+        this._popstateHandler = null;
+        this._historyGuardActive = false;
         // Retry safety — max 3 confirmation rejections or liveness failures per session
         this._confirmRetries = 0;
         this._livenessFailures = 0;
+        this._livenessAttemptId = 0;
         // IVS result stored for confirm_identity screen
         this._ivsName = "";
         this._ivsGender = "";
@@ -334,6 +368,26 @@ export class SmartComplyFlow {
             document.removeEventListener("keydown", this._keydownHandler);
             this._keydownHandler = null;
         }
+        if (this._visibilityHandler) {
+            document.removeEventListener("visibilitychange", this._visibilityHandler);
+            this._visibilityHandler = null;
+        }
+        if (this._popstateHandler) {
+            window.removeEventListener("popstate", this._popstateHandler);
+            this._popstateHandler = null;
+        }
+        // Closing via the ✕/Escape/completion (not via the back gesture, which
+        // handles its own guard entry above) still leaves our one guard entry
+        // sitting on top of the host's history — back out of it so the user
+        // isn't left pressing back once "into" a widget that's already gone.
+        if (this._historyGuardActive) {
+            this._historyGuardActive = false;
+            try {
+                if (history.state?.scFlowGuard)
+                    history.back();
+            }
+            catch { /* ignore — best effort only */ }
+        }
         this.docCapture?.destroy();
         // Release any pre-warmed camera stream
         if (this._prewarmedStream) {
@@ -464,6 +518,64 @@ export class SmartComplyFlow {
             }
         };
         document.addEventListener("keydown", this._keydownHandler);
+        // A tab backgrounded mid-scan (a notification, switching apps to copy a
+        // code, a phone call) leaves the camera stream and detection loop in an
+        // undefined state on most mobile browsers — rAF throttles/pauses while
+        // hidden, and some browsers suspend the camera outright. Rather than let
+        // the scan silently continue against stale state and fail confusingly,
+        // restart the liveness step cleanly once the tab has been away long
+        // enough to plausibly have disrupted an active camera session. A brief
+        // glance elsewhere (quick app switch, screen lock tap) is not enough to
+        // warrant restarting — only a real return-from-away.
+        const REBACKGROUND_RESTART_MS = 3000;
+        this._visibilityHandler = () => {
+            if (this.isDestroyed)
+                return;
+            if (document.hidden) {
+                this._hiddenAtMs = Date.now();
+                return;
+            }
+            const hiddenAt = this._hiddenAtMs;
+            this._hiddenAtMs = null;
+            if (hiddenAt === null)
+                return;
+            const awayMs = Date.now() - hiddenAt;
+            if (awayMs >= REBACKGROUND_RESTART_MS && this.currentStep === "liveness") {
+                this.showStep("liveness");
+            }
+        };
+        document.addEventListener("visibilitychange", this._visibilityHandler);
+        // Intercept the browser/OS back gesture so it steps back within the flow
+        // instead of navigating the host page away and abandoning the session
+        // mid-verification (camera left open, timers orphaned). One guard entry
+        // is pushed — not one per step — to minimize interference with a host
+        // page's own router; popstate re-arms it each time so back can be
+        // pressed repeatedly. If the current step has no back target, back
+        // closes the widget cleanly instead (same as the header ✕).
+        this._historyGuardActive = true;
+        try {
+            history.pushState({ scFlowGuard: true }, "");
+        }
+        catch {
+            this._historyGuardActive = false; // host disallows pushState — degrade silently
+        }
+        this._popstateHandler = () => {
+            if (this.isDestroyed || !this._historyGuardActive)
+                return;
+            const backAction = this._getBackAction(this.currentStep);
+            if (backAction) {
+                backAction();
+            }
+            else {
+                this.close();
+                return; // don't re-arm — we're closing, let the real back navigation proceed
+            }
+            try {
+                history.pushState({ scFlowGuard: true }, "");
+            }
+            catch { /* ignore — nothing more we can do */ }
+        };
+        window.addEventListener("popstate", this._popstateHandler);
     }
     async initialize() {
         this.showStep("loading");
@@ -732,14 +844,16 @@ export class SmartComplyFlow {
         btn.style.cssText += "margin-top:2px;";
         btn.addEventListener("click", () => this.showStep("country"));
         container.appendChild(btn);
-        // Trust badge — "Powered by Adhere" already lives in the persistent
-        // modal footer below; repeating it here just cost vertical space.
+        // Plain-language line on what the camera/photo is for and what happens
+        // to it — shown before the "Get Started" tap that leads to the first
+        // camera permission prompt, so the browser's own prompt isn't the only
+        // context the user gets for why a camera is being requested.
         const trust = document.createElement("div");
         trust.style.cssText = `
-      display:flex;align-items:center;gap:6px;
-      color:${this.theme.textMuted};font-size:10.5px;
+      display:flex;align-items:flex-start;gap:6px;text-align:left;
+      color:${this.theme.textMuted};font-size:10.5px;line-height:1.5;
     `;
-        trust.textContent = "🔒  End-to-end encrypted";
+        trust.innerHTML = `<span style="flex-shrink:0;">🔒</span><span>Your photo and camera scan are used only to verify it's really you, and are kept encrypted.</span>`;
         container.appendChild(trust);
     }
     // ── Country Select ──────────────────────────────────────────────
@@ -1853,6 +1967,11 @@ export class SmartComplyFlow {
             this._renderRetryLimitReached(container);
             return;
         }
+        // Each render gets its own id so a stale attempt (e.g. abandoned after
+        // the tab was backgrounded and we restarted the scan on return) can't
+        // resolve/reject into the current one — see the visibilitychange
+        // handler in mount(), which re-renders this step on return-to-foreground.
+        const attemptId = ++this._livenessAttemptId;
         const title = this.createStepTitle("Face verification");
         container.appendChild(title);
         const desc = document.createElement("div");
@@ -1901,8 +2020,12 @@ export class SmartComplyFlow {
                 error: this.theme.error,
                 warning: this.theme.warning,
             },
-        }, ["BLINK"], this.livenessEntryId || undefined)
+        }, [...DEFAULT_CHALLENGE_ACTIONS], this.livenessEntryId || undefined)
             .then((result) => {
+            // A stale attempt (superseded by a restart after the tab was
+            // backgrounded) resolving late must not act on the current screen.
+            if (attemptId !== this._livenessAttemptId)
+                return;
             // W11: After submit, end user is done — show "You're all done" screen.
             // Backend processing continues in background; client receives webhook.
             // Track liveness failures for retry limit (W14).
@@ -1915,8 +2038,18 @@ export class SmartComplyFlow {
             this.showStep("done");
         })
             .catch((err) => {
-            this._livenessFailures++;
-            this.showErrorStep(err.message || "Liveness verification failed. Please try again.");
+            if (attemptId !== this._livenessAttemptId)
+                return;
+            // Only count a genuine verification failure against the retry limit —
+            // a dropped camera, network blip, or upload failure isn't the user's
+            // fault and shouldn't cost them one of their limited attempts. These
+            // are infrastructure-layer errors (thrown/rejected); a real face-
+            // match/quality failure comes back as a resolved result with
+            // status "failed" instead (handled in .then() above).
+            if (!_isInfrastructureError(err)) {
+                this._livenessFailures++;
+            }
+            this.showErrorStep(_userFacingLivenessError(err));
         });
     }
     // ── Error ───────────────────────────────────────────────────────
@@ -2238,6 +2371,24 @@ export class SmartComplyFlow {
             .flatMap((ch) => ch.fields || []);
         return allFields.some((f) => isUploadFieldType(f.type));
     }
+    /**
+     * The "go back one step" target for a given step, if that step is
+     * navigable — shared by the header back button and the browser
+     * back-button (popstate) handler in mount() so both agree on the same
+     * step order.
+     */
+    _getBackAction(step) {
+        const countries = Object.keys(this.sdkConfig?.channels || {});
+        const backTargets = {
+            id_type: () => this.showStep(countries.length > 1 ? "country" : "welcome"),
+            country: () => this.showStep("welcome"),
+            id_input: () => this.showStep("id_type"),
+            confirm_identity: () => this.showStep("id_input"),
+            document_capture: () => { this.docCapture?.destroy(); this.showStep("id_type"); },
+            document_confirm: () => { this.docCapture?.destroy(); this.showStep("document_capture"); },
+        };
+        return backTargets[step];
+    }
     updateProgress() {
         const isDocFlow = this.isDocumentFlow();
         const countries = Object.keys(this.sdkConfig?.channels || {});
@@ -2289,15 +2440,7 @@ export class SmartComplyFlow {
         }
         // Back button — show for navigable steps only
         if (this.headerBackBtn) {
-            const backTargets = {
-                id_type: () => this.showStep(countries.length > 1 ? "country" : "welcome"),
-                country: () => this.showStep("welcome"),
-                id_input: () => this.showStep("id_type"),
-                confirm_identity: () => this.showStep("id_input"),
-                document_capture: () => { this.docCapture?.destroy(); this.showStep("id_type"); },
-                document_confirm: () => { this.docCapture?.destroy(); this.showStep("document_capture"); },
-            };
-            const backAction = backTargets[this.currentStep];
+            const backAction = this._getBackAction(this.currentStep);
             if (backAction) {
                 this.headerBackBtn.style.display = "flex";
                 const newBtn = this.headerBackBtn.cloneNode(true);