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

package/src/types.ts

@@ -1,5 +1,138 @@
-import { DateAndPlaceOfBirth, NationalIdentification } from 'ivms/types';
+import {
+  Address,
+  Beneficiary,
+  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`;
+
+/**
+ * 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;
+
+/**
+ * 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
+ */
 export type Theme = {
   primaryColor: string;
   secondaryColor: string;
@@ -7,109 +140,507 @@ export type Theme = {
   logo: string;
 };
 
-export enum WidgetType {
-  WITHDRAWAL = 'WITHDRAWAL',
-  POST_DEPOSIT = 'POST_DEPOSIT',
+/**
+ * The type of Agent. Either a wallet or a VASP
+ * @public
+ */
+export enum AgentType {
+  PRIVATE = 'WALLET',
+  VASP = 'VASP',
 }
 
-export type TransactionTypeAllowed =
-  | 'ALL'
-  | 'VASP_2_VASP_ONLY'
-  | 'SELF_TRANSACTION_ONLY';
+/**
+ * Who is the agent acting on behalf of the counterparty
+ * @public
+ */
+export interface Agent {
+  did: DID;
+  type: AgentType;
+  logo?: URI;
+  url?: URI;
+  name?: string;
+  verified?: boolean;
+}
 
-export type NonCustodialDeclarationType =
-  | 'SIGNATURE'
-  | 'DECLARATION'
-  | 'SIGNATURE_AND_DECLARATION';
+/**
+ * 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
+}
 
-export type OwnershipProofInput = {
-  type?: string | null;
-  proof?: string | null;
-};
+/**
+ * A VASP agent acting on behalf of the counterparty
+ * @public
+ */
+export interface VASP extends Agent {
+  lei?: LEI;
+  logo?: URI;
+  website?: URI;
+  countryOfRegistration?: ISOCountryCode;
+}
+
+/**
+ * A wallet agent acting on behalf of the counterparty
+ * @public
+ */
+export interface Wallet extends Agent {
+  proof: OwnershipProof;
+  wallet_connect_id?: string;
+}
 
-export type TransactionBlockchainInfo = {
-  destination?: string | null;
-  origin?: string | null;
+/**
+ * The counterparty of a transaction.
+ * @public
+ */
+export interface Counterparty {
+  name?: string;
+  accountNumber?: 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;
+  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;
 };
 
-export type CountryType = {
-  id: string;
+/**
+ * A counterparty object representing a legal person
+ * @public
+ */
+export interface LegalPerson extends Counterparty {
+  type: PersonType.LEGAL;
   name: 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;
 };
 
-export type PersonType = 'natural' | 'legal';
+/**
+ * Fields specific to the originator of a transaction
+ * @public
+ */
+type OriginatorFields = {
+  source?: Source;
+};
 
-export type OriginatorFields = {
-  originatorAccountNumber?: string;
-  originatorDid?: string;
-  originatorVASPname?: string;
-  originatorVASPdid?: string;
-  originatorName?: string;
-  originatorGeographicAddress?: string;
-  originatorNationalIdentification?: NationalIdentification;
-  originatorDateAndPlaceOfBirth?: DateAndPlaceOfBirth;
-  originatorPersonType?: PersonType;
+/**
+ * Fields specific to the beneficiary of a transaction
+ * @public
+ */
+type BeneficiaryFields = {
+  destination?: Destination;
 };
 
-export type BeneficiaryFields = {
-  beneficiaryAccountNumber?: string;
-  beneficiaryDid?: string;
-  beneficiaryVASPname?: string;
-  beneficiaryVASPdid?: string;
-  beneficiaryName?: string;
-  beneficiaryGeographicAddress?: string;
-  beneficiaryNationalIdentification?: NationalIdentification;
-  beneficiaryDateAndPlaceOfBirth?: DateAndPlaceOfBirth;
-  beneficiaryPersonType?: PersonType;
+/**
+ * Fields specific to a deposit request
+ * @public
+ */
+type DepositRequestFields = {
+  destinations: Destination[];
 };
 
-export type CAIP19 = {
-  caip19: string;
+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 extends ComponentRequest {
+  agent: Agent;
+  counterparty: Counterparty;
+  asset: TransactionAsset;
+  amountDecimal: number;
+  proof?: OwnershipProof;
+  assetPrice?: {
+    price: number;
+    currency: ISOCurrency;
+  };
+}
+
+/**
+ * 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 {}
+
+/**
+ * An object representing a connection request
+ * @public
+ */
+export interface ConnectionRequest extends ComponentRequest {
+  asset: TransactionAsset;
+}
+
+/**
+ * An object representing a connection response
+ * @public
+ */
+export interface ConnectionResponse extends ComponentResponse {
+  value: ConnectionRequest;
+  ivms: IVMS101;
+  proof?: OwnershipProof;
+  txCreate?: V1Transaction;
+}
+
+/**
+ * The verification status of a transaction
+ * @public
+ */
+export enum Status {
+  EMPTY = 'empty',
+  VERIFY = 'verify',
+  PENDING = 'pending',
+  VERIFIED = 'verified',
+  BANNED = 'banned',
+}
+
+type V1Asset = NotabeneAsset | { caip19: CAIP19 };
+/**
+ * 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;
 };
 
-export type CoingeckoIdAndNetwork = { coingeckoId: string; network: string };
+export interface ComponentResponse {
+  requestID: RequestID;
+  valid: boolean;
+  status: Status;
+  errors: ValidationError[];
+}
+/**
+ * The response of a transaction
+ * @public
+ */
+export interface TransactionResponse<V> extends ComponentResponse {
+  value: V;
+  ivms: IVMS101;
+  proof?: OwnershipProof;
+  txCreate?: V1Transaction;
+}
+
+/**
+ * Validation error
+ * @public
+ */
+export type ValidationError = {
+  attribute: string;
+  message: string;
+};
 
-export type TransactionAsset = string | CAIP19 | CoingeckoIdAndNetwork;
-export type Transaction = OriginatorFields &
-  BeneficiaryFields & {
-    transactionAsset: TransactionAsset;
-    transactionAmount: string;
-    transactionBlockchainInfo?: TransactionBlockchainInfo;
-    customAssetPrice?: {
-      priceUSD: number;
-      decimals: number;
+/**
+ * Field properties
+ * @public
+ */
+export type FieldOptions =
+  | boolean
+  | {
+      optional: boolean; // Shown but optional
+      transmit: boolean; // Transmit as part of IVMS 101 to counterparty
     };
-    isNonCustodial?: boolean;
-    originatorEqualsBeneficiary?: boolean;
-    beneficiaryProof?: OwnershipProofInput;
-    originatorProof?: OwnershipProofInput;
-    isValid?: boolean;
-    errors?: string[];
+
+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
+ * @public
+ */
+export const enum CMType {
+  COMPLETE = 'complete',
+  RESIZE = 'resize',
+  RESULT = 'result',
+  READY = 'ready',
+  INVALID = 'invalid',
+  MODAL = 'openModal',
+  ERROR = 'error',
+  CLOSE = 'closeModal',
+  CANCEL = 'cancel',
+}
+
+/**
+ * Represents a completed component message
+ * @public
+ */
+export type Completed = {
+  type: CMType.COMPLETE;
+  response: ComponentResponse;
+};
 
-export type FieldProps = {
-  forceDisplay?: boolean; // instead of beneficiaryDetails - defaults to false
-  optional?: boolean; // bypass the jurisdiction rules validation - defaults to false
+/**
+ * Represents a ready component message
+ * @public
+ */
+export type Ready = {
+  type: CMType.READY;
 };
 
-export type FieldName =
-  | 'counterparty'
-  | 'geographicAddress'
-  | 'firstName'
-  | 'name'
-  | 'nationalIdentification'
-  | 'dateAndPlaceOfBirth';
+/**
+ * Represents a resize request component message
+ * @public
+ */
+export type ResizeRequest = {
+  type: CMType.RESIZE;
+  height: number;
+};
 
-export type FieldsProps = {
-  [name in FieldName]?: FieldProps;
+/**
+ * Represents an error component message
+ * @public
+ */
+export type Error = {
+  type: CMType.ERROR;
+  message: string;
 };
 
-type WalletNotSupportedFlow = {
-  flow: 'WALLET_NOT_SUPPORTED';
-  action: 'DECLARATION' | 'REJECT';
+/**
+ * Represents a cancel component message
+ * @public
+ */
+export type Cancel = {
+  type: CMType.CANCEL;
 };
 
-// This is going to be union type
-export type Fallback = WalletNotSupportedFlow;
+/**
+ * Represents an invalid value component message
+ * @public
+ */
+export type InvalidValue = {
+  type: CMType.INVALID;
+  value: any;
+  errors: ValidationError[];
+};
+
+/**
+ * Component Message
+ * @public
+ */
+export type ComponentMessage =
+  | Completed
+  | Cancel
+  | Error
+  | Ready
+  | ResizeRequest
+  | InvalidValue;
+
+/**
+ * Host Message Types
+ * @public
+ */
 
-export type OptInFeature = 'REUSE_ADDRESS_OWNERSHIP_PROOF';
+export const enum HMType {
+  UPDATE = 'update',
+  REQUEST_RESPONSE = 'requestResponse',
+}
+
+/**
+ * Represents an update value host message
+ * @public
+ */
+export type UpdateValue = {
+  type: HMType.UPDATE;
+  value: ComponentRequest;
+};
+
+/**
+ * Host Messages
+ * @public
+ */
+export type HostMessage = UpdateValue;
+
+/**
+ * Options for callback and redirect URIs
+ * @public
+ */
+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;
+  amountSubunits: string;
+}
+
+/**
+ * Ownership Proof using Screenshot
+ * @public
+ */
+export interface ScreenshotProof extends OwnershipProof {
+  type: ProofTypes.Screenshot;
+  url: string;
+}