# Notabene SafeConnect Components JavaScript SDK [](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/master) [](https://www.npmjs.com/package/@notabene/javascript-sdk) [](https://www.npmjs.com/package/@notabene/javascript-sdk) [](https://bundlephobia.com/package/@notabene/javascript-sdk) [](https://www.npmjs.com/package/@notabene/javascript-sdk) [](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/main/LICENSE.md) [](https://libraries.io/npm/@notabene%2Fjavascript-sdk) This library is the JavaScript SDK for loading the Notabene UX components in the front-end. [Additional Documentation](https://devx.notabene.id/docs/embedded=ux)

...) ``` An example error object. ```ts type Error = { type: CMType.Error; message: string; description: string; identifier: ErrorIdentifierCode; }; ``` Errors can be handled in this way: ```ts component.on('error', (error) => { if (error.type === CMType.Error) { switch (error.identifier) { case ErrorIdentifierCode.SERVICE_UNAVAILABLE: // handle the error break; //... } } }); ``` #### Error reference | ErrorIdentifierCode | Description/Message | In Use | |--------------------------|----------------------------------------------------------------------------------------------------------|---| | 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. | ✅ | | WALLET_NOT_SUPPORTED | The wallet used does not support the required functionality or blockchain. | | ## Warning Message Handling Warning messages include an identifier code to help developers diagnose and handle specific error conditions. ```ts component.on('warning', (event) => { switch(event.identifier) { case WarningIdentifierCode.WALLET_ADDRESS_NOT_CONNECTED: // Handle wallet connection issue break; case WarningIdentifierCode.IDV_UNAVAILABLE: // Handle identity verification service unavailability break; case WarningIdentifierCode.WALLET_LOCKED: // Handle wallet locked or password is either not entered or invalid break; case WarningIdentifierCode.WALLET_UNREACHABLE: // Handle wallet connection failure break; case WarningIdentifierCode.JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE: // Handle jurisdictional compliance check failure break; } }); ``` ### Warning Reference | Identifier Code | Description | Status | |----------------|-------------|--------| | `WALLET_ADDRESS_NOT_CONNECTED` | The specified wallet address is not connected to the selected wallet | ✅ Active | | `IDV_UNAVAILABLE` | Identity verification service is unavailable for the transaction | ✅ Active | | `WALLET_LOCKED` | The wallet in use is either locked or not open. | ✅ Active | | `WALLET_UNREACHABLE` | Connection to wallet failed due to network issues or unsupported wallet type | ✅ Active | | `JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE` | Unable to retrieve jurisdictional compliance requirements | ✅ Active | ## Info Message handling Info messages notify the host application of events within the component. Some are purely informational, while others (identified by an `identifier` code) may require host-side handling. ```ts component.on('info', (event) => { switch (event.identifier) { case InfoIdentifierCode.CONTACT_SUPPORT: // User clicked the contact support button — open a support modal, redirect, etc. break; } }); ``` #### Info reference | Identifier Code | Description | Status | |----------------|-------------|--------| | `CONTACT_SUPPORT` | User clicked the contact support button | ✅ Active | ## 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. ### 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. ### Destination 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 ### Source 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 - [BIP-21](https://en.bitcoin.it/wiki/BIP_0021) Bitcoin URI - Native blockchain address ### Asset Price The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this: ```ts assetPrice: { currency: 'USD', // ISO currency code price: 1700.12, // Asset price }; ``` ## Configuration ### 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: ```ts import Notabene, { AgentType, PersonType, ProofTypes, type SectionOption, } from '@notabene/javascript-sdk'; const options: TransactionOptions = { jurisdiction: "US", // Defaults to the jurisdiction associated with customer token agentSections: { // Explicit control over agent selection layout main: ['signature', 'screenshot', 'microtransfer'], fallback: ['add-vasp', 'self-declaration'], // When agentSections is set, proofs.fallbacks and vasps.addUnknown below are ignored }, proofs: { reuseProof: true, // Defaults true microTransfer: { destination: '0x...', amountSubunits: '12344', requireHash: true, }, 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: { // V1 options — `searchable` is mutually exclusive with V2 `showTrustStatus` below 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 }, // V2 alternative — filter by trust status instead of `searchable`. `addUnknown` // and `onlyActive` remain valid; `searchable` cannot be combined with `showTrustStatus`: // vasps: { // addUnknown: true, // onlyActive: true, // showTrustStatus: ['TRUSTED', 'NEW'], // 'TRUSTED' | 'NEW' | 'FLAGGED' | 'BANNED' // }, counterpartyAssist: { // Allows users to share a link to collect counterparty data counterpartyTypes: [ PersonType.LEGAL, // JS: 'legal' PersonType.NATURAL, // JS: 'natural' PersonType.SELF, // JS: 'self' ], }, contactSupport: { // Configures the contact support button (enabled via agentSections) supportUrl: 'https://support.example.com', }, hide: ['asset', 'destination'], // Don't show specific sections of component. Also accepts 'header' to drop the card header (icon, title, description, participant logo) autoSubmit: false // Automatically sends the complete event and hides the complete button - Default false }; 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', requireHash: true, }, }, }, ); ``` ### Common use cases #### Only allow first party transactions ```ts const firstParty: TransactionOptions = { allowedCounterpartyTypes: [ PersonType.SELF, // JS: 'self' ], }; ``` #### Only VASP to VASP transactions ```ts const vasp2vasp: TransactionOptions = { allowedAgentTypes: [AgentType.VASP], // js ['VASP'] }; ``` #### Only Self-hosted wallet transactions ```ts const options: TransactionOptions = { allowedAgentTypes: [AgentType.PRIVATE], // js ['WALLET'] }; ``` ### Configuring National Identifier Type The National Identifier Type is a dropdown that allows the developer configure the types of national identifiers they are supporting. ```ts const options: TransactionOptions = { fields: { naturalPerson: { name: {optional: false}, nationalIdentification: { optional: true, // allow optional national identification nationalIdentifierType: { values: ['ARNU', 'CCPT', 'RAID', 'DRLC', 'TXID', 'SOCS'], // default values }, }, }, legalPerson: { name: true, lei: {optional: true}, nationalIdentification: { optional: false, // require national identification nationalIdentifierType: { values: ['RAID', 'TXID', 'MISC'], // default values }, }, }, }, }; ``` ### Agent Section Layout The `agentSections` option gives explicit control over which options appear in the main selection area vs. behind the "Can't find what you're looking for?" fallback toggle in the agent selection step. ```ts const options: TransactionOptions = { agentSections: { main: ['signature', 'screenshot', 'microtransfer'], fallback: ['add-vasp', 'self-declaration'], }, }; ``` When `agentSections` is provided, the following legacy fields are ignored: - `proofs.fallbacks` — use `agentSections.fallback` instead - `vasps.addUnknown` — include `'add-vasp'` in `agentSections` instead Fields like `proofs.deminimis`, `proofs.microTransfer`, and `proofs.reuseProof` continue to work as before. #### Section Options | Option | Flow | Description | |--------|------|-------------| | `'signature'` | Self-hosted | Wallet connection for ownership proof via signature | | `'self-declaration'` | Self-hosted | Self-declaration of wallet ownership (`ProofTypes.SelfDeclaration`) | | `'screenshot'` | Self-hosted | Ownership proof via screenshot upload (`ProofTypes.Screenshot`) | | `'microtransfer'` | Self-hosted | Ownership proof via micro-transfer (`ProofTypes.MicroTransfer`) | | `'manual-signing'` | Self-hosted | Ownership proof via manual message signing (no `ProofTypes` equivalent) | | `'add-vasp'` | Hosted | Manually add an unlisted exchange/VASP | | `'contact-support'` | Both | Show a contact support button | Options are automatically filtered by flow — e.g. `'add-vasp'` is ignored in the self-hosted tab, `'signature'` is ignored in the hosted tab. Including an option implicitly enables that capability (e.g. `'add-vasp'` enables VASP creation without needing `vasps.addUnknown`). #### Fallback Promotion When the main section has **no options** (either empty, omitted, or all filtered out for the current flow), fallback options are automatically promoted and shown inline instead of behind the toggle. A section whose only remaining option is a proof form (`'self-declaration'`, `'screenshot'`, `'microtransfer'` or `'manual-signing'`) opens that form straight away instead of showing a one-entry list. This also applies to the third-party self-hosted flow, to a `deminimis.proofTypes` list with a single entry, and to a deposit without a `source` on a V2 node, where only the self-declaration is offered. ```ts // Only fallback options — these get promoted to main since main is empty const options: TransactionOptions = { agentSections: { fallback: ['self-declaration'], }, }; ``` #### Legacy Behavior When `agentSections` is **not** provided, the existing behavior using `proofs.fallbacks` and `vasps.addUnknown` is preserved. #### Contact Support Include `'contact-support'` in `agentSections.main` or `agentSections.fallback` to show a contact support button in the agent selection step. ```ts const options: TransactionOptions = { agentSections: { main: ['signature'], fallback: ['contact-support'], }, }; ``` By default, clicking the button sends an `info` message to the host application, letting the host decide what to do (open a modal, redirect, etc.). To also provide a URL that the widget attempts to open as a fallback, use the `contactSupport` config: ```ts const options: TransactionOptions = { agentSections: { main: ['signature'], fallback: ['contact-support'], }, contactSupport: { supportUrl: 'https://support.example.com', }, }; ``` | Property | Type | Description | |----------|------|-------------| | `supportUrl` | `string` | URL to open when the user clicks the support button | > **Note:** If `'contact-support'` is not included in `agentSections`, the button is hidden regardless of the `contactSupport` configuration. ### Configuring ownership proofs By default components support message signing proofs. #### Supporting Micro Transactions (aka Satoshi tests) You can support Micro Transfers (aka Satoshi tests) by adding a deposit address for the test. Your compliance team will have to determine how to handle and verify these transactions in the rules engine or individually. | Property | Type | Description | |----------|------|-------------| | `destination` | `string` | The deposit address for the micro-transfer test | | `amountSubunits` | `string` | The amount in subunits (e.g. satoshis, wei) to send | | `requireHash` | `boolean` | When `true`, the user must provide the transaction hash as proof (default true) | ```ts const options: TransactionOptions = { proofs: { microTransfer: { destination: '0x...', amountSubunits: '1234', requireHash: true, }, fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration'] }, }; ``` Notabene does not currently verify these tests automatically as you likely already have the infrastructure to do so. You will receive a response back from the component containing a proof object. For MicroTransfers it will look like this: ```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: ```ts const options: TransactionOptions = { proofs: { fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration'] }, }; ``` The two options are: - `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 By default, counterparty fields are determined based on the rules of the jurisdiction associated with the VASP using the component. This ensures compliance even when fields are not explicitly configured. If a specific jurisdiction is manually configured, the component will instead derive the fields according to that jurisdiction’s rules. For VASPs seeking more granular control over the fields displayed to customers about counterparties, the fields object can be used to customize visibility. Required and optional fields can be configured independently for both natural and legal persons. We recommend working closely with your compliance team when making these configurations, as regulatory requirements vary significantly across jurisdictions. 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: {optional: true }, // Default optional website: { optional: true }, // Default optional 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. ## Theming You can optionally theme the UI when creating an instance of `Notabene` ```js const notabene = new Notabene({ nodeUrl: 'https://api.notabene.id', authToken: 'YOUR_CUSTOMER_TOKEN', theme: { mode: 'light', // Color mode: 'light' or 'dark' primaryColor: '#0a852d', // Main brand color (buttons, highlights, accents) primaryForeground: '#000000', // Text/icon color displayed on top of primaryColor backgroundColor: '#ffffff', // Base background color for the component fontFamily: 'Montserrat' // Font family (supports Google Fonts) } }); ``` ## [License](LICENSE.md) MIT © Notabene Inc.