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

package/src/universal-wallet-connector.ts

@@ -18,9 +18,10 @@ import type {
   EVMCapabilities,
   SignatureType,
   EIP712TypedData,
-  WalletError
+  LogLevel,
+  Logger,
+  Session
 } from '@meshconnect/uwc-types'
-import { WalletConnectorError } from '@meshconnect/uwc-types'
 import { InjectedConnector } from '@meshconnect/uwc-injected-connector'
 import { WalletConnectConnector } from '@meshconnect/uwc-wallet-connect-connector'
 import { TonConnectConnector } from '@meshconnect/uwc-ton-connector'
@@ -33,8 +34,20 @@ import { SignatureService } from './services/signature-service'
 import { TransactionService } from './services/transaction-service'
 import { WalletCapabilitiesService } from './services/wallet-capabilities-service'
 import { createNetworkRpcMap } from './utils/network-rpc-utils'
+import { generateId } from './utils/id'
+import { toWalletError, isAbortError } from './utils/to-wallet-error'
+import { createLogger, type ManagedLogger } from './logger/create-logger'
+import { connectObserver } from './observability/connect-observer'
+import type { UWCObserver } from './observability/telemetry'
+import {
+  instrumentHandoff,
+  type HandoffContext
+} from './observability/instrument-handoff'
 import type { UWCEventName, UWCEventListener, UWCOperation } from './events'
 
+/** Default observational wallet-response deadline (ms). Matches TON's 60s. */
+const DEFAULT_WALLET_RESPONSE_TIMEOUT_MS = 60_000
+
 /**
  * Configuration object form of the UniversalWalletConnector constructor.
  * Prefer this over the positional constructor in new code.
@@ -49,6 +62,35 @@ export interface UWCConfig {
   walletConnectConfig?: WalletConnectConfig
   tonConnectConfig?: TonConnectConfig
   tronConnectorConfig?: TronConnectorConfig
+  // ---- Observability (all optional; defaults preserve current behaviour) -----
+  /**
+   * Vendor-agnostic telemetry sink. When omitted, UWC emits NOTHING externally —
+   * zero egress is the security-first default for a sign-only wallet layer. The
+   * consumer implements the sink and wires it to their backend (Datadog/…).
+   */
+  observer?: UWCObserver
+  /**
+   * Redirect UWC's internal logging into your own logger. Receives raw
+   * `(message, ...args)` at/above `logLevel`. When omitted, a console-backed
+   * logger is used.
+   */
+  logger?: Logger
+  /** Console threshold for the default logger. Default `'warn'`. */
+  logLevel?: LogLevel
+  /**
+   * Correlation id stamped on every telemetry record (`sdkSessionId`). Supply
+   * your own (e.g. the consumer's `link_sess_id`) so UWC events join your existing
+   * telemetry in Datadog/RUM without a separate mapping. Pass a getter if the id
+   * isn't known at construction or can change. Defaults to a generated per-instance
+   * id. Resolved per-event; a throwing/empty getter falls back to the default.
+   */
+  correlationId?: string | (() => string)
+  /**
+   * Observational wallet-response deadline (ms) for the `walletTimedOut` marker.
+   * `0` disables it. TON is always exempt (it bounds its own response). Default
+   * 60_000.
+   */
+  walletResponseTimeoutMs?: number
 }
 
 /** Common options for user-initiated async operations. */
