@metamask-previews/core-backend 1.0.1-preview-5f3688c1 → 1.0.1-preview-0189b42

package/dist/BackendWebSocketService.cjs

@@ -10,7 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _BackendWebSocketService_instances, _BackendWebSocketService_messenger, _BackendWebSocketService_options, _BackendWebSocketService_isEnabled, _BackendWebSocketService_ws, _BackendWebSocketService_state, _BackendWebSocketService_reconnectAttempts, _BackendWebSocketService_reconnectTimer, _BackendWebSocketService_connectionTimeout, _BackendWebSocketService_connectionPromise, _BackendWebSocketService_pendingRequests, _BackendWebSocketService_connectedAt, _BackendWebSocketService_subscriptions, _BackendWebSocketService_channelCallbacks, _BackendWebSocketService_setupAuthentication, _BackendWebSocketService_buildAuthenticatedUrl, _BackendWebSocketService_establishConnection, _BackendWebSocketService_handleMessage, _BackendWebSocketService_isServerResponse, _BackendWebSocketService_isSubscriptionNotification, _BackendWebSocketService_isChannelMessage, _BackendWebSocketService_handleServerResponse, _BackendWebSocketService_handleChannelMessage, _BackendWebSocketService_handleSubscriptionNotification, _BackendWebSocketService_parseMessage, _BackendWebSocketService_handleClose, _BackendWebSocketService_handleError, _BackendWebSocketService_scheduleReconnect, _BackendWebSocketService_clearTimers, _BackendWebSocketService_clearPendingRequests, _BackendWebSocketService_clearSubscriptions, _BackendWebSocketService_setState, _BackendWebSocketService_shouldReconnectOnClose;
+var _BackendWebSocketService_instances, _BackendWebSocketService_messenger, _BackendWebSocketService_options, _BackendWebSocketService_isEnabled, _BackendWebSocketService_trace, _BackendWebSocketService_ws, _BackendWebSocketService_state, _BackendWebSocketService_reconnectAttempts, _BackendWebSocketService_reconnectTimer, _BackendWebSocketService_connectionTimeout, _BackendWebSocketService_connectionPromise, _BackendWebSocketService_pendingRequests, _BackendWebSocketService_connectedAt, _BackendWebSocketService_manualDisconnect, _BackendWebSocketService_subscriptions, _BackendWebSocketService_channelCallbacks, _BackendWebSocketService_subscribeEvents, _BackendWebSocketService_buildAuthenticatedUrl, _BackendWebSocketService_establishConnection, _BackendWebSocketService_handleMessage, _BackendWebSocketService_isServerResponse, _BackendWebSocketService_isSubscriptionNotification, _BackendWebSocketService_isChannelMessage, _BackendWebSocketService_handleServerResponse, _BackendWebSocketService_handleChannelMessage, _BackendWebSocketService_handleSubscriptionNotification, _BackendWebSocketService_parseMessage, _BackendWebSocketService_handleClose, _BackendWebSocketService_handleError, _BackendWebSocketService_scheduleReconnect, _BackendWebSocketService_clearTimers, _BackendWebSocketService_clearPendingRequests, _BackendWebSocketService_clearSubscriptions, _BackendWebSocketService_setState;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BackendWebSocketService = exports.WebSocketEventType = exports.WebSocketState = exports.getCloseReason = void 0;
 const utils_1 = require("@metamask/utils");
