@metamask-previews/core-backend 0.0.0-preview-bc80f5a1

package/dist/BackendWebSocketService.mjs

@@ -0,0 +1,836 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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;
+import { getErrorMessage } from "@metamask/utils";
+import { v4 as uuidV4 } from "uuid";
+import { projectLogger, createModuleLogger } from "./logger.mjs";
+const SERVICE_NAME = 'BackendWebSocketService';
+const log = createModuleLogger(projectLogger, SERVICE_NAME);
+const MESSENGER_EXPOSED_METHODS = [
+    'connect',
+    'disconnect',
+    'sendMessage',
+    'sendRequest',
+    'subscribe',
+    'getConnectionInfo',
+    'getSubscriptionsByChannel',
+    'channelHasSubscription',
+    'findSubscriptionsByChannelPrefix',
+    'addChannelCallback',
+    'removeChannelCallback',
+    'getChannelCallbacks',
+];
+/**
+ * Gets human-readable close reason from RFC 6455 close code
+ *
+ * @param code - WebSocket close code
+ * @returns Human-readable close reason
+ */
+export function getCloseReason(code) {
+    switch (code) {
+        case 1000:
+            return 'Normal Closure';
+        case 1001:
+            return 'Going Away';
+        case 1002:
+            return 'Protocol Error';
+        case 1003:
+            return 'Unsupported Data';
+        case 1004:
+            return 'Reserved';
+        case 1005:
+            return 'No Status Received';
+        case 1006:
+            return 'Abnormal Closure';
+        case 1007:
+            return 'Invalid frame payload data';
+        case 1008:
+            return 'Policy Violation';
+        case 1009:
+            return 'Message Too Big';
+        case 1010:
+            return 'Mandatory Extension';
+        case 1011:
+            return 'Internal Server Error';
+        case 1012:
+            return 'Service Restart';
+        case 1013:
+            return 'Try Again Later';
+        case 1014:
+            return 'Bad Gateway';
+        case 1015:
+            return 'TLS Handshake';
+        default:
+            if (code >= 3000 && code <= 3999) {
+                return 'Library/Framework Error';
+            }
+            if (code >= 4000 && code <= 4999) {
+                return 'Application Error';
+            }
+            return 'Unknown';
+    }
+}
+/**
+ * WebSocket connection states
+ */
+export var WebSocketState;
+(function (WebSocketState) {
+    WebSocketState["CONNECTING"] = "connecting";
+    WebSocketState["CONNECTED"] = "connected";
+    WebSocketState["DISCONNECTING"] = "disconnecting";
+    WebSocketState["DISCONNECTED"] = "disconnected";
+    WebSocketState["ERROR"] = "error";
+})(WebSocketState || (WebSocketState = {}));
+/**
+ * WebSocket event types
+ */
+export var WebSocketEventType;
+(function (WebSocketEventType) {
+    WebSocketEventType["CONNECTED"] = "connected";
+    WebSocketEventType["DISCONNECTED"] = "disconnected";
+    WebSocketEventType["MESSAGE"] = "message";
+    WebSocketEventType["ERROR"] = "error";
+    WebSocketEventType["RECONNECTING"] = "reconnecting";
+    WebSocketEventType["RECONNECTED"] = "reconnected";
+})(WebSocketEventType || (WebSocketEventType = {}));
+/**
+ * WebSocket Service with automatic reconnection, session management and direct callback routing
+ *
+ * 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
+ */
+export class BackendWebSocketService {
+    // =============================================================================
+    // 1. CONSTRUCTOR & INITIALIZATION
+    // =============================================================================
+    /**
+     * Creates a new WebSocket service instance
+     *
+     * @param options - Configuration options for the WebSocket service
+     */
+    constructor(options) {
+        _BackendWebSocketService_instances.add(this);
+        /**
+         * The name of the service.
+         */
+        this.name = SERVICE_NAME;
+        _BackendWebSocketService_messenger.set(this, void 0);
+        _BackendWebSocketService_options.set(this, void 0);
+        _BackendWebSocketService_isEnabled.set(this, void 0);
+        _BackendWebSocketService_ws.set(this, void 0);
+        _BackendWebSocketService_state.set(this, WebSocketState.DISCONNECTED);
+        _BackendWebSocketService_reconnectAttempts.set(this, 0);
+        _BackendWebSocketService_reconnectTimer.set(this, null);
+        _BackendWebSocketService_connectionTimeout.set(this, null);
+        // 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);
+        // Simplified subscription storage (single flat map)
+        // Key: subscription ID string (e.g., 'sub_abc123def456')
+        // Value: WebSocketSubscription object with channels, callback and metadata
+        _BackendWebSocketService_subscriptions.set(this, new Map());
+        // Channel-based callback storage
+        // Key: channel name (serves as unique identifier)
+        // Value: ChannelCallback configuration
+        _BackendWebSocketService_channelCallbacks.set(this, new Map());
+        __classPrivateFieldSet(this, _BackendWebSocketService_messenger, options.messenger, "f");
+        __classPrivateFieldSet(this, _BackendWebSocketService_isEnabled, options.isEnabled, "f");
+        __classPrivateFieldSet(this, _BackendWebSocketService_options, {
+            url: options.url,
+            timeout: options.timeout ?? 10000,
+            reconnectDelay: options.reconnectDelay ?? 500,
+            maxReconnectDelay: options.maxReconnectDelay ?? 5000,
+            requestTimeout: options.requestTimeout ?? 30000,
+        }, "f");
+        // Setup authentication (always enabled)
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setupAuthentication).call(this);
+        // Register action handlers using the method actions pattern
+        __classPrivateFieldGet(this, _BackendWebSocketService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    // =============================================================================
+    // 2. PUBLIC API METHODS
+    // =============================================================================
+    /**
+     * 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
+     *
+     * @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
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f") && !__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f").call(this)) {
+            // Clear any pending reconnection attempts since app is disabled
+            __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
+            __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
+            return;
+        }
+        // If already connected, return immediately
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTED) {
+            return;
+        }
+        // If already connecting, wait for the existing connection attempt to complete
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTING && __classPrivateFieldGet(this, _BackendWebSocketService_connectionPromise, "f")) {
+            await __classPrivateFieldGet(this, _BackendWebSocketService_connectionPromise, "f");
+            return;
+        }
+        // Priority 2: Check authentication requirements (simplified - just check if 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);
+                return;
+            }
+            bearerToken = token;
+        }
+        catch (error) {
+            log('Failed to check authentication requirements', { error });
+            // If we can't connect for ANY reason, schedule a retry
+            __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
+            return;
+        }
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_setState).call(this, WebSocketState.CONNECTING);
+        // Create and store the connection promise
+        __classPrivateFieldSet(this, _BackendWebSocketService_connectionPromise, __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_establishConnection).call(this, bearerToken), "f");
+        try {
+            await __classPrivateFieldGet(this, _BackendWebSocketService_connectionPromise, "f");
+        }
+        catch (error) {
+            const errorMessage = 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}`);
+        }
+        finally {
+            // Clear the connection promise when done (success or failure)
+            __classPrivateFieldSet(this, _BackendWebSocketService_connectionPromise, null, "f");
+        }
+    }
+    /**
+     * Closes WebSocket connection
+     *
+     * @returns Promise that resolves when disconnection is complete
+     */
+    async disconnect() {
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.DISCONNECTED ||
+            __classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.DISCONNECTING) {
+            return;
+        }
+        __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'));
+        // Clear any pending connection promise
+        __classPrivateFieldSet(this, _BackendWebSocketService_connectionPromise, null, "f");
+        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');
+    }
+    /**
+     * Sends a message through the WebSocket (fire-and-forget, no response expected)
+     *
+     * This is a low-level method for sending messages without waiting for a response.
+     * Most consumers should use `sendRequest()` instead, which handles request-response
+     * correlation and provides proper error handling with timeouts.
+     *
+     * Use this method only when:
+     * - You don't need a response from the server
+     * - You're implementing custom message protocols
+     * - You need fine-grained control over message timing
+     *
+     * @param message - The message to send
+     * @throws Error if WebSocket is not connected or send fails
+     *
+     * @see sendRequest for request-response pattern with automatic correlation
+     */
+    sendMessage(message) {
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") !== WebSocketState.CONNECTED || !__classPrivateFieldGet(this, _BackendWebSocketService_ws, "f")) {
+            throw new Error(`Cannot send message: WebSocket is ${__classPrivateFieldGet(this, _BackendWebSocketService_state, "f")}`);
+        }
+        try {
+            __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").send(JSON.stringify(message));
+        }
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
+            __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleError).call(this, new Error(errorMessage));
+            throw new Error(errorMessage);
+        }
+    }
+    /**
+     * Sends a request and waits for a correlated response (recommended for most use cases)
+     *
+     * This is the recommended high-level method for request-response communication.
+     * It automatically handles:
+     * - Request ID generation and correlation
+     * - Response matching with timeout protection
+     * - Automatic reconnection on timeout
+     * - Proper cleanup of pending requests
+     *
+     * @param message - The request message (can include optional requestId for testing)
+     * @returns Promise that resolves with the response data
+     * @throws Error if WebSocket is not connected, request times out, or response indicates failure
+     *
+     * @see sendMessage for fire-and-forget messaging without response handling
+     */
+    async sendRequest(message) {
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") !== WebSocketState.CONNECTED) {
+            throw new Error(`Cannot send request: WebSocket is ${__classPrivateFieldGet(this, _BackendWebSocketService_state, "f")}`);
+        }
+        // Use provided requestId if available, otherwise generate a new one
+        const requestId = message.data?.requestId ?? uuidV4();
+        const requestMessage = {
+            event: message.event,
+            data: {
+                ...message.data,
+                requestId, // Set after spread to ensure it's not overwritten by undefined
+            },
+        };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").delete(requestId);
+                log('Request timeout - triggering reconnection', {
+                    timeout: __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").requestTimeout,
+                });
+                // Trigger reconnection on request timeout as it may indicate stale connection
+                if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTED && __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f")) {
+                    // Force close the current connection to trigger reconnection logic
+                    __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").close(3000, 'Request timeout - forcing reconnect');
+                }
+                reject(new Error(`Request timeout after ${__classPrivateFieldGet(this, _BackendWebSocketService_options, "f").requestTimeout}ms`));
+            }, __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").requestTimeout);
+            // Store in pending requests for response correlation
+            __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").set(requestId, {
+                resolve: resolve,
+                reject,
+                timeout,
+            });
+            // Send the request
+            try {
+                this.sendMessage(requestMessage);
+            }
+            catch (error) {
+                __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").delete(requestId);
+                clearTimeout(timeout);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /**
+     * Gets current connection information
+     *
+     * @returns Current connection status and details
+     */
+    getConnectionInfo() {
+        return {
+            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,
+        };
+    }
+    /**
+     * Gets all subscription information for a specific channel
+     *
+     * @param channel - The channel name to look up
+     * @returns Array of subscription details for all subscriptions containing the channel
+     */
+    getSubscriptionsByChannel(channel) {
+        const matchingSubscriptions = [];
+        for (const [subscriptionId, subscription] of __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f")) {
+            if (subscription.channels.includes(channel)) {
+                matchingSubscriptions.push({
+                    subscriptionId,
+                    channels: subscription.channels,
+                    unsubscribe: subscription.unsubscribe,
+                });
+            }
+        }
+        return matchingSubscriptions;
+    }
+    /**
+     * Checks if a channel has a subscription
+     *
+     * @param channel - The channel name to check
+     * @returns True if the channel has a subscription, false otherwise
+     */
+    channelHasSubscription(channel) {
+        for (const subscription of __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").values()) {
+            if (subscription.channels.includes(channel)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Finds all subscriptions that have channels starting with the specified prefix
+     *
+     * @param channelPrefix - The channel prefix to search for (e.g., "account-activity.v1")
+     * @returns Array of subscription info for matching subscriptions
+     */
+    findSubscriptionsByChannelPrefix(channelPrefix) {
+        const matchingSubscriptions = [];
+        for (const [subscriptionId, subscription] of __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f")) {
+            // Check if any channel in this subscription starts with the prefix
+            const hasMatchingChannel = subscription.channels.some((channel) => channel.startsWith(channelPrefix));
+            if (hasMatchingChannel) {
+                matchingSubscriptions.push({
+                    subscriptionId,
+                    channels: subscription.channels,
+                    unsubscribe: subscription.unsubscribe,
+                });
+            }
+        }
+        return matchingSubscriptions;
+    }
+    /**
+     * Register a callback for specific channels (local callback only, no server subscription)
+     *
+     * **Key Difference from `subscribe()`:**
+     * - `addChannelCallback()`: Registers a local callback without creating a server-side subscription.
+     * The callback triggers on ANY message matching the channel name, regardless of subscriptionId.
+     * Useful for system-wide notifications or when you don't control the subscription lifecycle.
+     *
+     * - `subscribe()`: Creates a proper server-side subscription with a subscriptionId.
+     * The callback only triggers for messages with the matching subscriptionId.
+     * Includes proper lifecycle management (unsubscribe, automatic cleanup on disconnect).
+     *
+     * **When to use `addChannelCallback()`:**
+     * - Listening to system-wide notifications (e.g., 'system-notifications.v1')
+     * - Monitoring channels where subscriptions are managed elsewhere
+     * - Debug/logging scenarios where you want to observe all channel messages
+     *
+     * **When to use `subscribe()` instead:**
+     * - Creating new subscriptions that need server-side registration
+     * - When you need proper cleanup via unsubscribe
+     * - Most application use cases (recommended approach)
+     *
+     * @param options - Channel callback configuration
+     * @param options.channelName - Channel name to match exactly
+     * @param options.callback - Function to call when channel matches
+     *
+     * @example
+     * ```typescript
+     * // Listen to system notifications (no server subscription needed)
+     * webSocketService.addChannelCallback({
+     *   channelName: 'system-notifications.v1',
+     *   callback: (notification) => {
+     *     console.log('System notification:', notification.data);
+     *   }
+     * });
+     *
+     * // For account-specific subscriptions, use subscribe() instead:
+     * // const sub = await webSocketService.subscribe({
+     * //   channels: ['account-activity.v1.eip155:0:0x1234...'],
+     * //   callback: (notification) => { ... }
+     * // });
+     * ```
+     *
+     * @see subscribe for creating proper server-side subscriptions with lifecycle management
+     */
+    addChannelCallback(options) {
+        const channelCallback = {
+            channelName: options.channelName,
+            callback: options.callback,
+        };
+        // Check if callback already exists for this channel
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").has(options.channelName)) {
+            return;
+        }
+        __classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").set(options.channelName, channelCallback);
+    }
+    /**
+     * Remove a channel callback
+     *
+     * @param channelName - The channel name returned from addChannelCallback
+     * @returns True if callback was found and removed, false otherwise
+     */
+    removeChannelCallback(channelName) {
+        return __classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").delete(channelName);
+    }
+    /**
+     * Get all registered channel callbacks (for debugging)
+     *
+     * @returns Array of all registered channel callbacks
+     */
+    getChannelCallbacks() {
+        return Array.from(__classPrivateFieldGet(this, _BackendWebSocketService_channelCallbacks, "f").values());
+    }
+    /**
+     * Destroy the service and clean up resources
+     * Called when service is being destroyed or app is terminating
+     */
+    destroy() {
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearSubscriptions).call(this);
+        // Clear any pending connection promise
+        __classPrivateFieldSet(this, _BackendWebSocketService_connectionPromise, null, "f");
+        // Clear all pending requests
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearPendingRequests).call(this, new Error('Service cleanup'));
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_ws, "f") && __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").readyState === WebSocket.OPEN) {
+            __classPrivateFieldGet(this, _BackendWebSocketService_ws, "f").close(1000, 'Service cleanup');
+        }
+    }
+    /**
+     * Create and manage a subscription with server-side registration (recommended for most use cases)
+     *
+     * This is the recommended subscription API for high-level services. It creates a proper
+     * server-side subscription and routes notifications based on subscriptionId.
+     *
+     * **Key Features:**
+     * - Creates server-side subscription with unique subscriptionId
+     * - Callback triggered only for messages with matching subscriptionId
+     * - Automatic lifecycle management (cleanup on disconnect)
+     * - Includes unsubscribe method for proper cleanup
+     * - Request-response pattern with error handling
+     *
+     * **When to use `subscribe()`:**
+     * - Creating new subscriptions (account activity, price updates, etc.)
+     * - When you need proper cleanup/unsubscribe functionality
+     * - Most application use cases
+     *
+     * **When to use `addChannelCallback()` instead:**
+     * - System-wide notifications without server-side subscription
+     * - Observing channels managed elsewhere
+     * - Debug/logging scenarios
+     *
+     * @param options - Subscription configuration
+     * @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)
+     * @returns Subscription object with unsubscribe method
+     *
+     * @example
+     * ```typescript
+     * // AccountActivityService usage
+     * const subscription = await webSocketService.subscribe({
+     *   channels: ['account-activity.v1.eip155:0:0x1234...'],
+     *   callback: (notification) => {
+     *     this.handleAccountActivity(notification.data);
+     *   }
+     * });
+     *
+     * // Later, clean up
+     * await subscription.unsubscribe();
+     * ```
+     *
+     * @see addChannelCallback for local callbacks without server-side subscription
+     */
+    async subscribe(options) {
+        const { channels, 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")}`);
+        }
+        // Send subscription request and wait for response
+        const subscriptionResponse = await this.sendRequest({
+            event: 'subscribe',
+            data: { channels, requestId },
+        });
+        if (!subscriptionResponse?.subscriptionId) {
+            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
+            await this.sendRequest({
+                event: 'unsubscribe',
+                data: {
+                    subscription: subscriptionId,
+                    channels,
+                    requestId: unsubRequestId,
+                },
+            });
+            // Clean up subscription mapping
+            __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").delete(subscriptionId);
+        };
+        const subscription = {
+            subscriptionId,
+            channels: [...channels],
+            unsubscribe,
+        };
+        // Store subscription with subscription ID as key
+        __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").set(subscriptionId, {
+            subscriptionId,
+            channels: [...channels],
+            callback,
+            unsubscribe,
+        });
+        return subscription;
+    }
+}
+_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: ${getErrorMessage(error)}`);
+    }
+}, _BackendWebSocketService_buildAuthenticatedUrl = function _BackendWebSocketService_buildAuthenticatedUrl(bearerToken) {
+    const baseUrl = __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").url;
+    // Add token as query parameter to the WebSocket URL
+    const url = new URL(baseUrl);
+    url.searchParams.set('token', bearerToken);
+    return url.toString();
+}, _BackendWebSocketService_establishConnection = 
+/**
+ * Establishes the actual WebSocket connection
+ *
+ * @param bearerToken - The bearer token to use for authentication
+ * @returns Promise that resolves when connection is established
+ */
+async function _BackendWebSocketService_establishConnection(bearerToken) {
+    const wsUrl = __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_buildAuthenticatedUrl).call(this, bearerToken);
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(wsUrl);
+        __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, setTimeout(() => {
+            log('WebSocket connection timeout - forcing close', {
+                timeout: __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").timeout,
+            });
+            ws.close();
+            reject(new Error(`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();
+        };
+        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}`));
+            }
+        };
+        ws.onclose = (event) => {
+            log('WebSocket onclose event triggered', {
+                code: event.code,
+                reason: event.reason || 'none',
+                wasClean: event.wasClean,
+            });
+            if (__classPrivateFieldGet(this, _BackendWebSocketService_state, "f") === WebSocketState.CONNECTING) {
+                // Handle connection-phase close events
+                if (__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f")) {
+                    clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f"));
+                    __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, null, "f");
+                }
+                reject(new Error(`WebSocket connection closed during connection: ${event.code} ${event.reason}`));
+            }
+            else {
+                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleClose).call(this, event);
+            }
+        };
+        // Set up message handler immediately - no need to wait for connection
+        ws.onmessage = (event) => {
+            try {
+                const message = __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_parseMessage).call(this, event.data);
+                __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleMessage).call(this, message);
+            }
+            catch {
+                // Silently ignore invalid JSON messages
+            }
+        };
+    });
+}, _BackendWebSocketService_handleMessage = function _BackendWebSocketService_handleMessage(message) {
+    // Handle server responses (correlated with requests) first
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_isServerResponse).call(this, message)) {
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleServerResponse).call(this, message);
+        return;
+    }
+    // Handle subscription notifications with valid subscriptionId
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_isSubscriptionNotification).call(this, message)) {
+        const handled = __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleSubscriptionNotification).call(this, message);
+        // If subscription notification wasn't handled (falsy subscriptionId), fall through to channel handling
+        if (handled) {
+            return;
+        }
+    }
+    // Trigger channel callbacks for any message with a channel property
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_isChannelMessage).call(this, message)) {
+        __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_handleChannelMessage).call(this, message);
+    }
+}, _BackendWebSocketService_isServerResponse = function _BackendWebSocketService_isServerResponse(message) {
+    return ('data' in message &&
+        message.data &&
+        typeof message.data === 'object' &&
+        'requestId' in message.data);
+}, _BackendWebSocketService_isSubscriptionNotification = function _BackendWebSocketService_isSubscriptionNotification(message) {
+    return 'subscriptionId' in message && !__classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_isServerResponse).call(this, message);
+}, _BackendWebSocketService_isChannelMessage = function _BackendWebSocketService_isChannelMessage(message) {
+    return 'channel' in message;
+}, _BackendWebSocketService_handleServerResponse = function _BackendWebSocketService_handleServerResponse(message) {
+    const { requestId } = message.data;
+    const request = __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").get(requestId);
+    if (!request) {
+        return;
+    }
+    __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").delete(requestId);
+    clearTimeout(request.timeout);
+    // Check if the response indicates failure
+    if (message.data.failed && message.data.failed.length > 0) {
+        request.reject(new Error(`Request failed: ${message.data.failed.join(', ')}`));
+    }
+    else {
+        request.resolve(message.data);
+    }
+}, _BackendWebSocketService_handleChannelMessage = function _BackendWebSocketService_handleChannelMessage(message) {
+    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);
+}, _BackendWebSocketService_handleSubscriptionNotification = function _BackendWebSocketService_handleSubscriptionNotification(message) {
+    const { subscriptionId } = 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);
+        return true;
+    }
+    return false;
+}, _BackendWebSocketService_parseMessage = function _BackendWebSocketService_parseMessage(data) {
+    return JSON.parse(data);
+}, _BackendWebSocketService_handleClose = function _BackendWebSocketService_handleClose(event) {
+    __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_clearTimers).call(this);
+    __classPrivateFieldSet(this, _BackendWebSocketService_connectedAt, null, "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);
+        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', {
+            code: event.code,
+        });
+        __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() {
+    __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, __classPrivateFieldGet(this, _BackendWebSocketService_reconnectAttempts, "f") + 1, "f");
+    const rawDelay = __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").reconnectDelay * Math.pow(1.5, __classPrivateFieldGet(this, _BackendWebSocketService_reconnectAttempts, "f") - 1);
+    const delay = Math.min(rawDelay, __classPrivateFieldGet(this, _BackendWebSocketService_options, "f").maxReconnectDelay);
+    log('Scheduling reconnection attempt', {
+        attempt: __classPrivateFieldGet(this, _BackendWebSocketService_reconnectAttempts, "f"),
+        delayMs: delay,
+    });
+    __classPrivateFieldSet(this, _BackendWebSocketService_reconnectTimer, setTimeout(() => {
+        // Clear timer reference first
+        __classPrivateFieldSet(this, _BackendWebSocketService_reconnectTimer, null, "f");
+        // Check if connection is still enabled before reconnecting
+        if (__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f") && !__classPrivateFieldGet(this, _BackendWebSocketService_isEnabled, "f").call(this)) {
+            log('Reconnection disabled by isEnabled - stopping all attempts');
+            __classPrivateFieldSet(this, _BackendWebSocketService_reconnectAttempts, 0, "f");
+            return;
+        }
+        // Attempt to reconnect - if it fails, schedule another attempt
+        this.connect().catch(() => {
+            __classPrivateFieldGet(this, _BackendWebSocketService_instances, "m", _BackendWebSocketService_scheduleReconnect).call(this);
+        });
+    }, delay), "f");
+}, _BackendWebSocketService_clearTimers = function _BackendWebSocketService_clearTimers() {
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_reconnectTimer, "f")) {
+        clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_reconnectTimer, "f"));
+        __classPrivateFieldSet(this, _BackendWebSocketService_reconnectTimer, null, "f");
+    }
+    if (__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f")) {
+        clearTimeout(__classPrivateFieldGet(this, _BackendWebSocketService_connectionTimeout, "f"));
+        __classPrivateFieldSet(this, _BackendWebSocketService_connectionTimeout, null, "f");
+    }
+}, _BackendWebSocketService_clearPendingRequests = function _BackendWebSocketService_clearPendingRequests(error) {
+    for (const [, request] of __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f")) {
+        clearTimeout(request.timeout);
+        request.reject(error);
+    }
+    __classPrivateFieldGet(this, _BackendWebSocketService_pendingRequests, "f").clear();
+}, _BackendWebSocketService_clearSubscriptions = function _BackendWebSocketService_clearSubscriptions() {
+    __classPrivateFieldGet(this, _BackendWebSocketService_subscriptions, "f").clear();
+}, _BackendWebSocketService_setState = function _BackendWebSocketService_setState(newState) {
+    const oldState = __classPrivateFieldGet(this, _BackendWebSocketService_state, "f");
+    __classPrivateFieldSet(this, _BackendWebSocketService_state, newState, "f");
+    if (oldState !== newState) {
+        log('WebSocket state changed', { oldState, newState });
+        // Publish connection state change event
+        // 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.mjs.map