smartcomply-web-sdk 1.0.70 → 1.0.71

package/README.md

@@ -15,8 +15,8 @@ SmartComply SDK is a **KYC-as-a-service** widget that businesses embed in their
 
 The SDK verifies that a person is **real**, **alive**, and **who they claim to be**:
 
-1. **Identity verification** — Validates the user's BVN/NIN against government databases, or extracts data from uploaded documents via OCR
-2. **Liveness detection** — Camera-based challenge-response (blink, turn head, open mouth) to prove the person is physically present — not a photo or video replay
+1. **Identity verification** — Validates the user's BVN/NIN against government databases, or extracts data from uploaded documents
+2. **Liveness detection** — A short passive camera scan (blink + natural head movement, one continuous window) to prove the person is physically present — not a photo or video replay
 3. **Face matching** — Compares the user's live selfie against:
    - The government-returned photo (BVN/NIN flow), or
    - The face on their uploaded document (passport/license flow)
@@ -25,8 +25,10 @@ The SDK verifies that a person is **real**, **alive**, and **who they claim to b
 
 | Flow | How it works | ID Types |
 |------|-------------|----------|
-| **Data verification** | User enters an ID number → backend validates against government database → face match against government photo | BVN, NIN |
-| **Document verification** | User uploads/captures a document photo → OCR extracts data + expiry check → face match against document photo | Passport, National ID, Driver's License |
+| **Data verification** | User enters an ID number → backend validates against government database → face match against government photo | BVN, NIN, and other data-only channels configured in your dashboard |
+| **Document verification** | User captures/uploads a document photo (front, plus back if required or offered) → data is extracted + expiry checked → face match against document photo | Passport, National ID (NIN slip/card), Driver's License, Voter's Card, and other document channels configured in your dashboard |
+
+Exactly which ID types are available depends on what's enabled for your account and country in the Adhere dashboard — fetch `config.channels` (see [Load Configuration](#load-configuration)) rather than hardcoding a list.
 
 ### End-to-End Flow
 
@@ -46,8 +48,8 @@ The SDK verifies that a person is **real**, **alive**, and **who they claim to b
 │                         │                                           │
 │               ┌─────────┼──────────┐                               │
 │               ▼         ▼          ▼                                │
-│          Face Match   OCR      Gov DB Check                        │
-│          (DeepFace)  (document)  (BVN/NIN)                         │
+│          Face Match   Document Read   Gov DB Check                 │
+│        (+ liveness)   (extraction)      (BVN/NIN)                  │
 │               └─────────┼──────────┘                               │
 │                         ▼                                           │
 │                    Webhook POST ──────────► YOUR SERVER             │
@@ -64,7 +66,14 @@ npm install smartcomply-web-sdk
 ### Alternative: CDN (No Build Step)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@1.0.3/dist/smartcomply.browser.js"></script>
