@notabene/javascript-sdk 1.32.0 → 2.0.0-next.2

package/src/types.ts

@@ -1,5 +1,43 @@
-import { DateAndPlaceOfBirth, NationalIdentification } from 'ivms/types';
+import {
+  DateAndPlaceOfBirth,
+  IVMS101,
+  NationalIdentification,
+} from './ivms/types';
 
+export type { IVMS101 };
+
+export type CAIP2 = string;
+export type CAIP10 = string;
+export type CAIP19 = string;
+export type CAIP220 = string;
+
+export type DTI = string;
+export type NotabeneAsset = string;
+
+/**
+ * The asset of a transaction either a Notabene asset, a CAIP-19 asset, or a DTI.
+ *
+ * @public
+ */
+
+export type TransactionAsset = NotabeneAsset | CAIP19 | DTI;
+
+export type BlockchainAddress = string;
+export type TravelAddress = string;
+
+/**
+ * The destination of a transaction either a blockchain address, a CAIP-19 address, or a travel address.
+ * @public
+ */
+export type Destination = BlockchainAddress | CAIP19 | TravelAddress;
+export type Source = BlockchainAddress | CAIP19;
+export type URI = string;
+export type DID = string;
+
+/**
+ * The theme of the Notabene SDK
+ * @public
+ */
 export type Theme = {
   primaryColor: string;
   secondaryColor: string;
@@ -7,21 +45,44 @@ export type Theme = {
   logo: string;
 };
 
-export enum WidgetType {
-  WITHDRAWAL = 'WITHDRAWAL',
-  POST_DEPOSIT = 'POST_DEPOSIT',
+export enum ComponentTypes {
+  WITHDRAW_ASSIST = 'WITHDRAW_ASSIST',
 }
 
+export type TransactionType = 'VASP_2_VASP' | 'SELF_HOSTED';
+
 export type TransactionTypeAllowed =
   | 'ALL'
   | 'VASP_2_VASP_ONLY'
-  | 'SELF_TRANSACTION_ONLY';
+  | 'FIRST_PARTY_ONLY';
 
 export type NonCustodialDeclarationType =
   | 'SIGNATURE'
   | 'DECLARATION'
   | 'SIGNATURE_AND_DECLARATION';
 
+/**
+ * The type of Agent. Either a wallet or a VASP
+ * @public
+ */
+
+export enum AgentType {
+  PRIVATE = 'WALLET',
+  VASP = 'VASP',
+}
+
+/**
+ * Who is the agent acting on behalf of the counterparty
+ * @public
+ */
+export declare interface Agent {
+  did: DID;
+  type: AgentType;
+  logo?: string;
+  url?: string;
+  name?: string;
+  verified?: boolean;
+}
 export type OwnershipProofInput = {
   type?: string | null;
   proof?: string | null;
@@ -37,55 +98,134 @@ export type CountryType = {
   name: string;
 };
 
-export type PersonType = 'natural' | 'legal';
+/**
+ * The type of counterparty. Either a natural person or a legal person. If the customer is the same as the counterparty then the counterparty is a self.
+ * @public
+ */
+export enum PersonType {
+  NATURAL = 'natural',
+  LEGAL = 'legal',
+  SELF = 'self', // first party
+}
+
+/**
+ * A VASP agent acting on behalf of the counterparty
+ * @public
+ */
+export interface VASP extends Agent {
+  url?: string;
+  name?: string;
+}
+/**
+ * A wallet agent acting on behalf of the counterparty
+ * @public
+ */
+export interface Wallet extends Agent {
+  proof: OwnershipProof;
+  wallet_connect_id?: string;
+}
+
+/**
+ * The counterparty of a transaction.
+ * @public
+ */
+export interface Counterparty {
+  name?: string;
+  accountNumber?: string;
+  did?: string;
+  geographicAddress?: string;
+  type?: PersonType;
+  verified?: boolean;
+}
+/**
+ * A counterparty object representing a natural person
+ * @public
+ */
+export interface NaturalPerson extends Counterparty {
+  type: PersonType.NATURAL;
+  nationalIdentification?: NationalIdentification;
+  dateAndPlaceOfBirth?: DateAndPlaceOfBirth;
+  name: string;
+}
+
+/**
+ * A counterparty object representing a legal person
+ * @public
+ */
+export interface LegalPerson extends Counterparty {
+  type: PersonType.LEGAL;
+  name: string;
+  lei?: string;
+  url?: string;
+  logo?: string;
+}
 
 export type OriginatorFields = {
-  originatorAccountNumber?: string;
-  originatorDid?: string;
-  originatorVASPname?: string;
-  originatorVASPdid?: string;
-  originatorName?: string;
-  originatorGeographicAddress?: string;
-  originatorNationalIdentification?: NationalIdentification;
-  originatorDateAndPlaceOfBirth?: DateAndPlaceOfBirth;
-  originatorPersonType?: PersonType;
+  source?: Source;
 };
 
 export type BeneficiaryFields = {
-  beneficiaryAccountNumber?: string;
-  beneficiaryDid?: string;
-  beneficiaryVASPname?: string;
-  beneficiaryVASPdid?: string;
-  beneficiaryName?: string;
-  beneficiaryGeographicAddress?: string;
-  beneficiaryNationalIdentification?: NationalIdentification;
-  beneficiaryDateAndPlaceOfBirth?: DateAndPlaceOfBirth;
-  beneficiaryPersonType?: PersonType;
-};
-
-export type CAIP19 = {
-  caip19: string;
-};
-
-export type CoingeckoIdAndNetwork = { coingeckoId: string; network: string };
-
-export type TransactionAsset = string | CAIP19 | CoingeckoIdAndNetwork;
-export type Transaction = OriginatorFields &
-  BeneficiaryFields & {
-    transactionAsset: TransactionAsset;
-    transactionAmount: string;
-    transactionBlockchainInfo?: TransactionBlockchainInfo;
-    customAssetPrice?: {
-      priceUSD: number;
-      decimals: number;
-    };
-    isNonCustodial?: boolean;
-    originatorEqualsBeneficiary?: boolean;
-    beneficiaryProof?: OwnershipProofInput;
-    originatorProof?: OwnershipProofInput;
-    isValid?: boolean;
-    errors?: string[];
+  destination?: Destination;
+};
+
+/**
+ * An abstract transaction object
+ * @public
+ */
+export interface Transaction {
+  agent: Agent;
+  customer?: Counterparty;
+  counterparty: Counterparty;
+  asset: TransactionAsset;
+  amountDecimal: number;
+  // transactionBlockchainInfo?: TransactionBlockchainInfo;
+  customAssetPrice?: {
+    price: number;
+    currency: string;
   };
+}
+
+/**
+ * An object representing a withdrawal transaction
+ * @public
+ */
+export interface Withdrawal extends BeneficiaryFields, Transaction {}
+/**
+ * An object representing a deposit transaction
+ * @public
+ */
+export interface Deposit extends OriginatorFields, Transaction {}
+
+/**
+ * The verification status of a transaction
+ * @public
+ */
+export enum Status {
+  EMPTY = 'empty',
+  VERIFY = 'verify',
+  PENDING = 'pending',
+  VERIFIED = 'verified',
+  BANNED = 'banned',
+}
+
+/**
+ * The response of a transaction
+ * @public
+ */
+
+export type TransactionResponse = {
+  value: Transaction;
+  ivms: IVMS101;
+  proof?: OwnershipProof;
+  valid: boolean;
+  status: Status;
+  errors: ValidationError[];
+};
+
+export type ValidationError = {
+  attribute: string;
+  message: string;
+};
 
 export type FieldProps = {
   forceDisplay?: boolean; // instead of beneficiaryDetails - defaults to false
@@ -95,6 +235,7 @@ export type FieldProps = {
 export type FieldName =
   | 'counterparty'
   | 'geographicAddress'
+  | 'firstName'
   | 'name'
   | 'nationalIdentification'
   | 'dateAndPlaceOfBirth';
@@ -103,7 +244,7 @@ export type FieldsProps = {
   [name in FieldName]?: FieldProps;
 };
 
-type WalletNotSupportedFlow = {
+export type WalletNotSupportedFlow = {
   flow: 'WALLET_NOT_SUPPORTED';
   action: 'DECLARATION' | 'REJECT';
 };
@@ -112,3 +253,194 @@ type WalletNotSupportedFlow = {
 export type Fallback = WalletNotSupportedFlow;
 
 export type OptInFeature = 'REUSE_ADDRESS_OWNERSHIP_PROOF';
+
+/**
+ * Component Message Types
+ * @internal
+ */
+export const enum CMType {
+  COMPLETE = 'complete',
+  RESIZE = 'resize',
+  RESULT = 'result',
+  READY = 'ready',
+  INVALID = 'invalid',
+  MODAL = 'openModal',
+  ERROR = 'error',
+  CLOSE = 'closeModal',
+  CANCEL = 'cancel',
+}
+
+export type Completed = {
+  type: CMType.COMPLETE;
+  response: TransactionResponse;
+};
+
+export type Result = {
+  type: CMType.RESULT;
+  reqid: RequestID;
+  response: TransactionResponse;
+};
+
+export type Ready = {
+  type: CMType.READY;
+};
+
+export type ResizeRequest = {
+  type: CMType.RESIZE;
+  height: number;
+};
+
+export type Error = {
+  type: CMType.ERROR;
+  message: string;
+};
+
+export type ModalRequest = {
+  type: CMType.MODAL;
+  url: string;
+  reqid: RequestID;
+};
+
+export type CloseModal = {
+  type: CMType.CLOSE;
+  reqid: RequestID;
+};
+
+export type Cancel = {
+  type: CMType.CANCEL;
+};
+
+export type InvalidValue = {
+  type: CMType.INVALID;
+  value: any;
+  errors: ValidationError[];
+};
+
+/**
+ * Component Message
+ * @internal
+ */
+export type ComponentMessage =
+  | Completed
+  | Cancel
+  | Error
+  | Result
+  | Ready
+  | ResizeRequest
+  | ModalRequest
+  | InvalidValue
+  | CloseModal;
+
+export type RequestID = string;
+
+/**
+ * Host Message Types
+ * @internal
+ */
+
+export const enum HMType {
+  UPDATE = 'update',
+  REQUEST_RESPONSE = 'requestResponse',
+}
+
+export type UpdateValue = {
+  type: HMType.UPDATE;
+  value: Partial<Transaction>;
+};
+
+export type RequestResponse = {
+  type: HMType.REQUEST_RESPONSE;
+  reqid: RequestID;
+};
+
+/**
+ * Host Messages
+ * @internal
+ */
+
+export type HostMessage = UpdateValue | RequestResponse;
+
+export interface CallbackOptions {
+  callback?: URI;
+  redirectUri?: URI;
+}
+
+/**
+ * Status of the proof
+ * @public
+ */
+export enum ProofStatus {
+  PENDING = 'pending', // Verification is pending
+  FAILED = 'rejected', // Rejected
+  FLAGGED = 'flagged', // Flagged for manual review
+  VERIFIED = 'verified', // Verified
+}
+
+/**
+ * The type of Proofs supported
+ * @public
+ **/
+export enum ProofTypes {
+  SelfDeclaration = 'self-declaration',
+  PersonalSignEIP191 = 'eip-191',
+  PersonalSignEIP712 = 'eip-712',
+  PersonalSignBIP137 = 'bip-137',
+  PersonalSignXPUB = 'xpub',
+  MicroTransfer = 'microtransfer',
+  Screenshot = 'screenshot',
+}
+/**
+ * Ownership Proof
+ * @public
+ */
+export interface OwnershipProof {
+  type: ProofTypes;
+  status: ProofStatus;
+  did: DID;
+  address: CAIP10;
+}
+
+/**
+ * Ownership Proof using Message Signature
+ * @public
+ */
+export interface SignatureProof extends OwnershipProof {
+  type:
+    | ProofTypes.PersonalSignEIP191
+    | ProofTypes.PersonalSignEIP712
+    | ProofTypes.PersonalSignBIP137
+    | ProofTypes.PersonalSignXPUB;
+  proof: string;
+  attestation: string;
+  wallet_provider: string;
+}
+
+/**
+ * Ownership Proof using Self Declaration
+ * @public
+ */
+export interface DeclarationProof extends OwnershipProof {
+  type: ProofTypes.SelfDeclaration;
+  attestation: string;
+  confirmed: boolean;
+}
+
+/**
+ * Ownership Proof using Micro Transfer
+ * @public
+ */
+export interface MicroTransferProof extends OwnershipProof {
+  type: ProofTypes.MicroTransfer;
+  txhash: string;
+  chain: CAIP2;
+  amount: number;
+}
+
+/**
+ * Ownership Proof using Screenshot
+ * @public
+ */
+export interface ScreenshotProof extends OwnershipProof {
+  type: ProofTypes.Screenshot;
+  url: string;
+}

package/src/utils/MessageEventManager.ts

@@ -0,0 +1,55 @@
+import { ComponentMessage, HostMessage } from '../types';
+
+export type MessageCallback = (message: ComponentMessage) => void;
+
+export class MessageEventManager {
+  private listeners: Map<string, Set<MessageCallback>> = new Map();
+  private port?: MessagePort;
+
+  constructor() {
+    this.handleMessage = this.handleMessage.bind(this);
+  }
+
+  setPort(port: MessagePort): void {
+    this.port = port;
+    this.port.onmessage = this.handleMessage;
+    this.port.start();
+  }
+
+  on(messageType: string, callback: MessageCallback): void {
+    if (!this.listeners.has(messageType)) {
+      this.listeners.set(messageType, new Set());
+    }
+    this.listeners.get(messageType)!.add(callback);
+  }
+
+  off(messageType: string, callback: MessageCallback): void {
+    const callbacks = this.listeners.get(messageType);
+    if (callbacks) {
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        this.listeners.delete(messageType);
+      }
+    }
+  }
+
+  private handleMessage(event: MessageEvent): void {
+    console.log('received message', event.data);
+    const message = event.data;
+    if (typeof message === 'object' && message !== null && 'type' in message) {
+      const messageType = message.type as string;
+      const callbacks = this.listeners.get(messageType);
+      if (callbacks) {
+        callbacks.forEach((callback) => callback(message));
+      }
+    }
+  }
+
+  // Method to send messages through the port
+  send(message: HostMessage): void {
+    if (!this.port) {
+      throw new Error('No port set');
+    }
+    this.port.postMessage(message);
+  }
+}

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

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { HMType, UpdateValue } from '../../types';
+import { MessageEventManager } from '../MessageEventManager';
+
+describe('MessageEventManager', () => {
+  let messageEventManager: MessageEventManager;
+  let mockPort: MessagePort;
+
+  beforeEach(() => {
+    mockPort = {
+      onmessage: null,
+      postMessage: vi.fn(),
+      start: vi.fn(),
+    } as unknown as MessagePort;
+
+    messageEventManager = new MessageEventManager();
+  });
+
+  describe('setPort', () => {
+    beforeEach(() => {
+      messageEventManager.setPort(mockPort);
+    });
+
+    it('should start the port when initialized', () => {
+      expect(mockPort.start).toHaveBeenCalled();
+    });
+
+    it('should subscribe and receive messages of a specific type', () => {
+      const readyHandler = vi.fn();
+      messageEventManager.on('ready', readyHandler);
+
+      const readyMessage = { type: 'ready' };
+      mockPort.onmessage!({ data: readyMessage } as MessageEvent);
+
+      expect(readyHandler).toHaveBeenCalledWith(readyMessage);
+    });
+
+    it('should not call handlers for different message types', () => {
+      const updateHandler = vi.fn();
+      const errorHandler = vi.fn();
+      messageEventManager.on('update', updateHandler);
+      messageEventManager.on('error', errorHandler);
+
+      const errorMessage = { type: 'error', message: 'Something went wrong' };
+      mockPort.onmessage!({ data: errorMessage } as MessageEvent);
+
+      expect(updateHandler).not.toHaveBeenCalled();
+      expect(errorHandler).toHaveBeenCalledWith(errorMessage);
+    });
+
+    it('should unsubscribe handlers', () => {
+      const updateHandler = vi.fn();
+      messageEventManager.on('update', updateHandler);
+      messageEventManager.off('update', updateHandler);
+
+      const updateMessage = { type: 'update', data: { foo: 'bar' } };
+      mockPort.onmessage!({ data: updateMessage } as MessageEvent);
+
+      expect(updateHandler).not.toHaveBeenCalled();
+    });
+
+    it('should allow multiple subscribers for the same message type', () => {
+      const updateHandler1 = vi.fn();
+      const updateHandler2 = vi.fn();
+      messageEventManager.on('update', updateHandler1);
+      messageEventManager.on('update', updateHandler2);
+
+      const updateMessage = { type: 'update', data: { foo: 'bar' } };
+      mockPort.onmessage!({ data: updateMessage } as MessageEvent);
+
+      expect(updateHandler1).toHaveBeenCalledWith(updateMessage);
+      expect(updateHandler2).toHaveBeenCalledWith(updateMessage);
+    });
+
+    it('should send messages through the port', () => {
+      const message: UpdateValue = {
+        type: HMType.UPDATE,
+        value: { asset: 'USDC' },
+      };
+      messageEventManager.send(message);
+
+      expect(mockPort.postMessage).toHaveBeenCalledWith(message);
+    });
+
+    it('should ignore messages without a type', () => {
+      const handler = vi.fn();
+      messageEventManager.on('update', handler);
+
+      const invalidMessage = { data: 'no type field' };
+      mockPort.onmessage!({ data: invalidMessage } as MessageEvent);
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/utils/arbitraries.ts

@@ -0,0 +1,21 @@
+import fc from 'fast-check';
+import type { CAIP10, CAIP19, CAIP2, CAIP220 } from '../types';
+import {
+  CAIP10_MATCHER,
+  CAIP19_MATCHER,
+  CAIP220_MATCHER,
+  CAIP2_MATCHER,
+} from './caip';
+
+// Arbitraries
+export const arbitraryCAIP10 = (): fc.Arbitrary<CAIP10> =>
+  fc.stringMatching(CAIP10_MATCHER);
+
+export const arbitraryCAIP2 = (): fc.Arbitrary<CAIP2> =>
+  fc.stringMatching(CAIP2_MATCHER);
+
+export const arbitraryCAIP19 = (): fc.Arbitrary<CAIP19> =>
+  fc.stringMatching(CAIP19_MATCHER);
+
+export const arbitraryCAIP220 = (): fc.Arbitrary<CAIP220> =>
+  fc.stringMatching(CAIP220_MATCHER);

package/src/utils/caip.ts

@@ -0,0 +1,16 @@
+// Regexes
+export const ACCOUNT_ADDRESS_REGEX = '[-.%a-zA-Z0-9]{1,128}';
+export const CAIP2_REGEX = '[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}';
+export const CAIP10_REGEX = `^${CAIP2_REGEX}:${ACCOUNT_ADDRESS_REGEX}$`;
+export const CAIP19_REGEX = `^${CAIP2_REGEX}/[-a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}(/[-.%a-zA-Z0-9]{1,78})?$`;
+export const CAIP220_REGEX = `^${CAIP2_REGEX}:[block:]?tx/[-.%a-zA-Z0-9]{1,128}$`;
+export const CRYPTO_SYMBOL_REGEX = '^[A-Z0-9]{2,10}$';
+export const DTI_REGEX = '^[A-Za-z0-9]{10}$';
+export const COMBINED_ASSET_REGEX = `(${CRYPTO_SYMBOL_REGEX})|(${CAIP19_REGEX})|(${DTI_REGEX})`;
+
+// Matchers
+export const CAIP2_MATCHER = new RegExp(CAIP2_REGEX);
+export const CAIP10_MATCHER = new RegExp(CAIP10_REGEX);
+export const CAIP19_MATCHER = new RegExp(CAIP19_REGEX);
+export const CAIP220_MATCHER = new RegExp(CAIP220_REGEX);
+export const COMBINED_ASSET_MATCHER = new RegExp(COMBINED_ASSET_REGEX);

package/src/utils/urls.ts

@@ -0,0 +1,15 @@
+export function encodeObjectToFragment(obj: any) {
+  return Object.entries(obj)
+    .map(([key, value]) => {
+      if (!(key && value)) return undefined;
+      const encodedKey = encodeURIComponent(key);
+      const encodedValue = encodeURIComponent(
+        typeof value === 'object'
+          ? JSON.stringify(value)
+          : (value as string | number | boolean),
+      );
+      return `${encodedKey}=${encodedValue}`;
+    })
+    .filter((entry) => !!entry)
+    .join('&');
+}