@getpara/core-sdk 0.1.0 → 0.2.1

package/dist/esm/ParaCore.js

@@ -34,17 +34,22 @@ import { AuthMethod, PublicKeyStatus, PublicKeyType, WalletType, WalletScheme, O
 import forge from 'node-forge';
 const { pki, jsbn } = forge;
 import { decryptWithPrivateKey, getAsymmetricKeyPair, getPublicKeyHex } from './cryptography/utils.js';
-import { CURRENT_WALLET_IDS_CHANGE_EVENT, EXTERNAL_WALLET_CHANGE_EVENT, WalletSchemeTypeMap, getPortalBaseURL, getParaConnectBaseUrl, } from './definitions.js';
-import { getBaseUrl, initClient } from './external/userManagementClient.js';
+import { WalletSchemeTypeMap, getPortalBaseURL, getParaConnectBaseUrl, } from './definitions.js';
+import { getBaseOAuthUrl, initClient } from './external/userManagementClient.js';
 import * as mpcComputationClient from './external/mpcComputationClient.js';
 import { distributeNewShare } from './shares/shareDistribution.js';
-import { PopupType, } from './types/index.js';
+import { PopupType, ParaEvent, } from './types/index.js';
 import * as transmissionUtils from './transmission/transmissionUtils.js';
 import { sendRecoveryForShare } from './shares/recovery.js';
 import parsePhoneNumberFromString from 'libphonenumber-js';
 import { getCosmosAddress, truncateAddress } from './utils/formattingUtils.js';
 import { TransactionReviewDenied, TransactionReviewError, TransactionReviewTimeout } from './errors.js';
-const PARA_CORE_VERSION = '0.1.0';
+const PARA_CORE_VERSION = '0.2.1';
+function dispatchEvent(type, data, error) {
+    typeof window !== 'undefined' &&
+        !!window.dispatchEvent &&
+        window.dispatchEvent(new CustomEvent(type, { detail: Object.assign({ data }, (error && { error: new Error(error) })) }));
+}
 function isPregenIdentifierMatch(a, b, type) {
     if (!a || !b) {
         return false;
@@ -768,7 +773,7 @@ export class ParaCore {
             this.currentExternalWalletAddresses = [address];
             this.setCurrentExternalWalletAddresses(this.currentExternalWalletAddresses);
             this.setExternalWallets(this.externalWallets);
-            typeof window !== 'undefined' && !!window.dispatchEvent && window.dispatchEvent(new Event(EXTERNAL_WALLET_CHANGE_EVENT));
+            dispatchEvent(ParaEvent.EXTERNAL_WALLET_CHANGE_EVENT, null);
         });
     }
     /**
@@ -875,9 +880,7 @@ export class ParaCore {
             if (sessionLookupId) {
                 yield this.ctx.client.setCurrentWalletIds(this.getUserId(), this.currentWalletIds, needsWallet, sessionLookupId, newDeviceSessionLookupId);
             }
-            typeof window !== 'undefined' &&
-                !!window.dispatchEvent &&
-                window.dispatchEvent(new Event(CURRENT_WALLET_IDS_CHANGE_EVENT));
+            dispatchEvent(ParaEvent.WALLETS_CHANGE_EVENT, null);
         });
     }
     /**
@@ -1062,44 +1065,39 @@ export class ParaCore {
         });
     }
     /**
-     * Generates a URL that can be used to perform web auth
-     * for creating a new credential.
-     * @param sessionId - id of the session to use for web auth
-     * @param loginEncryptionPublicKey - public key to use for encrypting the login encryption key
-     * @param partnerId - id of the partner to get the portal URL for
-     * @param newDeviceSessionId - id of the session to use for web auth for a new device
-     * @param newDeviceEncryptionKey - public key to use for encrypting the login encryption key for a new device
-     * @returns - web auth url
+     * Generates a URL for registering a new WebAuth passkey.
+     * @param {GetWebAuthUrlForLoginParams} opts the options object
+     * @returns - the URL for creating a new passkey
      */
-    getWebAuthURLForLogin(options) {
+    getWebAuthURLForLogin(opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.constructPortalUrl('loginAuth', options);
+            return this.constructPortalUrl('loginAuth', opts);
         });
     }
-    getPasswordURLForLogin(options) {
+    /**
+     * Generates a URL for registering a new user password.
+     * @param {GetWebAuthUrlForLoginParams} opts the options object
+     * @returns - the URL for creating a new password
+     */
+    getPasswordURLForLogin(opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.constructPortalUrl('loginPassword', options);
+            return this.constructPortalUrl('loginPassword', opts);
         });
     }
     /**
-     * Generates a URL that can be used to perform web auth for phone number
-     * for creating a new credential.
-     * @param sessionId - id of the session to use for web auth
-     * @param loginEncryptionPublicKey - public key to use for encrypting the login encryption key
-     * @param partnerId - id of the partner to get the portal URL for
-     * @param newDeviceSessionId - id of the session to use for web auth for a new device
-     * @param newDeviceEncryptionKey - public key to use for encrypting the login encryption key for a new device
+     * Generates a URL for registering a new WebAuth passkey for a phone number.
+     * @param {Omit<GetWebAuthUrlForLoginParams, 'authType'>} opts the options object
      * @returns - web auth url
      */
