verant_id_cloud_scan 1.4.5-beta.11 → 1.4.5-beta.13

package/Api.js

@@ -1,4 +1,4 @@
-import { compressAndCompareImages } from "./FaceComparison.js";
+import { compressAndCompareImages } from "./FaceApi.js";
 import { formatDateToISO, DATE_FIELDS } from "./DateUtils.js";
 import { FIELD_MAPPING, FIELD_DEFAULTS, getFieldValue } from "./FieldMapping.js";
 import { sanitizeFieldForDmv } from "./FormatUtils.js";
@@ -62,47 +62,61 @@ export function setEnvironment(environment) {
 }
 
 /**
- * Get license server address based on current environment
+ * Per-service host by environment.
+ */
+const HOSTS = {
+  staging: {
+    license: "https://lic-staging.verantid.com/api/v1",
+    dmv: "https://dmv-check-server-staging-fcaab48bec21.herokuapp.com",
+    face: "https://staging.face.verantid.bluerocket.us",
+    mobile: "https://staging.mdl.verantid.bluerocket.us",
+  },
+  production: {
+    license: "https://lic.verantid.com/api/v1",
+    dmv: "https://dmv.verantid.com",
+    face: "https://faceid.verantid.com",
+    mobile: "https://mdl.verantid.bluerocket.us",
+  },
+};
+
+/**
+ * Resolve a service's host for the current environment.
+ * @param {'license' | 'dmv' | 'face' | 'mobile'} service
  * @returns {string}
  */
+function host(service) {
+  return HOSTS[getEnvironment()][service];
+}
+
 function getLicenseServerAddress() {
-  const env = getEnvironment();
-  return env === 'staging'
-    ? "https://lic-staging.verantid.com/api/v1"
-    : "https://lic.verantid.com/api/v1";
+  return host("license");
 }
 
 /**
- * Get DMV server address based on current environment
- * @returns {string}
+ * Still on /api/v1 (SOAP transport), which does NOT carry
+ * the personDigitalImage match. The field already forwards in the driver object,
+ * but the "License Portrait" match indicator will only round-trip once this path
+ * is switched to /api/v2/dmv_check (REST 3.0). That endpoint is request/response
+ * compatible — change the path below — but it must NOT be flipped until VNT-1463
+ * is deployed to these hosts, or all DMV checks will 404.
  */
 function getDmvServerAddress() {
-  const env = getEnvironment();
-  return env === 'staging'
-    ? "https://dmv-check-server-staging-fcaab48bec21.herokuapp.com/api/v1/dmv_check"
-    : "https://dmv.verantid.com/api/v1/dmv_check";
+  return `${host("dmv")}/api/v1/dmv_check`;
 }
 
-/**
- * Get Face Comparison server address based on current environment
- * @returns {string}
- */
 export function getFaceComparisonServerAddress() {
-  const env = getEnvironment();
-  return env === 'staging'
-    ? "https://staging.face.verantid.bluerocket.us/compare_id_and_face"
-    : "https://faceid.verantid.com/compare_id_and_face";
+  return `${host("face")}/compare_id_and_face`;
 }
 
 /**
- * Get Mobile Verification server address based on current environment
- * @returns {string}
+ * License Portrait extraction
  */
+export function getExtractPortraitServerAddress() {
+  return `${host("face")}/extract_portrait`;
+}
+
 function getMobileVerificationServerAddress() {
-  const env = getEnvironment();
-  return env === 'staging'
-    ? "https://staging.mdl.verantid.bluerocket.us"
-    : "https://mdl.verantid.bluerocket.us";
+  return host("mobile");
 }
 
 export const dmvCheck = async (clientId, scannerType, licenseData) => {

package/Api.test.js

@@ -14,7 +14,9 @@ import {
   checkScannerPresentDetailed,
   buildSecurelinkUrl,
   getNetworkInfo,
+  dmvCheck,
 } from "./Api.js";
+import { FIELD_MAPPING, FIELD_LABELS, getFieldValue } from "./FieldMapping.js";
 
 let originalFetch;
 
@@ -336,3 +338,66 @@ describe("postToScannerApi (throw-on-error wrapper) — JSON contract (VNT-1522)
     );
   });
 });
