@notabene/javascript-sdk 2.9.0 → 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)
@@ -380,7 +386,7 @@ const connect = notabene.createConnectWallet(
 The Deposit Request lets your customers request deposits that are fully Travel Rule compliant.
 
 ```js
-const withdrawal = notabene.createDepositRequest({
+const depositRequest = notabene.createDepositRequest({
   asset: 'ETH',
   destination: '0x...',
   amountDecimal: 1.23,
@@ -408,7 +414,7 @@ const deposit = notabene.createDepositAssist(
   {
     asset: 'ETH',
     amountDecimal: 1.23,
-    origin: '0x...',
+    source: '0x...',
     destination: '0x...',
     transactionId: "UUID"
   },
@@ -421,7 +427,7 @@ const deposit = notabene.createDepositAssist(
 ### Parameters
 
 - `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
-- `origin`: The origin or blockchain address for the deposit. See [Origin](#origin)
+- `source`: The source or blockchain address for the deposit. See [Origin](#origin)
 - `destination`: The destination or blockchain address for the deposit. See [Destination](#destination)
 - `amountDecimal`: Optional amount to deposit in decimal format. See [Transaction Amount](#transaction-amount)
 - `transactionId`: Optional transactionId of a Notabene transaction. Will be returned with the payload to assist updating the Transaction
@@ -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.
@@ -480,7 +674,6 @@ The `asset` field the following types of assets specified:
 
 - `notabene_asset` code passed as a`string`. See [Notabene Assets Service](https://devx.notabene.id/docs/coins-decimals#assets-service-api).
 - [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-19.md_) is a chain agnostic format allows you to support the widest amount of assets and blockchains including NFTs.
-- [DTI](https://www.iso.org/standard/80601.html) is the ISO Digital Token Identifier format. See [DTI registry](https://dtif.org/registry-search/) for supported tokens.
 
 ### Transaction amount
 
@@ -497,9 +690,9 @@ Specify the beneficiary address as `destination` using one of the following form
 - [BIP-21](https://en.bitcoin.it/wiki/BIP_0021) Bitcoin URI
 - Native blockchain address
 
-### Origin
+### Source
 
-Specify the originator address as `origin` using one of the following formats:
+Specify the originator address as `source` using one of the following formats:
 
 - [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md_) is a chain agnostic format allows you to specify the specific blockchain and address
 - [EIP-3770](https://eips.ethereum.org/EIPS/eip-3770) EVM URI
@@ -575,16 +768,23 @@ const options: TransactionOptions = {
       nationalIdentification: false,
       countryOfRegistration: true,
     },
-    vasps: {
-      addUnknown: true, // Allow users to add a missing VASP - Defaults to false
-      onlyActive: true, // Only list active VASPs - Default false
-      searchable: [
-        VASPSearchControl.ALLOWED, // JS: 'allowed'
-        VASPSearchControl.PENDING, // JS: 'pending'
-      ], // Control searches for VASPs - Defaults to undefined
-    },
     hide: [ValidationSections.ASSET, ValidationSections.DESTINATION], // Don't show specific sections of component
   },
+  vasps: {
+    addUnknown: true, // Allow users to add a missing VASP - Defaults to false
+    onlyActive: true, // Only list active VASPs - Default false
+    searchable: [
+      VASPSearchControl.ALLOWED, // JS: 'allowed'
+      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/notabene.d.ts

@@ -430,12 +430,8 @@ export declare interface Counterparty {
  *
  * @public
  */
-export declare type CounterpartyAssistConfig = {
-    enabled?: boolean;
-} | {
-    [key in PersonType]: {
-        enabled?: boolean;
-    };
+export declare type CounterpartyAssistConfig = boolean | {
+    counterpartyTypes: PersonType[];
 };
 
 /**
@@ -1556,7 +1552,7 @@ export declare interface TransactionOptions {
     fields?: FieldTypes;
     vasps?: VASPOptions;
     hide?: ValidationSections[];
-    counterpartyAssistConfig?: CounterpartyAssistConfig;
+    counterpartyAssist?: CounterpartyAssistConfig;
 }
 
 /**

package/dist/cjs/package.json

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

package/dist/esm/notabene.d.ts

@@ -430,12 +430,8 @@ export declare interface Counterparty {
  *
  * @public
  */
-export declare type CounterpartyAssistConfig = {
-    enabled?: boolean;
-} | {
-    [key in PersonType]: {
-        enabled?: boolean;
-    };
+export declare type CounterpartyAssistConfig = boolean | {
+    counterpartyTypes: PersonType[];
 };
 
 /**
@@ -1556,7 +1552,7 @@ export declare interface TransactionOptions {
     fields?: FieldTypes;
     vasps?: VASPOptions;
     hide?: ValidationSections[];
-    counterpartyAssistConfig?: CounterpartyAssistConfig;
+    counterpartyAssist?: CounterpartyAssistConfig;
 }
 
 /**

package/dist/esm/package.json

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

package/dist/notabene.d.ts

@@ -430,12 +430,8 @@ export declare interface Counterparty {
  *
  * @public
  */
-export declare type CounterpartyAssistConfig = {
-    enabled?: boolean;
-} | {
-    [key in PersonType]: {
-        enabled?: boolean;
-    };
+export declare type CounterpartyAssistConfig = boolean | {
+    counterpartyTypes: PersonType[];
 };
 
 /**
@@ -1556,7 +1552,7 @@ export declare interface TransactionOptions {
     fields?: FieldTypes;
     vasps?: VASPOptions;
     hide?: ValidationSections[];
-    counterpartyAssistConfig?: CounterpartyAssistConfig;
+    counterpartyAssist?: CounterpartyAssistConfig;
 }
 
 /**

package/package.json

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

package/src/types.ts

@@ -802,13 +802,9 @@ export type VASPOptions = {
  * @public
  */
 export type CounterpartyAssistConfig =
+  | boolean
   | {
-      enabled?: boolean;
-    }
-  | {
-      [key in PersonType]: {
-        enabled?: boolean;
-      };
+      counterpartyTypes: PersonType[];
     };
 
 /**
@@ -859,7 +855,7 @@ export interface TransactionOptions {
   fields?: FieldTypes;
   vasps?: VASPOptions;
   hide?: ValidationSections[]; // You can hide a specific section of the component by listing it here
-  counterpartyAssistConfig?: CounterpartyAssistConfig;
+  counterpartyAssist?: CounterpartyAssistConfig;
 }
 /**
  * Component Message Type enum representing different message types that can be sent