@pagopa/io-react-native-iso18013 0.3.0 → 0.4.0

package/src/iso18013/iso18013-5/README.md

@@ -18,14 +18,16 @@ This library emits the following events:
 | onDeviceDisconnected | `undefined` | Event dispatched when the verifier app disconnects. |
 | onError | `{ error: string } \| undefined` | Event dispatched when an error occurs which is contained in the error payload. It can be parsed via the `parseError` provided [here](src/schema.ts). |
 
-Listeners can be added using the `addListener` method and removed using the `removeListener` method.
+Listeners can be added using the `addListener` method and removed by using the returned reference by calling the `remove` method.
 
 ```typescript
 import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
 
-ISO18013_5.addListener('event', () => console.log('event occurred'));
+const listener = ISO18013_5.addListener('event', () =>
+  console.log('event occurred')
+);
 
-ISO18013_5.removeListener('event');
+listener.remove();
 ```
 
 #### `onDeviceConnecting`
@@ -173,7 +175,7 @@ await ISO18013_5.sendErrorResponse({
 
 Closes the QR engagement by releasing the resources allocated during the `start` method.
 Before starting a new flow, it is necessary to call this method to ensure that the previous flow is properly closed.
-The listeners can be removed using the `removeListener` method.
+Listeners can be added using the `addListener` method and removed using the `removeListener` method.
 
 ```typescript
 import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
@@ -220,15 +222,49 @@ sequenceDiagram
     proximity->>+app: Calls the onDeviceDisconnected callback
 ```
 
-## Error Codes
-
-| Type                            | Platform    | Description                                                                  |
-| ------------------------------- | ----------- | ---------------------------------------------------------------------------- |
-| DRH_NOT_DEFINED                 | Android     | The device retrieval helper hasn't been initialized, call the `start` method |
-| QR_ENGAGEMENT_NOT_DEFINED_ERROR | Android     | The QR engagement hasn't been initialized, call the `start` method           |
-| START_ERROR                     | Android/iOS | An error occurred while initializing the required resources                  |
-| GET_QR_CODE_ERROR               | Android/iOS | An error occurred while generating the engagement QR code                    |
-| GENERATE_RESPONSE_ERROR         | Android/iOS | An error occurred while generating the response for the verifier app         |
-| SEND_RESPONSE_ERROR             | Android/iOS | An error occurred while sending the response to the verifier app             |
-| SEND_ERROR_RESPONSE_ERROR       | Android/iOS | An error occurred while sending the error response to the verifier app       |
-| CLOSE_ERROR                     | Android     | An error occured while closing the required resources                        |
+## Errors
+
+This table contains the list of error codes that can be thrown by the `ISO18013_5` module which are mapped via the `ModuleErrorCodes` type:
+
+| Type                      | Platform    | Description                                                                  |
+| ------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| DRH_NOT_DEFINED           | Android     | The device retrieval helper hasn't been initialized, call the `start` method |
+| QR_ENGAGEMENT_NOT_DEFINED | Android     | The QR engagement hasn't been initialized, call the `start` method           |
+| START_ERROR               | Android/iOS | An error occurred while initializing the required resources                  |
+| GET_QR_CODE_ERROR         | Android/iOS | An error occurred while generating the engagement QR code                    |
+| SEND_RESPONSE_ERROR       | Android/iOS | An error occurred while sending the response for the verifier app            |
+| SEND_ERROR_RESPONSE_ERROR | Android/iOS | An error occurred while sending the error response to the verifier app       |
+| GENERATE_RESPONSE_ERROR   | Android/iOS | An error occurred while generating the response for the verifier app         |
+| CLOSE_ERROR               | Android     | An error occured while closing the required resources                        |
+| EUNSPECIFIED              | Android     | Default error when no other error is specified                               |
+
+An error can be parsed using the `ModuleErrorSchema` with type `ModuleErrorCodes` exposed by the `ISO18013_5` module. The error can be parsed as follows:
+
+```typescript
+import { ISO18013_5 } from '@pagopa/io-react-native-iso18013';
+try {
+  await ISO18013_5.func();
+} catch (error) {
+  const parsedError = ISO18013_5.ModuleErrorSchema.parse(error); // Or ModuleErrorSchema.safeParse(error) for safe parsing
+  console.log(JSON.stringify(parsedError, null, 2));
+}
+```
+
+The parsed object will contain properties from both iOS and Android platforms:
+
+```typescript
+{
+  code: string; // Defined in ModuleErrorCodes
+  message: string;
+  name: string;
+  userInfo?: Record<string, any> | null;
+  nativeStackAndroid?: Array<{
+    lineNumber: number;
+    file: string;
+    methodName: string;
+    class: string;
+  }>;
+  domain?: string;
+  nativeStackIOS?: Array<string>;
+};
+```

package/src/iso18013/iso18013-5/error.ts

@@ -0,0 +1,35 @@
+import z from 'zod';
+import { GenericModuleErrorSchema } from '../../schema';
+
+/**
+ * Schema for parsing the payload returned by the `onError` event in Proximity `Events`, along with its type definition.
+ */
+export const OnErrorPayloadSchema = z.string().catch('Unknown error');
+
+export type OnErrorPayload = z.infer<typeof OnErrorPayloadSchema>;
+
+/**
+ * Error codes which the ISO18013_5 module uses to reject a promise.
+ */
+const ModuleErrorCodesSchema = z.enum([
+  'DRH_NOT_DEFINED', // Android only
+  'QR_ENGAGEMENT_NOT_DEFINED', // Android only
+  'START_ERROR',
+  'GET_QR_CODE_ERROR',
+  'SEND_RESPONSE_ERROR',
+  'SEND_ERROR_RESPONSE_ERROR',
+  'GENERATE_RESPONSE_ERROR',
+  'CLOSE_ERROR', // Android only
+  'EUNSPECIFIED', // Android only default when no other error is specified
+]);
+
+export type ModuleErrorCodes = z.infer<typeof ModuleErrorCodesSchema>;
+
+/**
+ * Schema which can be used to parse a rejected promise error by the ISO18013_5 module.
+ */
+export const ModuleErrorSchema = GenericModuleErrorSchema(
+  ModuleErrorCodesSchema
+);
+
+export type ModuleError = z.infer<typeof ModuleErrorSchema>;

package/src/iso18013/iso18013-5/index.ts

@@ -1,10 +1,16 @@
 export {
   type AcceptedFields,
-  type EventError,
   type VerifierRequest,
-  parseEventError,
   parseVerifierRequest,
-} from './schema';
+} from './request';
+
+export {
+  type OnErrorPayload,
+  OnErrorPayloadSchema,
+  ModuleErrorSchema,
+  type ModuleErrorCodes,
+  type ModuleError,
+} from './error';
 
 export {
   ErrorCode,
@@ -14,7 +20,6 @@ export {
   close,
   generateResponse,
   getQrCodeString,
-  removeListener,
   sendErrorResponse,
   sendResponse,
   start,

package/src/iso18013/iso18013-5/proximity.ts

@@ -1,6 +1,6 @@
 import { NativeEventEmitter, Platform } from 'react-native';
+import type { AcceptedFields } from './request';
 import { IoReactNativeIso18013 } from '..';
-import type { AcceptedFields } from './schema';
 import type { RequestedDocument } from '../types';
 
 const eventEmitter = new NativeEventEmitter(IoReactNativeIso18013);
@@ -122,13 +122,5 @@ export function addListener<E extends Events>(
   event: E,
   callback: (data: EventsPayload[E]) => void
 ) {
-  eventEmitter.addListener(event, callback);
-}
-
-/**
- * Removes a listener for a `QrEngagementEvents` event.
- * @param event - The event to remove the listener for. The available events are defined in the `QrEngagementEvents` type.
- */
-export function removeListener(event: Events) {
-  eventEmitter.removeAllListeners(event);
+  return eventEmitter.addListener(event, callback);
 }

package/src/iso18013/iso18013-5/{schema.ts → request.ts}

@@ -44,26 +44,6 @@ export const parseVerifierRequest = (input: unknown): VerifierRequest => {
   return VerifierRequest.parse(input);
 };
 
-/**
- * Zod schema for the type returned by the `onError` event in Proximity `Events`.
- */
-const EventError = z.string().catch('Unknown error');
-
-/**
- * Error type returned by the `onError` event in Proximity `Events`.
- */
-export type EventError = z.infer<typeof EventError>;
-
-/**
- * Parses the input to an Error object.
- * This function is used to parse the error received from the verifier app via the `onError` event.
- * @param input - The input to be parsed
- * @returns The parsed Error object or a default error message if parsing fails
- */
-export const parseEventError = (input: unknown): EventError => {
-  return EventError.parse(input);
-};
-
 /**
  * This is the type definition for the accepted fields that will be presented to the verifier app.
  * It contains of a nested object structure, where the outermost key represents the credential doctype.

package/src/iso18013/iso18013-7/README.md

@@ -48,12 +48,41 @@ export const generateOID4VPDeviceResponse = async (
 ) : Promise<string> => {...};
 ```
 
-### Error Codes
-
-| Type                              | Platform    | Description                                                        |
-| --------------------------------- | ----------- | ------------------------------------------------------------------ |
-| UNABLE_TO_GENERATE_RESPONSE       | Android/iOS | Failure during the generation of a response                        |
-| DOC_REQUESTED_PARSING_EXCEPTION   | Android/iOS | The passed documents where in a bad format or contained wrong data |
-| REQUESTED_ITEMS_PARSING_EXCEPTION | iOS         | The passed items where in a bad format                             |
-| UNABLE_TO_GENERATE_TRANSCRIPT     | Android     | There has been an error generating the session transcript          |
-| UNKNOWN_EXCEPTION                 | Android/iOS | Unexpected failure                                                 |
+## Errors
+
+This table contains the list of error codes that can be thrown by the `ISO18013_7` module which are mapped via the `ModuleErrorCodes` type:
+
+| Type                           | Platform    | Description                                     |
+| ------------------------------ | ----------- | ----------------------------------------------- |
+| GENERATE_OID4VP_RESPONSE_ERROR | Android/iOS | An error occurred while generating the response |
+
+An error can be parsed using the `ModuleErrorSchema` with type `ModuleErrorCodes` exposed by the `ISO18013_5` module. The error can be parsed as follows:
+
+```typescript
+import { ISO18013_7 } from '@pagopa/io-react-native-iso18013';
+try {
+  await ISO18013_7.func();
+} catch (error) {
+  const parsedError = ISO18013_7.ModuleErrorSchema.parse(error); // Or ModuleErrorSchema.safeParse(error) for safe parsing
+  console.log(JSON.stringify(parsedError, null, 2));
+}
+```
+
+The parsed object will contain properties from both iOS and Android platforms:
+
+```typescript
+{
+  code: string; // Defined in ModuleErrorCodes
+  message: string;
+  name: string;
+  userInfo?: Record<string, any> | null;
+  nativeStackAndroid?: Array<{
+    lineNumber: number;
+    file: string;
+    methodName: string;
+    class: string;
+  }>;
+  domain?: string;
+  nativeStackIOS?: Array<string>;
+};
+```

package/src/iso18013/iso18013-7/error.ts

@@ -0,0 +1,21 @@
+import z from 'zod';
+import { GenericModuleErrorSchema } from '../../schema';
+
+/**
+ * Error codes which the ISO18013_7 module uses to reject a promise.
+ */
+const ModuleErrorCodesSchema = z.enum([
+  'GENERATE_OID4VP_RESPONSE_ERROR',
+  'EUNSPECIFIED', // Android only default when no other error is specified
+]);
+
+export type ModuleErrorCodes = z.infer<typeof ModuleErrorCodesSchema>;
+
+/**
+ * Schema which can be used to parse a rejected promise error by the ISO18013_7 module.
+ */
+export const ModuleErrorSchema = GenericModuleErrorSchema(
+  ModuleErrorCodesSchema
+);
+
+export type ModuleError = z.infer<typeof ModuleErrorSchema>;

package/src/iso18013/iso18013-7/index.ts

@@ -1,7 +1,8 @@
+export { generateOID4VPDeviceResponse } from './remote';
 export {
-  generateOID4VPDeviceResponse,
-  type OID4VPFailure,
-  type OID4VPFailureCodes,
-} from './remote';
+  ModuleErrorSchema,
+  type ModuleError,
+  type ModuleErrorCodes,
+} from './error';
 
 export { type RequestedDocument } from '../types';

package/src/iso18013/iso18013-7/remote.ts

@@ -1,26 +1,6 @@
 import { IoReactNativeIso18013 } from '..';
 import type { RequestedDocument } from '../types';
 
-/**
- * All error codes that the module could return.
- */
-export type OID4VPFailureCodes =
-  | 'UNABLE_TO_GENERATE_RESPONSE'
-  | 'UNABLE_TO_GENERATE_TRANSCRIPT'
-  | 'INVALID_DOC_REQUESTED'
-  | 'GENERATE_OID4VP_DEVICE_RESPONSE_FAILED';
-
-/**
- * Error type returned by a rejected promise.
- *
- * If additional error information are available,
- * they are stored in the {@link OID4VPFailure["userInfo"]} field.
- */
-export type OID4VPFailure = {
-  message: OID4VPFailureCodes;
-  userInfo: Record<string, string>;
-};
-
 /**
  *
  * @param clientId extracted from OID4VP session

package/src/schema.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+
+/**
+ * Schema for parsing a nativeStackAndroid object of a rejected promise error in an Android native module.
+ */
+const StackTraceElementSchema = z.object({
+  lineNumber: z.number(),
+  file: z.string(),
+  methodName: z.string(),
+  class: z.string(),
+});
+
+/**
+ * Schema for parsing specific parameters of a rejected promise error in an Android native module.
+ * It's defined as partial to allow merging with the common schema and it must be checked at runtime.
+ */
+const ModuleErrorAndroidSchema = z
+  .object({
+    nativeStackAndroid: z.array(StackTraceElementSchema),
+  })
+  .partial();
+
+/**
+ * Schema for parsing specific parameters of a rejected promise error in an iOS native module.
+ * It's defined as partial to allow merging with the common schema and it must be checked at runtime.
+ */
+const ModuleErrorIosSchema = z
+  .object({
+    domain: z.string(),
+    nativeStackIOS: z.array(z.string()),
+  })
+  .partial();
+
+/**
+ * Schema for parsing common parameters of a rejected promise error in a native module.
+ * This schema contains the common parameters that are shared across both Android and iOS native modules.
+ * Parameters which are platform specific are defined as optional and must be checked at runtime.
+ * It accepts a generic code schema to allow for different error codes which can be defined in each module.
+ * @param codeSchema - The Zod schema for the error codes used by the module.
+ * @returns A schema for the common parameters of a rejected promise error in a native module.
+ */
+export const GenericModuleErrorSchema = <
+  CodeType extends z.ZodEnum<[string, ...string[]]>,
+>(
+  codeSchema: CodeType
+) =>
+  z
+    .object({
+      code: codeSchema,
+      message: z.string(),
+      name: z.string(),
+      userInfo: z.record(z.string(), z.any()).optional().or(z.null()),
+    })
+    .and(ModuleErrorAndroidSchema)
+    .and(ModuleErrorIosSchema);

package/lib/module/cbor/cbor/failure.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=failure.js.map

package/lib/module/cbor/cbor/failure.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["cbor/cbor/failure.ts"],"mappings":"","ignoreList":[]}

package/lib/module/cbor/cose/failure.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=failure.js.map

package/lib/module/cbor/cose/failure.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["cbor/cose/failure.ts"],"mappings":"","ignoreList":[]}

