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

package/src/types.ts

@@ -1,31 +1,92 @@
 import {
+  Address,
   Beneficiary,
-  DateAndPlaceOfBirth,
+  ISOCountryCode,
+  ISODate,
   IVMS101,
   NationalIdentification,
   Originator,
 } from './ivms/types';
 
+/**
+ * Interoperable Virtual Asset Service Provider (VASP) Messaging Standard
+ * @public
+ */
 export type { IVMS101 };
 
+/**
+ * UUID v4
+ * @public
+ */
+export type UUID = string;
+
+/**
+ * Chain Agnostic Blockchain Identifier
+ * Represents a blockchain in a chain-agnostic way
+ * Format: `namespace:reference`
+ * @example "eip155:1" for Ethereum Mainnet
+ * @public
+ */
 export type CAIP2 = `${string}:${string}`;
+
+/**
+ * Chain Agnostic Account Identifier
+ * Represents an account on a specific blockchain
+ * Format: `{caip2}:{address}`
+ * @example "eip155:1:0x742d35Cc6634C0532925a3b844Bc454e4438f44e" for an Ethereum account
+ * @public
+ */
 export type CAIP10 = `${CAIP2}:${string}`;
+
+/**
+ * Chain Agnostic Asset Identifier
+ * Represents an asset on a specific blockchain
+ * Format: `{caip2}/{asset_namespace}:{asset_reference}`
+ * @example "eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f" for DAI on Ethereum
+ * @public
+ */
 export type CAIP19 = `${CAIP2}/${string}:${string}`;
+
+/**
+ * Chain Agnostic Payload Identifier
+ * @public
+ */
 export type CAIP220 = string;
 
+/**
+ * Digital Token Identifier
+ * @public
+ */
 export type DTI = string;
+
+/**
+ * Notabene Asset Identifier
+ * @public
+ */
 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;
 
+/**
+ * A blockchain address
+ * @public
+ */
 export type BlockchainAddress = string;
+
+/**
+ * A travel address
+ * @public
+ */
 export type TravelAddress = `ta${string}`;
+
+/**
+ * A crypto credential
+ * @public
+ */
 export type CryptoCredential = `${string}.${string}.mastercard`;
 
 /**
@@ -37,10 +98,37 @@ export type Destination =
   | CAIP10
   | CryptoCredential
   | TravelAddress;
+
+/**
+ * The source of a transaction
+ * @public
+ */
 export type Source = BlockchainAddress | CAIP10;
+
+/**
+ * A Uniform Resource Identifier
+ * @public
+ */
 export type URI = string;
+
+/**
+ * A Decentralized Identifier
+ * @public
+ */
 export type DID = `did:${string}:${string}`;
 
+/**
+ * A LEI Legal Entity Identifier
+ * @public
+ */
+export type LEI = string;
+
+/**
+ * 3 letter ISO currency code
+ * @public
+ */
+export type ISOCurrency = string;
+
 /**
  * The theme of the Notabene SDK
  * @public
@@ -52,23 +140,10 @@ export type Theme = {
   logo: string;
 };
 
-// export type TransactionType = 'VASP_2_VASP' | 'SELF_HOSTED';
-
-// export type TransactionTypeAllowed =
-//   | 'ALL'
-//   | 'VASP_2_VASP_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',
@@ -78,28 +153,14 @@ export enum AgentType {
  * Who is the agent acting on behalf of the counterparty
  * @public
  */
