@meshconnect/uwc-core 1.0.3 → 1.1.0

package/dist/universal-wallet-connector.d.ts

@@ -1,5 +1,6 @@
-import type { UniversalWalletConnectorState, Network, WalletMetadata, NetworkId, ConnectionMode, WalletConnectConfig, TonConnectConfig, TransactionRequest, TransactionResult, EVMCapabilities, SignatureType, EIP712TypedData } from '@meshconnect/uwc-types';
+import type { UniversalWalletConnectorState, Network, WalletMetadata, NetworkId, ConnectionMode, WalletConnectConfig, TonConnectConfig, TransactionRequest, TransactionResult, EVMCapabilities, SignatureType, EIP712TypedData, LogLevel, Logger } from '@meshconnect/uwc-types';
 import type { TronConnectorConfig } from '@meshconnect/uwc-tron-connector';
+import type { UWCObserver } from './observability/telemetry';
 import type { UWCEventName, UWCEventListener } from './events';
 /**
  * Configuration object form of the UniversalWalletConnector constructor.
@@ -12,6 +13,37 @@ export interface UWCConfig {
     walletConnectConfig?: WalletConnectConfig;
     tonConnectConfig?: TonConnectConfig;
     tronConnectorConfig?: TronConnectorConfig;
+    /**
+     * 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. LOCAL SINK by contract: args are NOT scrubbed here — do not
+     * wire this to a remote transport; use `observer.onLog` (scrubbed) for egress.
+     */
+    logger?: Logger;
+    /** Console threshold for the default logger. Default `'warn'`. */
+    logLevel?: LogLevel;
+    /**
+     * Consumer correlation id, surfaced as its OWN `correlationId` field on every
+     * telemetry record — never aliased onto the generated `sdkSessionId`, so
+     * "no id supplied" and "id == session" stay distinguishable. 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; resolved per-event, and a
+     * throwing/empty getter OMITS the field for that record.
+     */
+    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. */
 export interface OperationOptions {
@@ -35,6 +67,12 @@ export declare class UniversalWalletConnector {
     private usingIntegratedBrowser;
     private detectionComplete;
     private networkRpcMap;
+    private logger;
+    /** Per-instance correlation id stamped on every telemetry record. */
+    private readonly sdkSessionId;
+    private walletResponseTimeoutMs;
+    /** Tears down the observer subscriptions; set only when an observer is wired. */
+    private observerTeardown;
     /**
      * Recommended entry point: returns the shared instance, creating it on the
      * first call. Subsequent calls ignore the `config` argument — use
@@ -55,6 +93,13 @@ export declare class UniversalWalletConnector {
      * in parallel without racing on the merge logic.
      */
     private applyDetectedWallet;
+    /**
+     * Per-namespace requested-vs-matched counts after detection. `requested` =
+     * configured wallets that declared the namespace; `matched` = those now marked
+     * installed. Counts only — never a wallet id or address. Feeds `walletsDetected`
+     * so a dashboard can answer "asked for N, matched 0?".
+     */
+    private summarizeDiscovery;
     getSession(): import("@meshconnect/uwc-types").Session;
     isReady(): boolean;
     /** Subscribe to a typed event. Returns an unsubscribe function. */
@@ -123,6 +168,16 @@ export declare class UniversalWalletConnector {
      */
     isConnectionModeAvailable(connectionMode: ConnectionMode, walletId: string): boolean;
     getActiveWalletCapabilities(): Record<string, EVMCapabilities> | null;
+    /**
+     * 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;
+    /**
+     * Release observer subscriptions and clear all event listeners. Call on full
+     * teardown / logout to avoid leaking listeners across connector lifecycles.
+     */
+    dispose(): void;
     private emitError;
 }
 //# sourceMappingURL=universal-wallet-connector.d.ts.map

package/dist/universal-wallet-connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"universal-wallet-connector.d.ts","sourceRoot":"","sources":["../src/universal-wallet-connector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"universal-wallet-connector.d.ts","sourceRoot":"","sources":["../src/universal-wallet-connector.ts"],"names":[],"mappings":"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"}

package/dist/universal-wallet-connector.js

@@ -1,4 +1,3 @@
-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';
@@ -10,6 +9,14 @@ 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, classifyError } from './utils/to-wallet-error';
+import { NoCommonNetworkError } from '@meshconnect/uwc-types';
+import { createLogger } from './logger/create-logger';
+import { connectObserver } from './observability/connect-observer';
+import { hasHandoffTerminal } from './observability/instrument-handoff';
+/** Default observational wallet-response deadline (ms). Matches TON's 60s. */
+const DEFAULT_WALLET_RESPONSE_TIMEOUT_MS = 60_000;
 export class UniversalWalletConnector {
     static instance = null;
     static instanceCount = 0;
@@ -27,6 +34,12 @@ export class UniversalWalletConnector {
     usingIntegratedBrowser;
     detectionComplete = false;
     networkRpcMap;
+    logger;
+    /** Per-instance correlation id stamped on every telemetry record. */
+    sdkSessionId = generateId();
+    walletResponseTimeoutMs;
+    /** Tears down the observer subscriptions; set only when an observer is wired. */
+    observerTeardown;
     /**
      * Recommended entry point: returns the shared instance, creating it on the
      * first call. Subsequent calls ignore the `config` argument — use
@@ -72,12 +85,43 @@ export class UniversalWalletConnector {
             config = networksOrConfig;
         }
         const { networks, wallets: configuredWallets = [], usingIntegratedBrowser: configuredUsingIntegratedBrowser = false, walletConnectConfig: configuredWalletConnectConfig, tonConnectConfig: configuredTonConnectConfig, 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 OPTIONAL consumer correlation id per-event so a consumer can
+            // align it to their own session key (e.g. link_sess_id). It is kept
+            // separate from the always-present generated `sdkSessionId` — never aliased
+            // — so a record can distinguish "no consumer id" from "id == session". A
+            // missing/empty value or a throwing getter yields `undefined` (no fallback).
+            const cid = config.correlationId;
+            const getCorrelationId = typeof cid === 'function'
+                ? () => {
+                    try {
+                        return cid() || undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }
+                : () => cid;
+            this.observerTeardown = connectObserver(this.eventManager, config.observer, this.sdkSessionId, getCorrelationId, Date.now, this.logger);
+        }
         // Track instance creation and warn on duplicates
         UniversalWalletConnector.instanceCount++;
         if (UniversalWalletConnector.instanceCount > 1 &&
             !UniversalWalletConnector.hasWarnedAboutMultipleInstances) {
-            // eslint-disable-next-line no-console
-            console.error(`⚠️ WARNING: Multiple instances of UniversalWalletConnector detected (${UniversalWalletConnector.instanceCount} instances). ` +
+            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. ' +
                 'Use UniversalWalletConnector.getInstance(config) instead of `new` to guarantee a single instance. ' +
@@ -100,21 +144,34 @@ export class UniversalWalletConnector {
         this.networkRpcMap = createNetworkRpcMap(networks);
         // Initialize connectors with RPC map
         this.connectors = new Map();
-        this.injectedConnector = new InjectedConnector(this.networkRpcMap, this.wallets, configuredTonConnectConfig, configuredTronConnectorConfig, networks);
+        this.injectedConnector = new InjectedConnector(this.networkRpcMap, this.wallets, configuredTonConnectConfig, configuredTronConnectorConfig, networks, 
+        // Surface BridgeChild discovery failures (the Bitstarz "wallet never
+        // appeared via the bridge" class) as a telemetry event.
+        info => this.eventManager.emit('bridgeError', {
+            namespace: info.namespace,
+            error: { type: 'unknown', message: info.message }
+        }));
         this.connectors.set('injected', this.injectedConnector);
         if (configuredTonConnectConfig) {
             this.connectors.set('tonConnect', new TonConnectConnector(configuredTonConnectConfig));
         }
         // Only add WalletConnect connector if config is provided
         if (configuredWalletConnectConfig) {
-            this.connectors.set('walletConnect', new WalletConnectConnector(configuredWalletConnectConfig, this.networkRpcMap));
+            this.connectors.set('walletConnect', new WalletConnectConnector(configuredWalletConnectConfig, this.networkRpcMap, 
+            // Surface relay-socket failures (e.g. code 3000 JWT clock skew) that are
+            // detached from the connect handoff, as a telemetry event.
+            (error) => this.eventManager.emit('relayError', {
+                error: {
+                    type: 'unknown',
+                    message: error instanceof Error ? error.message : String(error)
+                }
+            })));
         }
         this.sessionManager = new SessionManager();
-        this.eventManager = new EventManager();
-        this.connectionService = new ConnectionService(networks, this.wallets, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager);
-        this.networkSwitchService = new NetworkSwitchService(networks, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager);
-        this.signatureService = new SignatureService(this.sessionManager, this.connectors);
-        this.transactionService = new TransactionService(this.sessionManager, this.connectors);
+        this.connectionService = new ConnectionService(networks, this.wallets, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager, this.walletResponseTimeoutMs);
+        this.networkSwitchService = new NetworkSwitchService(networks, this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager, this.walletResponseTimeoutMs);
+        this.signatureService = new SignatureService(this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager, this.walletResponseTimeoutMs);
+        this.transactionService = new TransactionService(this.sessionManager, this.connectors, configuredUsingIntegratedBrowser, this.eventManager, this.walletResponseTimeoutMs);
         this.walletCapabilitiesService = new WalletCapabilitiesService(networks, this.connectors, this.sessionManager, this.eventManager);
         // Register as the shared instance so getInstance() works
         // (only set if no instance exists, to avoid overwriting an earlier one)
@@ -148,7 +205,7 @@ export class UniversalWalletConnector {
             // call, not the sum.
             const detectionTasks = [];
             for (const namespace of namespaces) {
-                for (const [, connector] of this.connectors) {
+                for (const [connectionMode, connector] of this.connectors) {
                     if (typeof connector.getAvailableWallets !== 'function')
                         continue;
                     detectionTasks.push(Promise.resolve()
@@ -158,8 +215,17 @@ export class UniversalWalletConnector {
                             this.applyDetectedWallet(namespace, d);
                         }
                     })
-                        .catch(() => {
-                        // Silently handle errors for individual connector/namespace combinations
+                        .catch(error => {
+                        // Was a silent catch — now a telemetry signal so a discovery
+                        // failure (the "why didn't wallet X appear?" class) is observable
+                        // rather than vanishing. STILL swallowed for control flow: one
+                        // namespace × connector failing must not abort the others or
+                        // reject detection.
+                        this.eventManager.emit('walletDiscoveryFailed', {
+                            namespace: namespace,
+                            connectionMode,
+                            error: toWalletError(error)
+                        });
                     }));
                 }
             }
@@ -168,7 +234,13 @@ export class UniversalWalletConnector {
             this.connectionService.updateWallets(this.wallets);
             // Mark detection as complete
             this.detectionComplete = true;
-            this.eventManager.emit('walletsDetected', { wallets: this.wallets });
+            // Per-namespace requested-vs-matched summary (counts only, non-PII) so a
+            // dashboard can tell "asked for N solana wallets, matched 0" (a metadata /
+            // config problem) from "asked for none".
+            this.eventManager.emit('walletsDetected', {
+                wallets: this.wallets,
+                discovery: this.summarizeDiscovery(namespaces)
+            });
             this.eventManager.emit('ready', undefined);
         }
         catch (error) {
@@ -273,6 +345,32 @@ export class UniversalWalletConnector {
             };
         }
     }
+    /**
+     * Per-namespace requested-vs-matched counts after detection. `requested` =
+     * configured wallets that declared the namespace; `matched` = those now marked
+     * installed. Counts only — never a wallet id or address. Feeds `walletsDetected`
+     * so a dashboard can answer "asked for N, matched 0?".
+     */
+    summarizeDiscovery(namespaces) {
+        const pickProvider = (w) => this.usingIntegratedBrowser
+            ? w.integratedBrowserInjectedProvider
+            : w.extensionInjectedProvider;
+        const summary = {};
+        for (const namespace of namespaces) {
+            let requested = 0;
+            let matched = 0;
+            for (const wallet of this.wallets) {
+                const nsMeta = pickProvider(wallet)?.namespaceMetaData?.[namespace];
+                if (!nsMeta)
+                    continue;
+                requested++;
+                if (nsMeta.installed)
+                    matched++;
+            }
+            summary[namespace] = { requested, matched };
+        }
+        return summary;
+    }
     getSession() {
         return this.sessionManager.getSession();
     }
@@ -311,10 +409,13 @@ export class UniversalWalletConnector {
     }
     async connect(connectionMode, walletId, networkId, options) {
         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, networkId, options);
         }
         catch (error) {
-            this.emitError(error, 'connect');
+            this.emitError(error, 'connect', options?.signal);
             throw error;
         }
     }
@@ -326,16 +427,27 @@ export class UniversalWalletConnector {
             await this.connectionService.disconnect(options);
         }
         catch (error) {
-            this.emitError(error, 'disconnect');
+            this.emitError(error, 'disconnect', options?.signal);
             throw error;
         }
     }
     async switchNetwork(networkId, options) {
+        // Captured before the switch so a cross-namespace move is detectable after.
+        const previousNamespace = this.sessionManager.getSession().activeNetwork?.namespace;
         try {
+            // Hand-off instrumentation lives in NetworkSwitchService.switchNetwork
+            // (emitted after validation, at the real wallet boundary).
             await this.networkSwitchService.switchNetwork(networkId, options);
+            // A cross-namespace switch changes the live provider, so the connect-time
+            // lifecycle subscription would keep observing the OLD namespace's provider
+            // and label its events with the new session's routing. Re-evaluate it.
+            const nextNamespace = this.sessionManager.getSession().activeNetwork?.namespace;
+            if (nextNamespace !== undefined && nextNamespace !== previousNamespace) {
+                this.connectionService.reattachLifecycle();
+            }
         }
         catch (error) {
-            this.emitError(error, 'switchNetwork');
+            this.emitError(error, 'switchNetwork', options?.signal);
             throw error;
         }
     }
@@ -349,34 +461,13 @@ export class UniversalWalletConnector {
      * @returns A promise that resolves to the signature
      */
     async signMessage(message, options) {
-        const session = this.sessionManager.getSession();
-        if (!session.activeWallet) {
-            throw new Error('No active wallet');
-        }
-        if (!session.connectionMode) {
-            throw new Error('No active connection');
-        }
         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);
-            }
-            if (!provider) {
-                throw new Error('No provider available for the active wallet');
-            }
-            return await this.signatureService.signMessage(message, provider, options);
+            // Validation + funnel instrumentation live in SignatureService (after
+            // validation, at the real wallet boundary) — same layering as connect.
+            return await this.signatureService.signMessage(message, options);
         }
         catch (error) {
-            this.emitError(error, 'signMessage');
+            this.emitError(error, 'signMessage', options?.signal);
             throw error;
         }
     }
