@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/observability/instrument-handoff.test.ts

@@ -0,0 +1,397 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import { EventManager } from '../managers/event-manager'
+import {
+  instrumentHandoff,
+  hasHandoffTerminal,
+  type HandoffContext
+} from './instrument-handoff'
+
+const CTX: HandoffContext = {
+  operation: 'signMessage',
+  connectionMode: 'injected',
+  walletId: 'metamask',
+  namespace: 'eip155',
+  chainId: 'eip155:1'
+}
+
+function record(em: EventManager) {
+  const seen: Array<{ name: string; data: unknown }> = []
+  for (const name of [
+    'awaitingWallet',
+    'walletSucceeded',
+    'walletRejected',
+    'walletFailed',
+    'walletTimedOut'
+  ] as const) {
+    em.on(name, data => seen.push({ name, data }))
+  }
+  return seen
+}
+
+describe('instrumentHandoff', () => {
+  it('emits awaitingWallet then walletSucceeded on success', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const result = await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      CTX,
+      async () => 'sig'
+    )
+    expect(result).toBe('sig')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletSucceeded'])
+    const start = seen[0].data as { handoffId: string }
+    const end = seen[1].data as { handoffId: string; timedOut: boolean }
+    expect(end.handoffId).toBe(start.handoffId)
+    // A fast op never tripped the marker.
+    expect(end.timedOut).toBe(false)
+  })
+
+  it('carries targetAlreadyActive through awaitingWallet and the terminal', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      { ...CTX, operation: 'switchNetwork', targetAlreadyActive: true },
+      async () => 'ok'
+    )
+    expect(
+      (seen[0].data as { targetAlreadyActive?: boolean }).targetAlreadyActive
+    ).toBe(true)
+    expect(
+      (seen[1].data as { targetAlreadyActive?: boolean }).targetAlreadyActive
+    ).toBe(true)
+  })
+
+  it('classifies a user rejection (4001) with errorCode/failureKind/source', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw Object.assign(new Error('rejected'), { code: 4001 })
+      })
+    ).rejects.toThrow()
+    const rejected = seen[1].data as {
+      errorCode?: string
+      failureKind?: string
+      source?: string
+    }
+    expect(rejected.errorCode).toBe('4001')
+    expect(rejected.failureKind).toBe('user_rejected')
+    expect(rejected.source).toBe('provider')
+  })
+
+  it('classifies an unmapped failure as unknown (no guess)', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new Error('rpc exploded')
+      })
+    ).rejects.toThrow()
+    const failed = seen[1].data as {
+      errorCode?: string
+      failureKind?: string
+      source?: string
+    }
+    expect(failed.errorCode).toBeUndefined()
+    expect(failed.failureKind).toBe('unknown')
+    expect(failed.source).toBe('unknown')
+  })
+
+  it('stamps every terminal with the same routing facets as awaitingWallet', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      CTX,
+      async () => 'sig'
+    )
+    const routing = {
+      connectionMode: CTX.connectionMode,
+      walletId: CTX.walletId,
+      namespace: CTX.namespace,
+      chainId: CTX.chainId
+    }
+    // awaitingWallet (start) and walletSucceeded (terminal) both self-describe.
+    expect(seen[0].data).toMatchObject(routing)
+    expect(seen[1].data).toMatchObject(routing)
+  })
+
+  it('emits walletRejected for an explicit user rejection', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new WalletConnectorError({
+          type: 'rejected',
+          message: 'user said no'
+        })
+      })
+    ).rejects.toThrow('user said no')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletRejected'])
+  })
+
+  it('emits walletRejected for a raw EIP-1193 4001', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw Object.assign(new Error('rejected'), { code: 4001 })
+      })
+    ).rejects.toThrow()
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletRejected'])
+  })
+
+  it('emits walletFailed (with scrubbed error) for any other error', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new Error('rpc exploded')
+      })
+    ).rejects.toThrow('rpc exploded')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletFailed'])
+    const failed = seen[1].data as { error: { type: string; message: string } }
+    expect(failed.error.type).toBe('unknown')
+    expect(failed.error.message).toBe('rpc exploded')
+  })
+
+  it('emits NO terminal for an intentional abort', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new DOMException('Aborted', 'AbortError')
+      })
+    ).rejects.toThrow()
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet'])
+  })
+
+  it('emits NO terminal for a custom abort(reason) when the signal is threaded through', async () => {
+    // `controller.abort(new Error('nav away'))` rejects with the CUSTOM reason —
+    // not an AbortError by name — so the name check alone would mis-file the
+    // cancellation as a walletFailed. The signal is the reliable evidence.
+    const em = new EventManager()
+    const seen = record(em)
+    const controller = new AbortController()
+    const reason = new Error('nav away')
+    await expect(
+      instrumentHandoff(
+        { eventManager: em, timeoutMs: 0, signal: controller.signal },
+        CTX,
+        async () => {
+          controller.abort(reason)
+          throw reason
+        }
+      )
+    ).rejects.toThrow('nav away')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet'])
+    expect(hasHandoffTerminal(reason)).toBe(false)
+  })
+
+  it('still emits walletFailed for a non-abort error while a threaded signal is NOT aborted', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const controller = new AbortController()
+    await expect(
+      instrumentHandoff(
+        { eventManager: em, timeoutMs: 0, signal: controller.signal },
+        CTX,
+        async () => {
+          throw new Error('rpc exploded')
+        }
+      )
+    ).rejects.toThrow('rpc exploded')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletFailed'])
+  })
+
+  it('a custom abort(reason) WITHOUT a threaded signal still lands as walletFailed (documented residual)', async () => {
+    // With no signal to consult, a custom reason is indistinguishable from a
+    // real wallet error — the caller opts into precise cancellation telemetry
+    // by passing the signal through the op's options.
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new Error('nav away')
+      })
+    ).rejects.toThrow('nav away')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletFailed'])
+  })
+
+  describe('timeout marker', () => {
+    beforeEach(() => vi.useFakeTimers())
+    afterEach(() => vi.useRealTimers())
+
+    it('fires walletTimedOut while pending, then still resolves with walletSucceeded', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      let resolveFn: (v: string) => void = () => {}
+      const promise = instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        CTX,
+        () => new Promise<string>(r => (resolveFn = r))
+      )
+      // Deadline passes with the op still pending → side marker fires.
+      await vi.advanceTimersByTimeAsync(1000)
+      expect(seen.map(s => s.name)).toContain('walletTimedOut')
+      const marker = seen.find(s => s.name === 'walletTimedOut')!.data as {
+        timeoutMs: number
+      }
+      expect(marker.timeoutMs).toBe(1000)
+      // The op then completes → real terminal still fires.
+      resolveFn('late-sig')
+      await expect(promise).resolves.toBe('late-sig')
+      expect(seen.map(s => s.name)).toEqual([
+        'awaitingWallet',
+        'walletTimedOut',
+        'walletSucceeded'
+      ])
+      // The late terminal records that it overran the deadline.
+      const late = seen.find(s => s.name === 'walletSucceeded')!.data as {
+        timedOut: boolean
+        timeoutMs?: number
+      }
+      expect(late.timedOut).toBe(true)
+      expect(late.timeoutMs).toBe(1000)
+    })
+
+    it('does NOT fire walletTimedOut for an op that settles before the deadline', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      await instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        CTX,
+        async () => 'fast'
+      )
+      await vi.advanceTimersByTimeAsync(5000)
+      expect(seen.map(s => s.name)).toEqual([
+        'awaitingWallet',
+        'walletSucceeded'
+      ])
+    })
+
+    it('never arms the timer for tonConnect (already bounded by TON)', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      let resolveFn: (v: string) => void = () => {}
+      const promise = instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        { ...CTX, connectionMode: 'tonConnect' },
+        () => new Promise<string>(r => (resolveFn = r))
+      )
+      await vi.advanceTimersByTimeAsync(5000)
+      expect(seen.map(s => s.name)).not.toContain('walletTimedOut')
+      resolveFn('ok')
+      await promise
+    })
+  })
+
+  describe('focus facts during a pending handoff (P4)', () => {
+    const setVisibility = (state: string) =>
+      Object.defineProperty(document, 'visibilityState', {
+        value: state,
+        configurable: true
+      })
+
+    afterEach(() => setVisibility('visible'))
+
+    it('records a tab-hide while pending and stops once the op settles', async () => {
+      const em = new EventManager()
+      const focus: string[] = []
+      em.on('pageHiddenDuringHandoff', () => focus.push('hidden'))
+      em.on('pageVisibleDuringHandoff', () => focus.push('visible'))
+
+      let resolveFn: (v: string) => void = () => {}
+      const handoff = instrumentHandoff(
+        { eventManager: em, timeoutMs: 0 },
+        CTX,
+        () => new Promise<string>(r => (resolveFn = r))
+      )
+
+      // While pending, a tab-hide records the app-switch fact.
+      setVisibility('hidden')
+      document.dispatchEvent(new Event('visibilitychange'))
+      expect(focus).toEqual(['hidden'])
+
+      // After the op settles the listeners are torn down — later transitions are
+      // NOT recorded (focus is observed only during the blind window).
+      resolveFn('ok')
+      await handoff
+      setVisibility('visible')
+      document.dispatchEvent(new Event('visibilitychange'))
+      expect(focus).toEqual(['hidden'])
+    })
+  })
+
+  describe('hasHandoffTerminal', () => {
+    // The marker lets `emitError` tag its back-compat `error` record as
+    // `handoffCovered` when a funnel terminal already reported the same failure
+    // — the structural fix for dashboard double-counting.
+    it('marks an error that produced a walletFailed terminal', async () => {
+      const em = new EventManager()
+      const boom = new Error('wallet exploded')
+
+      await expect(
+        instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, () =>
+          Promise.reject(boom)
+        )
+      ).rejects.toThrow('wallet exploded')
+
+      expect(hasHandoffTerminal(boom)).toBe(true)
+    })
+
+    it('marks an error that produced a walletRejected terminal', async () => {
+      const em = new EventManager()
+      const rejection = new WalletConnectorError({
+        type: 'rejected',
+        message: 'User rejected'
+      })
+
+      await expect(
+        instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, () =>
+          Promise.reject(rejection)
+        )
+      ).rejects.toThrow('User rejected')
+
+      expect(hasHandoffTerminal(rejection)).toBe(true)
+    })
+
+    it('does NOT mark an abort (no terminal was emitted)', async () => {
+      const em = new EventManager()
+      const abort = new DOMException('Aborted', 'AbortError')
+
+      await expect(
+        instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, () =>
+          Promise.reject(abort)
+        )
+      ).rejects.toThrow()
+
+      expect(hasHandoffTerminal(abort)).toBe(false)
+    })
+
+    it('does NOT mark an error that never went through a handoff', () => {
+      expect(hasHandoffTerminal(new Error('validation failed'))).toBe(false)
+      expect(hasHandoffTerminal('a string throw')).toBe(false)
+      expect(hasHandoffTerminal(null)).toBe(false)
+    })
+
+    it('pins the primitive-throw gap: the terminal fires but the value cannot be marked', async () => {
+      // A WeakSet cannot hold primitives, so a wallet that rejects with a bare
+      // string produces a walletFailed terminal AND an uncovered back-compat
+      // `error` record — a documented double-count under the "terminals +
+      // uncovered error" metric. Wrapping the thrown value to make it markable
+      // would mutate what the caller receives, so the gap is accepted and pinned.
+      const em = new EventManager()
+      const seen = record(em)
+      await expect(
+        instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, () =>
+          Promise.reject('wallet said no')
+        )
+      ).rejects.toBe('wallet said no')
+      expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletFailed'])
+      expect(hasHandoffTerminal('wallet said no')).toBe(false)
+    })
+  })
+})

