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

package/dist/utils/to-wallet-error.js

@@ -1,33 +0,0 @@
-import { WalletConnectorError } from '@meshconnect/uwc-types';
-/** Normalize any thrown value into the PII-light `WalletError` shape. */
-export function toWalletError(error) {
-    if (error instanceof WalletConnectorError) {
-        return { type: error.type, message: error.message };
-    }
-    return {
-        type: 'unknown',
-        message: error instanceof Error ? error.message : String(error)
-    };
-}
-/**
- * Whether a thrown value is an explicit user rejection. Connectors usually wrap
- * these as `WalletConnectorError{type:'rejected'}`, but a raw EIP-1193 reject
- * (code `4001`) or ethers' `ACTION_REJECTED` can also reach the façade.
- */
-export function isUserRejection(error) {
-    if (error instanceof WalletConnectorError)
-        return error.type === 'rejected';
-    const code = error?.code;
-    return code === 4001 || code === 'ACTION_REJECTED';
-}
-/**
- * Whether a thrown value is an intentional cancellation (AbortSignal / fetch
- * abort). Matched by `name` rather than `instanceof Error` because a real abort is
- * a `DOMException`, which is not an `Error` subclass in every runtime.
- */
-export function isAbortError(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        error.name === 'AbortError');
-}
-//# sourceMappingURL=to-wallet-error.js.map

package/dist/utils/to-wallet-error.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"to-wallet-error.js","sourceRoot":"","sources":["../../src/utils/to-wallet-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,wBAAwB,CAAA;AAE/E,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;IACrD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KAChE,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,oBAAoB;QAAE,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,CAAA;IAC3E,MAAM,IAAI,GAAI,KAA+C,EAAE,IAAI,CAAA;IACnE,OAAO,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,iBAAiB,CAAA;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA4B,CAAC,IAAI,KAAK,YAAY,CACpD,CAAA;AACH,CAAC"}

package/src/logger/create-logger.test.ts

