verant_id_cloud_scan 1.4.5-beta.8 → 1.4.5-beta.9

package/Api.js

@@ -94,6 +94,17 @@ export function getFaceComparisonServerAddress() {
     : "https://faceid.verantid.com/compare_id_and_face";
 }
 
+/**
+ * Get Mobile Verification server address based on current environment
+ * @returns {string}
+ */
+function getMobileVerificationServerAddress() {
+  const env = getEnvironment();
+  return env === 'staging'
+    ? "https://staging.mdl.verantid.bluerocket.us"
+    : "https://mdl.verantid.bluerocket.us";
+}
+
 export const dmvCheck = async (clientId, scannerType, licenseData) => {
   const url = getDmvServerAddress();
 
@@ -440,3 +451,58 @@ export const checkScannerPresent = async (scannerAddress) => {
     return false;
   }
 };
+
+/**
+ * Create a verification session for mobile ID verification
+ *
+ * POST /sessions
+ * Returns: session_id, session_url (for QR code), websocket_url (for real-time updates)
+ *
+ * @param {string} userId - User ID for the verification session
+ * @param {string} clientId - Client ID for licensing and tracking
+ * @returns {Promise<Object>} Session data with session_id, session_url, and websocket_url
+ */
+export const createVerificationSession = async (userId, clientId) => {
+  const url = getMobileVerificationServerAddress() + "/sessions";
+  const data = { user_id: userId, client_id: clientId };
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (response.ok) {
+      const responseData = await response.json();
+      return responseData;
+    } else {
+      // Try to parse error response
+      try {
+        const errorData = await response.json();
+        console.error("Verification session creation failed:", errorData);
+        return {
+          status: 'error',
+          message: errorData.message || 'Failed to create verification session',
+          error: errorData
+        };
+      } catch (parseError) {
+        const errorText = await response.text();
+        console.error("Verification session creation failed:", errorText);
+        return {
+          status: 'error',
+          message: 'Failed to create verification session',
+          raw_error: errorText
+        };
+      }
+    }
+  } catch (error) {
+    console.error("There was a problem with the verification session request:", error);
+    return {
+      status: 'error',
+      message: error.message || 'Unable to connect to verification service.'
+    };
+  }
+};

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.9] - 2026-04-21
+
+### Added
+- Mobile ID verification support (VNT-1409, VNT-1419, VNT-1429, VNT-1455)
+  - Added `startMobileVerification()` function to initiate mobile verification sessions
+  - Added `createVerificationSession()` API function to create verification sessions with user ID and client ID
+  - Added WebSocket client (`WebSocketClient.js`) for real-time verification updates from AWS API Gateway
+  - Added mobile verification server address configuration with environment detection
+  - QR code generation for mobile verification sessions with customizable base URLs
+  - Real-time verification callbacks: `onVerificationStarted`, `onVerificationResult`, `onStatusChange`, `onError`
+  - Session management with session ID, session URL, WebSocket URL, and QR code SVG
+  - Connection state management (CONNECTING, OPEN, CLOSED, ERROR) for WebSocket connections
+
+### Changed
+- Updated environment detection to support mobile verification endpoints
+  - Mobile verification uses `staging.mdl.verantid.bluerocket.us` for staging
+  - Mobile verification uses `mdl.verantid.bluerocket.us` for production
+- Updated scanner type detection to use `scannerProfile` from scanner response in auto-DMV verification
+- Enhanced TypeScript definitions (`index.d.ts`) to include mobile verification types and callbacks
+
 ## [1.4.5-beta.8] - 2026-04-15
 
 ### Changed

package/CloudScan.js

@@ -15,8 +15,14 @@ import {
   scannerPresent,
 } from "./ScannerApi.js";
 import { VerificationModal } from "./VerificationModal.js";
-import { checkAutoDmvEnabled, setEnvironment } from "./Api.js";
+import { checkAutoDmvEnabled, setEnvironment, createVerificationSession } from "./Api.js";
 import { formatSexCodeForDisplay, formatHeightForDisplay } from "./FormatUtils.js";
