verant_id_cloud_scan 1.4.5-beta.10 → 1.4.5-beta.11

package/Api.js

@@ -264,9 +264,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 +363,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 +531,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,
+  };
+};
+
+/**
+ * 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",
+  };
 
-    const connectResponse = await postToScannerApi(scannerAddress, connectCommand, 5000);
+  const probe = await postToScannerApiDetailed(
+    scannerAddress,
+    connectCommand,
+    5000,
+    signal,
+  );
 
-    // If connection failed or no session ID, scanner not present
-    if (!connectResponse || !connectResponse.SessionId) {
-      return false;
-    }
+  if (probe.threw) {
+    return {
+      ok: false,
+      error: classifyFetchError(
+        probe.error,
+        attemptedUrl,
+        Boolean(signal?.aborted),
+      ),
+    };
+  }
 
-    // Got a session ID, now disconnect
-    const disconnectCommand = {
-      Command: "Disconnect",
-      MessageId: new Date().toISOString(),
-      SessionId: connectResponse.SessionId,
+  if (!probe.ok) {
+    return {
+      ok: false,
+      error: {
+        code: "HTTP_ERROR",
+        name: "HTTPError",
+        message: probe.statusText || `HTTP ${probe.status}`,
+        status: probe.status,
+        attemptedUrl,
+      },
     };
+  }
 
-    await postToScannerApi(scannerAddress, disconnectCommand, 5000);
+  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,
+      },
+    };
+  }
 
-    // Successfully connected and disconnected
-    return true;
-  } catch (error) {
-    // Any error means scanner is not reachable
-    return false;
+  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;
 };
 
 /**

package/Api.test.js

@@ -0,0 +1,338 @@
+/**
+ * Tests for the structured scanner-presence API (VNT-1522).
+ *
+ * Uses node:test (built-in, no extra deps) — run with `npm test`.
+ * `globalThis.fetch` is stubbed per test so we can simulate timeouts,
+ * network failures, HTTP errors, and scanner-layer body errors without
+ * needing a real local scanner.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  checkScannerPresentDetailed,
+  buildSecurelinkUrl,
+  getNetworkInfo,
+} from "./Api.js";
+
+let originalFetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+/** Build a Response-like object the production code will treat as a real Response. */
+function jsonResponse(body, init = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+    ...init,
+  });
+}
+
+describe("buildSecurelinkUrl — case-insensitive scheme detection (VNT-1522)", () => {
+  it("prepends http:// when no scheme is given", () => {
+    assert.equal(
+      buildSecurelinkUrl("192.168.1.50"),
+      "http://192.168.1.50/securelink",
+    );
+  });
+
+  it("preserves a lowercase https:// scheme", () => {
+    assert.equal(
+      buildSecurelinkUrl("https://192.168.1.50"),
+      "https://192.168.1.50/securelink",
+    );
+  });
+
+  it("preserves a lowercase http:// scheme", () => {
+    assert.equal(
+      buildSecurelinkUrl("http://192.168.1.50"),
+      "http://192.168.1.50/securelink",
+    );
+  });
+
+  it("preserves an UPPERCASE HTTPS:// scheme and does not double-prefix", () => {
+    // Previously this regressed to `http://HTTPS://...` because the SDK's
+    // `startsWith("https://")` check was case-sensitive.
+    assert.equal(
+      buildSecurelinkUrl("HTTPS://192.168.1.50"),
+      "HTTPS://192.168.1.50/securelink",
+    );
+  });
+
+  it("preserves a mixed-case Https:// scheme", () => {
+    assert.equal(
+      buildSecurelinkUrl("Https://192.168.1.50"),
+      "Https://192.168.1.50/securelink",
+    );
+  });
+
+  it("strips trailing slashes so /securelink is appended cleanly", () => {
+    assert.equal(
+      buildSecurelinkUrl("http://192.168.1.50/"),
+      "http://192.168.1.50/securelink",
+    );
+    assert.equal(
+      buildSecurelinkUrl("http://192.168.1.50///"),
+      "http://192.168.1.50/securelink",
+    );
+  });
+});
+
+describe("checkScannerPresentDetailed — happy path", () => {
+  it("returns ok=true when Connect responds with a SessionId", async () => {
+    let connectCalled = false;
+    let disconnectCalled = false;
+
+    globalThis.fetch = async (_url, init) => {
+      const body = JSON.parse(init.body);
+      if (body.Command === "Connect") {
+        connectCalled = true;
+        return jsonResponse({ SessionId: "abc-123" });
+      }
+      if (body.Command === "Disconnect") {
+        disconnectCalled = true;
+        return jsonResponse({});
+      }
+      throw new Error(`Unexpected command: ${body.Command}`);
+    };
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.deepEqual(result, { ok: true });
+    assert.equal(connectCalled, true, "Connect should have been called");
+    assert.equal(disconnectCalled, true, "Disconnect should have been called");
+  });
+
+  it("still returns ok=true when Disconnect fails (scanner is present regardless)", async () => {
+    let attempt = 0;
+    globalThis.fetch = async (_url, init) => {
+      attempt += 1;
+      const body = JSON.parse(init.body);
+      if (body.Command === "Connect") {
+        return jsonResponse({ SessionId: "abc-123" });
+      }
+      // Disconnect call fails — should NOT degrade the ok=true return,
+      // since the host app's question ("is the scanner present?") has
+      // already been answered yes.
+      throw new TypeError("network error on disconnect");
+    };
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.equal(result.ok, true);
+    assert.equal(attempt, 2, "both Connect and Disconnect should be attempted");
+  });
+});
+
+describe("checkScannerPresentDetailed — error codes", () => {
+  it("returns SCANNER_ERROR when 200 OK has no SessionId in body", async () => {
+    // Becca's case: HTTPS-only scanner being hit over HTTP returns 200 OK
+    // with a body like `{"HttpRC":"403", "ExtInformation":"Scanner not
+    // configured for HTTP"}`. The SDK's old boolean form collapsed this
+    // to `false`; the detailed form surfaces the vendor message.
+    globalThis.fetch = async () =>
+      jsonResponse({
+        HttpRC: "403",
+        Result: "12",
+        ErrorInformation: "Device specific error",
+        ExtInformation: "Scanner not configured for HTTP",
+      });
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "SCANNER_ERROR");
+    assert.equal(result.error.message, "Scanner not configured for HTTP");
+    assert.equal(result.error.status, 403);
+    assert.equal(result.error.attemptedUrl, "http://192.168.1.50/securelink");
+    assert.equal(
+      result.error.scannerResponse.ExtInformation,
+      "Scanner not configured for HTTP",
+    );
+  });
+
+  it("returns HTTP_ERROR when the server replies with a non-2xx status", async () => {
+    globalThis.fetch = async () =>
+      new Response("Forbidden", { status: 403, statusText: "Forbidden" });
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "HTTP_ERROR");
+    assert.equal(result.error.status, 403);
+    assert.equal(result.error.message, "Forbidden");
+    assert.equal(result.error.attemptedUrl, "http://192.168.1.50/securelink");
+  });
+
+  it("returns NETWORK_ERROR when fetch throws a TypeError (DNS, CORS, mixed content, etc.)", async () => {
+    globalThis.fetch = async () => {
+      throw new TypeError("Failed to fetch");
+    };
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "NETWORK_ERROR");
+    assert.equal(result.error.name, "TypeError");
+    assert.match(result.error.message, /Failed to fetch/);
+    assert.equal(result.error.attemptedUrl, "http://192.168.1.50/securelink");
+  });
+
+  it("returns ABORTED when an already-aborted external signal is passed", async () => {
+    // Real browser fetch rejects synchronously when given an already-
+    // aborted signal — mirror that contract in the mock so the test
+    // doesn't deadlock if the listener is attached post-abort.
+    globalThis.fetch = async (_url, init) => {
+      if (init.signal?.aborted) {
+        const err = new Error("aborted");
+        err.name = "AbortError";
+        throw err;
+      }
+      return new Promise((_resolve, reject) => {
+        init.signal?.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    };
+
+    const controller = new AbortController();
+    controller.abort();
+    const result = await checkScannerPresentDetailed("192.168.1.50", {
+      signal: controller.signal,
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "ABORTED");
+    assert.equal(result.error.name, "AbortError");
+  });
+
+  it("returns TIMEOUT when fetch aborts and no external signal was supplied", async () => {
+    // Simulates the internal 5s AbortController firing — fetch throws
+    // AbortError, no external signal was passed in, so classification
+    // falls through to TIMEOUT rather than ABORTED.
+    globalThis.fetch = async () => {
+      const err = new Error("aborted");
+      err.name = "AbortError";
+      throw err;
+    };
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "TIMEOUT");
+    assert.equal(result.error.name, "AbortError");
+  });
+
+  it("returns INVALID_RESPONSE when the body isn't JSON", async () => {
+    globalThis.fetch = async () =>
+      new Response("<html>not json</html>", {
+        status: 200,
+        headers: { "Content-Type": "text/html" },
+      });
+
+    const result = await checkScannerPresentDetailed("192.168.1.50");
+    assert.equal(result.ok, false);
+    // The body parses as a non-object string, so the `typeof !== "object"`
+    // branch fires before the SessionId check.
+    assert.equal(result.error.code, "INVALID_RESPONSE");
+    assert.equal(result.error.status, 200);
+    assert.equal(result.error.attemptedUrl, "http://192.168.1.50/securelink");
+  });
+});
+
+describe("checkScannerPresentDetailed — AbortSignal support", () => {
+  it("propagates an external abort to the in-flight fetch", async () => {
+    let fetchSignal = null;
+    globalThis.fetch = async (_url, init) => {
+      fetchSignal = init.signal;
+      if (init.signal?.aborted) {
+        const err = new Error("aborted");
+        err.name = "AbortError";
+        throw err;
+      }
+      return new Promise((_resolve, reject) => {
+        init.signal.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    };
+
+    const controller = new AbortController();
+    const resultPromise = checkScannerPresentDetailed("192.168.1.50", {
+      signal: controller.signal,
+    });
+
+    // Give the fetch microtask a beat to start, then abort externally.
+    await Promise.resolve();
+    controller.abort();
+
+    const result = await resultPromise;
+    assert.equal(result.ok, false);
+    assert.equal(result.error.code, "ABORTED");
+    assert.equal(
+      fetchSignal.aborted,
+      true,
+      "the fetch's signal should have been aborted",
+    );
+  });
+});
+
+describe("postToScannerApi (throw-on-error wrapper) — JSON contract (VNT-1522)", () => {
+  // Tested via `getNetworkInfo`, the simplest of the thin wrappers around
+  // `postToScannerApi`. Behaviour must match here for every wrapper —
+  // they're identical one-liners.
+
+  it("returns the parsed object on a 2xx JSON response", async () => {
+    globalThis.fetch = async () => jsonResponse({ NetworkInfo: { ip: "x" } });
+    const result = await getNetworkInfo("192.168.1.50", { Command: "GetNetworkInfo" });
+    assert.deepEqual(result, { NetworkInfo: { ip: "x" } });
+  });
+
+  it("throws on a 2xx response with a non-JSON body (preserves the response.json() contract)", async () => {
+    // Pre-VNT-1522 behaviour: the wrapper called `response.json()` which
+    // threw `SyntaxError` on invalid JSON. The detailed-form refactor
+    // accepted non-JSON bodies (kept them as strings for diagnostics);
+    // the wrapper has to re-throw so existing callers — which all read
+    // object properties off the return value — fail loudly instead of
+    // silently receiving a string.
+    globalThis.fetch = async () =>
+      new Response("not json", {
+        status: 200,
+        headers: { "Content-Type": "text/plain" },
+      });
+
+    await assert.rejects(
+      getNetworkInfo("192.168.1.50", { Command: "GetNetworkInfo" }),
+      /not a JSON object/,
+    );
+  });
+
+  it("throws on a 2xx response with an empty body", async () => {
+    globalThis.fetch = async () =>
+      new Response("", {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+
+    await assert.rejects(
+      getNetworkInfo("192.168.1.50", { Command: "GetNetworkInfo" }),
+      /not a JSON object/,
+    );
+  });
+
+  it("throws on non-2xx HTTP responses (unchanged)", async () => {
+    globalThis.fetch = async () =>
+      new Response("Forbidden", { status: 403, statusText: "Forbidden" });
+
+    await assert.rejects(
+      getNetworkInfo("192.168.1.50", { Command: "GetNetworkInfo" }),
+      /Forbidden/,
+    );
+  });
+});

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.11] - 2026-05-21
+
+### Added
+- **`scannerPresentDetailed(scannerAddress, options?)`** (VNT-1522). Returns
+  a structured `{ ok, error? }` result so host apps can distinguish
+  timeouts, host-app cancellations, network errors, HTTP-level errors,
+  application-layer scanner errors (e.g. HTTPS-only scanner refusing HTTP
+  with `HttpRC:403` / `ExtInformation` in the body), and missing-
+  `SessionId` responses. The `error` object carries `code` (`TIMEOUT` |
+  `ABORTED` | `NETWORK_ERROR` | `HTTP_ERROR` | `INVALID_RESPONSE` |
+  `SCANNER_ERROR`), `name`, `message`, `status`, `attemptedUrl`, and the
+  raw `scannerResponse` body for the `SCANNER_ERROR` case so callers can
+  surface vendor-specific text. `ABORTED` is distinct from `TIMEOUT` so
+  UI copy that branches on "scanner timed out" doesn't mislabel a user-
+  cancelled probe.
+- Optional `signal: AbortSignal` parameter on `scannerPresentDetailed` so
+  host apps can cancel an in-flight probe on retry / unmount instead of
+  waiting for the internal 5s timeout.
+- `Api.test.js` — first test suite in this repo, using Node's built-in
+  `node:test` runner (zero new dependencies). Covers timeout, HTTP 4xx,
+  network error, scanner-error-in-body, invalid response, AbortSignal
+  propagation, happy path, and case-insensitive scheme detection.
+
+### Fixed
+- Case-insensitive scheme detection in `postToScannerApi` URL builder
+  (VNT-1522). Previously `HTTPS://192.168.1.50` was treated as having no
+  scheme and double-prefixed to `http://HTTPS://...`; now matches `/^https?:\/\//i`
+  per RFC 3986.
+
+### Changed
+- `scannerPresent` (boolean) now delegates to `scannerPresentDetailed`.
+  One small behaviour difference: a failed Disconnect after a successful
+  Connect no longer flips the return to `false`. From the host app's
+  perspective the scanner IS present at that point, and the leaked
+  session times out server-side per the scanner's `IdleTimeout`. The
+  pre-refactor behaviour was a side-effect of the older try/catch wrap;
+  treating the disconnect as best-effort is the intended contract.
+- `package.json` `test` script now runs Node's built-in `node --test`
+  runner instead of stubbing an error.
+
 ## [1.4.5-beta.10] - 2026-05-11
 
 ### Fixed

package/CloudScan.js

@@ -13,6 +13,7 @@ import {
   getBarcodeLicenseKey,
   scannerChain,
   scannerPresent,
+  scannerPresentDetailed,
 } from "./ScannerApi.js";
 import { VerificationModal } from "./VerificationModal.js";
 import { checkAutoDmvEnabled, setEnvironment, createVerificationSession } from "./Api.js";
@@ -42,7 +43,7 @@ export const checkFaceCompareFeature = async (clientId) => {
   return await checkFaceComparisonFeatureLicense(clientId);
 }
 
-export { scannerPresent, setEnvironment };
+export { scannerPresent, scannerPresentDetailed, setEnvironment };
 
 export async function readImageBarcode(imageFile, clientId = null, scannerType = 'Upload') {
   let returnObj = {

package/LocalScannerApi.js

@@ -57,37 +57,49 @@ export async function localScannerChain(ambirApiAddress, clientId) {
     }
 
     // //2-3 Get serial number and Check the license
-    // try {
-    //   //2 check scanner serial
-    //   const scannerSerialNumberResult = await LocalAPI.getScannerSerialNumber();
-    //   if (!scannerSerialNumberResult) {
-    //     clearImageAndCloseScannerConnection(); // Even if scanning has errors, always attempt to close the connection
-    //     return {
-    //       success: false,
-    //       errorMessages,
-    //     };
-    //   }
-
-    //   //3 check license
-    //   const isValid = await checkLicense(clientId, scannerSerialNumberResult);
-
-    //   if (isValid) {
-    //     // continue
-    //   } else {
-    //     buildError("Error: License error!");
-    //     return {
-    //       success: false,
-    //       errorMessages,
-    //     };
-    //   }
-    // } catch (error) {
-    //   buildError(" Error: " + error.message);
-    //   console.error("An error occurred:", error.message);
-    //   return {
-    //     success: false,
-    //     errorMessages,
-    //   };
-    // }
+    try {
+      //2 check scanner serial
+      const scannerSerialNumberResult = await getLocalScannerSerialNumber();
+      // Intentionally NOT logging the serial — it's a stable device
+      // identifier and shouldn't appear in customer-facing browser logs.
+      // Use the network tab if you need to inspect it during dev.
+      if (!scannerSerialNumberResult) {
+        console.log("No serial retrieved, closing connection");
+        await clearImageAndCloseScannerConnection(); // Even if scanning has errors, always attempt to close the connection
+        return {
+          success: false,
+          errorMessages,
+        };
+      }
+
+      const isValid = await checkLicense(clientId, { serialNumber: scannerSerialNumberResult });
+
+      if (isValid) {
+        // continue
+      } else {
+        // `checkLicense` collapses both "denied" and "request failed"
+        // (network blip, 5xx, etc.) into a bare `false`, so this branch
+        // is genuinely ambiguous. Copy reflects that until the SDK
+        // surfaces a structured result (VNT-1522 follow-up).
+        buildError(
+          "License check failed or this scanner is not licensed. " +
+            "Try again, or contact Verant ID if this persists."
+        );
+        await clearImageAndCloseScannerConnection();
+        return {
+          success: false,
+          errorMessages,
+        };
+      }
+    } catch (error) {
+      buildError("Serial/license check error: " + (error?.message ?? error));
+      console.error("Serial/license check error:", error);
+      await clearImageAndCloseScannerConnection();
+      return {
+        success: false,
+        errorMessages,
+      };
+    }
   }
 
   console.log("about to check scanner availability");
@@ -344,7 +356,10 @@ async function getLocalScannerSerialNumber() {
     return false;
   }
 
-  return responseData;
+  // Ambir's /getserialnumber response shape isn't pinned down yet — handle both
+  // a bare string and a structured payload so we don't send a Hash on the wire.
+  if (typeof responseData === "string") return responseData;
+  return responseData.SerialNumber || responseData.serialNumber || false;
 }
 
 // step 3 - check if scanner is licensed with verant

package/ScannerApi.js

@@ -1,6 +1,14 @@
 import * as API from "./Api.js";
 import { getProfile } from "./ScannerProfiles.js";
 
+// Maps a scanner-profile field name to the corresponding license-server
+// request key. Static — defined at module scope so it's not re-allocated
+// on every scannerChain() call.
+const SCANNER_FIELD_TO_LICENSE_KEY = {
+  ScannerMAC: "macAddress",
+  ScannerSerial: "serialNumber",
+};
+
 let errorMessages = [];
 let selectedScannerAddress = "";
 
@@ -46,6 +54,19 @@ export async function scannerPresent(scannerAddress) {
   return await API.checkScannerPresent(scannerAddress);
 }
 
+/**
+ * Detailed scanner-presence check (VNT-1522). Returns a structured result
+ * so callers can distinguish timeouts, network errors, HTTP errors,
+ * application-layer scanner errors (e.g. HTTPS-only scanner refusing HTTP),
+ * and missing-SessionId responses without inspecting the SDK's internals.
+ *
+ * Supports an optional `AbortSignal` so callers can cancel in-flight
+ * probes on retry / unmount.
+ */
+export async function scannerPresentDetailed(scannerAddress, options) {
+  return await API.checkScannerPresentDetailed(scannerAddress, options);
+}
+
 //This is the top level function that calls the other functions in order
 export async function scannerChain(
   scannerAddress,
@@ -111,10 +132,12 @@ export async function scannerChain(
   const identifierField = profile.licenseIdentifierField;
   const fallbackField = profile.licenseIdentifierFallback;
   let scannerIdentifier = existingParams[identifierField];
+  let usedField = identifierField;
 
   // Fall back to alternate field if primary is missing
   if (!scannerIdentifier && fallbackField) {
     scannerIdentifier = existingParams[fallbackField];
+    usedField = fallbackField;
   }
 
   if (!scannerIdentifier) {
@@ -128,9 +151,19 @@ export async function scannerChain(
     };
   }
 
+  const licenseKey = SCANNER_FIELD_TO_LICENSE_KEY[usedField];
+  if (!licenseKey) {
+    buildError(`Error: Unknown scanner identifier field "${usedField}" — cannot check license`);
+    await closeScannerConnection(currentSessionId);
+    return {
+      success: false,
+      errorMessages,
+    };
+  }
+
   // Check the license
   try {
-    const isValid = await API.checkLicense(clientId, scannerIdentifier);
+    const isValid = await API.checkLicense(clientId, { [licenseKey]: scannerIdentifier });
 
     if (isValid) {
       // continue

package/index.d.ts

@@ -143,10 +143,91 @@ declare module "verant_id_cloud_scan" {
     disconnect(): void;
     getState(): ConnectionStateValue;
   }
+
+  // Scanner presence — VNT-1522
+  //
+  // `scannerPresent` returns the simple boolean form (legacy); new code
+  // should prefer `scannerPresentDetailed` for richer error info.
+
+  export type ScannerPresentErrorCode =
+    | "TIMEOUT"
+    | "ABORTED"
+    | "NETWORK_ERROR"
+    | "HTTP_ERROR"
+    | "INVALID_RESPONSE"
+    | "SCANNER_ERROR";
+
+  export interface ScannerPresentError {
+    /** SDK-defined tag for branching UX without parsing `message`. */
+    code: ScannerPresentErrorCode;
+    /** Underlying error class name (e.g. "TypeError", "AbortError", "HTTPError"). */
+    name: string;
+    /** Human-readable detail; for `SCANNER_ERROR` this includes vendor-supplied text when present. */
+    message: string;
+    /** HTTP status when a response was received; for `SCANNER_ERROR` may be the scanner-layer `HttpRC` if it was a parseable number. */
+    status?: number;
+    /** The /securelink URL the SDK probed. */
+    attemptedUrl: string;
+    /** For `SCANNER_ERROR`: raw scanner response body (vendor-specific fields like `ExtInformation`, `ErrorInformation`). */
+    scannerResponse?: unknown;
+  }
+
+  export type ScannerPresentResult =
+    | { ok: true }
+    | { ok: false; error: ScannerPresentError };
+
+  export interface ScannerPresentOptions {
+    /** External signal to cancel the probe (retry, unmount). Forwarded into the underlying fetch. */
+    signal?: AbortSignal;
+  }
+
+  /**
+   * Detailed scanner-presence check. Returns a structured result so callers
+   * can distinguish timeouts, network errors, HTTP errors, application-layer
+   * scanner errors (HTTPS-only scanner refusing HTTP, etc.), and missing-
+   * SessionId responses without inspecting the SDK's internals.
+   */
+  export function scannerPresentDetailed(
+    scannerAddress: string,
+    options?: ScannerPresentOptions,
+  ): Promise<ScannerPresentResult>;
 }
 
 export function scannerPresent(scannerAddress: string): Promise<boolean>;
 
+// Same signature as the in-module declaration above; mirrored here so it
+// resolves under both lookup paths (matches `scannerPresent`'s existing
+// outside-the-module placement).
+export type ScannerPresentErrorCode =
+  | "TIMEOUT"
+  | "ABORTED"
+  | "NETWORK_ERROR"
+  | "HTTP_ERROR"
+  | "INVALID_RESPONSE"
+  | "SCANNER_ERROR";
+
+export interface ScannerPresentError {
+  code: ScannerPresentErrorCode;
+  name: string;
+  message: string;
+  status?: number;
+  attemptedUrl: string;
+  scannerResponse?: unknown;
+}
+
+export type ScannerPresentResult =
+  | { ok: true }
+  | { ok: false; error: ScannerPresentError };
+
+export interface ScannerPresentOptions {
+  signal?: AbortSignal;
+}
+
+export function scannerPresentDetailed(
+  scannerAddress: string,
+  options?: ScannerPresentOptions,
+): Promise<ScannerPresentResult>;
+
 /**
  * Explicitly set the API environment.
  * By default, production is used for all hosts (including localhost).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verant_id_cloud_scan",
-  "version": "1.4.5-beta.10",
+  "version": "1.4.5-beta.11",
   "description": "Verant ID Cloud Scan NPM Library",
   "main": "CloudScan.js",
   "types": "index.d.ts",
@@ -8,7 +8,7 @@
     "ws": false
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
   "author": "Verant ID Inc",
   "license": "ISC",