package/lib/module/iso18013/iso18013-5/schema.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["z","booleanFieldGroup","record","boolean","credentialEntrySchema","object","isAuthenticated","catchall","VerifierRequest","request","parseVerifierRequest","input","parse","EventError","string","catch","parseEventError"],"sourceRoot":"../../../../src","sources":["iso18013/iso18013-5/schema.ts"],"mappings":";;AAAA,SAASA,CAAC,QAAQ,KAAK;;AAEvB;AACA,MAAMC,iBAAiB,GAAGD,CAAC,CAACE,MAAM,CAACF,CAAC,CAACG,OAAO,CAAC,CAAC,CAAC;AAE/C,MAAMC,qBAAqB,GAAGJ,CAAC,CAC5BK,MAAM,CAAC;EACNC,eAAe,EAAEN,CAAC,CAACG,OAAO,CAAC;AAC7B,CAAC,CAAC,CACDI,QAAQ,CAACN,iBAAiB,CAAC;AAE9B,MAAMO,eAAe,GAAGR,CAAC,CAACK,MAAM,CAAC;EAC/BI,OAAO,EAAET,CAAC,CAACE,MAAM,CAACE,qBAAqB;AACzC,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMM,oBAAoB,GAAIC,KAAc,IAAsB;EACvE,OAAOH,eAAe,CAACI,KAAK,CAACD,KAAK,CAAC;AACrC,CAAC;;AAED;AACA;AACA;AACA,MAAME,UAAU,GAAGb,CAAC,CAACc,MAAM,CAAC,CAAC,CAACC,KAAK,CAAC,eAAe,CAAC;;AAEpD;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAIL,KAAc,IAAiB;EAC7D,OAAOE,UAAU,CAACD,KAAK,CAACD,KAAK,CAAC;AAChC,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","ignoreList":[]}