@@ -109,18 +109,24 @@ var WebSocketEventType;
 /**
  * WebSocket Service with automatic reconnection, session management and direct callback routing
  *
+ * Connection Management:
+ * - Automatically subscribes to AuthenticationController:stateChange (sign in/out)
+ * - Automatically subscribes to KeyringController:lock/unlock events
+ * - Idempotent connect() function safe for multiple rapid calls
+ * - Auto-reconnects on unexpected disconnects (manualDisconnect = false)
+ *
+ * Platform Responsibilities:
+ * - Call connect() when app opens/foregrounds
+ * - Call disconnect() when app closes/backgrounds
+ * - Provide isEnabled() callback (feature flag)
+ * - Call destroy() on app termination
+ *
  * Real-Time Performance Optimizations:
  * - Fast path message routing (zero allocations)
  * - Production mode removes try-catch overhead
  * - Optimized JSON parsing with fail-fast
  * - Direct callback routing bypasses event emitters
  * - Memory cleanup and resource management
- *
- * Mobile Integration:
- * Mobile apps should handle lifecycle events (background/foreground) by:
- * 1. Calling disconnect() when app goes to background
- * 2. Calling connect() when app returns to foreground
- * 3. Calling destroy() on app termination
  */
 class BackendWebSocketService {
     // =============================================================================
@@ -140,6 +146,7 @@ class BackendWebSocketService {
         _BackendWebSocketService_messenger.set(this, void 0);
         _BackendWebSocketService_options.set(this, void 0);
         _BackendWebSocketService_isEnabled.set(this, void 0);
+        _BackendWebSocketService_trace.set(this, void 0);
         _BackendWebSocketService_ws.set(this, void 0);
         _BackendWebSocketService_state.set(this, WebSocketState.DISCONNECTED);
         _BackendWebSocketService_reconnectAttempts.set(this, 0);
@@ -148,7 +155,9 @@ class BackendWebSocketService {
         // Track the current connection promise to handle concurrent connection attempts
         _BackendWebSocketService_connectionPromise.set(this, null);
         _BackendWebSocketService_pendingRequests.set(this, new Map());
-        _BackendWebSocketService_connectedAt.set(this, null);
+        _BackendWebSocketService_connectedAt.set(this, 0);
+        // Track manual disconnects to prevent automatic reconnection
+        _BackendWebSocketService_manualDisconnect.set(this, false);
         // Simplified subscription storage (single flat map)
         // Key: subscription ID string (e.g., 'sub_abc123def456')
         // Value: WebSocketSubscription object with channels, callback and metadata
@@ -159,6 +168,8 @@ class BackendWebSocketService {
         _BackendWebSocketService_channelCallbacks.set(this, new Map());
         __classPrivateFieldSet(this, _BackendWebSocketService_messenger, options.messenger, "f");
         __classPrivateFieldSet(this, _BackendWebSocketService_isEnabled, options.isEnabled, "f");
+        // Default to no-op trace function to keep core platform-agnostic
+        __classPrivateFieldSet(this, _BackendWebSocketService_trace, options.traceFn ?? ((_request, fn) => fn?.()), "f");
         __classPrivateFieldSet(this, _BackendWebSocketService_options, {
             url: options.url,
             timeout: options.timeout ?? 10000,
@@ -166,8 +177,8 @@ class BackendWebSocketService {
             maxReconnectDelay: options.maxReconnectDelay ?? 5000,
             requestTimeout: options.requestTimeout ?? 30000,
         }, "f");
-        // Setup authentication (always enabled)
-        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setupAuthentication).call(this);
+        // Subscribe to authentication and keyring controller events
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_subscribeEvents).call(this);
         // Register action handlers using the method actions pattern
         __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
     }
@@ -177,18 +188,23 @@ class BackendWebSocketService {
     /**
      * Establishes WebSocket connection with smart reconnection behavior
      *
-     * Simplified Priority System (using AuthenticationController):
-     * 1. App closed/backgrounded → Stop all attempts (save resources)
-     * 2. User not signed in (wallet locked OR not authenticated) → Keep retrying
-     * 3. User signed in (wallet unlocked + authenticated) → Connect successfully
+     * Connection Requirements (all must be true):
+     * 1. Feature enabled (isEnabled() = true)
+     * 2. Wallet unlocked (checked by getBearerToken)
+     * 3. User signed in (checked by getBearerToken)
+     *
+     * Platform code should call this when app opens/foregrounds.
+     * Automatically called on KeyringController:unlock event.
      *
      * @returns Promise that resolves when connection is established
      */
     async connect() {
-        // Priority 1: Check if connection is enabled via callback (app lifecycle check)
-        // If app is closed/backgrounded, stop all connection attempts to save resources
+        // Reset manual disconnect flag when explicitly connecting
+        __classPrivateFieldSet(this, _BackendWebSocketService_manualDisconnect, false, "f");
+        // Priority 1: Check if feature is enabled via callback (feature flag check)
+        // If feature is disabled, stop all connection attempts
         if (__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f") && !__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f").call(this)) {
-            // Clear any pending reconnection attempts since app is disabled
+            // Clear any pending reconnection attempts since feature is disabled
             __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
             __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
             return;
@@ -202,10 +218,9 @@ class BackendWebSocketService {
             await __classPrivateFieldGet(this, _BackendWebSocketService_connectionPromise, "f");
             return;
         }
-        // Priority 2: Check authentication requirements (simplified - just check if signed in)
+        // Priority 2: Check authentication requirements (signed in)
         let bearerToken;
         try {
-            // AuthenticationController.getBearerToken() handles wallet unlock checks internally
             const token = await __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").call('AuthenticationController:getBearerToken');
             if (!token) {
                 __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
@@ -214,8 +229,10 @@ class BackendWebSocketService {
             bearerToken = token;
         }
         catch (error) {
-            log('Failed to check authentication requirements', { error });
-            // If we can't connect for ANY reason, schedule a retry
+            log('Failed to get bearer token (wallet locked or not signed in)', {
+                error,
+            });
+            // Can't connect - schedule retry
             __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
             return;
         }
@@ -229,7 +246,8 @@ class BackendWebSocketService {
             const errorMessage = (0, utils_1.getErrorMessage)(error);
             log('Connection attempt failed', { errorMessage, error });
             __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.ERROR);
-            throw new Error(`Failed to connect to WebSocket: ${errorMessage}`);
+            // Rethrow to propagate error to caller
+            throw error;
         }
         finally {
             // Clear the connection promise when done (success or failure)
@@ -246,6 +264,8 @@ class BackendWebSocketService {
             __classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.DISCONNECTING) {
             return;
         }
+        // Mark this as a manual disconnect to prevent automatic reconnection
+        __classPrivateFieldSet(this, _BackendWebSocketService_manualDisconnect, true, "f");
         __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTING);
         __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
         __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearPendingRequests).call(this, new Error('WebSocket disconnected'));
@@ -254,7 +274,6 @@ class BackendWebSocketService {
         if (__classPrivateFieldGet(this, _BackendWebSocketService_ws, "f")) {
             __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").close(1000, 'Normal closure');
         }
-        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTED);
         log('WebSocket manually disconnected');
     }
     /**
@@ -356,7 +375,7 @@ class BackendWebSocketService {
             state: __classPrivateFieldGet(this, _BackendWebSocketService_state, "f"),
             url: __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").url,
             reconnectAttempts: __classPrivateFieldGet(this, _BackendWebSocketService_reconnectAttempts, "f"),
-            connectedAt: __classPrivateFieldGet(this, _BackendWebSocketService_connectedAt, "f") ?? undefined,
+            connectedAt: __classPrivateFieldGet(this, _BackendWebSocketService_connectedAt, "f"),
         };
     }
     /**
@@ -372,6 +391,7 @@ class BackendWebSocketService {
                 matchingSubscriptions.push({
                     subscriptionId,
                     channels: subscription.channels,
+                    channelType: subscription.channelType,
                     unsubscribe: subscription.unsubscribe,
                 });
             }
@@ -407,6 +427,7 @@ class BackendWebSocketService {
                 matchingSubscriptions.push({
                     subscriptionId,
                     channels: subscription.channels,
+                    channelType: subscription.channelType,
                     unsubscribe: subscription.unsubscribe,
                 });
             }
@@ -500,6 +521,8 @@ class BackendWebSocketService {
         if (__classPrivateFieldGet(this, _BackendWebSocketService_ws, "f") && __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").readyState === WebSocket.OPEN) {
             __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").close(1000, 'Service cleanup');
         }
+        // Set state to disconnected immediately
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTED);
     }
     /**
      * Create and manage a subscription with server-side registration (recommended for most use cases)
@@ -528,6 +551,7 @@ class BackendWebSocketService {
      * @param options.channels - Array of channel names to subscribe to
      * @param options.callback - Callback function for handling notifications
      * @param options.requestId - Optional request ID for testing (will generate UUID if not provided)
+     * @param options.channelType - Channel type identifier
      * @returns Subscription object with unsubscribe method
      *
      * @example
@@ -547,7 +571,7 @@ class BackendWebSocketService {
      * @see addChannelCallback for local callbacks without server-side subscription
      */
     async subscribe(options) {
-        const { channels, callback, requestId } = options;
+        const { channels, channelType, callback, requestId } = options;
         if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") !== WebSocketState.CONNECTED) {
             throw new Error(`Cannot create subscription(s) ${channels.join(', ')}: WebSocket is ${__classPrivateFieldGet(this, _BackendWebSocketService_state, "f")}`);
         }
@@ -560,10 +584,6 @@ class BackendWebSocketService {
             throw new Error('Invalid subscription response: missing subscription ID');
         }
         const { subscriptionId } = subscriptionResponse;
-        // Check for failures
-        if (subscriptionResponse.failed && subscriptionResponse.failed.length > 0) {
-            throw new Error(`Subscription failed for channels: ${subscriptionResponse.failed.join(', ')}`);
-        }
         // Create unsubscribe function
         const unsubscribe = async (unsubRequestId) => {
             // Send unsubscribe request first
@@ -581,12 +601,14 @@ class BackendWebSocketService {
         const subscription = {
             subscriptionId,
             channels: [...channels],
+            channelType,
             unsubscribe,
         };
         // Store subscription with subscription ID as key
         __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").set(subscriptionId, {
             subscriptionId,
             channels: [...channels],
+            channelType,
             callback,
             unsubscribe,
         });
@@ -594,33 +616,28 @@ class BackendWebSocketService {
     }
 }
 exports.BackendWebSocketService = BackendWebSocketService;
-_BackendWebSocketService_messenger = new WeakMap(), _BackendWebSocketService_options = new WeakMap(), _BackendWebSocketService_isEnabled = new WeakMap(), _BackendWebSocketService_ws = new WeakMap(), _BackendWebSocketService_state = new WeakMap(), _BackendWebSocketService_reconnectAttempts = new WeakMap(), _BackendWebSocketService_reconnectTimer = new WeakMap(), _BackendWebSocketService_connectionTimeout = new WeakMap(), _BackendWebSocketService_connectionPromise = new WeakMap(), _BackendWebSocketService_pendingRequests = new WeakMap(), _BackendWebSocketService_connectedAt = new WeakMap(), _BackendWebSocketService_subscriptions = new WeakMap(), _BackendWebSocketService_channelCallbacks = new WeakMap(), _BackendWebSocketService_instances = new WeakSet(), _BackendWebSocketService_setupAuthentication = function _BackendWebSocketService_setupAuthentication() {
-    try {
-        // Subscribe to authentication state changes - this includes wallet unlock state
-        // AuthenticationController can only be signed in if wallet is unlocked
-        // Using selector to only listen for isSignedIn property changes for better performance
-        __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").subscribe('AuthenticationController:stateChange', (isSignedIn) => {
-            if (isSignedIn) {
-                // User signed in (wallet unlocked + authenticated) - try to connect
-                // Clear any pending reconnection timer since we're attempting connection
-                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
-                this.connect().catch((error) => {
-                    log('Failed to connect after sign-in', { error });
-                });
-            }
-            else {
-                // User signed out (wallet locked OR signed out) - disconnect and stop reconnection attempts
-                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
-                __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
-                this.disconnect().catch((error) => {
-                    log('Failed to disconnect after sign-out', { error });
-                });
-            }
-        }, (state) => state.isSignedIn);
-    }
-    catch (error) {
-        throw new Error(`Authentication setup failed: ${(0, utils_1.getErrorMessage)(error)}`);
-    }
+_BackendWebSocketService_messenger = new WeakMap(), _BackendWebSocketService_options = new WeakMap(), _BackendWebSocketService_isEnabled = new WeakMap(), _BackendWebSocketService_trace = new WeakMap(), _BackendWebSocketService_ws = new WeakMap(), _BackendWebSocketService_state = new WeakMap(), _BackendWebSocketService_reconnectAttempts = new WeakMap(), _BackendWebSocketService_reconnectTimer = new WeakMap(), _BackendWebSocketService_connectionTimeout = new WeakMap(), _BackendWebSocketService_connectionPromise = new WeakMap(), _BackendWebSocketService_pendingRequests = new WeakMap(), _BackendWebSocketService_connectedAt = new WeakMap(), _BackendWebSocketService_manualDisconnect = new WeakMap(), _BackendWebSocketService_subscriptions = new WeakMap(), _BackendWebSocketService_channelCallbacks = new WeakMap(), _BackendWebSocketService_instances = new WeakSet(), _BackendWebSocketService_subscribeEvents = function _BackendWebSocketService_subscribeEvents() {
+    // Subscribe to authentication state changes (sign in/out)
+    __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").subscribe('AuthenticationController:stateChange', (state) => {
+        if (state.isSignedIn) {
+            // eslint-disable-next-line no-void
+            void this.connect();
+        }
+        else {
+            // eslint-disable-next-line no-void
+            void this.disconnect();
+        }
+    });
+    // Subscribe to wallet unlock event
+    __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").subscribe('KeyringController:unlock', () => {
+        // eslint-disable-next-line no-void
+        void this.connect();
+    });
+    // Subscribe to wallet lock event
+    __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").subscribe('KeyringController:lock', () => {
+        // eslint-disable-next-line no-void
+        void this.disconnect();
+    });
 }, _BackendWebSocketService_buildAuthenticatedUrl = function _BackendWebSocketService_buildAuthenticatedUrl(bearerToken) {
     const baseUrl = __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").url;
     // Add token as query parameter to the WebSocket URL
@@ -636,6 +653,7 @@ _BackendWebSocketService_messenger = new WeakMap(), _BackendWebSocketService_opt
  */
 async function _BackendWebSocketService_establishConnection(bearerToken) {
     const wsUrl = __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_buildAuthenticatedUrl).call(this, bearerToken);
+    const connectionStartTime = Date.now();
     return new Promise((resolve, reject) => {
         const ws = new WebSocket(wsUrl);
         __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, setTimeout(() => {
@@ -643,40 +661,48 @@ async function _BackendWebSocketService_establishConnection(bearerToken) {
                 timeout: __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").timeout,
             });
             ws.close();
-            reject(new Error(`Connection timeout after ${__classPrivateFieldGet(this, _BackendWebSocketService_options, "f").timeout}ms`));
+            reject(new Error(`Failed to connect to WebSocket: Connection timeout after ${__classPrivateFieldGet(this, _BackendWebSocketService_options, "f").timeout}ms`));
         }, __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").timeout), "f");
         ws.onopen = () => {
             if (__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f")) {
                 clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f"));
                 __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, null, "f");
             }
-            __classPrivateFieldSet(this, _BackendWebSocketService_ws, ws, "f");
-            __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.CONNECTED);
-            __classPrivateFieldSet(this, _BackendWebSocketService_connectedAt, Date.now(), "f");
-            // Reset reconnect attempts on successful connection
-            __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
-            resolve();
+            // Calculate connection latency
+            const connectionLatency = Date.now() - connectionStartTime;
+            // Trace successful connection with latency
+            __classPrivateFieldGet(this, _BackendWebSocketService_trace, "f").call(this, {
+                name: `${SERVICE_NAME} Connection`,
+                data: {
+                    reconnectAttempt: __classPrivateFieldGet(this, _BackendWebSocketService_reconnectAttempts, "f"),
+                    latency_ms: connectionLatency,
+                },
+                tags: {
+                    service: SERVICE_NAME,
+                },
+            }, () => {
+                __classPrivateFieldSet(this, _BackendWebSocketService_ws, ws, "f");
+                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.CONNECTED);
+                __classPrivateFieldSet(this, _BackendWebSocketService_connectedAt, Date.now(), "f");
+                // Reset reconnect attempts on successful connection
+                __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
+                resolve();
+            });
         };
         ws.onerror = (event) => {
             log('WebSocket onerror event triggered', { event });
-            if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTING) {
-                // Handle connection-phase errors
-                if (__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f")) {
-                    clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f"));
-                    __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, null, "f");
-                }
-                const error = new Error(`WebSocket connection error to ${wsUrl}`);
-                reject(error);
-            }
-            else {
-                // Handle runtime errors
-                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleError).call(this, new Error(`WebSocket error: ${event.type}`));
+            // Handle connection-phase errors
+            if (__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f")) {
+                clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f"));
+                __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, null, "f");
             }
