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

package/src/types.ts

@@ -1,5 +1,50 @@
-import { DateAndPlaceOfBirth, NationalIdentification } from 'ivms/types';
+import {
+  Beneficiary,
+  DateAndPlaceOfBirth,
+  IVMS101,
+  NationalIdentification,
+  Originator,
+} from './ivms/types';
 
+export type { IVMS101 };
+
+export type CAIP2 = `${string}:${string}`;
+export type CAIP10 = `${CAIP2}:${string}`;
+export type CAIP19 = `${CAIP2}/${string}:${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 = `ta${string}`;
+export type CryptoCredential = `${string}.${string}.mastercard`;
+
+/**
+ * The destination of a transaction either a blockchain address, a CAIP-19 address, or a travel address.
+ * @public
+ */
+export type Destination =
+  | BlockchainAddress
+  | CAIP10
+  | CryptoCredential
+  | TravelAddress;
+export type Source = BlockchainAddress | CAIP10;
+export type URI = string;
+export type DID = `did:${string}:${string}`;
+
+/**
+ * The theme of the Notabene SDK
+ * @public
+ */
 export type Theme = {
   primaryColor: string;
   secondaryColor: string;
@@ -7,21 +52,40 @@ export type Theme = {
   logo: string;
 };
 
-export enum WidgetType {
-  WITHDRAWAL = 'WITHDRAWAL',
-  POST_DEPOSIT = 'POST_DEPOSIT',
-}
+// export type TransactionType = 'VASP_2_VASP' | 'SELF_HOSTED';
+
+// export type TransactionTypeAllowed =
+//   | 'ALL'
+//   | 'VASP_2_VASP_ONLY'
+//   | 'FIRST_PARTY_ONLY';
 
-export type TransactionTypeAllowed =
-  | 'ALL'
-  | 'VASP_2_VASP_ONLY'
-  | 'SELF_TRANSACTION_ONLY';
+// export type NonCustodialDeclarationType =
+//   | 'SIGNATURE'
+//   | 'DECLARATION'
+//   | 'SIGNATURE_AND_DECLARATION';
 
-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 +101,177 @@ export type CountryType = {
   name: string;
 };
 
-export type PersonType = 'natural' | 'legal';
-
-export type OriginatorFields = {
-  originatorAccountNumber?: string;
-  originatorDid?: string;
-  originatorVASPname?: string;
-  originatorVASPdid?: string;
-  originatorName?: string;
-  originatorGeographicAddress?: string;
-  originatorNationalIdentification?: NationalIdentification;
-  originatorDateAndPlaceOfBirth?: DateAndPlaceOfBirth;
-  originatorPersonType?: PersonType;
-};
-
-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[];
+/**
+ * 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;
+}
+
+type OriginatorFields = {
+  source?: Source;
+};
+
+type BeneficiaryFields = {
+  destination?: Destination;
+};
+
+type DepositRequestFields = {
+  destinations: 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 {}
+
+/**
+ * An object representing a request for a deposit
+ * @public
+ */
+export interface DepositRequest extends DepositRequestFields, Transaction {}
+
+/**
+ * Configuration options for Transaction components
+ * @public
+ */
+
+export interface TransactionOptions {
+  microTransactionAddress?: BlockchainAddress;
+  proofFallbacks?: ProofTypes[];
+}
+
+/**
+ * The verification status of a transaction
+ * @public
+ */
+export enum Status {
+  EMPTY = 'empty',
+  VERIFY = 'verify',
+  PENDING = 'pending',
+  VERIFIED = 'verified',
+  BANNED = 'banned',
+}
+
+type V1Asset =
+  | {
+      caip19: CAIP19;
+    }
+  | string;
+
+/**
+ * Transaction payload suitable for calling Notabene v1 tx/create
+ * @public
+ */
+
+export type V1Transaction = {
+  transactionAsset: V1Asset;
+  transactionAmount: string;
+  originatorEqualsBeneficiary?: boolean;
+  originatorVASPdid: DID;
+  beneficiaryVASPdid: DID;
+  beneficiaryProof: OwnershipProof;
+  originator: Originator;
+  beneficiary: Beneficiary;
+};
+/**
+ * The response of a transaction
+ * @public
+ */
+
+export type TransactionResponse = {
+  value: Transaction;
+  ivms: IVMS101;
+  proof?: OwnershipProof;
+  valid: boolean;
+  status: Status;
+  errors: ValidationError[];
+  txCreate?: V1Transaction;
+};
+
+export type ValidationError = {
+  attribute: string;
+  message: string;
+};
 
 export type FieldProps = {
   forceDisplay?: boolean; // instead of beneficiaryDetails - defaults to false
@@ -95,6 +281,7 @@ export type FieldProps = {
 export type FieldName =
   | 'counterparty'
   | 'geographicAddress'
+  | 'firstName'
   | 'name'
   | 'nationalIdentification'
   | 'dateAndPlaceOfBirth';
@@ -103,12 +290,193 @@ export type FieldsProps = {
   [name in FieldName]?: FieldProps;
 };
 
-type WalletNotSupportedFlow = {
-  flow: 'WALLET_NOT_SUPPORTED';
-  action: 'DECLARATION' | 'REJECT';
+/**
+ * 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>;
 };
 
-// This is going to be union type
-export type Fallback = WalletNotSupportedFlow;
+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;
+}
 
-export type OptInFeature = 'REUSE_ADDRESS_OWNERSHIP_PROOF';
+/**
+ * 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,54 @@
+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) {
+      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,26 @@
+import fc from 'fast-check';
+import type { CAIP10, CAIP19, CAIP2, CAIP220 } from '../types';
+import {
+  CAIP10_MATCHER,
+  CAIP19_MATCHER,
+  CAIP220_MATCHER,
+  CAIP2_MATCHER,
+} from './caip';
+
+const LOCALE = new RegExp(/^[a-z]{2}(-[A-Z]{2})?$/);
+
+// Arbitraries
+export const arbitraryCAIP10 = (): fc.Arbitrary<CAIP10> =>
+  fc.stringMatching(CAIP10_MATCHER) as fc.Arbitrary<CAIP10>;
+
+export const arbitraryCAIP2 = (): fc.Arbitrary<CAIP2> =>
+  fc.stringMatching(CAIP2_MATCHER) as fc.Arbitrary<CAIP2>;
+
+export const arbitraryCAIP19 = (): fc.Arbitrary<CAIP19> =>
+  fc.stringMatching(CAIP19_MATCHER) as fc.Arbitrary<CAIP19>;
+
+export const arbitraryCAIP220 = (): fc.Arbitrary<CAIP220> =>
+  fc.stringMatching(CAIP220_MATCHER) as fc.Arbitrary<CAIP220>;
+
+export const arbitraryLocale = (): fc.Arbitrary<string> =>
+  fc.stringMatching(LOCALE) as fc.Arbitrary<string>;