package/lib/typescript/src/cbor/cbor/failure.d.ts

@@ -1,15 +0,0 @@
-/**
- * All error codes that the module could return.
- */
-export type CborFailureCodes = 'UNABLE_TO_DECODE' | 'INVALID_ENCODING' | 'UNKNOWN_EXCEPTION';
-/**
- * Error type returned by a rejected promise.
- *
- * If additional error information are available,
- * they are stored in the {@link CborFailure["userInfo"]} field.
- */
-export type CborFailure = {
-    message: CborFailureCodes;
-    userInfo: Record<string, string>;
-};
-//# sourceMappingURL=failure.d.ts.map

package/lib/typescript/src/cbor/cbor/failure.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../../../../src/cbor/cbor/failure.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC"}

package/lib/typescript/src/cbor/cose/failure.d.ts

@@ -1,15 +0,0 @@
-/**
- * All error codes that the module could return.
- */
-export type CoseFailureCodes = 'PUBLIC_KEY_NOT_FOUND' | 'UNABLE_TO_SIGN' | 'INVALID_ENCODING' | 'THREADING_ERROR' | 'UNKNOWN_EXCEPTION';
-/**
- * Error type returned by a rejected promise.
- *
- * If additional error information are available,
- * they are stored in the {@link CoseError["userInfo"]} field.
- */
-export type CoseFailure = {
-    message: CoseFailureCodes;
-    userInfo: Record<string, string>;
-};
-//# sourceMappingURL=failure.d.ts.map