+<!-- Always latest version -->
+<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@latest/dist/smartcomply.browser.js"></script>
+
+<!-- Or pin to a specific version (recommended for production) — replace X.Y.Z
+     with the version you've actually tested against. Current version:
+     https://www.npmjs.com/package/smartcomply-web-sdk -->
+<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@X.Y.Z/dist/smartcomply.browser.js"></script>
+
 <script>
   // SDK available as window.SmartComplySDK
   SmartComplySDK.SmartComplyFlow.open({
@@ -75,6 +84,8 @@ npm install smartcomply-web-sdk
 </script>
 ```
 
+> Pin to a specific version in production to avoid unexpected breaking changes — `@latest` is convenient for prototyping only. See [npmjs.com/package/smartcomply-web-sdk](https://www.npmjs.com/package/smartcomply-web-sdk) for the current version number.
+
 ---
 
 ## Option 1: Drop-in Widget (Recommended)
@@ -117,9 +128,9 @@ That's it. The SDK will:
 1. Create a secure session with the Adhere backend
 2. Show a branded welcome screen (your brand name + theme from dashboard)
 3. Let the user select their country and ID type
-4. Collect their BVN/NIN number **or** capture their document photo
-5. Run face liveness detection (camera + challenge actions)
-6. Record a video and submit everything to the backend
+4. Collect their BVN/NIN number **or** capture their document photo (front, and back if the document has/needs one)
+5. Run a passive face liveness scan (camera stays open for a few seconds — the user blinks and turns their head naturally, no discrete step-by-step prompts)
+6. Record a short clip and submit everything to the backend
 7. Show a result screen and call your `onComplete` callback
 
 ### What the User Sees
@@ -130,9 +141,21 @@ That's it. The SDK will:
 | 2 | Country | Select country (auto-skipped if only one country configured) |
 | 3 | ID Type | Choose from the channels you configured (e.g., BVN, NIN, Passport) |
 | 4a | ID Input | Enter BVN/NIN number → instant backend verification against government DB |
-| 4b | Document | Capture a photo of passport/ID card (camera or file upload) |
-| 5 | Liveness | Camera opens — user completes challenge actions (blink, turn head, open mouth) |
-| 6 | Done | "Verification Submitted" — user clicks Done, result arrives via webhook |
+| 4b | Document | Capture/upload the document photo — front required; back is required, optional, or not offered depending on the document type (see [Two-Sided Documents](#two-sided-documents)) |
+| 5 | Liveness | Camera opens — a single passive scan window; the user blinks and turns their head naturally, no sequential prompts |
+| 6 | Done | "Verification Submitted" — user clicks Done, final result arrives via webhook |
+
+### Two-Sided Documents
+
+Some document types capture a back-side photo as well as the front:
+
+| Document | Back side |
+|----------|-----------|
+| Passport | Never — front only |
+| NIN (slip or card) | **Optional** — offered, with a "Skip" option, since not every NIN document has a usable back |
+| Driver's License, Voter's Card, National ID Card | **Required** |
+
+This is driven entirely by the `requires_back_side` flag the backend returns per channel in `config.channels` (see [Load Configuration](#load-configuration)) — the drop-in widget handles it automatically. If you're building your own UI (headless), pass both `document`/`id_file` (front) and `document_back` (back) to `liveness.create()`/`startCheck()` when you have one; `document_back` is always optional at the API level regardless of what the UI requires.
 
 ### `SmartComplyFlow.open()` Options
 
@@ -155,12 +178,21 @@ SmartComplyFlow.open({
 
 ### `onComplete` Result
 
+`onComplete` fires as soon as the user finishes their part (the "Verification Submitted" screen renders) — **not** when verification is actually decided. Backend processing (face match, OCR, government DB check) continues after this fires; the pass/fail outcome only ever arrives via [webhook](#receiving-results-webhook).
+
 ```typescript
 {
-  entryId: 42,                    // Use this to track the verification
-  status: "processing",           // Always "processing" — final result via webhook
-  submittedAt: "2026-04-13T...",  // ISO timestamp
-  verificationResult: {           // Only for data verification (BVN/NIN)
+  entryId: 42,                          // Use this to track the verification — matches
+                                         // verification_id in the webhook payload
+  sessionId: "da7623bd-9158-4b56-...",  // The session token used for this flow
+  status: "processing",                 // Always "processing" — this is a submission
+                                         // receipt, not a verification verdict
+  submittedAt: "2026-04-13T...",        // ISO timestamp
+  verificationResult: {                 // Only present for data verification (BVN/NIN) —
+                                         // the immediate government-DB lookup result.
+                                         // This confirms the ID number matched a real
+                                         // record; it says nothing about the face match,
+                                         // which is still pending at this point.
     status: "success",
     code: "VERIFICATION_COMPLETE",
     data: { first_name: "Amara", last_name: "Okafor", identity_check_id: 123, ... }
@@ -210,14 +242,17 @@ console.log(config.verification_type); // ["data_verification"]
 console.log(config.channels);
 // {
 //   "nigeria": [
-//     { id: 8, name: "National Identity Number (NIN)", fields: [{ type: "input", label: "Identification Number" }] },
-//     { id: 2, name: "Bank Verification Number Advanced (BVN)", fields: [{ type: "input", label: "Bank Verification Number" }] }
+//     { id: 8, name: "National Identity Number (NIN)", fields: [{ type: "input", label: "Identification Number" }], requires_back_side: "optional" },
+//     { id: 2, name: "Bank Verification Number Advanced (BVN)", fields: [{ type: "input", label: "Bank Verification Number" }] },
+//     { id: 5, name: "Driver's License", fields: [{ type: "upload", label: "Document" }], requires_back_side: true }
 //   ]
 // }
 ```
 
 Use `config.channels` to build your own country/ID type selector. Each channel's `fields` array tells you what inputs to render.
 
+For a document-verification channel, `requires_back_side` tells you whether to also collect a back-side photo: `true` (required), `false`/absent (never), or the string `"optional"` (offer it, but the user can skip — see [Two-Sided Documents](#two-sided-documents)).
+
 ### Verify Identity (Data Verification)
 
 For BVN/NIN — validates against the government database:
@@ -245,14 +280,16 @@ const result = await sdk.liveness.startCheck(container, {
   identifier: "12345678901",          // The ID number entered by the user
   identifier_type: "NIN",
   country: "NG",
-  id_file: documentBlob,              // Optional: document photo (for document flow)
-  identity_check: identityCheckId,    // Optional: from verify response (for data flow)
-}, ["BLINK", "TURN_LEFT", "OPEN_MOUTH"]);
+  document: documentFrontBlob,        // Optional: document front photo (document flow)
+  document_back: documentBackBlob,    // Optional: document back photo, if the channel's
+                                       // requires_back_side is true or "optional"
+  identity_check: identityCheckId,    // Optional: from verify response (data flow)
+}, ["BLINK", "TURN_HEAD"]);
 
 console.log(result.status); // "processing"
 ```
 
-The SDK handles camera access, face detection, action prompts, video recording, and submission.
+The camera UI runs a single passive scan (the user blinks and turns their head naturally within one window) rather than stepping through discrete prompts. The `actions` array (3rd argument, defaults to `["BLINK", "TURN_HEAD"]`) is sent to the backend as a descriptive tag — shown on your Adhere dashboard — not a live command sequence the UI enforces. The SDK handles camera access, face detection, video recording, and submission end to end.
 
 ### Liveness Check (fully manual)
 
@@ -264,9 +301,12 @@ const entry = await sdk.liveness.create({
   identifier: "A12345678",
   identifier_type: "Passport",
   country: "US",
-  challenge_actions: ["BLINK", "TURN_LEFT", "OPEN_MOUTH"],
+  challenge_actions: ["BLINK", "TURN_HEAD"],  // Descriptive tag, not a live prompt sequence
   autoshot_file: selfieBlob,          // Captured selfie (JPEG/PNG, max 5MB)
-  id_file: passportPhotoBlob,         // Optional: document photo
+  document: passportFrontBlob,        // Optional: document front photo
+  document_back: passportBackBlob,    // Optional: document back photo (rarely needed —
+                                       // most document types are front-only; see
+                                       // Two-Sided Documents above)
   identity_check: identityCheckId,    // Optional: from verify response
 });
 
@@ -284,121 +324,236 @@ const result = await sdk.liveness.submit(entry.id, videoBlob, snapshotBlob);
 
 ## Receiving Results (Webhook)
 
-Verification is processed asynchronously. After the user submits, the backend runs face matching using AI (DeepFace with RetinaFace detection) and delivers results via webhook to the URL configured in your SDK Config.
+Verification is processed asynchronously. After the user submits, the backend runs face matching, OCR (for documents), and the government DB check (for BVN/NIN), then delivers one `liveness.completed` webhook to the URL configured in your SDK Config once everything is done.
+
+The payload shape is the same for both verification types — `verification_type` tells you which one it was, and `document` is only present for document verification.
 
 ### Webhook Payload — Data Verification (BVN/NIN)
 
 ```json
 POST https://your-server.com/webhook
 Content-Type: application/json
-X-Adhere-Signature: <hmac-sha256-hex>
+X-Adhere-Signature: sha256=<hmac-sha256-hex>
 
 {
   "event": "liveness.completed",
-  "data": {
-    "entry_id": 42,
-    "status": "passed",
-    "is_verified": true,
-    "match_score": 0.15,
-    "confidence_percentage": 62.5,
-    "identity_face_match": {
+  "verification_id": 42,
+  "verification_type": "data_verification",
+  "status": "passed",
+  "failure_reason": null,
+  "timestamp": "2026-08-08T10:15:00.000Z",
+  "subject": {
+    "identifier": "12345678901",
+    "identifier_type": "National Identity Number (NIN)",
+    "country": "nigeria"
+  },
+  "biometrics": {
+    "liveness_verified": true,
+    "face_match": {
+      "attempted": true,
       "verified": true,
-      "distance": 0.12,
-      "threshold": 0.4,
       "confidence_percentage": 70.0
     },
-    "metadata": { "ip_address": "...", "user_agent": "..." }
+    "selfie_url": "https://.../autoshot.jpg",
+    "face_analysis": {
+      "gender": "Female",
+      "dominant_emotion": "neutral",
+      "face_quality": {
+        "face_detected": true,
+        "face_confidence": 0.98,
+        "blur_score": 142.3,
+        "is_blurry": false
+      }
+    }
+  },
+  "activity": {
+    "session_id": "da7623bd-9158-4b56-a9e4-4bccf3c0133f",
+    "started_at": "2026-08-08T10:12:00.000Z",
+    "submitted_at": "2026-08-08T10:14:30.000Z",
+    "completed_at": "2026-08-08T10:15:00.000Z",
+    "duration_seconds": 180
+  },
+  "request_context": {
+    "ip": { "address": "102.67.1.66", "city": "Lagos", "country_code": "NG", "...": "..." },
+    "device": { "user_agent": "Mozilla/5.0 ...", "type": "desktop", "os": "Windows", "...": "..." }
+  },
+  "customer_profile": {
+    "first_name": "AMARA",
+    "last_name": "OKAFOR",
+    "other_name": null,
+    "date_of_birth": "01-Jan-1997",
+    "age": 29,
+    "gender": "Female",
+    "id_number": "12345678901",
+    "serial_number": null,
+    "occupation": null,
+    "place_of_birth": null,
+    "place_of_live": "...",
+    "date_of_issue": null,
+    "photo_url": null
   }
 }
 ```
 
-### Webhook Payload — Document Verification (Passport/License)
+`photo_url` is always `null` here — the government-returned photo isn't exposed in the webhook (it's already used server-side for face matching; the `biometrics.selfie_url` field above is the user's own selfie, not the reference photo).
+
+### Webhook Payload — Document Verification (Passport/License/NIN card)
+
+Same top-level shape, plus a `document` block instead of (or alongside) `customer_profile`:
 
 ```json
 {
   "event": "liveness.completed",
-  "data": {
-    "entry_id": 43,
-    "status": "passed",
-    "is_verified": true,
-    "match_score": 0.18,
-    "confidence_percentage": 55.0,
-    "document_verification": {
-      "status": "verified",
-      "document_type": "passport",
-      "is_expired": false,
-      "face_match_verified": true,
-      "face_match_score": 0.22,
-      "extracted_name": "AMARA OKAFOR",
-      "extracted_expiry_date": "2030-06-15"
-    },
-    "metadata": { "ip_address": "...", "user_agent": "..." }
+  "verification_id": 43,
+  "verification_type": "document_verification",
+  "status": "passed",
+  "failure_reason": null,
+  "timestamp": "2026-08-08T10:20:00.000Z",
+  "subject": {
+    "identifier": "A12345678",
+    "identifier_type": "Passport",
+    "country": "usa"
+  },
+  "biometrics": { "...": "same shape as the data-verification example above" },
+  "activity": { "...": "same shape as the data-verification example above" },
+  "request_context": { "...": "same shape as the data-verification example above" },
+  "document": {
+    "status": "verified",
+    "document_type": "passport",
+    "is_expired": false,
+    "first_name": "AMARA",
+    "last_name": "OKAFOR",
+    "date_of_birth": "1997-01-01",
+    "age": 29,
+    "gender": "Female",
+    "nationality": "NGA",
+    "place_of_birth": "LAGOS",
+    "document_number": "A12345678",
+    "expiry_date": "2030-06-15",
+    "issue_date": "2020-06-15",
+    "issuing_authority": "...",
+    "place_of_issue": null,
+    "address": null,
+    "district": null,
+    "division": null,
+    "location": null,
+    "sub_location": null,
+    "serial_number": null,
+    "barcode_number": null,
+    "document_url": "https://.../document.jpg",
+    "document_back_url": null,
+    "face_match": {
+      "attempted": true,
+      "verified": true,
+      "confidence_percentage": 55.0,
+      "threshold_percentage": 35.0,
+      "reason": null,
+      "selfie_url": "https://.../autoshot.jpg",
+      "document_face_url": "https://.../document_face.jpg"
+    }
   }
 }
 ```
 
-### Understanding the Scores
+<details>
+<summary>Every field on <code>document</code></summary>
+
+Most of these are extracted from the document and will be `null` if the document type doesn't carry that field (e.g. `serial_number`/`barcode_number` mainly apply to newer Kenyan ID cards) or OCR couldn't read it:
+
+`status`, `document_type`, `is_expired`, `first_name`, `last_name`, `date_of_birth`, `age`, `gender`, `nationality`, `place_of_birth`, `document_number`, `expiry_date`, `issue_date`, `issuing_authority`, `place_of_issue`, `address`, `district`, `division`, `location`, `sub_location`, `serial_number`, `barcode_number`, `document_url`, `document_back_url`, `face_match` (`attempted`, `verified`, `confidence_percentage`, `threshold_percentage`, `reason`, `selfie_url`, `document_face_url`).
+
+`face_match.reason` is populated when `verified` is `false` or the match was skipped — a user-facing explanation (e.g. "Face similarity is below the match threshold").
 
-- **`match_score`** (distance) — Raw distance between face embeddings. Lower = more similar. Threshold is 0.4 (Facenet default).
-- **`confidence_percentage`** — Human-readable score: how close the match is to perfect. 100% = identical, 0% = at the threshold boundary.
-- **`identity_face_match`** — Only present in data verification (BVN/NIN). Confirms the person doing liveness matches the face on the government database.
-- **`document_verification`** — Only present in document verification. Includes OCR results and document-to-selfie face match.
+</details>
+
+### Field Notes
+
+- **`verification_id`** — matches the `entryId` your `onComplete` callback received when the user submitted.
+- **`status`** — unlike `onComplete`'s `status` (always `"processing"`), this is terminal — but it means **"the check ran to completion,"  not "the person matched."** A face mismatch, low confidence score, or expired document does **not** set `status` to `"failed"` — it's still `"passed"` with the real outcome recorded deeper in the payload. `status: "failed"` is reserved for cases where the check itself couldn't run (service error, no selfie captured, government DB rejection). **Always check `biometrics.face_match.verified` (and `document.is_expired`, for document verification) to know whether the person actually passed — never gate access on `status` alone.**
+- **`biometrics.face_match`** — present for every verification type. `attempted: false` means face matching was skipped (e.g. a document type with no face, like a CAC certificate or NIN slip) — `verified`/`confidence_percentage` are `null` in that case, meaning "not applicable," not a failure. When `attempted: true`, `verified: false` is the real "face did not match" signal.
+- **`biometrics.face_analysis`** — supplementary selfie diagnostics (emotion, blur/quality), `null`/absent if analysis failed or no selfie was captured. `gender` here is sourced from the verified document/government record, not estimated from the selfie itself. There is no age estimate — age (where shown) is calculated from the document's date of birth, not the photo.
+- **`customer_profile`** — only present for data verification, sourced from the government DB response.
+- **`document`** — only present for document verification, sourced from OCR + the document-to-selfie face match. Check `document.is_expired` separately — an expired document can still have `verified: true` on the face match.
+- **`request_context`** — IP/device metadata captured at session start; useful for fraud signals (e.g. `ip.country_matches_document`).
 
 ### Possible Statuses
 
 | Status | Meaning |
 |--------|---------|
-| `passed` | All checks passed — person is verified |
-| `failed` | Face mismatch, expired document, or processing error |
-| `processing` | Still being processed (rare — usually completes in seconds) |
+| `passed` | The check ran to completion — inspect `biometrics.face_match.verified` (and `document.is_expired` for documents) for the real outcome |
+| `failed` | The check itself could not complete — service error, no selfie/document captured, or a government DB rejection. See `failure_reason` for a user-safe description |
 
 ### Verify Signature
 
-**Always verify the webhook signature** to prevent spoofing:
+**Always verify the webhook signature** to prevent spoofing. Two details matter here: the header value is prefixed with `sha256=`, and the signature is computed over the **exact compact-JSON bytes** the server sent (no extra whitespace) — so you must use the **raw request body**, not a re-serialized copy of the parsed object, or the HMAC won't match.
 
 ```javascript
 const crypto = require("crypto");
 
-app.post("/webhook/smartcomply", express.json(), (req, res) => {
-  const signature = req.headers["x-adhere-signature"];
-  const secret = process.env.WEBHOOK_SECRET.replace(/-/g, "");
-  const expected = crypto
-    .createHmac("sha256", secret)
-    .update(JSON.stringify(req.body))
-    .digest("hex");
-
-  const isValid = crypto.timingSafeEqual(
-    Buffer.from(signature, "hex"),
-    Buffer.from(expected, "hex")
-  );
-
-  if (!isValid) return res.status(401).send("Bad signature");
-
-  // Handle the event
-  const { event, data } = req.body;
-
-  if (event === "liveness.completed" && data.is_verified) {
-    // ✓ User is verified — update your database
-    markUserAsVerified(data.entry_id);
+// IMPORTANT: register this route with a raw-body parser (not express.json()),
+// or capture the raw body via a verify callback — re-stringifying req.body
+// after JSON.parse produces different bytes and the signature will never match.
+app.post(
+  "/webhook/smartcomply",
+  express.json({
+    verify: (req, res, buf) => { req.rawBody = buf; },
+  }),
+  (req, res) => {
+    const header = req.headers["x-adhere-signature"] || "";
+    const signature = header.replace(/^sha256=/, "");
+    const secret = process.env.WEBHOOK_SECRET.replace(/-/g, "");
+    const expected = crypto
+      .createHmac("sha256", secret)
+      .update(req.rawBody)
+      .digest("hex");
+
+    const isValid =
+      signature.length === expected.length &&
+      crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));
+
+    if (!isValid) return res.status(401).send("Bad signature");
+
+    const { event, verification_id, status, biometrics, document } = req.body;
+
+    // status === "passed" only means the check ran to completion — it is
+    // NOT the same as "the person is verified". Check the real outcome:
+    const faceMatched = biometrics?.face_match?.attempted
+      ? biometrics.face_match.verified === true
+      : true; // not attempted (e.g. NIN slip, CAC) — nothing to fail here
+    const documentOk = document ? document.is_expired === false : true;
+
+    if (event === "liveness.completed" && status === "passed" && faceMatched && documentOk) {
+      // ✓ User is verified — update your database
+      markUserAsVerified(verification_id);
+    } else if (event === "liveness.completed") {
+      // Check completed but didn't pass verification (face mismatch, expired
+      // document) — or status === "failed" (the check itself couldn't run).
+      // Either way, do not treat this as a verified user.
+      recordVerificationOutcome(verification_id, req.body);
+    }
+
+    res.json({ received: true });
   }
-
-  res.json({ received: true });
-});
+);
 ```
 
 ---
 
 ## Challenge Actions
 
-| Action | What the user does |
+The built-in camera UI (`SmartComplyFlow.open()` and `liveness.startCheck()`) runs a **single passive scan** — the user blinks and turns their head naturally within one continuous window, with no discrete step-by-step prompts. There is no server-side per-action scoring; liveness is confirmed by the scan as a whole (blink + motion detected during the window), not by ticking off each action in `challenge_actions` individually.
+
+The `challenge_actions`/`actions` array you pass to `liveness.create()` or `startCheck()` is sent to the backend as a **descriptive tag only** — it's what shows up in the "Challenge Actions" column on your Adhere dashboard for that verification. It does not change what the widget's camera UI actually asks the user to do.
+
+| Action | Used to describe |
 |--------|-------------------|
-| `BLINK` | Blink both eyes |
-| `TURN_LEFT` | Turn head to the left |
-| `TURN_RIGHT` | Turn head to the right |
-| `TURN_HEAD` | Turn head in any direction |
-| `OPEN_MOUTH` | Open mouth wide |
+| `BLINK` | The user blinked during the scan |
+| `TURN_HEAD` | The user turned their head during the scan |
+| `TURN_LEFT` | Legacy — turned head left (older multi-step challenge design) |
+| `TURN_RIGHT` | Legacy — turned head right (older multi-step challenge design) |
+| `OPEN_MOUTH` | Legacy — opened mouth (older multi-step challenge design) |
 
-Actions must be **UPPERCASE**. We recommend using 3 actions: `["BLINK", "TURN_LEFT", "OPEN_MOUTH"]`.
+Actions must be **UPPERCASE**. Default (and recommended) is `["BLINK", "TURN_HEAD"]` — it's what the widget actually does and what gets tagged accurately.
 
 ---
 
@@ -425,9 +580,11 @@ try {
 
 | Error Code | HTTP | Meaning |
 |------------|------|---------|
-| `INVALID_API_KEY` | 401 | Bad API key or expired session |
+| `INVALID_API_KEY` | 401 | Bad/missing `apiKey`, malformed `Authorization` header, or the branch isn't enabled for onboarding — only ever returned at session creation (`createSession()`), not after |
+| `INVALID_SESSION` | 401 | Session token missing, malformed, expired (30 min), or already revoked — every call *after* `createSession()` uses this, not `INVALID_API_KEY`. Fix: call `createSession()` again; `apiKey`/`clientId` are unchanged and reused as-is |
 | `SDK_CONFIG_NOT_FOUND` | 404 | Invalid `clientId` |
 | `VALIDATION_ERROR` | 400 | Missing or invalid fields |
+| `RETRY_LIMIT_EXCEEDED` | 429 | User exceeded the retry limit for confirmation/liveness attempts — they must restart with a new session |
 | `INSUFFICIENT_BALANCE` | 402 | Top up your wallet |
 
 ---

package/dist/esm/flow/SmartComplyFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SmartComplyFlow.d.ts","sourceRoot":"","sources":["../../../src/flow/SmartComplyFlow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SmartComplyFlow.d.ts","sourceRoot":"","sources":["../../../src/flow/SmartComplyFlow.ts"],"names":[],"mappings":"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"}

package/dist/esm/flow/SmartComplyFlow.js

@@ -1660,13 +1660,28 @@ export class SmartComplyFlow {
         container.appendChild(icon);
         const t = document.createElement("h2");
         t.style.cssText = `color:${this.theme.text};font-size:${TYPE.heading}px;font-weight:700;margin:0;`;
-        t.textContent = "Document Photo Unclear";
+        // "Photo unclear" only fits the blur/lighting reasons below — a wrong
+        // document entirely (mismatch/no-document-detected) isn't a clarity
+        // problem, so give it its own, accurate title instead of implying the
+        // user just needs better lighting.
+        const isWrongDocument = reason === "document_not_detected"
+            || reason === "document_type_mismatch"
+            || reason === "country_mismatch";
+        t.textContent = isWrongDocument ? "That Doesn't Look Right" : "Document Photo Unclear";
         container.appendChild(t);
         const msg = reason === "image_too_blurry" ? "Your document photo is too blurry. Please retake it in good lighting with a steady hand."
             : reason === "image_too_dark" ? "Your document photo is too dark. Please retake it in better lighting."
                 : reason === "image_too_bright" ? "Your document photo has too much glare. Please reduce reflections and retake."
-                    : reason === "document_not_detected" ? "We could not detect a document in the photo. Please ensure the full ID is visible."
-                        : "We could not read your document clearly. Please retake the photo in good lighting with no glare.";
+                    : reason === "document_not_detected" ? "We could not detect a document in the photo. Please make sure you're photographing the actual ID document, with the full document visible."
+                        : reason === "document_type_mismatch" ? "This document doesn't match the ID type you selected. Please upload the correct document, or go back and choose the matching type."
+                            : reason === "country_mismatch" ? "This document doesn't appear to be from the expected country. Please check you've selected the right country and document."
+                                // Any other reason: if it already reads like a real sentence (starts
+                                // capitalized, has spaces — matches the backend's own
+                                // _safe_failure_reason heuristic for "already user-facing"), show it
+                                // as-is instead of masking a specific, accurate reason behind a
+                                // generic "bad lighting" message that may not describe what's wrong.
+                                : reason && /^[A-Z]/.test(reason) && reason.includes(" ") ? reason
+                                    : "We could not read your document clearly. Please retake the photo in good lighting with no glare.";
         const d = document.createElement("p");
         d.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.6;`;
         d.textContent = msg;