@meshconnect/uwc-core 0.7.4 → 0.7.5-snapshot.3e19fe0

package/src/services/wallet-capabilities-service.ts

@@ -6,6 +6,7 @@ import type {
 } from '@meshconnect/uwc-types'
 import type { SessionManager } from '../managers/session-manager'
 import type { EventManager } from '../managers/event-manager'
+import type { ServiceOptions } from './connection-service'
 
 export class WalletCapabilitiesService {
   constructor(
@@ -17,8 +18,11 @@ export class WalletCapabilitiesService {
 
   async getWalletCapabilities(
     address: string,
-    activeNetwork?: Network
+    activeNetwork?: Network,
+    options?: ServiceOptions
   ): Promise<void> {
+    options?.signal?.throwIfAborted()
+
     let activeWalletCapabilities: Record<string, EVMCapabilities> = {}
     let activeNetworkWalletCapabilities: EVMCapabilities = {}
 
@@ -49,6 +53,8 @@ export class WalletCapabilitiesService {
         capabilities = {}
       }
 
+      options?.signal?.throwIfAborted()
+
       // keep only supported networks
       activeWalletCapabilities = Object.fromEntries(
         Object.entries(capabilities).filter(([networkId, _]) =>
@@ -71,7 +77,13 @@ export class WalletCapabilitiesService {
           activeNetworkWalletCapabilities: null
         })
       }
-      this.eventManager.notify()
+
+      this.eventManager.emit('capabilitiesUpdated', {
+        capabilities: activeWalletCapabilities
+      })
+      this.eventManager.emit('sessionChanged', {
+        session: this.sessionManager.getSession()
+      })
     }
   }
 }

package/src/universal-wallet-connector.test.ts

@@ -29,7 +29,11 @@ const mockSessionManager = {
 
 const mockEventManager = {
   subscribe: vi.fn().mockReturnValue(() => {}),
-  notify: vi.fn()
+  notify: vi.fn(),
+  emit: vi.fn(),
+  on: vi.fn().mockReturnValue(() => {}),
+  off: vi.fn(),
+  once: vi.fn().mockReturnValue(() => {})
 }
 
 const mockConnectionService = {
@@ -117,8 +121,7 @@ describe('UniversalWalletConnector', () => {
   let mockWalletConnectConfig: WalletConnectConfig
 
   beforeEach(() => {
-    ;(UniversalWalletConnector as any).instanceCount = 0
-    ;(UniversalWalletConnector as any).hasWarnedAboutMultipleInstances = false
+    UniversalWalletConnector.resetInstance()
 
     mockNetworks = [
       {
@@ -402,6 +405,87 @@ describe('UniversalWalletConnector', () => {
       expect(typeof connector.sendTransaction).toBe('function')
       expect(typeof connector.isConnectionModeAvailable).toBe('function')
       expect(typeof connector.getActiveWalletCapabilities).toBe('function')
+      expect(typeof connector.on).toBe('function')
+      expect(typeof connector.once).toBe('function')
+      expect(typeof connector.off).toBe('function')
+    })
+  })
+
+  describe('getInstance singleton factory', () => {
+    it('creates an instance on first call and reuses it afterwards', () => {
+      const a = UniversalWalletConnector.getInstance({
+        networks: mockNetworks,
+        wallets: mockWallets
+      })
+      const b = UniversalWalletConnector.getInstance({
+        networks: mockNetworks,
+        wallets: mockWallets
+      })
+      expect(a).toBe(b)
+    })
+
+    it('throws when called before any instance exists and no config is given', () => {
+      expect(() => UniversalWalletConnector.getInstance()).toThrow(
+        /getInstance.*before an instance existed/
+      )
+    })
+
+    it('resetInstance() clears the shared reference', () => {
+      const first = UniversalWalletConnector.getInstance({
+        networks: mockNetworks,
+        wallets: mockWallets
+      })
+      UniversalWalletConnector.resetInstance()
+      const second = UniversalWalletConnector.getInstance({
+        networks: mockNetworks,
+        wallets: mockWallets
+      })
+      expect(second).not.toBe(first)
+    })
+
+    it('adopts a `new`-constructed instance as the singleton', () => {
+      const created = new UniversalWalletConnector(mockNetworks, mockWallets)
+      expect(UniversalWalletConnector.getInstance()).toBe(created)
+    })
+  })
+
+  describe('config-object constructor', () => {
+    it('accepts the { networks, wallets, ... } form', () => {
+      const connector = new UniversalWalletConnector({
+        networks: mockNetworks,
+        wallets: mockWallets,
+        walletConnectConfig: mockWalletConnectConfig
+      })
+      expect(connector).toBeInstanceOf(UniversalWalletConnector)
+    })
+  })
+
+  describe('AbortSignal support', () => {
+    it('connect rejects immediately when signal is already aborted', async () => {
+      const connector = new UniversalWalletConnector(mockNetworks, mockWallets)
+      const controller = new AbortController()
+      controller.abort()
+
+      // ConnectionService.connect is mocked to return undefined by default,
+      // so the abort check is what surfaces the error.
+      mockConnectionService.connect = vi.fn().mockImplementation(
+        async (
+          _m: unknown,
+          _w: unknown,
+          _n: unknown,
+          options?: {
+            signal?: AbortSignal
+          }
+        ) => {
+          options?.signal?.throwIfAborted()
+        }
+      )
+
+      await expect(
+        connector.connect('injected', 'metamask', undefined, {
+          signal: controller.signal
+        })
+      ).rejects.toThrow()
     })
   })
 

package/src/universal-wallet-connector.ts

@@ -16,8 +16,10 @@ import type {
   TransactionResult,
   NetworkRpcMap,
   EVMCapabilities,
-  SignatureType
+  SignatureType,
+  WalletError
 } from '@meshconnect/uwc-types'
+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'
@@ -29,8 +31,28 @@ import { SignatureService } from './services/signature-service'
 import { TransactionService } from './services/transaction-service'
 import { WalletCapabilitiesService } from './services/wallet-capabilities-service'
 import { createNetworkRpcMap } from './utils/network-rpc-utils'
+import type { UWCEventName, UWCEventListener, UWCOperation } from './events'
+
+/**
+ * Configuration object form of the UniversalWalletConnector constructor.
+ * Prefer this over the positional constructor in new code.
+ */
+export interface UWCConfig {
+  networks: Network[]
+  wallets?: WalletMetadata[]
+  usingIntegratedBrowser?: boolean
+  walletConnectConfig?: WalletConnectConfig
+  tonConnectConfig?: TonConnectConfig
+}
+
+/** Common options for user-initiated async operations. */
+export interface OperationOptions {
+  /** Abort the operation if the signal fires. State mutations are skipped after abort. */
+  signal?: AbortSignal
+}
 
 export class UniversalWalletConnector {
+  private static instance: UniversalWalletConnector | null = null
   private static instanceCount = 0
   private static hasWarnedAboutMultipleInstances = false
 
@@ -48,17 +70,78 @@ export class UniversalWalletConnector {
   private detectionComplete = false
   private networkRpcMap: NetworkRpcMap
 
+  /**
+   * 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?: UWCConfig): UniversalWalletConnector {
+    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(): void {
+    UniversalWalletConnector.instance = null
+    UniversalWalletConnector.instanceCount = 0
+    UniversalWalletConnector.hasWarnedAboutMultipleInstances = false
+  }
+
+  constructor(config: UWCConfig)
   constructor(
     networks: Network[],
+    wallets?: WalletMetadata[],
+    usingIntegratedBrowser?: boolean,
+    walletConnectConfig?: WalletConnectConfig,
+    tonConnectConfig?: TonConnectConfig
+  )
+  constructor(
+    networksOrConfig: Network[] | UWCConfig,
     wallets: WalletMetadata[] = [],
     usingIntegratedBrowser = false,
     walletConnectConfig?: WalletConnectConfig,
     tonConnectConfig?: TonConnectConfig
   ) {
-    // Track instance creation
-    UniversalWalletConnector.instanceCount++
+    if (!networksOrConfig) {
+      throw new Error(
+        'Universal Wallet Connector must be initialized with at least one network'
+      )
+    }
+
+    let config: UWCConfig
+    if (Array.isArray(networksOrConfig)) {
+      config = {
+        networks: networksOrConfig,
+        wallets,
+        usingIntegratedBrowser
+      }
+      if (walletConnectConfig) {
+        config.walletConnectConfig = walletConnectConfig
+      }
+      if (tonConnectConfig) {
+        config.tonConnectConfig = tonConnectConfig
+      }
+    } else {
+      config = networksOrConfig
+    }
+
+    const {
+      networks,
+      wallets: configuredWallets = [],
+      usingIntegratedBrowser: configuredUsingIntegratedBrowser = false,
+      walletConnectConfig: configuredWalletConnectConfig,
+      tonConnectConfig: configuredTonConnectConfig
+    } = config
 
-    // Warn about multiple instances
+    // Track instance creation and warn on duplicates
+    UniversalWalletConnector.instanceCount++
     if (
       UniversalWalletConnector.instanceCount > 1 &&
       !UniversalWalletConnector.hasWarnedAboutMultipleInstances
@@ -68,7 +151,7 @@ export class UniversalWalletConnector {
         `⚠️ 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
@@ -79,14 +162,14 @@ export class UniversalWalletConnector {
         'Universal Wallet Connector must be initialized with at least one network'
       )
     }
-    if (!wallets) {
+    if (!configuredWallets) {
       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)
@@ -96,22 +179,25 @@ export class UniversalWalletConnector {
     this.injectedConnector = new InjectedConnector(
       this.networkRpcMap,
       this.wallets,
-      tonConnectConfig
+      configuredTonConnectConfig
     )
     this.connectors.set('injected', this.injectedConnector)
 
-    if (tonConnectConfig) {
+    if (configuredTonConnectConfig) {
       this.connectors.set(
         'tonConnect',
-        new TonConnectConnector(tonConnectConfig)
+        new TonConnectConnector(configuredTonConnectConfig)
       )
     }
 
     // Only add WalletConnect connector if config is provided
-    if (walletConnectConfig) {
+    if (configuredWalletConnectConfig) {
       this.connectors.set(
         'walletConnect',
-        new WalletConnectConnector(walletConnectConfig, this.networkRpcMap)
+        new WalletConnectConnector(
+          configuredWalletConnectConfig,
+          this.networkRpcMap
+        )
       )
     }
 
@@ -122,14 +208,14 @@ export class UniversalWalletConnector {
       this.wallets,
       this.sessionManager,
       this.connectors,
-      usingIntegratedBrowser,
+      configuredUsingIntegratedBrowser,
       this.eventManager
     )
     this.networkSwitchService = new NetworkSwitchService(
       networks,
       this.sessionManager,
       this.connectors,
-      usingIntegratedBrowser,
+      configuredUsingIntegratedBrowser,
       this.eventManager
     )
     this.signatureService = new SignatureService(
@@ -147,6 +233,12 @@ export class UniversalWalletConnector {
       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()
   }
@@ -323,12 +415,12 @@ export class UniversalWalletConnector {
       // Mark detection as complete
       this.detectionComplete = true
 
-      // Notify listeners about the update
-      this.eventManager.notify()
-    } catch {
-      // Silently handle error during initialization
+      this.eventManager.emit('walletsDetected', { wallets: this.wallets })
+      this.eventManager.emit('ready', undefined)
+    } catch (error) {
       this.detectionComplete = true
-      this.eventManager.notify()
+      this.emitError(error, 'initialize')
+      this.eventManager.emit('ready', undefined)
     }
   }
 
@@ -340,6 +432,32 @@ export class UniversalWalletConnector {
     return this.detectionComplete
   }
 
+  // ---- Event subscription ----
+
+  /** Subscribe to a typed event. Returns an unsubscribe function. */
+  on<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    return this.eventManager.on(event, listener)
+  }
+
+  /** Subscribe once; the listener is removed after the first dispatch. */
+  once<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    return this.eventManager.once(event, listener)
+  }
+
+  off<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): void {
+    this.eventManager.off(event, listener)
+  }
+
+  /**
+   * @deprecated Prefer `on(eventName, listener)` for targeted updates.
+   * Subscribes to the catch-all `change` event.
+   */
   subscribe(listener: () => void): () => void {
     return this.eventManager.subscribe(listener)
   }
@@ -361,24 +479,45 @@ export class UniversalWalletConnector {
   async connect(
     connectionMode: ConnectionMode,
     walletId: string,
-    networkId?: NetworkId
+    networkId?: NetworkId,
+    options?: OperationOptions
   ): Promise<void> {
-    await this.connectionService.connect(connectionMode, walletId, networkId)
-    this.eventManager.notify()
+    try {
+      await this.connectionService.connect(
+        connectionMode,
+        walletId,
+        networkId,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'connect')
+      throw error
+    }
   }
 
   getConnectionURI(): string | undefined {
     return this.connectionService.getConnectionURI()
   }
 
-  async disconnect(): Promise<void> {
-    await this.connectionService.disconnect()
-    this.eventManager.notify()
+  async disconnect(options?: OperationOptions): Promise<void> {
+    try {
+      await this.connectionService.disconnect(options)
+    } catch (error) {
+      this.emitError(error, 'disconnect')
+      throw error
+    }
   }
 
-  async switchNetwork(networkId: NetworkId): Promise<void> {
-    await this.networkSwitchService.switchNetwork(networkId)
-    this.eventManager.notify()
+  async switchNetwork(
+    networkId: NetworkId,
+    options?: OperationOptions
+  ): Promise<void> {
+    try {
+      await this.networkSwitchService.switchNetwork(networkId, options)
+    } catch (error) {
+      this.emitError(error, 'switchNetwork')
+      throw error
+    }
   }
 
   getNetworkSwitchLoadingState() {
@@ -388,9 +527,13 @@ 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: string): Promise<SignatureType> {
+  async signMessage(
+    message: string,
+    options?: OperationOptions
+  ): Promise<SignatureType> {
     const session = this.sessionManager.getSession()
 
     if (!session.activeWallet) {
@@ -401,32 +544,43 @@ export class UniversalWalletConnector {
       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')
-    }
+      if (!provider) {
+        throw new Error('No provider available for the active wallet')
+      }
 
-    return await this.signatureService.signMessage(message, provider)
+      return await this.signatureService.signMessage(message, provider, options)
+    } catch (error) {
+      this.emitError(error, 'signMessage')
+      throw error
+    }
   }
 
   /**
    * 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: TransactionRequest
+    request: TransactionRequest,
+    options?: OperationOptions
   ): Promise<TransactionResult> {
     const session = this.sessionManager.getSession()
 
@@ -438,39 +592,60 @@ export class UniversalWalletConnector {
       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')
-    }
+      if (!provider) {
+        throw new Error('No provider available for the active wallet')
+      }
 
-    return await this.transactionService.sendTransaction(request, provider)
+      return await this.transactionService.sendTransaction(
+        request,
+        provider,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'sendTransaction')
+      throw error
+    }
   }
 
   /**
    * 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: string,
-    activeNetwork?: Network
+    activeNetwork?: Network,
+    options?: OperationOptions
   ): Promise<void> {
-    return await this.walletCapabilitiesService.getWalletCapabilities(
-      address,
-      activeNetwork
-    )
+    try {
+      return await this.walletCapabilitiesService.getWalletCapabilities(
+        address,
+        activeNetwork,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'getWalletCapabilities')
+      throw error
+    }
   }
 
   /**
@@ -532,4 +707,17 @@ export class UniversalWalletConnector {
     const session = this.sessionManager.getSession()
     return session.activeWalletCapabilities
   }
+
+  // ---- private helpers ----
+
+  private emitError(error: unknown, operation: UWCOperation): void {
+    const walletError: 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 })
+  }
 }