feat: optimize error and event handling

dariosechi-ping · dariosechi-ping · commit 01690abb226c · 2026-06-12T13:49:12.000+02:00
diff --git a/packages/recognize/package.json b/packages/recognize/package.json
@@ -17,6 +17,9 @@
   "dependencies": {
     "tslib": "^2.3.0"
   },
+  "devDependencies": {
+    "@aracna/web-components": "^1.1.18"
+  },
   "nx": {
     "tags": ["scope:package"],
     "targets": {
diff --git a/packages/recognize/src/lib/classes/recognize-error.ts b/packages/recognize/src/lib/classes/recognize-error.ts
@@ -0,0 +1,14 @@
+import type { RecognizeErrorCode } from '../defs/recognize-error-code.js';
+
+/** @public */
+export class RecognizeError extends Error {
+  code: RecognizeErrorCode;
+
+  constructor(code: RecognizeErrorCode, cause?: Error) {
+    super(code);
+
+    this.code = code;
+    this.cause = cause;
+    this.name = 'RecognizeError';
+  }
+}
diff --git a/packages/recognize/src/lib/defs/constants.ts b/packages/recognize/src/lib/defs/constants.ts
@@ -0,0 +1,11 @@
+/** @internal */
+export const CAMERA_ONLY_DISABLE_STEPS: string[] = [
+  'bootstrap',
+  'camera-instructions',
+  'done',
+  'error',
+  'microphone-permission',
+  'server-computation',
+  'stm-choice',
+  'stm-qrcode',
+];
diff --git a/packages/recognize/src/lib/functions/create-recognize-error.ts b/packages/recognize/src/lib/functions/create-recognize-error.ts
@@ -7,33 +7,28 @@
  *
  */
 
+import { RecognizeError } from '../classes/recognize-error.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 { RecognizeError } from '../recognize.types.js';
 
 /** @public */
 export const createRecognizeError = (
   codeOrSdkError: RecognizeErrorCode | ErrorEvent,
   cause?: Error,
 ): RecognizeError => {
-  let code: RecognizeErrorCode;
-  let errorCause: Error | undefined;
-
   if (codeOrSdkError instanceof ErrorEvent) {
-    const reason = (codeOrSdkError as ErrorEvent & { reason?: string }).reason;
-    code =
-      (reason && RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP[reason]) ||
-      RecognizeErrorCode.SDK_ERROR;
-    errorCause = codeOrSdkError.error instanceof Error ? codeOrSdkError.error : undefined;
+    if (codeOrSdkError.error instanceof Error) {
+      let code: RecognizeErrorCode;
+
+      code =
+        RECOGNIZE_SDK_TO_RECOGNIZE_PROXY_ERROR_MAP[codeOrSdkError.error.message] ||
+        RecognizeErrorCode.SDK_ERROR;
+
+      return new RecognizeError(code, codeOrSdkError.error);
+    }
   } else {
-    code = codeOrSdkError;
-    errorCause = cause;
+    return new RecognizeError(codeOrSdkError, cause);
   }
 
-  const error: RecognizeError = Object.assign(new Error(code), {
-    name: 'RecognizeError',
-    code,
-    cause: errorCause,
-  });
-  return error;
+  return new RecognizeError(RecognizeErrorCode.SDK_ERROR, cause);
 };
diff --git a/packages/recognize/src/lib/recognize-sdk/index.d.ts b/packages/recognize/src/lib/recognize-sdk/index.d.ts
@@ -1096,7 +1096,7 @@ export declare interface KeylessWebSocketOpenEventDetail {
 }
 
 /** @internal */
-declare class RootElement extends AracnaBaseElement {
+declare class RootElement extends AracnaBaseElement<RootElementEventMap> {
     appearanceController: KeylessAppearanceController;
     localizationController: KeylessLocalizationController;
     loggerController: KeylessLoggerController;
diff --git a/packages/recognize/src/lib/recognize.spec.ts b/packages/recognize/src/lib/recognize.spec.ts
@@ -191,8 +191,7 @@ describe('recognize — error observer', () => {
     await client.init({ mode: 'mount', container, type: 'auth', username: 'user' });
     const el = container.querySelector('kl-auth')!;
 
-    const event = new ErrorEvent('error', { error: new Error('raw') });
-    Object.defineProperty(event, 'reason', { value: 'MEDIA_STREAM_NOT_ALLOWED' });
+    const event = new ErrorEvent('error', { error: new Error('MEDIA_STREAM_NOT_ALLOWED') });
     el.dispatchEvent(event);
 
     const receivedError = errorFn.mock.calls[0][0];
diff --git a/packages/recognize/src/lib/recognize.ts b/packages/recognize/src/lib/recognize.ts
@@ -7,112 +7,67 @@
  *
  */
 
-import type {
-  KeylessAuthElement,
-  KeylessEnrollElement,
-  KeylessFinishedEvent,
-  KeylessFrameResultsEvent,
-  KeylessStepChangeEvent,
-  KeylessVideoFrameQualityEvent,
-  KeylessWebSocketCloseEvent,
-  KeylessWebSocketOpenEvent,
-} from './recognize-sdk/index.js';
+import type { RecognizeError } from './classes/recognize-error.js';
+import { CAMERA_ONLY_DISABLE_STEPS } from './defs/constants.js';
 import { RecognizeErrorCode } from './defs/recognize-error-code.js';
 import { createRecognizeError } from './functions/create-recognize-error.js';
+import type { KeylessFinishedEvent } from './recognize-sdk/index.js';
 import type {
-  RecognizeError,
+  RecognizeRootElement,
   RecognizeWcClient,
   RecognizeWcConfig,
   RecognizeWcInitOptions,
   RecognizeWcObserver,
   RecognizeWcUnsubscribe,
 } from './recognize.types.js';
 
-type RootEl = KeylessAuthElement | KeylessEnrollElement;
-
-const CAMERA_ONLY_DISABLE_STEPS: string[] = [
-  'bootstrap',
-  'camera-instructions',
-  'done',
-  'error',
-  'microphone-permission',
-  'server-computation',
-  'stm-choice',
-  'stm-qrcode',
-];
-
 /**
  * @function recognize - Returns a client to interact with the PingOne Recognize SDK web components
  * @param {RecognizeWcConfig} config - Configuration for the PingOne Recognize SDK
  * @returns {RecognizeWcClient}
  */
 export function recognize(config: RecognizeWcConfig): RecognizeWcClient {
   const effectiveConfig: RecognizeWcConfig = { disableSteps: CAMERA_ONLY_DISABLE_STEPS, ...config };
-  let element: RootEl | null = null;
-  let abortController: AbortController | null = null;
   const observers: Set<RecognizeWcObserver> = new Set();
 
+  let element: RecognizeRootElement | null = null;
+  let abortController: AbortController | null = null;
+
   const dispatch = (type: string, detail: unknown): void => {
     for (const observer of observers) {
       observer.next({ type, detail } as Parameters<RecognizeWcObserver['next']>[0]);
     }
   };
 
-  const attachListeners = (el: RootEl): void => {
+  const attachListeners = (el: RecognizeRootElement): void => {
     abortController = new AbortController();
     const { signal } = abortController;
 
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'step-change',
-      (e: KeylessStepChangeEvent) => dispatch('step-change', e.detail),
-      { signal },
-    );
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'finished',
-      (e: KeylessFinishedEvent) => {
-        for (const observer of observers) observer.complete?.(e.detail);
-        observers.clear();
-      },
-      { signal },
-    );
-    el.addEventListener(
-      'error',
-      (e: ErrorEvent) => {
-        const err = createRecognizeError(e);
-        for (const observer of observers) observer.error?.(err);
-        observers.clear();
-      },
-      { signal },
-    );
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'frame-results',
-      (e: KeylessFrameResultsEvent) => dispatch('frame-results', e.detail),
-      { signal },
-    );
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'video-frame-quality',
-      (e: KeylessVideoFrameQualityEvent) => dispatch('video-frame-quality', e.detail),
-      { signal },
-    );
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'ws-open',
-      (e: KeylessWebSocketOpenEvent) => dispatch('ws-open', e.detail),
-      { signal },
-    );
-    // @ts-expect-error — SDK event map not reflected on HTMLElement.addEventListener
-    el.addEventListener(
-      'ws-close',
-      (e: KeylessWebSocketCloseEvent) => dispatch('ws-close', e.detail),
-      { signal },
-    );
+    const onEvent = (type: string) => {
+      return (event: CustomEvent) => dispatch(type, event.detail);
+    };
+
+    const onFinished = (event: KeylessFinishedEvent) => {
+      for (const observer of observers) observer.complete?.(event.detail);
+      observers.clear();
+    };
+
+    const onError = (e: ErrorEvent) => {
+      const err = createRecognizeError(e);
+      for (const observer of observers) observer.error?.(err);
+      observers.clear();
+    };
+
+    el.addEventListener('error', onError, { signal });
+    el.addEventListener('finished', onFinished, { signal });
+    el.addEventListener('step-change', onEvent('step-change'), { signal });
+    el.addEventListener('frame-results', onEvent('frame-results'), { signal });
+    el.addEventListener('video-frame-quality', onEvent('video-frame-quality'), { signal });
+    el.addEventListener('ws-open', onEvent('ws-open'), { signal });
+    el.addEventListener('ws-close', onEvent('ws-close'), { signal });
   };
 
-  const applyConfig = (el: RootEl): void => {
+  const applyConfig = (el: RecognizeRootElement): void => {
     const target = el as unknown as Record<string, unknown>;
     for (const [k, v] of Object.entries(effectiveConfig)) {
       if (v !== undefined) {
@@ -141,22 +96,28 @@ export function recognize(config: RecognizeWcConfig): RecognizeWcClient {
       }
 
       if (options.mode === 'attach') {
-        const tag = (options.element as HTMLElement).tagName;
+        const tag = options.element.tagName;
+
         if (tag !== 'KL-AUTH' && tag !== 'KL-ENROLL') {
           throw new Error(
             `recognize: invalid element <${tag.toLowerCase()}> — options.element must be a <kl-auth> or <kl-enroll> custom element`,
           );
         }
-        element = options.element as RootEl;
+
+        element = options.element as RecognizeRootElement;
         element.username = options.username;
+
         applyConfig(element);
         attachListeners(element);
       } else {
         const tag = options.type === 'auth' ? 'kl-auth' : 'kl-enroll';
-        element = document.createElement(tag) as RootEl;
+
+        element = document.createElement(tag) as RecognizeRootElement;
         element.username = options.username;
+
         applyConfig(element);
         attachListeners(element);
+
         options.container.appendChild(element);
       }
     },
diff --git a/packages/recognize/src/lib/recognize.types.ts b/packages/recognize/src/lib/recognize.types.ts
@@ -7,21 +7,20 @@
  *
  */
 
+import type { RecognizeError } from './classes/recognize-error.js';
 import type {
+  KeylessAuthElement,
+  KeylessEnrollElement,
   KeylessFinishedEventDetail,
   KeylessFrameResultsEventDetail,
   KeylessStepChangeEventDetail,
   KeylessVideoFrameQualityEventDetail,
   KeylessWebSocketCloseEventDetail,
   KeylessWebSocketOpenEventDetail,
 } from './recognize-sdk/index.js';
-import type { RecognizeErrorCode } from './defs/recognize-error-code.js';
 
 /** @public */
-export interface RecognizeError extends Error {
-  code: RecognizeErrorCode;
-  cause?: Error;
-}
+export type RecognizeRootElement = KeylessAuthElement | KeylessEnrollElement;
 
 /** @public */
 export type RecognizeSessionType = 'auth' | 'enroll';
@@ -33,8 +32,7 @@ export interface RecognizeWcStepChangeEventDetail extends KeylessStepChangeEvent
 export interface RecognizeWcFrameResultsEventDetail extends KeylessFrameResultsEventDetail {}
 
 /** @public */
-export interface RecognizeWcVideoFrameQualityEventDetail
-  extends KeylessVideoFrameQualityEventDetail {}
+export interface RecognizeWcVideoFrameQualityEventDetail extends KeylessVideoFrameQualityEventDetail {}
 
 /** @public */
 export interface RecognizeWcWebSocketOpenEventDetail extends KeylessWebSocketOpenEventDetail {}

Original file line number	Diff line number	Diff line change
`@@ -1096,7 +1096,7 @@ export declare interface KeylessWebSocketOpenEventDetail {`
`1096`	`1096`	`}`
`1097`	`1097`
`1098`	`1098`	`/** @internal */`
`1099`		`-declare class RootElement extends AracnaBaseElement {`
	`1099`	`+declare class RootElement extends AracnaBaseElement<RootElementEventMap> {`
`1100`	`1100`	`appearanceController: KeylessAppearanceController;`
`1101`	`1101`	`localizationController: KeylessLocalizationController;`
`1102`	`1102`	`loggerController: KeylessLoggerController;`