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

package/README.md

@@ -8,27 +8,32 @@
 [![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) •
+[Documentation](https://devx.notabene.id/docs/embedded=ux)
 [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)
+    - [Fields Properties](#fields-properties)
+    - [Transaction Custom Asset Price](#transaction-custom-asset-price)
+  - [License](#license)
 
 ## Installation
 
@@ -57,83 +62,122 @@ 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',
+  nodeUrl: 'https://api.notabene.id',
   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);
-  },
+  locale: 'de' // default locale
 });
 ```
 
-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.
+
+### Embedded Component
 
-// 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');
+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 => ...)
+```
+
+### 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);
 ```
 
-Calling the `renderWidget` methods without destroying it first will not work.
+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
 
 ---
 
@@ -175,18 +219,6 @@ Type | Code | Title | Detail
 
 ## Customization
 
-### Functionality
-
-`transactionTypeAllowed`: `ALL` | `VASP_2_VASP_ONLY` | `SELF_TRANSACTION_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.
-
----
-
 `nonCustodialDeclarationType`: `SIGNATURE` | `DECLARATION`
 
 For deciding which ownership proof type you want to use.
@@ -194,82 +226,11 @@ 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.
 
-### Pass the variables in the configuration
-
-```js
-const notabene = new Notabene({
-    vaspDID: 'did:ethr:0x94c38fd29ef36f5cb2f7bc771f9d5bd9f7d05f27',
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    allowedTransactionTypes: 'VASP_2_VASP_ONLY',
-    nonCustodialDeclarationType: 'DECLARATION',
-});
-```
-
 ---
 
-### Theme
+`counterpartyManualEntry`: `TRUE` | `FALSE`
 
-Pass a `theme` object when creating an instance
-
-Here you can pass configuration which will customize the styles of the widget to meet your brand needs, all values are optional.
-
-```js
-{
-  primaryColor: '#fff',
-  secondaryColor: '#fff',
-  primaryFontColor: '#fff',
-  secondaryFontColor: '#fff',
-  backgroundColor: '#fff',
-  fontFamily: Arial,
-  logo: {LOGO_URL},
-  mode: 'dark', // default: 'light'
-
-  // If you are using the Signature flow, here is the full list of custom theme that can be applied to the WalletConnect Modal.
-  '--w3m-font-family',
-  '--w3m-font-feature-settings',
-  '--w3m-overlay-background-color',
-  '--w3m-overlay-backdrop-filter',
-  '--w3m-z-index',
-  '--w3m-accent-color',
-  '--w3m-accent-fill-color',
-  '--w3m-background-color',
-  '--w3m-background-image-url',
-  '--w3m-logo-image-url',
-  '--w3m-background-border-radius',
-  '--w3m-container-border-radius',
-  '--w3m-wallet-icon-border-radius',
-  '--w3m-wallet-icon-large-border-radius',
-  '--w3m-wallet-icon-small-border-radius',
-  '--w3m-input-border-radius',
-  '--w3m-notification-border-radius',
-  '--w3m-button-border-radius',
-  '--w3m-secondary-button-border-radius',
-  '--w3m-icon-button-border-radius',
-  '--w3m-button-hover-highlight-border-radius',
-}
-```
-
-To get a list of supported fonts, visit [https://fonts.google.com/](https://fonts.google.com/)
-
-To get more details about the WalletConnect theme variables, visit [General style variables](https://docs.walletconnect.com/2.0/web/web3modal/react/wagmi/theming#general-style-variables).
-
----
-
-### Dictionary
-
-Pass a `dictionary` object mapping in text in the widget to your own language, for example:
-
-To replace `Loading...` with `Cargando...`
-
-```js
-{
-  'Loading...': 'Cargando...',
-}
-```
-
-###### The property name must be the same as the text in the widget, for it to be replaced
+For deciding if you would like to allow your customer to provide a manual counterparty vasp name in the counterparty field.
 
 ---
 
@@ -279,10 +240,9 @@ Possible fields customization support:
 
 | field name               | `forceDisplay` | `optional` | description                                             |
 | ------------------------ | -------------- | ---------- | ------------------------------------------------------- |
-| `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                              |
+| `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)           |
 
@@ -303,84 +263,7 @@ Possible fields customization support:
 }
 ```
 
----
-
-**_Beneficiary Details_ [DEPRECATED]**
-
-You can require specific beneficiary fields that are not required by your jurisdiction.
-
-Possible fields:
-
-- `beneficiaryName` - Recipient Name
-- `beneficiaryGeographicAddress` - Recipient Address
-- `beneficiaryNationalIdentification` - Recipient National Identification
-- `beneficiaryDateAndPlaceOfBirth` - Recipient Date and Place of Birth
-
-```js
-beneficiaryDetails: [
-  'benficiaryName',
-  'beneficiaryGeographicAddress',
-  'beneficiaryNationalIdentification',
-  'beneficiaryDateAndPlaceOfBirth',
-];
-```
-
----
-
-### Fallbacks
-
-Fallbacks are custom options provided when desired outcome is not achieved
-
-Possible options and actions:
-
-- `WALLET_NOT_SUPPORTED` - Performs one of the following options when wallet is not supported
-  - `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",
-          "title": "Wallet Not Supported",
-          "status": 501,
-          "detail": "We don't support the wallet for the provided asset"
-        }
-      ```
-
-```js
-fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
-```
----
-
-Finally you pass the configuration to a Notabene instance:
-
-```js
-const notabene = new Notabene({
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    theme: {THEME},
-    dictionary: {DICTIONARY},
-    fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
-});
-```
----
-
-### Opt-In Features
-
-```js
-const notabene = new Notabene({
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    theme: {THEME},
-    dictionary: {DICTIONARY},
-    optInFeatures: ['REUSE_ADDRESS_OWNERSHIP_PROOF']
-});
-```
-
-**Available Opt-In Features**
 
-- `REUSE_ADDRESS_OWNERSHIP_PROOF`: For a given unique customer (identified by the `customerRef` from the customer token used) + unique wallet address, the widget would not ask for data collection if the customer previously verified the address ownership in a previous first party self-hosted transfer.
 
 ### Transaction Custom Asset Price
 

package/dist/notabene.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var c=(r,e,t)=>e in r?d(r,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):r[e]=t;var n=(r,e,t)=>c(r,typeof e!="symbol"?e+"":e,t);var a=(r=>(r.COMPLETE="complete",r.RESIZE="resize",r.RESULT="result",r.READY="ready",r.INVALID="invalid",r.MODAL="openModal",r.ERROR="error",r.CLOSE="closeModal",r.CANCEL="cancel",r))(a||{}),l=(r=>(r.UPDATE="update",r.REQUEST_RESPONSE="requestResponse",r))(l||{});class m{constructor(){n(this,"listeners",new Map);n(this,"port");this.handleMessage=this.handleMessage.bind(this)}setPort(e){this.port=e,this.port.onmessage=this.handleMessage,this.port.start()}on(e,t){this.listeners.has(e)||this.listeners.set(e,new Set),this.listeners.get(e).add(t)}off(e,t){const s=this.listeners.get(e);s&&(s.delete(t),s.size===0&&this.listeners.delete(e))}handleMessage(e){console.log("received message",e.data);const t=e.data;if(typeof t=="object"&&t!==null&&"type"in t){const s=t.type,o=this.listeners.get(s);o&&o.forEach(i=>i(t))}}send(e){this.port&&this.port.postMessage(e)}}class u{constructor(e,t){n(this,"_url");n(this,"_value");n(this,"_errors",[]);n(this,"iframe");n(this,"eventManager");n(this,"ready",!1);n(this,"modal");this._url=e,this._value=t,this.eventManager=new m,this.on(a.INVALID,s=>{s.type===a.INVALID&&(this._errors=s.errors,this._value=s.value)}),this.on(a.RESIZE,s=>{s.type===a.RESIZE&&this.iframe&&(this.iframe.style.height=`${s.height}px`)})}get url(){return this._url}get value(){return this._value}get errors(){return this._errors}open(){document.location.href=this.url}mount(e){const t=document.querySelector(e);if(!t)throw new Error(`parentID ${e} not found`);this.embed(t)}embed(e){var t,s;this.iframe=document.createElement("iframe"),this.iframe.src=this.url,this.iframe.style.width="100%",this.iframe.style.height="100px",this.iframe.style.border="none",this.iframe.style.overflow="hidden",this.iframe.setAttribute("allowtransparency","true"),this.iframe.style.backgroundColor="transparent",e.appendChild(this.iframe),window.addEventListener("message",o=>{var i,h;o.source===((i=this.iframe)==null?void 0:i.contentWindow)&&(console.log("received message from iframe",o.data),(h=this.eventManager)==null||h.setPort(o.ports[0]),this.ready=!0)}),(s=(t=this.iframe)==null?void 0:t.contentWindow)==null||s.focus()}send(e){this.eventManager.send(e)}on(e,t){this.eventManager.on(e,t)}off(e,t){this.eventManager.off(e,t)}update(e){this._value=e,this.send({type:l.UPDATE,value:e})}completion(){return new Promise((e,t)=>{this.closeModal(),this.on(a.COMPLETE,s=>{e(s.response)}),this.on("error",s=>{t(new Error(s.message))})})}openModal(){this.modal&&this.closeModal(),this.modal=document.createElement("dialog"),document.body.appendChild(this.modal),this.embed(this.modal),this.on(a.CANCEL,()=>{this.closeModal()}),this.on(a.CLOSE,()=>{this.closeModal()}),this.on(a.COMPLETE,()=>{this.closeModal()}),this.modal.showModal(),this.modal.addEventListener("click",()=>{this.closeModal()})}closeModal(){var e;this.modal&&(console.log("closeModal"),(e=this.modal)==null||e.close(),this.modal.remove(),this.modal=void 0)}}function f(r){return Object.entries(r).map(([e,t])=>{if(!(e&&t))return;const s=encodeURIComponent(e),o=encodeURIComponent(typeof t=="object"?JSON.stringify(t):t);return`${s}=${o}`}).filter(e=>!!e).join("&")}class p{constructor(e){n(this,"nodeUrl");n(this,"authToken");n(this,"uxUrl");n(this,"theme");n(this,"locale");this.uxUrl=e.uxUrl||"https://connect.notabene.id",this.nodeUrl=e.nodeUrl,this.authToken=e.authToken,this.theme=e.theme,this.locale=e.locale}componentUrl(e,t,s,o){const i=new URL(this.uxUrl);i.pathname=e;const h=f({authToken:this.authToken,value:t,configuration:s});return i.hash=h,this.nodeUrl&&i.searchParams.set("nodeUrl",this.nodeUrl),this.theme&&i.searchParams.set("theme",JSON.stringify(this.theme)),this.locale&&i.searchParams.set("locale",this.locale),o&&(o.callback&&i.searchParams.set("callback_url",o.callback),o.redirectUri&&i.searchParams.set("redirect_uri",o.redirectUri)),i.toString()}createComponent(e,t,s,o){return new u(this.componentUrl(e,t,s,o),t)}createWithdrawalAssist(e,t,s){return this.createComponent("withdrawal-assist",e,t,s)}createDepositAssist(e,t,s){return this.createComponent("deposit-assist",e,t,s)}createConnect(e,t,s){return this.createComponent("connect",e,t,s)}createDepositRequest(e,t,s){return this.createComponent("deposit-request",e,t,s)}decodeFragmentToObject(e){return e.slice(1).split("&").reduce((s,o)=>{const[i,h]=o.split("=");return s[decodeURIComponent(i)]=decodeURIComponent(h),s},{})}}module.exports=p;