@meshconnect/uwc-core 0.10.1 → 1.0.1

package/dist/universal-wallet-connector.js

@@ -1,3 +1,4 @@
+import { WalletConnectorError } from '@meshconnect/uwc-types';
 import { InjectedConnector } from '@meshconnect/uwc-injected-connector';
 import { WalletConnectConnector } from '@meshconnect/uwc-wallet-connect-connector';
 import { TonConnectConnector } from '@meshconnect/uwc-ton-connector';
@@ -10,6 +11,7 @@ import { TransactionService } from './services/transaction-service';
 import { WalletCapabilitiesService } from './services/wallet-capabilities-service';
 import { createNetworkRpcMap } from './utils/network-rpc-utils';
 export class UniversalWalletConnector {
+    static instance = null;
     static instanceCount = 0;
     static hasWarnedAboutMultipleInstances = false;
     sessionManager;
@@ -25,48 +27,100 @@ export class UniversalWalletConnector {
     usingIntegratedBrowser;
     detectionComplete = false;
     networkRpcMap;
-    constructor(networks, wallets = [], usingIntegratedBrowser = false, walletConnectConfig, tonConnectConfig, tronConnectorConfig) {
-        // Track instance creation
+    /**
+     * Recommended entry point: returns the shared instance, creating it on the
+     * first call. Subsequent calls ignore the `config` argument — use
+     * `resetInstance()` first if you need to reinitialise (e.g. in tests).
+     */
+    static getInstance(config) {
+        if (UniversalWalletConnector.instance) {
+            return UniversalWalletConnector.instance;
+        }
+        if (!config) {
+            throw new Error('UniversalWalletConnector.getInstance() was called before an instance existed. Pass a config on the first call.');
+        }
+        return new UniversalWalletConnector(config);
+    }
+    /** Clear the shared instance reference. Primarily for tests and full-logout flows. */
+    static resetInstance() {
+        UniversalWalletConnector.instance = null;
+        UniversalWalletConnector.instanceCount = 0;
+        UniversalWalletConnector.hasWarnedAboutMultipleInstances = false;
+    }
+    constructor(networksOrConfig, wallets = [], usingIntegratedBrowser = false, walletConnectConfig, tonConnectConfig, tronConnectorConfig) {
+        if (!networksOrConfig) {
+            throw new Error('Universal Wallet Connector must be initialized with at least one network');
+        }
+        let config;
+        if (Array.isArray(networksOrConfig)) {
+            config = {
+                networks: networksOrConfig,
+                wallets,
+                usingIntegratedBrowser
+            };
+            if (walletConnectConfig) {
+                config.walletConnectConfig = walletConnectConfig;
+            }
+            if (tonConnectConfig) {
+                config.tonConnectConfig = tonConnectConfig;
+            }
+            if (tronConnectorConfig) {
+                config.tronConnectorConfig = tronConnectorConfig;
+            }
+        }
+        else {
+            config = networksOrConfig;
+        }
+        const { networks, wallets: configuredWallets = [], usingIntegratedBrowser: configuredUsingIntegratedBrowser = false, walletConnectConfig: configuredWalletConnectConfig, tonConnectConfig: configuredTonConnectConfig, tronConnectorConfig: configuredTronConnectorConfig } = config;
+        // Track instance creation and warn on duplicates
         UniversalWalletConnector.instanceCount++;
-        // Warn about multiple instances
         if (UniversalWalletConnector.instanceCount > 1 &&
             !UniversalWalletConnector.hasWarnedAboutMultipleInstances) {
             // eslint-disable-next-line no-console
             console.error(`⚠️ WARNING: Multiple instances of UniversalWalletConnector detected (${UniversalWalletConnector.instanceCount} instances). ` +
                 'This can lead to state inconsistencies and unexpected behavior. ' +
                 'Please ensure you create only one instance and reuse it throughout your application. ' +
-                'Consider using a singleton pattern or a context provider. ' +
+                'Use UniversalWalletConnector.getInstance(config) instead of `new` to guarantee a single instance. ' +
                 'You can ignore this warning if you are using React Strict Mode, which intentionally mounts components twice in development to help identify side effects.');
             UniversalWalletConnector.hasWarnedAboutMultipleInstances = true;
         }
-        if (!networks) {
+        // Reject empty arrays as well as null/undefined to honour the error
+        // messages below. The companion type `UWCConfig.wallets` is required, so
+        // TypeScript callers get a compile error for the missing-wallets case;
+        // this runtime guard catches the empty-array case the type can't express.
+        if (!networks || networks.length === 0) {
             throw new Error('Universal Wallet Connector must be initialized with at least one network');
         }
-        if (!wallets) {
+        if (!configuredWallets || configuredWallets.length === 0) {
             throw new Error('Universal Wallet Connector must be initialized with at least one wallet');
         }
-        this.wallets = wallets;
-        this.usingIntegratedBrowser = usingIntegratedBrowser;
+        this.wallets = configuredWallets;
+        this.usingIntegratedBrowser = configuredUsingIntegratedBrowser;
         // Create RPC map from networks
         this.networkRpcMap = createNetworkRpcMap(networks);
         // Initialize connectors with RPC map
         this.connectors = new Map();
-        this.injectedConnector = new InjectedConnector(this.networkRpcMap, this.wallets, tonConnectConfig, tronConnectorConfig, networks);
+        this.injectedConnector = new InjectedConnector(this.networkRpcMap, this.wallets, configuredTonConnectConfig, configuredTronConnectorConfig, networks);
         this.connectors.set('injected', this.injectedConnector);
-        if (tonConnectConfig) {
-            this.connectors.set('tonConnect', new TonConnectConnector(tonConnectConfig));
+        if (configuredTonConnectConfig) {
+            this.connectors.set('tonConnect', new TonConnectConnector(configuredTonConnectConfig));
         }
         // Only add WalletConnect connector if config is provided
-        if (walletConnectConfig) {
-            this.connectors.set('walletConnect', new WalletConnectConnector(walletConnectConfig, this.networkRpcMap));
+        if (configuredWalletConnectConfig) {
+            this.connectors.set('walletConnect', new WalletConnectConnector(configuredWalletConnectConfig, this.networkRpcMap));
         }
         this.sessionManager = new SessionManager();
         this.eventManager = new EventManager();
-        this.connectionService = new ConnectionService(networks, this.wallets, this.sessionManager, this.connectors, usingIntegratedBrowser, this.eventManager);
-        this.networkSwitchService = new NetworkSwitchService(networks, this.sessionManager, this.connectors, usingIntegratedBrowser, this.eventManager);
+        this.connectionService = new ConnectionService(networks, this.wallets, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager);
+        this.networkSwitchService = new NetworkSwitchService(networks, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager);
         this.signatureService = new SignatureService(this.sessionManager, this.connectors);
         this.transactionService = new TransactionService(this.sessionManager, this.connectors);
         this.walletCapabilitiesService = new WalletCapabilitiesService(networks, this.connectors, this.sessionManager, this.eventManager);
+        // Register as the shared instance so getInstance() works
+        // (only set if no instance exists, to avoid overwriting an earlier one)
+        if (!UniversalWalletConnector.instance) {
+            UniversalWalletConnector.instance = this;
+        }
         // Initialize detected wallets after services are created
         this.initializeDetectedWallets();
     }
@@ -87,153 +141,136 @@ export class UniversalWalletConnector {
                     });
                 }
             });
-            // Check available wallets for each namespace across all connectors
+            // Run every namespace × connector detection concurrently.
+            // The namespace loop used to be sequential and `await`-ed each call,
+            // which meant a 100ms EIP-6963 native timeout + any bridge polling
+            // added up. With Promise.all the total time is the slowest single
+            // call, not the sum.
+            const detectionTasks = [];
             for (const namespace of namespaces) {
                 for (const [, connector] of this.connectors) {
-                    // Check if connector supports getAvailableWallets
-                    if (typeof connector.getAvailableWallets === 'function') {
-                        try {
-                            const detectedWallets = await connector.getAvailableWallets(namespace, this.wallets);
-                            // Update wallets with detected information
-                            detectedWallets.forEach(detected => {
-                                // Find matching wallet based on namespace-specific naming
-                                let wallet;
-                                if (namespace === 'eip155') {
-                                    // For EIP155, match by eip155Name
-                                    wallet = this.wallets.find(w => {
-                                        const provider = this.usingIntegratedBrowser
-                                            ? w.integratedBrowserInjectedProvider
-                                            : w.extensionInjectedProvider;
-                                        return (provider?.namespaceMetaData?.eip155?.eip155Name?.toLowerCase() ===
-                                            detected.name.toLowerCase());
-                                    });
-                                }
-                                else if (namespace === 'solana') {
-                                    // For Solana, match by walletStandardName
-                                    wallet = this.wallets.find(w => {
-                                        const provider = this.usingIntegratedBrowser
-                                            ? w.integratedBrowserInjectedProvider
-                                            : w.extensionInjectedProvider;
-                                        return (provider?.namespaceMetaData?.solana?.walletStandardName?.toLowerCase() ===
-                                            detected.name.toLowerCase());
-                                    });
-                                }
-                                else if (namespace === 'tron') {
-                                    // Two id schemes can appear here:
-                                    //  - Mesh-owned TronConnector: uuid === WalletMetadata.id
-                                    //    (a stable TronWalletId like 'tronlink').
-                                    //  - Legacy window-global discovery: uuid === `tron-${injectedId}`
-                                    //    (e.g. 'tron-tronlink'), derived from the injection path.
-                                    const tronDetected = detected;
-                                    wallet = this.wallets.find(w => {
-                                        if (tronDetected.uuid === w.id)
-                                            return true;
-                                        const provider = this.usingIntegratedBrowser
-                                            ? w.integratedBrowserInjectedProvider
-                                            : w.extensionInjectedProvider;
-                                        const injectedId = provider?.namespaceMetaData?.tron?.injectedId;
-                                        if (!injectedId)
-                                            return false;
-                                        // Mesh-owned connector reports the canonical injectedId —
-                                        // match it directly so catalog-driven wallets (whose `id`
-                                        // is a backend GUID, not a TronWalletId) are recognized.
-                                        if (tronDetected.injectedId &&
-                                            injectedId.toLowerCase() ===
-                                                tronDetected.injectedId.toLowerCase()) {
-                                            return true;
-                                        }
-                                        // Legacy window-global discovery scheme: `tron-${injectedId}`.
-                                        return (tronDetected.uuid ===
-                                            `tron-${injectedId}`.toLowerCase().replace(/\./g, '-'));
-                                    });
-                                }
-                                else if (namespace === 'tvm') {
-                                    // For TON, match by jsBridgeKey
-                                    const tonDetected = detected;
-                                    wallet = this.wallets.find(w => {
-                                        const provider = this.usingIntegratedBrowser
-                                            ? w.integratedBrowserInjectedProvider
-                                            : w.extensionInjectedProvider;
-                                        return (provider?.namespaceMetaData?.tvm?.jsBridgeKey ===
-                                            tonDetected.jsBridgeKey);
-                                    });
-                                }
-                                else {
-                                    // For other namespaces, fall back to wallet name
-                                    wallet = this.wallets.find(w => w.name.toLowerCase() === detected.name.toLowerCase());
-                                }
-                                if (wallet) {
-                                    // Determine which provider to update based on usingIntegratedBrowser
-                                    const provider = this.usingIntegratedBrowser
-                                        ? wallet.integratedBrowserInjectedProvider
-                                        : wallet.extensionInjectedProvider;
-                                    // Update the appropriate namespace metadata
-                                    if (provider?.namespaceMetaData) {
-                                        const nsMetadata = provider.namespaceMetaData[namespace];
-                                        if (nsMetadata && namespace === 'eip155') {
-                                            // For EIP155, we have specific fields
-                                            const eip155Metadata = nsMetadata;
-                                            eip155Metadata.installed = true;
-                                            const eip155Detected = detected;
-                                            eip155Metadata.detectedWallet = {
-                                                uuid: eip155Detected.uuid,
-                                                name: eip155Detected.name,
-                                                icon: eip155Detected.icon,
-                                                rdns: eip155Detected.rdns
-                                            };
-                                        }
-                                        else if (namespace === 'solana') {
-                                            // For Solana, we have different fields
-                                            const solanaMetadata = nsMetadata;
-                                            solanaMetadata.installed = true;
-                                            const solanaDetected = detected;
-                                            solanaMetadata.detectedWallet = {
-                                                uuid: solanaDetected.uuid,
-                                                name: solanaDetected.name,
-                                                features: solanaDetected.features
-                                            };
-                                        }
-                                        else if (namespace === 'tron') {
-                                            const tronMetadata = nsMetadata;
-                                            tronMetadata.installed = true;
-                                            const tronDetected = detected;
-                                            tronMetadata.detectedWallet = {
-                                                uuid: tronDetected.uuid,
-                                                name: tronDetected.name
-                                            };
-                                        }
-                                        else if (namespace === 'tvm') {
-                                            const tonMetadata = nsMetadata;
-                                            tonMetadata.installed = true;
-                                            const tonDetected = detected;
-                                            tonMetadata.detectedWallet = {
-                                                uuid: tonDetected.uuid,
-                                                name: tonDetected.name,
-                                                icon: tonDetected.icon,
-                                                jsBridgeKey: tonDetected.jsBridgeKey
-                                            };
-                                        }
-                                    }
-                                }
-                            });
-                        }
-                        catch {
-                            // Silently handle errors for individual connector/namespace combinations
+                    if (typeof connector.getAvailableWallets !== 'function')
+                        continue;
+                    detectionTasks.push(Promise.resolve()
+                        .then(() => connector.getAvailableWallets(namespace, this.wallets))
+                        .then(detected => {
+                        for (const d of detected) {
+                            this.applyDetectedWallet(namespace, d);
                         }
-                    }
+                    })
+                        .catch(() => {
+                        // Silently handle errors for individual connector/namespace combinations
+                    }));
                 }
             }
+            await Promise.all(detectionTasks);
             // Notify the connection service to update its internal wallets reference
             this.connectionService.updateWallets(this.wallets);
             // Mark detection as complete
             this.detectionComplete = true;
-            // Notify listeners about the update
-            this.eventManager.notify();
+            this.eventManager.emit('walletsDetected', { wallets: this.wallets });
+            this.eventManager.emit('ready', undefined);
         }
-        catch {
-            // Silently handle error during initialization
+        catch (error) {
             this.detectionComplete = true;
-            this.eventManager.notify();
+            this.emitError(error, 'initialize');
+            this.eventManager.emit('ready', undefined);
+        }
+    }
+    /**
+     * Merge a single detected wallet (from one namespace × connector run) into
+     * the configured wallet metadata. Factored out so detection tasks can run
+     * in parallel without racing on the merge logic.
+     */
+    applyDetectedWallet(namespace, detected) {
+        let wallet;
+        const pickProvider = (w) => this.usingIntegratedBrowser
+            ? w.integratedBrowserInjectedProvider
+            : w.extensionInjectedProvider;
+        if (namespace === 'eip155') {
+            wallet = this.wallets.find(w => pickProvider(w)?.namespaceMetaData?.eip155?.eip155Name?.toLowerCase() ===
+                detected.name.toLowerCase());
+        }
+        else if (namespace === 'solana') {
+            wallet = this.wallets.find(w => pickProvider(w)?.namespaceMetaData?.solana?.walletStandardName?.toLowerCase() ===
+                detected.name.toLowerCase());
+        }
+        else if (namespace === 'tron') {
+            // Three id schemes can appear here:
+            //  - Mesh-owned TronConnector reports the canonical `injectedId` directly
+            //    (added in #174) — match catalog wallets whose `id` is a backend GUID.
+            //  - Mesh-owned TronConnector: uuid === WalletMetadata.id
+            //    (a stable TronWalletId like 'tronlink').
+            //  - Legacy window-global discovery: uuid === `tron-${injectedId}`
+            //    (e.g. 'tron-tronlink'), derived from the injection path.
+            const tronDetected = detected;
+            wallet = this.wallets.find(w => {
+                if (tronDetected.uuid === w.id)
+                    return true;
+                const injectedId = pickProvider(w)?.namespaceMetaData?.tron?.injectedId;
+                if (!injectedId)
+                    return false;
+                if (tronDetected.injectedId &&
+                    injectedId.toLowerCase() === tronDetected.injectedId.toLowerCase()) {
+                    return true;
+                }
+                return (tronDetected.uuid ===
+                    `tron-${injectedId}`.toLowerCase().replace(/\./g, '-'));
+            });
+        }
+        else if (namespace === 'tvm') {
+            const tonDetected = detected;
+            wallet = this.wallets.find(w => pickProvider(w)?.namespaceMetaData?.tvm?.jsBridgeKey ===
+                tonDetected.jsBridgeKey);
+        }
+        else {
+            wallet = this.wallets.find(w => w.name.toLowerCase() === detected.name.toLowerCase());
+        }
+        if (!wallet)
+            return;
+        const provider = pickProvider(wallet);
+        if (!provider?.namespaceMetaData)
+            return;
+        const nsMetadata = provider.namespaceMetaData[namespace];
+        if (!nsMetadata)
+            return;
+        if (namespace === 'eip155') {
+            const m = nsMetadata;
+            const d = detected;
+            m.installed = true;
+            m.detectedWallet = {
+                uuid: d.uuid,
+                name: d.name,
+                icon: d.icon,
+                rdns: d.rdns
+            };
+        }
+        else if (namespace === 'solana') {
+            const m = nsMetadata;
+            const d = detected;
+            m.installed = true;
+            m.detectedWallet = {
+                uuid: d.uuid,
+                name: d.name,
+                features: d.features
+            };
+        }
+        else if (namespace === 'tron') {
+            const m = nsMetadata;
+            const d = detected;
+            m.installed = true;
+            m.detectedWallet = { uuid: d.uuid, name: d.name };
+        }
+        else if (namespace === 'tvm') {
+            const m = nsMetadata;
+            const d = detected;
+            m.installed = true;
+            m.detectedWallet = {
+                uuid: d.uuid,
+                name: d.name,
+                icon: d.icon,
+                jsBridgeKey: d.jsBridgeKey
+            };
         }
     }
     getSession() {
@@ -242,6 +279,22 @@ export class UniversalWalletConnector {
     isReady() {
         return this.detectionComplete;
     }
+    // ---- Event subscription ----
+    /** Subscribe to a typed event. Returns an unsubscribe function. */
+    on(event, listener) {
+        return this.eventManager.on(event, listener);
+    }
+    /** Subscribe once; the listener is removed after the first dispatch. */
+    once(event, listener) {
+        return this.eventManager.once(event, listener);
+    }
+    off(event, listener) {
+        this.eventManager.off(event, listener);
+    }
+    /**
+     * @deprecated Prefer `on(eventName, listener)` for targeted updates.
+     * Subscribes to the catch-all `change` event.
+     */
     subscribe(listener) {
         return this.eventManager.subscribe(listener);
     }
@@ -256,20 +309,35 @@ export class UniversalWalletConnector {
     getNetworks() {
         return this.connectionService.getNetworks();
     }
-    async connect(connectionMode, walletId, networkId) {
-        await this.connectionService.connect(connectionMode, walletId, networkId);
-        this.eventManager.notify();
+    async connect(connectionMode, walletId, networkId, options) {
+        try {
+            await this.connectionService.connect(connectionMode, walletId, networkId, options);
+        }
+        catch (error) {
+            this.emitError(error, 'connect');
+            throw error;
+        }
     }
     getConnectionURI() {
         return this.connectionService.getConnectionURI();
     }
-    async disconnect() {
-        await this.connectionService.disconnect();
-        this.eventManager.notify();
+    async disconnect(options) {
+        try {
+            await this.connectionService.disconnect(options);
+        }
+        catch (error) {
+            this.emitError(error, 'disconnect');
+            throw error;
+        }
     }
-    async switchNetwork(networkId) {
-        await this.networkSwitchService.switchNetwork(networkId);
-        this.eventManager.notify();
+    async switchNetwork(networkId, options) {
+        try {
+            await this.networkSwitchService.switchNetwork(networkId, options);
+        }
+        catch (error) {
+            this.emitError(error, 'switchNetwork');
+            throw error;
+        }
     }
     getNetworkSwitchLoadingState() {
         return this.networkSwitchService.getLoadingState();
@@ -277,9 +345,10 @@ export class UniversalWalletConnector {
     /**
      * Sign a message with the connected wallet
      * @param message The message to sign
+     * @param options Optional cancellation signal
      * @returns A promise that resolves to the signature
      */
-    async signMessage(message) {
+    async signMessage(message, options) {
         const session = this.sessionManager.getSession();
         if (!session.activeWallet) {
             throw new Error('No active wallet');
@@ -287,23 +356,29 @@ export class UniversalWalletConnector {
         if (!session.connectionMode) {
             throw new Error('No active connection');
         }
-        // Get the provider from the active wallet based on connection mode
-        let provider;
-        if (session.connectionMode === 'injected') {
-            provider = this.usingIntegratedBrowser
-                ? session.activeWallet.integratedBrowserInjectedProvider
-                : session.activeWallet.extensionInjectedProvider;
-        }
-        else if (session.connectionMode === 'walletConnect') {
-            provider = session.activeWallet.walletConnectProvider;
-        }
-        else if (session.connectionMode === 'tonConnect') {
-            return await this.signatureService.signMessage(message);
+        try {
+            // Get the provider from the active wallet based on connection mode
+            let provider;
+            if (session.connectionMode === 'injected') {
+                provider = this.usingIntegratedBrowser
+                    ? session.activeWallet.integratedBrowserInjectedProvider
+                    : session.activeWallet.extensionInjectedProvider;
+            }
+            else if (session.connectionMode === 'walletConnect') {
+                provider = session.activeWallet.walletConnectProvider;
+            }
+            else if (session.connectionMode === 'tonConnect') {
+                return await this.signatureService.signMessage(message, undefined, options);
+            }
+            if (!provider) {
+                throw new Error('No provider available for the active wallet');
+            }
+            return await this.signatureService.signMessage(message, provider, options);
         }
-        if (!provider) {
-            throw new Error('No provider available for the active wallet');
+        catch (error) {
+            this.emitError(error, 'signMessage');
+            throw error;
         }
-        return await this.signatureService.signMessage(message, provider);
     }
     /**
      * Sign EIP-712 typed structured data (eth_signTypedData_v4).
@@ -340,9 +415,10 @@ export class UniversalWalletConnector {
     /**
      * Send a transaction with the connected wallet
      * @param request The transaction request parameters
+     * @param options Optional cancellation signal
      * @returns A promise that resolves to the transaction result
      */
-    async sendTransaction(request) {
+    async sendTransaction(request, options) {
         const session = this.sessionManager.getSession();
         if (!session.activeWallet) {
             throw new Error('No active wallet');
@@ -350,23 +426,29 @@ export class UniversalWalletConnector {
         if (!session.connectionMode) {
             throw new Error('No active connection');
         }
-        // Get the provider from the active wallet based on connection mode
-        let provider;
-        if (session.connectionMode === 'injected') {
-            provider = this.usingIntegratedBrowser
-                ? session.activeWallet.integratedBrowserInjectedProvider
-                : session.activeWallet.extensionInjectedProvider;
-        }
-        else if (session.connectionMode === 'walletConnect') {
-            provider = session.activeWallet.walletConnectProvider;
-        }
-        else if (session.connectionMode === 'tonConnect') {
-            return await this.transactionService.sendTransaction(request);
+        try {
+            // Get the provider from the active wallet based on connection mode
+            let provider;
+            if (session.connectionMode === 'injected') {
+                provider = this.usingIntegratedBrowser
+                    ? session.activeWallet.integratedBrowserInjectedProvider
+                    : session.activeWallet.extensionInjectedProvider;
+            }
+            else if (session.connectionMode === 'walletConnect') {
+                provider = session.activeWallet.walletConnectProvider;
+            }
+            else if (session.connectionMode === 'tonConnect') {
+                return await this.transactionService.sendTransaction(request, undefined, options);
+            }
+            if (!provider) {
+                throw new Error('No provider available for the active wallet');
+            }
+            return await this.transactionService.sendTransaction(request, provider, options);
         }
-        if (!provider) {
-            throw new Error('No provider available for the active wallet');
+        catch (error) {
+            this.emitError(error, 'sendTransaction');
+            throw error;
         }
-        return await this.transactionService.sendTransaction(request, provider);
     }
     /**
      * Sign a Solana tx without broadcasting (raw bytes in/out, no @solana/web3.js
@@ -392,10 +474,17 @@ export class UniversalWalletConnector {
      * Fetch wallet capabilities for the connected wallet
      * @param address The wallet address to fetch capabilities for
      * @param activeNetwork Optional network to set as the active network for capabilities
+     * @param options Optional cancellation signal
      * @returns A promise that resolves when capabilities are fetched and updated
      */
-    async getWalletCapabilities(address, activeNetwork) {
-        return await this.walletCapabilitiesService.getWalletCapabilities(address, activeNetwork);
+    async getWalletCapabilities(address, activeNetwork, options) {
+        try {
+            return await this.walletCapabilitiesService.getWalletCapabilities(address, activeNetwork, options);
+        }
+        catch (error) {
+            this.emitError(error, 'getWalletCapabilities');
+            throw error;
+        }
     }
     /**
      * Check if a connection mode is available for a specific wallet
@@ -439,5 +528,21 @@ export class UniversalWalletConnector {
         const session = this.sessionManager.getSession();
         return session.activeWalletCapabilities;
     }
+    // ---- private helpers ----
+    emitError(error, operation) {
+        // Intentional cancellations (AbortSignal.throwIfAborted, fetch abort,
+        // DOMException) should NOT surface as wallet errors — the caller already
+        // knows it asked to abort. Skip emission so error telemetry stays clean.
+        if (error instanceof Error && error.name === 'AbortError') {
+            return;
+        }
+        const walletError = error instanceof WalletConnectorError
+            ? { type: error.type, message: error.message }
+            : {
+                type: 'unknown',
+                message: error instanceof Error ? error.message : String(error)
+            };
+        this.eventManager.emit('error', { error: walletError, operation });
+    }
 }
 //# sourceMappingURL=universal-wallet-connector.js.map