@@ -389,28 +480,14 @@ export class UniversalWalletConnector {
      * @returns A promise that resolves to the 65-byte hex signature (0x-prefixed)
      */
     async signTypedData(typedData) {
-        const session = this.sessionManager.getSession();
-        if (!session.activeWallet) {
-            throw new Error('No active wallet');
-        }
-        if (!session.connectionMode) {
-            throw new Error('No active connection');
-        }
-        if (session.connectionMode === 'tonConnect') {
-            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;
-            if (!provider) {
-                throw new Error('No provider available for the active wallet');
-            }
+        try {
+            // Validation + funnel instrumentation live in SignatureService.
+            return await this.signatureService.signTypedData(typedData);
+        }
+        catch (error) {
+            this.emitError(error, 'signTypedData');
+            throw error;
         }
-        return await this.signatureService.signTypedData(typedData, provider);
     }
     /**
      * Send a transaction with the connected wallet
@@ -419,34 +496,13 @@ export class UniversalWalletConnector {
      * @returns A promise that resolves to the transaction result
      */
     async sendTransaction(request, options) {
-        const session = this.sessionManager.getSession();
-        if (!session.activeWallet) {
-            throw new Error('No active wallet');
-        }
-        if (!session.connectionMode) {
-            throw new Error('No active connection');
-        }
         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);
-            }
-            if (!provider) {
-                throw new Error('No provider available for the active wallet');
-            }
-            return await this.transactionService.sendTransaction(request, provider, options);
+            // Validation + funnel instrumentation live in TransactionService (after
+            // validation, at the real wallet boundary) — same layering as connect.
+            return await this.transactionService.sendTransaction(request, options);
         }
         catch (error) {
-            this.emitError(error, 'sendTransaction');
+            this.emitError(error, 'sendTransaction', options?.signal);
             throw error;
         }
     }