+
+describe("dmvCheck — personDigitalImage passthrough (VNT-1464)", () => {
+  // A base64 data URI that includes '+', '/', and '=' padding, to prove the
+  // value is forwarded byte-for-byte (no sanitization / no re-encoding).
+  const PORTRAIT =
+    "data:image/jpeg;base64,/9j/4AAQSkZJRg+ABAQEAYABgAAD/2wBDAA==";
+
+  it("forwards personDigitalImage into the driver object unchanged", async () => {
+    let sentBody = null;
+    globalThis.fetch = async (_url, init) => {
+      sentBody = JSON.parse(init.body);
+      return jsonResponse({ status: "success", match_status: true });
+    };
+
+    await dmvCheck("client-1", "Upload", {
+      jurisdiction_code: "P6",
+      license_number: "D123",
+      personDigitalImage: PORTRAIT,
+    });
+
+    assert.equal(
+      sentBody.driver.person_digital_image,
+      PORTRAIT,
+      "base64 portrait should pass through byte-for-byte",
+    );
+  });
+
+  it("does not send person_digital_image when it is absent", async () => {
+    let sentBody = null;
+    globalThis.fetch = async (_url, init) => {
+      sentBody = JSON.parse(init.body);
+      return jsonResponse({ status: "success" });
+    };
+
+    await dmvCheck("client-1", "Upload", {
+      jurisdiction_code: "P6",
+      license_number: "D123",
+    });
+
+    assert.equal(
+      Object.prototype.hasOwnProperty.call(sentBody.driver, "person_digital_image"),
+      false,
+      "absent field should not be added to the driver",
+    );
+  });
+});
+
+describe("FieldMapping — person_digital_image (VNT-1464)", () => {
+  it("resolves the value from every supported key variant", () => {
+    for (const key of [
+      "person_digital_image",
+      "personDigitalImage",
+      "PersonDigitalImage",
+    ]) {
+      assert.equal(getFieldValue({ [key]: "IMG" }, "person_digital_image"), "IMG");
+    }
+  });
+
+  it("is registered in FIELD_MAPPING and labeled 'License Portrait'", () => {
+    assert.ok(FIELD_MAPPING.person_digital_image, "should exist in FIELD_MAPPING");
+    assert.equal(FIELD_LABELS.person_digital_image, "License Portrait");
+  });
+});

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.5-beta.13] - 2026-06-26
+
+### Added
+- **`extractPortraitFromLicense(clientId, licenseImage)`** (VNT-1464 / VNT-1470).
+  Extracts the cropped portrait from a license image via the face lambda's
+  dedicated `/extract_portrait` endpoint — sends only the license image, no
+  comparison. Resolves to `{ extractedPortrait, error? }` where
+  `extractedPortrait` is a base64 JPEG data URI or `null` when no face is
+  detected. Exported from `CloudScan.js` and typed in `index.d.ts`.
+- **`getExtractPortraitServerAddress()`** — resolves the `/extract_portrait`
+  endpoint for the current environment.
+- **`person_digital_image` field support** (VNT-1464). Added to `FIELD_MAPPING`
+  (key variants `person_digital_image` / `personDigitalImage` /
+  `PersonDigitalImage`) and `FIELD_LABELS` (`"License Portrait"`). `dmvCheck`
+  forwards it in the driver payload when present; `VerificationModal` renders
+  `"Photo"` for the field on the confirmation step instead of the base64 string.
+
+### Changed
+- Renamed `FaceComparison.js` → `FaceApi.js`; it now houses both the face
+  comparison and portrait-extraction clients. No public API change — the
+  library entry point still exports `startFaceComparison` and
+  `extractPortraitFromLicense`.
+- Centralized per-environment host resolution in `Api.js` behind a single
+  `HOSTS` map and a `host(service)` helper. The address getters now append
+  their path to a per-service host instead of each branching on environment.
+
 ## [1.4.5-beta.11] - 2026-05-21
 
 ### Added

package/CloudScan.js

@@ -5,7 +5,7 @@ import {
 } from "./BarcodeScanner.js";
 import { driverLicenseFields } from "./DriverLicenseFields.js";
 import { localScannerChain, scanBack, scanFrontOnly, getCachedClientId } from "./LocalScannerApi.js";
