@notabene/javascript-sdk 2.0.0-next.9 → 2.0.0

package/README.md

@@ -2,54 +2,104 @@
 
 <img src="https://assets-global.website-files.com/5e68f0772de982756aa8c1a4/5eee5fb470215e6ecdc34b94_Full_transparent_black_1280x413.svg" height=50>
 <br>
-
-# JavaScript SDK
+# Notabene SafeConnect Components JavaScript SDK
 
 [![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)
+[![npm version](https://img.shields.io/npm/v/@notabene/javascript-sdk.svg)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@notabene/javascript-sdk.svg)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@notabene/javascript-sdk)](https://bundlephobia.com/package/@notabene/javascript-sdk)
+[![Types](https://img.shields.io/npm/types/@notabene/javascript-sdk)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![License](https://img.shields.io/npm/l/@notabene/javascript-sdk)](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/main/LICENSE.md)
+[![Dependencies](https://img.shields.io/librariesio/release/npm/@notabene/javascript-sdk)](https://libraries.io/npm/@notabene%2Fjavascript-sdk)
 
 This library is the JavaScript SDK for loading the Notabene UX components in the front-end.
 
-[Documentation](https://devx.notabene.id/docs/embedded=ux)
-[Installation](#installation)
+[Additional Documentation](https://devx.notabene.id/docs/embedded=ux)
 
 </div>
 
-- [JavaScript SDK](#javascript-sdk)
-  - [Installation](#installation)
-  - [Usage](#usage)
-    - [Authentication](#authentication)
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Authentication](#authentication)
+- [General Component Usage](#general-component-usage)
+  - [Embedded Component](#embedded-component)
+    - [Dynamic updates](#dynamic-updates)
+  - [Modal](#modal)
+  - [Linked Component](#linked-component)
+- [Components](#components)
   - [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)
+  - [Connect Wallet](#connect-wallet)
+  - [Deposit Request](#deposit-request)
+- [Error handling](#error-handling)
+- [Transaction parameters](#transaction-parameters)
+  - [Asset specification](#asset-specification)
+  - [Transaction amount](#transaction-amount)
+  - [Destination](#destination)
+  - [Asset Price](#asset-price)
+- [Configuration](#configuration)
+  - [Transaction Options](#transaction-options)
+  - [Common use cases](#common-use-cases)
+  - [Configuring ownership proofs](#configuring-ownership-proofs)
+  - [Counterparty Field Properties](#counterparty-field-properties)
+- [Locales](#locales)
+- [License](#license)
 
 ## Installation
 
 There are two options for loading the Notabene SDK:
 
 ```bash
-<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@1.31.0/dist/es/index.js"></script>
+<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@next/dist/notabene.js"></script>
 ```
 
 Or installing the library:
 
+Using Yarn:
+
 ```bash
 yarn add @notabene/javascript-sdk
 ```
 
-## Usage
+Using NPM:
+
+```bash
+npm install @notabene/javascript-sdk
+```
+
+If you installed the library into your project, you can import it into your project:
+
+```js
+import Notabene from '@notabene/javascript-sdk';
+```
+
+## Quick Start
+
+```js
+// 1. Create Notabene instance
+const notabene = new Notabene({
+  nodeUrl: 'https://api.notabene.id',
+  authToken: 'YOUR_CUSTOMER_TOKEN'
+});
+
+// 2. Create and mount withdrawal component
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x1234...',
+  amountDecimal: 1.0
+});
+withdrawal.mount('#nb-withdrawal');
+
+// 3. Handle completion
+const { valid, value, txCreate } = await withdrawal.completion();
+if (valid) {
+  // Submit to your backend
+}
+```
+
+## Core Concepts
 
 ### Authentication
 
@@ -62,19 +112,18 @@ Use the [customer token endpoint](https://devx.notabene.id/docs/customertoken) w
 Create a new Notabene instance:
 
 ```js
-
 const notabene = new Notabene({
-  nodeUrl: 'https://api.notabene.id',
+  nodeUrl: 'https://api.notabene.id', // use `https://api.notabene.dev` for testing
   authToken: '{CUSTOMER_TOKEN}',
-  locale: 'de' // default locale
+  locale: 'de', // default locale = `en`
 });
 ```
 
 Use the same `nodeUrl` that you use to interact with the Notabene API.
 
-## Assisted Withdrawal
+## General Component Usage
 
-The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
+Each component can be used in various ways depending on your use case.
 
 ### Embedded Component
 
@@ -90,19 +139,20 @@ Instantiate the withdrawal element and mount it using the id from above
 
 ```js
 const withdrawal = notabene.createWithdrawalAssist(tx, options);
-withdrawal.mount("nb-withdrawal");
+withdrawal.mount('#nb-withdrawal');
 ```
 
 The simplest way to get the result is to use:
 
 ```js
 try {
- const {valid, ivms101} = await withdrawal.completion()
- if (valid) {
-  // Submit result to your backend
- }
+  const { valid, value, txCreate, ivms101, proof } =
+    await withdrawal.completion();
+  if (valid) {
+    // Submit result to your backend
+  }
 } catch (e) {
- console.error(e)
+  console.error(e);
 }
 ```
 
@@ -114,22 +164,50 @@ To update the component as users enter transaction details:
 withdrawal.update({
   asset: 'ETH',
   destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  amountDecimal: 1.12
+  amountDecimal: 1.12,
 });
 ```
 
 To be notified once the validation is completed so you can submit the withdrawal to your back end:
 
 ```js
-withdrawal.on('valid', {ivms101} => ...)
+withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
 ```
 
-To be notified of any errors use:
+To be notified of any validation errors use:
 
 ```js
 withdrawal.on('error',error => ...)
 ```
 
+Calling `on` returns a function that will allow you to cleanly unsubscribe.
+
+```js
+const unsubscribe = withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
+
+// Clean up
+unsubscribe()
+
+```
+
+### Modal
+
+All components support being opened in a modal using `openModal()`, which returns a promise.
+
+```js
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+try {
+  const { valid, value, txCreate, ivms101, proof } =
+    await withdrawal.openModal();
+  if (valid) {
+    // Submit result to your backend
+  }
+} catch (e) {
+  console.error(e);
+}
+```
+
+
 ### 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.
@@ -153,6 +231,128 @@ The two parameters that should be configured are:
 
 **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.
 
+
+## Components
+
+## Assisted Withdrawal
+
+The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
+
+```js
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  assetPrice: {
+    currency: 'USD', // ISO currency code
+    price: 1700.12, // Asset price
+  }
+});
+```
+
+### Parameters
+
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
+- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
+- `amountDecimal`: The amount to transfer in decimal format. See [Transaction Amount](#transaction-amount)
+- `assetPrice`: Optional price information in a fiat currency. See [Asset Price](#asset-price)
+
+If any of the required parameters are missing the component will just show the Notabene badge.
+
+### Configuration Options
+
+Include configuration Options as a second optional parameter:
+
+```js
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  assetPrice: {
+    currency: 'USD', // ISO currency code
+    price: 1700.12, // Asset price
+  }
+}, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
+});
+```
+
+See [Transaction Options](#transaction-options)
+
+## Connect Wallet
+
+The Connect Wallet component helps you collect and verify the address of your users self-hosted wallet in one go.
+
+```js
+const connect = notabene.createConnectWallet({
+  asset: 'ETH'
+});
+
+const { proof, txCreate } = await connect.openModal()
+```
+
+### Parameters
+
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
+
+### Configuration Options
+
+Include configuration Options as a second optional parameter:
+
+```js
+const connect = notabene.createConnectWallet({
+    asset: 'ETH',
+  }, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
+});
+```
+
+## Deposit Request
+
+The Deposit Request lets your customers request deposits that are fully Travel Rule compliant.
+
+```js
+const withdrawal = notabene.createDepositRequest({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  customer: {
+    name: "John Smith"
+  }
+});
+```
+
+### Parameters
+
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
+- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
+- `amountDecimal`: Optional amount to deposit in decimal format. See [Transaction Amount](#transaction-amount)
+- `customer`: Optional Customer object containing their name
+
+If any of the required parameters are missing the component will just show the Notabene badge.
+
+---
+
+## Error handling
+
+If any error occurs, the `error` event is passed containing a message.
+
+```ts
+withdrawal.on('error', {message} => ...)
+```
+
 ## Transaction parameters
 
 ### Asset specification
@@ -163,14 +363,13 @@ The `asset` field the following types of assets specified:
 - [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
+### Transaction amount
 
 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
+### Destination
 
 Specify the beneficiary address as `destination` using one of the following formats:
 
@@ -179,108 +378,269 @@ 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
 
----
+### Asset Price
 
-### Error handling
+The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this:
 
-If any error occurs, the `onError` function from the Notabene instance will be triggered. The `error` passed as argument contains a `data` property that has the following type `ErrorData`.
+```ts
+assetPrice: {
+  currency: 'USD', // ISO currency code
+  price: 1700.12, // Asset price
+};
+```
 
-> ⚠️ **Note**: These errors are mainly used for debugging internal issues while implementing the widget. They are not meant to be shown directly to the end user.
 
-```js
-type ErrorData = {
-  title: string;
-  detail: string;
-  code: number;
-  type: string;
-};
+## Configuration
 
-const notabene = new Notabene({
-  ...,
-  onError: (err) => {
-    const errorData = err.data;
+### Transaction Options
+
+Some components can be configured using an optional [TransactionOptions](./docs/types/interfaces/TransactionOptions.md) object.
+
+The following shows the full set of options in typescript:
 
-    // Do something
+```ts
+import Notabene, {
+  AgentType,
+  PersonType,
+  ProofTypes,
+} from '@notabene/javascript-sdk';
+
+const options: TransactionOptions = {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    },
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
+    deminimis: {
+      threshold: 1000,
+      currency: 'EUR',
+      proofTypes: [ProofTypes.SelfDeclaration]
+    }
+  },
+  allowedAgentTypes: [AgentType.PRIVATE, AgentType.VASP], // js ['WALLET','VASP']
+  allowedCounterpartyTypes: [
+    PersonType.LEGAL, // JS: 'legal'
+    PersonType.NATURAL, // JS: 'natural'
+    PersonType.SELF, // JS: 'self'
+  ],
+  fields: {
+    naturalPerson: {
+      name: true, // Default true
+      website: { optional: true },
+      email: true,
+      phone: true,
+      geographicAddress: false,
+      nationalIdentification: false,
+      dateOfBirth: false,
+      placeOfBirth: false,
+      countryOfResidence: true,
+    },
+    legalPerson: {
+      name: true, // Default true
+      lei: true, // Default true
+      website: { optional: true }, // Default true
+      email: true,
+      phone: true,
+      geographicAddress: false,
+      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
+    },
+    hide: [ValidationSections.ASSET, ValidationSections.DESTINATION] // Don't show specific sections of component
   },
+};
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+```
+
+The options can additionally be updated dynamically with the `update()` function.
+
+```js
+withdrawal.update({
+  asset: 'ETH',
+  destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
+  amountDecimal: 1.12,
+}, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
 });
 ```
 
-**Notabene Internal Errors**
+### Common use cases
 
-Type | Code | Title | Detail
--- | -- | -- | --
-`BAD_REQUEST` | `400` | `Bad Request` | `NotabeneBadRequest: ...`
-`TRANSACTION_INVALID` | `400` | `Transaction Invalid` | `NotabeneTransactionInvalid: ...`
-`TOKEN_INVALID` | `401` | `Token Invalid` | `NotabeneTokenInvalid: ...`
-`ASSET_NOT_SUPPORTED` | `404` | `Asset Not Supported` | `NotabeneAssetNotSupported: ...`
-`SERVICE_UNAVAILABLE` | `500` | `Service Unavailable` | `NotabeneServiceUnavailable: ...`
-`WALLET_CONNECTED_FAILED` | `500` | `Wallet Connection Failed` | `NotabeneWalletConnectionFailed: ...`
-`WALLET_NOT_SUPPORTED` | `501` | `Wallet Not Supported` | `NotabeneWalletNotSupported: ...`
+#### Only allow first party transactions
 
-## Customization
+```ts
+const firstParty: TransactionOptions = {
+  allowedCounterpartyTypes: [
+    PersonType.SELF, // JS: 'self'
+  ],
+};
+```
 
-`nonCustodialDeclarationType`: `SIGNATURE` | `DECLARATION`
+#### Only VASP to VASP transactions
 
-For deciding which ownership proof type you want to use.
+```ts
+const vasp2vasp: TransactionOptions = {
+  allowedAgentTypes: [AgentType.VASP], // js ['VASP']
+};
+```
 
-`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.
+#### Only Self-hosted wallet transactions
 
----
+```ts
+const options: TransactionOptions = {
+  allowedAgentTypes: [AgentType.PRIVATE], // js ['WALLET']
+};
+```
 
-`counterpartyManualEntry`: `TRUE` | `FALSE`
+### Configuring ownership proofs
 
-For deciding if you would like to allow your customer to provide a manual counterparty vasp name in the counterparty field.
+By default components support message signing proofs.
 
----
+#### Supporting Micro Transactions (aka Satoshi tests)
 
-### Fields Properties
+You can support Micro Transfers (aka Satoshi tests) by adding a deposit address for the test.
 
-Possible fields customization support:
+Your compliance team will have to determine how to handle and verify these transactions in the rules engine or individually.
 
-| field name               | `forceDisplay` | `optional` | description                                             |
-| ------------------------ | -------------- | ---------- | ------------------------------------------------------- |
-| `dateAndPlaceOfBirth`    | ☑️             | --         | Recipient (or Sender) Date and Place of Birth           |
-| `geographicAddress`      | ☑️             | ☑️          | Recipient (or Sender) Address                           |
-| `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)           |
+```ts
+const options: TransactionOptions = {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '1234',
+      timeout: 86440, // Optional timeout in seconds, which is displayed to the user
+    },
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
+  },
+};
+```
 
-**Field Options**
+Notabene does not currently verify these tests automatically as you likely already have the infrastructure to do so.
 
-- **forceDisplay** - Force a field that is not required by your jurisdiction to be displayed - defaults to **false**
-- **optional** - Bypass the jurisdiction rules validation for that specific field - defaults to **false**
+You will receive a response back from the component containing a proof object. For MicroTransfers it will look like this:
 
-```js
-{
-  counterparty: {
-    optional: true;
-  },
-  geographicAddress: {
-    forceDisplay: true,
-    optional: true;
-  },
+```ts
+type MicroTransferProof {
+  type: ProofTypes.MicroTransfer;
+  status: ProofStatus.PENDING;
+  did: DID;
+  address: CAIP10; // CAIP10 account to be verified
+  txhash: string; // Transaction Hash to verify
+  chain: CAIP2; // CAIP2 identifier of blockchain
+  amountSubunits: string; // Amount in subunits eg (satoshi or wei) to be verified
 }
 ```
 
+#### Fallback Proof Options
 
+You may accept a few options if none of the other are available. We do not recommend them, as they do not provide sufficient proof. However many VASPs do allow them for now:
 
-### Transaction Custom Asset Price
+```ts
+const options: TransactionOptions = {
+  proofs: {
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
+  },
+};
+```
 
-To use your own asset price as fallback in case an asset is not supported by Notabene, you can provide a `customAssetPrice` object that will be used instead to render the widget with the correct jurisdiction requirements.
+The two options are:
 
-```js
-notabene.setTransaction({
-  transactionAsset: 'ASSET_UNSUPPORTED_FROM_NOTABENE',
-  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  transactionAmount: '2000000000',
-  customAssetPrice: {
-      priceUSD: 1700.12, // Asset price in USD
-      decimals: 10 // Decimals used for the given transactionAmount
-    };
-});
+- `screenshot` Where a user is requested to upload a screenshot of their wallet
+- `self-declaration` Where a user self declares that they control the wallet address
+
+### Counterparty Field Properties
+
+The fields requested from a customer about a counterparty can be configured with the fields object. You can configure required and optional fields individually for both natural and legal persons.
+
+We recommend working closely with your compliance team for this. Bearing in mind that different jurisdictions have different rules.
+
+Each field can be configured like this:
+
+- `true` required field
+- `false` don't show
+- `{ optional: true }` show but don't require
+
+Eg:
+
+```ts
+{
+  naturalPerson: {
+    website: { optional: true },
+    email: true,
+    phone: false,
+  }
+}
+```
+
+The above will always ask the user for the following for natural persons:
+
+- `name` since it is on by default (you can disable it explicitly by setting it to `false`)
+- `website` is show but is optional
+- `email` is required
+
+#### Full Example
+
+```ts
+const options: TransactionOptions = {
+  fields: {
+    naturalPerson: {
+      name: true, // Default true
+      website: { optional: true },
+      email: true,
+      phone: true,
+      geographicAddress: false,
+      nationalIdentification: false,
+      dateOfBirth: {
+        transmit: true,
+      },
+      placeOfBirth: false,
+      countryOfResidence: true,
+    },
+    legalPerson: {
+      name: true, // Default true
+      lei: true, // Default true
+      website: { optional: true }, // Default true
+      email: true,
+      phone: true,
+      geographicAddress: false,
+      nationalIdentification: false,
+      countryOfRegistration: true,
+    },
+  },
+};
 ```
 
+#### Field reference
+
+| Field name               | Natural | Legal | IVMS101 |  description                                   |
+| ------------------------ | ------- | ----- | ------- |  --------------------------------------------- |
+| `name`                   | ✅      | ✅    | 🟩      | Full name                                     |
+| `email`                  | 🟩      | 🟩    | --      |  Email (for your internal purposes)            |
+| `website`                | --      | ✅    | --      |  Business Website (for your internal purposes) |
+| `phone`                  | 🟩      | 🟩    | --      |  Mobile Phone (for your internal purposes)     |
+| `geographicAddress`      | 🟩      | 🟩    | 🟩      | Residencial or business address               |
+| `nationalIdentification` | 🟩      | 🟩    | 🟩      | National Identification number                |
+| `dateOfBirth`            | 🟩      | --    | 🟩      | Date of birth                                 |
+| `placeOfBirth`           | 🟩      | --    | 🟩      | Place of birth                                |
+| `countryOfResidence`     | 🟩      | --    | 🟩      | Country of Residence                          |
+| `lei`                    | --      | ✅    | 🟩      | LEI (Legal Entity Identifier)                 |
+| `countryOfRegistration`  | --      | 🟩    | 🟩      | Country of Registration                       |
+
+## Locales
+
+See [locales](src/locales.ts) for the list of supported locales.
+
 ## [License](LICENSE.md)
 
-BSD 3-Clause © Notabene Inc.
+MIT © Notabene Inc.