-    getWebAuthURLForLoginForPhone(options) {
+    getWebAuthURLForLoginForPhone(opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.constructPortalUrl('loginAuth', Object.assign({ authType: 'phone' }, options));
+            return this.constructPortalUrl('loginAuth', Object.assign({ authType: 'phone' }, opts));
         });
     }
     /**
      * Gets the private key for the given wallet.
-     * @param walletId - (optional) id of the wallet to get the private key for. Will default to the first wallet if not provided.
-     * @returns - private key string.
+     * @param {string } [walletId] id of the wallet to get the private key for. Will default to the first wallet if not provided.
+     * @returns - the private key string.
      */
     getPrivateKey(walletId) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1117,7 +1115,7 @@ export class ParaCore {
     }
     /**
      * Fetches the wallets associated with the user.
-     * @returns - wallets that were fetched.
+     * @returns {WalletEntity[]} wallets that were fetched.
      */
     fetchWallets() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1152,28 +1150,34 @@ export class ParaCore {
         });
     }
     /**
-     * Checks if a user exists.
-     * @returns - true if user exists, false otherwise.
+     * Checks if a user exists for an email address.
+     * @param {Object} opts the options object
+     * @param {string} opts.email the email to check.
+     * @returns true if user exists, false otherwise.
      */
-    checkIfUserExists(email) {
+    checkIfUserExists({ email }) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.checkUserExists({ email });
             return res.data.exists;
         });
     }
     /**
-     * Checks if a user exists by their phone number.
-     * @returns - true if user exists, false otherwise.
+     * Checks if a user exists for a phone number.
+     * @param {Object} opts the options object
+     * @param {string} opts.phone - phone number to check.
+     * @param {string} opts.countryCode - the country code.
+     * @returns true if user exists, false otherwise.
      */
-    checkIfUserExistsByPhone(phone, countryCode) {
+    checkIfUserExistsByPhone({ phone, countryCode }) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.checkUserExists({ phone, countryCode });
             return res.data.exists;
         });
     }
-    /*
+    /**
      * Creates a new user.
-     * @param email - email to use for creating the user.
+     * @param {Object} opts the options object
+     * @param {string} opts.email the email to use.
      */
     createUser({ email }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1185,8 +1189,9 @@ export class ParaCore {
     }
     /**
      * Creates a new user with a phone number.
-     * @param phone - phone number to use for creating the user.
-     * @param countryCode - country code to use for creating the user.
+     * @param {Object} opts the options object
+     * @param {string} opts.phone - the phone number to use for creating the user.
+     * @param {string} opts.countryCode - the country code to use for creating the user.
      */
     createUserByPhone({ phone, countryCode }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1201,9 +1206,10 @@ export class ParaCore {
     }
     /**
      * Logs in or creates a new user using an external wallet address.
-     * @param externalAddress - external wallet address to use for identification.
-     * @param type - type of external wallet to use for identification.
-     * @param externalWalletProvider - name of provider for the external wallet.
+     * @param {Object} opts the options object
+     * @param {string} opts.address the external wallet address to use for identification.
+     * @param {WalletType} opts.type type of external wallet to use for identification.
+     * @param {string} opts.provider the name of the provider for the external wallet.
      */
     externalWalletLogin(wallet) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1225,10 +1231,11 @@ export class ParaCore {
     }
     /**
      * Passes the email code obtained from the user for verification.
-     * @param verificationCode
-     * @returns - web auth url for creating a new credential
+     * @param {Object} opts the options object
+     * @param {string} verificationCode the six-digit code to check
+     * @returns {string} the web auth url for creating a new credential
      */
-    verifyEmail(verificationCode) {
+    verifyEmail({ verificationCode }) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ctx.client.verifyEmail(this.userId, { verificationCode });
             return this.getSetUpBiometricsURL();
@@ -1236,10 +1243,11 @@ export class ParaCore {
     }
     /**
      * Passes the phone code obtained from the user for verification.
-     * @param verificationCode
-     * @returns - web auth url for creating a new credential
+     * @param {Object} opts the options object
+     * @param {string} verificationCode the six-digit code to check
+     * @returns {string} the web auth url for creating a new credential
      */
-    verifyPhone(verificationCode) {
+    verifyPhone({ verificationCode }) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ctx.client.verifyPhone(this.userId, { verificationCode });
             return this.getSetUpBiometricsURLForPhone();
@@ -1267,11 +1275,12 @@ export class ParaCore {
     }
     /**
      * Performs 2FA verification.
-     * @param email - email to use for performing a 2FA verification.
-     * @param verificationCode - verification code to received via 2FA.
-     * @returns { address, initiatedAt, status, userId, walletId }
+     * @param {Object} opts the options object
+     * @param {string} opts.email the email to use for performing a 2FA verification.
+     * @param {string} opts.verificationCode the verification code to received via 2FA.
+     * @returns {Object} `{ address, initiatedAt, status, userId, walletId }`
      */
-    verify2FA(email, verificationCode) {
+    verify2FA({ email, verificationCode }) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.verify2FA(email, verificationCode);
             return {
@@ -1284,11 +1293,13 @@ export class ParaCore {
     }
     /**
      * Performs 2FA verification.
-     * @param phone - phone to use for performing a 2FA verification.
-     * @param verificationCode - verification code to received via 2FA.
-     * @returns { address, initiatedAt, status, userId, walletId }
+     * @param {Object} opts the options object
+     * @param {string} opts.phone the phone number
+     * @param {string} opts.countryCode - the country code
+     * @param {string} opts.verificationCode - verification code to received via 2FA.
+     * @returns {Object} `{ address, initiatedAt, status, userId, walletId }`
      */
-    verify2FAForPhone(phone, countryCode, verificationCode) {
+    verify2FAForPhone({ phone, countryCode, verificationCode, }) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.verify2FAForPhone(phone, countryCode, verificationCode);
             return {
@@ -1300,8 +1311,8 @@ export class ParaCore {
         });
     }
     /**
-     * Sets up 2FA.
-     * @returns uri - uri to use for setting up 2FA
+     * Sets up two-factor authentication for the current user.
+     * @returns {string} uri - uri to use for setting up 2FA
      * */
     setup2FA() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1313,16 +1324,17 @@ export class ParaCore {
     }
     /**
      * Enables 2FA.
-     * @param verificationCode - verification code received via 2FA.
+     * @param {Object} opts the options object
+     * @param {string} opts.verificationCode - the verification code received via 2FA.
      */
-    enable2FA(verificationCode) {
+    enable2FA({ verificationCode }) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ctx.client.enable2FA(this.userId, verificationCode);
         });
     }
     /**
      * Determines if 2FA has been set up.
-     * @returns { isSetup } - true if 2FA is setup, false otherwise
+     * @returns {Object} `{ isSetup: boolean }` - true if 2FA is setup, false otherwise
      */
     check2FAStatus() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1335,11 +1347,17 @@ export class ParaCore {
             };
         });
     }
+    /**
+     * Resend a verification email for the current user.
+     */
     resendVerificationCode() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ctx.client.resendVerificationCode(Object.assign({ userId: this.userId }, this.getVerificationEmailProps()));
         });
     }