@@ -75,6 +117,12 @@ export class UniversalWalletConnector {
   private usingIntegratedBrowser: boolean
   private detectionComplete = false
   private networkRpcMap: NetworkRpcMap
+  private logger: ManagedLogger
+  /** Per-instance correlation id stamped on every telemetry record. */
+  private readonly sdkSessionId: string = generateId()
+  private walletResponseTimeoutMs: number
+  /** Tears down the observer subscriptions; set only when an observer is wired. */
+  private observerTeardown: (() => void) | undefined
 
   /**
    * Recommended entry point: returns the shared instance, creating it on the
@@ -152,14 +200,49 @@ export class UniversalWalletConnector {
       tronConnectorConfig: configuredTronConnectorConfig
     } = config
 
+    // Observability seam — wire the event bus, logger, and (optional) observer
+    // FIRST so even construction-time logs/events are captured. `sdkSessionId` is
+    // already assigned as a field initializer.
+    this.eventManager = new EventManager()
+    this.walletResponseTimeoutMs =
+      config.walletResponseTimeoutMs ?? DEFAULT_WALLET_RESPONSE_TIMEOUT_MS
+    this.logger = createLogger({
+      level: config.logLevel ?? 'warn',
+      sink: config.logger,
+      // Pre-gate tap → typed `log` event → observer.onLog. Fires for all levels
+      // regardless of the console threshold.
+      onLog: (level, message, args) =>
+        this.eventManager.emit('log', { level, message, args })
+    })
+    if (config.observer) {
+      // Resolve the correlation id per-event. A consumer can align it to their
+      // own session key (e.g. link_sess_id); the generated `sdkSessionId` is the
+      // always-available fallback if none is supplied or a getter misbehaves.
+      const cid = config.correlationId
+      const getCorrelationId: () => string =
+        typeof cid === 'function'
+          ? () => {
+              try {
+                return cid() || this.sdkSessionId
+              } catch {
+                return this.sdkSessionId
+              }
+            }
+          : () => cid ?? this.sdkSessionId
+      this.observerTeardown = connectObserver(
+        this.eventManager,
+        config.observer,
+        getCorrelationId
+      )
+    }
+
     // Track instance creation and warn on duplicates
     UniversalWalletConnector.instanceCount++
     if (
       UniversalWalletConnector.instanceCount > 1 &&
       !UniversalWalletConnector.hasWarnedAboutMultipleInstances
     ) {
-      // eslint-disable-next-line no-console
-      console.error(
+      this.logger.error(
         `⚠️ WARNING: Multiple instances of UniversalWalletConnector detected (${UniversalWalletConnector.instanceCount} instances). ` +
           'This can lead to state inconsistencies and unexpected behavior. ' +
           'Please ensure you create only one instance and reuse it throughout your application. ' +
@@ -220,21 +303,22 @@ export class UniversalWalletConnector {
     }
 
     this.sessionManager = new SessionManager()
-    this.eventManager = new EventManager()
     this.connectionService = new ConnectionService(
       networks,
       this.wallets,
       this.sessionManager,
       this.connectors,
       configuredUsingIntegratedBrowser,
-      this.eventManager
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.networkSwitchService = new NetworkSwitchService(
       networks,
       this.sessionManager,
       this.connectors,
       configuredUsingIntegratedBrowser,
-      this.eventManager
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.signatureService = new SignatureService(
       this.sessionManager,
@@ -518,6 +602,9 @@ export class UniversalWalletConnector {
     options?: OperationOptions
   ): Promise<void> {
     try {
+      // Hand-off instrumentation lives in ConnectionService.connect (emitted
+      // after validation, at the real wallet boundary) — not here, so pre-wallet
+      // validation failures don't pollute the funnel.
       await this.connectionService.connect(
         connectionMode,
         walletId,
@@ -548,6 +635,8 @@ export class UniversalWalletConnector {
     options?: OperationOptions
   ): Promise<void> {
     try {
+      // Hand-off instrumentation lives in NetworkSwitchService.switchNetwork
+      // (emitted after validation, at the real wallet boundary).
       await this.networkSwitchService.switchNetwork(networkId, options)
     } catch (error) {
       this.emitError(error, 'switchNetwork')
@@ -580,27 +669,36 @@ export class UniversalWalletConnector {
     }
 
     try {
-      // Get the provider from the active wallet based on connection mode
-      let provider
-      if (session.connectionMode === 'injected') {
-        provider = this.usingIntegratedBrowser
-          ? session.activeWallet.integratedBrowserInjectedProvider
-          : session.activeWallet.extensionInjectedProvider
-      } else if (session.connectionMode === 'walletConnect') {
-        provider = session.activeWallet.walletConnectProvider
-      } else if (session.connectionMode === 'tonConnect') {
-        return await this.signatureService.signMessage(
-          message,
-          undefined,
-          options
-        )
-      }
+      return await this.instrument(
+        this.sessionHandoffContext('signMessage', session),
+        async () => {
+          // Get the provider from the active wallet based on connection mode
+          let provider
+          if (session.connectionMode === 'injected') {
+            provider = this.usingIntegratedBrowser
+              ? session.activeWallet!.integratedBrowserInjectedProvider
+              : session.activeWallet!.extensionInjectedProvider
+          } else if (session.connectionMode === 'walletConnect') {
+            provider = session.activeWallet!.walletConnectProvider
+          } else if (session.connectionMode === 'tonConnect') {
+            return await this.signatureService.signMessage(
+              message,
+              undefined,
+              options
+            )
+          }
 
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
+          if (!provider) {
+            throw new Error('No provider available for the active wallet')
+          }
 
-      return await this.signatureService.signMessage(message, provider, options)
+          return await this.signatureService.signMessage(
+            message,
+            provider,
+            options
+          )
+        }
+      )
     } catch (error) {
       this.emitError(error, 'signMessage')
       throw error
@@ -630,20 +728,30 @@ export class UniversalWalletConnector {
       throw new Error('signTypedData is not supported for TON wallets')
     }
 
-    // Resolve the injected provider from the active wallet. WalletConnect
-    // resolves its own provider inside the connector, so it stays undefined here.
-    let provider
-    if (session.connectionMode === 'injected') {
-      provider = this.usingIntegratedBrowser
-        ? session.activeWallet.integratedBrowserInjectedProvider
-        : session.activeWallet.extensionInjectedProvider
+    try {
+      return await this.instrument(
+        this.sessionHandoffContext('signTypedData', session),
+        async () => {
+          // Resolve the injected provider from the active wallet. WalletConnect
+          // resolves its own provider inside the connector, so it stays undefined.
+          let provider
+          if (session.connectionMode === 'injected') {
+            provider = this.usingIntegratedBrowser
+              ? session.activeWallet!.integratedBrowserInjectedProvider
+              : session.activeWallet!.extensionInjectedProvider
+
+            if (!provider) {
+              throw new Error('No provider available for the active wallet')
+            }
+          }
 
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
+          return await this.signatureService.signTypedData(typedData, provider)
+        }
+      )
+    } catch (error) {
+      this.emitError(error, 'signTypedData')
+      throw error
     }
-
-    return await this.signatureService.signTypedData(typedData, provider)
   }
 
   /**
@@ -667,30 +775,35 @@ export class UniversalWalletConnector {
     }
 
     try {
-      // Get the provider from the active wallet based on connection mode
-      let provider
-      if (session.connectionMode === 'injected') {
-        provider = this.usingIntegratedBrowser
-          ? session.activeWallet.integratedBrowserInjectedProvider
-          : session.activeWallet.extensionInjectedProvider
-      } else if (session.connectionMode === 'walletConnect') {
-        provider = session.activeWallet.walletConnectProvider
-      } else if (session.connectionMode === 'tonConnect') {
-        return await this.transactionService.sendTransaction(
-          request,
-          undefined,
-          options
-        )
-      }
+      return await this.instrument(
+        this.sessionHandoffContext('sendTransaction', session),
+        async () => {
+          // Get the provider from the active wallet based on connection mode
+          let provider
+          if (session.connectionMode === 'injected') {
+            provider = this.usingIntegratedBrowser
+              ? session.activeWallet!.integratedBrowserInjectedProvider
+              : session.activeWallet!.extensionInjectedProvider
+          } else if (session.connectionMode === 'walletConnect') {
+            provider = session.activeWallet!.walletConnectProvider
+          } else if (session.connectionMode === 'tonConnect') {
+            return await this.transactionService.sendTransaction(
+              request,
+              undefined,
+              options
+            )
+          }
 
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
+          if (!provider) {
+            throw new Error('No provider available for the active wallet')
+          }
 
-      return await this.transactionService.sendTransaction(
-        request,
-        provider,
-        options
+          return await this.transactionService.sendTransaction(
+            request,
+            provider,
+            options
+          )
+        }
       )
     } catch (error) {
       this.emitError(error, 'sendTransaction')
@@ -722,7 +835,15 @@ export class UniversalWalletConnector {
       )
     }
 
-    return await connector.signSolanaTransactionBytes(serializedTx)
+    try {
+      return await this.instrument(
+        this.sessionHandoffContext('signSolanaTransaction', session),
+        () => connector.signSolanaTransactionBytes!(serializedTx)
+      )
+    } catch (error) {
+      this.emitError(error, 'signSolanaTransaction')
+      throw error
+    }
   }
 
   /**
@@ -809,22 +930,74 @@ export class UniversalWalletConnector {
     return session.activeWalletCapabilities
   }
 
+  /**
+   * Set the console log threshold at runtime (e.g. from a support toggle). The
+   * global `window.UWC_DEBUG` override still takes precedence for ad-hoc triage.
+   */
+  setLogLevel(level: LogLevel): void {
+    this.logger.setLevel(level)
+  }
+
+  /**
+   * Release observer subscriptions and clear all event listeners. Call on full
+   * teardown / logout to avoid leaking listeners across connector lifecycles.
+   */
+  dispose(): void {
+    this.observerTeardown?.()
+    this.observerTeardown = undefined
+    this.eventManager.clearAllListeners()
+    // Full teardown: if this was the shared singleton, clear the static refs too
+    // so a later getInstance()/new starts clean — otherwise getInstance() would
+    // hand back this now-listener-less instance, and the instance-count warning
+    // would mis-fire on the next construction.
+    if (UniversalWalletConnector.instance === this) {
+      UniversalWalletConnector.resetInstance()
+    }
+  }
+
   // ---- private helpers ----
 
+  /** Instrument a wallet-boundary op (emits awaitingWallet + a terminal). */
+  private instrument<T>(
+    context: HandoffContext,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    return instrumentHandoff(
+      {
+        eventManager: this.eventManager,
+        timeoutMs: this.walletResponseTimeoutMs
+      },
+      context,
+      fn
+    )
+  }
+
+  /** Build handoff routing facets from the active session (no address). */
+  private 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
+    }
+  }
+
   private emitError(error: unknown, operation: UWCOperation): void {
     // Intentional cancellations (AbortSignal.throwIfAborted, fetch abort,
     // DOMException) should NOT surface as wallet errors — the caller already
-    // knows it asked to abort. Skip emission so error telemetry stays clean.
-    if (error instanceof Error && error.name === 'AbortError') {
+    // knows it asked to abort. Uses the same name-based check as
+    // `instrumentHandoff` so a DOMException abort (not an `Error` subclass in
+    // every runtime) is skipped consistently on both paths.
+    if (isAbortError(error)) {
       return
     }
-    const walletError: WalletError =
-      error instanceof WalletConnectorError
-        ? { type: error.type, message: error.message }
-        : {
-            type: 'unknown',
-            message: error instanceof Error ? error.message : String(error)
-          }
-    this.eventManager.emit('error', { error: walletError, operation })
+    this.eventManager.emit('error', {
+      error: toWalletError(error),
+      operation
+    })
   }
 }

