@notabene/javascript-sdk 2.14.2 → 2.15.0-next.1

package/package.json

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

package/src/__tests__/notabene.test.ts

@@ -1,5 +1,5 @@
 import { fc, test } from '@fast-check/vitest';
-import { describe } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import Notabene from '../notabene';
 import {
   abitraryCallbackOptions,
@@ -14,11 +14,13 @@ import {
   arbitraryWithdrawal,
 } from '../utils/arbitraries';
 
+const arbitraryNodeUrl = () => fc.webUrl().map((u) => u.replace(/\/+$/, ''));
+
 describe('Notabene', () => {
   describe('defaults', () => {
     test.prop([
       fc.string({ minLength: 3 }),
-      fc.webUrl(),
+      arbitraryNodeUrl(),
       arbitraryComponent(),
       fc.object(),
     ])(
@@ -32,7 +34,7 @@ describe('Notabene', () => {
         return (
           url.hash ===
             `#authToken=${encodeURIComponent(authToken)}&value=${encodeURIComponent(JSON.stringify(value))}` &&
-          url.searchParams.get('nodeUrl') === nodeUrl &&
+          url.searchParams.get('nodeUrl') === nodeUrl.replace(/\/+$/, '') &&
           url.pathname === `/${component}`
         );
       },
@@ -42,7 +44,7 @@ describe('Notabene', () => {
   describe('locale', () => {
     test.prop([
       fc.string({ minLength: 3 }),
-      fc.webUrl(),
+      arbitraryNodeUrl(),
       arbitraryComponent(),
       fc.object(),
       arbitraryLocale(),
@@ -84,7 +86,7 @@ describe('Notabene', () => {
   describe('with uxUrl', () => {
     test.prop([
       fc.string({ minLength: 3 }),
-      fc.webUrl(),
+      arbitraryNodeUrl(),
       arbitraryComponent(),
       fc.webAuthority(),
       fc.object(),
@@ -113,7 +115,7 @@ describe('Notabene', () => {
   describe('with value and configuration', () => {
     test.prop([
       fc.string({ minLength: 3 }),
-      fc.webUrl(),
+      arbitraryNodeUrl(),
       arbitraryComponent(),
       fc.object(),
       fc.object(),
@@ -140,7 +142,7 @@ describe('Notabene', () => {
   describe('with value and configuration', () => {
     test.prop([
       fc.string({ minLength: 3 }),
-      fc.webUrl(),
+      arbitraryNodeUrl(),
       arbitraryComponent(),
       fc.object(),
       fc.object(),
@@ -170,7 +172,7 @@ describe('Notabene', () => {
   describe('createWithdrawalAssist', () => {
     test.prop([
       fc.string({ minLength: 3 }), // authToken
-      fc.webUrl(), // nodeUrl
+      arbitraryNodeUrl(), // nodeUrl
       arbitraryWithdrawal(),
       arbitraryTransactionOptions(), // options
       abitraryCallbackOptions(), // callbacks
@@ -204,7 +206,7 @@ describe('Notabene', () => {
   describe('createDepositRequest', () => {
     test.prop([
       fc.string({ minLength: 3 }), // authToken
-      fc.webUrl(), // nodeUrl
+      arbitraryNodeUrl(), // nodeUrl
       arbitraryDepositRequest(),
       arbitraryDepositRequestOptions(), // options
       abitraryCallbackOptions(), // callbacks
@@ -238,7 +240,7 @@ describe('Notabene', () => {
   describe('createConnectWallet', () => {
     test.prop([
       fc.string({ minLength: 3 }), // authToken
-      fc.webUrl(), // nodeUrl
+      arbitraryNodeUrl(), // nodeUrl
       arbitraryConnectionRequest(),
       arbitraryConnectionOptions(), // options
       abitraryCallbackOptions(), // callbacks
@@ -268,10 +270,80 @@ describe('Notabene', () => {
       },
     );
   });
+  describe('nodeUrl trailing slash normalization', () => {
+    it('should strip a single trailing slash', () => {
+      const notabene = new Notabene({
+        nodeUrl: 'https://api.eu1.notabene.id/',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.searchParams.get('nodeUrl')).toBe(
+        'https://api.eu1.notabene.id',
+      );
+    });
+
+    it('should strip multiple trailing slashes', () => {
+      const notabene = new Notabene({
+        nodeUrl: 'https://api.eu1.notabene.id///',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.searchParams.get('nodeUrl')).toBe(
+        'https://api.eu1.notabene.id',
+      );
+    });
+
+    it('should leave a clean URL unchanged', () => {
+      const notabene = new Notabene({
+        nodeUrl: 'https://api.eu1.notabene.id',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.searchParams.get('nodeUrl')).toBe(
+        'https://api.eu1.notabene.id',
+      );
+    });
+
+    it('should trim whitespace', () => {
+      const notabene = new Notabene({
+        nodeUrl: '  https://api.eu1.notabene.id  ',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.searchParams.get('nodeUrl')).toBe(
+        'https://api.eu1.notabene.id',
+      );
+    });
+
+    it('should throw for an invalid URL', () => {
+      expect(
+        () => new Notabene({ nodeUrl: 'not-a-url', authToken: 'token' }),
+      ).toThrow('Invalid nodeUrl');
+    });
+
+    it('should throw for a non-http protocol', () => {
+      expect(
+        () =>
+          new Notabene({ nodeUrl: 'ftp://example.com', authToken: 'token' }),
+      ).toThrow('must start with http:// or https://');
+    });
+
+    it('should preserve URL paths', () => {
+      const notabene = new Notabene({
+        nodeUrl: 'https://api.notabene.id/v2',
+        authToken: 'token',
+      });
+      const url = new URL(notabene.componentUrl('withdrawal-assist', {}));
+      expect(url.searchParams.get('nodeUrl')).toBe(
+        'https://api.notabene.id/v2',
+      );
+    });
+  });
+
   describe('createDepositAssist', () => {
     test.prop([
       fc.string({ minLength: 3 }), // authToken
-      fc.webUrl(), // nodeUrl
+      arbitraryNodeUrl(), // nodeUrl
       arbitraryDeposit(),
       arbitraryTransactionOptions(), // options
       abitraryCallbackOptions(), // callbacks

package/src/components/EmbeddedComponent.ts

@@ -1,12 +1,12 @@
 import {
   CMType,
   HMType,
-  HostMessage,
-  TransactionResponse,
-  ValidationError,
+  type HostMessage,
+  type TransactionResponse,
+  type ValidationError,
 } from '../types';
 import {
-  MessageCallback,
+  type MessageCallback,
   MessageEventManager,
 } from '../utils/MessageEventManager';
 

package/src/ivms/v2Types.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   NaturalPerson,
   NaturalPersonName,
   NaturalPersonNameTypeCode,

package/src/notabene.ts

@@ -2,6 +2,7 @@ import EmbeddedComponent from './components/EmbeddedComponent';
 import type {
   Account,
   Agent,
+  AgentSections,
   BlockchainAddress,
   CAIP10,
   CAIP19,
@@ -45,6 +46,7 @@ import type {
   RefreshSource,
   ResizeRequest,
   ScreenshotProof,
+  SectionOption,
   SignatureProof,
   SIWXInput,
   SolanaMetadata,
@@ -70,7 +72,6 @@ import {
   ErrorIdentifierCode,
   HMType,
   IdentityVerificationMethod,
-  OAuthProvider,
   PersonType,
   ProofStatus,
   ProofTypes,
@@ -113,7 +114,6 @@ export {
   ErrorIdentifierCode,
   HMType,
   IdentityVerificationMethod,
-  OAuthProvider,
   PersonType,
   ProofStatus,
   ProofTypes,
@@ -125,6 +125,7 @@ export {
 export type {
   Account,
   Agent,
+  AgentSections,
   BlockchainAddress,
   CAIP10,
   CAIP19,
@@ -169,6 +170,7 @@ export type {
   RefreshSource,
   ResizeRequest,
   ScreenshotProof,
+  SectionOption,
   SignatureProof,
   SIWXInput,
   SolanaMetadata,
@@ -228,6 +230,23 @@ export interface NotabeneConfig {
  *
  * @public
  */
+/** Trim whitespace, validate, and strip trailing slashes from a URL. */
+function normalizeUrl(url: string, field: string): string {
+  const normalized = url.trim().replace(/\/+$/, '');
+  let parsed: URL;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error(`Invalid ${field}: "${url}" is not a valid URL`);
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(
+      `Invalid ${field}: "${url}" (must start with http:// or https://)`,
+    );
+  }
+  return normalized;
+}
+
 export default class Notabene {
   private nodeUrl?: string;
   private authToken?: string;
@@ -241,8 +260,13 @@ export default class Notabene {
    * @param config - Configuration options for the Notabene SDK
    */
   constructor(config: NotabeneConfig) {
-    this.uxUrl = config.uxUrl || 'https://connect.notabene.id';
-    this.nodeUrl = config.nodeUrl;
+    this.uxUrl = normalizeUrl(
+      config.uxUrl || 'https://connect.notabene.id',
+      'uxUrl',
+    );
+    this.nodeUrl = config.nodeUrl
+      ? normalizeUrl(config.nodeUrl, 'nodeUrl')
+      : undefined;
     this.authToken = config.authToken;
     this.theme = config.theme;
     this.locale = config.locale;

package/src/responseTransformer/__tests__/transformer.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { OriginatorV2 } from '../../ivms/v2Types';
+import type { OriginatorV2 } from '../../ivms/v2Types';
 import type { Deposit, TransactionResponse, Withdrawal } from '../../types';
 import { PersonType } from '../../types';
 import { componentResponseToTxRequests, enrichConfig } from '../transformer';

package/src/responseTransformer/mappers.ts

@@ -7,8 +7,8 @@ import type {
 } from '@notabene/javascript-sdk/src/ivms/types';
 import type { Agent } from '@taprsvp/types';
 import {
-  Deposit,
   PersonType,
+  type Deposit,
   type IVMS101,
   type V1Transaction,
   type Withdrawal,

package/src/responseTransformer/transformer.ts

@@ -1,8 +1,8 @@
 import { decodeJwt } from 'jose';
 import {
-  Deposit,
-  DID,
   PersonType,
+  type Deposit,
+  type DID,
   type OwnershipProof,
   type TransactionResponse,
   type Withdrawal,

package/src/responseTransformer/utils.ts

@@ -4,12 +4,12 @@ import type {
 } from '@notabene/javascript-sdk/src/ivms/types';
 import { CAIP10Schema, type DID } from '@taprsvp/types';
 import type { NaturalPersonNameV2, PersonV2 } from '../ivms';
-import { Deposit, Withdrawal } from '../types';
+import type { Deposit, Withdrawal } from '../types';
 
 export function isDeposit(
   transaction: Withdrawal | Deposit,
 ): transaction is Deposit {
-  return 'source' in transaction && transaction.source !== undefined;
+  return (transaction as Deposit).source !== undefined;
 }
 
 export function isWithdrawal(

package/src/types.ts

@@ -792,7 +792,6 @@ export type VASPOptions = {
  */
 export enum IdentityVerificationMethod {
   SMS = 'sms',
-  EMAIL = 'email',
 }
 
 /**
@@ -808,14 +807,6 @@ export enum CodeVerificationStatus {
   UNREACHABLE = 'unreachable',
 }
 
-/**
- * Supported OAuth providers for authentication
- * @public
- */
-export enum OAuthProvider {
-  COINBASE = 'coinbase',
-}
-
 /**
  * Configuration options for identity verification
  * @public
@@ -823,8 +814,6 @@ export enum OAuthProvider {
 export type IdentityVerificationConfig = {
   /** The required verification method. If not specified, none will be used */
   requiredMethod?: IdentityVerificationMethod;
-  /** OAuth provider(s) to use for authentication. Can be a single provider or array of providers */
-  oAuth?: OAuthProvider[] | OAuthProvider;
 };
 
 /**
@@ -839,6 +828,7 @@ export type CounterpartyAssistConfig =
   | boolean
   | {
       counterpartyTypes: PersonType[];
+      /** @remarks Requires a transactionId to be passed in. */
       identityVerification?: IdentityVerificationConfig;
     };
 
@@ -870,18 +860,68 @@ export interface ThresholdOptions {
   currency: ISOCurrency; // Currency of threshold
   proofTypes?: ProofTypes[]; // If left empty no proof will be required under threshold
 }
+/**
+ * Options that can be placed in either the main or fallback sections of the agent selection step.
+ *
+ * @remarks
+ * Combines proof types from {@link ProofTypes} with additional UI-specific options:
+ * - `ProofTypes.SelfDeclaration` — ownership proof via self-declaration
+ * - `ProofTypes.Screenshot` — ownership proof via screenshot upload
+ * - `ProofTypes.MicroTransfer` — ownership proof via micro-transfer
+ * - `'signature'` — wallet connection for ownership proof via signature
+ * - `'manual-signing'` — ownership proof via manual message signing
+ * - `'add-vasp'` — manually add an unlisted exchange/VASP (hosted flow)
+ *
+ * Options are automatically filtered by flow (e.g. `add-vasp` is ignored in self-hosted).
+ * Including an option implicitly enables that capability.
+ *
+ * @public
+ */
+export type SectionOption =
+  | ProofTypes.SelfDeclaration
+  | ProofTypes.Screenshot
+  | ProofTypes.MicroTransfer
+  | 'signature'
+  | 'manual-signing'
+  | 'add-vasp';
+
+/**
+ * Explicit layout configuration for the agent selection step.
+ *
+ * @remarks
+ * Controls which options appear in the main selection area vs. behind the
+ * "Can't find what you're looking for?" fallback toggle.
+ *
+ * When the main section has no options (empty or all filtered out), fallback options
+ * are promoted and shown inline. When the main section has only one option, a dedicated
+ * single-option layout is used.
+ *
+ * @public
+ */
+export interface AgentSections {
+  /** Options shown in the main selection area (always visible) */
+  main?: SectionOption[];
+  /** Options shown behind the "Can't find what you're looking for?" fallback toggle */
+  fallback?: SectionOption[];
+}
+
 /**
  * Configuration options for Transaction components
  * @public
  */
 export interface TransactionOptions {
+  /**
+   * Explicit layout configuration for the agent selection step.
+   * When provided, takes precedence over legacy fields (`proofs.fallbacks`, `vasps.addUnknown`).
+   */
+  agentSections?: AgentSections;
   proofs?: {
     reuseProof?: boolean; // Defaults true
     microTransfer?: {
       destination: BlockchainAddress;
       amountSubunits: string;
     };
-    fallbacks?: ProofTypes[];
+    fallbacks?: ProofTypes[]; // Legacy — replaced by agentSections.fallback
     deminimis?: ThresholdOptions;
   };
   jurisdiction?: string;

package/src/utils/MessageEventManager.ts

@@ -1,4 +1,4 @@
-import { ComponentMessage, HostMessage } from '../types';
+import type { ComponentMessage, HostMessage } from '../types';
 
 /**
  * Callback function for handling component messages.

package/src/utils/__tests__/connections.test.ts

@@ -3,9 +3,9 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { DID, RefreshSource } from '../../types';
 import {
   ConnectionManager,
-  ConnectionStatus,
+  type ConnectionStatus,
   getRefreshResult,
-  TransactionType,
+  type TransactionType,
 } from '../connections';
 import { seal } from '../encryption';
 

package/src/utils/__tests__/encryption.test.ts

@@ -1,6 +1,6 @@
 import * as fc from 'fast-check';
 import { describe, expect, it } from 'vitest';
-import { Agent, AgentType } from '../../types';
+import { type Agent, AgentType } from '../../types';
 import { seal, unseal } from '../encryption';
 
 // Helper to validate that two objects are deeply equal