+    /**
+     * Resend a verification SMS for the current user.
+     */
     resendVerificationCodeByPhone() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ctx.client.resendVerificationCodeByPhone({
@@ -1347,7 +1365,13 @@ export class ParaCore {
             });
         });
     }
-    // returns web auth url for creating a new credential
+    /**
+     * Returns a URL for setting up a new WebAuth passkey.
+     * @param {Object} opts the options object
+     * @param {string} opts.authType - the auth type to use
+     * @param {boolean} opts.isForNewDevice whether the passkey is for a new device of an existing user
+     * @returns {string} the URL
+     */
     getSetUpBiometricsURL({ authType = 'email', isForNewDevice = false, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.addSessionPublicKey(this.userId, {
@@ -1362,7 +1386,12 @@ export class ParaCore {
             });
         });
     }
-    // returns web auth url for creating a new credential
+    /**
+     * Returns a URL for setting up a new WebAuth passkey for a phone number.
+     * @param {Object} opts the options object
+     * @param {boolean} opts.isForNewDevice whether the passkey is for a new device of an existing user
+     * @returns {string} the URL
+     */
     getSetUpBiometricsURLForPhone({ isForNewDevice = false, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.addSessionPublicKey(this.userId, {
@@ -1377,6 +1406,14 @@ export class ParaCore {
             });
         });
     }
+    /**
+     * Returns a URL for setting up a new password.
+     * @param {Object} opts the options object
+     * @param {string} opts.authType - the auth type to use
+     * @param {boolean} opts.isForNewDevice whether the passkey is for a new device of an existing user
+     * @param {Theme} [opts.theme] the portal theme to use in place of the partner's default
+     * @returns {string} the URL
+     */
     getSetupPasswordURL({ authType = 'email', isForNewDevice = false, theme, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this.ctx.client.addSessionPasswordPublicKey(this.userId, {
@@ -1391,6 +1428,10 @@ export class ParaCore {
             });
         });
     }
