@meshconnect/uwc-core 1.0.0 → 1.0.1-snapshot.c7e65ce

package/src/observability/telemetry.ts

@@ -0,0 +1,211 @@
+import type {
+  ConnectionMode,
+  WalletError,
+  WalletFlowType,
+  Platform,
+  LogLevel,
+  Namespace,
+  NetworkId
+} from '@meshconnect/uwc-types'
+import type { UWCEventName, UWCEventMap, UWCOperation } from '../events'
+import { scrubMessage } from './scrub'
+
+/**
+ * A normalized, PII-safe telemetry record derived from a `UWCEventMap` event.
+ *
+ * This is the ONLY shape that reaches `observer.onEvent`. It is the PII boundary:
+ * it has no field for a signing payload, signature, raw transaction, or wallet
+ * address — leaking those is structurally impossible, not merely discouraged.
+ */
+export interface UWCTelemetryEvent {
+  /** The originating event name. */
+  name: UWCEventName
+  /** Per-connector-instance correlation id (stamped on every event). */
+  sdkSessionId: string
+  /** ms since epoch when the record was produced. */
+  timestamp: number
+  /** Wallet-boundary op, when the event relates to one. */
+  operation?: UWCOperation | undefined
+  connectionMode?: ConnectionMode | undefined
+  /** CAIP namespace (eip155 | solana | tron | tvm …) — never an address. */
+  namespace?: Namespace | undefined
+  /** CAIP chain id (e.g. `eip155:1`) — never an address. */
+  chainId?: NetworkId | undefined
+  /** Catalog wallet id — never an address. */
+  walletId?: string | undefined
+  /** Correlates a handoff start with its terminal. */
+  handoffId?: string | undefined
+  durationMs?: number | undefined
+  walletFlowType?: WalletFlowType | undefined
+  platform?: Platform | undefined
+  /** Present on failure events. `message` is scrubbed before egress. */
+  error?: WalletError | undefined
+  /** Log level, present only for `name === 'log'`. */
+  level?: LogLevel | undefined
+}
+
+/**
+ * Vendor-agnostic telemetry sink. Consumers implement; UWC ships no vendor SDK.
+ * Both methods are optional and called best-effort (throws are swallowed upstream).
+ *
+ * CONTRACT — both methods are invoked **synchronously on the wallet-operation
+ * path**. A terminal event (e.g. `walletSucceeded`) fires between the wallet
+ * returning a result and that result reaching the caller, so a slow handler adds
+ * latency to connect / sign / sendTransaction. Keep handlers **non-blocking**:
+ * hand off to a queue-backed sink (Datadog `addAction`, Segment `track`, etc. are
+ * already non-blocking) or defer heavy work yourself — e.g.
+ * `onEvent: e => queueMicrotask(() => doHeavyWork(e))`. Do not perform synchronous
+ * network/IO or expensive serialization inline.
+ */
+export interface UWCObserver {
+  /** A normalized, PII-safe event. Forward to Datadog / Amplitude / Segment / … (non-blocking). */
+  onEvent?(event: UWCTelemetryEvent): void
+  /** A log line (all levels). `args` is already scrubbed. Keep non-blocking. */
+  onLog?(level: LogLevel, message: string, args: unknown[]): void
+}
+
+/**
+ * Best-effort coarse runtime surface. HEURISTIC — user agents lie and in-app
+ * browsers are hard to detect; treat `webview` as a hint, not a guarantee.
+ * Never returns the raw UA (PII / high-cardinality).
+ */
+export function derivePlatform(): Platform {
+  if (typeof navigator === 'undefined' || !navigator.userAgent) return 'unknown'
+  const ua = navigator.userAgent
+  const isIOS = /iPhone|iPad|iPod/i.test(ua)
+  const isAndroid = /Android/i.test(ua)
+  // Android in-app browsers tag the UA with `; wv`; iOS WKWebViews lack `Safari`.
+  const isWebview =
+    (isAndroid && /; wv\)/i.test(ua)) || (isIOS && !/Safari/i.test(ua))
+  if (isWebview) return 'webview'
+  if (isIOS || isAndroid) return 'mobile'
+  return 'desktop'
+}
+
+/**
+ * Derive the flow taxonomy from connection mode + surface. HEURISTIC — UWC does
+ * not always know whether a WalletConnect handoff used a deeplink vs a QR scan;
+ * we infer from the platform (mobile ⇒ deeplink, desktop ⇒ QR), matching link-v2's
+ * historical intent. Consumers with better context may override downstream.
+ */
+export function deriveWalletFlowType(
+  connectionMode: ConnectionMode,
+  platform: Platform
+): WalletFlowType {
+  const isDesktop = platform === 'desktop'
+  switch (connectionMode) {
+    case 'injected':
+      // Injected on a phone almost always means we're inside a wallet's browser.
+      return isDesktop ? 'browser_extension_flow' : 'in_wallet_browser_flow'
+    case 'walletConnect':
+      return isDesktop
+        ? 'wallet_connect_qr_flow'
+        : 'wallet_connect_deep_link_flow'
+    case 'tonConnect':
+      return isDesktop ? 'ton_connect_qr_flow' : 'ton_connect_deep_link_flow'
+    default:
+      return 'unknown'
+  }
+}
+
+/**
+ * Map a raw `UWCEventMap` event to its PII-safe `UWCTelemetryEvent`.
+ *
+ * Per-event allow-listing: only known-safe fields are copied. Payloads carrying a
+ * `Session`/`Network` (which include the wallet address) are reduced to
+ * `namespace` + `chainId` + `walletId`. Unknown/noisy payloads collapse to just
+ * the name. `error.message` is scrubbed.
+ */
+export function normalizeEvent<K extends UWCEventName>(
+  name: K,
+  data: UWCEventMap[K],
+  sdkSessionId: string,
+  now: number
+): UWCTelemetryEvent {
+  const base: UWCTelemetryEvent = { name, sdkSessionId, timestamp: now }
+
+  switch (name) {
+    case 'connecting': {
+      const d = data as UWCEventMap['connecting']
+      return {
+        ...base,
+        operation: 'connect',
+        connectionMode: d.connectionMode,
+        walletId: d.walletId
+      }
+    }
+    case 'connected':
+    case 'sessionChanged': {
+      const d = data as UWCEventMap['connected']
+      const session = d.session
+      return {
+        ...base,
+        connectionMode: session.connectionMode ?? undefined,
+        namespace: session.activeNetwork?.namespace,
+        chainId: session.activeNetwork?.id,
+        walletId: session.activeWallet?.id
+      }
+    }
+    case 'networkSwitched': {
+      const d = data as UWCEventMap['networkSwitched']
+      return {
+        ...base,
+        operation: 'switchNetwork',
+        namespace: d.network.namespace,
+        chainId: d.network.id
+      }
+    }
+    case 'connectionUri': {
+      // Carry the mode but NEVER the URI itself (a relay/pairing string).
+      const d = data as UWCEventMap['connectionUri']
+      return { ...base, connectionMode: d.connectionMode }
+    }
+    case 'error': {
+      const d = data as UWCEventMap['error']
+      return {
+        ...base,
+        operation: d.operation,
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    case 'awaitingWallet': {
+      const d = data as UWCEventMap['awaitingWallet']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        walletFlowType: d.walletFlowType,
+        platform: d.platform
+      }
+    }
+    case 'walletSucceeded':
+    case 'walletRejected':
+    case 'walletTimedOut': {
+      const d = data as UWCEventMap['walletSucceeded']
+      return {
+        ...base,
+        operation: d.operation,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs
+      }
+    }
+    case 'walletFailed': {
+      const d = data as UWCEventMap['walletFailed']
+      return {
+        ...base,
+        operation: d.operation,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs,
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    default:
+      // ready / walletsDetected / disconnected / networkSwitching /
+      // capabilitiesUpdated / change / log — name only (log goes via onLog).
+      return base
+  }
+}

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

@@ -81,7 +81,8 @@ describe('ConnectionService', () => {
       sessionManager,
       connectors,
       false,
-      eventManager
+      eventManager,
+      60_000
     )
   })
 
@@ -193,6 +194,70 @@ describe('ConnectionService', () => {
       expect(connectingListener).not.toHaveBeenCalled()
     })
 
+    it('does NOT emit awaitingWallet when validation throws (pre-wallet failure stays out of the funnel)', async () => {
+      const awaiting = vi.fn()
+      const failed = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      eventManager.on('walletFailed', failed)
+
+      await expect(
+        connectionService.connect('injected', 'no-such-wallet', 'eip155:1')
+      ).rejects.toThrow()
+
+      expect(awaiting).not.toHaveBeenCalled()
+      expect(failed).not.toHaveBeenCalled()
+    })
+
+    it('emits awaitingWallet + walletSucceeded around the wallet call, with resolved facets', async () => {
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['eip155:1']
+      } as any
+      const events: Array<{ name: string; data: any }> = []
+      eventManager.on('awaitingWallet', d =>
+        events.push({ name: 'awaitingWallet', data: d })
+      )
+      eventManager.on('walletSucceeded', d =>
+        events.push({ name: 'walletSucceeded', data: d })
+      )
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+
+      expect(events.map(e => e.name)).toEqual([
+        'awaitingWallet',
+        'walletSucceeded'
+      ])
+      const awaiting = events[0].data
+      expect(awaiting.operation).toBe('connect')
+      expect(awaiting.namespace).toBe('eip155')
+      expect(awaiting.chainId).toBe('eip155:1')
+      expect(awaiting.handoffId).toBe(events[1].data.handoffId)
+    })
+
+    it('emits awaitingWallet + walletFailed when the connector call throws', async () => {
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['eip155:1']
+      } as any
+      const awaiting = vi.fn()
+      const failed = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      eventManager.on('walletFailed', failed)
+      mockConnector.connect = vi
+        .fn()
+        .mockRejectedValue(new Error('wallet exploded'))
+
+      await expect(
+        connectionService.connect('injected', 'metamask', 'eip155:1')
+      ).rejects.toThrow('wallet exploded')
+
+      expect(awaiting).toHaveBeenCalledTimes(1)
+      expect(failed).toHaveBeenCalledTimes(1)
+    })
+
     it('rejects mid-flight when AbortSignal fires during connector.connect', async () => {
       wallets[0].extensionInjectedProvider = {
         supportedNetworkIds: ['eip155:1']

package/src/services/connection-service.ts

@@ -13,6 +13,7 @@ import type {
 import type { SessionManager } from '../managers/session-manager'
 import type { EventManager } from '../managers/event-manager'
 import { raceAbort } from '../utils/abort'
+import { instrumentHandoff } from '../observability/instrument-handoff'
 
 export interface ServiceOptions {
   signal?: AbortSignal
@@ -27,7 +28,9 @@ export class ConnectionService {
     private sessionManager: SessionManager,
     private connectors: Map<ConnectionMode, Connector>,
     private usingIntegratedBrowser: boolean,
-    private eventManager: EventManager
+    private eventManager: EventManager,
+    // Observational wallet-response deadline for the handoff timeout marker.
+    private walletResponseTimeoutMs: number
   ) {}
 
   async connect(
@@ -60,37 +63,56 @@ export class ConnectionService {
 
     let result
     try {
-      // Race the connector call against the AbortSignal so a mid-flight abort
-      // (e.g. user cancels the WalletConnect QR while the prompt is open)
-      // rejects the caller's await promptly. The underlying wallet prompt
-      // itself can't be cancelled, but the dapp UI is no longer blocked on it.
-      if (connectionMode === 'injected') {
-        result = await raceAbort(
-          connector.connect(
-            network,
-            provider as
-              | ExtensionInjectedProvider
-              | IntegratedBrowserInjectedProvider
-          ),
-          options?.signal
-        )
-      } else if (
-        connectionMode === 'tonConnect' ||
-        connectionMode === 'walletConnect'
-      ) {
-        result = await raceAbort(
-          this.connectWithURIPoll(
-            connector,
-            network,
-            provider,
-            connectionMode,
-            options?.signal
-          ),
-          options?.signal
-        )
-      } else {
-        throw new Error(`Unsupported connection mode: ${connectionMode}`)
-      }
+      // Instrument the wallet hand-off HERE — after validation + the `connecting`
+      // emit — so `awaitingWallet` marks the real wallet boundary. A pre-wallet
+      // lookup/validation failure throws above and never enters the funnel. The
+      // resolved `network` gives accurate namespace/chainId facets.
+      result = await instrumentHandoff(
+        {
+          eventManager: this.eventManager,
+          timeoutMs: this.walletResponseTimeoutMs
+        },
+        {
+          operation: 'connect',
+          connectionMode,
+          walletId,
+          namespace: network.namespace,
+          chainId: network.id
+        },
+        async () => {
+          // Race the connector call against the AbortSignal so a mid-flight abort
+          // (e.g. user cancels the WalletConnect QR while the prompt is open)
+          // rejects the caller's await promptly. The underlying wallet prompt
+          // itself can't be cancelled, but the dapp UI is no longer blocked on it.
+          if (connectionMode === 'injected') {
+            return await raceAbort(
+              connector.connect(
+                network,
+                provider as
+                  | ExtensionInjectedProvider
+                  | IntegratedBrowserInjectedProvider
+              ),
+              options?.signal
+            )
+          } else if (
+            connectionMode === 'tonConnect' ||
+            connectionMode === 'walletConnect'
+          ) {
+            return await raceAbort(
+              this.connectWithURIPoll(
+                connector,
+                network,
+                provider,
+                connectionMode,
+                options?.signal
+              ),
+              options?.signal
+            )
+          } else {
+            throw new Error(`Unsupported connection mode: ${connectionMode}`)
+          }
+        }
+      )
     } catch (error) {
       this.activeConnector = null
       throw error

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

@@ -84,7 +84,8 @@ describe('NetworkSwitchService', () => {
       sessionManager,
       connectors,
       false,
-      eventManager
+      eventManager,
+      60_000
     )
   })
 
@@ -184,4 +185,53 @@ describe('NetworkSwitchService', () => {
       "Wallet 'metamask' does not have a provider for injected mode"
     )
   })
+
+  it('does NOT emit awaitingWallet when validation throws (no active wallet)', async () => {
+    const awaiting = vi.fn()
+    eventManager.on('awaitingWallet', awaiting)
+
+    await expect(
+      networkSwitchService.switchNetwork('eip155:1')
+    ).rejects.toThrow()
+
+    expect(awaiting).not.toHaveBeenCalled()
+  })
+
+  it('emits awaitingWallet + walletSucceeded around the wallet switch call', async () => {
+    sessionManager.updateSession({
+      connectionMode: 'injected',
+      activeWallet: {
+        id: 'metamask',
+        name: 'MetaMask',
+        metadata: {
+          icon: 'test',
+          downloadUrl: 'test',
+          supportedChains: ['eip155:1', 'eip155:137']
+        },
+        extensionInjectedProvider: {
+          supportedNetworkIds: ['eip155:1', 'eip155:137']
+        }
+      } as any
+    })
+    mockConnector.switchNetwork = vi.fn().mockResolvedValue({
+      address: '0xabc',
+      availableAddresses: [{ address: '0xabc', networkId: 'eip155:137' }]
+    })
+    const events: Array<{ name: string; data: any }> = []
+    eventManager.on('awaitingWallet', d =>
+      events.push({ name: 'awaitingWallet', data: d })
+    )
+    eventManager.on('walletSucceeded', d =>
+      events.push({ name: 'walletSucceeded', data: d })
+    )
+
+    await networkSwitchService.switchNetwork('eip155:137')
+
+    expect(events.map(e => e.name)).toEqual([
+      'awaitingWallet',
+      'walletSucceeded'
+    ])
+    expect(events[0].data.operation).toBe('switchNetwork')
+    expect(events[0].data.chainId).toBe('eip155:137')
+  })
 })

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

@@ -12,6 +12,7 @@ import type {
 import type { SessionManager } from '../managers/session-manager'
 import type { EventManager } from '../managers/event-manager'
 import type { ServiceOptions } from './connection-service'
+import { instrumentHandoff } from '../observability/instrument-handoff'
 
 export class NetworkSwitchService {
   private isLoading = false
@@ -22,7 +23,9 @@ export class NetworkSwitchService {
     private sessionManager: SessionManager,
     private connectors: Map<ConnectionMode, Connector>,
     private usingIntegratedBrowser: boolean,
-    private eventManager: EventManager
+    private eventManager: EventManager,
+    // Observational wallet-response deadline for the handoff timeout marker.
+    private walletResponseTimeoutMs: number
   ) {}
 
   getLoadingState() {
@@ -115,28 +118,45 @@ export class NetworkSwitchService {
         isWaitingForUserApproval: requiresApproval
       })
 
-      // Perform the network switch and get the new address
-      // Pass the appropriate provider based on connection mode
-      let result
-      if (
-        (session.connectionMode === 'injected' ||
-          session.connectionMode === 'tonConnect') &&
-        provider
-      ) {
-        result = await activeConnector.switchNetwork(
-          network,
-          provider as
-            | ExtensionInjectedProvider
-            | IntegratedBrowserInjectedProvider
-        )
-      } else if (session.connectionMode === 'walletConnect' && provider) {
-        result = await activeConnector.switchNetwork(
-          network,
-          provider as WalletConnectProvider
-        )
-      } else {
-        result = await activeConnector.switchNetwork(network)
-      }
+      // Perform the network switch and get the new address. Instrument the
+      // wallet hand-off HERE — after validation + the `networkSwitching` emit —
+      // so `awaitingWallet` marks the real wallet boundary; pre-wallet validation
+      // failures throw above and never enter the funnel.
+      // Pass the appropriate provider based on connection mode.
+      const result = await instrumentHandoff(
+        {
+          eventManager: this.eventManager,
+          timeoutMs: this.walletResponseTimeoutMs
+        },
+        {
+          operation: 'switchNetwork',
+          connectionMode: session.connectionMode,
+          walletId: currentWallet.id,
+          namespace: network.namespace,
+          chainId: network.id
+        },
+        async () => {
+          if (
+            (session.connectionMode === 'injected' ||
+              session.connectionMode === 'tonConnect') &&
+            provider
+          ) {
+            return await activeConnector.switchNetwork(
+              network,
+              provider as
+                | ExtensionInjectedProvider
+                | IntegratedBrowserInjectedProvider
+            )
+          } else if (session.connectionMode === 'walletConnect' && provider) {
+            return await activeConnector.switchNetwork(
+              network,
+              provider as WalletConnectProvider
+            )
+          } else {
+            return await activeConnector.switchNetwork(network)
+          }
+        }
+      )
 
       options?.signal?.throwIfAborted()