verant_id_cloud_scan 1.4.5-beta.10 → 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) => {
@@ -264,9 +278,26 @@ export const checkFaceComparisonFeatureLicense = async (clientId) => {
   }
 }
 
-export const checkLicense = async (clientId, macAddress) => {
+// Pass exactly one of macAddress / serialNumber. The license server rejects
+// requests that supply both or neither; we also fail fast here so callers
+// don't have to wait for a 400 to learn they passed a bad identifier.
+export const checkLicense = async (clientId, identifier = {}) => {
+  if (identifier === null || typeof identifier !== "object") {
+    throw new TypeError(
+      `checkLicense: second argument must be an object like { macAddress } or { serialNumber }, got ${typeof identifier}`,
+    );
+  }
+  const { macAddress, serialNumber } = identifier;
+  if (Boolean(macAddress) === Boolean(serialNumber)) {
+    throw new Error(
+      "checkLicense: pass exactly one of macAddress / serialNumber",
+    );
+  }
+
   const url = getLicenseServerAddress() + "/check_license";
-  const data = { client_id: clientId, mac_address: macAddress };
+  const data = { client_id: clientId };
+  if (macAddress) data.mac_address = macAddress;
+  if (serialNumber) data.serial_number = serialNumber;
 
   try {
     const response = await fetch(url, {
@@ -346,48 +377,148 @@ export const getBarcodeLicenseKey = async () => {
   }
 };
 
-// Helper function for making POST requests to the scanner API
-const postToScannerApi = async (
+/**
+ * Build the /securelink URL for the given scanner address.
+ *
+ * Mirrors the SDK's historical behaviour: if the caller didn't include a
+ * scheme, default to http://. The scheme test is case-insensitive per
+ * RFC 3986 (VNT-1522) — `HTTP://`, `HTTPS://`, and mixed-case forms are
+ * recognised so the SDK doesn't double-prefix them with another `http://`.
+ */
+export const buildSecurelinkUrl = (scannerAddress) => {
+  const hasScheme = /^https?:\/\//i.test(scannerAddress);
+  const withScheme = hasScheme ? scannerAddress : `http://${scannerAddress}`;
+  return `${withScheme.replace(/\/+$/, "")}/securelink`;
+};
+
+/**
+ * Lower-level POST that returns a structured result instead of throwing.
+ * Used by `checkScannerPresentDetailed` (VNT-1522) so the caller can
+ * distinguish network failures, HTTP errors, parse failures, and scanner
+ * application-layer errors. Existing callers go through `postToScannerApi`
+ * which preserves the throw-on-error contract.
+ *
+ * Supports an external `AbortSignal` so host apps can cancel an in-flight
+ * probe on retry / unmount without waiting for the internal timeout.
+ *
+ * @param {string} scannerAddress
+ * @param {object} commandObj
+ * @param {number} [timeout=10000] timeout in ms before the internal AbortController aborts
+ * @param {AbortSignal} [externalSignal] optional external signal; when aborted, the request is cancelled
+ * @returns {Promise<{
+ *   threw: boolean,
+ *   error?: Error,
+ *   ok?: boolean,
+ *   status?: number,
+ *   statusText?: string,
+ *   body?: unknown,
+ *   attemptedUrl: string,
+ * }>}
+ */
+const postToScannerApiDetailed = async (
   scannerAddress,
   commandObj,
-  timeout = 10000
+  timeout = 10000,
+  externalSignal,
 ) => {
-  // Ensure the scanner address has a protocol (http:// or https://)
-  let formattedAddress = scannerAddress;
-  if (!scannerAddress.startsWith('http://') && !scannerAddress.startsWith('https://')) {
-    formattedAddress = `http://${scannerAddress}`;
-  }
-
-  // Remove trailing slash to prevent double slashes in URL
-  formattedAddress = formattedAddress.replace(/\/+$/, '');
-
-  let apiAddress = `${formattedAddress}/securelink`;
+  const attemptedUrl = buildSecurelinkUrl(scannerAddress);
 
   const controller = new AbortController();
-  const signal = controller.signal;
-
-  const fetchTimeout = setTimeout(() => {
-    controller.abort();
-  }, timeout);
+  const fetchTimeout = setTimeout(() => controller.abort(), timeout);
+
+  // Forward an external abort signal to our controller so the host app's
+  // cancellation (retry, unmount) propagates to the in-flight fetch.
+  let externalAbortHandler;
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort();
+    } else {
+      externalAbortHandler = () => controller.abort();
+      externalSignal.addEventListener("abort", externalAbortHandler, { once: true });
+    }
+  }
 
   try {
-    const response = await fetch(apiAddress, {
+    const response = await fetch(attemptedUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(commandObj),
-      signal: signal,
+      signal: controller.signal,
     });
 
-    clearTimeout(fetchTimeout);
+    // Read the body once as text, then try to JSON-parse — keeps a malformed
+    // body from making us discard otherwise-useful status info.
+    let body = null;
+    try {
+      const text = await response.text();
+      if (text) {
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = text; // not JSON, but still meaningful for diagnostics
+        }
+      }
+    } catch {
+      // body read failed — leave body=null, caller can decide
+    }
 
-    if (!response.ok) throw new Error(response.statusText);
-    return response.json();
+    return {
+      threw: false,
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      body,
+      attemptedUrl,
+    };
   } catch (error) {
-    if (error.name === "AbortError") {
+    return { threw: true, error, attemptedUrl };
+  } finally {
+    clearTimeout(fetchTimeout);
+    if (externalSignal && externalAbortHandler) {
+      externalSignal.removeEventListener("abort", externalAbortHandler);
+    }
+  }
+};
+
+// Helper function for making POST requests to the scanner API. Thin wrapper
+// around `postToScannerApiDetailed` that preserves the historical contract
+// (throws on timeout / network / non-2xx; returns parsed JSON on success).
+const postToScannerApi = async (
+  scannerAddress,
+  commandObj,
+  timeout = 10000
+) => {
+  const result = await postToScannerApiDetailed(
+    scannerAddress,
+    commandObj,
+    timeout,
+  );
+
+  if (result.threw) {
+    if (result.error?.name === "AbortError") {
       throw new Error("Request timed out");
     }
-    throw error;
+    throw result.error;
+  }
+
+  if (!result.ok) {
+    throw new Error(result.statusText || `HTTP ${result.status}`);
+  }
+
+  // Match the original `response.json()` contract: throw if the 2xx body
+  // wasn't a parseable JSON object. The detailed wrapper deliberately
+  // preserves non-JSON bodies as strings (or `null` for empty) so error
+  // surfaces like `checkScannerPresentDetailed` can use them — but every
+  // existing caller of `postToScannerApi` (`getNetworkInfo`,
+  // `establishConnection`, `getParams`, `resetParams`, `setParameters`,
+  // `scanDocument`, …) reads object properties off the return value, so
+  // returning a string or null here would silently produce `undefined`
+  // downstream instead of failing loudly.
+  if (result.body === null || typeof result.body !== "object") {
+    throw new SyntaxError("Scanner response was not a JSON object");
   }
+
+  return result.body;
 };
 
 export const getNetworkInfo = (scannerAddress, commandObj) =>
@@ -414,42 +545,174 @@ export const stopScanning = (scannerAddress, commandObj) =>
 export const closeConnection = (scannerAddress, commandObj) =>
   postToScannerApi(scannerAddress, commandObj);
 
-// Check if scanner is present by attempting to connect and disconnect
-export const checkScannerPresent = async (scannerAddress) => {
-  try {
-    // Generate a unique message ID for this check
-    const messageId = new Date().toISOString();
-
-    // Attempt to establish connection
-    const connectCommand = {
-      Command: "Connect",
-      MessageId: messageId,
-      Exclusive: "false", // Use non-exclusive mode for just checking
-      IdleTimeout: "5",
+/**
+ * Classify a thrown fetch error into one of the documented codes (VNT-1522).
+ *
+ * `externallyAborted` distinguishes a host-app cancellation (retry, unmount)
+ * from an internal timeout — both surface as `AbortError` from fetch, but
+ * callers branching on `code` for UI copy (e.g. "scanner timed out") should
+ * not see the timeout label when the user themselves cancelled.
+ *
+ * @param {unknown} error
+ * @param {string} attemptedUrl
+ * @param {boolean} [externallyAborted=false]
+ * @returns {{ code: string, name: string, message: string, attemptedUrl: string }}
+ */
+const classifyFetchError = (error, attemptedUrl, externallyAborted = false) => {
+  if (error?.name === "AbortError") {
+    return {
+      code: externallyAborted ? "ABORTED" : "TIMEOUT",
+      name: "AbortError",
+      message: externallyAborted ? "Request aborted" : "Request timed out",
+      attemptedUrl,
     };
+  }
+  if (error instanceof TypeError) {
+    // Browser fetch surfaces network failures (DNS, connection refused,
+    // mixed-content blocks, CORS preflight rejection) as `TypeError`.
+    return {
+      code: "NETWORK_ERROR",
+      name: "TypeError",
+      message: error.message || "Network error",
+      attemptedUrl,
+    };
+  }
+  return {
+    code: "NETWORK_ERROR",
+    name: error?.name || "Unknown",
+    message: error?.message || String(error),
+    attemptedUrl,
+  };
+};
 
-    const connectResponse = await postToScannerApi(scannerAddress, connectCommand, 5000);
+/**
+ * Structured version of `checkScannerPresent` (VNT-1522).
+ *
+ * Returns `{ ok: true }` on success or `{ ok: false, error }` with a tagged
+ * `error.code` so host apps can distinguish:
+ *  - `TIMEOUT` — internal 5s timeout fired
+ *  - `ABORTED` — host app cancelled via the external `AbortSignal`
+ *  - `NETWORK_ERROR` — fetch threw (DNS, refused, mixed content, CORS, etc.)
+ *  - `HTTP_ERROR` — server replied non-2xx
+ *  - `INVALID_RESPONSE` — 2xx but the body wasn't JSON
+ *  - `SCANNER_ERROR` — 2xx JSON but no `SessionId` (the scanner returned
+ *    an application-layer error in the body, e.g. an HTTPS-only scanner
+ *    rejecting an HTTP probe with `{HttpRC:"403", ExtInformation:"..."}`)
+ *
+ * The error object also carries `attemptedUrl`, `status` (when a response
+ * was received), and the raw `scannerResponse` body for SCANNER_ERROR so
+ * callers can surface vendor-specific fields like `ExtInformation`.
+ *
+ * @param {string} scannerAddress
+ * @param {{ signal?: AbortSignal }} [options]
+ */
+export const checkScannerPresentDetailed = async (
+  scannerAddress,
+  options = {},
+) => {
+  const { signal } = options;
+  const attemptedUrl = buildSecurelinkUrl(scannerAddress);
+
+  const connectCommand = {
+    Command: "Connect",
+    MessageId: new Date().toISOString(),
+    Exclusive: "false", // non-exclusive — we're only probing
+    IdleTimeout: "5",
+  };
 
-    // If connection failed or no session ID, scanner not present
-    if (!connectResponse || !connectResponse.SessionId) {
-      return false;
-    }
+  const probe = await postToScannerApiDetailed(
+    scannerAddress,
+    connectCommand,
+    5000,
+    signal,
+  );
 
-    // Got a session ID, now disconnect
-    const disconnectCommand = {
-      Command: "Disconnect",
-      MessageId: new Date().toISOString(),
-      SessionId: connectResponse.SessionId,
+  if (probe.threw) {
+    return {
+      ok: false,
+      error: classifyFetchError(
+        probe.error,
+        attemptedUrl,
+        Boolean(signal?.aborted),
+      ),
     };
+  }
 
-    await postToScannerApi(scannerAddress, disconnectCommand, 5000);
+  if (!probe.ok) {
+    return {
+      ok: false,
+      error: {
+        code: "HTTP_ERROR",
+        name: "HTTPError",
+        message: probe.statusText || `HTTP ${probe.status}`,
+        status: probe.status,
+        attemptedUrl,
+      },
+    };
+  }
 
-    // Successfully connected and disconnected
-    return true;
-  } catch (error) {
-    // Any error means scanner is not reachable
-    return false;
+  if (!probe.body || typeof probe.body !== "object") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_RESPONSE",
+        name: "InvalidResponse",
+        message: "Scanner returned a non-JSON or empty body",
+        status: probe.status,
+        attemptedUrl,
+      },
+    };
+  }
+
+  if (!probe.body.SessionId) {
+    // App-layer scanner error — common when an HTTPS-only scanner is hit
+    // over HTTP. The body usually contains vendor-specific fields like
+    // `ExtInformation` ("Scanner not configured for HTTP") that we forward
+    // so callers can present an actionable message.
+    return {
+      ok: false,
+      error: {
+        code: "SCANNER_ERROR",
+        name: "ScannerError",
+        message:
+          probe.body.ExtInformation ||
+          probe.body.ErrorInformation ||
+          "Scanner returned no SessionId",
+        status:
+          typeof probe.body.HttpRC === "string"
+            ? parseInt(probe.body.HttpRC, 10) || probe.status
+            : probe.status,
+        attemptedUrl,
+        scannerResponse: probe.body,
+      },
+    };
   }
+
+  // Got a SessionId — clean up by disconnecting. We don't surface a
+  // disconnect failure: from the host app's perspective the scanner IS
+  // present and the leaked session will time out server-side per the
+  // scanner's IdleTimeout.
+  const disconnectCommand = {
+    Command: "Disconnect",
+    MessageId: new Date().toISOString(),
+    SessionId: probe.body.SessionId,
+  };
+  await postToScannerApiDetailed(
+    scannerAddress,
+    disconnectCommand,
+    5000,
+    signal,
+  );
+
+  return { ok: true };
+};
+
+// Boolean form of scanner presence check. Thin wrapper around
+// `checkScannerPresentDetailed` (VNT-1522) — preserved for existing
+// callers; new code should prefer the detailed version.
+export const checkScannerPresent = async (scannerAddress) => {
+  const result = await checkScannerPresentDetailed(scannerAddress);
+  return result.ok;
 };
 
 /**