+    /**
+     * Checks if the current session is active.
+     * @returns `true` if active, `false` otherwise
+     */
     isSessionActive() {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.isUsingExternalWallet()) {
@@ -1402,8 +1443,7 @@ export class ParaCore {
     }
     /**
      * Checks if a session is active and a wallet exists.
-     *
-     * @returns true if session is active and a wallet exists.
+     * @returns `true` if active, `false` otherwise
      **/
     isFullyLoggedIn() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1473,9 +1513,10 @@ export class ParaCore {
     }
     /**
      * Initiates a login.
-     * @param email - the email to login with
-     * @param useShortURL - whether to shorten the link
-     * @returns - web auth url for logging in
+     * @param {Object} opts the options object
+     * @param {String} opts.email - the email to login with
+     * @param {boolean} opts.useShortURL - whether to shorten the link
+     * @returns - the WebAuth URL for logging in
      **/
     initiateUserLogin(_a) {
         var { useShortUrl = false } = _a, auth = __rest(_a, ["useShortUrl"]);
@@ -1514,10 +1555,11 @@ export class ParaCore {
     }
     /**
      * Initiates a login.
-     * @param phone - the phone number to login with
-     * @param countryCode
-     * @param useShortURL - whether to shorten the link
-     * @returns - web auth url for logging in
+     * @param opts the options object
+     * @param opts.phone the phone number
+     * @param opts.countryCode the country code
+     * @param opts.useShortURL - whether to shorten the link
+     * @returns - the WebAuth URL for logging in
      **/
     initiateUserLoginForPhone(_a) {
         var { useShortUrl = false } = _a, auth = __rest(_a, ["useShortUrl"]);
@@ -1553,6 +1595,7 @@ export class ParaCore {
                     yield new Promise(resolve => setTimeout(resolve, POLLING_INTERVAL_MS));
                     if (yield this.isSessionActive()) {
                         this.isAwaitingAccountCreation = false;
+                        dispatchEvent(ParaEvent.ACCOUNT_CREATION_EVENT, true);
                         return true;
                     }
                 }
@@ -1580,14 +1623,15 @@ export class ParaCore {
             const created = yield this.createWalletPerType();
             recoverySecret = recoverySecret !== null && recoverySecret !== void 0 ? recoverySecret : created.recoverySecret;
             walletIds = Object.assign(Object.assign({}, walletIds), created.walletIds);
-            return { walletIds, recoverySecret };
+            const resp = { walletIds, recoverySecret };
+            dispatchEvent(ParaEvent.ACCOUNT_SETUP_EVENT, resp);
+            return resp;
         });
     }
     /**
      * Initiates a Farcaster login attempt and return the URI for the user to connect.
      * You can create a QR code with this URI that works with Farcaster's mobile app.
-     *
-     * @return {string}
+     * @return {string} the Farcaster connect URI
      */
     getFarcasterConnectURL() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1600,9 +1644,7 @@ export class ParaCore {
     /**
      * Awaits the response from a user's attempt to log in with Farcaster.
      * If successful, this returns the user's Farcaster username and profile picture and indicates whether the user already exists.
-     *
-     * @param {Object} opts the options object.
-     * @return {Object} the user's information and whether the user already exists.
+     * @return {Object} `{userExists: boolean; username: string; pfpUrl?: string | null }` - the user's information and whether the user already exists.
      */
     waitForFarcasterStatus() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1632,16 +1674,17 @@ export class ParaCore {
     /**
      * Generates a URL for the user to log in with OAuth using a desire method.
      *
-     * @param {OAuthMethod} oAuthMethod the third-party service to use for OAuth.
+     * @param {Object} opts the options object
+     * @param {OAuthMethod} opts.method the third-party service to use for OAuth.
      * @returns {string} the URL for the user to log in with OAuth.
      */
-    getOAuthURL(oAuthMethod) {
+    getOAuthURL({ method }) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.logout();
             const res = yield this.touchSession(true);
             return constructUrl({
-                base: oAuthMethod === OAuthMethod.TELEGRAM ? getPortalBaseURL(this.ctx, true) : getBaseUrl(this.ctx.env),
-                path: `/auth/${oAuthMethod.toLowerCase()}`,
+                base: method === OAuthMethod.TELEGRAM ? getPortalBaseURL(this.ctx, true) : getBaseOAuthUrl(this.ctx.env),
+                path: `/auth/${method.toLowerCase()}`,
                 params: {
                     apiKey: this.ctx.apiKey,
                     sessionLookupId: res.data.sessionLookupId,
@@ -1655,7 +1698,7 @@ export class ParaCore {
      *
      * @param {Object} opts the options object.
      * @param {Window} [opts.popupWindow] the popup window being used for login.
-     * @return {Object} the user's email address and whether the user already exists.
+     * @return {Object} `{ email?: string; isError?: boolean; userExists: boolean; }` the result data
      */
     waitForOAuth({ popupWindow } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1672,7 +1715,7 @@ export class ParaCore {
                             const { userId, email } = res.data;
                             yield this.setUserId(userId);
                             yield this.setEmail(email);
-                            const userExists = yield this.checkIfUserExists(email);
+                            const userExists = yield this.checkIfUserExists({ email });
                             this.isAwaitingOAuth = false;
                             return {
                                 userExists,
@@ -1694,12 +1737,12 @@ export class ParaCore {
      * @param {Object} opts the options object
      * @param {Window} [opts.popupWindow] the popup window being used for login.
      * @param {boolean} [opts.skipSessionRefresh] whether to skip refreshing the session.
-     * @returns { needsWallet } - whether a wallet needs to be created
+     * @returns {Object} `{ isComplete: boolean; isError: boolean; needsWallet: boolean; partnerId: string; }` the result data
      **/
     waitForLoginAndSetup({ popupWindow, skipSessionRefresh = false, } = {}) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
-            // Remove external wallets if logging in with Para
+            // Remove external wallets if logging in with Capsule
             this.currentExternalWalletAddresses = undefined;
             this.externalWallets = {};
             this.isAwaitingLogin = true;
@@ -1708,7 +1751,9 @@ export class ParaCore {
                     yield new Promise(resolve => setTimeout(resolve, POLLING_INTERVAL_MS));
                     if (!(yield this.isSessionActive())) {
                         if (popupWindow === null || popupWindow === void 0 ? void 0 : popupWindow.closed) {
-                            return { isComplete: false, isError: true };
+                            const resp = { isComplete: false, isError: true };
+                            dispatchEvent(ParaEvent.LOGIN_EVENT, resp, 'failed to setup user');
+                            return resp;
                         }
                         continue;
                     }
@@ -1717,7 +1762,9 @@ export class ParaCore {
                     if (!needsWallet) {
                         if (this.currentWalletIdsArray.length === 0) {
                             if (popupWindow === null || popupWindow === void 0 ? void 0 : popupWindow.closed) {
-                                return { isComplete: false, isError: true };
+                                const resp = { isComplete: false, isError: true };
+                                dispatchEvent(ParaEvent.LOGIN_EVENT, resp, 'failed to setup user');
+                                return resp;
                             }
                             else {
                                 continue;
@@ -1731,11 +1778,13 @@ export class ParaCore {
                     if (tempSharesRes.data.temporaryShares.length === fetchedWallets.length) {
                         yield this.setupAfterLogin({ temporaryShares: tempSharesRes.data.temporaryShares, skipSessionRefresh });
                         yield this.claimPregenWallets();
-                        return {
+                        const resp = {
                             isComplete: true,
                             needsWallet: needsWallet || Object.values(this.wallets).length === 0,
                             partnerId: postLoginData.data.partnerId,
                         };
+                        dispatchEvent(ParaEvent.LOGIN_EVENT, resp);
+                        return resp;
                     }
                 }
                 catch (err) {
@@ -1743,7 +1792,9 @@ export class ParaCore {
                     console.error(err);
                 }
             }
-            return { isComplete: false };
+            const resp = { isComplete: false };
+            dispatchEvent(ParaEvent.LOGIN_EVENT, resp, 'exitted login without setting up user');
+            return resp;
         });
     }
     /**
@@ -1752,7 +1803,7 @@ export class ParaCore {
      *
      * @param {Object} opts the options object.
      * @param {boolean} [shouldOpenPopup] - if `true`, the running device will open a popup to reauthenticate the user.
-     * @returns - a URL for the user to reauthenticate.
+     * @returns a URL for the user to reauthenticate.
      **/
     refreshSession({ shouldOpenPopup = false } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1787,8 +1838,8 @@ export class ParaCore {
     }
     /**
      * Get transmission shares associated with session.
-     *
-     * @param isForNewDevice - true if this device is registering.
+     * @param {Object} opts the options object.
+     * @param {boolean} opts.isForNewDevice - true if this device is registering.
      * @returns - transmission keyshares.
      **/
     getTransmissionKeyShares({ isForNewDevice = false } = {}) {
@@ -1800,8 +1851,9 @@ export class ParaCore {
     }
     /**
      * Call this method after login to perform setup.
-     *
-     * @param temporaryShares - optional temporary shares to use for decryption.
+     * @param {Object} opts the options object.
+     * @param {any[]} opts.temporaryShares optional temporary shares to use for decryption.
+     * @param {boolean} [opts.skipSessionRefresh] - whether or not to skip refreshing the session.
      **/
     setupAfterLogin({ temporaryShares, skipSessionRefresh = false, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1822,12 +1874,12 @@ export class ParaCore {
     }
     /**
      * Distributes a new wallet recovery share.
-     *
-     * @param walletId - the wallet to distribute the recovery share for.
-     * @param userShare - optional user share generate the recovery share from. Defaults to the signer from the passed in walletId
-     * @param skipBiometricShareCreation - whether or not to skip biometric share creation. Used when regenerating recovery shares.
-     * @param forceRefreshRecovery - whether or not to force recovery secret regeneration. Used when regenerating recovery shares.
-     * @returns - recovery share.
+     * @param {Object} opts the options object.
+     * @param {string} opts.walletId the wallet to distribute the recovery share for.
+     * @param {string} opts.userShare optional user share generate the recovery share from. Defaults to the signer from the passed in walletId
+     * @param {boolean} opts.skipBiometricShareCreation whether or not to skip biometric share creation. Used when regenerating recovery shares.
+     * @param {boolean} opts.forceRefreshRecovery whether or not to force recovery secret regeneration. Used when regenerating recovery shares.
+     * @returns {string} the recovery share.
      **/
     distributeNewWalletShare({ walletId, userShare, skipBiometricShareCreation = false, forceRefresh = false, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1971,10 +2023,10 @@ export class ParaCore {
     }
     /**
      * Creates a new wallet.
-     *
-     * @param skipDistribute - if true, recovery share will not be distributed.
-     * @param [customFunction] - {deprecated} method called when createWallet is done.
-     * @returns [wallet, recoveryShare]
+     * @param {Object} opts the options object.
+     * @param {WalletType} opts.type the type of wallet to create.
+     * @param {boolean} opts.skipDistribute - if true, recovery share will not be distributed.
+     * @returns {[Wallet, string | null]} `[wallet, recoveryShare]` - the wallet object and the new recovery share.
      **/
     createWallet({ type: _type, skipDistribute = false, } = {}) {
         var _a, _b;
@@ -2016,6 +2068,12 @@ export class ParaCore {
                 });
             }
             yield this.setCurrentWalletIds(Object.assign(Object.assign({}, this.currentWalletIds), { [walletType]: [...((_b = this.currentWalletIds[walletType]) !== null && _b !== void 0 ? _b : []), walletId] }));
+            const walletNoSigner = Object.assign({}, wallet);
+            delete walletNoSigner.signer;
+            dispatchEvent(ParaEvent.WALLET_CREATED, {
+                wallet: walletNoSigner,
+                recoverySecret: recoveryShare,
+            });
             return [wallet, recoveryShare];
         });
     }
@@ -2028,7 +2086,7 @@ export class ParaCore {
      * @param {WalletType} [opts.type] the type of wallet to create. Defaults to the first non-optional type in the instance's `supportedWalletTypes` array.
      * @returns {Wallet} the created wallet.
      **/
-    createWalletPreGen(opts) {
+    createPregenWallet(opts) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             const { type: _type = (_a = this.supportedWalletTypes.find(({ optional }) => !optional)) === null || _a === void 0 ? void 0 : _a.type, pregenIdentifier, pregenIdentifierType = 'EMAIL', } = opts;
@@ -2062,17 +2120,17 @@ export class ParaCore {
      * Creates new pregenerated wallets for each desired type.
      * If no types are provided, this method will create one for each of the non-optional types
      * specified in the instance's `supportedWalletTypes` array that are not already present.
-     *
-     * @param {string} pregenIdentifier the identifier to associate each wallet with.
-     * @param {TPregenIdentifierType} pregenIdentifierType - either `'EMAIL'` or `'PHONE'`.
-     * @param {WalletType[]} [types] the wallet types to create. Defaults to any types the instance supports that are not already present.
-     * @returns an array containing the created wallets.
+     * @param {Object} opts the options object.
+     * @param {string} opts.pregenIdentifier the identifier to associate each wallet with.
+     * @param {TPregenIdentifierType} opts.pregenIdentifierType - either `'EMAIL'` or `'PHONE'`.
+     * @param {WalletType[]} [opts.types] the wallet types to create. Defaults to any types the instance supports that are not already present.
+     * @returns {Wallet[]} an array containing the created wallets.
      **/
     createPregenWalletPerType({ types, pregenIdentifier, pregenIdentifierType = 'EMAIL', }) {
         return __awaiter(this, void 0, void 0, function* () {
             const wallets = [];
             for (const type of yield this.getTypesToCreate(types)) {
-                const wallet = yield this.createWalletPreGen({ type, pregenIdentifier, pregenIdentifierType });
+                const wallet = yield this.createPregenWallet({ type, pregenIdentifier, pregenIdentifierType });
                 wallets.push(wallet);
             }
             return wallets;
@@ -2081,11 +2139,12 @@ export class ParaCore {
     /**
      * Claims a pregenerated wallet.
      *
-     * @param pregenIdentifier string the identifier of the user claiming the wallet
-     * @param pregenIdentifierType type of the identifier of the user claiming the wallet
-     * @returns [wallet, recoveryShare]
+     * @param {Object} opts the options object.
+     * @param {string} opts.pregenIdentifier string the identifier of the user claiming the wallet
+     * @param {TPregenIdentifierType} opts.pregenIdentifierType type of the identifier of the user claiming the wallet
+     * @returns {[Wallet, string | null]} `[wallet, recoveryShare]` - the wallet object and the new recovery share.
      **/
-    claimPregenWallets(pregenIdentifier, pregenIdentifierType = !!pregenIdentifier ? 'EMAIL' : undefined) {
+    claimPregenWallets({ pregenIdentifier, pregenIdentifierType = !!pregenIdentifier ? 'EMAIL' : undefined, } = {}) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
             this.requireApiKey();
@@ -2129,17 +2188,23 @@ export class ParaCore {
                     }
                 }
                 this.wallets[wallet.id] = Object.assign(Object.assign({}, this.wallets[wallet.id]), { signer: (_a = refreshedShare === null || refreshedShare === void 0 ? void 0 : refreshedShare.signer) !== null && _a !== void 0 ? _a : wallet.signer, userId: this.userId, pregenIdentifier: undefined, pregenIdentifierType: undefined });
+                const walletNoSigner = Object.assign({}, this.wallets[wallet.id]);
+                delete walletNoSigner.signer;
+                dispatchEvent(ParaEvent.PREGEN_WALLET_CLAIMED, {
+                    wallet: walletNoSigner,
+                    recoverySecret: newRecoverySecret,
+                });
             }
             yield this.setWallets(this.wallets);
             return newRecoverySecret;
         });
     }
     /**
-     * Updates a pregenerated wallet identifier.
-     *
-     * @param newIdentifier - string
-     * @param walletId - string
-     * @returns Promise<void>
+     * Updates the identifier for a pregen wallet.
+     * @param {Object} opts the options object.
+     * @param {string} opts.walletId the pregen wallet ID
+     * @param {string} opts.newPregenIdentifier the new identtifier
+     * @param {TPregenIdentifierType} opts.newPregenIdentifierType: the new identifier type
      **/
     updatePregenWalletIdentifier({ walletId, newPregenIdentifier, newPregenIdentifierType, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2155,11 +2220,11 @@ export class ParaCore {
         });
     }
     /**
-     * Checks if Pregen Wallet exists for the identifier and partnerId
-     *
-     * @param pregenIdentifier string the identifier of the user claiming the wallet
-     * @param pregenIdentifierType type of the string of the identifier of the user claiming the wallet
-     * @returns Promise<boolean>
+     * Checks if a pregen Wallet exists for the given identifier with the current partner.
+     * @param {Object} opts the options object.
+     * @param {string} opts.pregenIdentifier string the identifier of the user claiming the wallet
+     * @param {TPregenIdentifierType} opts.pregenIdentifierType type of the string of the identifier of the user claiming the wallet
+     * @returns {boolean} whether the pregen wallet exists
      **/
     hasPregenWallet({ pregenIdentifier, pregenIdentifierType, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2174,11 +2239,11 @@ export class ParaCore {
         });
     }
     /**
-     * Get pregen wallets for the identifier
-     *
-     * @param {string} pregenIdentifier - the identifier of the user claiming the wallet
-     * @param {TPregenIdentifierType} pregenIdentifierType - type of the identifier of the user claiming the wallet
-     * @returns {Promise<WalletEntity[]>} Promise of pregen wallets
+     * Get pregen wallets for the given identifier.
+     * @param {Object} opts the options object.
+     * @param {string} opts.pregenIdentifier - the identifier of the user claiming the wallet
+     * @param {TPregenIdentifierType} opts.pregenIdentifierType - type of the identifier of the user claiming the wallet
+     * @returns {Promise<WalletEntity[]>} the array of found wallets
      **/
     getPregenWallets({ pregenIdentifier, pregenIdentifierType = !!pregenIdentifier ? 'EMAIL' : undefined, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2193,9 +2258,8 @@ export class ParaCore {
         return base64Wallet;
     }
     /**
-     * Returns a base64 encoded wallet
-     *
-     * @returns string base64 encoded wallet
+     * Encodes the current wallets encoded in Base 64.
+     * @returns {string} the encoded wallet string
      **/
     getUserShare() {
         if (Object.values(this.wallets).length === 0) {
@@ -2206,10 +2270,8 @@ export class ParaCore {
             .join('-');
     }
     /**
-     * Sets a wallet from a base 64 encoded wallet
-     *
-     * @param base64Wallet
-     * @returns Promise<void>
+     * Sets the current wallets from a Base 64 string.
+     * @param {string} base64Wallet the encoded wallet string
      **/
     setUserShare(base64Wallets) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2256,13 +2318,15 @@ export class ParaCore {
         });
     }
     /**
-     * Signs a message.
+     * Signs a message using one of the current wallets.
      *
      * If you want to sign the keccak256 hash of a message, hash the
      * message first and then pass in the base64 encoded hash.
-     * @param walletId - id of the wallet to sign with.
-     * @param messageBase64 - base64 encoding of exact message that should be signed
-     * @param timeout - optional timeout in milliseconds. If not present, defaults to 30 seconds.
+     * @param {Object} opts the options object.
+     * @param {string} opts.walletId the id of the wallet to sign with.
+     * @param {string} opts.messageBase64 the base64 encoding of exact message that should be signed
+     * @param {number} [opts.timeout] optional timeout in milliseconds. If not present, defaults to 30 seconds.
+     * @param {string} [opts.cosmosSignDocBase64] the Cosmos `SignDoc` in base64, if applicable
      **/
     signMessage({ walletId, messageBase64, timeoutMs = 30000, cosmosSignDocBase64, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2278,6 +2342,7 @@ export class ParaCore {
                 this.platformUtils.openPopup(yield this.getTransactionReviewUrl(signRes.pendingTransactionId, timeoutMs), { type: cosmosSignDocBase64 ? PopupType.SIGN_TRANSACTION_REVIEW : PopupType.SIGN_MESSAGE_REVIEW });
             }
             else {
+                dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes);
                 return signRes;
             }
             yield new Promise(resolve => setTimeout(resolve, POLLING_INTERVAL_MS));
@@ -2289,7 +2354,9 @@ export class ParaCore {
                     yield this.ctx.client.getPendingTransaction(this.userId, signRes.pendingTransactionId);
                 }
                 catch (err) {
-                    throw new TransactionReviewDenied();
+                    const error = new TransactionReviewDenied();
+                    dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+                    throw error;
                 }
                 signRes = yield this.signMessageInner({ wallet, signerId, messageBase64, cosmosSignDocBase64 });
                 if (signRes.pendingTransactionId) {
@@ -2300,8 +2367,11 @@ export class ParaCore {
                 }
             }
             if (signRes.pendingTransactionId) {
-                throw new TransactionReviewTimeout(yield this.getTransactionReviewUrl(signRes.pendingTransactionId), signRes.pendingTransactionId);
+                const error = new TransactionReviewTimeout(yield this.getTransactionReviewUrl(signRes.pendingTransactionId), signRes.pendingTransactionId);
+                dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+                throw error;
             }
+            dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes);
             return signRes;
         });
     }
@@ -2321,9 +2391,11 @@ export class ParaCore {
     }
     /**
      * Signs a transaction.
-     * @param walletId - id of the wallet to sign the transaction from.
-     * @param rlpEncodedTxBase64 - rlp encoded tx as base64 string
-     * @param chainId - chain id of the chain the transaction is being sent on.
+     * @param {Object} opts the options object.
+     * @param {string} opts.walletId the id of the wallet to sign with.
+     * @param {string} opts.rlpEncodedTxBase64 the transaction to sign, in RLP base64 encoding
+     * @param {string} [opts.chainId] the EVM chain id of the chain the transaction is being sent on, if applicable
+     * @param {number} [opts.timeoutMs] the amount of time to wait for the user to sign the transaction, in milliseconds
      **/
     signTransaction({ walletId, rlpEncodedTxBase64, chainId, timeoutMs = 30000, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2339,6 +2411,7 @@ export class ParaCore {
                 this.platformUtils.openPopup(yield this.getTransactionReviewUrl(signRes.pendingTransactionId, timeoutMs), { type: PopupType.SIGN_TRANSACTION_REVIEW });
             }
             else {
+                dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
                 return signRes;
             }
             yield new Promise(resolve => setTimeout(resolve, POLLING_INTERVAL_MS));
@@ -2350,7 +2423,9 @@ export class ParaCore {
                     yield this.ctx.client.getPendingTransaction(this.userId, signRes.pendingTransactionId);
                 }
                 catch (err) {
-                    throw new TransactionReviewDenied();
+                    const error = new TransactionReviewDenied();
+                    dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+                    throw error;
                 }
                 signRes = yield this.platformUtils.signTransaction(this.ctx, signerId, walletId, this.wallets[walletId].signer, rlpEncodedTxBase64, chainId, this.retrieveSessionCookie(), wallet.scheme === WalletScheme.DKLS);
                 if (signRes.pendingTransactionId) {
@@ -2361,12 +2436,16 @@ export class ParaCore {
                 }
             }
             if (signRes.pendingTransactionId) {
-                throw new TransactionReviewTimeout(yield this.getTransactionReviewUrl(signRes.pendingTransactionId), signRes.pendingTransactionId);
+                const error = new TransactionReviewTimeout(yield this.getTransactionReviewUrl(signRes.pendingTransactionId), signRes.pendingTransactionId);
+                dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+                throw error;
             }
+            dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
             return signRes;
         });
     }
     /**
+     * @deprecated
      * Sends a transaction.
      * @param walletId - id of the wallet to send the transaction from.
      * @param rlpEncodedTxBase64 - rlp encoded tx as base64 string
@@ -2379,7 +2458,8 @@ export class ParaCore {
             const signRes = yield this.platformUtils.sendTransaction(this.ctx, this.userId, walletId, this.wallets[walletId].signer, rlpEncodedTxBase64, chainId, this.retrieveSessionCookie(), wallet.scheme === WalletScheme.DKLS);
             if (signRes.pendingTransactionId) {
                 this.platformUtils.openPopup(yield this.getTransactionReviewUrl(signRes.pendingTransactionId), { type: PopupType.SIGN_TRANSACTION_REVIEW });
-                throw new TransactionReviewError(yield this.getTransactionReviewUrl(signRes.pendingTransactionId));
+                const error = new TransactionReviewError(yield this.getTransactionReviewUrl(signRes.pendingTransactionId));
+                throw error;
             }
             return signRes;
         });
@@ -2389,11 +2469,11 @@ export class ParaCore {
     }
     /**
      * Starts a on-ramp or off-ramp transaction and returns the Para Portal link for the user to finalize and complete it.
-     * @param {Object} options - the options for the transaction.
-     * @param {OnRampPurchaseCreateParams} options.params - the transaction settings.
-     * @param {boolean} options.shouldOpenPopup - if `true`, a popup window with the link will be opened.
-     * @param {string} options.walletId - the wallet ID to use for the transaction, where funds will be sent or withdrawn.
-     * @param {string} options.externalWalletAddress - the external wallet address to send funds to or withdraw funds from, if using an external wallet.
+     * @param {Object} opts the options object
+     * @param {OnRampPurchaseCreateParams} opts.params the transaction settings.
+     * @param {boolean} opts.shouldOpenPopup if `true`, a popup window with the link will be opened.
+     * @param {string} opts.walletId the wallet ID to use for the transaction, where funds will be sent or withdrawn.
+     * @param {string} opts.externalWalletAddress the external wallet address to send funds to or withdraw funds from, if using an external wallet.
      **/
     initiateOnRampTransaction(options) {
         var _a;
@@ -2408,7 +2488,7 @@ export class ParaCore {
         });
     }
     /**
-     * Returns true if session was successfully kept alive, false otherwise.
+     * Returns `true` if session was successfully kept alive, `false` otherwise.
      **/
     keepSessionAlive() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2421,6 +2501,10 @@ export class ParaCore {
             }
         });
     }
+    /**
+     * Serialize the current session for import by another Para instance.
+     * @returns {string} the serialized session
+     */
     exportSession() {
         const sessionInfo = {
             email: this.email,
@@ -2433,6 +2517,10 @@ export class ParaCore {
         };
         return Buffer.from(JSON.stringify(sessionInfo)).toString('base64');
     }
+    /**
+     * Imports a session serialized by another Para instance.
+     * @param {string} serializedInstanceBase64 the serialized session
+     */
     importSession(serializedInstanceBase64) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -2483,8 +2571,8 @@ export class ParaCore {
     }
     /**
      * Logs the user out.
-     *
-     * @param preservePregenWallets - preserves the stored pregen wallets in memory after the logout.
+     * @param {Object} opts the options object.
+     * @param {boolean} opts.clearPregenWallets if `true`, will remove all pregen wallets from storage
      **/
     logout({ clearPregenWallets = false } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2511,6 +2599,7 @@ export class ParaCore {
             this.countryCode = undefined;
             this.userId = undefined;
             this.sessionCookie = undefined;
+            dispatchEvent(ParaEvent.LOGOUT_EVENT, null);
         });
     }
     getSupportedCreateAuthMethods() {