Merge pull request #9 from elven-js/refactor-login-callbacks

rename and add callbacks

CHANGELOG.md

@@ -1,3 +1,10 @@
+### [0.16.0](https://github.com/elven-js/elven.js/releases/tag/v0.16.0) (2024-01-28)
+- rename and add more login callbacks (breaking)
+- rename some of the transaction and message signing callbacks (breaking)
+- add callbacks for logout
+- add callbacks for `queryContract`
+- check [docs](https://www.elvenjs.com/docs/sdk-reference.html#initialization) and [example demo](/example/index.html) for more information
+
 ### [0.15.0](https://github.com/elven-js/elven.js/releases/tag/v0.15.0) (2024-01-13)
 - add webview provider (based on sdk-dapp), required for xPortal Hub integration (experimental, need more tests and rewrites, it will probably land in a separate package in the following updates)
 - update dependencies

build/types/elven.d.ts

@@ -13,5 +13,7 @@ export { BytesType, BytesValue, } from '@multiversx/sdk-core/out/smartcontracts/
 export { U16Type, U16Value, U32Type, U32Value, U64Type, U64Value, U8Type, U8Value, BigUIntType, BigUIntValue, } from '@multiversx/sdk-core/out/smartcontracts/typesystem/numerical';
 export { BooleanType, BooleanValue, } from '@multiversx/sdk-core/out/smartcontracts/typesystem/boolean';
 export { AddressType, AddressValue, } from '@multiversx/sdk-core/out/smartcontracts/typesystem/address';
+export { QueryArguments } from '@multiversx/sdk-core/out/smartcontracts/interface';
+export { ContractQueryResponse } from '@multiversx/sdk-network-providers/out/contractQueryResponse';
 export { ElvenJS } from './main';
-export { LoginMethodsEnum } from './types';
+export * from './types';

build/types/initialize-events-store.d.ts

@@ -0,0 +1,2 @@
+import { InitOptions } from './types';
+export declare const initializeEventsStore: (initOptions: InitOptions) => void;

build/types/network-provider.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-import BigNumber from 'bignumber.js';
 import { Address } from '@multiversx/sdk-core/out/address';
 import { TransactionStatus } from '@multiversx/sdk-network-providers/out/transactionStatus';
 import { TransactionReceipt } from '@multiversx/sdk-network-providers/out/transactionReceipt';
@@ -18,7 +17,7 @@ export type NetworkProviderOptions = Pick<InitOptions, 'apiUrl' | 'chainType' |
 export interface AccountOnNetwork {
     address: IAddress;
     nonce: number;
-    balance: BigNumber;
+    balance: bigint;
     code: string;
     userName: string;
 }

build/types/types.d.ts

@@ -3,24 +3,56 @@ import { Transaction } from '@multiversx/sdk-core/out/transaction';
 import { WalletConnectV2Provider } from '@multiversx/sdk-wallet-connect-provider/out/walletConnectV2Provider';
 import { WalletProvider } from '@multiversx/sdk-web-wallet-provider/out/walletProvider';
 import { WebviewProvider } from './webview-provider/webview-provider';
+import { QueryArguments } from '@multiversx/sdk-core/out/smartcontracts';
+import { ContractQueryResponse } from '@multiversx/sdk-network-providers/out/contractQueryResponse';
 export interface InitOptions {
     apiUrl?: string;
     chainType?: string;
     apiTimeout?: number;
     walletConnectV2ProjectId?: string;
     walletConnectV2RelayAddresses?: string[];
-    onLoginPending?: () => void;
-    onLoggedIn?: () => void;
-    onLogout?: () => void;
+    onLoginStart?: () => void;
+    onLoginEnd?: () => void;
+    onLoginSuccess?: () => void;
+    onLoginFailure?: (error: string) => void;
+    onLogoutStart?: () => void;
+    onLogoutEnd?: () => void;
+    onLogoutSuccess?: () => void;
+    onLogoutFailure?: (error: string) => void;
     onQrPending?: () => void;
     onQrLoaded?: () => void;
-    onTxStarted?: (transaction: Transaction) => void;
+    onTxStart?: (transaction: Transaction) => void;
     onTxSent?: (transaction: Transaction) => void;
     onTxFinalized?: (transaction: Transaction) => void;
-    onTxError?: (transaction: Transaction, error: string) => void;
-    onSignMsgStarted?: (message: string) => void;
+    onTxFailure?: (transaction: Transaction, error: string) => void;
+    onSignMsgStart?: (message: string) => void;
     onSignMsgFinalized?: (messageSignature: string) => void;
-    onSignMsgError?: (message: string, error: string) => void;
+    onSignMsgFailure?: (message: string, error: string) => void;
+    onQueryStart?: (queryArgs: QueryArguments) => void;
+    onQueryFinalized?: (queryResponse: ContractQueryResponse) => void;
+    onQueryFailure?: (queryArgs: QueryArguments, error: string) => void;
+}
+export declare enum EventStoreEvents {
+    onLoginStart = "onLoginStart",
+    onLoginEnd = "onLoginEnd",
+    onLoginSuccess = "onLoginSuccess",
+    onLoginFailure = "onLoginFailure",
+    onLogoutStart = "onLogoutStart",
+    onLogoutEnd = "onLogoutEnd",
+    onLogoutSuccess = "onLogoutSuccess",
+    onLogoutFailure = "onLogoutFailure",
+    onQrPending = "onQrPending",
+    onQrLoaded = "onQrLoaded",
+    onTxStart = "onTxStart",
+    onTxSent = "onTxSent",
+    onTxFinalized = "onTxFinalized",
+    onTxFailure = "onTxFailure",
+    onSignMsgStart = "onSignMsgStart",
+    onSignMsgFinalized = "onSignMsgFinalized",
+    onSignMsgFailure = "onSignMsgFailure",
+    onQueryStart = "onQueryStart",
+    onQueryFinalized = "onQueryFinalized",
+    onQueryFailure = "onQueryFailure"
 }
 export declare enum LoginMethodsEnum {
     ledger = "ledger",
@@ -39,20 +71,6 @@ export declare enum DappCoreWCV2CustomMethodsEnum {
     mvx_cancelAction = "mvx_cancelAction",
     mvx_signNativeAuthToken = "mvx_signNativeAuthToken"
 }
-export declare enum EventStoreEvents {
-    onLoginPending = "onLoginPending",
-    onLoggedIn = "onLoggedIn",
-    onQrPending = "onQrPending",
-    onQrLoaded = "onQrLoaded",
-    onLogout = "onLogout",
-    onTxStarted = "onTxStarted",
-    onTxSent = "onTxSent",
-    onTxFinalized = "onTxFinalized",
-    onTxError = "onTxError",
-    onSignMsgStarted = "onSignMsgStarted",
-    onSignMsgFinalized = "onSignMsgFinalized",
-    onSignMsgError = "onSignMsgError"
-}
 export declare enum WebWalletUrlParamsEnum {
     hasWebWalletGuardianSign = "hasWebWalletGuardianSign"
 }

build/types/utils/with-login-events.d.ts

@@ -0,0 +1 @@
+export declare const withLoginEvents: (fn: (onLoginSuccess: () => void) => Promise<void>) => Promise<void>;

build/types/webview-provider/webview-provider.d.ts

@@ -3,7 +3,7 @@
  * Based on sdk-dapp webview provider implementation
  * It will probably be replaced with separate library in the future
  */
-import { Transaction } from '@multiversx/sdk-core';
+import { Transaction } from '@multiversx/sdk-core/out/transaction';
 export declare class WebviewProvider {
     constructor();
     logout(): Promise<unknown>;

esbuild.config.cjs

@@ -6,12 +6,6 @@ const fs = require('fs');
 esbuild
   .build({
     inject: [require.resolve('node-stdlib-browser/helpers/esbuild/shim')],
-    define: {
-      global: 'global',
-      process: 'process',
-      Buffer: 'Buffer',
-      'process.env.NODE_ENV': '"production"',
-    },
     format: 'esm',
     entryPoints: ['./src/elven.ts'],
     bundle: true,

example/demo-styles.css

@@ -53,6 +53,8 @@ a {
   font-weight: bold;
   word-break: break-all;
   margin-bottom: 30px;
+  display: flex;
+  justify-content: center;
 }
 
 @media screen and (max-width: 680px) {

example/demo-ui-tools.js

@@ -51,14 +51,28 @@ export const uiLoggedInState = (loggedIn) => {
   uiPending(false);
 };
 
-export const updateTxHashContainer = (txHash) => {
+export const displayError = (error) => {
+  if (error) {
+    const txHashContainer = document.getElementById('operation-result');
+    txHashContainer.replaceChildren();
+    const container = document.createElement('div');
+    container.classList.add('operation-result');
+    container.innerText =
+      'There was an error: "' + error + '" Please try again!';
+    txHashContainer?.appendChild(container);
+  }
+};
+
+export const updateTxHashContainer = (txHash, isPending) => {
   if (txHash) {
     const txHashContainer = document.getElementById('operation-result');
+    txHashContainer.replaceChildren();
     const url = `https://devnet-explorer.multiversx.com/transactions/${txHash}`;
     const link = document.createElement('a');
     link.setAttribute('href', url);
+    link.setAttribute('target', '_blank');
     link.classList.add('transaction-link');
-    link.innerText = `➡️ ${url}`;
+    link.innerText = `Click to check your transaction on the Explorer.${isPending ? ' (Still pending...)' : ''}`;
     txHashContainer?.appendChild(link);
   }
 };

example/index.html

@@ -157,7 +157,8 @@ <h3>Other demos:</h3>
       updateTxHashContainer,
       base64ToDecimalHex,
       updateOperationResultContainer,
-      clearQrCodeContainer
+      clearQrCodeContainer,
+      displayError
     } from './demo-ui-tools.js'
 
     // Elven.js tools
@@ -187,18 +188,45 @@ <h3>Other demos:</h3>
           // Remember to change it. Get yours here: https://cloud.walletconnect.com/sign-in
           walletConnectV2ProjectId: 'f502675c63610bfe4454080ac86d70e6',
           walletConnectV2RelayAddresses: ['wss://relay.walletconnect.com'],
-          onLoginPending: () => { uiPending(true) },
-          onLoggedIn: () => { uiLoggedInState(true); uiPending(false); },
-          onLogout: () => { uiLoggedInState(false); },
-          onTxStarted: (tx) => { uiPending(true); },
-          onTxSent: (tx) => { console.log('Tx sent, not finalized on chain yet! ', tx.getHash().toString()) },
+          // All callbacks are optional
+          // You could also rely on try catch to some extent, but callbacks in one place seems convenient
+          // Login callbacks:
+          onLoginStart: () => { uiPending(true) },
+          onLoginEnd: () => { uiPending(false) },
+          onLoginSuccess: () => { uiLoggedInState(true); },
+          onLoginFailure: (error) => { displayError(error); },
+          // Logout callbacks:
+          onLogoutStart: () => { uiPending(true) },
+          onLogoutEnd: () => { uiPending(false) },
+          onLogoutSuccess: () => { uiLoggedInState(false); },
+          onLogoutFailure: (error) => { displayError(error); },
+          // Transaction callbacks
+          onTxStart: (tx) => { uiPending(true); },
+          onTxSent: (tx) => { const hash = tx.getHash().toString(); hash && updateTxHashContainer(hash, true); },
           onTxFinalized: (tx) => { tx?.hash && updateTxHashContainer(tx.hash); uiPending(false); },
-          onTxError: (tx, error) => { console.log('Tx error: ', error); uiPending(false); },
+          onTxFailure: (tx, error) => { displayError(error); uiPending(false); },
+          // Qr code callbacks:
           onQrPending: () => { uiPending(true); },
           onQrLoaded: () => { uiPending(false); },
-          onSignMsgStarted: () => { uiPending(true); },
+          // Signing callbacks:
+          onSignMsgStart: (message) => { uiPending(true); },
           onSignMsgFinalized: (message, messageSignature) => { messageSignature && updateOperationResultContainer(`➡️ The signature for "${message}" message:\n${messageSignature}`); uiPending(false); },
-          onSignMsgError: (message, error) => { console.log('Signing message error: ', error); uiPending(false); },
+          onSignMsgFailure: (message, error) => { displayError(error); uiPending(false); },
+          // Query callbacks:
+          onQueryStart: (queryArgs) => { uiPending(true); },
+          onQueryFinalized: (queryResponse) => {
+            // Manual decoding of a simple type (number here), there will be additional tools for that using ABI
+            // For now please check data converter in Buildo.dev: 
+            // https://github.com/xdevguild/buildo.dev/blob/main/components/operations/utils-operations/data-converters.tsx#L103
+            const hexVal = base64ToDecimalHex(queryResponse?.returnData?.[0]);
+            let intVal = 0;
+            if (hexVal) {
+              intVal = parseInt(hexVal, 16);
+            }
+            updateOperationResultContainer(`➡️ The result of the query is: ${intVal}`);
+            uiPending(false);
+          },
+          onQueryFailure: (queryArgs, error) => { displayError(error); uiPending(false); }
         }
       );
     }
@@ -261,7 +289,6 @@ <h3>Other demos:</h3>
     const egldTransferAddress = 'erd17a4wydhhd6t3hhssvcp9g23ppn7lgkk4g2tww3eqzx4mlq95dukss0g50f';
 
     document.getElementById('button-tx').addEventListener('click', async () => {
-      updateTxHashContainer(false);
       const demoMessage = 'Transaction demo from Elven.js!';
 
       const isGuardian = ElvenJS.storage.get('activeGuardian');
@@ -291,8 +318,6 @@ <h3>Other demos:</h3>
     const esdtTransferAddress = 'erd17a4wydhhd6t3hhssvcp9g23ppn7lgkk4g2tww3eqzx4mlq95dukss0g50f';
 
     document.getElementById('button-tx-esdt').addEventListener('click', async () => {
-      updateTxHashContainer(false);
-
       // The preconfigured transaction is for the 1 'BUILDO-22c0a5' ESDT token on the devnet
       // You need to know its ticker and how many decimals places it has
       // In this case, the token has 18 decimal places. You can check it in the MultiversX devnet explorer
@@ -323,9 +348,6 @@ <h3>Other demos:</h3>
     // It mints on the smart contract from: https://dapp-demo.elven.tools/
     const nftMinterSmartContract = 'erd1qqqqqqqqqqqqqpgqufmyqvy3kvda2uywqgx809lglxftq9t667es3956pv';
     document.getElementById('button-mint').addEventListener('click', async () => {
-
-      updateTxHashContainer(false);
-
       const contractAddress = new Address(nftMinterSmartContract);
       const contract = new SmartContract({ address: contractAddress });
 
@@ -357,28 +379,12 @@ <h3>Other demos:</h3>
     // Read more about the Elven Tools Smart Contract here: https://www.elven.tools/docs/sc-endpoints.html
     document.getElementById('button-query').addEventListener('click', async () => {
       try {
-        updateOperationResultContainer();
-        uiPending(true);
-
-        const results = await ElvenJS.queryContract({
+        await ElvenJS.queryContract({
           address: new Address(nftMinterSmartContract),
           func: new ContractFunction('getMintedPerAddressTotal'),
           args: [new AddressValue(new Address(ElvenJS.storage.get('address')))]
         });
-
-        uiPending(false);
-
-        // Manual decoding of a simple type (number here), there will be additional tools for that using ABI
-        // For now please check data converter in Buildo.dev: 
-        // https://github.com/xdevguild/buildo.dev/blob/main/components/operations/utils-operations/data-converters.tsx#L103
-        const hexVal = base64ToDecimalHex(results?.returnData?.[0]);
-        let intVal = 0;
-        if (hexVal) {
-          intVal = parseInt(hexVal, 16);
-        }
-        updateOperationResultContainer(`➡️ The result of the query is: ${intVal}`);
       } catch (e) {
-        uiPending(false);
         throw new Error(e?.message);
       }
     });
@@ -390,7 +396,6 @@ <h3>Other demos:</h3>
       try {
         await ElvenJS.signMessage('Elven Family is awesome!');
       } catch (e) {
-        uiPending(false);
         throw new Error(e?.message);
       }
     });