@@ -456,19 +512,14 @@ export class UniversalWalletConnector {
      * tonConnect doesn't implement it.
      */
     async signSolanaTransaction(serializedTx) {
-        const session = this.sessionManager.getSession();
-        if (!session.activeWallet) {
-            throw new Error('No active wallet');
-        }
-        if (!session.connectionMode) {
-            throw new Error('No active connection');
+        try {
+            // Validation + funnel instrumentation live in TransactionService.
+            return await this.transactionService.signSolanaTransactionBytes(serializedTx);
         }
-        // The active connector must implement the optional signSolanaTransactionBytes.
-        const connector = this.connectors.get(session.connectionMode);
-        if (!connector?.signSolanaTransactionBytes) {
-            throw new Error(`signSolanaTransaction is not supported for connection mode "${session.connectionMode}"`);
+        catch (error) {
+            this.emitError(error, 'signSolanaTransaction');
+            throw error;
         }
-        return await connector.signSolanaTransactionBytes(serializedTx);
     }
     /**
      * Fetch wallet capabilities for the connected wallet
@@ -482,7 +533,7 @@ export class UniversalWalletConnector {
             return await this.walletCapabilitiesService.getWalletCapabilities(address, activeNetwork, options);
         }
         catch (error) {
-            this.emitError(error, 'getWalletCapabilities');
+            this.emitError(error, 'getWalletCapabilities', options?.signal);
             throw error;
         }
     }
@@ -528,21 +579,67 @@ export class UniversalWalletConnector {
         const session = this.sessionManager.getSession();
         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) {
+        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() {
+        this.observerTeardown?.();
+        this.observerTeardown = undefined;
+        // Release any live provider-lifecycle listeners on a connected session —
+        // `dispose()` can be called without a prior `disconnect()`, and leaving the
+        // EIP-1193/adapter `.on` handlers attached is the zombie-listener leak this
+        // method's contract promises to prevent.
+        this.connectionService.teardownLifecycle();
+        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 ----
-    emitError(error, operation) {
+    emitError(error, operation, signal) {
         // 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+signal check as
+        // `instrumentHandoff`, so both a DOMException abort (not an `Error`
+        // subclass in every runtime) AND a custom `abort(reason)` — whose rejection
+        // value carries the caller's own name — are skipped consistently.
+        if (isAbortError(error) || signal?.aborted) {
             return;
         }
-        const 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 });
+        // Classify here too so a PRE-wallet validation failure — which never enters
+        // the handoff funnel (no awaitingWallet/terminal) — still carries
+        // failureKind/source/errorCode in telemetry. The #1 prod connection error,
+        // `no_common_network`, lands here; forward its two CAIP-2 id lists.
+        const { errorCode, failureKind, source } = classifyError(error);
+        this.eventManager.emit('error', {
+            error: toWalletError(error),
+            operation,
+            errorCode,
+            failureKind,
+            source,
+            // A handoff terminal already reported this failure — mark this record as
+            // the back-compat duplicate so metrics can count terminals + uncovered
+            // errors without double-counting.
+            ...(hasHandoffTerminal(error) && { handoffCovered: true }),
+            ...(error instanceof NoCommonNetworkError && {
+                networkMismatch: {
+                    walletNetworkIds: error.walletNetworkIds,
+                    configuredNetworkIds: error.configuredNetworkIds
+                }
+            })
+        });
     }
 }
 //# sourceMappingURL=universal-wallet-connector.js.map