@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/observability/telemetry.test.ts

@@ -0,0 +1,549 @@
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import type { Session } from '@meshconnect/uwc-types'
+import {
+  normalizeEvent,
+  deriveWalletFlowType,
+  derivePlatform,
+  TELEMETRY_SCHEMA_VERSION
+} from './telemetry'
+import { UWC_CORE_VERSION } from '../version'
+
+describe('deriveWalletFlowType', () => {
+  it('maps injected to extension on desktop, in-wallet-browser on mobile', () => {
+    expect(deriveWalletFlowType('injected', 'desktop')).toBe(
+      'browser_extension_flow'
+    )
+    expect(deriveWalletFlowType('injected', 'mobile')).toBe(
+      'in_wallet_browser_flow'
+    )
+    expect(deriveWalletFlowType('injected', 'webview')).toBe(
+      'in_wallet_browser_flow'
+    )
+  })
+
+  it('maps walletConnect to QR on desktop, deeplink on mobile', () => {
+    expect(deriveWalletFlowType('walletConnect', 'desktop')).toBe(
+      'wallet_connect_qr_flow'
+    )
+    expect(deriveWalletFlowType('walletConnect', 'mobile')).toBe(
+      'wallet_connect_deep_link_flow'
+    )
+  })
+
+  it('maps tonConnect to QR on desktop, deeplink on mobile', () => {
+    expect(deriveWalletFlowType('tonConnect', 'desktop')).toBe(
+      'ton_connect_qr_flow'
+    )
+    expect(deriveWalletFlowType('tonConnect', 'mobile')).toBe(
+      'ton_connect_deep_link_flow'
+    )
+  })
+})
+
+describe('derivePlatform', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('returns desktop for a desktop UA', () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh)' })
+    expect(derivePlatform()).toBe('desktop')
+  })
+
+  it('returns mobile for an iOS Safari UA', () => {
+    vi.stubGlobal('navigator', {
+      userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) Safari/604.1'
+    })
+    expect(derivePlatform()).toBe('mobile')
+  })
+
+  it('returns webview for an Android in-app browser UA (; wv)', () => {
+    vi.stubGlobal('navigator', {
+      userAgent: 'Mozilla/5.0 (Linux; Android 13; wv) Chrome/120'
+    })
+    expect(derivePlatform()).toBe('webview')
+  })
+})
+
+describe('normalizeEvent', () => {
+  const SDK_SESSION = 'sess-1'
+  const NOW = 1_700_000_000_000
+
+  it('reduces a `connected` session to facets and never leaks the address', () => {
+    const session = {
+      connectionMode: 'injected',
+      activeNetwork: { namespace: 'eip155', id: 'eip155:1', name: 'Ethereum' },
+      activeWallet: { id: 'metamask', name: 'MetaMask' },
+      activeAddress: '0xDEADBEEFcafe1234567890',
+      publicKey: 'pubkey-should-not-leak'
+    } as unknown as Session
+
+    const out = normalizeEvent('connected', { session }, SDK_SESSION, NOW)
+
+    expect(out.namespace).toBe('eip155')
+    expect(out.chainId).toBe('eip155:1')
+    expect(out.walletId).toBe('metamask')
+    expect(out.sdkSessionId).toBe(SDK_SESSION)
+    expect(out.timestamp).toBe(NOW)
+    // The address / pubkey must be structurally absent from the record.
+    const serialized = JSON.stringify(out)
+    expect(serialized).not.toContain('0xDEADBEEF')
+    expect(serialized).not.toContain('pubkey-should-not-leak')
+  })
+
+  it('surfaces missingNamespaces when a supported namespace returned no address', () => {
+    // The framed-embed secondary-gather skip: Phantom connects on EVM, supports
+    // Solana for a configured network, but no Solana address came back. This is
+    // the exact symptom that would otherwise be silent.
+    const session = {
+      connectionMode: 'injected',
+      activeNetwork: { namespace: 'eip155', id: 'eip155:1', name: 'Ethereum' },
+      activeWallet: { id: 'phantom', name: 'Phantom' },
+      activeAddress: '0xEVMonly1234567890',
+      publicKey: null,
+      availableNetworks: [
+        { namespace: 'eip155', id: 'eip155:1' },
+        { namespace: 'solana', id: 'solana:101' }
+      ],
+      availableAddresses: [
+        { networkId: 'eip155:1', address: '0xEVMonly1234567890' }
+      ]
+    } as unknown as Session
+
+    const out = normalizeEvent('connected', { session }, SDK_SESSION, NOW)
+
+    expect(out.addressNamespaces).toEqual({ eip155: 1 })
+    expect(out.missingNamespaces).toEqual(['solana'])
+    // Still only namespace names + counts — no address.
+    expect(JSON.stringify(out)).not.toContain('0xEVMonly')
+  })
+
+  it('counts addresses per namespace and omits missingNamespaces on full coverage', () => {
+    const session = {
+      connectionMode: 'injected',
+      activeNetwork: { namespace: 'eip155', id: 'eip155:1' },
+      activeWallet: { id: 'phantom' },
+      availableNetworks: [
+        { namespace: 'eip155', id: 'eip155:1' },
+        { namespace: 'eip155', id: 'eip155:8453' },
+        { namespace: 'solana', id: 'solana:101' }
+      ],
+      availableAddresses: [
+        { networkId: 'eip155:1', address: '0xa' },
+        { networkId: 'eip155:8453', address: '0xb' },
+        { networkId: 'solana:101', address: 'SoLaddr' }
+      ]
+    } as unknown as Session
+
+    // sessionChanged shares the path — assert the second name resolves too.
+    const out = normalizeEvent('sessionChanged', { session }, SDK_SESSION, NOW)
+
+    expect(out.addressNamespaces).toEqual({ eip155: 2, solana: 1 })
+    expect('missingNamespaces' in out).toBe(false)
+  })
+
+  it('scrubs the error message on `error` events', () => {
+    // '0' is outside the base58 alphabet, so this exercises the length cap
+    // (a base58-looking run of this length would be redacted whole instead).
+    const out = normalizeEvent(
+      'error',
+      {
+        error: { type: 'unknown', message: '0'.repeat(800) },
+        operation: 'signMessage'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.operation).toBe('signMessage')
+    expect(out.error?.message.endsWith('…[truncated]')).toBe(true)
+  })
+
+  it('caps networkMismatch id lists on egress (wallet-declared, unbounded upstream)', () => {
+    // walletNetworkIds comes from the wallet's own supportedNetworkIds — a
+    // non-compliant wallet controls its cardinality and element length, so the
+    // telemetry copy is bounded. Elements are NOT scrubbed: a legit
+    // `solana:<32-char-base58-ref>` CAIP-2 id would be eaten by the base58 rule.
+    const walletNetworkIds = [
+      ...Array.from({ length: 29 }, (_, i) => `eip155:${i}`),
+      'x'.repeat(200)
+    ]
+    const out = normalizeEvent(
+      'error',
+      {
+        error: { type: 'unknown', message: 'no overlap' },
+        operation: 'connect',
+        networkMismatch: {
+          walletNetworkIds,
+          configuredNetworkIds: ['eip155:1']
+        }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.networkMismatch?.walletNetworkIds).toHaveLength(20)
+    expect(
+      out.networkMismatch?.walletNetworkIds.every(id => id.length <= 64)
+    ).toBe(true)
+    expect(out.networkMismatch?.configuredNetworkIds).toEqual(['eip155:1'])
+  })
+
+  it('omits undefined optional fields rather than emitting present-but-undefined keys', () => {
+    // An ordinary error carries no classification facets — they must be ABSENT,
+    // not present-and-undefined, so a consumer's `'errorCode' in event` is honest.
+    const out = normalizeEvent(
+      'error',
+      {
+        error: { type: 'unknown', message: 'boom' },
+        operation: 'signMessage'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect('errorCode' in out).toBe(false)
+    expect('failureKind' in out).toBe(false)
+    expect('source' in out).toBe(false)
+    expect('networkMismatch' in out).toBe(false)
+    expect(Object.values(out).every(v => v !== undefined)).toBe(true)
+  })
+
+  it('passes handoff facets through for awaitingWallet', () => {
+    const out = normalizeEvent(
+      'awaitingWallet',
+      {
+        operation: 'sendTransaction',
+        connectionMode: 'walletConnect',
+        walletId: 'rainbow',
+        namespace: 'eip155',
+        chainId: 'eip155:8453',
+        handoffId: 'h-1',
+        walletFlowType: 'wallet_connect_deep_link_flow',
+        platform: 'mobile'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.handoffId).toBe('h-1')
+    expect(out.walletFlowType).toBe('wallet_connect_deep_link_flow')
+    expect(out.platform).toBe('mobile')
+  })
+
+  it('collapses noisy/unknown events to name only', () => {
+    const out = normalizeEvent('ready', undefined, SDK_SESSION, NOW)
+    expect(out).toEqual({
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
+      uwcVersion: UWC_CORE_VERSION,
+      name: 'ready',
+      sdkSessionId: SDK_SESSION,
+      timestamp: NOW
+    })
+  })
+
+  it('stamps schemaVersion on every record', () => {
+    const ready = normalizeEvent('ready', undefined, SDK_SESSION, NOW)
+    const connecting = normalizeEvent(
+      'connecting',
+      { connectionMode: 'injected', walletId: 'metamask' },
+      SDK_SESSION,
+      NOW
+    )
+    expect(ready.schemaVersion).toBe(TELEMETRY_SCHEMA_VERSION)
+    expect(connecting.schemaVersion).toBe(TELEMETRY_SCHEMA_VERSION)
+  })
+
+  it('stamps uwcVersion on every record (aggregate bugs per released version)', () => {
+    const ready = normalizeEvent('ready', undefined, SDK_SESSION, NOW)
+    const connecting = normalizeEvent(
+      'connecting',
+      { connectionMode: 'injected', walletId: 'metamask' },
+      SDK_SESSION,
+      NOW
+    )
+    expect(ready.uwcVersion).toBe(UWC_CORE_VERSION)
+    expect(connecting.uwcVersion).toBe(UWC_CORE_VERSION)
+  })
+
+  it('stamps correlationId as its own field only when supplied (never aliased)', () => {
+    const without = normalizeEvent('ready', undefined, SDK_SESSION, NOW)
+    expect(without.correlationId).toBeUndefined()
+    expect('correlationId' in without).toBe(false)
+
+    const withId = normalizeEvent(
+      'ready',
+      undefined,
+      SDK_SESSION,
+      NOW,
+      'link-123'
+    )
+    expect(withId.correlationId).toBe('link-123')
+    // The generated session id is untouched — the two are not aliased.
+    expect(withId.sdkSessionId).toBe(SDK_SESSION)
+  })
+
+  it('threads timedOut / timeoutMs on a late walletSucceeded', () => {
+    const out = normalizeEvent(
+      'walletSucceeded',
+      {
+        handoffId: 'h-1',
+        operation: 'sendTransaction',
+        durationMs: 1234,
+        connectionMode: 'injected',
+        timedOut: true,
+        timeoutMs: 1000
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.timedOut).toBe(true)
+    expect(out.timeoutMs).toBe(1000)
+  })
+
+  it('threads timeoutMs + targetAlreadyActive on walletTimedOut', () => {
+    const out = normalizeEvent(
+      'walletTimedOut',
+      {
+        handoffId: 'h-1',
+        operation: 'switchNetwork',
+        durationMs: 1000,
+        connectionMode: 'injected',
+        timeoutMs: 1000,
+        targetAlreadyActive: true
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.timeoutMs).toBe(1000)
+    expect(out.targetAlreadyActive).toBe(true)
+  })
+
+  it('threads errorCode / failureKind / source on walletRejected and walletFailed', () => {
+    const rejected = normalizeEvent(
+      'walletRejected',
+      {
+        handoffId: 'h-1',
+        operation: 'signMessage',
+        durationMs: 5,
+        connectionMode: 'injected',
+        timedOut: false,
+        errorCode: '4001',
+        failureKind: 'user_rejected',
+        source: 'provider'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(rejected.errorCode).toBe('4001')
+    expect(rejected.failureKind).toBe('user_rejected')
+    expect(rejected.source).toBe('provider')
+
+    const failed = normalizeEvent(
+      'walletFailed',
+      {
+        handoffId: 'h-1',
+        operation: 'signMessage',
+        durationMs: 5,
+        error: { type: 'unknown', message: 'boom' },
+        connectionMode: 'injected',
+        timedOut: false,
+        failureKind: 'unknown',
+        source: 'unknown'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(failed.failureKind).toBe('unknown')
+    expect(failed.source).toBe('unknown')
+  })
+
+  it('summarizes capabilitiesUpdated to per-chain supported feature names', () => {
+    const out = normalizeEvent(
+      'capabilitiesUpdated',
+      {
+        capabilities: {
+          'eip155:8453': {
+            atomic: { status: 'supported' },
+            paymasterService: { status: 'unsupported' }
+          },
+          'eip155:1': { atomic: { status: 'ready' } }
+        }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.capabilities).toEqual({
+      'eip155:8453': ['atomic'],
+      'eip155:1': ['atomic']
+    })
+  })
+
+  it('threads taxonomy + networkMismatch on an `error` event (delta A)', () => {
+    const out = normalizeEvent(
+      'error',
+      {
+        error: {
+          type: 'unknown',
+          message:
+            'No common supported network found between wallet and configured networks'
+        },
+        operation: 'connect',
+        failureKind: 'no_common_network',
+        source: 'connector',
+        networkMismatch: {
+          walletNetworkIds: ['eip155:1', 'eip155:137'],
+          configuredNetworkIds: ['solana:101']
+        }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.operation).toBe('connect')
+    expect(out.failureKind).toBe('no_common_network')
+    expect(out.source).toBe('connector')
+    expect(out.networkMismatch).toEqual({
+      walletNetworkIds: ['eip155:1', 'eip155:137'],
+      configuredNetworkIds: ['solana:101']
+    })
+  })
+
+  it('carries the discovery summary on walletsDetected, never the wallet list', () => {
+    const out = normalizeEvent(
+      'walletsDetected',
+      {
+        wallets: [{ id: 'leaky', name: 'Leaky' } as never],
+        discovery: { solana: { requested: 2, matched: 0 } }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.discovery).toEqual({ solana: { requested: 2, matched: 0 } })
+    // The raw wallet list must NOT ride along.
+    expect(JSON.stringify(out)).not.toContain('leaky')
+  })
+
+  it('normalizes walletDiscoveryFailed with scrubbed message + routing (P5)', () => {
+    const out = normalizeEvent(
+      'walletDiscoveryFailed',
+      {
+        namespace: 'tvm',
+        connectionMode: 'tonConnect',
+        error: { type: 'unknown', message: 'bridge unreachable' }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.namespace).toBe('tvm')
+    expect(out.connectionMode).toBe('tonConnect')
+    expect(out.error?.message).toBe('bridge unreachable')
+  })
+
+  it('normalizes lifecycle events with routing only, no address (P2)', () => {
+    const acct = normalizeEvent(
+      'walletAccountChanged',
+      { connectionMode: 'injected', walletId: 'metamask', namespace: 'eip155' },
+      SDK_SESSION,
+      NOW
+    )
+    expect(acct).toEqual({
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
+      uwcVersion: UWC_CORE_VERSION,
+      name: 'walletAccountChanged',
+      sdkSessionId: SDK_SESSION,
+      timestamp: NOW,
+      connectionMode: 'injected',
+      walletId: 'metamask',
+      namespace: 'eip155'
+    })
+
+    const chain = normalizeEvent(
+      'walletChainChanged',
+      {
+        connectionMode: 'injected',
+        namespace: 'eip155',
+        chainId: 'eip155:8453'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(chain.chainId).toBe('eip155:8453')
+  })
+
+  it('normalizes lifecycleTelemetryUnavailable with reason + runtime (P2)', () => {
+    const out = normalizeEvent(
+      'lifecycleTelemetryUnavailable',
+      {
+        reason: 'provider_subscription_unavailable',
+        connectionMode: 'walletConnect',
+        namespace: 'eip155',
+        runtime: 'iframe'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.reason).toBe('provider_subscription_unavailable')
+    expect(out.runtime).toBe('iframe')
+  })
+
+  it('normalizes bridgeError with source/failureKind + scrubbed message (P6)', () => {
+    const out = normalizeEvent(
+      'bridgeError',
+      {
+        namespace: 'tron',
+        error: {
+          type: 'unknown',
+          message: 'discoverTronWallets is not a function'
+        }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.namespace).toBe('tron')
+    expect(out.source).toBe('bridge')
+    expect(out.failureKind).toBe('bridge_error')
+    expect(out.error?.message).toBe('discoverTronWallets is not a function')
+  })
+
+  it('normalizes relayError as a walletConnect network failure, message scrubbed', () => {
+    const out = normalizeEvent(
+      'relayError',
+      {
+        error: {
+          type: 'unknown',
+          message:
+            'WebSocket connection closed abnormally with code: 3000 (JWT validation error: JWT Token is not yet valid) 0xAbC1230000000000000000000000000000000000'
+        }
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.connectionMode).toBe('walletConnect')
+    expect(out.source).toBe('provider')
+    expect(out.failureKind).toBe('network_error')
+    // The diagnostic close code survives; a stray address in the message does not.
+    expect(out.error?.message).toContain('3000')
+    expect(JSON.stringify(out)).not.toContain('0xAbC123')
+  })
+
+  it('carries handoffCovered on an error record that duplicates a funnel terminal', () => {
+    const out = normalizeEvent(
+      'error',
+      {
+        error: { type: 'unknown', message: 'wallet exploded' },
+        operation: 'signMessage',
+        handoffCovered: true
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect(out.handoffCovered).toBe(true)
+  })
+
+  it('omits handoffCovered on a pre-wallet error record (no duplicate terminal)', () => {
+    const out = normalizeEvent(
+      'error',
+      {
+        error: { type: 'unknown', message: 'No provider available' },
+        operation: 'signMessage'
+      },
+      SDK_SESSION,
+      NOW
+    )
+    expect('handoffCovered' in out).toBe(false)
+  })
+})