-import { compressAndCompareImages, compressImage } from "./FaceComparison.js";
+import { compressAndCompareImages, compressImage } from "./FaceApi.js";
 import {
   checkDmvFeatureLicense,
   checkFaceComparisonFeatureLicense,
@@ -39,6 +39,8 @@ export const startFaceComparison = async (clientId, licenseSrc, faceSrc) => {
   return await compressAndCompareImages(clientId, licenseSrc, faceSrc);
 };
 
+export { extractPortraitFromLicense } from "./FaceApi.js";
+
 export const checkFaceCompareFeature = async (clientId) => {
   return await checkFaceComparisonFeatureLicense(clientId);
 }

package/{FaceComparison.js → FaceApi.js}

@@ -1,4 +1,4 @@
-import { getFaceComparisonServerAddress } from "./Api.js";
+import { getFaceComparisonServerAddress, getExtractPortraitServerAddress } from "./Api.js";
 
 
 export async function compressImage(source, maxSize = 2 * 1024 * 1024) {
@@ -98,6 +98,45 @@ export async function compressAndCompareImages(
   return result;
 }
 
+/**
+ * Extracts a portrait from a license image
+ *
+ * @param {string} clientId
+ * @param {string|File|HTMLCanvasElement} licenseInput
+ * @param {number} [maxSize]  max compressed size in bytes (defaults to 2 MB)
+ * @returns {Promise<{ extractedPortrait: string|null, error?: { error: any, details: any } }>}
+ */
+export async function extractPortraitFromLicense(
+  clientId,
+  licenseInput,
+  maxSize = 2 * 1024 * 1024
+) {
+  let licSource = licenseInput;
+  if (typeof licSource === 'string') {
+    licSource = await base64ToCanvas(licSource);
+  }
+  const licenseBase64 = await compressImage(licSource, maxSize);
+
+  const res = await fetch(getExtractPortraitServerAddress(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: clientId,
+      license_front: `data:image/jpeg;base64,${licenseBase64}`,
+    }),
+  });
+
+  const data = await res.json();
+
+  const result = { extractedPortrait: data?.extractedPortrait ?? null };
+
+  if (data?.error || data?.details) {
+    result.error = { error: data?.error, details: data?.details };
+  }
+
+  return result;
+}
+
 async function base64ToCanvas(src) {
   // if it’s missing the data: prefix, add it
   const dataUrl = src.startsWith('data:') ? src : `data:image/jpeg;base64,${src}`;

package/FieldMapping.js

@@ -19,7 +19,8 @@ export const FIELD_MAPPING = {
   state: ['state', 'State', 'MailingJurisdictionCode'],
   postal_code: ['postal_code', 'postalCode', 'PostalCode', 'MailingPostalCode'],
   height: ['OriginalHeight', 'height', 'Height', 'HeightInFT_IN', 'HeightInCM'],
-  weight: ['weight', 'Weight', 'WeightInLBS', 'WeightInKG']
+  weight: ['weight', 'Weight', 'WeightInLBS', 'WeightInKG'],
+  person_digital_image: ['person_digital_image', 'personDigitalImage', 'PersonDigitalImage']
 };
 
 /**
@@ -68,5 +69,6 @@ export const FIELD_LABELS = {
   state: 'State',
   postal_code: 'Postal Code',
   jurisdiction_code: 'Jurisdiction',
-  document_category_code: 'Document Category'
+  document_category_code: 'Document Category',
+  person_digital_image: 'License Portrait'
 };

package/VerificationModal.js

@@ -503,6 +503,10 @@ export class VerificationModal {
       return 'N/A';
     }
 
+    if (fieldName === 'person_digital_image') {
+      return 'Photo';
+    }
+
     let displayValue = String(value).trim();
 
     // Format date fields to MM/DD/YYYY

package/index.d.ts

@@ -19,6 +19,14 @@ declare module "verant_id_cloud_scan" {
     range: string;
   }>;
 
+  export function extractPortraitFromLicense(
+    clientId: string,
+    licenseImage: string | File | HTMLCanvasElement,
+  ): Promise<{
+    extractedPortrait: string | null;
+    error?: { error: any; details: any };
+  }>;
+
   export function readImageBarcode(
     imageFile: File,
     clientId?: string | null,
@@ -80,13 +88,13 @@ declare module "verant_id_cloud_scan" {
   }>;
 
   // Mobile Verification Types
-  export type ConnectionStateValue = 'connecting' | 'open' | 'closed' | 'error';
+  export type ConnectionStateValue = "connecting" | "open" | "closed" | "error";
 
   export const ConnectionState: {
-    readonly CONNECTING: 'connecting';
-    readonly OPEN: 'open';
-    readonly CLOSED: 'closed';
-    readonly ERROR: 'error';
+    readonly CONNECTING: "connecting";
+    readonly OPEN: "open";
+    readonly CLOSED: "closed";
+    readonly ERROR: "error";
   };
 
   export interface VerificationCallbacks {
@@ -127,14 +135,14 @@ declare module "verant_id_cloud_scan" {
    * use `startMobileVerification`.
    */
   export function connectToVerificationSession(
-    options: ConnectToVerificationSessionOptions
+    options: ConnectToVerificationSessionOptions,
   ): Promise<ConnectedSession>;
 
   export function startMobileVerification(
     userId: string,
     clientId: string,
     callbacks?: VerificationCallbacks,
-    mobileVerifyBaseUrl?: string
+    mobileVerifyBaseUrl?: string,
   ): Promise<VerificationSession>;
 
   export class WebSocketClient {
@@ -234,4 +242,4 @@ export function scannerPresentDetailed(
  * Only verify-staging.verantid.com automatically uses staging.
  * @param environment - 'staging' or 'production'
  */
-export function setEnvironment(environment: 'staging' | 'production'): void;
+export function setEnvironment(environment: "staging" | "production"): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verant_id_cloud_scan",
-  "version": "1.4.5-beta.11",
+  "version": "1.4.5-beta.13",
   "description": "Verant ID Cloud Scan NPM Library",
   "main": "CloudScan.js",
   "types": "index.d.ts",