@meshconnect/uwc-core 1.0.3 → 1.1.0

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

@@ -0,0 +1,610 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type {
+  Network,
+  WalletMetadata,
+  Logger,
+  Session
+} from '@meshconnect/uwc-types'
+import { NoCommonNetworkError } from '@meshconnect/uwc-types'
+import { UniversalWalletConnector } from './universal-wallet-connector'
+import type { UWCObserver, UWCTelemetryEvent } from './observability/telemetry'
+
+// Mock connectors (and the connect/switch services) so the façade resolves
+// deterministically, but leave the EventManager + logger + observability wiring
+// AND the sign/send services REAL — sign/send here run end-to-end through the
+// real SignatureService / TransactionService (which own validation + the
+// funnel) down to the mocked connector boundary.
+const signMessageMock = vi.fn()
+const signTypedDataMock = vi.fn()
+const tonSignMessageMock = vi.fn()
+// Shared so individual tests can drive the connect path (delta A) and the
+// detection path (P5) without re-mocking the module.
+const connectMock = vi.fn()
+const getAvailableWalletsMock = vi.fn()
+const teardownLifecycleMock = vi.fn()
+const reattachLifecycleMock = vi.fn()
+const switchNetworkMock = vi.fn()
+const sendTransactionMock = vi.fn()
+const getWalletCapabilitiesMock = vi.fn()
+
+const connectedSession: Session = {
+  connectionMode: 'injected',
+  activeNetwork: {
+    internalId: 1,
+    id: 'eip155:1',
+    namespace: 'eip155',
+    name: 'Ethereum',
+    logoUrl: '',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    networkType: 'evm'
+  },
+  activeWalletCapabilities: null,
+  activeNetworkWalletCapabilities: null,
+  activeAddress: '0xabc',
+  publicKey: null,
+  availableNetworks: [],
+  activeWallet: {
+    id: 'metamask',
+    name: 'MetaMask',
+    extensionInjectedProvider: {}
+  } as unknown as WalletMetadata,
+  availableAddresses: []
+}
+
+vi.mock('@meshconnect/uwc-injected-connector', () => ({
+  InjectedConnector: vi.fn().mockImplementation(function () {
+    return {
+      getAvailableWallets: getAvailableWalletsMock,
+      // The REAL sign/send services route connectionMode 'injected' here —
+      // these mocks are the instrumented wallet boundary.
+      signMessage: signMessageMock,
+      signTypedData: signTypedDataMock,
+      sendTransaction: sendTransactionMock
+    }
+  })
+}))
+vi.mock('@meshconnect/uwc-wallet-connect-connector', () => ({
+  WalletConnectConnector: vi.fn().mockImplementation(function () {
+    return { getAvailableWallets: vi.fn().mockResolvedValue([]) }
+  })
+}))
+vi.mock('@meshconnect/uwc-ton-connector', () => ({
+  TonConnectConnector: vi.fn().mockImplementation(function () {
+    return {
+      getAvailableWallets: vi.fn().mockResolvedValue([]),
+      signMessage: tonSignMessageMock
+    }
+  })
+}))
+vi.mock('./managers/session-manager', () => ({
+  SessionManager: vi.fn().mockImplementation(function () {
+    return { getSession: () => connectedSession, updateSession: vi.fn() }
+  })
+}))
+vi.mock('./services/connection-service', () => ({
+  ConnectionService: vi.fn().mockImplementation(function () {
+    return {
+      connect: connectMock,
+      disconnect: vi.fn().mockResolvedValue(undefined),
+      getWallets: vi.fn().mockReturnValue([]),
+      getNetworks: vi.fn().mockReturnValue([]),
+      getConnectionURI: vi.fn(),
+      updateWallets: vi.fn(),
+      teardownLifecycle: teardownLifecycleMock,
+      reattachLifecycle: reattachLifecycleMock
+    }
+  })
+}))
+vi.mock('./services/network-switch-service', () => ({
+  NetworkSwitchService: vi.fn().mockImplementation(function () {
+    return { switchNetwork: switchNetworkMock, getLoadingState: vi.fn() }
+  })
+}))
+vi.mock('./services/wallet-capabilities-service', () => ({
+  WalletCapabilitiesService: vi.fn().mockImplementation(function () {
+    return { getWalletCapabilities: getWalletCapabilitiesMock }
+  })
+}))
+
+const networks = [
+  {
+    internalId: 1,
+    id: 'eip155:1',
+    namespace: 'eip155',
+    name: 'Ethereum',
+    logoUrl: '',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    networkType: 'evm'
+  }
+] as unknown as Network[]
+
+const wallets = [
+  { id: 'metamask', name: 'MetaMask' }
+] as unknown as WalletMetadata[]
+
+describe('UniversalWalletConnector — observability wiring', () => {
+  beforeEach(() => {
+    UniversalWalletConnector.resetInstance()
+    signMessageMock.mockReset()
+    signMessageMock.mockResolvedValue({ type: 'standard', signature: '0xsig' })
+    connectMock.mockReset()
+    connectMock.mockResolvedValue(undefined)
+    getAvailableWalletsMock.mockReset()
+    getAvailableWalletsMock.mockResolvedValue([])
+    teardownLifecycleMock.mockReset()
+    reattachLifecycleMock.mockReset()
+    switchNetworkMock.mockReset()
+    switchNetworkMock.mockResolvedValue(undefined)
+    sendTransactionMock.mockReset()
+    sendTransactionMock.mockResolvedValue({ hash: '0xtx' })
+    signTypedDataMock.mockReset()
+    signTypedDataMock.mockResolvedValue('0xtypedsig')
+    tonSignMessageMock.mockReset()
+    tonSignMessageMock.mockResolvedValue({
+      type: 'standard',
+      signature: 'tonsig'
+    })
+    getWalletCapabilitiesMock.mockReset()
+    getWalletCapabilitiesMock.mockResolvedValue(undefined)
+  })
+
+  it('forwards a sign handoff to observer.onEvent (awaitingWallet → walletSucceeded)', async () => {
+    const events: UWCTelemetryEvent[] = []
+    const observer: UWCObserver = { onEvent: e => events.push(e) }
+    const uwc = new UniversalWalletConnector({ networks, wallets, observer })
+
+    await uwc.signMessage('hello')
+
+    const names = events.map(e => e.name)
+    expect(names).toContain('awaitingWallet')
+    expect(names).toContain('walletSucceeded')
+
+    const awaiting = events.find(e => e.name === 'awaitingWallet')!
+    const succeeded = events.find(e => e.name === 'walletSucceeded')!
+    // Same correlation id pairs start↔terminal, and the per-instance session id
+    // is stamped on every record.
+    expect(awaiting.handoffId).toBe(succeeded.handoffId)
+    expect(awaiting.sdkSessionId).toBe(succeeded.sdkSessionId)
+    expect(awaiting.operation).toBe('signMessage')
+    expect(signMessageMock).toHaveBeenCalledOnce()
+  })
+
+  it('stamps a consumer-supplied correlationId (string) as its own field', async () => {
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) },
+      correlationId: 'link-123'
+    })
+
+    await uwc.signMessage('hello')
+
+    expect(events.length).toBeGreaterThan(0)
+    // correlationId is the consumer's value; sdkSessionId stays the generated
+    // instance id and is never aliased to it.
+    expect(events.every(e => e.correlationId === 'link-123')).toBe(true)
+    expect(events.every(e => e.sdkSessionId !== 'link-123')).toBe(true)
+    expect(
+      events.every(
+        e => typeof e.sdkSessionId === 'string' && e.sdkSessionId.length > 0
+      )
+    ).toBe(true)
+  })
+
+  it('resolves a correlationId getter per-event (dynamic id)', async () => {
+    let id = 'a'
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) },
+      correlationId: () => id
+    })
+
+    await uwc.signMessage('one')
+    id = 'b'
+    await uwc.signMessage('two')
+
+    const ids = new Set(events.map(e => e.correlationId))
+    expect(ids.has('a')).toBe(true)
+    expect(ids.has('b')).toBe(true)
+  })
+
+  it('omits correlationId (keeps the instance id) when the getter throws', async () => {
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) },
+      correlationId: () => {
+        throw new Error('not ready')
+      }
+    })
+
+    await uwc.signMessage('hello')
+
+    expect(events.length).toBeGreaterThan(0)
+    // No consumer id survives a throw — the field is omitted...
+    expect(events.every(e => e.correlationId === undefined)).toBe(true)
+    // ...but the generated instance id is always stamped.
+    expect(
+      events.every(
+        e => typeof e.sdkSessionId === 'string' && e.sdkSessionId.length > 0
+      )
+    ).toBe(true)
+  })
+
+  it('emits walletFailed when the underlying op throws', async () => {
+    signMessageMock.mockRejectedValueOnce(new Error('relay down'))
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(uwc.signMessage('hello')).rejects.toThrow('relay down')
+    const failed = events.find(e => e.name === 'walletFailed')
+    expect(failed?.error?.message).toBe('relay down')
+    // The back-compat `error` event still fires too — marked as the duplicate
+    // of the terminal so metrics can count without double-counting.
+    const err = events.find(e => e.name === 'error')
+    expect(err).toBeDefined()
+    expect(err?.handoffCovered).toBe(true)
+  })
+
+  it('marks the error record of a walletRejected terminal as handoffCovered', async () => {
+    signMessageMock.mockRejectedValueOnce({ code: 4001 })
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(uwc.signMessage('hello')).rejects.toEqual({ code: 4001 })
+
+    expect(events.some(e => e.name === 'walletRejected')).toBe(true)
+    const err = events.find(e => e.name === 'error')
+    expect(err?.handoffCovered).toBe(true)
+    expect(err?.failureKind).toBe('user_rejected')
+  })
+
+  it('an aborted op emits awaitingWallet with no terminal and no error', async () => {
+    // A DOMException AbortError is an intentional cancellation, not a wallet
+    // outcome: instrumentHandoff emits no terminal, and emitError must skip it
+    // too (both paths share isAbortError).
+    signMessageMock.mockRejectedValueOnce(
+      new DOMException('Aborted', 'AbortError')
+    )
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(uwc.signMessage('hello')).rejects.toThrow()
+
+    const names = events.map(e => e.name)
+    expect(names).toContain('awaitingWallet')
+    expect(names).not.toContain('walletSucceeded')
+    expect(names).not.toContain('walletRejected')
+    expect(names).not.toContain('walletFailed')
+    expect(names).not.toContain('error')
+  })
+
+  it('a custom abort(reason) mid-flight emits NO terminal and NO error (the signal is the evidence)', async () => {
+    // `controller.abort(new Error(...))` rejects with the CUSTOM reason — not an
+    // AbortError by name — so both the funnel and emitError must consult the
+    // caller's signal, not just the error name.
+    const controller = new AbortController()
+    const reason = new Error('nav away')
+    signMessageMock.mockImplementationOnce(async () => {
+      controller.abort(reason)
+      throw reason
+    })
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(
+      uwc.signMessage('hello', { signal: controller.signal })
+    ).rejects.toThrow('nav away')
+
+    const names = events.map(e => e.name)
+    expect(names).toContain('awaitingWallet')
+    expect(names).not.toContain('walletFailed')
+    expect(names).not.toContain('walletRejected')
+    expect(names).not.toContain('error')
+  })
+
+  it('an abort racing completion records the truthful walletSucceeded, then rejects with the abort', async () => {
+    const controller = new AbortController()
+    signMessageMock.mockImplementationOnce(async () => {
+      controller.abort()
+      return { type: 'standard', signature: '0xsig' }
+    })
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(
+      uwc.signMessage('hello', { signal: controller.signal })
+    ).rejects.toMatchObject({ name: 'AbortError' })
+
+    const names = events.map(e => e.name)
+    expect(names).toContain('walletSucceeded')
+    expect(names).not.toContain('error')
+  })
+
+  it('a custom abort(reason) during getWalletCapabilities emits NO error (same contract as the other ops)', async () => {
+    // getWalletCapabilities accepts { signal } like the wallet ops — its
+    // emitError must consult the same signal, or a custom abort(reason)
+    // surfaces as a spurious `error` only for this op.
+    const controller = new AbortController()
+    const reason = new Error('nav away')
+    getWalletCapabilitiesMock.mockImplementationOnce(async () => {
+      controller.abort(reason)
+      throw reason
+    })
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(
+      uwc.getWalletCapabilities('0xabc', undefined, {
+        signal: controller.signal
+      })
+    ).rejects.toThrow('nav away')
+
+    expect(events.map(e => e.name)).not.toContain('error')
+  })
+
+  it('routes a custom logger as the sink and the multi-instance warning through it', () => {
+    const calls: string[] = []
+    const logger: Logger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: msg => calls.push(msg)
+    }
+    // First instance is fine; the SECOND triggers the multi-instance warning,
+    // which must travel through the injected logger, not raw console.
+    new UniversalWalletConnector({ networks, wallets, logger })
+    new UniversalWalletConnector({ networks, wallets, logger })
+
+    expect(calls.some(m => m.includes('Multiple instances'))).toBe(true)
+  })
+
+  it('enriches the `error` event with no_common_network + networkMismatch (delta A)', async () => {
+    // The #1 prod connection failure is a PRE-wallet validation throw, so it
+    // surfaces via the `error` event (no handoff terminal). emitError must still
+    // classify it and forward the two CAIP-2 id lists.
+    connectMock.mockRejectedValueOnce(
+      new NoCommonNetworkError(['eip155:1', 'eip155:137'], ['solana:101'])
+    )
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    await expect(uwc.connect('injected', 'metamask')).rejects.toThrow()
+
+    const err = events.find(e => e.name === 'error')!
+    expect(err.operation).toBe('connect')
+    expect(err.failureKind).toBe('no_common_network')
+    expect(err.source).toBe('connector')
+    expect(err.networkMismatch).toEqual({
+      walletNetworkIds: ['eip155:1', 'eip155:137'],
+      configuredNetworkIds: ['solana:101']
+    })
+    // Pre-wallet failure: no terminal fired, so this record is not a duplicate.
+    expect(err.handoffCovered).toBeUndefined()
+  })
+
+  it('emits walletDiscoveryFailed + a requested-vs-matched summary (P5)', async () => {
+    // Detection runs in the constructor. A connector throw used to vanish in a
+    // silent catch; now it surfaces, and the summary distinguishes "asked for 1,
+    // matched 0" from "asked for none".
+    getAvailableWalletsMock.mockRejectedValue(new Error('eip6963 probe failed'))
+    const eip155Wallet = {
+      id: 'metamask',
+      name: 'MetaMask',
+      extensionInjectedProvider: {
+        supportedNetworkIds: ['eip155:1'],
+        namespaceMetaData: {
+          eip155: { eip155Name: 'metamask', injectedId: 'isMetaMask' }
+        }
+      }
+    } as unknown as WalletMetadata
+
+    const events: UWCTelemetryEvent[] = []
+    let resolveReady!: () => void
+    const ready = new Promise<void>(r => (resolveReady = r))
+    new UniversalWalletConnector({
+      networks,
+      wallets: [eip155Wallet],
+      observer: {
+        onEvent: e => {
+          events.push(e)
+          if (e.name === 'ready') resolveReady()
+        }
+      }
+    })
+    await ready
+
+    const failed = events.find(e => e.name === 'walletDiscoveryFailed')!
+    expect(failed.namespace).toBe('eip155')
+    expect(failed.connectionMode).toBe('injected')
+    expect(failed.error?.message).toBe('eip6963 probe failed')
+
+    const detected = events.find(e => e.name === 'walletsDetected')!
+    expect(detected.discovery).toEqual({ eip155: { requested: 1, matched: 0 } })
+  })
+
+  it('a missing provider fails BEFORE the funnel — config error, not a wallet outcome', async () => {
+    // Design parity with connect/switch: provider resolution is validation, so
+    // its failure must surface only via the `error` event, never as an
+    // awaitingWallet + walletFailed pair (which would pollute the funnel with a
+    // failure the wallet never saw).
+    const originalWallet = connectedSession.activeWallet
+    connectedSession.activeWallet = {
+      id: 'metamask',
+      name: 'MetaMask'
+      // no extensionInjectedProvider / walletConnectProvider
+    } as unknown as WalletMetadata
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    try {
+      await expect(uwc.signMessage('hello')).rejects.toThrow(
+        'No provider available for the active wallet'
+      )
+      await expect(
+        uwc.sendTransaction({ to: '0xdef', amount: 1n } as never)
+      ).rejects.toThrow('No provider available for the active wallet')
+      await expect(
+        uwc.signTypedData({
+          domain: {},
+          types: {},
+          primaryType: 'X',
+          message: {}
+        } as never)
+      ).rejects.toThrow('No provider available for the active wallet')
+
+      const names = events.map(e => e.name)
+      expect(names).not.toContain('awaitingWallet')
+      expect(names).not.toContain('walletFailed')
+      const errs = events.filter(e => e.name === 'error')
+      expect(errs).toHaveLength(3)
+      // No terminal fired, so none of these are duplicates.
+      expect(errs.every(e => e.handoffCovered === undefined)).toBe(true)
+      expect(signMessageMock).not.toHaveBeenCalled()
+      expect(sendTransactionMock).not.toHaveBeenCalled()
+    } finally {
+      connectedSession.activeWallet = originalWallet
+    }
+  })
+
+  it('a tonConnect session still enters the funnel with no resolved provider', async () => {
+    // TON resolves its provider inside the connector, so an undefined provider
+    // is the NORMAL case there — the pre-funnel provider check must not break it.
+    const originalMode = connectedSession.connectionMode
+    const originalWallet = connectedSession.activeWallet
+    connectedSession.connectionMode = 'tonConnect'
+    connectedSession.activeWallet = {
+      id: 'tonkeeper',
+      name: 'Tonkeeper'
+    } as unknown as WalletMetadata
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      // Registers the (mocked) TON connector so the real service can route to it.
+      tonConnectConfig: { manifestUrl: 'https://x/manifest.json' } as never,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    try {
+      await uwc.signMessage('hello')
+      const names = events.map(e => e.name)
+      expect(names).toContain('awaitingWallet')
+      expect(names).toContain('walletSucceeded')
+      // The TON connector resolves its own provider — called with the message only.
+      expect(tonSignMessageMock).toHaveBeenCalledWith('hello')
+    } finally {
+      connectedSession.connectionMode = originalMode
+      connectedSession.activeWallet = originalWallet
+    }
+  })
+
+  it('re-attaches provider lifecycle after a CROSS-namespace switchNetwork', async () => {
+    // The live provider (and thus the lifecycle surface) changes when the
+    // namespace changes — the connect-time subscription would observe the wrong
+    // provider (e.g. EVM listeners on a now-Solana session).
+    const originalNetwork = connectedSession.activeNetwork
+    switchNetworkMock.mockImplementation(async () => {
+      connectedSession.activeNetwork = {
+        internalId: 101,
+        id: 'solana:mainnet',
+        namespace: 'solana',
+        name: 'Solana',
+        logoUrl: '',
+        nativeCurrency: { name: 'SOL', symbol: 'SOL', decimals: 9 },
+        networkType: 'solana'
+      } as never
+    })
+    const uwc = new UniversalWalletConnector({ networks, wallets })
+
+    try {
+      await uwc.switchNetwork('solana:mainnet' as never)
+      expect(reattachLifecycleMock).toHaveBeenCalledTimes(1)
+    } finally {
+      connectedSession.activeNetwork = originalNetwork
+    }
+  })
+
+  it('does NOT re-attach lifecycle on a same-namespace switchNetwork', async () => {
+    const originalNetwork = connectedSession.activeNetwork
+    switchNetworkMock.mockImplementation(async () => {
+      connectedSession.activeNetwork = {
+        ...originalNetwork!,
+        internalId: 137,
+        id: 'eip155:137',
+        name: 'Polygon'
+      } as never
+    })
+    const uwc = new UniversalWalletConnector({ networks, wallets })
+
+    try {
+      await uwc.switchNetwork('eip155:137' as never)
+      expect(reattachLifecycleMock).not.toHaveBeenCalled()
+    } finally {
+      connectedSession.activeNetwork = originalNetwork
+    }
+  })
+
+  it('does NOT re-attach lifecycle when the switch fails', async () => {
+    switchNetworkMock.mockRejectedValueOnce(new Error('switch failed'))
+    const uwc = new UniversalWalletConnector({ networks, wallets })
+
+    await expect(uwc.switchNetwork('eip155:137' as never)).rejects.toThrow(
+      'switch failed'
+    )
+    expect(reattachLifecycleMock).not.toHaveBeenCalled()
+  })
+
+  it('dispose() stops further observer delivery AND releases provider-lifecycle listeners', async () => {
+    const events: UWCTelemetryEvent[] = []
+    const uwc = new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+    uwc.dispose()
+    // dispose() must tear down the live provider-lifecycle subscription, not just
+    // the observer bus — otherwise EIP-1193/adapter `.on` listeners leak when the
+    // app disposes a connected session without calling disconnect() first.
+    expect(teardownLifecycleMock).toHaveBeenCalledTimes(1)
+    events.length = 0
+    await uwc.signMessage('hello')
+    expect(events).toHaveLength(0)
+  })
+})