@notabene/javascript-sdk 2.15.0-next.2 → 2.15.0

package/README.md

@@ -64,6 +64,10 @@ This library is the JavaScript SDK for loading the Notabene UX components in the
       - [Only allow first party transactions](#only-allow-first-party-transactions)
       - [Only VASP to VASP transactions](#only-vasp-to-vasp-transactions)
       - [Only Self-hosted wallet transactions](#only-self-hosted-wallet-transactions)
+    - [Agent Section Layout](#agent-section-layout)
+      - [Section Options](#section-options)
+      - [Fallback Promotion](#fallback-promotion)
+      - [Legacy Behavior](#legacy-behavior)
     - [Configuring ownership proofs](#configuring-ownership-proofs)
       - [Supporting Micro Transactions (aka Satoshi tests)](#supporting-micro-transactions-aka-satoshi-tests)
       - [Fallback Proof Options](#fallback-proof-options)
@@ -747,10 +751,16 @@ 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: {
@@ -893,6 +903,55 @@ const options: TransactionOptions = {
 };
 ```
 
+### 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 |
+
+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.
+
+```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.
+
 ### Configuring ownership proofs
 
 By default components support message signing proofs.

package/dist/cjs/notabene.d.ts

@@ -1345,6 +1345,15 @@ declare type NaturalPersonV2 = Omit<NaturalPerson_2, 'name'> & {
     name: NaturalPersonNameV2;
 };
 
+/**
+ * Primary constructor for Notabene UX elements
+ *
+ * This class provides methods to create and manage various Notabene components
+ * such as withdrawal assist, deposit assist, connect, and deposit request.
+ * It also handles URL generation and fragment decoding for these components.
+ *
+ * @public
+ */
 declare class Notabene {
     private nodeUrl?;
     private authToken?;

package/dist/cjs/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.15.0-next.2",
+  "version": "2.15.0",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/dist/esm/notabene.d.ts

@@ -1345,6 +1345,15 @@ declare type NaturalPersonV2 = Omit<NaturalPerson_2, 'name'> & {
     name: NaturalPersonNameV2;
 };
 
+/**
+ * Primary constructor for Notabene UX elements
+ *
+ * This class provides methods to create and manage various Notabene components
+ * such as withdrawal assist, deposit assist, connect, and deposit request.
+ * It also handles URL generation and fragment decoding for these components.
+ *
+ * @public
+ */
 declare class Notabene {
     private nodeUrl?;
     private authToken?;

package/dist/esm/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.15.0-next.2",
+  "version": "2.15.0",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/dist/notabene.d.ts

@@ -1345,6 +1345,15 @@ declare type NaturalPersonV2 = Omit<NaturalPerson_2, 'name'> & {
     name: NaturalPersonNameV2;
 };
 
+/**
+ * Primary constructor for Notabene UX elements
+ *
+ * This class provides methods to create and manage various Notabene components
+ * such as withdrawal assist, deposit assist, connect, and deposit request.
+ * It also handles URL generation and fragment decoding for these components.
+ *
+ * @public
+ */
 declare class Notabene {
     private nodeUrl?;
     private authToken?;

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.15.0-next.2",
+  "version": "2.15.0",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/src/__tests__/notabene.test.ts

@@ -340,6 +340,56 @@ describe('Notabene', () => {
     });
   });
 
+  describe('uxUrl trailing slash normalization', () => {
+    it('should strip a single trailing slash', () => {
+      const notabene = new Notabene({
+        uxUrl: 'https://connect.notabene.id/',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.origin).toBe('https://connect.notabene.id');
+    });
+
+    it('should strip multiple trailing slashes', () => {
+      const notabene = new Notabene({
+        uxUrl: 'https://connect.notabene.id///',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.origin).toBe('https://connect.notabene.id');
+    });
+
+    it('should leave a clean URL unchanged', () => {
+      const notabene = new Notabene({
+        uxUrl: 'https://connect.notabene.id',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.origin).toBe('https://connect.notabene.id');
+    });
+
+    it('should trim whitespace', () => {
+      const notabene = new Notabene({
+        uxUrl: '  https://connect.notabene.id  ',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.origin).toBe('https://connect.notabene.id');
+    });
+
+    it('should throw for an invalid URL', () => {
+      expect(
+        () => new Notabene({ uxUrl: 'not-a-url', authToken: 'token' }),
+      ).toThrow('Invalid uxUrl');
+    });
+
+    it('should throw for a non-http protocol', () => {
+      expect(
+        () => new Notabene({ uxUrl: 'ftp://example.com', authToken: 'token' }),
+      ).toThrow('must start with http:// or https://');
+    });
+  });
+
   describe('createDepositAssist', () => {
     test.prop([
       fc.string({ minLength: 3 }), // authToken

package/src/notabene.ts

@@ -221,15 +221,7 @@ export interface NotabeneConfig {
    */
   locale?: string;
 }
-/**
- * Primary constructor for Notabene UX elements
- *
- * This class provides methods to create and manage various Notabene components
- * such as withdrawal assist, deposit assist, connect, and deposit request.
- * It also handles URL generation and fragment decoding for these components.
- *
- * @public
- */
+
 /** Trim whitespace, validate, and strip trailing slashes from a URL. */
 function normalizeUrl(url: string, field: string): string {
   const normalized = url.trim().replace(/\/+$/, '');
@@ -247,6 +239,15 @@ function normalizeUrl(url: string, field: string): string {
   return normalized;
 }
 
+/**
+ * Primary constructor for Notabene UX elements
+ *
+ * This class provides methods to create and manage various Notabene components
+ * such as withdrawal assist, deposit assist, connect, and deposit request.
+ * It also handles URL generation and fragment decoding for these components.
+ *
+ * @public
+ */
 export default class Notabene {
   private nodeUrl?: string;
   private authToken?: string;