+import { WebSocketClient, ConnectionState } from "./WebSocketClient.js";
+
+// Re-export WebSocket primitives so host apps can import them from the
+// library entry point (e.g. for typing connection state in their own UI).
+export { WebSocketClient, ConnectionState };
+import QRCode from "qrcode";
 
 let cachedLicenseFrontBase64 = "";
 
@@ -496,3 +502,148 @@ export const localContinueScanId = async (scannerAddress, includeData, clientId
   }
   return returnObj;
 };
+
+/**
+ * Connect to a verification session's WebSocket
+ *
+ * Low-level primitive: opens a WebSocket connection to the given API Gateway
+ * URL and wires up the event callbacks. Use this when the caller already has
+ * a session (URL obtained out-of-band). For the full flow that also creates
+ * the session and generates a QR code, use `startMobileVerification`.
+ *
+ * AWS message frames are parsed and dispatched as high-level events:
+ *   - verification_started → callbacks.onVerificationStarted(payload)
+ *   - verification_result  → callbacks.onResult(payload)
+ * Connection lifecycle is surfaced via callbacks.onStatusChange and
+ * callbacks.onError with clean `{ message, code, error }` shapes.
+ *
+ * @param {Object} options
+ * @param {string} options.websocketUrl - API Gateway WebSocket URL (must include session_id)
+ * @param {Object} [options.callbacks] - Event callbacks
+ * @param {Function} [options.callbacks.onVerificationStarted]
+ * @param {Function} [options.callbacks.onResult]
+ * @param {Function} [options.callbacks.onStatusChange]
+ * @param {Function} [options.callbacks.onError]
+ * @returns {Promise<Object>} Handle with live `status` getter and `close()` method
+ */
+export const connectToVerificationSession = async ({ websocketUrl, callbacks = {} } = {}) => {
+  if (!websocketUrl) {
+    throw new Error('connectToVerificationSession: websocketUrl is required');
+  }
+
+  const wsClient = new WebSocketClient(callbacks);
+
+  // WebSocketClient.connect() already invokes callbacks.onError on failure;
+  // we just let the error propagate so the caller can react too.
+  await wsClient.connect(websocketUrl);
+
+  return {
+    get status() { return wsClient.getState(); },
+    close: () => wsClient.disconnect()
+  };
+};
+
+/**
+ * Start mobile verification session
+ *
+ * Creates a verification session, generates a QR code, and establishes WebSocket connection
+ * for real-time verification updates.
+ *
+ * @param {string} userId - User ID for the verification session
+ * @param {string} clientId - Client ID for licensing and tracking
+ * @param {Object} callbacks - Event callbacks for verification lifecycle
+ * @param {Function} callbacks.onVerificationStarted - Called when customer starts verification
+ * @param {Function} callbacks.onResult - Called when verification completes with verified fields
+ * @param {Function} callbacks.onStatusChange - Called when WebSocket connection state changes
+ * @param {Function} callbacks.onError - Called on errors
+ * @returns {Promise<Object>} Session handle with QR code and control methods
+ */
+export const startMobileVerification = async (userId, clientId, callbacks = {}, mobileVerifyBaseUrl) => {
+  try {
+    const sessionData = await createVerificationSession(userId, clientId);
+
+    if (sessionData.status === 'error') {
+      throw new Error(sessionData.message || 'Failed to create verification session');
+    }
+
+    const { session_id, session_url, websocket_url } = sessionData;
+
+    if (!session_id || !session_url || !websocket_url) {
+      throw new Error('Invalid session response: missing required fields');
+    }
+
+    // Generate QR code SVG
+    // If mobileVerifyBaseUrl is provided, construct the mobile verify URL by
+    // appending the session_id as a path segment (matches host-app routes like
+    //   route("mobile-verify/:sessionId", ...)
+    // in VerantID-Web). Falls back to the backend session_url if no base is
+    // provided, but note that the backend URL typically requires auth headers
+    // that a phone browser can't send from a QR-code open, so host apps should
+    // always pass mobileVerifyBaseUrl in production.
+    let qrCodeUrl = session_url;
+    if (mobileVerifyBaseUrl) {
+      // Remove trailing slash if present so we don't end up with "//{session_id}"
+      const baseUrl = mobileVerifyBaseUrl.endsWith('/') ? mobileVerifyBaseUrl.slice(0, -1) : mobileVerifyBaseUrl;
+      qrCodeUrl = `${baseUrl}/${session_id}`;
+      console.log('[startMobileVerification] Using custom mobile verify URL:', qrCodeUrl);
+    } else {
+      console.log('[startMobileVerification] Using backend session URL for QR code:', qrCodeUrl);
+    }
+
+    let qrCodeSvg = '';
+    try {
+      qrCodeSvg = await QRCode.toString(qrCodeUrl, {
+        type: 'svg',
+        width: 256,
+        margin: 2,
+        errorCorrectionLevel: 'M'
+      });
+      console.log('[startMobileVerification] QR code generated');
+    } catch (qrError) {
+      console.error('[startMobileVerification] QR code generation failed:', qrError);
+      throw new Error('Failed to generate QR code: ' + qrError.message);
+    }
+
+    // Step 3: Connect to WebSocket via the shared primitive
+    let wsSession;
+    try {
+      wsSession = await connectToVerificationSession({
+        websocketUrl: websocket_url,
+        callbacks
+      });
+      console.log('[startMobileVerification] WebSocket connected');
+    } catch (wsError) {
+      console.error('[startMobileVerification] WebSocket connection failed:', wsError);
+      throw new Error('Failed to establish WebSocket connection: ' + wsError.message);
+    }
+
+    // Step 4: Return session handle — `status` is a live getter that
+    // delegates to the underlying WebSocket client, so host apps always
+    // observe the current connection state (not a snapshot).
+    return {
+      sessionId: session_id,
+      sessionUrl: session_url, // Backend API URL for session
+      qrCodeUrl: qrCodeUrl, // The URL that was encoded in the QR code (mobile verify page or session URL)
+      qrCodeSvg: qrCodeSvg,
+      get status() { return wsSession.status; },
+      close: () => {
+        console.log('[startMobileVerification] Closing session:', session_id);
+        wsSession.close();
+      }
+    };
+
+  } catch (error) {
+    console.error('[startMobileVerification] Error:', error);
+
+    // Notify error callback if provided
+    if (typeof callbacks.onError === 'function') {
+      callbacks.onError({
+        message: error.message || 'Failed to start mobile verification',
+        code: 'SESSION_CREATION_FAILED',
+        error
+      });
+    }
+
+    throw error;
+  }
+};

