@flarenetwork/multichain-wallet-connector 0.0.2-rc.25 → 0.0.2-rc.27

package/README.md

@@ -16,7 +16,7 @@ A TypeScript library for connecting to multiple blockchain wallets across EVM an
 ## Installation
 
 ```bash
-npm install @flarenetwork/multichain-wallet-connector
+pnpm add @flarenetwork/multichain-wallet-connector
 ```
 
 ## Prerequisites
@@ -48,6 +48,27 @@ const multichain = new MultiChain({
 
 Only include wallets you need. Each wallet key is optional.
 
+You can also pass an `events` map to the constructor to handle wallet events outside of React (e.g. logging, analytics, non-React consumers):
+
+```typescript
+const multichain = new MultiChain({
+  wallets: {
+    /* ... */
+  },
+  events: {
+    onConnect: ({ walletType, caip2, address, isReconnect }) => {
+      console.log(`${walletType} connected to ${caip2} as ${address} (reconnect: ${isReconnect})`);
+    },
+    onDisconnect: ({ walletType }) => {},
+    onChainChanged: ({ walletType, caip2 }) => {},
+    onAccountChanged: ({ walletType, address }) => {},
+    onError: ({ walletType, error }) => {},
+  },
+});
+```
+
+Inside React components, prefer [`useMultichainEvents`](#usemultichaineventshandlers) — both can be used together.
+
 ### 2. Setup React provider
 
 ```tsx
@@ -398,6 +419,7 @@ const selection = useMultichainSelection();
 
 const args = selection.selectWallet("metamask");
 selection.toggleCaip2("eip155:14");
+selection.setSelectedCaip2s(["eip155:14", "xrpl:0"]);
 selection.clearWallet();
 selection.reset();
 
@@ -414,6 +436,10 @@ selection.selectedWallet;
 selection.selectedCaip2s;
 selection.availableCaip2s;
 selection.wallets;
+
+selection.mode; // active MultichainSelectionMode
+selection.fixedCaip2; // pinned chain for *:single-chain modes, otherwise null
+selection.chainSelectionMode; // "single" | "multi" | null — what the chain UI should render for the selected wallet
 ```
 
 #### Example A: Generic Connect Modal (app-owned view)
@@ -572,6 +598,9 @@ function LedgerAddressPicker({ caip2 }: { caip2: Caip2 }) {
   // Switch HD standard
   selection.setHdStandard("ledgerLive");
 
+  // Clear the selected address for this chain
+  selection.clearSelection();
+
   // Access all selections across chains
   console.log(selections); // { 'eip155:14': { address, bip44 }, ... }
 }

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { $ as MultiChainEvents, A as ConnectorTypeMap, B as LedgerConnectOptions, C as ConnectorClientMap, D as ConnectorProviderMap, E as ConnectorProvider, F as XrpClient, G as ChainChangedEvent, H as LedgerPaginatedBip44, I as EvmClient, J as DcentWalletOptions, K as ChainOverride, L as ChainClient, M as XamanSendTxOptions, N as LedgerSession, O as ConnectorSendTxOptions, P as DcentConnector, Q as MetaMaskWalletOptions, R as LedgerCaip2, S as ConnectorClient, T as ConnectorConnectOptionsMap, U as Bip44, V as LedgerHDStandard, W as AccountChangedEvent, X as ErrorEvent, Y as DisconnectEvent, Z as LedgerWalletOptions, _ as ConfigResolver, _t as XRPlCaip2, a as shortenAddress, at as XamanWalletOptions, c as WalletConnectError, d as DcentError, dt as BaseChain, et as MultiChainOptions, f as WalletError, ft as Caip2, g as MultiChain, gt as NonEvmChain, h as ChainGuards, ht as EvmChain, i as objectValues, it as WalletOptions, j as ConnectorXrpClientMap, k as ConnectorSendTxOptionsMap, l as MetaMaskError, m as ErrorCodeKey, mt as Eip155Caip2, n as objectFromEntries, nt as WalletConnectWalletOptions, o as WalletErrorHelper, ot as WalletAddressState, p as ErrorCode, pt as Chain, q as ConnectEvent, r as objectKeys, rt as WalletMetadata, s as XamanError, st as WalletState, t as objectEntries, tt as ResolvedWalletConfig, u as LedgerError, ut as WalletType, vt as XrplChain, w as ConnectorConnectOptions, x as Connector, z as LedgerComputedAddress } from "../index-BoPtY6iM.mjs";
+import { $ as MultiChainEvents, A as ConnectorTypeMap, B as LedgerConnectOptions, C as ConnectorClientMap, D as ConnectorProviderMap, E as ConnectorProvider, F as XrpClient, G as ChainChangedEvent, H as LedgerPaginatedBip44, I as EvmClient, J as DcentWalletOptions, K as ChainOverride, L as ChainClient, M as XamanSendTxOptions, N as LedgerSession, O as ConnectorSendTxOptions, P as DcentConnector, Q as MetaMaskWalletOptions, R as LedgerCaip2, S as ConnectorClient, T as ConnectorConnectOptionsMap, U as Bip44, V as LedgerHDStandard, W as AccountChangedEvent, X as ErrorEvent, Y as DisconnectEvent, Z as LedgerWalletOptions, _ as ConfigResolver, _t as XRPlCaip2, a as shortenAddress, at as XamanWalletOptions, c as WalletConnectError, d as DcentError, dt as BaseChain, et as MultiChainOptions, f as WalletError, ft as Caip2, g as MultiChain, gt as NonEvmChain, h as ChainGuards, ht as EvmChain, i as objectValues, it as WalletOptions, j as ConnectorXrpClientMap, k as ConnectorSendTxOptionsMap, l as MetaMaskError, m as ErrorCodeKey, mt as Eip155Caip2, n as objectFromEntries, nt as WalletConnectWalletOptions, o as WalletErrorHelper, ot as WalletAddressState, p as ErrorCode, pt as Chain, q as ConnectEvent, r as objectKeys, rt as WalletMetadata, s as XamanError, st as WalletState, t as objectEntries, tt as ResolvedWalletConfig, u as LedgerError, ut as WalletType, vt as XrplChain, w as ConnectorConnectOptions, x as Connector, z as LedgerComputedAddress } from "../index-DYYzjIvq.mjs";
 export { AccountChangedEvent, BaseChain, Bip44, Caip2, Chain, ChainChangedEvent, ChainClient, ChainGuards, ChainOverride, ConfigResolver, ConnectEvent, Connector, ConnectorClient, ConnectorClientMap, ConnectorConnectOptions, ConnectorConnectOptionsMap, ConnectorProvider, ConnectorProviderMap, ConnectorSendTxOptions, ConnectorSendTxOptionsMap, ConnectorTypeMap, ConnectorXrpClientMap, DcentConnector, DcentError, DcentWalletOptions, DisconnectEvent, Eip155Caip2, ErrorCode, ErrorCodeKey, ErrorEvent, EvmChain, EvmClient, LedgerCaip2, LedgerComputedAddress, LedgerConnectOptions, LedgerError, LedgerHDStandard, LedgerPaginatedBip44, LedgerSession, LedgerWalletOptions, MetaMaskError, MetaMaskWalletOptions, MultiChain, MultiChainEvents, MultiChainOptions, NonEvmChain, ResolvedWalletConfig, WalletAddressState, WalletConnectError, WalletConnectWalletOptions, WalletError, WalletErrorHelper, WalletMetadata, WalletOptions, WalletState, WalletType, XRPlCaip2, XamanError, XamanSendTxOptions, XamanWalletOptions, XrpClient, XrplChain, objectEntries, objectFromEntries, objectKeys, objectValues, shortenAddress };

package/dist/core/index.mjs

@@ -1,2 +1,2 @@
-import { _ as objectFromEntries, a as WalletErrorHelper, b as shortenAddress, c as MetaMaskError, d as WalletError, f as ErrorCode, g as objectEntries, h as ChainGuards, i as DcentConnector, l as LedgerError, n as EvmClient, o as XamanError, p as ConfigResolver, r as Bip44, s as WalletConnectError, t as MultiChain, u as DcentError, v as objectKeys, y as objectValues } from "../core-CJ2Ge7oD.mjs";
+import { _ as objectFromEntries, a as WalletErrorHelper, b as shortenAddress, c as MetaMaskError, d as WalletError, f as ErrorCode, g as objectEntries, h as ChainGuards, i as DcentConnector, l as LedgerError, n as EvmClient, o as XamanError, p as ConfigResolver, r as Bip44, s as WalletConnectError, t as MultiChain, u as DcentError, v as objectKeys, y as objectValues } from "../core-CwmjYh7S.mjs";
 export { Bip44, ChainGuards, ConfigResolver, DcentConnector, DcentError, ErrorCode, EvmClient, LedgerError, MetaMaskError, MultiChain, WalletConnectError, WalletError, WalletErrorHelper, XamanError, objectEntries, objectFromEntries, objectKeys, objectValues, shortenAddress };

package/dist/{core-CJ2Ge7oD.mjs → core-CwmjYh7S.mjs}

@@ -2507,6 +2507,34 @@ var WalletConnectConnector = class extends BaseConnector {
 	}
 };
 //#endregion
+//#region src/core/utils/app-resume.ts
+/**
+* Invokes `onResume` whenever the page returns to the foreground — the
+* situation after a mobile app-switch (user went to a wallet app and came
+* back), during which browsers freeze the page and let websockets die.
+*
+* Listens to both `visibilitychange` and window `focus`: iOS Safari does not
+* reliably fire visibilitychange on app-switch return, so focus backs it up.
+* `onResume` runs single-flight (a trigger while a run is still in progress
+* is ignored); its rejection is delivered to `onError`.
+*
+* Detach by aborting the provided signal. No-op outside a browser.
+*/
+function onAppResume(onResume, onError, signal) {
+	const doc = globalThis.document;
+	if (!doc) return;
+	let inFlight = false;
+	const handleResume = () => {
+		if (doc.visibilityState !== "visible" || inFlight) return;
+		inFlight = true;
+		onResume().catch(onError).finally(() => {
+			inFlight = false;
+		});
+	};
+	doc.addEventListener("visibilitychange", handleResume, { signal });
+	globalThis.window?.addEventListener("focus", handleResume, { signal });
+}
+//#endregion
 //#region src/core/connectors/xaman/xaman-xrpl-client.ts
 var XamanClient = class XamanClient extends Xumm {
 	static {
@@ -2520,6 +2548,12 @@ var XamanClient = class XamanClient extends Xumm {
 		this.resolvedConfig = resolvedConfig;
 	}
 	async sendTx(tx, sendTxOptions) {
+		const subscription = await this.createSignRequest(tx, sendTxOptions);
+		const txid = await this.awaitSignedTxid(subscription);
+		if (!txid) throw new XamanError("XAMAN_SIGN_REJECTED");
+		return txid;
+	}
+	async createSignRequest(tx, sendTxOptions) {
 		if (!this.payload) throw new XamanError("XAMAN_SDK_NOT_READY");
 		const { reference } = parseCaip2(await this.getCaip2());
 		const networkKey = XamanClient.NETWORK_KEYS[reference];
@@ -2535,12 +2569,60 @@ var XamanClient = class XamanClient extends Xumm {
 		};
 		const subscription = await this.payload.createAndSubscribe(payload, (event) => "signed" in event.data ? event : void 0);
 		if (!subscription?.created) throw new XamanError("XAMAN_SDK_NOT_READY");
-		const txid = (await subscription.resolved)?.payload?.response?.txid;
-		if (!txid) throw new XamanError("XAMAN_SIGN_REJECTED");
-		return txid;
+		return subscription;
+	}
+	/**
+	* Waits for the sign result. Primary source: the websocket subscription.
+	* Fallback: if the page was backgrounded (mobile app switch), the socket
+	* may have died without delivering the result — so on every app resume the
+	* payload is re-fetched over HTTP and, if settled, wins the race.
+	* Returns the txid, or null when the user rejected the request.
+	*/
+	async awaitSignedTxid(subscription) {
+		const listeners = new AbortController();
+		const viaSocket = Promise.resolve(subscription.resolved).then((event) => this.readSocketTxid(event));
+		const viaResume = new Promise((resolve, reject) => {
+			onAppResume(async () => {
+				const outcome = await this.refetchSignOutcome(subscription.created.uuid);
+				if (outcome.status === "pending") return;
+				subscription.resolve();
+				resolve(outcome.txid);
+			}, reject, listeners.signal);
+		});
+		try {
+			return await Promise.race([viaSocket, viaResume]);
+		} finally {
+			listeners.abort();
+		}
+	}
+	readSocketTxid(event) {
+		if (!this.isSubscriptionEvent(event)) return null;
+		return event.payload.response.txid ?? null;
+	}
+	isSubscriptionEvent(event) {
+		return typeof event === "object" && event !== null && "payload" in event;
+	}
+	async refetchSignOutcome(uuid) {
+		if (!this.payload) throw new XamanError("XAMAN_SDK_NOT_READY");
+		try {
+			const refetched = await this.payload.get(uuid);
+			return this.readSignOutcome(refetched);
+		} catch {
+			return { status: "pending" };
+		}
+	}
+	readSignOutcome(payload) {
+		if (!payload?.meta) return { status: "pending" };
+		const { resolved, cancelled, expired } = payload.meta;
+		if (!(resolved || cancelled || expired)) return { status: "pending" };
+		return {
+			status: "settled",
+			txid: payload.response.txid ?? null
+		};
 	}
 	async getCaip2() {
 		const networkId = await this.user.networkId;
+		if (networkId == null) throw new XamanError("XAMAN_SDK_NOT_READY");
 		return this.toCaip2Network(networkId);
 	}
 	async onDestroy() {
@@ -2937,4 +3019,4 @@ var MultiChain = class {
 //#endregion
 export { objectFromEntries as _, WalletErrorHelper as a, shortenAddress as b, MetaMaskError as c, WalletError as d, ErrorCode as f, objectEntries as g, ChainGuards as h, DcentConnector as i, LedgerError as l, evmCaip2s as m, EvmClient as n, XamanError as o, ConfigResolver as p, Bip44 as r, WalletConnectError as s, MultiChain as t, DcentError as u, objectKeys as v, objectValues as y };
 
-//# sourceMappingURL=core-CJ2Ge7oD.mjs.map
+//# sourceMappingURL=core-CwmjYh7S.mjs.map