@meshconnect/uwc-core 1.0.3 → 1.1.0

package/README.md

@@ -121,11 +121,11 @@ await connector.connect('injected', 'metamask', 'eip155:1')
 
 Three mutually exclusive ways a user can connect:
 
-| Mode            | Description                                                        | Typical wallets                  |
-| --------------- | ------------------------------------------------------------------ | -------------------------------- |
+| Mode            | Description                                                                                           | Typical wallets                        |
+| --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------- |
 | `injected`      | Browser-extension or in-app injected provider (EIP-6963, Solana Wallet Standard, Tron, TON JS Bridge) | MetaMask, Phantom, Tonkeeper extension |
-| `walletConnect` | WalletConnect v2 relay + QR code / deeplink                        | Any WC-compatible mobile wallet  |
-| `tonConnect`    | TON Connect JS Bridge + QR code / universal link                   | Tonkeeper, OKX TON Wallet        |
+| `walletConnect` | WalletConnect v2 relay + QR code / deeplink                                                           | Any WC-compatible mobile wallet        |
+| `tonConnect`    | TON Connect JS Bridge + QR code / universal link                                                      | Tonkeeper, OKX TON Wallet              |
 
 A wallet can support multiple modes. `isConnectionModeAvailable(mode, walletId)`
 tells you which ones are actually viable in the current runtime.
