@notabene/javascript-sdk 2.16.0 → 2.17.0-next.4

package/README.md

@@ -43,6 +43,8 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
     - [Parameters](#parameters-2)
   - [Deposit Assist](#deposit-assist)
     - [Parameters](#parameters-3)
+  - [Invoice Reader](#invoice-reader)
+    - [Response](#response)
   - [Counterparty Assist](#counterparty-assist)
     - [Use Cases](#use-cases)
     - [Counterparty Assist Configuration](#counterparty-assist-configuration)
@@ -52,6 +54,8 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
       - [Error reference](#error-reference)
   - [Warning Message handling](#warning-message-handling)
       - [Warning reference](#warning-reference)
+  - [Info Message handling](#info-message-handling)
+      - [Info reference](#info-reference)
   - [Transaction parameters](#transaction-parameters)
     - [Asset specification](#asset-specification)
     - [Transaction amount](#transaction-amount)
@@ -68,6 +72,7 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
       - [Section Options](#section-options)
       - [Fallback Promotion](#fallback-promotion)
       - [Legacy Behavior](#legacy-behavior)
+      - [Contact Support](#contact-support)
     - [Configuring ownership proofs](#configuring-ownership-proofs)
       - [Supporting Micro Transactions (aka Satoshi tests)](#supporting-micro-transactions-aka-satoshi-tests)
       - [Fallback Proof Options](#fallback-proof-options)
@@ -432,6 +437,51 @@ const deposit = notabene.createDepositAssist(
 
 If any of the required parameters are missing the component will just show the Notabene badge.
 
+## Invoice Reader
+
+The Invoice Reader component extracts structured [TAIP-16](https://tap.rsvp/TAIPs/taip-16) invoice data from a PDF invoice. The component renders a drag-and-drop upload UI; once the user drops a PDF, it is parsed and the extracted invoice, merchant, and customer data are returned to the host.
+
+It takes no input parameters.
+
+```js
+const reader = notabene.createInvoiceReader();
+reader.mount('#nb-invoice-reader');
+
+const { invoice, merchant, customer } = await reader.completion();
+```
+
+It also supports `openModal()` and `popup()` like the other components:
+
+```js
+const { invoice, merchant, customer } = await notabene
+  .createInvoiceReader()
+  .openModal();
+It also supports `openModal()` and `popup()` like the other components:
+
+```js
+// Modal
+const { invoice, merchant, customer } = await notabene
+  .createInvoiceReader()
+  .openModal();
+
+// Popup
+const { invoice, merchant, customer } = await notabene
+  .createInvoiceReader()
+  .popup();
+```  
+
+### Response
+
+The component emits a `complete` event (and resolves the `completion()` / `openModal()` / `popup()` promise) with an `InvoiceReaderResponse`:
+
+| Field      | Type      | Description                                                                                       |
+|------------|-----------|---------------------------------------------------------------------------------------------------|
+| `invoice`  | `Invoice` | The parsed TAIP-16 invoice (id, issueDate, currencyCode, lineItems, total, taxTotal, …)           |
+| `merchant` | `Party`   | The parsed TAIP-16 party issuing the invoice, extracted from the PDF                                             |
+| `customer` | `Party`   | The  parsed TAIP-16 party the invoice is addressed to, extracted from the PDF                                     |
+
+All fields are optional — if the PDF cannot be parsed or a section is missing, the corresponding field will be `undefined`.
+
 ---
 
 ## Counterparty Handoff
@@ -694,6 +744,25 @@ component.on('warning', (event) => {
 | `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
 
@@ -806,6 +875,7 @@ const options: TransactionOptions = {
     },
   },
   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: [
@@ -813,6 +883,13 @@ const options: TransactionOptions = {
       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'
@@ -820,6 +897,9 @@ const options: TransactionOptions = {
       PersonType.SELF, // JS: 'self'
     ],
   },
+  contactSupport: { // Configures the contact support button (enabled via agentSections)
+    supportUrl: 'https://support.example.com',
+  },
   hide: [ValidationSections.ASSET, ValidationSections.DESTINATION], // Don't show specific sections of component
   autoSubmit: false // Automatically sends the complete event and hides the complete button -  Default false
 };
@@ -935,6 +1015,7 @@ Fields like `proofs.deminimis`, `proofs.microTransfer`, and `proofs.reuseProof`
 | `'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`).
 
@@ -955,6 +1036,41 @@ const options: TransactionOptions = {
 
 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.