@meshconnect/uwc-core 0.9.0 → 0.9.1-snapshot.95b8dbe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-core",
-  "version": "0.9.0",
+  "version": "0.9.1-snapshot.95b8dbe",
   "description": "Core functionality for Universal Wallet Connector",
   "type": "module",
   "main": "dist/index.js",
@@ -16,10 +16,10 @@
     "src"
   ],
   "dependencies": {
-    "@meshconnect/uwc-injected-connector": "0.13.0",
-    "@meshconnect/uwc-ton-connector": "0.6.3",
-    "@meshconnect/uwc-types": "0.15.0",
-    "@meshconnect/uwc-wallet-connect-connector": "0.6.0"
+    "@meshconnect/uwc-injected-connector": "0.14.0-snapshot.95b8dbe",
+    "@meshconnect/uwc-ton-connector": "0.6.3-snapshot.95b8dbe",
+    "@meshconnect/uwc-wallet-connect-connector": "0.6.0-snapshot.95b8dbe",
+    "@meshconnect/uwc-types": "0.15.0-snapshot.95b8dbe"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/events.ts

@@ -0,0 +1,73 @@
+import type {
+  Session,
+  Network,
+  WalletMetadata,
+  ConnectionMode,
+  WalletError,
+  EVMCapabilities
+} from '@meshconnect/uwc-types'
+
+/**
+ * User-initiated operations that can surface through the `error` event.
+ */
+export type UWCOperation =
+  | 'connect'
+  | 'disconnect'
+  | 'switchNetwork'
+  | 'signMessage'
+  | 'sendTransaction'
+  | 'getWalletCapabilities'
+  | 'initialize'
+
+/**
+ * Typed event map emitted by UniversalWalletConnector.
+ *
+ * Subscribe with `on(event, listener)` to react to a single kind of change
+ * instead of re-reading `getSession()` on every notification.
+ *
+ * Every typed event also triggers the `change` event, so legacy
+ * `subscribe(listener)` callers continue to fire.
+ */
+export interface UWCEventMap {
+  /** Wallet detection finished; `getWallets()` now reflects which are installed. */
+  ready: void
+  /** Emitted once detection finishes, with the final wallet list. */
+  walletsDetected: { wallets: WalletMetadata[] }
+
+  /** `connect()` has started. */
+  connecting: { connectionMode: ConnectionMode; walletId: string }
+  /** `connect()` completed successfully. */
+  connected: { session: Session }
+  /** `disconnect()` completed and the session was cleared. */
+  disconnected: void
+  /**
+   * A pairing URI became available for WalletConnect / TonConnect flows.
+   * Prefer this over polling `getConnectionURI()`.
+   */
+  connectionUri: { uri: string; connectionMode: ConnectionMode }
+
+  /** The active session changed (address, network, capabilities, …). */
+  sessionChanged: { session: Session }
+
+  /** Network switching is in progress. Fires on start and end. */
+  networkSwitching: { isLoading: boolean; isWaitingForUserApproval: boolean }
+  /** Network switch succeeded. */
+  networkSwitched: { network: Network }
+
+  /** Wallet capabilities were refreshed. */
+  capabilitiesUpdated: { capabilities: Record<string, EVMCapabilities> }
+
+  /** A user-initiated operation failed. */
+  error: { error: WalletError; operation: UWCOperation }
+
+  /**
+   * Back-compat catch-all. Fires after every other event above.
+   * New code should prefer the specific events.
+   */
+  change: void
+}
+
+export type UWCEventName = keyof UWCEventMap
+export type UWCEventListener<K extends UWCEventName> = (
+  data: UWCEventMap[K]
+) => void

package/src/index.ts

@@ -1,3 +1,11 @@
-export * from './universal-wallet-connector'
-export * from './managers'
-export * from './services'
+export {
+  UniversalWalletConnector,
+  type UWCConfig,
+  type OperationOptions
+} from './universal-wallet-connector'
+export type {
+  UWCEventMap,
+  UWCEventName,
+  UWCEventListener,
+  UWCOperation
+} from './events'

package/src/managers/event-manager.test.ts

@@ -71,4 +71,74 @@ describe('EventManager', () => {
     eventManager.clearAllListeners()
     expect(eventManager.getListenerCount()).toBe(0)
   })
+
+  describe('typed events', () => {
+    it('dispatches typed event data only to on() listeners of that event', () => {
+      const disconnected: unknown[] = []
+      const networkSwitched: unknown[] = []
+
+      eventManager.on('disconnected', data => disconnected.push(data))
+      eventManager.on('networkSwitched', data => networkSwitched.push(data))
+
+      eventManager.emit('disconnected', undefined)
+
+      expect(disconnected).toHaveLength(1)
+      expect(networkSwitched).toHaveLength(0)
+    })
+
+    it('cascades every typed event to the legacy change channel', () => {
+      let changeCount = 0
+      eventManager.subscribe(() => {
+        changeCount++
+      })
+
+      eventManager.emit('connectionUri', {
+        uri: 'wc://x',
+        connectionMode: 'walletConnect'
+      })
+      eventManager.emit('disconnected', undefined)
+
+      expect(changeCount).toBe(2)
+    })
+
+    it('off() removes a listener from the typed set', () => {
+      const calls: unknown[] = []
+      const listener = (d: unknown) => calls.push(d)
+      eventManager.on('ready', listener)
+      eventManager.off('ready', listener)
+      eventManager.emit('ready', undefined)
+      expect(calls).toHaveLength(0)
+    })
+
+    it('once() removes the listener after a single dispatch', () => {
+      let calls = 0
+      eventManager.once('ready', () => {
+        calls++
+      })
+      eventManager.emit('ready', undefined)
+      eventManager.emit('ready', undefined)
+      expect(calls).toBe(1)
+    })
+
+    it('a throwing listener does not stop other listeners', () => {
+      const calls: string[] = []
+      eventManager.on('ready', () => {
+        throw new Error('boom')
+      })
+      eventManager.on('ready', () => {
+        calls.push('second')
+      })
+      eventManager.emit('ready', undefined)
+      expect(calls).toEqual(['second'])
+    })
+
+    it('emit("change") does not recurse into itself', () => {
+      let count = 0
+      eventManager.on('change', () => {
+        count++
+      })
+      eventManager.emit('change', undefined)
+      expect(count).toBe(1)
+    })
+  })
 })