+            const error = new Error(`WebSocket connection error to ${wsUrl}`);
+            reject(error);
         };
         ws.onclose = (event) => {
             log('WebSocket onclose event triggered', {
                 code: event.code,
-                reason: event.reason || 'none',
+                reason: event.reason,
                 wasClean: event.wasClean,
             });
             if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTING) {
@@ -748,42 +774,98 @@ async function _BackendWebSocketService_establishConnection(bearerToken) {
     if (__classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").size === 0) {
         return;
     }
-    // Direct lookup for exact channel match
-    __classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").get(message.channel)?.callback(message);
+    // Calculate notification latency: time from server sent to client received
+    const receivedAt = Date.now();
+    const latency = receivedAt - message.timestamp;
+    // Trace channel message processing with latency data
+    __classPrivateFieldGet(this, _BackendWebSocketService_trace, "f").call(this, {
+        name: `${SERVICE_NAME} Channel Message`,
+        data: {
+            channel: message.channel,
+            latency_ms: latency,
+            event: message.event,
+        },
+        tags: {
+            service: SERVICE_NAME,
+            channel_type: message.channel,
+        },
+    }, () => {
+        // Direct lookup for exact channel match
+        __classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").get(message.channel)?.callback(message);
+    });
 }, _BackendWebSocketService_handleSubscriptionNotification = function _BackendWebSocketService_handleSubscriptionNotification(message) {
-    const { subscriptionId } = message;
+    const { subscriptionId, timestamp, channel } = message;
     // Only handle if subscriptionId is defined and not null (allows "0" as valid ID)
     if (subscriptionId !== null && subscriptionId !== undefined) {
-        __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").get(subscriptionId)?.callback?.(message);
+        const subscription = __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").get(subscriptionId);
+        if (!subscription) {
+            return false;
+        }
+        // Calculate notification latency: time from server sent to client received
+        const receivedAt = Date.now();
+        const latency = receivedAt - timestamp;
+        // Trace notification processing with latency data
+        // Use stored channelType instead of parsing each time
+        __classPrivateFieldGet(this, _BackendWebSocketService_trace, "f").call(this, {
+            name: `${SERVICE_NAME} Notification`,
+            data: {
+                channel,
+                latency_ms: latency,
+                subscriptionId,
+            },
+            tags: {
+                service: SERVICE_NAME,
+                notification_type: subscription.channelType,
+            },
+        }, () => {
+            subscription.callback?.(message);
+        });
         return true;
     }
     return false;
 }, _BackendWebSocketService_parseMessage = function _BackendWebSocketService_parseMessage(data) {
     return JSON.parse(data);
 }, _BackendWebSocketService_handleClose = function _BackendWebSocketService_handleClose(event) {
+    // Calculate connection duration before we clear state
+    const connectionDuration = Date.now() - __classPrivateFieldGet(this, _BackendWebSocketService_connectedAt, "f");
     __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
-    __classPrivateFieldSet(this, _BackendWebSocketService_connectedAt, null, "f");
+    __classPrivateFieldSet(this, _BackendWebSocketService_connectedAt, 0, "f");
     // Clear any pending connection promise
     __classPrivateFieldSet(this, _BackendWebSocketService_connectionPromise, null, "f");
     // Clear subscriptions and pending requests on any disconnect
     // This ensures clean state for reconnection
     __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearPendingRequests).call(this, new Error('WebSocket connection closed'));
     __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearSubscriptions).call(this);
