@notabene/javascript-sdk 2.9.1-next.1 → 2.9.2

package/README.md

@@ -43,6 +43,11 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
     - [Parameters](#parameters-2)
   - [Deposit Assist](#deposit-assist)
     - [Parameters](#parameters-3)
+  - [Counterparty Assist](#counterparty-assist)
+    - [Use Cases](#use-cases)
+    - [Counterparty Assist Configuration](#counterparty-assist-configuration)
+    - [Component Response](#component-response)
+    - [Retrieving Completed Data](#retrieving-completed-data)
   - [Error handling](#error-handling)
       - [Error reference](#error-reference)
   - [Transaction parameters](#transaction-parameters)
@@ -63,6 +68,7 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
     - [Counterparty Field Properties](#counterparty-field-properties)
       - [Full Example](#full-example)
       - [Field reference](#field-reference)
+    - [Configure Counterparty Assist](#counterparty-assist-configuration)
   - [Locales](#locales)
   - [Theming](#theming)
   - [License](#license)
@@ -430,6 +436,194 @@ If any of the required parameters are missing the component will just show the N
 
 ---
 
+## Counterparty Assist
+
+The **Counterparty Assist** feature enables handoff of data collection to a counterparty or to another device by sharing a secure link. This facilitates more accurate and complete data collection, particularly when the counterparty is able to provide the required information directly.
+
+This feature can be enabled globally for all counterparty types or selectively for specific types.
+
+### Use Cases
+
+#### Third Parties (`natural`, `legal`)
+
+During the counterparty data collection step, users can generate and share a link to allow third-party counterparties (individuals or organizations) to enter their own data. This ensures data accuracy and supports robust address verification by allowing the rightful owner to provide the necessary information.
+
+#### First Parties (`self`)
+
+During the address verification step, users can share a link to complete self-hosted wallet proof submissions on another device. This is especially useful if the original device used to initiate the process doesn't support signing or wallet access.
+
+### Counterparty Assist Configuration
+
+You can enable **Counterparty Assist** via the `counterpartyAssist` configuration field in one of the following ways:
+
+- `true`: Enable for all counterparty types (`self`, `natural`, and `legal`)
+- `false`: Disable the feature entirely
+- `{ counterpartyTypes: [PersonType.SELF, PersonType.NATURAL, PersonType.LEGAL] }`: Enable for specific counterparty types
+
+**Example Config**
+
+```ts
+import Notabene, {
+  PersonType,
+} from '@notabene/javascript-sdk';
+
+// Counterparty assist is enabled for all counterparty types
+const optionsAllEnabled: TransactionOptions = {
+  ...
+  counterpartyAssist: true, // 'self', 'natural', and 'legal' enabled
+};
+
+// Counterparty assist is enabled for specific counterparty types
+const options: TransactionOptions = {
+  ...
+  counterpartyAssist: {
+    counterpartyTypes: [
+      PersonType.LEGAL, // JS: 'legal'
+      PersonType.NATURAL, // JS: 'natural'
+      PersonType.SELF, // JS: 'self'
+    ],
+  }
+};
+```
+
+### Component Response
+
+The component emits a response once a participant has completed their portion of the process. Depending on the party type — **Third Party** (`natural`, `legal`) or **First Party** (`self`) — the behavior and expectations differ slightly.
+
+#### Third Parties (`natural`, `legal`)
+
+When a third party completes their step after following the shared link, the host application will receive a **`COMPLETE`** message from the component. However, because not all required data may be available at this point, the `response` object will include the information gathered so far, along with a `refreshSource` field. This allows the host to fetch the latest encrypted data once it's available.
+
+##### Refresh Source Fields
+
+| Field | Type   | Description                                                                                      |
+|-------|--------|--------------------------------------------------------------------------------------------------|
+| `url` | URI    | The endpoint where the host can retrieve the encrypted data.                                     |
+| `key` | string | The encryption key used to decrypt the PII (Personally Identifiable Information). Not stored by Notabene. |
+
+**Example Response**
+
+```json
+{
+  type: CMType.COMPLETE, // 'complete'
+  response: { // transaciton data + refresh source
+    destination: "0xFf9A04788972C3803959454ECAE1ed327826a216",
+    asset: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      customer: {
+        type: "natural",
+        name: "sdfsd",
+        email: "sdjlf@sdlfj.com"
+      },
+    amountDecimal: 100,
+    counterparty: {
+      type: "natural"
+    },
+    account: {
+      caip10: "eip155:1:0xFf9A04788972C3803959454ECAE1ed327826a216",
+      blockchainAddress: "0xFf9A04788972C3803959454ECAE1ed327826a216",
+      chain: "eip155:1",
+      did: "did:pkh:eip155:1:0xFf9A04788972C3803959454ECAE1ed327826a216",
+      valid: true
+    },
+    refreshSource: {
+      url: "https://safe-connections.notabene.id/17f76e4c-9a2a-4c34-afcb-b4868e609a96", // endpoint to retreive data
+      key: "1Lcp5SFhaMHH7CAEILrS8IWA6BXS4tFZunPx08WU5Ok=" // key that can be used to decrypt data
+    }
+  }
+}
+```
+
+#### First Parties (`self`)
+
+When the user is the originator (i.e., acting on their own behalf), they complete the verification process via a shared link and are then prompted to return to the original page to continue.
+
+Upon completion, the component emits a **`COMPLETE`** response. In this case, the component handles all necessary data updates internally, so **no additional action is required from the host** to retrieve updated data. The host can directly proceed to submit the transfer to the Notabene API.
+
+### Retrieving Completed Data  
+**(Third Parties Only: `natural`, `legal`)**
+
+When data submission is handed off to third parties, we cannot predict how long it will take them to complete the process. For this reason, we provide the host with all the information needed to retrieve the data and allow them to design how the user experiences this flow.
+
+To simplify retrieval and decryption, we provide an asynchronous [`getRefreshResult`](./docs/notabene/functions/getRefreshResult.md) function. It accepts a `refreshSource` and returns information about the associated transaction. 
+
+
+**Example**
+
+```ts
+import { getRefreshResult } from "@notabene/javascript-sdk";
+
+const transaction = await getRefreshResult({
+  url: "https://safe-connections.notabene.id/17f76e4c-9a2a-4c34-afcb-b4868e609a96",
+  key: "1Lcp5SFhaMHH7CAEILrS8IWA6BXS4tFZunPx08WU5Ok="
+})
+```
+
+#### Response from `getRefreshResult`
+
+| **Property** | **Type**                              | **Optional?** | **Description**                                                                 |
+|--------------|---------------------------------------|---------------|---------------------------------------------------------------------------------|
+| `id`         | `UUID`                                | No            | Unique identifier for the transaction.                                          |
+| `metadata`   | `ConnectionMetadata`                  | No            | Metadata associated with the transaction.                                       |
+| `status`     | `'active'` \| `'completed'` \| `'closed'` | No         | Current status of the transaction’s data collection.                           |
+| `tx`         | `T`                                   | Yes           | Ongoing transaction data (available when status is `active`).                   |
+| `result`     | `TransactionResponse<T>`              | Yes           | Finalized transaction data (available when status is `completed`).             |
+
+
+**Example Active Transaction Data**
+
+```json
+{
+  "id": "17f76e4c-9a2a-4c34-afcb-b4868e609a96",
+  "metadata": {
+    "participants": [
+      "did:ethr:0x54b75d2a0925508682e65194cccb6f1e8eaafb2c"
+    ],
+    "nodeUrl": "https://api-qa.eu.notabene.id",
+    "transactionType": "withdraw"
+  },
+  "status": "active",
+  "tx": {
+    ...
+  }
+}
+```
+
+**Example Completed Transaction Data**
+
+```json
+{
+  "id": "17f76e4c-9a2a-4c34-afcb-b4868e609a96",
+  "metadata": {
+    "participants": [
+      "did:ethr:0x54b75d2a0925508682e65194cccb6f1e8eaafb2c" // DID of transaction participants
+    ],
+    "nodeUrl": "https://api-qa.eu.notabene.dev",
+    "transactionType": "withdraw"
+  },
+  "status": "completed",
+  "result": { // the response returned from the embedded component when all information is successfully collected
+    "proof": {
+      ...
+    },
+    "txCreate": {
+      ...
+    },
+    "errors": [],
+    "status": "pending",
+    "valid": true,
+    "value": {
+      ...
+    },
+    "ivms101": {
+      ...
+    }
+  }
+}
+
+```
+
+Once the host has retrieved the completed data, they can finalize the transaction by submitting it to the Notabene API.
+
 ## Error handling
 
 If any error occurs, the `error` event is passed containing a message.
@@ -584,6 +778,13 @@ const options: TransactionOptions = {
       VASPSearchControl.PENDING, // JS: 'pending'
     ], // Control searches for VASPs - Defaults to undefined
   },
+  counterpartyAssist: { // Allows users to share a link to collect counterparty data
+    counterpartyTypes: [
+      PersonType.LEGAL, // JS: 'legal'
+      PersonType.NATURAL, // JS: 'natural'
+      PersonType.SELF, // JS: 'self'
+    ],
+  }
 };
 const withdrawal = notabene.createWithdrawalAssist(tx, options);
 ```

package/dist/cjs/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.9.1-next.1",
+  "version": "2.9.2",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/dist/esm/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.9.1-next.1",
+  "version": "2.9.2",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.9.1-next.1",
+  "version": "2.9.2",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",