cordova-digital-onboarding 1.1.0 → 1.2.0

package/docs/Changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.2.0 (Jan, 2026)
+
+- **Breaking:** New `finishActivation` state in `WDOVerificationService` to complete the user verification process by activating a new PowerAuth instance.
+  - New method must be called by the client when handling the `finishActivation` state in the verification flow, i.e. after all verification steps (identity, documents, presence, etc.) have succeeded but before the new `PowerAuth` instance is used anywhere else in the app: `finishActivation(newPaInstance: PowerAuth, activationName: string, password: WDOPowerAuthPassword, validatePassword: boolean)`.
+- **Breaking:** Changed configuration endpoint response to include document groups instead of a flat list of documents.
+
 ## 1.1.0 (Dec, 2025)
 
 - PowerAuth Cordova SDK dependency now requires v. `4.2.0`.

package/docs/Device-Activation.md

@@ -13,18 +13,21 @@ PowerAuth enrolled in such a way will need [further user verification](Verifying
 To create an instance you will need a `PowerAuth` instance that is __ready to be activated__.
 
 <!-- begin box info -->
-[Documentation for `PowerAuth Mobile JS SDK`](https://developers.wultra.com/components/react-native-powerauth-mobile-sdk/). 
+[Documentation for the `PowerAuth Mobile JS SDK`](https://developers.wultra.com/components/react-native-powerauth-mobile-sdk/). 
 <!-- end -->
 
 
 Example with `PowerAuth` instance:
 
 ```typescript
+// create and configure PowerAuth instance
 const powerAuth = new PowerAuth("my-pa-instance")
-powerAuth.configure({
+await powerAuth.configure({
     configuration: "ARCB+...jg==", // base64 PowerAuth configuration
     baseEndpointUrl: "https://my-server-deployment.com/enrollment-server/"
 })
+
+// create activation service
 const activationService = new WDOActivationService(
     powerAuth,
     "https://my-server-deployment.com/enrollment-server-onboarding/"
@@ -36,13 +39,13 @@ const activationService = new WDOActivationService(
 To figure out if the activation process was already started and what is the status, you can use `hasActiveProcess`.
 
 ```typescript
-/**
- * If the activation process is in progress.
- *
+/** 
+ * If the activation process is in progress. 
+ * 
  * Note that even if this property is `true` it can be already discontinued on the server.
- * Calling `status()` for example after the app is launched in this case is recommended.
+ * Calling `status()` after the app is launched is recommended.
  */
-get hasActiveProcess(): boolean;
+hasActiveProcess(): Promise<boolean>
 ```
 
 If the process was started, you can verify its status by calling the `status` function. You can show an appropriate UI to the user based on this status.
@@ -53,7 +56,7 @@ If the process was started, you can verify its status by calling the `status` fu
  *
  * @return Promise resolved with onboarding status.
  */
-status(): Promise<WDOOnboardingStatus>;
+status(): Promise<WDOOnboardingStatus>
 ```
 
 `WDOOnboardingStatus` possible values.
@@ -75,30 +78,29 @@ declare enum WDOOnboardingStatus {
 
 To start the activation process, you can use any credentials that are sufficient to you that can identify the user.
 
-Often, such data are user email, phone number, or userID. The definition of such data is up to your server implementation and requirements.
+Often, such data are user email, phone number, or user ID. The definition of such data is up to your server implementation and requirements.
 
 To start the activation, use the `start` function.
 
 ```typescript
 /**
-     * Start onboarding activation with user credentials.
-     *
-     * For example, when you require email, your object would look like this:
-     * ```
-     * {
-     *   email: "<user_email>"
-     * }
-     * ```
-     * @param credentials Object with credentials. Which credentials are needed should be provided by a system/backend provider.
-     * @param processType The process type identification. If not specified, the default process type will be used.
-     */
-    start(credentials: any, processType?: string): Promise<void>;
+ * Start onboarding activation with user credentials.
+ *
+ * For example, when you require email, your object would look like this:
+ * ```
+ * {
+ *   email: "<user_email>"
+ * }
+ * ```
+ * @param credentials Object with credentials. Which credentials are needed should be provided by a system/backend provider.
+ * @param processType The process type identification. If not specified, the default process type will be used.
+ */
+start(credentials: any, processType?: string): Promise<void>
 ```
 
 ### Example
 
 ```typescript
-
 class MyUserService {
     // prepared service
     private activationService: WDOActivationService
@@ -106,9 +108,9 @@ class MyUserService {
     async startActivation(id: string) {
         const data = { userId: id}
         try {
-            await this.activationService.start(data)
-            // success, continue with `activate()`
-            // at this moment, the `hasActiveProcess` starts return true
+            await this.activationService.start(data, "onboarding")
+            // success, continue with the flow
+            // at this moment, the `hasActiveProcess` starts returning true
         } catch (error) {
             // show error to the user
         }
@@ -118,7 +120,7 @@ class MyUserService {
 
 ## Creating the activation
 
-To activate the user (activating the `PowerAuth` instance), data retrieved from the process start can be used with optional `OTP`. The OTP is usually sent via SMS, email, or other channel. To decide if the OTP is needed, you can use the [Configuration API](Process-Configuration.md) or have it hardcoded.
+To activate the user (activating the `PowerAuth` instance), data retrieved from the process start can be used with optional `OTP`. The OTP is usually sent via SMS, email, or other channel. To decide if the OTP is needed, you can use the [Configuration API](Process-Configuration.md) or have it hard-coded.
 
 Use the `activate` function to create the activation.
 
@@ -130,7 +132,7 @@ Use the `activate` function to create the activation.
  * @param otp OTP code received by the user (via SMS or email). Optional when not required.
  * @return Promise resolved with activation result.
  */
-activate(activationName: string, otp?: string): Promise<WDOPowerAuthActivationResult>;
+activate(activationName: string, otp?: string): Promise<WDOPowerAuthActivationResult>
 ```
 
 Example implementation:
@@ -169,14 +171,14 @@ To cancel the process, just call the `cancel` function.
  *
  * @param forceCancel When true, the process will be canceled in the SDK even when fails on backend. `true` by default.
  */
-cancel(forceCancel?: boolean): Promise<void>;
+cancel(forceCancel?: boolean): Promise<void>
 ```
 
 ## OTP resend
 
 In some cases, you need to resent the OTP:  
- - OTP was not received by the user (for example when the email ends in the spam folder).  
- - OTP expired. 
+ - OTP was not received by the user (for example when the email ends in the spam folder) 
+ - OTP expired 
 
  For such cases, use `resendOTP` function.
  
@@ -186,9 +188,11 @@ In some cases, you need to resent the OTP:
 *
 * This is intended to be displayed for the user to use in case of the OTP is not received.
 * For example, when the user does not receive SMS after some time, there should be a button to "send again".
+* There is a server-side rate limit applied to this operation to prevent abuse; it is good practice to disable the button temporarily while the OTP is being sent.
 */
-resendOTP(): Promise<void>;
+resendOTP(): Promise<void>
  ```
 
 ## Read next
-- [Verifying User With Document Scan And Genuine Presence Check](Verifying-User.md)
+
+- [Verifying the User](Verifying-User.md)

package/docs/Process-Configuration.md

@@ -9,19 +9,21 @@ To retrieve the configuration, create an instance of `WDOConfigurationService` a
 Example:
 
 ```typescript
-
+// create and configure PowerAuth instance
 const powerAuth = new PowerAuth("my-pa-instance")
-powerAuth.configure({
+await powerAuth.configure({
     configuration: "ARCB+...jg==", // base64 PowerAuth configuration
     baseEndpointUrl: "https://my-server-deployment.com/enrollment-server/"
 })
+
+// create configuration service
 const configurationService = new WDOConfigurationService(
     powerAuth,
     "https://my-server-deployment.com/enrollment-server-onboarding/"
 )
 
-const procesType = "onboarding" // defined on your server
-const config = await configurationService.getConfiguration(procesType)
+const processType = "onboarding" // defined on your server (can be undefined for default process type)
+const config = await configurationService.getConfiguration(processType)
 console.log("Configuration:", config)
 ```
 
@@ -31,27 +33,34 @@ console.log("Configuration:", config)
 /** Configuration for the onboarding process */
 interface WDOConfigurationResponse {
     /** Is the onboarding process enabled */
-    enabled: boolean;
+    enabled: boolean
     /** Is OTP required for the first part - identification/activation. */
-    otpForIdentification: boolean;
+    otpForIdentification: boolean
     /** Is OTP required for the second part - identity verification. */
-    otpForIdentityVerification: boolean;
+    otpForIdentityVerification: boolean
     /** Documents required for identity verification. */
     documents: {
-        /** Number of required documents */
-        requiredDocumentsCount: number;
-        /** List of documents */
-        items: Array<WDOConfigurationDocument>;
+        /** Number of total required documents */
+        totalRequiredDocumentsCount: number
+        /** Groups of documents */
+        groups: Array<WDOConfigurationDocumentGroup>
     }
 }
+
+/** Group of documents in the configuration */
+interface WDOConfigurationDocumentGroup {
+    /** Number of required documents in the group */
+    requiredDocumentsCount: number
+    /** Documents in the group */
+    items: Array<WDOConfigurationDocument>
+}
+
 /** Configuration for a document */
 interface WDOConfigurationDocument {
     /** Type of the document */
-    type: string;
-    /** Is the document mandatory */
-    mandatory: boolean;
+    type: string
     /** Number of sides the document has */
-    sideCount: number;
+    sideCount: number
 }
 ```
 

package/docs/Verifying-User.md

@@ -1,14 +1,16 @@
-# Verifying user
+# Verifying the User
 
-If your PowerAuthSDK instance was activated with the `WDOActivationService`, it will be in the state that needs additional verification. Without such verification, it won't be able to properly sign requests.
+If your `PowerAuth` instance was activated via the `WDOActivationService`, it will be in the state that needs additional verification. Without such verification, it won't be able to properly sign requests.
 
-Additional verification means that the user will need to scan his face and documents like ID and/or passport.
+Additional verification requires the user to scan their face and provide documents such as an ID card or passport.
 
 ## When is the verification needed?
 
 Verification is needed if the `activationFlags` in the `PowerAuthActivationStatus` contains `VERIFICATION_PENDING` or `VERIFICATION_IN_PROGRESS` value.
 
+<!-- begin box info -->
 To simplify this check, you can use the `WDOVerificationService.isVerificationRequired` method that returns a boolean indicating whether verification is required.
+<!-- end -->
 
 Example:
 
@@ -42,65 +44,71 @@ The final flow (which screens come after another) is controlled by the backend.
 - The screen that should be displayed is driven by the state on the server "session".   
 - At the beginning of the verification process, you will call the status which will tell you what to display to the user and which function to call next.
 - Each API call returns a result and a next screen to display.
-- This repeats until the process is finished or an "endstate state" is presented which terminates the process.
+- This repeats until the process is finished or an "end state" is presented which terminates the process.
 
 ## Possible state values
 
-State is defined by the `WDOVerificationStateType` enum with the following possibilities:
+State is defined by the `WDOVerificationStateType` with the following possibilities:
 
 ```typescript
 /** Types of the verification state */
-declare enum WDOVerificationStateType {
-    /**
-     * Show the verification introduction screen where the user can start the activation.
-     *
-     * The next step should be calling the `consentGet()`.
+enum WDOVerificationStateType {
+    /** 
+     * Show the verification introduction screen where the user can start the activation. 
+     * 
+     * The next step should be calling the `start()`.
      */
     intro = "intro",
     /**
      * 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`.
      */
     documentsToScanSelect = "documentsToScanSelect",
     /**
      * User should scan documents - display UI for the user to scan all necessary documents.
-     *
+     * 
      * The next step should be calling the `documentsSubmit`.
      */
     scanDocument = "scanDocument",
-    /**
+    /** 
      * The system is processing data - show loading with text hint from provided `WDOStatusCheckReason`.
-     *
+     * 
      * The next step should be calling the `status`.
      */
     processing = "processing",
-    /**
+    /** 
      * 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.
      */
     presenceCheck = "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.
      */
     otp = "otp",
+    /**
+     * Show "finish activation" with PIN prompt screen.
+     * 
+     * The next step should be calling the `finishActivation` with user entered PIN.
+     */
+    finishActivation = "finishActivation",
     /**
      * 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.
      */
     failed = "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.
      */
     endState = "endState",
@@ -123,6 +131,7 @@ export type WDOVerificationState =
     | WDOProcessingState
     | WDOPresenceCheckState
     | WDOOtpState
+    | WDOFinishActivation
     | WDOFailedState
     | WDOEndStateState
     | WDOSuccessState
@@ -193,6 +202,15 @@ export interface WDOOtpState {
     remainingAttempts?: number
 }
 
+/**
+ * Show "finish activation" with PIN prompt screen.
+ * 
+ * The next step should be calling the `finishActivation` with user entered PIN.
+ */
+export interface WDOFinishActivation {
+    type: WDOVerificationStateType.finishActivation
+}
+
 /**
  * Verification failed and can be restarted
  * 
@@ -233,11 +251,14 @@ To create an instance you will need a `PowerAuth` instance that is __already act
 
 Example:
 ```typescript
+// create and configure PowerAuth instance
 const powerAuth = new PowerAuth("my-pa-instance")
-powerAuth.configure({
+await powerAuth.configure({
     configuration: "ARCB+...jg==", // base64 PowerAuth configuration
     baseEndpointUrl: "https://my-server-deployment.com/enrollment-server/"
 })
+
+// create activation service
 const verification = new WDOVerificationService(
     powerAuth,
     "https://my-server-deployment.com/enrollment-server-onboarding/"
@@ -246,11 +267,11 @@ const verification = new WDOVerificationService(
 
 ## Getting the verification status
 
-When entering the verification flow for the first time (for example fresh app start), you need to retrieve the state of the verification.
+When starting the verification flow for the first time (such as after a fresh app launch), you should retrieve the current verification state.
 
-The same needs to be done after some operation fails and it's not sure what is the next step in the verification process.
+You should also retrieve the state after any operation fails, or whenever you are unsure about the next step in the verification process.
 
-Most verification functions return the result and also the state for your convenience of "what next".
+Most verification functions return both the result and the updated state, making it easier to determine what action to take next.
 
 Getting the state directly:
 
@@ -261,10 +282,6 @@ try {
     // 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
     }
@@ -309,13 +326,14 @@ try {
 
 ## Set document types to scan
 
-After the user approves the consent, present a document selector for documents which will be scanned. The number and types of documents (or other rules like 1 type required) are completely dependent on your backend system integration. You can retrieve the list of available document types from the [configuration service](Process-Configuration.md).
+After the user approves the consent, present a document selector for documents which will be scanned. The number and types of documents (or other rules like 1 type required) are completely dependent on your backend system integration. You can retrieve the list of available document types from the [configuration service](Process-Configuration.md) or have it hard-coded.
 
 For example, your system might require a national ID and one additional document like a driver's license, passport, or any other government-issued personal document.
 
 ```typescript
 const verification: WDOVerificationService // configured instance
 try {
+    // assuming user selected ID card and driver's license
     const docTypesResult = await verification.documentsSetSelectedTypes([
         WDODocumentType.idCard,
         WDODocumentType.driversLicense
@@ -338,7 +356,7 @@ This step does not move the state of the process but is a "stand-alone" API call
 
 Since the document scanning itself is not provided by this library but by a 3rd party library, some of them need a server-side initialization.
 
-If your chosen scanning SDK requires such a step, use this function to retrieve necessary data from the server.
+If your chosen "document scan SDK" requires such a step, use this function to retrieve necessary data from the server.
 
 Example:
 
@@ -367,7 +385,7 @@ for your implementation.
 When a document is scanned (both sides when required), it needs to be uploaded to the server.
 
 <!-- begin box warning -->
-__Images of the document should not be bigger than 1MB. Files that are too big will take longer time to upload and process on the server.__
+__Images of the document should not be bigger than hundreds of kilobytes. Files that are too big will take longer time to upload and process on the server.__
 <!-- end -->
 
 To upload a document, use `documentsSubmit` function. Each side of a document is a single `WDODocumentFile` instance.
@@ -381,8 +399,8 @@ const passportToUpload = WDODocumentFile(
     "BASE64_ENCODED_IMAGE_DATA", // raw image data from the document scanning library/photo camera
     WDODocumentType.passport,
     WDODocumentSide.front, // passport has only front side
-    undefined, // use only when re-uploading the file (for example when first upload was rejected because of a blur)
-    undefined // optional, use when provided by the document scanning library
+    undefined, // original id, optional (use only when re-uploading the file - for example when first upload was rejected because of a blur)
+    undefined // signature, optional (use when provided by the document scanning library)
 )
 try {
     const result = await verification.documentsSubmit([passportToUpload])
@@ -474,6 +492,35 @@ try {
 }
 ```
 
+## Finalizing the verification (optional)
+
+When the state `finishActivation` is received, prompt the user for a PIN code. 
+
+This PIN code is then used to activate a new `PowerAuth` object that will be used for signing requests.
+
+Once the new `PowerAuth` instance is activated, the verification process is finished, and the user can proceed to the main app flow *with the new `PowerAuth` instance*.
+
+<!-- begin box info -->
+If the user's PIN used for the original activation should be equal to the one used for the new activation, then:
+- Set the `validatePassword` parameter to `true` in the `finishActivation` call. 
+- The `PowerAuthPassword` passed to the `finishActivation` needs to be reusable (`destroyOnUse` set to false - `new PowerAuthPassword(false)`).
+<!-- end -->
+
+Example:
+
+```typescript
+const verification: WDOVerificationService // configured instance
+const newPaInstance: PowerAuth // new PowerAuth instance to be activated and then used in the app
+try {
+    const password = await PowerAuthPassword.fromString("user-password", false) // reusable password
+    const finishResult = await verification.finishActivation(newPaInstance, "my-new-activation-name", password, true)
+    // When here, the newPaInstance is activated and ready to use (to sign requests and so on).
+    // The original PowerAuth instance used for the verification will be in the `REMOVED` state and the `verification` instance can't be used anymore.
+} catch (error) {
+    // handle error
+}
+```
+
 ## Success state
 
 When a whole verification is finished, you will receive the `success` state. Show a success screen and navigate the user to a common activated flow.

package/docs/_Sidebar.md

@@ -3,7 +3,7 @@
 - [SDK Integration](SDK-Integration.md)
 - [Process Configuration](Process-Configuration.md)
 - [Device Activation (With Weak Credentials)](Device-Activation.md)
-- [Verifying User With Document Scan And Genuine Presence Check](Verifying-User.md)
+- [Verifying the User](Verifying-User.md)
 - [Language Configuration](Language-Configuration.md)
 - [Logging](Logging.md)