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

package/src/events.ts

@@ -4,7 +4,12 @@ import type {
   WalletMetadata,
   ConnectionMode,
   WalletError,
-  EVMCapabilities
+  EVMCapabilities,
+  LogLevel,
+  WalletFlowType,
+  Platform,
+  Namespace,
+  NetworkId
 } from '@meshconnect/uwc-types'
 
 /**
@@ -15,7 +20,9 @@ export type UWCOperation =
   | 'disconnect'
   | 'switchNetwork'
   | 'signMessage'
+  | 'signTypedData'
   | 'sendTransaction'
+  | 'signSolanaTransaction'
   | 'getWalletCapabilities'
   | 'initialize'
 
@@ -60,6 +67,69 @@ export interface UWCEventMap {
   /** A user-initiated operation failed. */
   error: { error: WalletError; operation: UWCOperation }
 
+  // ---- Observability (telemetry-only; see TELEMETRY_ONLY_EVENTS) -------------
+  // These describe what happened, not a state change, so they intentionally do
+  // NOT cascade to the legacy `change` channel (which drives React re-renders).
+
+  /**
+   * A line emitted through the internal `Logger`. Fires for ALL levels regardless
+   * of the console threshold so an observer can capture `debug`/`info` even when
+   * the console is quiet. `args` is scrubbed before reaching `observer.onLog`.
+   */
+  log: { level: LogLevel; message: string; args: unknown[] }
+
+  /**
+   * Emitted immediately BEFORE control is handed to the wallet for a boundary op
+   * (the moment the blind window opens). Pair with exactly one terminal event via
+   * `handoffId`. Carries no signing payload and no address — only routing facets.
+   */
+  awaitingWallet: {
+    operation: UWCOperation
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    /** CAIP namespace (eip155 | solana | tron | tvm …) — not an address. */
+    namespace?: Namespace | undefined
+    /** CAIP chain id (e.g. `eip155:1`) — not an address. */
+    chainId?: NetworkId | undefined
+    handoffId: string
+    /** Derived, best-effort flow taxonomy (heuristic — see deriveWalletFlowType). */
+    walletFlowType: WalletFlowType
+    /** Coarse runtime surface (heuristic — see derivePlatform). */
+    platform: Platform
+    timestamp: number
+  }
+
+  /** The wallet resolved the op successfully. Closes a handoff. */
+  walletSucceeded: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+  }
+  /** The user explicitly rejected (4001 / WalletError.type === 'rejected'). Closes a handoff. */
+  walletRejected: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+  }
+  /** The op failed for any non-rejection reason. Closes a handoff. */
+  walletFailed: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+    error: WalletError
+  }
+  /**
+   * Side marker: the deadline passed with the op still pending. OBSERVATIONAL —
+   * it does NOT reject, abort, or mutate state; the wallet may still complete and
+   * produce the real terminal. Never fires for an op that settled before the
+   * deadline. Not itself a terminal.
+   */
+  walletTimedOut: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+  }
+
   /**
    * Back-compat catch-all. Fires after every other event above.
    * New code should prefer the specific events.
@@ -67,7 +137,50 @@ export interface UWCEventMap {
   change: void
 }
 
+/**
+ * Events that describe telemetry rather than a state change. `EventManager.emit`
+ * skips the legacy `change` cascade for these so high-frequency logging / handoff
+ * instrumentation can't trigger React re-renders through `subscribe()`.
+ */
+export const TELEMETRY_ONLY_EVENTS: ReadonlySet<UWCEventName> = new Set([
+  'log',
+  'awaitingWallet',
+  'walletSucceeded',
+  'walletRejected',
+  'walletFailed',
+  'walletTimedOut'
+])
+
 export type UWCEventName = keyof UWCEventMap
 export type UWCEventListener<K extends UWCEventName> = (
   data: UWCEventMap[K]
 ) => void
+
+/**
+ * Runtime list of every event name. The `Record<UWCEventName, true>` literal
+ * forces this to stay exhaustive — adding an event to `UWCEventMap` without
+ * listing it here is a compile error — so the observer bridge can never silently
+ * drop a new event.
+ */
+const EVENT_NAME_FLAGS: Record<UWCEventName, true> = {
+  ready: true,
+  walletsDetected: true,
+  connecting: true,
+  connected: true,
+  disconnected: true,
+  connectionUri: true,
+  sessionChanged: true,
+  networkSwitching: true,
+  networkSwitched: true,
+  capabilitiesUpdated: true,
+  error: true,
+  log: true,
+  awaitingWallet: true,
+  walletSucceeded: true,
+  walletRejected: true,
+  walletFailed: true,
+  walletTimedOut: true,
+  change: true
+}
+
+export const UWC_EVENT_NAMES = Object.keys(EVENT_NAME_FLAGS) as UWCEventName[]

package/src/index.ts

@@ -9,4 +9,10 @@ export type {
   UWCEventListener,
   UWCOperation
 } from './events'
+export {
+  createLogger,
+  type ManagedLogger,
+  type CreateLoggerOptions
+} from './logger/create-logger'
+export type { UWCObserver, UWCTelemetryEvent } from './observability/telemetry'
 export { toBaseUnits } from './utils/to-base-units'

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

@@ -0,0 +1,111 @@
+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

@@ -0,0 +1,101 @@
+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/managers/event-manager.test.ts

@@ -140,5 +140,30 @@ describe('EventManager', () => {
       eventManager.emit('change', undefined)
       expect(count).toBe(1)
     })
+
+    it('telemetry-only events do NOT cascade to the legacy change channel', () => {
+      let changeCount = 0
+      eventManager.subscribe(() => {
+        changeCount++
+      })
+      eventManager.emit('log', { level: 'debug', message: 'x', args: [] })
+      eventManager.emit('walletTimedOut', {
+        handoffId: 'h',
+        operation: 'signMessage',
+        durationMs: 1
+      })
+      // Neither should have triggered a re-render via `change`.
+      expect(changeCount).toBe(0)
+    })
+
+    it('state-change events still cascade to change alongside telemetry events', () => {
+      let changeCount = 0
+      eventManager.subscribe(() => {
+        changeCount++
+      })
+      eventManager.emit('log', { level: 'debug', message: 'x', args: [] })
+      eventManager.emit('disconnected', undefined)
+      expect(changeCount).toBe(1)
+    })
   })
 })

package/src/managers/event-manager.ts

@@ -1,4 +1,5 @@
 import type { UWCEventMap, UWCEventName, UWCEventListener } from '../events'
+import { TELEMETRY_ONLY_EVENTS } from '../events'
 
 type LegacyListener = () => void
 type UntypedListener = (data: unknown) => void
@@ -46,7 +47,10 @@ export class EventManager {
 
   emit<K extends UWCEventName>(event: K, data: UWCEventMap[K]): void {
     this.dispatch(event, data)
-    if (event !== 'change') {
+    // Telemetry-only events (logs, handoff instrumentation) describe what
+    // happened, not a state change — don't cascade them to `change`, or every
+    // log line would trigger a React re-render via legacy `subscribe()`.
+    if (event !== 'change' && !TELEMETRY_ONLY_EVENTS.has(event)) {
       this.dispatch('change', undefined as UWCEventMap['change'])
     }
   }

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

@@ -0,0 +1,100 @@
+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

@@ -0,0 +1,71 @@
+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
+  }
+}