package/WebSocketClient.js

@@ -0,0 +1,209 @@
+/**
+ * WebSocketClient.js
+ *
+ * Manages WebSocket connections to AWS API Gateway for real-time verification updates.
+ * Handles connection lifecycle, message parsing, and event callbacks.
+ */
+
+/**
+ * Connection states
+ */
+export const ConnectionState = {
+  CONNECTING: 'connecting',
+  OPEN: 'open',
+  CLOSED: 'closed',
+  ERROR: 'error'
+};
+
+/**
+ * WebSocket message route keys from AWS API Gateway
+ */
+const RouteKeys = {
+  VERIFICATION_STARTED: 'verification_started',
+  VERIFICATION_RESULT: 'verification_result'
+};
+
+/**
+ * WebSocketClient
+ *
+ * Encapsulates WebSocket connection management and event handling for verification sessions.
+ */
+export class WebSocketClient {
+  constructor(callbacks = {}) {
+    this.ws = null;
+    this.state = ConnectionState.CLOSED;
+    this.callbacks = {
+      onVerificationStarted: callbacks.onVerificationStarted || null,
+      onResult: callbacks.onResult || null,
+      onStatusChange: callbacks.onStatusChange || null,
+      onError: callbacks.onError || null
+    };
+  }
+
+  /**
+   * Connect to WebSocket API Gateway
+   * @param {string} wsUrl - The WebSocket URL (already includes session_id query param)
+   * @returns {Promise<void>}
+   */
+  async connect(wsUrl) {
+    if (this.ws) {
+      throw new Error('WebSocket connection already exists');
+    }
+
+    // Resolve WebSocket implementation: native global (browser or modern Node)
+    // or the 'ws' package (older Node runtimes). Dynamic import is used because
+    // this file is an ES module — top-level `require` is not available.
+    let WebSocketImpl;
+    if (typeof WebSocket !== 'undefined') {
+      WebSocketImpl = WebSocket;
+    } else {
+      try {
+        const wsModule = await import('ws');
+        WebSocketImpl = wsModule.default || wsModule.WebSocket;
+      } catch (error) {
+        this._updateState(ConnectionState.ERROR);
+        this._invokeCallback('onError', {
+          message: 'No WebSocket implementation available (install "ws" for Node.js)',
+          code: 'NO_WEBSOCKET_IMPL',
+          error: error.message
+        });
+        throw error;
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this._updateState(ConnectionState.CONNECTING);
+        this.ws = new WebSocketImpl(wsUrl);
+
+        this.ws.onopen = () => {
+          console.log('[WebSocketClient] Connection established');
+          this._updateState(ConnectionState.OPEN);
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          this._handleMessage(event.data);
+        };
+
+        this.ws.onerror = (error) => {
+          console.error('[WebSocketClient] Connection error:', error);
+          this._updateState(ConnectionState.ERROR);
+          this._invokeCallback('onError', {
+            message: 'WebSocket connection error',
+            code: 'CONNECTION_ERROR',
+            error
+          });
+        };
+
+        this.ws.onclose = (event) => {
+          console.log('[WebSocketClient] Connection closed', event.code, event.reason);
+          this._updateState(ConnectionState.CLOSED);
+          this.ws = null;
+        };
+
+      } catch (error) {
+        this._updateState(ConnectionState.ERROR);
+        this._invokeCallback('onError', {
+          message: 'Failed to create WebSocket connection',
+          code: 'CONNECTION_FAILED',
+          error: error.message
+        });
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Disconnect and cleanup WebSocket connection
+   */
+  disconnect() {
+    if (this.ws) {
+      console.log('[WebSocketClient] Disconnecting...');
+      this.ws.close();
+      this.ws = null;
+      this._updateState(ConnectionState.CLOSED);
+    }
+  }
+
+  /**
+   * Get current connection state
+   * @returns {string}
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Handle incoming WebSocket messages
+   * @private
+   * @param {string} data - Raw message data
+   */
+  _handleMessage(data) {
+    try {
+      console.log('[WebSocketClient] Received message:', data);
+
+      // Parse the message (AWS API Gateway may send JSON-wrapped messages)
+      const message = typeof data === 'string' ? JSON.parse(data) : data;
+
+      // Extract route key and payload
+      // AWS API Gateway format may vary, handle both direct and wrapped formats
+      const routeKey = message.routeKey || message.action || message.type;
+      const payload = message.data || message.payload || message;
+
+      // Route to appropriate handler
+      switch (routeKey) {
+        case RouteKeys.VERIFICATION_STARTED:
+          console.log('[WebSocketClient] Verification started');
+          this._invokeCallback('onVerificationStarted', payload);
+          break;
+
+        case RouteKeys.VERIFICATION_RESULT:
+          console.log('[WebSocketClient] Verification result received');
+          this._invokeCallback('onResult', payload);
+          break;
+
+        default:
+          console.warn('[WebSocketClient] Unknown message route:', routeKey);
+          break;
+      }
+
+    } catch (error) {
+      console.error('[WebSocketClient] Error parsing message:', error);
+      this._invokeCallback('onError', {
+        message: 'Failed to parse WebSocket message',
+        code: 'PARSE_ERROR',
+        error: error.message
+      });
+    }
+  }
+
+  /**
+   * Update connection state and notify listeners
+   * @private
+   * @param {string} newState
+   */
+  _updateState(newState) {
+    if (this.state !== newState) {
+      this.state = newState;
+      console.log('[WebSocketClient] State changed:', newState);
+      this._invokeCallback('onStatusChange', newState);
+    }
+  }
+
+  /**
+   * Safely invoke a callback if it exists
+   * @private
+   * @param {string} callbackName
+   * @param {*} data
+   */
+  _invokeCallback(callbackName, data) {
+    if (typeof this.callbacks[callbackName] === 'function') {
+      try {
+        this.callbacks[callbackName](data);
+      } catch (error) {
+        console.error(`[WebSocketClient] Error in ${callbackName} callback:`, error);
+      }
+    }
+  }
+}

package/index.d.ts

@@ -78,6 +78,71 @@ declare module "verant_id_cloud_scan" {
     errorMessages: string;
     dmvVerificationResult?: any;
   }>;
+
+  // Mobile Verification Types
+  export type ConnectionStateValue = 'connecting' | 'open' | 'closed' | 'error';
+
+  export const ConnectionState: {
+    readonly CONNECTING: 'connecting';
+    readonly OPEN: 'open';
+    readonly CLOSED: 'closed';
+    readonly ERROR: 'error';
+  };
+
+  export interface VerificationCallbacks {
+    onVerificationStarted?: (data: any) => void;
+    onResult?: (verifiedFields: any) => void;
+    onStatusChange?: (status: ConnectionStateValue) => void;
+    onError?: (error: { message: string; code?: string; error?: any }) => void;
+  }
+
+  /**
+   * Handle returned by `connectToVerificationSession`. `status` is a live
+   * getter that reflects the current WebSocket state, not a snapshot.
+   */
+  export interface ConnectedSession {
+    readonly status: ConnectionStateValue;
+    close(): void;
+  }
+
+  export interface VerificationSession {
+    sessionId: string;
+    sessionUrl: string;
+    qrCodeUrl: string;
+    qrCodeSvg: string;
+    readonly status: ConnectionStateValue;
+    close: () => void;
+  }
+
+  export interface ConnectToVerificationSessionOptions {
+    websocketUrl: string;
+    callbacks?: VerificationCallbacks;
+  }
+
+  /**
+   * Low-level primitive: open a WebSocket connection to an existing
+   * verification session's API Gateway URL.
+   *
+   * For the full orchestrated flow (create session + QR + WS connect),
+   * use `startMobileVerification`.
+   */
+  export function connectToVerificationSession(
+    options: ConnectToVerificationSessionOptions
+  ): Promise<ConnectedSession>;
+
+  export function startMobileVerification(
+    userId: string,
+    clientId: string,
+    callbacks?: VerificationCallbacks,
+    mobileVerifyBaseUrl?: string
+  ): Promise<VerificationSession>;
+
+  export class WebSocketClient {
+    constructor(callbacks?: VerificationCallbacks);
+    connect(wsUrl: string): Promise<void>;
+    disconnect(): void;
+    getState(): ConnectionStateValue;
+  }
 }
 
 export function scannerPresent(scannerAddress: string): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verant_id_cloud_scan",
-  "version": "1.4.5-beta.8",
+  "version": "1.4.5-beta.9",
   "description": "Verant ID Cloud Scan NPM Library",
   "main": "CloudScan.js",
   "types": "index.d.ts",
@@ -9,5 +9,11 @@
   },
   "author": "Verant ID Inc",
   "license": "ISC",
-  "type": "module"
+  "type": "module",
+  "dependencies": {
+    "qrcode": "^1.5.3"
+  },
+  "optionalDependencies": {
+    "ws": "^8.16.0"
+  }
 }