package/src/managers/event-manager.ts

@@ -1,22 +1,93 @@
-type Listener = () => void
-type Unsubscribe = () => void
+import type { UWCEventMap, UWCEventName, UWCEventListener } from '../events'
 
+type LegacyListener = () => void
+type UntypedListener = (data: unknown) => void
+
+/**
+ * Typed event emitter used by UniversalWalletConnector.
+ *
+ * Each event has its own listener set. Emitting any typed event also
+ * dispatches the legacy `change` event, so `subscribe()` callers keep
+ * receiving a notification on every state change.
+ */
 export class EventManager {
-  private listeners: Set<Listener> = new Set()
+  private listeners: Map<UWCEventName, Set<UntypedListener>> = new Map()
+
+  /** Subscribe to a typed event. Returns an unsubscribe function. */
+  on<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(listener as UntypedListener)
+    return () => this.off(event, listener)
+  }
+
+  /** Subscribe once; the listener is removed after the first dispatch. */
+  once<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    const wrapper: UWCEventListener<K> = data => {
+      this.off(event, wrapper)
+      listener(data)
+    }
+    return this.on(event, wrapper)
+  }
+
+  off<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): void {
+    const set = this.listeners.get(event)
+    set?.delete(listener as UntypedListener)
+  }
+
+  emit<K extends UWCEventName>(event: K, data: UWCEventMap[K]): void {
+    this.dispatch(event, data)
+    if (event !== 'change') {
+      this.dispatch('change', undefined as UWCEventMap['change'])
+    }
+  }
 