@@ -141,7 +141,7 @@ interface Session {
   activeNetwork: Network | null
   activeAddress: string | null
   publicKey: string | null
-  availableNetworks: Network[]          // networks the current wallet supports
+  availableNetworks: Network[] // networks the current wallet supports
   availableAddresses: AvailableAddress[] // one per chain the wallet exposed
   activeWalletCapabilities: Record<string, EVMCapabilities> | null
   activeNetworkWalletCapabilities: EVMCapabilities | null
@@ -153,33 +153,44 @@ a `sessionChanged` event fires.
 
 ### Observer / event model
 
-The connector is an event emitter. There are twelve typed events:
-
-| Event                   | When it fires                                                |
-| ----------------------- | ------------------------------------------------------------ |
-| `ready`                 | Initial wallet detection has completed                       |
-| `walletsDetected`       | Detection completed, payload is the enriched wallet list     |
-| `connecting`            | `connect()` started                                          |
-| `connectionUri`         | A WC/TonConnect pairing URI is now available                 |
-| `connected`             | `connect()` finished successfully                            |
-| `disconnected`          | `disconnect()` finished (session cleared)                    |
-| `sessionChanged`        | Any session field changed                                    |
-| `networkSwitching`      | Network switch started or ended                              |
-| `networkSwitched`       | Network switch finished successfully                         |
-| `capabilitiesUpdated`   | `getWalletCapabilities()` refreshed data                     |
-| `error`                 | A user-initiated op threw                                    |
-| `change`                | Catch-all — fires after every other event                    |
-
-Use `on(eventName, listener)` for targeted updates. Every typed event also
+The connector is an event emitter. The state-change events are:
+
+| Event                 | When it fires                                            |
+| --------------------- | -------------------------------------------------------- |
+| `ready`               | Initial wallet detection has completed                   |
+| `walletsDetected`     | Detection completed, payload is the enriched wallet list |
+| `connecting`          | `connect()` started                                      |
+| `connectionUri`       | A WC/TonConnect pairing URI is now available             |
+| `connected`           | `connect()` finished successfully                        |
+| `disconnected`        | `disconnect()` finished (session cleared)                |
+| `sessionChanged`      | Any session field changed                                |
+| `networkSwitching`    | Network switch started or ended                          |
+| `networkSwitched`     | Network switch finished successfully                     |
+| `capabilitiesUpdated` | `getWalletCapabilities()` refreshed data                 |
+| `error`               | A user-initiated op threw                                |
+| `change`              | Catch-all — fires after every other state-change event   |
+
+Plus a set of **telemetry-only** events used for logging and wallet-handoff
+visibility (see [Logging & observability](#logging--observability)). These
+deliberately do **not** cascade to `change` (so they never trigger re-renders):
+`log`, `awaitingWallet`, `walletSucceeded`, `walletRejected`, `walletFailed`,
+`walletTimedOut`, `walletDiscoveryFailed`, `bridgeError`, `relayError`,
+`walletAccountChanged`, `walletChainChanged`, `walletDisconnected`,
+`walletSessionExpired`, `lifecycleTelemetryUnavailable`,
+`pageHiddenDuringHandoff`, `pageVisibleDuringHandoff` — the full list is the
+`TELEMETRY_ONLY_EVENTS` export in `events.ts`.
+
+Use `on(eventName, listener)` for targeted updates. Every state-change event also
 cascades to `change`, so the legacy `subscribe(listener)` pattern still works.
 
 ### AbortSignal
 
 Every async operation accepts an optional `{ signal }`. If the signal aborts,
-the operation rejects with an `AbortError` and no session mutations happen
-after the abort, even if the wallet prompt has already returned. Wallet
-prompts themselves cannot usually be cancelled — the signal protects your app
-from acting on stale results.
+the operation rejects with the signal's `reason` — a `DOMException` named
+`AbortError` by default, or whatever you passed to `controller.abort(reason)` —
+and no session mutations happen after the abort, even if the wallet prompt has
+already returned. Wallet prompts themselves cannot usually be cancelled — the
+signal protects your app from acting on stale results.
 
 ---
 
@@ -296,8 +307,8 @@ const connector = new UniversalWalletConnector(
 )
 ```
 
-Constructing a **second** instance logs a `console.error` warning — it's
-almost always a mistake. For tests and full-logout flows, call
+Constructing a **second** instance logs an error through the configured logger
+— it's almost always a mistake. For tests and full-logout flows, call
 `UniversalWalletConnector.resetInstance()` to clear the cached reference.
 
 ---
@@ -307,15 +318,15 @@ almost always a mistake. For tests and full-logout flows, call
 All reads are synchronous and cheap. Call them any time.
 
 ```ts
-connector.getSession()                 // current Session
-connector.getState()                   // { session } — parity with older API
-connector.isReady()                    // true once detection completed
-connector.getWallets()                 // wallets with `installed` flags set
-connector.getNetworks()                // the configured networks array
+connector.getSession() // current Session
+connector.getState() // { session } — parity with older API
+connector.isReady() // true once detection completed
+connector.getWallets() // wallets with `installed` flags set
+connector.getNetworks() // the configured networks array
 connector.isConnectionModeAvailable('walletConnect', 'metamask')
-connector.getConnectionURI()           // WC/TonConnect pairing URI, if any
+connector.getConnectionURI() // WC/TonConnect pairing URI, if any
 connector.getNetworkSwitchLoadingState()
-  // { isLoading, isWaitingForUserApproval }
+// { isLoading, isWaitingForUserApproval }
 connector.getActiveWalletCapabilities() // Record<NetworkId, EVMCapabilities> | null
 ```
 
@@ -363,18 +374,21 @@ connector.off('connectionUri', handler)
 import type { UWCEventMap } from '@meshconnect/uwc-core'
 
 // Narrowed per event:
-connector.on('connecting',    ({ connectionMode, walletId }) => {})
-connector.on('connected',     ({ session }) => {})
-connector.on('disconnected',  () => {})
+connector.on('connecting', ({ connectionMode, walletId }) => {})
+connector.on('connected', ({ session }) => {})
+connector.on('disconnected', () => {})
 connector.on('connectionUri', ({ uri, connectionMode }) => {})
-connector.on('networkSwitching', ({ isLoading, isWaitingForUserApproval }) => {})
-connector.on('networkSwitched',  ({ network }) => {})
-connector.on('sessionChanged',   ({ session }) => {})
+connector.on(
+  'networkSwitching',
+  ({ isLoading, isWaitingForUserApproval }) => {}
+)
+connector.on('networkSwitched', ({ network }) => {})
+connector.on('sessionChanged', ({ session }) => {})
 connector.on('capabilitiesUpdated', ({ capabilities }) => {})
-connector.on('walletsDetected',  ({ wallets }) => {})
+connector.on('walletsDetected', ({ wallets }) => {})
 connector.on('ready', () => {})
 connector.on('error', ({ error, operation }) => {})
-connector.on('change', () => {})  // catch-all; no payload
+connector.on('change', () => {}) // catch-all; no payload
 ```
 
 ### Legacy `subscribe()`
@@ -473,8 +487,8 @@ await connector.switchNetwork('eip155:8453') // Base
 // Track loading for UI
 connector.on('networkSwitching', ({ isLoading, isWaitingForUserApproval }) => {
   if (isWaitingForUserApproval) showBanner('Approve in your wallet…')
-  else if (isLoading)          showBanner('Switching network…')
-  else                         hideBanner()
+  else if (isLoading) showBanner('Switching network…')
+  else hideBanner()
 })
 ```
 
@@ -614,9 +628,10 @@ connectButton.addEventListener('click', () => {
 cancelButton.addEventListener('click', () => controller.abort())
 ```
 
-When the signal aborts, the in-flight promise rejects with an `AbortError`.
-Session state is **not** mutated after the abort, even if the wallet prompt
-later returns a result. This is especially useful in component lifecycles:
+When the signal aborts, the in-flight promise rejects with the signal's
+`reason` (an `AbortError` unless you aborted with a custom one). Session state
+is **not** mutated after the abort, even if the wallet prompt later returns a
+result. This is especially useful in component lifecycles:
 
 ```ts
 // Single-page app: abort on route change
@@ -647,8 +662,8 @@ interface WalletError {
 ```
 
 - `rejected` — user dismissed the prompt.
-- `expired`  — WalletConnect pairing proposal timed out.
-- `unknown`  — everything else (network errors, bad wallet state, …).
+- `expired` — WalletConnect pairing proposal timed out.
+- `unknown` — everything else (network errors, bad wallet state, …).
 
 ### Per-call handling
 
@@ -670,26 +685,29 @@ try {
 ```ts
 import type { UWCOperation } from '@meshconnect/uwc-core'
 
-connector.on('error', ({ error, operation }: {
-  error: WalletError
-  operation: UWCOperation
-}) => {
-  analytics.track('wallet.error', {
-    operation,
-    type: error.type,
-    message: error.message
-  })
-})
+connector.on(
+  'error',
+  ({ error, operation }: { error: WalletError; operation: UWCOperation }) => {
+    analytics.track('wallet.error', {
+      operation,
+      type: error.type,
+      message: error.message
+    })
+  }
+)
 ```
 
 `operation` is one of:
-`'connect' | 'disconnect' | 'switchNetwork' | 'signMessage' | 'sendTransaction' | 'getWalletCapabilities' | 'initialize'`.
+`'connect' | 'disconnect' | 'switchNetwork' | 'signMessage' | 'signTypedData' | 'sendTransaction' | 'signSolanaTransaction' | 'getWalletCapabilities' | 'initialize'`.
 
 ### AbortError
 
-Aborted operations reject with a `DOMException` whose `.name === 'AbortError'`.
-They are **not** routed through the `error` event — aborts are not wallet
-failures.
+Aborted operations reject with the signal's `reason`: a `DOMException` whose
+`.name === 'AbortError'` by default, or your own value when you called
+`controller.abort(customReason)`. Either way they are **not** routed through
+the `error` event — UWC consults the signal itself (not just the error name),
+so even a custom-reason abort is treated as a cancellation, not a wallet
+failure.
 
 ```ts
 try {
@@ -705,6 +723,139 @@ try {
 
 ---
 
+## Logging & observability
+
+UWC ships **no** third-party telemetry SDK. Instead it exposes two opt-in seams
+you wire to whatever stack you run (Datadog, Amplitude, Segment, a plain
+console). With neither configured, there is **zero external egress** — the
+security-first default for a sign-only wallet layer.
+
+### Logging
+
+A pluggable, level-gated logger backs UWC's internal logging. Configure it via
+`UWCConfig`:
+
+```ts
+const connector = new UniversalWalletConnector({
+  networks,
+  wallets,
+  logLevel: 'info', // console threshold; default 'warn'
+  logger: myAppLogger // optional: redirect output into your own logger
+})
+```
+
+`logger` (any object with `debug`/`info`/`warn`/`error`) receives the raw
+`(message, ...args)`; omit it and a console sink is used with an ISO/level prefix.
+
+Tune the threshold at runtime — useful when triaging in a wallet's in-app
+browser where you can't redeploy:
+
+```ts
+connector.setLogLevel('debug') // programmatic
+window.UWC_DEBUG = true // or from the console: surfaces everything
+window.UWC_DEBUG = 'info' // or a specific level (only ever lowers it)
+```
+
+### Observer (telemetry)
+
+Implement `UWCObserver` to receive a normalized, PII-safe event stream plus all
+log lines. The vendor code lives in **your** app, never in UWC:
+
+```ts
+import type { UWCObserver } from '@meshconnect/uwc-core'
+
+const observer: UWCObserver = {
+  onEvent: e => datadogRum.addAction(`uwc.${e.name}`, e), // or amplitude.track / …
+  onLog: (level, message, args) =>
+    myAppLogger[level](`[uwc] ${message}`, ...args)
+}
+
+const connector = new UniversalWalletConnector({ networks, wallets, observer })
+```
+
+> **Keep `onEvent` / `onLog` non-blocking.** They are called synchronously on the
+> wallet-operation path — a terminal event fires between the wallet returning a
+> result and that result reaching your `await`, so a slow handler adds latency to
+> connect / sign / sendTransaction. Queue-backed sinks (Datadog `addAction`,
+> Segment `track`) are already non-blocking; for anything heavy, defer it yourself
+> (`onEvent: e => queueMicrotask(() => …)`).
+
+Every `onEvent` record is a `UWCTelemetryEvent` — only routing facets
+(`operation`, `connectionMode`, `namespace`, `chainId`, `walletId`, `durationMs`,
+outcome…) plus a `sdkSessionId` correlation id. By default `sdkSessionId` is a
+generated per-instance id; pass `correlationId` (a string or getter) to align it
+to your own session key (e.g. `link_sess_id`) so UWC events join your existing
+Datadog/RUM telemetry without a separate mapping:
+
+```ts
+new UniversalWalletConnector({
+  ...config,
+  observer,
+  correlationId: () => myLinkSession.id // resolved per-event; getter may be lazy/dynamic
+})
+```
+
+**Structured fields never carry a signing payload or wallet address** — the shape has no slot for
+them. The two free-form surfaces (`error.message` and `onLog` args) additionally
+pass through a key + content scrubber that redacts sensitive keys, EVM hex blobs
+(addresses / signatures / keys), secret URL params, bearer tokens, and Solana
+base58 / TON (`EQ…`/`UQ…`) addresses. This last pass is best-effort and biased
+toward **over**-redaction (some non-secret base58-looking ids/hashes get redacted
+by design). One gap remains: BARE (non-`0x`) hex — a raw hex string is far more
+often a legitimate id/hash than a secret, so only `0x`-prefixed hex is redacted.
+Structured fields never carry addresses regardless.
+
+### Wallet-handoff funnel
+
+The moment UWC hands control to a wallet (extension popup, WC deeplink, TON
+sheet) it emits `awaitingWallet`; when the wallet answers it emits exactly one
+terminal — all sharing a `handoffId` and carrying `durationMs`:
+
+```
+awaitingWallet ─┬─ walletSucceeded   success
+                ├─ walletRejected    user said no (4001 / rejected)
+                └─ walletFailed      any other error
+```
+
+A non-cancelling `walletTimedOut` marker also fires if a non-TON handoff is still
+pending past `walletResponseTimeoutMs` (default 60s, `0` disables). It is purely
+observational — it never rejects, aborts, or mutates state, and is cleared the
+instant the op settles, so a fast op never false-fires it. This turns the
+previously-blind connect/sign/approve window into a per-(chain × wallet × flow)
+timed funnel.
+
+> A failed or rejected op emits **both** a handoff terminal
+> (`walletFailed` / `walletRejected`) **and** the back-compat `error` event. The
+> duplicate `error` record carries `handoffCovered: true`, so failure metrics
+> are: **terminals + `error` where NOT `handoffCovered`** (the uncovered ones
+> are pre-wallet validation failures, which have no terminal). Counting
+> terminals and all `error` records double-counts each wallet failure.
+> One documented edge: a wallet that rejects with a bare string/number (not an
+> object) can't be marked — a WeakSet can't hold primitives — so that rare
+> failure double-counts. EIP-1193 requires object errors, and wrapping the
+> thrown value to make it markable would mutate what the caller receives.
+
+> **Volume.** A single connect can emit several records (`awaitingWallet`, a
+> terminal, plus any focus / provider-lifecycle events), and
+> `pageHidden`/`pageVisibleDuringHandoff` fire on each visibility toggle while a
+> handoff is pending. If you forward `onEvent` straight to a metered backend
+> (Datadog RUM, etc.), sample or filter by `name` on your side — UWC emits every
+> record and does not sample for you. Provider-lifecycle events are additionally
+> capped at 100 per attachment (`MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT`) so a
+> storming provider cannot drive unbounded egress.
+
+### Teardown
+
+Call `dispose()` on full logout to release observer subscriptions, tear down any
+live provider-lifecycle listeners on a connected session, and clear all
+listeners:
+
+```ts
+connector.dispose()
+```
+
+---
+
 ## Testing
 
 The shared singleton can leak state between tests. Reset it in `beforeEach`:
@@ -726,7 +877,9 @@ When unit-testing consumer code, mock the whole module:
 vi.mock('@meshconnect/uwc-core', () => ({
   UniversalWalletConnector: class {
     static getInstance = () => new this()
-    getSession = () => ({ /* fixture */ })
+    getSession = () => ({
+      /* fixture */
+    })
     on = () => () => {}
     once = () => () => {}
     off = () => {}
@@ -757,12 +910,12 @@ connector.on('sessionChanged', ({ session }) => {
     session.activeAddress ?? 'not connected'
 })
 
-document.querySelector('#connect')!.addEventListener('click', () =>
-  connector.connect('injected', 'metamask')
-)
-document.querySelector('#disconnect')!.addEventListener('click', () =>
-  connector.disconnect()
-)
+document
+  .querySelector('#connect')!
+  .addEventListener('click', () => connector.connect('injected', 'metamask'))
+document
+  .querySelector('#disconnect')!
+  .addEventListener('click', () => connector.disconnect())
 ```
 
 ### Show QR and auto-close modal on pair
@@ -805,7 +958,9 @@ const controller = new AbortController()
 window.addEventListener('beforeunload', () => controller.abort())
 
 try {
-  const sig = await connector.signMessage('Sign in', { signal: controller.signal })
+  const sig = await connector.signMessage('Sign in', {
+    signal: controller.signal
+  })
   submitLogin(sig)
 } catch (error) {
   if ((error as { name?: string }).name === 'AbortError') return
@@ -828,6 +983,12 @@ export interface UWCConfig {
   walletConnectConfig?: WalletConnectConfig
   tonConnectConfig?: TonConnectConfig
   tronConnectorConfig?: TronConnectorConfig
+  // Observability (all optional; defaults preserve current behaviour)
+  observer?: UWCObserver // vendor-agnostic telemetry sink; default = no egress
+  logger?: Logger // redirect internal logging; default = console
+  logLevel?: LogLevel // console threshold; default 'warn'
+  walletResponseTimeoutMs?: number // walletTimedOut deadline; default 60_000, 0 disables
+  correlationId?: string | (() => string) // align sdkSessionId to your session key
 }
 
 export interface OperationOptions {
@@ -836,9 +997,15 @@ export interface OperationOptions {
 
 export type UWCEventName = keyof UWCEventMap
 export type UWCOperation =
-  | 'connect' | 'disconnect' | 'switchNetwork'
-  | 'signMessage' | 'sendTransaction'
-  | 'getWalletCapabilities' | 'initialize'
+  | 'connect'
+  | 'disconnect'
+  | 'switchNetwork'
+  | 'signMessage'
+  | 'signTypedData'
+  | 'sendTransaction'
+  | 'signSolanaTransaction'
+  | 'getWalletCapabilities'
+  | 'initialize'
 ```
 
 ### Static methods
@@ -879,6 +1046,10 @@ getNetworkSwitchLoadingState(): {
 getActiveWalletCapabilities(): Record<string, EVMCapabilities> | null
 isConnectionModeAvailable(mode: ConnectionMode, walletId: string): boolean
 
+// Observability
+setLogLevel(level: LogLevel): void   // tune the console threshold at runtime
+dispose(): void                      // release observer subs + clear listeners
+
 // Events
 on<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): () => void
 once<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): () => void