-    if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.DISCONNECTING) {
-        // Manual disconnect
-        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTED);
+    // Update state to disconnected
+    __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTED);
+    // Check if this was a manual disconnect
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_manualDisconnect, "f")) {
+        // Manual disconnect - don't reconnect
+        log('WebSocket closed due to manual disconnect, not reconnecting');
         return;
     }
-    // For unexpected disconnects, update the state to reflect that we're disconnected
-    __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.DISCONNECTED);
-    // Check if we should attempt reconnection based on close code
-    const shouldReconnect = __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_shouldReconnectOnClose).call(this, event.code);
-    if (shouldReconnect) {
-        log('Connection lost unexpectedly, will attempt reconnection', {
+    // Trace unexpected disconnect with details
+    __classPrivateFieldGet(this, _BackendWebSocketService_trace, "f").call(this, {
+        name: `${SERVICE_NAME} Disconnect`,
+        data: {
             code: event.code,
-        });
-        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
-    }
+            reason: event.reason || getCloseReason(event.code),
+            connectionDuration_ms: connectionDuration,
+        },
+        tags: {
+            service: SERVICE_NAME,
+            disconnect_type: 'unexpected',
+        },
+    }, () => {
+        // Empty trace callback - just measuring the event
+    });
+    // For any unexpected disconnects, attempt reconnection
+    // The manualDisconnect flag is the only gate - if it's false, we reconnect
+    log('Connection lost unexpectedly, will attempt reconnection', {
+        code: event.code,
+        reason: event.reason,
+    });
+    __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
 }, _BackendWebSocketService_handleError = function _BackendWebSocketService_handleError(_error) {
     // Placeholder for future error handling logic
 }, _BackendWebSocketService_scheduleReconnect = function _BackendWebSocketService_scheduleReconnect() {
@@ -834,8 +916,5 @@ async function _BackendWebSocketService_establishConnection(bearerToken) {
         // Messenger handles listener errors internally, no need for try-catch
         __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").publish('BackendWebSocketService:connectionStateChanged', this.getConnectionInfo());
     }
-}, _BackendWebSocketService_shouldReconnectOnClose = function _BackendWebSocketService_shouldReconnectOnClose(code) {
-    // Don't reconnect only on normal closure (manual disconnect)
-    return code !== 1000;
 };
 //# sourceMappingURL=BackendWebSocketService.cjs.map