-  subscribe(listener: Listener): Unsubscribe {
-    this.listeners.add(listener)
-    return () => {
-      this.listeners.delete(listener)
+  private dispatch<K extends UWCEventName>(
+    event: K,
+    data: UWCEventMap[K]
+  ): void {
+    const set = this.listeners.get(event)
+    if (!set || set.size === 0) return
+    // Clone to guard against mutation during dispatch.
+    for (const listener of [...set]) {
+      try {
+        listener(data)
+      } catch {
+        // A bad listener shouldn't break the rest of the dispatch chain.
+      }
     }
   }
 
+  // ---- legacy API (still used by the React ConnectionProvider) ----
+
+  /**
+   * @deprecated Prefer `on(eventName, listener)` for targeted updates.
+   * Subscribes to the catch-all `change` event.
+   */
+  subscribe(listener: LegacyListener): () => void {
+    return this.on('change', listener)
+  }
+
+  /** @deprecated Prefer `emit(eventName, data)`. Emits `change` with no payload. */
   notify(): void {
-    this.listeners.forEach(listener => listener())
+    this.dispatch('change', undefined as UWCEventMap['change'])
   }
 
   getListenerCount(): number {
-    return this.listeners.size
+    let count = 0
+    for (const set of this.listeners.values()) {
+      count += set.size
+    }
+    return count
   }
 
   clearAllListeners(): void {

package/src/services/connection-service.test.ts

@@ -253,10 +253,12 @@ describe('ConnectionService', () => {
       })
     })
 
-    it('polls for URI and notifies eventManager when available', async () => {
-      vi.useFakeTimers()
+    it('emits connectionUri and change events when URI becomes available', async () => {
+      const uriListener = vi.fn()
+      const changeListener = vi.fn()
+      eventManager.on('connectionUri', uriListener)
+      eventManager.on('change', changeListener)
 
-      const notifySpy = vi.spyOn(eventManager, 'notify')
       let connectResolve: (v: any) => void
 
       tonConnector.connect = vi.fn().mockReturnValue(
@@ -270,7 +272,7 @@ describe('ConnectionService', () => {
       tonConnector.getConnectionURI = vi.fn().mockImplementation(() => {
         uriCallCount++
         if (uriCallCount >= 2) return 'tc://some-uri'
-        return undefined
+        throw new Error('No URI yet')
       })
 
       const connectPromise = connectionService.connect(
@@ -278,22 +280,14 @@ describe('ConnectionService', () => {
         'tonkeeper'
       )
 
-      await vi.advanceTimersByTimeAsync(200)
-
-      // The URI becomes available on the second poll, which should stop polling
-      // and emit the event exactly once.
-      expect(notifySpy).toHaveBeenCalledTimes(1)
-      const uriCallCountAfterDiscovery = vi.mocked(
-        tonConnector.getConnectionURI
-      ).mock.calls.length
-      expect(uriCallCountAfterDiscovery).toBe(2)
+      // Wait for polling to detect URI
+      await new Promise(r => setTimeout(r, 250))
 
-      await vi.advanceTimersByTimeAsync(500)
-
-      expect(notifySpy).toHaveBeenCalledTimes(1)
-      expect(tonConnector.getConnectionURI).toHaveBeenCalledTimes(
-        uriCallCountAfterDiscovery
-      )
+      expect(uriListener).toHaveBeenCalledWith({
+        uri: 'tc://some-uri',
+        connectionMode: 'tonConnect'
+      })
+      expect(changeListener).toHaveBeenCalled()
 
       // Resolve the connection to let the test finish
       connectResolve!({

package/src/services/connection-service.ts

@@ -13,6 +13,10 @@ import type {
 import type { SessionManager } from '../managers/session-manager'
 import type { EventManager } from '../managers/event-manager'
 
+export interface ServiceOptions {
+  signal?: AbortSignal
+}
+
 export class ConnectionService {
   private activeConnector: Connector | null = null
 
@@ -28,8 +32,13 @@ export class ConnectionService {
   async connect(
     connectionMode: ConnectionMode,
     walletId: string,
-    networkId?: NetworkId
+    networkId?: NetworkId,
+    options?: ServiceOptions
   ): Promise<void> {
+    options?.signal?.throwIfAborted()
+
+    this.eventManager.emit('connecting', { connectionMode, walletId })
+
     // Find the wallet
     const wallet = this.findWallet(walletId)
 
@@ -59,7 +68,12 @@ export class ConnectionService {
         connectionMode === 'tonConnect' ||
         connectionMode === 'walletConnect'
       ) {
-        result = await this.connectWithURIPoll(connector, network, provider)
+        result = await this.connectWithURIPoll(
+          connector,
+          network,
+          provider,
+          connectionMode
+        )
       } else {
         throw new Error(`Unsupported connection mode: ${connectionMode}`)
       }
@@ -68,6 +82,9 @@ export class ConnectionService {
       throw error
     }
 
+    // If the caller aborted during the await, bail before mutating session
+    options?.signal?.throwIfAborted()
+
     // Filter available addresses to only include those for configured networks
     const filteredAvailableAddresses = result.availableAddresses.filter(addr =>
       this.networks.some(n => n.id === addr.networkId)
@@ -84,22 +101,28 @@ export class ConnectionService {
       ),
       availableAddresses: filteredAvailableAddresses
     })
+
+    const session = this.sessionManager.getSession()
+    this.eventManager.emit('connected', { session })
+    this.eventManager.emit('sessionChanged', { session })
   }
 
   private async connectWithURIPoll(
     connector: Connector,
     network: Network,
-    provider: SupportedProvider
+    provider: SupportedProvider,
+    connectionMode: ConnectionMode
   ): Promise<ConnectorResult> {
     const connectPromise = connector.connect(network, provider)
 
     let pollingStopped = false
+    let emittedUri: string | undefined
 
     const pollForURI = setInterval(() => {
       const uri = this.getConnectionURI()
-      if (uri) {
-        stopPolling()
-        this.eventManager.notify()
+      if (uri && uri !== emittedUri) {
+        emittedUri = uri
+        this.eventManager.emit('connectionUri', { uri, connectionMode })
       }
     }, 100)
 
@@ -234,7 +257,8 @@ export class ConnectionService {
     return network
   }
 
-  async disconnect(): Promise<void> {
+  async disconnect(options?: ServiceOptions): Promise<void> {
+    options?.signal?.throwIfAborted()
     try {
       if (
         this.activeConnector &&
@@ -245,6 +269,9 @@ export class ConnectionService {
     } finally {
       this.activeConnector = null
       this.sessionManager.clearSession()
+      const session = this.sessionManager.getSession()
+      this.eventManager.emit('disconnected', undefined)
+      this.eventManager.emit('sessionChanged', { session })
     }
   }
 

package/src/services/network-switch-service.ts

@@ -11,6 +11,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 NetworkSwitchService {
   private isLoading = false
@@ -31,7 +32,12 @@ export class NetworkSwitchService {
     }
   }
 
-  async switchNetwork(networkId: NetworkId): Promise<void> {
+  async switchNetwork(
+    networkId: NetworkId,
+    options?: ServiceOptions
+  ): Promise<void> {
+    options?.signal?.throwIfAborted()
+
     // Check if there's an active connection
     const session = this.sessionManager.getSession()
     if (!session) {
@@ -104,7 +110,10 @@ export class NetworkSwitchService {
       // Set loading states
       this.isLoading = true
       this.isWaitingForUserApproval = requiresApproval
-      this.eventManager.notify()
+      this.eventManager.emit('networkSwitching', {
+        isLoading: true,
+        isWaitingForUserApproval: requiresApproval
+      })
 
       // Perform the network switch and get the new address
       // Pass the appropriate provider based on connection mode
@@ -129,6 +138,8 @@ export class NetworkSwitchService {
         result = await activeConnector.switchNetwork(network)
       }
 
+      options?.signal?.throwIfAborted()
+
       // Filter available addresses to only include those for configured networks
       const filteredAvailableAddresses = result.availableAddresses
         ? result.availableAddresses.filter(addr =>
@@ -144,11 +155,19 @@ export class NetworkSwitchService {
           availableAddresses: filteredAvailableAddresses
         })
       })
+
+      this.eventManager.emit('networkSwitched', { network })
+      this.eventManager.emit('sessionChanged', {
+        session: this.sessionManager.getSession()
+      })
     } finally {
       // Clear loading states
       this.isLoading = false
       this.isWaitingForUserApproval = false
-      this.eventManager.notify()
+      this.eventManager.emit('networkSwitching', {
+        isLoading: false,
+        isWaitingForUserApproval: false
+      })
     }
   }
 

package/src/services/signature-service.ts

@@ -9,6 +9,7 @@ import type {
   EIP712TypedData
 } from '@meshconnect/uwc-types'
 import type { SessionManager } from '../managers/session-manager'
+import type { ServiceOptions } from './connection-service'
 
 /**
  * Service for handling signature operations across different connector types
@@ -23,12 +24,15 @@ export class SignatureService {
    * Sign a message with the currently connected wallet
    * @param message The message to sign
    * @param provider The wallet provider to use for signing (required for injected connector)
+   * @param options Optional cancellation signal
    * @returns A promise that resolves to the signature
    */
   async signMessage(
     message: string,
-    provider?: SupportedProvider
+    provider?: SupportedProvider,
+    options?: ServiceOptions
   ): Promise<SignatureType> {
+    options?.signal?.throwIfAborted()
     const session = this.sessionManager.getSession()
 
     if (!session.connectionMode) {
@@ -53,30 +57,34 @@ export class SignatureService {
     }
 
     // Call the connector's signMessage method with the appropriate provider
+    let signature: SignatureType
     if (session.connectionMode === 'injected') {
       if (!provider) {
         throw new Error('Provider is required for injected connector')
       }
-      return await connector.signMessage(
+      signature = await connector.signMessage(
         message,
         provider as
           | ExtensionInjectedProvider
           | IntegratedBrowserInjectedProvider
       )
     } else if (session.connectionMode === 'tonConnect') {
-      return await connector.signMessage(message)
+      signature = await connector.signMessage(message)
     } else if (session.connectionMode === 'walletConnect') {
       if (!provider) {
         throw new Error('Provider is required for WalletConnect connector')
       }
-      return await connector.signMessage(
+      signature = await connector.signMessage(
         message,
         provider as WalletConnectProvider
       )
     } else {
       // For other connectors that might not need the provider
-      return await connector.signMessage(message)
+      signature = await connector.signMessage(message)
     }
+
+    options?.signal?.throwIfAborted()
+    return signature
   }
 
   /**

package/src/services/transaction-service.ts

@@ -9,6 +9,7 @@ import type {
   TransactionResult
 } from '@meshconnect/uwc-types'
 import type { SessionManager } from '../managers/session-manager'
+import type { ServiceOptions } from './connection-service'
 
 /**
  * Service for handling transaction operations across different connector types
@@ -23,12 +24,15 @@ export class TransactionService {
    * Send a transaction with the currently connected wallet
    * @param request The transaction request parameters
    * @param provider The wallet provider to use for sending (required for injected connector)
+   * @param options Optional cancellation signal
    * @returns A promise that resolves to the transaction result
    */
   async sendTransaction(
     request: TransactionRequest,
-    provider?: SupportedProvider
+    provider?: SupportedProvider,
+    options?: ServiceOptions
   ): Promise<TransactionResult> {
+    options?.signal?.throwIfAborted()
     const session = this.sessionManager.getSession()
 
     if (!session.connectionMode) {
@@ -53,29 +57,33 @@ export class TransactionService {
     }
 
     // Call the connector's sendTransaction method with the appropriate provider
+    let result: TransactionResult
     if (session.connectionMode === 'injected') {
       if (!provider) {
         throw new Error('Provider is required for injected connector')
       }
-      return await connector.sendTransaction(
+      result = await connector.sendTransaction(
         request,
         provider as
           | ExtensionInjectedProvider
           | IntegratedBrowserInjectedProvider
       )
     } else if (session.connectionMode === 'tonConnect') {
-      return await connector.sendTransaction(request)
+      result = await connector.sendTransaction(request)
     } else if (session.connectionMode === 'walletConnect') {
       if (!provider) {
         throw new Error('Provider is required for WalletConnect connector')
       }
-      return await connector.sendTransaction(
+      result = await connector.sendTransaction(
         request,
         provider as WalletConnectProvider
       )
     } else {
       // For other connectors that might not need the provider
-      return await connector.sendTransaction(request)
+      result = await connector.sendTransaction(request)
     }
+
+    options?.signal?.throwIfAborted()
+    return result
   }
 }

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()
+      })
     }
   }
 }