cordova-digital-onboarding 1.0.1 → 1.1.0

package/docs/Changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0 (Dec, 2025)
+
+- PowerAuth Cordova SDK dependency now requires v. `4.2.0`.
+- Process cache is now persistent across app restarts.
+- Changes to `WDOError`:
+    - added `reason: WDOErrorReason` property to specify the error cause.
+    - added `allowOnboardingOtpRetry: boolean` property to indicate if OTP retry is allowed (during activation failure).
+    - modified `onboardingOtpRemainingAttempts` to parse the remaining attempts from the original exception (during activation failure).
+- `WDOActivaitonService` changes:
+   - `hasActiveProcess()` now returns Promise<boolean> instead of boolean. 
+   - `clear()` is now asynchronous and returns Promise<void>.
+- `WDOActivaitonService` changes:
+   - removed `consent` state
+   - replaced `consentApprove` with `start` method with a `consent` argument.
+   - `consentGet` now returns Promise<string> instead of the verification state.
+   - `documentsInitSDK` method now returns strongly typed response.
+   - `presenceCheckInit` method now returns strongly typed response.
+   - `intro` state now contains `consentRequired: boolean` property in the corresponding union type.
+
 ## 1.0.0 (Nov, 2025)
 
 Initial release.

package/docs/Device-Activation.md

@@ -126,7 +126,7 @@ Use the `activate` function to create the activation.
 /**
  * Activate the PowerAuth instance that was passed in the initializer.
  *
- * @param activationName Name of the activation. Device name by default (usually something like John's iPhone or similar).
+ * @param activationName Name of the activation. Usually something like John's iPhone or similar.
  * @param otp OTP code received by the user (via SMS or email). Optional when not required.
  * @return Promise resolved with activation result.
  */
