@notabene/javascript-sdk 1.32.0 → 2.0.0-next.2

package/.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-berry.cjs

package/CODEOWNERS

@@ -1 +1 @@
-* @ajunge @brunosimplicio @lluissuros @omrinuri @dw1284 @ilja.nevolin @richardcrosby @david1250 @marieh_mai @timothy4915912
+* @ajunge @brunosimplicio @dw1284 @richardcrosby @david1250 @marieh_mai @timothy4915912 @graham9961840

package/README.md

@@ -8,27 +8,37 @@
 [![pipeline status](https://gitlab.com/notabene/open-source/javascript-sdk/badges/master/pipeline.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/master)
 [![Latest Release](https://gitlab.com/notabene/open-source/javascript-sdk/-/badges/release.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/releases)
 
-This library is the JavaScript SDK for loading the widget on a frontend.
+This library is the JavaScript SDK for loading the Notabene UX components in the front-end.
 
 [Documentation](https://devx.notabene.id/docs/widget-v2) •
 [Installation](#installation)
 
 </div>
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Supported asset formats](#supported-asset-formats)
-  - [Re-rendering](#re-rendering)
-  - [Error handling](#error-handling)
-- [Customization](#customization)
-  - [Functionality](#functionality)
-  - [Pass the variables in the configuration](#pass-the-variables-in-the-configuration)
-  - [Theme](#theme)
-  - [Dictionary](#dictionary)
-  - [Fields Properties](#fields-properties)
-  - [Fallbacks](#fallbacks)
-  - [Transaction Custom Asset Price](#transaction-custom-asset-price)
-- [License](#license)
+- [JavaScript SDK](#javascript-sdk)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Authentication](#authentication)
+  - [Assisted Withdrawal](#assisted-withdrawal)
+    - [Embedded Component](#embedded-component)
+      - [Dynamic updates](#dynamic-updates)
+    - [Linked Component](#linked-component)
+  - [Transaction parameters](#transaction-parameters)
+    - [Asset specification](#asset-specification)
+    - [Transaction amount specification](#transaction-amount-specification)
+    - [Destination address](#destination-address)
+    - [Error handling](#error-handling)
+  - [Customization](#customization)
+    - [Functionality](#functionality)
+    - [Pass the variables in the configuration](#pass-the-variables-in-the-configuration)
+    - [Theme](#theme)
+    - [Dictionary](#dictionary)
+          - [The property name must be the same as the text in the widget, for it to be replaced](#the-property-name-must-be-the-same-as-the-text-in-the-widget-for-it-to-be-replaced)
+    - [Fields Properties](#fields-properties)
+    - [Fallbacks](#fallbacks)
+    - [Opt-In Features](#opt-in-features)
+    - [Transaction Custom Asset Price](#transaction-custom-asset-price)
+  - [License](#license)
 
 ## Installation
 
@@ -57,83 +67,121 @@ Use the [customer token endpoint](https://devx.notabene.id/docs/customertoken) w
 Create a new Notabene instance:
 
 ```js
+
 const notabene = new Notabene({
-  vaspDID: 'did:ethr:0x94c38fd29ef36f5cb2f7bc771f9d5bd9f7d05f27',
-  widget: 'https://beta-widget.notabene.id',
-  container: '#container',
-  authToken: '{CUSTOMER_TOKEN}',
-  onValidStateChange: (isValid) => {
-    // Use this value to determine if the transaction is ready to be created.
-    console.log('is transaction valid', isValid);
-  },
-  onError: (err) => {
-    // If any errors are encountered, they will be passed to this function
-    alert(err.message);
-  },
+  nodeUrl: 'https://api.notabene.id',
+  authToken: '{CUSTOMER_TOKEN}'
 });
 ```
 
-Then render the widget:
+Use the same `nodeUrl` that you use to interact with the Notabene API.
 
-```js
-// Use this method when you need to collect missing information from the sender about the recipient (normal withdrawal)
-notabene.renderWidget('WITHDRAWAL');
+## Assisted Withdrawal
+
+The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
 
-// Use this method when you need to collect missing information from the recipient about the sender (for transactions created via notification)
-notabene.renderWidget('POST_DEPOSIT');
+### Embedded Component
+
+This will let you embed the component into your existing withdrawal flow.
+
+Create an html element to contain the component:
+
+```html
+<div id="nb-withdrawal/>
 ```
 
-To update the widget as users enter transaction details:
+Instantiate the withdrawal element and mount it using the id from above
 
 ```js
-notabene.setTransaction({
-  transactionAsset: 'ETH',
-  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  transactionAmount: '2000000000',
-});
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+withdrawal.mount("nb-withdrawal");
 ```
 
-Once the widget determines the transaction is valid, it will call the `onValidStateChange` callback, to access the transaction details:
+The simplest way to get the result is to use:
 
 ```js
-const currentTransactionInfo = notabene.tx;
+try {
+ const {valid, ivms101} = await withdrawal.completion()
+ if (valid) {
+  // Submit result to your backend
+ }
+} catch (e) {
+ console.error(e)
+}
 ```
 
-### Supported asset formats
-
-- `USDC` the simple asset code passed as a `string`, in case different chain (polygon) -> `USDC-POLY`
-- `CAIP19` format
-  ```js
-  {
-    caip19: 'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'; // for USDC
-  }
-  ```
-- `coingeckoId` and `network` format
-  ```js
-  {
-    coingeckoId: "usd-coin",
-    network: "ethereum"
-  }
-  ```
+#### Dynamic updates
 
----
+To update the component as users enter transaction details:
 
-### Re-rendering
+```js
+withdrawal.update({
+  asset: 'ETH',
+  destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
+  amountDecimal: 1.12
+});
+```
 
-**WARNING:** this shouldn't be used often, if you need to change the transaction's initial fields call `setTransaction` again. (This should be used only for tearing down the component).
+To be notified once the validation is completed so you can submit the withdrawal to your back end:
 
-The container of the widget must be in the DOM before calling `destroyWidget` or `renderWidget`.
+```js
+withdrawal.on('valid', {ivms101} => ...)
+```
 
-If you need to close and re-render the widget, call the `destroyWidget` method like so:
+To be notified of any errors use:
 
 ```js
-// Will remove the widget
-notabene.destroyWidget();
-// Will re-render the widget
-notabene.renderWidget();
+withdrawal.on('error',error => ...)
 ```
 
-Calling the `renderWidget` methods without destroying it first will not work.
+### Linked Component
+
+In some cases, in particular institutional or mobile apps you may prefer to link your customers to the component through an email or redirect the user to it in a mobile app.
+
+```js
+const withdrawal = notabene.createWithdrawalAssist(tx, options, {
+  callback: /// a serverside backend url
+  redirectUri: // URI of website or mobile app to redirect user to after completion
+});
+
+// NodeJS redirect. Link also works in an email.
+res.redirect(withdrawal.url);
+```
+
+Bear in mind that this is a full screen view for your users.
+
+The two parameters that should be configured are:
+
+- `callback` - a URL for your serverside. On completion this will receive an HTTP POST with the result as a json body and the `authToken` as an `Authorization: Bearer` header.
+- `redirectUri` - the user will be redirected here on completion. The result parameters will be json encoded in the URL fragment. You can use a mobile app schema to intercept these in your mobile app.
+
+**Note** for data privacy reasons the callback will be coming from your users web browser and not from our infrastructure, so no static IP is currently possible. Instead please check the `authToken` provided with the request.
+
+## Transaction parameters
+
+### Asset specification
+
+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 specification
+
+Use one of the following
+
+- `amountDecimal` A number specifying the amount in decimal format. Eg. `amountDecimal=1.1` would mean 1.1 of for example BTC or ETH.
+- `amountSubunits` A string specifying the amount in the native blockchain subunits eg Satoshi for Bitcoin or wei for Ethereum
+
+### Destination address
+
+Specify the beneficiary address as `destination` 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
+- [BIP-21](https://en.bitcoin.it/wiki/BIP_0021) Bitcoin URI
+- Native blockchain address
 
 ---
 
@@ -177,13 +225,13 @@ Type | Code | Title | Detail
 
 ### Functionality
 
-`transactionTypeAllowed`: `ALL` | `VASP_2_VASP_ONLY` | `SELF_TRANSACTION_ONLY`
+`transactionTypeAllowed`: `ALL` | `VASP_2_VASP_ONLY` | `FIRST_PARTY_ONLY`
 
 For limiting the type of transaction destinations you can pass.
 
 `ALL`: All transaction destinations are allowed. (DEFAULT)
 `VASP_2_VASP_ONLY`: Only transaction destinations that are VASPs are allowed.
-`SELF_TRANSACTION_ONLY`: Only transaction destinations that the originator owns are allowed.
+`FIRST_PARTY_ONLY`: Only transaction destinations that the originator owns are allowed.
 
 ---
 
@@ -194,6 +242,12 @@ For deciding which ownership proof type you want to use.
 `SIGNATURE`: The ownership proof will be signed by the originator using a wallet. (DEFAULT)
 `DECLARATION`: The ownership proof will be declared by the originator using a checkbox.
 
+---
+
+`counterpartyManualEntry`: `TRUE` | `FALSE`
+
+For deciding if you would like to allow your customer to provide a manual counterparty vasp name in the counterparty field.
+
 ### Pass the variables in the configuration
 
 ```js
@@ -282,7 +336,8 @@ Possible fields customization support:
 | `counterparty`           | --             | ☑️         | Counterparty VASP or Wallet (destination or originator) |
 | `dateAndPlaceOfBirth`    | ☑️             | --         | Recipient (or Sender) Date and Place of Birth           |
 | `geographicAddress`      | ☑️             | ☑️          | Recipient (or Sender) Address                           |
-| `name`                   | ☑️             | --         | Recipient (or Sender) Name                              |
+| `firstName`              | ☑️             | --         | Recipient (or Sender) First name                        |
+| `name`                   | ☑️             | --         | Recipient (or Sender) Last Name / Company Name          |
 | `nationalIdentification` | ☑️             | --️         | Recipient (or Sender) National Identification           |
 | `country`                | ☑️             | ☑️          | Recipient (or Sender) Country of Residence (for natural person) / Country of Registration (for legal person)           |
 
@@ -337,6 +392,7 @@ Possible options and actions:
   - `DECLARATION` - Falls back to the self declaration flow
   - `REJECT` - Rejects the transaction and throws an error
     - The error that will be thrown here will have the following structure
+
       ```js
         {
           "type": "WALLET_NOT_SUPPORTED",
@@ -349,6 +405,7 @@ Possible options and actions:
 ```js
 fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
 ```
+
 ---
 
 Finally you pass the configuration to a Notabene instance:
@@ -363,6 +420,7 @@ const notabene = new Notabene({
     fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
 });
 ```
+
 ---
 
 ### Opt-In Features