package/lib/typescript/src/cbor/cose/failure.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../../../../src/cbor/cose/failure.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,sBAAsB,GACtB,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC"}

package/lib/typescript/src/iso18013/iso18013-5/schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../../src/iso18013/iso18013-5/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;EAEnB,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,eAErD,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,UAAU,yBAAoC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,UAEhD,CAAC;AAEF;;;;;;;;;;;;;;;IAeI;AACJ,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,CAAC,SAAS,EAAE,MAAM,GAAG;YAAE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;KACnD,CAAC;CACH,CAAC"}

package/src/cbor/cbor/failure.ts

@@ -1,18 +0,0 @@
-/**
- * All error codes that the module could return.
- */
-export type CborFailureCodes =
-  | 'UNABLE_TO_DECODE'
-  | 'INVALID_ENCODING'
-  | 'UNKNOWN_EXCEPTION';
-
-/**
- * Error type returned by a rejected promise.
- *
- * If additional error information are available,
- * they are stored in the {@link CborFailure["userInfo"]} field.
- */
-export type CborFailure = {
-  message: CborFailureCodes;
-  userInfo: Record<string, string>;
-};

package/src/cbor/cose/failure.ts

@@ -1,20 +0,0 @@
-/**
- * All error codes that the module could return.
- */
-export type CoseFailureCodes =
-  | 'PUBLIC_KEY_NOT_FOUND'
-  | 'UNABLE_TO_SIGN'
-  | 'INVALID_ENCODING'
-  | 'THREADING_ERROR'
-  | 'UNKNOWN_EXCEPTION';
-
-/**
- * Error type returned by a rejected promise.
- *
- * If additional error information are available,
- * they are stored in the {@link CoseError["userInfo"]} field.
- */
-export type CoseFailure = {
-  message: CoseFailureCodes;
-  userInfo: Record<string, string>;
-};