@@ -1,111 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest'
-import type { Logger } from '@meshconnect/uwc-types'
-import { createLogger } from './create-logger'
-
-function makeSink(): Logger & { calls: Record<string, unknown[][]> } {
-  const calls: Record<string, unknown[][]> = {
-    debug: [],
-    info: [],
-    warn: [],
-    error: []
-  }
-  return {
-    calls,
-    debug: (...a) => calls.debug.push(a),
-    info: (...a) => calls.info.push(a),
-    warn: (...a) => calls.warn.push(a),
-    error: (...a) => calls.error.push(a)
-  }
-}
-
-describe('createLogger', () => {
-  afterEach(() => {
-    delete (globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG
-    vi.restoreAllMocks()
-  })
-
-  it('gates the console sink by level (default warn)', () => {
-    const sink = makeSink()
-    const log = createLogger({ sink })
-    log.debug('d')
-    log.info('i')
-    log.warn('w')
-    log.error('e')
-    expect(sink.calls.debug).toHaveLength(0)
-    expect(sink.calls.info).toHaveLength(0)
-    expect(sink.calls.warn).toHaveLength(1)
-    expect(sink.calls.error).toHaveLength(1)
-  })
-
-  it('fires onLog for EVERY level, pre-gate (even below the console threshold)', () => {
-    const onLog = vi.fn()
-    const sink = makeSink()
-    const log = createLogger({ level: 'error', sink, onLog })
-    log.debug('d', 1)
-    log.error('e')
-    // onLog sees both; the sink only sees error.
-    expect(onLog).toHaveBeenCalledTimes(2)
-    expect(onLog).toHaveBeenNthCalledWith(1, 'debug', 'd', [1])
-    expect(sink.calls.debug).toHaveLength(0)
-    expect(sink.calls.error).toHaveLength(1)
-  })
-
-  it('passes raw (message, ...args) to a custom sink — no ISO prefix', () => {
-    const sink = makeSink()
-    const log = createLogger({ level: 'debug', sink })
-    log.warn('hello', { a: 1 })
-    expect(sink.calls.warn[0]).toEqual(['hello', { a: 1 }])
-  })
-
-  it('formats with an ISO/level prefix for the default console sink', () => {
-    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    const log = createLogger({ level: 'warn' })
-    log.warn('boom', 42)
-    const firstArg = spy.mock.calls[0]?.[0] as string
-    expect(firstArg).toMatch(/WARN: boom$/)
-    expect(spy.mock.calls[0]?.[1]).toBe(42)
-  })
-
-  it('setLevel changes the threshold at runtime', () => {
-    const sink = makeSink()
-    const log = createLogger({ level: 'error', sink })
-    log.info('before')
-    expect(sink.calls.info).toHaveLength(0)
-    log.setLevel('debug')
-    log.info('after')
-    expect(sink.calls.info).toHaveLength(1)
-    expect(log.getLevel()).toBe('debug')
-  })
-
-  it('honours the global UWC_DEBUG override (true ⇒ debug) without recreation', () => {
-    const sink = makeSink()
-    const log = createLogger({ level: 'error', sink })
-    log.debug('hidden')
-    expect(sink.calls.debug).toHaveLength(0)
-    ;(globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG = true
-    log.debug('shown')
-    expect(sink.calls.debug).toHaveLength(1)
-  })
-
-  it('a string UWC_DEBUG override only lowers the threshold, never raises it', () => {
-    const sink = makeSink()
-    const log = createLogger({ level: 'debug', sink })
-    ;(globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG = 'error'
-    // configured=debug, override=error → effective stays debug (min of the two).
-    log.debug('still shown')
-    expect(sink.calls.debug).toHaveLength(1)
-  })
-
-  it('swallows a throwing onLog so the log call never breaks', () => {
-    const sink = makeSink()
-    const log = createLogger({
-      level: 'warn',
-      sink,
-      onLog: () => {
-        throw new Error('sink boom')
-      }
-    })
-    expect(() => log.warn('ok')).not.toThrow()
-    expect(sink.calls.warn).toHaveLength(1)
-  })
-})

package/src/logger/create-logger.ts

@@ -1,101 +0,0 @@
-import type { LogLevel, Logger } from '@meshconnect/uwc-types'
-
-const LEVEL_WEIGHT: Record<LogLevel, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3
-}
-
-/** The logger returned by `createLogger`, with runtime-tunable level controls. */
-export interface ManagedLogger extends Logger {
-  /** Lower/raise the console threshold at runtime (e.g. from a support toggle). */
-  setLevel(level: LogLevel): void
-  /** The currently configured threshold (ignores the global override). */
-  getLevel(): LogLevel
-}
-
-export interface CreateLoggerOptions {
-  /** Console threshold. Default `'warn'` — UWC stays quiet unless asked. */
-  level?: LogLevel | undefined
-  /**
-   * Pre-gate tap: invoked for EVERY log line regardless of the console threshold.
-   * The observer bridge subscribes here so `debug`/`info` reach remote telemetry
-   * even when the console is silent. Throws are swallowed — a bad sink must not
-   * break a log call.
-   */
-  onLog?:
-    | ((level: LogLevel, message: string, args: unknown[]) => void)
-    | undefined
-  /**
-   * Output sink for gated lines. When provided (e.g. a consumer's own logger), it
-   * receives the RAW `(message, ...args)` so it can apply its own formatting. When
-   * omitted, the default `console` sink is used with an ISO/level prefix.
-   */
-  sink?: Logger | undefined
-}
-
-/**
- * Resolve the effective console threshold, honouring a runtime global override so
- * an issue can be triaged in a wallet's in-app browser WITHOUT a redeploy:
- *
- *   window.UWC_DEBUG = true        // surface everything (debug)
- *   window.UWC_DEBUG = 'info'      // surface info and above
- *
- * The override only ever LOWERS the threshold (shows more) — it can't hide logs a
- * consumer explicitly opted into. Re-read on every call so toggling it mid-session
- * takes effect immediately. SSR/Node-safe via the `globalThis` guard.
- */
-function resolveWeight(configured: LogLevel): number {
-  if (typeof globalThis !== 'undefined') {
-    const override = (globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG
-    if (override === true) return LEVEL_WEIGHT.debug
-    if (typeof override === 'string' && override in LEVEL_WEIGHT) {
-      return Math.min(
-        LEVEL_WEIGHT[override as LogLevel],
-        LEVEL_WEIGHT[configured]
-      )
-    }
-  }
-  return LEVEL_WEIGHT[configured]
-}
-
-/**
- * Console-backed, level-gated logger. ~zero-dep. Two seams:
- *  - `onLog` fires pre-gate (all levels) → drives the observer.
- *  - the console sink fires only at/above the threshold.
- */
-export function createLogger(options: CreateLoggerOptions = {}): ManagedLogger {
-  let configured: LogLevel = options.level ?? 'warn'
-  const customSink = options.sink
-
-  const emit = (level: LogLevel, message: string, args: unknown[]): void => {
-    // Pre-gate tap first — observability must not depend on the console threshold.
-    if (options.onLog) {
-      try {
-        options.onLog(level, message, args)
-      } catch {
-        // A failing sink must never break the caller's log statement.
-      }
-    }
-    if (LEVEL_WEIGHT[level] < resolveWeight(configured)) return
-    if (customSink) {
-      customSink[level](message, ...args)
-    } else {
-      const line = `[${new Date().toISOString()}] ${level.toUpperCase()}: ${message}`
-      // eslint-disable-next-line no-console -- this IS the default console sink
-      console[level](line, ...args)
-    }
-  }
-
-  return {
-    debug: (message, ...args) => emit('debug', message, args),
-    info: (message, ...args) => emit('info', message, args),
-    warn: (message, ...args) => emit('warn', message, args),
-    error: (message, ...args) => emit('error', message, args),
-    setLevel: level => {
-      configured = level
-    },
-    getLevel: () => configured
-  }
-}

package/src/observability/connect-observer.test.ts

@@ -1,100 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-import type { Session } from '@meshconnect/uwc-types'
-import { EventManager } from '../managers/event-manager'
-import { connectObserver } from './connect-observer'
-import type { UWCTelemetryEvent } from './telemetry'
-
-const FIXED_NOW = 1_700_000_000_000
-
-describe('connectObserver', () => {
-  it('forwards typed events to onEvent as normalized records', () => {
-    const em = new EventManager()
-    const events: UWCTelemetryEvent[] = []
-    connectObserver(
-      em,
-      { onEvent: e => events.push(e) },
-      () => 'sess',
-      () => FIXED_NOW
-    )
-
-    em.emit('connecting', { connectionMode: 'injected', walletId: 'metamask' })
-
-    expect(events).toHaveLength(1)
-    expect(events[0]).toMatchObject({
-      name: 'connecting',
-      operation: 'connect',
-      walletId: 'metamask',
-      sdkSessionId: 'sess',
-      timestamp: FIXED_NOW
-    })
-  })
-
-  it('routes log to onLog (scrubbed args), not onEvent', () => {
-    const em = new EventManager()
-    const onEvent = vi.fn()
-    const onLog = vi.fn()
-    connectObserver(em, { onEvent, onLog }, () => 'sess')
-
-    em.emit('log', {
-      level: 'info',
-      message: 'hi',
-      args: [{ secret: 's', id: 1 }]
-    })
-
-    expect(onEvent).not.toHaveBeenCalled()
-    expect(onLog).toHaveBeenCalledTimes(1)
-    const [level, message, args] = onLog.mock.calls[0]
-    expect(level).toBe('info')
-    expect(message).toBe('hi')
-    expect((args[0] as Record<string, unknown>).secret).toBe('[Redacted]')
-    expect((args[0] as Record<string, unknown>).id).toBe(1)
-  })
-
-  it('does not forward the legacy change event', () => {
-    const em = new EventManager()
-    const onEvent = vi.fn()
-    connectObserver(em, { onEvent }, () => 'sess')
-    em.emit('change', undefined)
-    expect(onEvent).not.toHaveBeenCalled()
-  })
-
-  it('teardown removes every subscription', () => {
-    const em = new EventManager()
-    const onEvent = vi.fn()
-    const teardown = connectObserver(em, { onEvent }, () => 'sess')
-    teardown()
-    em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
-    expect(onEvent).not.toHaveBeenCalled()
-    expect(em.getListenerCount()).toBe(0)
-  })
-
-  it('does not leak the wallet address through a connected event', () => {
-    const em = new EventManager()
-    const events: UWCTelemetryEvent[] = []
-    connectObserver(em, { onEvent: e => events.push(e) }, () => 'sess')
-    const session = {
-      connectionMode: 'injected',
-      activeNetwork: { namespace: 'eip155', id: 'eip155:1' },
-      activeWallet: { id: 'metamask' },
-      activeAddress: '0xSECRETADDR'
-    } as unknown as Session
-    em.emit('connected', { session })
-    expect(JSON.stringify(events)).not.toContain('0xSECRETADDR')
-  })
-
-  it('a throwing observer never breaks the dispatch chain', () => {
-    const em = new EventManager()
-    connectObserver(
-      em,
-      {
-        onEvent: () => {
-          throw new Error('observer boom')
-        }
-      },
-      () => 'sess'
-    )
-    expect(() =>
-      em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
-    ).not.toThrow()
-  })
-})

package/src/observability/connect-observer.ts

@@ -1,71 +0,0 @@
-import type { EventManager } from '../managers/event-manager'
-import { UWC_EVENT_NAMES } from '../events'
-import type { UWCEventMap } from '../events'
-import { normalizeEvent, type UWCObserver } from './telemetry'
-import { scrubArgs } from './scrub'
-
-/**
- * Bridge the internal event bus to a consumer-supplied `UWCObserver`.
- *
- * Subscribes to every `UWCEventMap` event, normalizes each to a PII-safe
- * `UWCTelemetryEvent`, and forwards it to `observer.onEvent`. The `log` event is
- * routed to `observer.onLog` instead (with scrubbed args) — it's the logging
- * channel, not a telemetry record. `change` is skipped: it's the legacy
- * re-render cascade and carries no payload.
- *
- * Returns a teardown function that removes every subscription. The caller MUST
- * invoke it on connector teardown — leaving these attached is the same listener-
- * leak class as the historical `BridgeParent.destroy()` zombie bug.
- *
- * @param getCorrelationId - resolves the correlation id stamped on every event,
- *   called per-event so a consumer-supplied id that arrives/changes after
- *   construction is honoured. Must not throw (the caller pre-wraps it).
- * @param now - clock injectable for deterministic tests; defaults to `Date.now`.
- */
-export function connectObserver(
-  eventManager: EventManager,
-  observer: UWCObserver,
-  getCorrelationId: () => string,
-  now: () => number = Date.now
-): () => void {
-  const unsubscribers: Array<() => void> = []
-
-  for (const name of UWC_EVENT_NAMES) {
-    if (name === 'change') continue
-
-    if (name === 'log') {
-      unsubscribers.push(
-        eventManager.on('log', data => {
-          if (!observer.onLog) return
-          const { level, message, args } = data as UWCEventMap['log']
-          try {
-            observer.onLog(level, message, scrubArgs(args))
-          } catch {
-            // A throwing observer must not break the dispatch chain.
-          }
-        })
-      )
-      continue
-    }
-
-    unsubscribers.push(
-      eventManager.on(name, data => {
-        if (!observer.onEvent) return
-        try {
-          // Normalize OUTSIDE the EventManager's own try/catch (which guards the
-          // listener, not the work the listener does), then hand off.
-          observer.onEvent(
-            normalizeEvent(name, data, getCorrelationId(), now())
-          )
-        } catch {
-          // Same: never let a bad observer break other listeners.
-        }
-      })
-    )
-  }
-
-  return () => {
-    for (const unsubscribe of unsubscribers) unsubscribe()
-    unsubscribers.length = 0
-  }
-}

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

@@ -1,150 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { WalletConnectorError } from '@meshconnect/uwc-types'
-import { EventManager } from '../managers/event-manager'
-import { instrumentHandoff, 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 }
-    expect(end.handoffId).toBe(start.handoffId)
-  })
-
-  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'])
-  })
-
-  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')
-      // 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'
-      ])
-    })
-
-    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
-    })
-  })
-})