package/src/utils/id.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+import { generateId } from './id'
+
+describe('generateId', () => {
+  it('produces unique values', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => generateId()))
+    expect(ids.size).toBe(1000)
+  })
+
+  it('produces a non-empty string', () => {
+    const id = generateId()
+    expect(typeof id).toBe('string')
+    expect(id.length).toBeGreaterThan(0)
+  })
+})

package/src/utils/id.ts

@@ -0,0 +1,48 @@
+/**
+ * Generate a correlation id (RFC-4122 v4 when available).
+ *
+ * Used for the per-instance `sdkSessionId` and per-handoff `handoffId` — both are
+ * opaque correlation tokens, never derived from wallet data (no address, no key).
+ * Prefers the native `crypto.randomUUID()` (browsers + Node ≥ 16); falls back to a
+ * `crypto.getRandomValues`-backed v4, and finally to a timestamp + monotonic
+ * counter only in environments that expose neither. Correlation ids need to be
+ * collision-resistant enough to pair a start event with its terminal — NOT
+ * cryptographically unpredictable — so the last-resort branch uses no PRNG.
+ */
+// Monotonic counter for the no-crypto fallback: guarantees per-process uniqueness
+// without any pseudo-random generator (correlation ids need uniqueness, not
+// unpredictability — and a counter is strictly more collision-resistant here).
+let fallbackCounter = 0
+
+export function generateId(): string {
+  const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined
+
+  if (c?.randomUUID) {
+    return c.randomUUID()
+  }
+
+  if (c?.getRandomValues) {
+    const bytes = c.getRandomValues(new Uint8Array(16))
+    // Set the version (4) and variant (10xx) bits per RFC 4122 §4.4.
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0'))
+    return (
+      hex.slice(0, 4).join('') +
+      '-' +
+      hex.slice(4, 6).join('') +
+      '-' +
+      hex.slice(6, 8).join('') +
+      '-' +
+      hex.slice(8, 10).join('') +
+      '-' +
+      hex.slice(10, 16).join('')
+    )
+  }
+
+  // Last-resort fallback (no Web Crypto). Timestamp + monotonic counter keeps
+  // ids unique within the process without a PRNG. Sufficient for correlation.
+  return (
+    'uwc-' + Date.now().toString(36) + '-' + (fallbackCounter++).toString(36)
+  )
+}

package/src/utils/to-wallet-error.ts

@@ -0,0 +1,36 @@
+import { WalletConnectorError, type WalletError } from '@meshconnect/uwc-types'
+
+/** Normalize any thrown value into the PII-light `WalletError` shape. */
+export function toWalletError(error: unknown): WalletError {
+  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: unknown): boolean {
+  if (error instanceof WalletConnectorError) return error.type === 'rejected'
+  const code = (error as { code?: unknown } | null | undefined)?.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: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { name?: unknown }).name === 'AbortError'
+  )
+}