@@ -148,9 +148,9 @@ class MyUserService {
             // the PIN keyboard to finish the PowerAuthSDK initialization.
             // For more information, follow the PowerAuthSDK documentation.
         } catch (error) {
-            if (allowOnboardingOtpRetry(error)) {
+            if (error instanceof WDOError && error.allowOnboardingOtpRetry) {
                 // User entered the wrong OTP, prompt for a new one.
-                // Remaining OTP attempts count: onboardingOtpRemainingAttempts(error)
+                // Remaining OTP attempts count: error.onboardingOtpRemainingAttempts
             } else {
                 // show error UI
             }

package/docs/Verifying-User.md

@@ -57,14 +57,6 @@ declare enum WDOVerificationStateType {
      * The next step should be calling the `consentGet()`.
      */
     intro = "intro",
-    /**
-     * Show approve/cancel user consent.
-     *
-     * The content of the text depends on the server configuration and might be plain text or HTML.
-     *
-     * The next step should be calling the `consentApprove`.
-     */
-    consent = "consent",
     /**
      * Show document selection to the user. Which documents are available and how many
      * can the user select is up to your backend configuration.
@@ -119,6 +111,117 @@ declare enum WDOVerificationStateType {
 }
 ```
 
+Based on the type value, additional data is provided in the union type `WDOVerificationState`.
+
+Available data per state type:
+
+```typescript
+export type WDOVerificationState =
+    | WDOIntroState
+    | WDODocumentsToScanSelectState
+    | WDOScanDocumentState
+    | WDOProcessingState
+    | WDOPresenceCheckState
+    | WDOOtpState
+    | WDOFailedState
+    | WDOEndStateState
+    | WDOSuccessState
+
+/** 
+ * Show the verification introduction screen where the user can start the activation. 
+ * 
+ * The next step should be calling the `start`.
+ */
+export interface WDOIntroState {
+    type: WDOVerificationStateType.intro,
+    /** Indicates whether the user consent is required to proceed */
+    consentRequired: boolean
+}
+
+/**
+ * Show document selection to the user. Which documents are available and how many
+ * can the user select is up to your backend configuration.
+ * 
+ * The next step should be calling the `documentsSetSelectedTypes`.
+ */
+export interface WDODocumentsToScanSelectState {
+    type: WDOVerificationStateType.documentsToScanSelect
+}
+
+/**
+ * User should scan documents - display UI for the user to scan all necessary documents.
+ * 
+ * The next step should be calling the `documentsSubmit`.
+ */
+export interface WDOScanDocumentState {
+    type: WDOVerificationStateType.scanDocument
+    /** Scanning process that helps with the document scanning */
+    process: WDOVerificationScanProcess
+}
+
+/** 
+ * The system is processing data - show loading with text hint from provided `WDOStatusCheckReason`.
+ * 
+ * The next step should be calling the `status`.
+ */
+export interface WDOProcessingState {
+    type: WDOVerificationStateType.processing
+    /** Reason for the current processing state */
+    item: WDOStatusCheckReason
+}
+
+/** 
+ * The user should be presented with a presence check.
+ * Presence check is handled by third-party SDK based on the project setup.
+ * 
+ * The next step should be calling the `presenceCheckInit` to start the check and `presenceCheckSubmit` to
+ * mark it finished.  Note that these methods won't change the status and it's up to the app to handle the process of the presence check.
+ */
+export interface WDOPresenceCheckState {
+    type: WDOVerificationStateType.presenceCheck
+}
+
+/**
+ * Show enter OTP screen with resend button.
+ * 
+ * The next step should be calling the `verifyOTP` with user-entered OTP.
+ * The OTP is usually SMS or email.
+ */
+export interface WDOOtpState {
+    type: WDOVerificationStateType.otp
+    /** Number of remaining attempts to enter the correct OTP */
+    remainingAttempts?: number
+}
+
+/**
+ * Verification failed and can be restarted
+ * 
+ * The next step should be calling the `restartVerification` or `cancelWholeProcess` based on
+ * the user's decision if he wants to try it again or cancel the process.
+ */
+export interface WDOFailedState {
+    type: WDOVerificationStateType.failed
+}
+
+/**
+ * Verification is canceled and the user needs to start again with a new PowerAuth activation.
+ * 
+ * The next step should be calling the `PowerAuth.removeActivationLocal()` and starting activation from scratch.
+ */
+export interface WDOEndStateState {
+    type: WDOVerificationStateType.endState
+    /** Reason for the end state */
+    reason: WDOEndStateReason
+}
+
+/**
+ * Verification was successfully ended. Continue into your app flow.
+ */
+export interface WDOSuccessState {
+    type: WDOVerificationStateType.success
+}
+```
+
 ## Creating an instance
 
 To create an instance you will need a `PowerAuth` instance that is __already activated__.
@@ -156,6 +259,16 @@ const verification: WDOVerificationService // configured instance
 try {
     const vfStatus = await verification.status()
     // handle `WDOVerificationState` state and navigate to the expected screen
+    if (vfStatus.type === WDOVerificationStateType.intro) {
+        // display intro screen
+        const consentRequired = vfStatus.consentRequired // accessible based on union type 'intro'
+        // show consent info if needed
+        verification.start(WDOConsentResponse.approved) // example of starting the process
+
+    } else if (vfStatus.type === WDOVerificationStateType.documentsToScanSelect) {
+        // display document selector
+    }
+    // ... other states
 } catch (error) {
     if (error.verificationState) {
         // show expected screen based on the state
@@ -165,37 +278,26 @@ try {
 }
 ```
 
-## Getting the user consent text
+## Starting the identity verification
 
-When the state is `intro`, the first step in the flow is to get the context text for the user to approve.
+When the state is `intro`, the first step in the flow is to start the verification process by calling `start` function.
 
 ```typescript
+const state: WDOVerificationState // we're assuming that the state is `intro` here (WDOIntroState)
 const verification: WDOVerificationService // configured instance
 try {
-    const consentTextResponse = await verification.consentGet()
-    // state will be in the `consent` case here - display the consent screen
-} catch (error) {
-    if (error.verificationState) {
-        // show expected screen based on the state
+    let consentResult: WDOConsentResponse
+    const introState = state as WDOIntroState
+    if (introState.consentRequired) {
+        const consentTextResponse = await verification.consentGet()
+        // show consent screen to the user and get his approval
+        // assuming user approved the consent here
+        consentResult = WDOConsentResponse.approved
     } else {
-        // navigate to error screen
+        consentResult = WDOConsentResponse.notRequired
     }
-}
-```
-
-## Approving the user consent
-
-When the state is `consent`, you should display the consent text to the user to approve or reject.
-
-If the user __rejects the consent__, just return him to the intro screen, there's no API call for reject.
-
-If the user chooses to accept the consent, call `consentApprove` function. If successful, `documentsToScanSelect` state will be returned.
-
-```typescript
-const verification: WDOVerificationService // configured instance
-try {
-    const approvalResult = await verification.consentApprove()
-    // state will be in the `documentsToScanSelect` case here - display the document selector
+    const startResult = await verification.start(consentResult)
+    // process the returned state, should be `documentsToScanSelect` now
 } catch (error) {
     if (error.verificationState) {
         // show expected screen based on the state
@@ -238,6 +340,15 @@ Since the document scanning itself is not provided by this library but by a 3rd
 
 If your chosen scanning SDK requires such a step, use this function to retrieve necessary data from the server.
 
+Example:
+
+```typescript
+const verification: WDOVerificationService // configured instance
+const challengeFromSDK = "..." // optional challenge from the scanning SDK
+const initResult = await verification.documentsInitSDK(challengeFromSDK)
+// use the `initResult` to initialize the scanning SDK
+```
+
 ## Scanning a document
 
 When the state of the process is `scanDocument` with the `WDOVerificationScanProcess` parameter, you need to present a document scan UI to the user. This UI needs