package/src/observability/instrument-handoff.ts

@@ -0,0 +1,231 @@
+import type {
+  ConnectionMode,
+  Namespace,
+  NetworkId,
+  Session
+} from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+import type { UWCOperation } from '../events'
+import { generateId } from '../utils/id'
+import {
+  classifyError,
+  isAbortError,
+  isUserRejection,
+  toWalletError
+} from '../utils/to-wallet-error'
+import { derivePlatform, deriveWalletFlowType } from './telemetry'
+import { trackFocusDuringHandoff } from './focus-tracker'
+
+/** Routing facets known at the moment of a wallet handoff. No address, no payload. */
+export interface HandoffContext {
+  operation: UWCOperation
+  connectionMode: ConnectionMode
+  walletId?: string | undefined
+  namespace?: Namespace | undefined
+  chainId?: NetworkId | undefined
+  /** switchNetwork only: target chain already the active one (no-op switch). */
+  targetAlreadyActive?: boolean | undefined
+}
+
+/** Build handoff routing facets from the active session (no address). */
+export function sessionHandoffContext(
+  operation: UWCOperation,
+  session: Session
+): HandoffContext {
+  return {
+    operation,
+    connectionMode: session.connectionMode ?? 'injected',
+    walletId: session.activeWallet?.id,
+    namespace: session.activeNetwork?.namespace,
+    chainId: session.activeNetwork?.id ?? undefined
+  }
+}
+
+/**
+ * Errors that already produced a funnel terminal (`walletRejected` /
+ * `walletFailed`). `emitError` reads this to tag its back-compat `error` record
+ * as `handoffCovered`, so a dashboard can count wallet failures from terminals
+ * and pre-wallet failures from `error` without double-counting. A WeakSet keyed
+ * on the error object — no mutation of the thrown value, and entries die with
+ * the error.
+ *
+ * DOCUMENTED GAP: a WeakSet cannot hold primitives. A wallet that rejects with
+ * a bare string/number still produces its terminal, but the façade's `error`
+ * record can't be marked — that failure double-counts under the "terminals +
+ * uncovered `error`" metric. Accepted: EIP-1193 requires object errors, and
+ * wrapping the thrown value to make it markable would mutate what the caller
+ * receives.
+ */
+const handoffTerminalErrors = new WeakSet<object>()
+
+/** Whether this thrown value already produced a handoff terminal. */
+export function hasHandoffTerminal(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    handoffTerminalErrors.has(error)
+  )
+}
+
+function markHandoffTerminal(error: unknown): void {
+  if (typeof error === 'object' && error !== null) {
+    handoffTerminalErrors.add(error)
+  }
+}
+
+export interface InstrumentHandoffOptions {
+  eventManager: EventManager
+  /**
+   * Deadline after which `walletTimedOut` fires as a SIDE marker (never rejects).
+   * `0` disables the marker. `tonConnect` is always skipped — TON bounds its own
+   * wallet response internally, so a second observational timer would be noise.
+   */
+  timeoutMs: number
+  /**
+   * The caller's cancellation signal, when the op accepts one. Consulted in the
+   * catch path: a rejection observed while the signal is aborted is treated as
+   * the cancellation itself (no terminal) even when the rejection value is a
+   * custom `abort(reason)` — which is NOT an AbortError by name.
+   */
+  signal?: AbortSignal | undefined
+  /** Clock injectable for deterministic tests. */
+  now?: () => number
+}
+
+/**
+ * Instrument one wallet-boundary op so the blind window is measured.
+ *
+ * Emits `awaitingWallet` immediately (before the await that hands control to the
+ * wallet), then exactly one terminal — `walletSucceeded` (success),
+ * `walletRejected` (explicit user no), or `walletFailed` (any other error) — all
+ * carrying the same `handoffId` and a `durationMs`. An intentional abort emits no
+ * terminal (the caller cancelled; it isn't a wallet outcome) — services check
+ * their signal AFTER this wrapper returns, so a wallet op that settled before
+ * the abort still records its truthful terminal first.
+ *
+ * A non-cancelling `walletTimedOut` marker fires if the deadline passes while the
+ * op is still pending; it is cleared the instant the op settles, so a fast op
+ * never false-fires it, and it NEVER rejects/aborts/mutates state — the wrapped
+ * promise stays the single terminal source of truth. This is a deliberate
+ * deviation from TON's cancelling `withWalletResponseTimeout`.
+ */
+export async function instrumentHandoff<T>(
+  options: InstrumentHandoffOptions,
+  context: HandoffContext,
+  fn: () => Promise<T>
+): Promise<T> {
+  const { eventManager, timeoutMs } = options
+  const now = options.now ?? Date.now
+
+  const handoffId = generateId()
+  const platform = derivePlatform()
+  const start = now()
+  // Flipped by the observational timeout timer; rides every terminal so a late
+  // completion is distinguishable from a fast one without a handoffId self-join.
+  let timedOut = false
+
+  eventManager.emit('awaitingWallet', {
+    operation: context.operation,
+    connectionMode: context.connectionMode,
+    walletId: context.walletId,
+    namespace: context.namespace,
+    chainId: context.chainId,
+    handoffId,
+    walletFlowType: deriveWalletFlowType(context.connectionMode, platform),
+    platform,
+    ...(context.targetAlreadyActive !== undefined && {
+      targetAlreadyActive: context.targetAlreadyActive
+    })
+  })
+
+  // Observe page-visibility transitions ONLY while this handoff is pending — the
+  // app-switch signal for deep-link flows (left for the wallet / came back). The
+  // teardown in `finally` removes the listeners the instant the op settles.
+  const stopFocus = trackFocusDuringHandoff(eventManager, handoffId, platform)
+
+  // Same routing facets as `awaitingWallet` so every terminal is self-describing
+  // (no handoffId self-join needed to know which wallet / chain / mode it closed).
+  const routing = {
+    connectionMode: context.connectionMode,
+    walletId: context.walletId,
+    namespace: context.namespace,
+    chainId: context.chainId,
+    ...(context.targetAlreadyActive !== undefined && {
+      targetAlreadyActive: context.targetAlreadyActive
+    })
+  }
+
+  const shouldTime = timeoutMs > 0 && context.connectionMode !== 'tonConnect'
+  const timer: ReturnType<typeof setTimeout> | undefined = shouldTime
+    ? setTimeout(() => {
+        timedOut = true
+        eventManager.emit('walletTimedOut', {
+          handoffId,
+          operation: context.operation,
+          durationMs: now() - start,
+          timeoutMs,
+          ...routing
+        })
+      }, timeoutMs)
+    : undefined
+
+  try {
+    const result = await fn()
+    eventManager.emit('walletSucceeded', {
+      handoffId,
+      operation: context.operation,
+      durationMs: now() - start,
+      timedOut,
+      timeoutMs: timedOut ? timeoutMs : undefined,
+      ...routing
+    })
+    return result
+  } catch (error) {
+    // Caller-driven cancellation isn't a wallet outcome — leave it unterminated,
+    // mirroring the façade's `emitError` AbortError skip. Checked BEFORE rejection
+    // is safe: real user rejections surface as WalletConnectorError{rejected} or
+    // EIP-1193 4001 (see isUserRejection), never as an AbortError — within UWC's
+    // dependency surface AbortError is produced only by the caller's AbortSignal.
+    // The signal covers `abort(customReason)`, whose rejection value carries the
+    // caller's own name; a real wallet failure that lands while the caller has
+    // already aborted is intentionally folded into the cancellation — the caller
+    // walked away, so the outcome no longer describes a user-visible interaction.
+    if (isAbortError(error) || options.signal?.aborted) throw error
+
+    const durationMs = now() - start
+    const { errorCode, failureKind, source } = classifyError(error)
+    // Either branch below emits a terminal for this error — record that so the
+    // façade's back-compat `error` event can mark itself as a duplicate.
+    markHandoffTerminal(error)
+    if (isUserRejection(error)) {
+      eventManager.emit('walletRejected', {
+        handoffId,
+        operation: context.operation,
+        durationMs,
+        timedOut,
+        timeoutMs: timedOut ? timeoutMs : undefined,
+        errorCode,
+        failureKind,
+        source,
+        ...routing
+      })
+    } else {
+      eventManager.emit('walletFailed', {
+        handoffId,
+        operation: context.operation,
+        durationMs,
+        error: toWalletError(error),
+        timedOut,
+        timeoutMs: timedOut ? timeoutMs : undefined,
+        errorCode,
+        failureKind,
+        source,
+        ...routing
+      })
+    }
+    throw error
+  } finally {
+    if (timer) clearTimeout(timer)
+    stopFocus()
+  }
+}