-export declare interface Agent {
+export interface Agent {
   did: DID;
   type: AgentType;
-  logo?: string;
-  url?: string;
+  logo?: URI;
+  url?: URI;
   name?: string;
   verified?: boolean;
 }
-export type OwnershipProofInput = {
-  type?: string | null;
-  proof?: string | null;
-};
-
-export type TransactionBlockchainInfo = {
-  destination?: string | null;
-  origin?: string | null;
-};
-
-export type CountryType = {
-  id: string;
-  name: 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.
@@ -116,9 +177,12 @@ export enum PersonType {
  * @public
  */
 export interface VASP extends Agent {
-  url?: string;
-  name?: string;
+  lei?: LEI;
+  logo?: URI;
+  website?: URI;
+  countryOfRegistration?: ISOCountryCode;
 }
+
 /**
  * A wallet agent acting on behalf of the counterparty
  * @public
@@ -135,21 +199,47 @@ export interface Wallet extends Agent {
 export interface Counterparty {
   name?: string;
   accountNumber?: string;
-  did?: string;
-  geographicAddress?: string;
+  did?: DID;
   type?: PersonType;
   verified?: boolean;
+  geographicAddress?: Address;
+  nationalIdentification?: NationalIdentification;
+  website?: URI;
+  phone?: string;
 }
+
 /**
  * A counterparty object representing a natural person
  * @public
  */
 export interface NaturalPerson extends Counterparty {
   type: PersonType.NATURAL;
-  nationalIdentification?: NationalIdentification;
-  dateAndPlaceOfBirth?: DateAndPlaceOfBirth;
+  dateOfBirth?: ISODate;
+  placeOfBirth?: string;
+  countryOfResidence?: ISOCountryCode;
   name: string;
 }
+/**
+ * Field names for NaturalPerson
+ * @public
+ */
+export type NaturalPersonFieldName =
+  | 'name' // Full legal name
+  | 'website' // Primary website of entity
+  | 'email' // Contact email
+  | 'phone' // Contact mobile phone
+  | 'geographicAddress' // Address string
+  | 'nationalIdentification' // National Identification number
+  | 'dateOfBirth' // Date of Birty YYYY-MM-DD
+  | 'placeOfBirth' // Place of Birth
+  | 'countryOfResidence'; // ISO Country code of residence of Natural Person
+/**
+ * Field properties by field name
+ * @public
+ */
+export type NaturalPersonFields = {
+  [name in NaturalPersonFieldName]?: FieldOptions;
+};
 
 /**
  * A counterparty object representing a legal person
@@ -158,37 +248,81 @@ export interface NaturalPerson extends Counterparty {
 export interface LegalPerson extends Counterparty {
   type: PersonType.LEGAL;
   name: string;
-  lei?: string;
-  url?: string;
-  logo?: string;
+  lei?: LEI;
+  logo?: URI;
+  countryOfRegistration?: ISOCountryCode;
 }
+/**
+ * Field names for LegalPerson
+ * @public
+ */
+
+export type LegalPersonFieldName =
+  | 'name' // Full legal name
+  | 'lei' // Legal Entity Identifier
+  | 'website' // Primary website of entity
+  | 'email' // Contact email
+  | 'phone' // Contact mobile phone
+  | 'geographicAddress' // Address string
+  | 'nationalIdentification' // National Identification number
+  | 'countryOfRegistration'; // ISO Country code of registration of Legal Person
+
+/**
+ * Field properties by field name
+ * @public
+ */
+export type LegalPersonFields = {
+  [name in LegalPersonFieldName]?: FieldOptions;
+};
 
+/**
+ * Fields specific to the originator of a transaction
+ * @public
+ */
 type OriginatorFields = {
   source?: Source;
 };
 
+/**
+ * Fields specific to the beneficiary of a transaction
+ * @public
+ */
 type BeneficiaryFields = {
   destination?: Destination;
 };
 
+/**
+ * Fields specific to a deposit request
+ * @public
+ */
 type DepositRequestFields = {
   destinations: Destination[];
 };
 
+type RequestID = UUID;
+
+/**
+ * An abstract request for communicating with a component
+ * @public
+ */
+export interface ComponentRequest {
+  requestId?: RequestID;
+  customer?: Counterparty;
+}
+
 /**
  * An abstract transaction object
  * @public
  */
-export interface Transaction {
+export interface Transaction extends ComponentRequest {
   agent: Agent;
-  customer?: Counterparty;
   counterparty: Counterparty;
   asset: TransactionAsset;
   amountDecimal: number;
-  // transactionBlockchainInfo?: TransactionBlockchainInfo;
-  customAssetPrice?: {
+  proof?: OwnershipProof;
+  assetPrice?: {
     price: number;
-    currency: string;
+    currency: ISOCurrency;
   };
 }
 
@@ -211,13 +345,22 @@ export interface Deposit extends OriginatorFields, Transaction {}
 export interface DepositRequest extends DepositRequestFields, Transaction {}
 
 /**
- * Configuration options for Transaction components
+ * An object representing a connection request
  * @public
  */
+export interface ConnectionRequest extends ComponentRequest {
+  asset: TransactionAsset;
+}
 
-export interface TransactionOptions {
-  microTransactionAddress?: BlockchainAddress;
-  proofFallbacks?: ProofTypes[];
+/**
+ * An object representing a connection response
+ * @public
+ */
+export interface ConnectionResponse extends ComponentResponse {
+  value: ConnectionRequest;
+  ivms: IVMS101;
+  proof?: OwnershipProof;
+  txCreate?: V1Transaction;
 }
 
 /**
@@ -232,17 +375,11 @@ export enum Status {
   BANNED = 'banned',
 }
 
-type V1Asset =
-  | {
-      caip19: CAIP19;
-    }
-  | string;
-
+type V1Asset = NotabeneAsset | { caip19: CAIP19 };
 /**
  * Transaction payload suitable for calling Notabene v1 tx/create
  * @public
  */
-
 export type V1Transaction = {
   transactionAsset: V1Asset;
   transactionAmount: string;
@@ -253,46 +390,68 @@ export type V1Transaction = {
   originator: Originator;
   beneficiary: Beneficiary;
 };
+
+export interface ComponentResponse {
+  requestID: RequestID;
+  valid: boolean;
+  status: Status;
+  errors: ValidationError[];
+}
 /**
  * The response of a transaction
  * @public
  */
-
-export type TransactionResponse = {
-  value: Transaction;
+export interface TransactionResponse<V> extends ComponentResponse {
+  value: V;
   ivms: IVMS101;
   proof?: OwnershipProof;
-  valid: boolean;
-  status: Status;
-  errors: ValidationError[];
   txCreate?: V1Transaction;
-};
+}
 
+/**
+ * Validation error
+ * @public
+ */
 export type ValidationError = {
   attribute: string;
   message: string;
 };
 
-export type FieldProps = {
-  forceDisplay?: boolean; // instead of beneficiaryDetails - defaults to false
-  optional?: boolean; // bypass the jurisdiction rules validation - defaults to false
-};
-
-export type FieldName =
-  | 'counterparty'
-  | 'geographicAddress'
-  | 'firstName'
-  | 'name'
-  | 'nationalIdentification'
-  | 'dateAndPlaceOfBirth';
+/**
+ * Field properties
+ * @public
+ */
+export type FieldOptions =
+  | boolean
+  | {
+      optional: boolean; // Shown but optional
+      transmit: boolean; // Transmit as part of IVMS 101 to counterparty
+    };
 
-export type FieldsProps = {
-  [name in FieldName]?: FieldProps;
+export type FieldTypes = {
+  naturalPerson?: NaturalPersonFields;
+  legalPerson?: LegalPersonFields;
 };
+/**
+ * Configuration options for Transaction components
+ * @public
+ */
+export interface TransactionOptions {
+  proofs?: {
+    microTransfer?: {
+      destination: BlockchainAddress;
+      timeout?: number; // Time to verify in seconds
+    };
+    fallbacks?: ProofTypes[];
+  };
+  allowedAgentTypes?: AgentType[]; // Defaults to All
+  allowedCounterpartyTypes?: PersonType[]; // Defaults to All
+  fields?: FieldTypes;
+}
 
 /**
  * Component Message Types
- * @internal
+ * @public
  */
 export const enum CMType {
   COMPLETE = 'complete',
@@ -306,46 +465,53 @@ export const enum CMType {
   CANCEL = 'cancel',
 }
 
+/**
+ * Represents a completed component message
+ * @public
+ */
 export type Completed = {
   type: CMType.COMPLETE;
-  response: TransactionResponse;
-};
-
-export type Result = {
-  type: CMType.RESULT;
-  reqid: RequestID;
-  response: TransactionResponse;
+  response: ComponentResponse;
 };
 
+/**
+ * Represents a ready component message
+ * @public
+ */
 export type Ready = {
   type: CMType.READY;
 };
 
+/**
+ * Represents a resize request component message
+ * @public
+ */
 export type ResizeRequest = {
   type: CMType.RESIZE;
   height: number;
 };
 
+/**
+ * Represents an error component message
+ * @public
+ */
 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;
-};
-
+/**
+ * Represents a cancel component message
+ * @public
+ */
 export type Cancel = {
   type: CMType.CANCEL;
 };
 
+/**
+ * Represents an invalid value component message
+ * @public
+ */
 export type InvalidValue = {
   type: CMType.INVALID;
   value: any;
@@ -354,24 +520,19 @@ export type InvalidValue = {
 
 /**
  * Component Message
- * @internal
+ * @public
  */
 export type ComponentMessage =
   | Completed
   | Cancel
   | Error
-  | Result
   | Ready
   | ResizeRequest
-  | ModalRequest
-  | InvalidValue
-  | CloseModal;
-
-export type RequestID = string;
+  | InvalidValue;
 
 /**
  * Host Message Types
- * @internal
+ * @public
  */
 
 export const enum HMType {
@@ -379,23 +540,25 @@ export const enum HMType {
   REQUEST_RESPONSE = 'requestResponse',
 }
 
+/**
+ * Represents an update value host message
+ * @public
+ */
 export type UpdateValue = {
   type: HMType.UPDATE;
-  value: Partial<Transaction>;
-};
-
-export type RequestResponse = {
-  type: HMType.REQUEST_RESPONSE;
-  reqid: RequestID;
+  value: ComponentRequest;
 };
 
 /**
  * Host Messages
- * @internal
+ * @public
  */
+export type HostMessage = UpdateValue;
 
-export type HostMessage = UpdateValue | RequestResponse;
-
+/**
+ * Options for callback and redirect URIs
+ * @public
+ */
 export interface CallbackOptions {
   callback?: URI;
   redirectUri?: URI;
@@ -415,7 +578,7 @@ export enum ProofStatus {
 /**
  * The type of Proofs supported
  * @public
- **/
+ */
 export enum ProofTypes {
   SelfDeclaration = 'self-declaration',
   PersonalSignEIP191 = 'eip-191',
@@ -425,6 +588,7 @@ export enum ProofTypes {
   MicroTransfer = 'microtransfer',
   Screenshot = 'screenshot',
 }
+
 /**
  * Ownership Proof
  * @public
@@ -469,7 +633,7 @@ export interface MicroTransferProof extends OwnershipProof {
   type: ProofTypes.MicroTransfer;
   txhash: string;
   chain: CAIP2;
-  amount: number;
+  amountSubunits: string;
 }
 
 /**

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

@@ -75,7 +75,7 @@ describe('MessageEventManager', () => {
     it('should send messages through the port', () => {
       const message: UpdateValue = {
         type: HMType.UPDATE,
-        value: { asset: 'USDC' },
+        value: { requestId: 'id' },
       };
       messageEventManager.send(message);