package/src/observability/instrument-handoff.ts

@@ -1,122 +0,0 @@
-import type {
-  ConnectionMode,
-  Namespace,
-  NetworkId
-} from '@meshconnect/uwc-types'
-import type { EventManager } from '../managers/event-manager'
-import type { UWCOperation } from '../events'
-import { generateId } from '../utils/id'
-import {
-  isAbortError,
-  isUserRejection,
-  toWalletError
-} from '../utils/to-wallet-error'
-import { derivePlatform, deriveWalletFlowType } from './telemetry'
-
-/** 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
-}
-
-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
-  /** 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).
- *
- * 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()
-
-  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,
-    timestamp: start
-  })
-
-  const shouldTime = timeoutMs > 0 && context.connectionMode !== 'tonConnect'
-  const timer: ReturnType<typeof setTimeout> | undefined = shouldTime
-    ? setTimeout(() => {
-        eventManager.emit('walletTimedOut', {
-          handoffId,
-          operation: context.operation,
-          durationMs: now() - start
-        })
-      }, timeoutMs)
-    : undefined
-
-  try {
-    const result = await fn()
-    eventManager.emit('walletSucceeded', {
-      handoffId,
-      operation: context.operation,
-      durationMs: now() - start
-    })
-    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.
-    if (isAbortError(error)) throw error
-
-    const durationMs = now() - start
-    if (isUserRejection(error)) {
-      eventManager.emit('walletRejected', {
-        handoffId,
-        operation: context.operation,
-        durationMs
-      })
-    } else {
-      eventManager.emit('walletFailed', {
-        handoffId,
-        operation: context.operation,
-        durationMs,
-        error: toWalletError(error)
-      })
-    }
-    throw error
-  } finally {
-    if (timer) clearTimeout(timer)
-  }
-}