feat(recognize): handle recoverable-error, recognition-failure, and non-cancelable events from Keyless SDK v3

Author: eugeniobet-ping

packages/recognize/src/lib/classes/recognize-error.ts

@@ -3,11 +3,13 @@ import { RecognizeErrorCode } from '../defs/recognize-error-code.js';
 /** @public */
 export class RecognizeError extends Error {
   code: RecognizeErrorCode;
+  // recoverable: boolean;
 
   constructor(code: RecognizeErrorCode, options?: ErrorOptions) {
     super(RecognizeErrorCode[code], options);
 
     this.code = code;
     this.name = 'RecognizeError';
+    // this.recoverable = false;
   }
 }

packages/recognize/src/lib/defs/recognize-error-code.ts

@@ -34,7 +34,6 @@ export enum RecognizeErrorCode {
   CORE_USER_ALREADY_ENROLLED = 3002,
   CORE_USER_NOT_ENROLLED = 3003,
   CORE_FACE_NOT_MATCHING = 3004,
-  CORE_NOT_ENOUGH_CIRCUITS = 3005,
   CORE_SECRET_NOT_FOUND = 3006,
   CORE_USER_LOCKED_OUT = 3007,
   CORE_CUSTOMER_NOT_FOUND = 3008,
@@ -44,10 +43,7 @@ export enum RecognizeErrorCode {
   BIOM_LIVENESS_ENVIRONMENT_AWARE_NOT_SUPPORTED = 4003,
   BIOM_DEVICE_ENVIRONMENT_AWARE_NOT_SUPPORTED = 4004,
   SERVER_ERROR = 5000,
-  SERVER_ENCRYPTION_FAILED = 5001,
   SERVER_RECOGNITION_FAILED = 5002,
-  SERVER_AUTHORIZATION_FAILED = 5003,
-  SERVER_TIMEOUT = 5004,
   SECURITY_ERROR = 6000,
   SECURITY_DEVICE_NOT_GENUINE = 6001,
 }

packages/recognize/src/lib/defs/recognize-sdk-to-recognize-proxy-error-map.ts

@@ -11,9 +11,10 @@ import { RecognizeErrorCode } from './recognize-error-code.js';
 
 export const RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP: Record<string, RecognizeErrorCode> =
   Object.freeze({
+    FRAME_RESULTS_SET_UNSET: RecognizeErrorCode.SDK_ERROR,
     OPTIONS_UNSET: RecognizeErrorCode.SDK_ERROR,
+    USER_LOCKOUT_EXPIRATION_UNSET: RecognizeErrorCode.SDK_ERROR,
     VIDEO_ELEMENT_UNSET: RecognizeErrorCode.SDK_ERROR,
-    VIDEO_ELEMENT_EVENT_LISTENERS_UNSET: RecognizeErrorCode.SDK_ERROR,
     MEDIA_DEVICES_EMPTY_AUDIO_INPUT_LABEL: RecognizeErrorCode.SDK_ERROR,
     MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL: RecognizeErrorCode.CAMERA_PERMISSION_DENIED,
     MEDIA_DEVICES_NO_VIDEO_INPUTS: RecognizeErrorCode.CAMERA_NOT_FOUND,
@@ -25,36 +26,32 @@ export const RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP: Record<string, Recogniz
     MEDIA_STREAM_OVERCONSTRAINED: RecognizeErrorCode.CAMERA_NOT_SUPPORTED,
     MEDIA_STREAM_SECURITY: RecognizeErrorCode.CAMERA_ERROR,
     MEDIA_STREAM_TYPE: RecognizeErrorCode.CAMERA_ERROR,
-    MEDIA_STREAM_UNSET: RecognizeErrorCode.CAMERA_ERROR,
     SERVER_CUSTOMER_NOT_FOUND: RecognizeErrorCode.CORE_CUSTOMER_NOT_FOUND,
-    SERVER_FACE_DOES_NOT_MATCH: RecognizeErrorCode.CORE_FACE_NOT_MATCHING,
-    SERVER_FORBIDDEN: RecognizeErrorCode.SERVER_AUTHORIZATION_FAILED,
-    SERVER_IMAGE_ENCRYPT_FAILED: RecognizeErrorCode.SERVER_ENCRYPTION_FAILED,
     SERVER_INTERNAL_ERROR: RecognizeErrorCode.SERVER_ERROR,
-    SERVER_NO_ATTEMPTS_LEFT: RecognizeErrorCode.CORE_NOT_ENOUGH_CIRCUITS,
+    SERVER_INVALID_REQUEST: RecognizeErrorCode.SERVER_ERROR,
+    SERVER_INVALID_RESPONSE: RecognizeErrorCode.SERVER_ERROR,
     SERVER_RECOGNITION_FAILED: RecognizeErrorCode.SERVER_RECOGNITION_FAILED,
-    SERVER_TIMEOUT: RecognizeErrorCode.SERVER_TIMEOUT,
-    SERVER_UNAVAILABLE_SERVICE: RecognizeErrorCode.SERVER_ERROR,
-    SERVER_UNPROCESSABLE_EVENT: RecognizeErrorCode.SERVER_ERROR,
-    SERVER_USER_ALREADY_ENROLLED: RecognizeErrorCode.CORE_USER_ALREADY_ENROLLED,
-    SERVER_USER_NOT_FOUND: RecognizeErrorCode.CORE_USER_NOT_ENROLLED,
     SERVER_USER_LOCKED_OUT: RecognizeErrorCode.CORE_USER_LOCKED_OUT,
-    SERVER_VALIDATION_FAILED: RecognizeErrorCode.SERVER_ERROR,
+    SESSION_DATABASE_ERROR: RecognizeErrorCode.SDK_ERROR,
     SESSION_MANAGER_NOT_NULL: RecognizeErrorCode.SDK_ERROR,
     SESSION_MANAGER_NULL: RecognizeErrorCode.SDK_ERROR,
+    SESSION_MEDIA_STREAM_TIMEOUT: RecognizeErrorCode.SDK_TIMEOUT,
+    SESSION_MEDIA_STREAM_UNSET: RecognizeErrorCode.SDK_ERROR,
     CREATE_MEDIA_STREAM_ARGS_UNSET: RecognizeErrorCode.SDK_ERROR,
     EXCEPTION: RecognizeErrorCode.SDK_ERROR,
+    GET_VIDEO_MEDIA_DEVICES_ARGS_UNSET: RecognizeErrorCode.SDK_ERROR,
     RUNTIME_VIOLATION: RecognizeErrorCode.SECURITY_ERROR,
     SYMBOL_DESCRIPTION_UNSET: RecognizeErrorCode.SDK_ERROR,
-    SESSION_ID_UNSET: RecognizeErrorCode.SDK_ERROR,
     CUSTOMER_UNSET: RecognizeErrorCode.SDK_INVALID_CONFIGURATION,
+    SERVICE_URL_PARSE_FAILED: RecognizeErrorCode.SDK_INVALID_CONFIGURATION,
+    SERVICE_URL_UNSET: RecognizeErrorCode.SDK_INVALID_CONFIGURATION,
     USERNAME_UNSET: RecognizeErrorCode.SDK_INVALID_CONFIGURATION,
     WEB_ASSEMBLY_ABORTED: RecognizeErrorCode.SDK_WEB_ASSEMBLY_ERROR,
     WEB_ASSEMBLY_FACTORY_FAILED: RecognizeErrorCode.SDK_WEB_ASSEMBLY_ERROR,
     WEB_ASSEMBLY_IMPORT_FAILED: RecognizeErrorCode.SDK_WEB_ASSEMBLY_IMPORT_FAILED,
     WEB_ASSEMBLY_NOT_READY: RecognizeErrorCode.SDK_WEB_ASSEMBLY_IMPORT_NOT_FULFILLED,
     WEB_ASSEMBLY_MODULE_NOT_FOUND: RecognizeErrorCode.SDK_WEB_ASSEMBLY_ERROR,
-    QUEUE_UNSET: RecognizeErrorCode.SDK_ERROR,
     SLUG_UNSUPPORTED: RecognizeErrorCode.SDK_ERROR,
+    QUEUE_UNSET: RecognizeErrorCode.SDK_ERROR,
     SYMBOL_UNSET: RecognizeErrorCode.SDK_ERROR,
   });

packages/recognize/src/lib/recognize.ts

@@ -12,6 +12,7 @@ import { CAMERA_ONLY_DISABLE_STEPS } from './defs/constants.js';
 import { RecognizeErrorCode } from './defs/recognize-error-code.js';
 import { RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP } from './defs/recognize-sdk-to-recognize-proxy-error-map.js';
 import type { KeylessSuccessEvent } from './recognize-sdk/index.js';
+import { KeylessRecoverableErrorEvent } from './recognize-sdk/index.js';
 import type {
   RecognizeWebComponent,
   RecognizeWebComponentClient,
@@ -45,7 +46,7 @@ export function recognize(
     }
   };
 
-  const addEventListeners = (element: RecognizeWebComponent): void => {
+  const addEventListeners = (el: RecognizeWebComponent): void => {
     aborter = new AbortController();
 
     const onEvent = (type: RecognizeWebComponentEvent['type']) => {
@@ -61,10 +62,36 @@ export function recognize(
     };
 
     const onError = (e: ErrorEvent) => {
+      const recoverable = e instanceof KeylessRecoverableErrorEvent;
+
+      if (recoverable) {
+        console.log('%c[recognize] recoverable-error → calling element.dispose()', 'color: orange; font-weight: bold');
+        element?.dispose();
+      }
+
       const code: RecognizeErrorCode =
-        RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP[e.error.message] ?? RecognizeErrorCode.SDK_ERROR;
+        RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP[e.error?.message] ??
+        RecognizeErrorCode.SDK_ERROR;
 
       const error: RecognizeError = new RecognizeError(code, { cause: e.error });
+      // error.recoverable = recoverable;
+
+      for (const observer of observers) {
+        observer.error?.(error);
+      }
+
+      observers.clear();
+    };
+
+    const onRecoverableError = (e: KeylessRecoverableErrorEvent) => onError(e);
+
+    const onRecognitionFailure = (e: CustomEvent) => {
+      const error: RecognizeError = new RecognizeError(
+        RecognizeErrorCode.SERVER_RECOGNITION_FAILED,
+        {
+          cause: e.detail,
+        },
+      );
 
       for (const observer of observers) {
         observer.error?.(error);
@@ -75,10 +102,13 @@ export function recognize(
 
     const options: AddEventListenerOptions = { signal: aborter.signal };
 
-    element.addEventListener('error', onError, options);
-    element.addEventListener('step-change', onEvent('step-change'), options);
-    element.addEventListener('success', onSuccess, options);
-    element.addEventListener('video-frame-quality', onEvent('video-frame-quality'), options);
+    el.addEventListener('error', onError, options);
+    el.addEventListener('recoverable-error', onRecoverableError, options);
+    el.addEventListener('recognition-failure', onRecognitionFailure, options);
+    el.addEventListener('non-cancelable', onEvent('non-cancelable'), options);
+    el.addEventListener('step-change', onEvent('step-change'), options);
+    el.addEventListener('success', onSuccess, options);
+    el.addEventListener('video-frame-quality', onEvent('video-frame-quality'), options);
   };
 
   const setAttributes = (element: RecognizeWebComponent): void => {

packages/recognize/src/lib/recognize.types.ts

@@ -85,6 +85,7 @@ export type RecognizeWebComponent = KeylessAuthElement | KeylessEnrollElement;
 
 /** @public */
 export type RecognizeWebComponentEvent =
+  | { type: 'non-cancelable' }
   | { type: 'step-change'; detail: RecognizeWebComponentStepChangeEventDetail }
   | { type: 'video-frame-quality'; detail: RecognizeWebComponentVideoFrameQualityEventDetail };