@meshconnect/uwc-core 2.0.0 → 2.1.0

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

@@ -3,7 +3,8 @@ import type {
   Network,
   WalletMetadata,
   Logger,
-  Session
+  Session,
+  WalletStepInfo
 } from '@meshconnect/uwc-types'
 import { NoCommonNetworkError } from '@meshconnect/uwc-types'
 import { UniversalWalletConnector } from './universal-wallet-connector'
@@ -31,6 +32,12 @@ const getWalletCapabilitiesMock = vi.fn()
 // telemetry sinks and assert the emitted event — this is the only place the
 // sink→bus wiring is exercised.
 const wcConnectorCapture: { args: unknown[] } = { args: [] }
+// Captures the options bag the façade passes to the injected connector, so the
+// `onConnectStep` sink wiring (ONC-183) can be fired directly.
+const injectedConnectorCapture: { args: unknown[] } = { args: [] }
+// Stands in for the in-flight connect's routing (see
+// `ConnectionService.getCurrentHandoff`); reassigned per test.
+let currentHandoff: { handoffId: string; walletId: string } | undefined
 
 const connectedSession: Session = {
   connectionMode: 'injected',
@@ -57,7 +64,8 @@ const connectedSession: Session = {
 }
 
 vi.mock('@meshconnect/uwc-injected-connector', () => ({
-  InjectedConnector: vi.fn().mockImplementation(function () {
+  InjectedConnector: vi.fn().mockImplementation(function (...args: unknown[]) {
+    injectedConnectorCapture.args = args
     return {
       getAvailableWallets: getAvailableWalletsMock,
       // The REAL sign/send services route connectionMode 'injected' here —
@@ -99,7 +107,8 @@ vi.mock('./services/connection-service', () => ({
       getConnectionURI: vi.fn(),
       updateWallets: vi.fn(),
       teardownLifecycle: teardownLifecycleMock,
-      reattachLifecycle: reattachLifecycleMock
+      reattachLifecycle: reattachLifecycleMock,
+      getCurrentHandoff: () => currentHandoff
     }
   })
 }))
@@ -154,6 +163,120 @@ describe('UniversalWalletConnector — observability wiring', () => {
     })
     getWalletCapabilitiesMock.mockReset()
     getWalletCapabilitiesMock.mockResolvedValue(undefined)
+    injectedConnectorCapture.args = []
+    currentHandoff = undefined
+  })
+
+  /** Pull the `onConnectStep` sink out of the injected connector's options bag. */
+  function getConnectStepSink(): (info: WalletStepInfo) => void {
+    const options = injectedConnectorCapture.args[0] as {
+      onConnectStep?: (info: WalletStepInfo) => void
+    }
+    expect(typeof options.onConnectStep).toBe('function')
+    return options.onConnectStep!
+  }
+
+  it('forwards secondaryGatherTimeoutMs to the injected connector, including 0 (ONC-183)', () => {
+    // The documented opt-out. `0` must survive the plumbing — a truthy check
+    // anywhere along the way would silently drop it and leave the default 15s
+    // bound in place while the consumer believed they had disabled it.
+    new UniversalWalletConnector({
+      networks,
+      wallets,
+      secondaryGatherTimeoutMs: 0
+    })
+    expect(
+      (
+        injectedConnectorCapture.args[0] as {
+          secondaryGatherTimeoutMs?: number
+        }
+      ).secondaryGatherTimeoutMs
+    ).toBe(0)
+
+    UniversalWalletConnector.resetInstance()
+    injectedConnectorCapture.args = []
+    new UniversalWalletConnector({
+      networks,
+      wallets,
+      secondaryGatherTimeoutMs: 2_500
+    })
+    expect(
+      (
+        injectedConnectorCapture.args[0] as {
+          secondaryGatherTimeoutMs?: number
+        }
+      ).secondaryGatherTimeoutMs
+    ).toBe(2_500)
+  })
+
+  it('omits secondaryGatherTimeoutMs when unset so the connector default applies', () => {
+    new UniversalWalletConnector({ networks, wallets })
+    expect(
+      injectedConnectorCapture.args[0] as Record<string, unknown>
+    ).not.toHaveProperty('secondaryGatherTimeoutMs')
+  })
+
+  it('wires the onConnectStep sink → emits walletStep stamped with the in-flight handoff (ONC-183)', () => {
+    const events: UWCTelemetryEvent[] = []
+    new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    // A step raised while a connect is inside its handoff must carry that
+    // attempt's id + wallet, so a retry's steps never merge into the previous
+    // attempt's terminal.
+    currentHandoff = { handoffId: 'handoff-1', walletId: 'metamask' }
+    getConnectStepSink()({
+      step: 'secondaryGather',
+      outcome: 'timedOut',
+      durationMs: 15_000,
+      namespace: 'solana',
+      timeoutMs: 15_000
+    })
+
+    const step = events.find(e => e.name === 'walletStep')
+    expect(step).toMatchObject({
+      operation: 'connect',
+      connectionMode: 'injected',
+      handoffId: 'handoff-1',
+      walletId: 'metamask',
+      step: 'secondaryGather',
+      stepOutcome: 'timedOut',
+      namespace: 'solana',
+      timeoutMs: 15_000
+    })
+  })
+
+  it('emits walletStep with no handoffId when the step ran outside a handoff', () => {
+    const events: UWCTelemetryEvent[] = []
+    new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer: { onEvent: e => events.push(e) }
+    })
+
+    // No connect in flight — an unattributed step is correct here; inheriting a
+    // finished attempt's id would silently corrupt the join.
+    currentHandoff = undefined
+    getConnectStepSink()({
+      step: 'providerDetection',
+      outcome: 'failed',
+      durationMs: 3,
+      namespace: 'eip155'
+    })
+
+    const step = events.find(e => e.name === 'walletStep') as
+      | (UWCTelemetryEvent & { handoffId?: string; walletId?: string })
+      | undefined
+    expect(step).toBeDefined()
+    expect(step!.handoffId).toBeUndefined()
+    expect(step!.walletId).toBeUndefined()
+    // And no ASSERTED operation either (ONC-183 review): switchNetwork re-enters
+    // the same connect paths under a handoff NetworkSwitchService owns, so
+    // defaulting to 'connect' filed switch traffic under the connect funnel.
+    expect(step!.operation).toBeUndefined()
   })
 
   it('forwards a sign handoff to observer.onEvent (awaitingWallet → walletSucceeded)', async () => {

package/src/universal-wallet-connector.ts

@@ -95,6 +95,16 @@ export interface UWCConfig {
    * 60_000.
    */
   walletResponseTimeoutMs?: number
+  /**
+   * Per-namespace deadline (ms) for a best-effort SECONDARY address gather on an
+   * injected connect — the legs that run AFTER the target namespace is already
+   * authorized (e.g. MetaMask's Solana Snap prompt). On expiry the leg is
+   * abandoned and the connect completes without that namespace's address.
+   * `0` disables the bound, restoring the pre-ONC-183 behaviour where an
+   * unanswered secondary prompt could hold the whole connect open indefinitely.
+   * Default 15_000.
+   */
+  secondaryGatherTimeoutMs?: number
 }
 
 /** Common options for user-initiated async operations. */
@@ -290,6 +300,11 @@ export class UniversalWalletConnector {
       tonConnectConfig: configuredTonConnectConfig,
       tronConnectorConfig: configuredTronConnectorConfig,
       networks,
+      // Only forward when the consumer set it, so the connector's own default
+      // stays the single source of truth for the value (exactOptionalPropertyTypes).
+      ...(config.secondaryGatherTimeoutMs !== undefined && {
+        secondaryGatherTimeoutMs: config.secondaryGatherTimeoutMs
+      }),
       // Surface BridgeChild discovery failures (the Bitstarz "wallet never
       // appeared via the bridge" class) as a telemetry event.
       onBridgeError: info =>
@@ -324,7 +339,29 @@ export class UniversalWalletConnector {
       // The wallet-switch guard released a different wallet's live state —
       // surface it so the otherwise-silent release is observable in prod.
       onWalletConnectionsReleased: info =>
-        this.eventManager.emit('walletConnectionsReleased', info)
+        this.eventManager.emit('walletConnectionsReleased', info),
+      // Step-level connect telemetry (ONC-183). Stamped with the enclosing
+      // handoff's id so a step joins its own attempt's terminal; the getter is
+      // read at EMIT time, not here, because `connectionService` is constructed
+      // after this connector. Absent when a step runs outside a handoff.
+      onConnectStep: info => {
+        const handoff = this.connectionService?.getCurrentHandoff()
+        this.eventManager.emit('walletStep', {
+          connectionMode: 'injected',
+          // Only assert an operation we can actually source. A live
+          // ConnectionService handoff means this step belongs to a connect; with
+          // none we cannot tell (switchNetwork re-enters the same connect paths
+          // via ConnectionManager, under a handoff NetworkSwitchService owns),
+          // so the field is omitted rather than defaulted to 'connect' — which
+          // silently filed switch traffic under the connect funnel.
+          ...(handoff && {
+            operation: 'connect' as const,
+            handoffId: handoff.handoffId,
+            walletId: handoff.walletId
+          }),
+          ...info
+        })
+      }
     })
     this.connectors.set('injected', this.injectedConnector)
 

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated from package.json by scripts/generate-version.mjs — do not edit.
-export const UWC_CORE_VERSION = '2.0.0'
+export const UWC_CORE_VERSION = '2.1.0'