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

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,24 +153,30 @@ 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`.
+
+Use `on(eventName, listener)` for targeted updates. Every state-change event also
 cascades to `change`, so the legacy `subscribe(listener)` pattern still works.
 
 ### AbortSignal
@@ -296,8 +302,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 +313,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 +369,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 +482,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()
 })
 ```
 
@@ -647,8 +656,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,20 +679,20 @@ 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
 
@@ -705,6 +714,122 @@ 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, and bearer tokens. Note this
+last pass is best-effort: a base58 (Solana) or TON address embedded in a
+free-form error string is a documented gap (it can't be matched without
+false-positives), so don't rely on it for non-EVM address redaction.
+
+### 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. For
+> failure metrics, count the handoff terminals and treat `error` as the legacy
+> channel — counting both double-counts each failure.
+
+### Teardown
+
+Call `dispose()` on full logout to release observer subscriptions and clear all
+listeners:
+
+```ts
+connector.dispose()
+````
+
+---
+
 ## Testing
 
 The shared singleton can leak state between tests. Reset it in `beforeEach`:
@@ -726,7 +851,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 +884,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 +932,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 +957,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 +971,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 +1020,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

package/dist/events.d.ts

@@ -1,8 +1,8 @@
-import type { Session, Network, WalletMetadata, ConnectionMode, WalletError, EVMCapabilities } from '@meshconnect/uwc-types';
+import type { Session, Network, WalletMetadata, ConnectionMode, WalletError, EVMCapabilities, LogLevel, WalletFlowType, Platform, Namespace, NetworkId } from '@meshconnect/uwc-types';
 /**
  * User-initiated operations that can surface through the `error` event.
  */
-export type UWCOperation = 'connect' | 'disconnect' | 'switchNetwork' | 'signMessage' | 'sendTransaction' | 'getWalletCapabilities' | 'initialize';
+export type UWCOperation = 'connect' | 'disconnect' | 'switchNetwork' | 'signMessage' | 'signTypedData' | 'sendTransaction' | 'signSolanaTransaction' | 'getWalletCapabilities' | 'initialize';
 /**
  * Typed event map emitted by UniversalWalletConnector.
  *
@@ -60,12 +60,79 @@ export interface UWCEventMap {
         error: WalletError;
         operation: UWCOperation;
     };
+    /**
+     * 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.
      */
     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 declare const TELEMETRY_ONLY_EVENTS: ReadonlySet<UWCEventName>;
 export type UWCEventName = keyof UWCEventMap;
 export type UWCEventListener<K extends UWCEventName> = (data: UWCEventMap[K]) => void;
+export declare const UWC_EVENT_NAMES: UWCEventName[];
 //# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,cAAc,EACd,cAAc,EACd,WAAW,EACX,eAAe,EAChB,MAAM,wBAAwB,CAAA;AAE/B;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,YAAY,GACZ,eAAe,GACf,aAAa,GACb,iBAAiB,GACjB,uBAAuB,GACvB,YAAY,CAAA;AAEhB;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,KAAK,EAAE,IAAI,CAAA;IACX,mEAAmE;IACnE,eAAe,EAAE;QAAE,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAA;IAE9C,+BAA+B;IAC/B,UAAU,EAAE;QAAE,cAAc,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IAChE,0CAA0C;IAC1C,SAAS,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/B,4DAA4D;IAC5D,YAAY,EAAE,IAAI,CAAA;IAClB;;;OAGG;IACH,aAAa,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,cAAc,CAAA;KAAE,CAAA;IAE9D,sEAAsE;IACtE,cAAc,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAEpC,gEAAgE;IAChE,gBAAgB,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,wBAAwB,EAAE,OAAO,CAAA;KAAE,CAAA;IAC3E,gCAAgC;IAChC,eAAe,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAErC,0CAA0C;IAC1C,mBAAmB,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;KAAE,CAAA;IAEtE,yCAAyC;IACzC,KAAK,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAA;IAEtD;;;OAGG;IACH,MAAM,EAAE,IAAI,CAAA;CACb;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,WAAW,CAAA;AAC5C,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,YAAY,IAAI,CACrD,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KACjB,IAAI,CAAA"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -1,2 +1,41 @@
-export {};
+/**
+ * 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 = new Set([
+    'log',
+    'awaitingWallet',
+    'walletSucceeded',
+    'walletRejected',
+    'walletFailed',
+    'walletTimedOut'
+]);
+/**
+ * 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 = {
+    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);
 //# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":""}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AA2IA;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAA8B,IAAI,GAAG,CAAC;IACtE,KAAK;IACL,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,gBAAgB;CACjB,CAAC,CAAA;AAOF;;;;;GAKG;AACH,MAAM,gBAAgB,GAA+B;IACnD,KAAK,EAAE,IAAI;IACX,eAAe,EAAE,IAAI;IACrB,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;IACf,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;IACpB,gBAAgB,EAAE,IAAI;IACtB,eAAe,EAAE,IAAI;IACrB,mBAAmB,EAAE,IAAI;IACzB,KAAK,EAAE,IAAI;IACX,GAAG,EAAE,IAAI;IACT,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;IACpB,MAAM,EAAE,IAAI;CACb,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAmB,CAAA"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { UniversalWalletConnector, type UWCConfig, type OperationOptions } from './universal-wallet-connector';
 export type { UWCEventMap, UWCEventName, 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACb,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { UniversalWalletConnector } from './universal-wallet-connector';
+export { createLogger } from './logger/create-logger';
 export { toBaseUnits } from './utils/to-base-units';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAGzB,MAAM,8BAA8B,CAAA;AAOrC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAGzB,MAAM,8BAA8B,CAAA;AAOrC,OAAO,EACL,YAAY,EAGb,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/logger/create-logger.d.ts

@@ -0,0 +1,32 @@
+import type { LogLevel, Logger } from '@meshconnect/uwc-types';
+/** 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;
+}
+/**
+ * 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 declare function createLogger(options?: CreateLoggerOptions): ManagedLogger;
+//# sourceMappingURL=create-logger.d.ts.map

package/dist/logger/create-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-logger.d.ts","sourceRoot":"","sources":["../../src/logger/create-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAS9D,kFAAkF;AAClF,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,IAAI,QAAQ,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EACF,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,GAC7D,SAAS,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B;AA2BD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa,CAiC7E"}