Component Events

Once you have configured and rendered the embedded component you can listen for events returned by the component and take the appropriate next step.

Embedded Component Events

The embedded components generate events that inform your system when the component has been rendered, if there is an error, or when all required data has been collected, allowing you to proceed with calling the Notabene API.

Error Handling

All embedded components, regardless of how they are rendered, give you the option to listen for errors.

component.on('error', (error) => {
	if (error.type === 'error') {
    switch (error.identifier) {
    	case 'SERVICE_UNAVAILABLE':
       // handle error
      	break;
      case 'TOKEN_INVALID':
      	// handle error
        break;
      //...
    }
  }
});

component.on('error', (error) => {
	if (error.type === CMType.Error) {
    switch (error.identifier) {
    	case ErrorIdentifierCode.SERVICE_UNAVAILABLE:
       // handle error
      	break;
      case ErrorIdentifierCode.TOKEN_INVALID:
      	// handle error
        break;
      //...
    }
  }
});

Possible Errors:

Error Identifier Code	Description/Message
SERVICE_UNAVAILABLE	The Notabene service is currently unavailable
TOKEN_INVALID	Auth Token is Invalid
WALLET_CONNECTION_FAILED	The connection to the wallet service failed, possibly due to network issues or unsupported wallet types.

Ready Event

All embedded components, regardless of how they are rendered, give you the option to listen for an event indicating the component is has been rendered.

component.on('ready', (ready) => {
	// component is ready
});

component.on('ready', (ready) => {
  // component is ready
});

Listening for a Completed Form

Withdrawal assist, deposit assist and connect wallet rendered in any mode return completed travel rule data or a non-custodial proof.

Rendering the component as a modal or popup returns a promise that will contain the data collected from the end user.

If rendering the component as an iFrame you can listen for the same promise as the modal and popup with the completion() attribute.

// modal
const { valid, value, txCreate, ivms101, proof } = await component.openModal();

// popup
const { valid, value, txCreate, ivms101, proof } = await component.popup();

// mount an iframe
component.mount("#output");
const { valid, value, txCreate, ivms101, proof } = await component.completion()

Completed Event - Status

Some of the completed events returned by the component will have a status.

Beneficiary VASP: pending
Beneficiary Proof - Self-Declaration: verified
Beneficiary Proof - Signature Proof: verified
Beneficiary Proof - Satoshi Test: pending
Beneficiary Proof - Screenshot: no status

Info Events

The Withdrawal Assist and Deposit Assist components receive an info event notifying the loading of the required configured fields.

component.on('info', (info) => {
	// info - logging source of required fields
});

component.on('info', (info) => {
  // info - logging source of required fields
});

These are the possible info events:

Type	Message
Info	Using Configured Field Options

Warning Events

The components send warning events to assist in debugging.

component.on('warning', (warning) => {
	if (error.type === 'warning') {
    switch (error.identifier) {
    	case 'JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE':
       // handle error
      	break;
      case 'WALLET_ADDRESS_NOT_CONNECTED':
      	// handle error
        break;
      //...
    }
  }
});

component.on('warning', (warning) => {
  // warning - jurisdictionally required fields not fetched
});

These are the possible warning events:

Warning Identifier Code	Type	Message	Description
JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE	Warning	Unable to fetch Travel Rule Field Options	Unable to calculate local transaction value
WALLET_ADDRESS_NOT_CONNECTED	Warning	Unable to complete action	Unable to resolve provided wallet address.
WALLET_ADDRESS_NOT_CONNECTED	Warning	Unable to complete action	User rejected signing action
WALLET_LOCKED	Warning	Device locked	Wallet is locked
WALLET_UNREACHABLE	Warning	Device app not open	Connection to wallet failed
WALLET_UNREACHABLE	Warning	Internal error occurred. Please try again.	Connection to wallet failed due to network issues or unsupported wallet type

Counterparty Assist Results

The Withdrawal Assist and Deposit Assist components both include an option for Counterparty Assist in which the user can share a link with a 3rd party to collect data about the counterparty of the transaction.
When data submission is handed off to third parties, we cannot predict how long it will take to complete the process and therefore special event handling is available to customize how the user experiences this flow.

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

{
  "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

{
  "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": {
      //...
    }
  }
}