@maxtroost/use-websocket 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,9 +1,24 @@
+import { FunctionComponent } from 'react';
+import { PropsWithChildren } from 'react';
 import { Store } from '@tanstack/react-store';
 import { Store as Store_2 } from '@tanstack/store';
 
-/** Creates the initial state for a WebsocketSubscriptionStore. */
+/**
+ * Creates the initial state for a {@link WebsocketSubscriptionStore}.
+ *
+ * @template TData - The type of data in the store's `message` field
+ * @returns A new store with default values (message: undefined, subscribed: false, etc.)
+ */
 export declare function createInitialWebsocketSubscriptionStore<TData = unknown>(): WebsocketSubscriptionStore<TData>;
 
+/** Heartbeat (ping/pong) configuration */
+export declare interface HeartbeatConfig {
+    /** Whether to send ping messages and expect pong responses. Default: true */
+    enabled: boolean;
+    /** Time in ms to wait for a pong before considering the connection dead. Default: 10000 */
+    pongTimeoutMs: number;
+}
+
 /**
  * Structure of incoming WebSocket messages.
  *
@@ -21,6 +36,11 @@ export declare interface IncomingWebsocketMessage<TBody = unknown> {
     method?: string;
 }
 
+/**
+ * Type definitions for the WebSocket connection system.
+ *
+ * @module types
+ */
 /**
  * WebSocket connection ready states.
  *
@@ -43,6 +63,62 @@ declare enum ReadyState_2 {
 }
 export { ReadyState_2 as ReadyState }
 
+/**
+ * Configuration for WebSocket reconnection behavior with exponential backoff.
+ *
+ * The reconnection strategy uses three phases:
+ * - First phase (attempts 0-4): 4 second delay
+ * - Second phase (attempts 5-9): 30 second delay
+ * - Third phase (attempts 10+): 90 second delay
+ *
+ * User notifications are only shown after the notification threshold is exceeded
+ * to avoid spamming users during brief network interruptions.
+ *
+ * After MAX_RETRY_ATTEMPTS, reconnection stops to avoid infinite retries on dead
+ * endpoints (e.g. ~10 attempts ≈ 12 minutes); the user can manually retry via the
+ * notification action.
+ */
+declare const RECONNECTION_CONFIG: {
+    /**
+     * Maximum number of reconnection attempts before stopping and showing a permanent
+     * error. Prevents infinite retries on dead endpoints (CPU wake-ups, battery drain).
+     * ~10 attempts ≈ 12 minutes at phase 3 (90s interval). User can retry manually.
+     */
+    readonly MAX_RETRY_ATTEMPTS: 20;
+    /**
+     * Number of failed reconnection attempts before showing user notifications.
+     * Prevents notification spam during brief network interruptions.
+     */
+    readonly NOTIFICATION_THRESHOLD: 10;
+    /**
+     * Initial delay (in ms) when server closes with 1013 Try Again Later.
+     * The server explicitly asks to wait before reconnecting.
+     */
+    readonly TRY_AGAIN_LATER_DELAY_MS: 30000;
+    /**
+     * Delay durations (in milliseconds) for each reconnection phase.
+     */
+    readonly DELAYS: {
+        /** First phase delay: 4 seconds for the first 5 attempts */
+        readonly FIRST_PHASE: 4000;
+        /** Second phase delay: 30 seconds for attempts 6-10 */
+        readonly SECOND_PHASE: 30000;
+        /** Third phase delay: 90 seconds for attempts 11+ */
+        readonly THIRD_PHASE: 90000;
+    };
+    /**
+     * Threshold values that determine when to transition between reconnection phases.
+     */
+    readonly PHASE_THRESHOLDS: {
+        /** Maximum attempts in the first phase (0-4) */
+        readonly FIRST: 5;
+        /** Maximum attempts in the second phase (5-9) */
+        readonly SECOND: 10;
+    };
+};
+
+export declare type ReconnectionConfig = typeof RECONNECTION_CONFIG;
+
 /**
  * Structure for outgoing WebSocket messages.
  *
@@ -60,8 +136,6 @@ export declare interface SendMessage<TMethod = string, TUri = string, TBody = un
     uri?: TUri;
     /** Optional message body/payload */
     body?: TBody;
-    /** Correlation ID for tracking messages (automatically generated) */
-    correlation?: string;
 }
 
 /**
@@ -81,6 +155,22 @@ export declare interface SendMessageOptions {
  */
 export declare type SendToConnectionFn = (message: SendMessage<string, string, unknown>) => void;
 
+/**
+ * Returns the {@link WebsocketClient} from the nearest {@link WebsocketClientProvider}.
+ *
+ * Must be used within a `WebsocketClientProvider`; throws otherwise.
+ *
+ * @returns The WebsocketClient instance
+ * @throws Error if used outside WebsocketClientProvider
+ *
+ * @example
+ * ```typescript
+ * const client = useWebsocketClient();
+ * const api = useWebsocketSubscription({ key: 'my-sub', url: '...', uri: '...' });
+ * ```
+ */
+export declare const useWebsocketClient: () => WebsocketClient;
+
 /**
  * React hook that manages a WebSocket Message API for request/response style messaging.
  *
@@ -102,7 +192,7 @@ export declare type SendToConnectionFn = (message: SendMessage<string, string, u
  *   - `url`: The WebSocket URL
  *   - `key`: Unique identifier (components with same key share the API)
  *   - `enabled`: Whether this API is enabled (default: true)
- *   - `responseTimeoutMs`: Default timeout for `sendMessage` (default: 5000)
+ *   - `responseTimeoutMs`: Default timeout for `sendMessage` (default: 10000)
  *   - `onError`, `onMessageError`, `onClose`: Optional callbacks
  * @returns {@link WebsocketMessageApiPublic} with `sendMessage`, `sendMessageNoWait`, `reset`, `url`, `key`, `isEnabled`
  *
@@ -111,7 +201,7 @@ export declare type SendToConnectionFn = (message: SendMessage<string, string, u
  * const api = useWebsocketMessage<ModifyVoyageUim, ModifyVoyageUim>({
  *   key: 'voyages/modify',
  *   url: '/api',
- *   responseTimeoutMs: 5000
+ *   responseTimeoutMs: 10000
  * });
  *
  * // Await response (full form: uri, method, body?, options?)
@@ -146,7 +236,7 @@ export declare const useWebsocketMessage: (options: WebsocketMessageOptions) =>
  *    - Manages the underlying WebSocket connection lifecycle
  *    - Handles reconnection, heartbeat, and connection state
  *    - Routes incoming messages to the appropriate Subscription handlers
- *    - Retrieved via `findOrCreateWebsocketConnection()` which ensures only one
+ *    - Retrieved via `WebsocketClient.addConnection()` which ensures only one
  *      connection exists per WebSocket URL
  *
  * 2. **WebsocketSubscriptionApi** (one per subscription per connection)
@@ -166,7 +256,7 @@ export declare const useWebsocketMessage: (options: WebsocketMessageOptions) =>
  *   │           ├─→ Provides reactive store for data updates
  *   │           └─→ Handles subscribe/unsubscribe lifecycle
  *   │
- *   └─→ findOrCreateWebsocketConnection(url, url)
+ *   └─→ client.addConnection(url, url)
  *         └─→ Returns/creates WebsocketConnection singleton (per URL)
  *               ├─→ Manages WebSocket connection (connect, reconnect, heartbeat)
  *               ├─→ Routes messages to registered listeners
@@ -263,6 +353,169 @@ export declare function useWebsocketSubscription<TData = unknown, TBody = unknow
  */
 export declare const useWebsocketSubscriptionByKey: <TData = unknown>(key: string) => Store_2<WebsocketSubscriptionStore<TData>>;
 
+/**
+ * Global WebSocket configuration used by all WebsocketConnection instances.
+ *
+ * Instantiate with {@link WebsocketClientOverrides} to customize behavior.
+ * All overrides are merged with defaults; partial overrides are supported.
+ *
+ * @example
+ * ```typescript
+ * const client = new WebsocketClient({
+ *   maxRetryAttempts: 10,
+ *   heartbeat: { enabled: false },
+ *   messageResponseTimeoutMs: 5000
+ * });
+ * ```
+ */
+export declare class WebsocketClient {
+    /**
+     * Global map of active WebSocket connections, keyed by URL.
+     *
+     * One connection per key. Managed by {@link addConnection} and {@link removeConnection}.
+     */
+    private _connections;
+    /**
+     * Global map of active WebSocket listeners (subscription and message APIs), keyed by API key.
+     *
+     * One listener per key. Subscription APIs have `uri`; message APIs have `hasWaitingUri`.
+     * Managed by {@link createWebsocketSubscriptionApi}, {@link createWebsocketMessageApi},
+     * and {@link removeWebsocketListenerFromConnection}.
+     */
+    private _listeners;
+    /** Maximum reconnection attempts before stopping. */
+    maxRetryAttempts: number;
+    /** Attempts before showing user notifications. */
+    notificationThreshold: number;
+    /** Delay (ms) when server closes with 1013 Try Again Later. */
+    tryAgainLaterDelayMs: number;
+    /** Delay durations (ms) for each reconnection phase. */
+    delays: {
+        firstPhase: number;
+        secondPhase: number;
+        thirdPhase: number;
+    };
+    phaseThresholds: {
+        first: number;
+        second: number;
+    };
+    /** Delay (ms) before closing connection when no listeners remain. */
+    connectionCleanupDelayMs: number;
+    /** Default timeout (ms) for message API responses. */
+    messageResponseTimeoutMs: number;
+    /** Heartbeat (ping/pong) configuration. */
+    heartbeat: HeartbeatConfig;
+    /** Optional transform for outgoing message payloads. */
+    transformMessagePayload: ((payload: SendMessage<string, string, unknown>) => SendMessage<string, string, unknown>) | undefined;
+    /** Optional callback for connection event logging. */
+    connectionEvent: ((event: WebsocketLoggerConnectionEvent) => void) | undefined;
+    /**
+     * Creates a new WebsocketClient with optional overrides.
+     *
+     * All overrides are merged with defaults from {@link RECONNECTION_CONFIG},
+     * {@link CONNECTION_CLEANUP_DELAY_MS}, and {@link DEFAULT_HEARTBEAT_CONFIG}.
+     *
+     * @param overrides - Partial configuration overrides. Omitted values use defaults.
+     */
+    constructor({ maxRetryAttempts, notificationThreshold, tryAgainLaterDelayMs, delays, phaseThresholds, connectionCleanupDelayMs, messageResponseTimeoutMs, heartbeat, transformMessagePayload, connectionEvent }: WebsocketClientOverrides);
+    /** Reconnects all active WebSocket connections. Use after auth/region change. */
+    reconnectAllConnections: () => void;
+    /** Registers a listener (subscription or message API) in the client. */
+    addListener: (listener: WebsocketListener) => void;
+    /** Unregisters a listener from the client. */
+    removeListener: (listener: WebsocketListener) => void;
+    /**
+     * Returns a listener by key and type.
+     *
+     * @param key - The listener's unique key
+     * @param type - `'subscription'` or `'message'`
+     * @returns The listener if found, otherwise undefined
+     */
+    getListener<TData = unknown, TBody = unknown>(key: string, type: 'subscription'): WebsocketSubscriptionApi<TData, TBody> | undefined;
+    getListener(key: string, type: 'message'): WebsocketMessageApi | undefined;
+    /** Returns the WebSocket connection for the given URL key, or undefined. */
+    getConnection: (key: string) => WebsocketConnection | undefined;
+    /**
+     * Adds or returns an existing WebSocket connection for the given URL.
+     *
+     * @param key - The key used to identify the connection (typically the URL)
+     * @param url - The WebSocket URL to connect to
+     * @returns The existing or newly created connection
+     */
+    addConnection: (key: string, url: string) => WebsocketConnection;
+    /**
+     * Removes a connection from the client.
+     *
+     * @param url - The WebSocket URL used as the key when calling {@link addConnection}.
+     */
+    removeConnection: (url: string) => void;
+}
+
+/** Overrides for the global WebSocket configuration. All fields are optional. */
+export declare interface WebsocketClientOverrides {
+    /** Maximum number of reconnection attempts before stopping and showing a permanent error. Prevents infinite retries on dead endpoints (CPU wake-ups, battery drain). ~10 attempts ≈ 12 minutes at phase 3 (90s interval). User can retry manually. */
+    maxRetryAttempts?: number;
+    /** Number of failed reconnection attempts before showing user notifications. Prevents notification spam during brief network interruptions. */
+    notificationThreshold?: number;
+    /** Initial delay (in ms) when server closes with 1013 Try Again Later. The server explicitly asks to wait before reconnecting. */
+    tryAgainLaterDelayMs?: number;
+    /** Delay durations (in milliseconds) for each reconnection phase. */
+    delays?: {
+        firstPhase?: number;
+        secondPhase?: number;
+        thirdPhase?: number;
+    };
+    /** Threshold values that determine when to transition between reconnection phases. */
+    phaseThresholds?: {
+        first?: number;
+        second?: number;
+    };
+    /** Override connection cleanup delay when no listeners remain */
+    connectionCleanupDelayMs?: number;
+    /** Default timeout in ms when waiting for a message response. Used by WebsocketMessageApi */
+    messageResponseTimeoutMs?: number;
+    /** Override ping/pong heartbeat behavior */
+    heartbeat?: Partial<HeartbeatConfig>;
+    transformMessagePayload?: (payload: SendMessage<string, string, unknown>) => SendMessage<string, string, unknown>;
+    /**
+     * Callback for connection event logging. Receives events such as:
+     * - `{ type: 'open' | 'connect', url, retries, uriApis }`
+     * - `{ type: 'close', url, code, reason, wasClean, subscriptions }`
+     * - `{ type: 'reconnecting' | 'max-retries-exceeded', url, retries }`
+     * - `{ type: 'message-error', url, uri, uriApis, message }`
+     * - `{ type: 'invalid-message', url, uriApis, message }`
+     * - `{ type: 'parse-error', url, uriApis, message, error }`
+     * - `{ type: 'send-message', url, uri?, body, method? }`
+     * - `{ type: 'cleanup', url }`
+     * - `{ type: 'pong-timeout', url }`
+     *
+     * @param event - The connection event
+     */
+    connectionEvent?: (event: WebsocketLoggerConnectionEvent) => void;
+}
+
+/**
+ * Provides a {@link WebsocketClient} to the component tree.
+ *
+ * Wrap your app (or the part that uses WebSocket hooks) with this provider.
+ * Create the client once (e.g. at app startup) and pass it here.
+ *
+ * @example
+ * ```typescript
+ * const client = new WebsocketClient({ maxRetryAttempts: 10 });
+ * <WebsocketClientProvider client={client}>
+ *   <App />
+ * </WebsocketClientProvider>
+ * ```
+ */
+export declare const WebsocketClientProvider: FunctionComponent<PropsWithChildren<WebsocketClientProviderProps>>;
+
+/** Props for {@link WebsocketClientProvider}. */
+declare interface WebsocketClientProviderProps {
+    /** The WebsocketClient instance to provide to descendants. */
+    client: WebsocketClient;
+}
+
 /**
  * Manages a WebSocket connection with automatic reconnection, heartbeat monitoring, and URI-based message routing.
  *
@@ -271,7 +524,7 @@ export declare const useWebsocketSubscriptionByKey: <TData = unknown>(key: strin
  * - Heartbeat/ping mechanism to keep connections alive
  * - Multiple URI API registration for routing messages to different handlers
  * - Online/offline detection and handling
- * - Custom logger support for monitoring (configure via {@link setCustomLogger}
+ * - Custom logger support for monitoring (configure via {@link WebsocketClient} connectionEvent)
  * - User notifications for connection status
  *
  * @example
@@ -288,26 +541,15 @@ export declare const useWebsocketSubscriptionByKey: <TData = unknown>(key: strin
  * connection.addListener(uriApi);
  * ```
  *
- * @see {@link websocketConnectionsReconnect} - Reconnect all connections (e.g. on auth change)
- * @see {@link setCustomLogger} - Configure logging and connection-failed callback
+ * @see {@link WebsocketClient.reconnectAllConnections} - Reconnect all connections (e.g. on auth change)
  */
 export declare class WebsocketConnection {
-    /** Custom logger instance. Use {@link setCustomLogger} to configure. */
-    private static _logger;
-    /**
-     * Sets a custom logger for WebSocket connection events.
-     *
-     * @param logger - Logger implementation, or `undefined` to clear
-     */
-    static setCustomLogger(logger: WebsocketLogger | undefined): void;
     /** The underlying WebSocket instance */
     private _socket?;
     /** Map of all listeners (subscription and message APIs) keyed by their unique key */
     private _listeners;
     /** The WebSocket URL */
     private _url;
-    /** Display name extracted from URL pathname for user notifications */
-    private _name;
     /** Timeout for the next ping message */
     private pingTimeOut;
     /** Timeout for detecting missing pong after ping (dead-connection detection) */
@@ -325,13 +567,17 @@ export declare class WebsocketConnection {
      * Flushed when the connection opens. Subscribe messages are NOT cached — they trigger connect only.
      */
     private cachedMessages;
+    /** The WebsocketClient instance */
+    private _client;
     /**
      * Creates a new WebSocket connection instance.
-     * Note: The connection is not established until a URI API is added.
+     *
+     * The connection is not established until a listener is added via {@link addListener}.
      *
      * @param url - The WebSocket URL to connect to
+     * @param client - The {@link WebsocketClient} for configuration (reconnection, heartbeat, etc.)
      */
-    constructor(url: string);
+    constructor(url: string, client: WebsocketClient);
     /**
      * Gets the current ready state of the WebSocket connection.
      *
@@ -351,18 +597,6 @@ export declare class WebsocketConnection {
      * @returns The WebSocket instance if connected, or undefined if the connection hasn't been established yet or has been closed.
      */
     getSocket: () => WebSocket | undefined;
-    /**
-     * Retrieves a registered subscription API by its unique key.
-     * Message APIs are not returned; use {@link getWebsocketMessageApiByKey} for those.
-     *
-     * @template TData - The type of data stored in the subscription store
-     * @param key - The unique key identifying the subscription (must match the key used in {@link addListener})
-     * @returns The {@link WebsocketSubscriptionApi} instance if found, or `undefined`
-     *
-     * @see {@link addListener} - Method to register a listener
-     * @see {@link getWebsocketUriApiByKey} - Global function to search across all connections
-     */
-    getUriApiByKey: <TData = unknown>(key: string) => WebsocketSubscriptionApi<TData, any> | undefined;
     /**
      * Registers a listener (subscription or message API) with this connection.
      *
@@ -379,13 +613,13 @@ export declare class WebsocketConnection {
      * Unregisters a listener and schedules connection cleanup if no listeners remain.
      *
      * Disconnects the listener's send callback and removes it from the routing map.
-     * The WebSocket connection will be closed after {@link CONNECTION_CLEANUP_DELAY} if no other
+     * The WebSocket connection will be closed after {@link CONNECTION_CLEANUP_DELAY_MS} if no other
      * listeners are registered.
      *
      * @param listener - The listener instance to unregister
      */
     removeListener: (listener: WebsocketListener) => void;
-    /** Schedules connection close after {@link CONNECTION_CLEANUP_DELAY} when no listeners remain. */
+    /** Schedules connection close after configured delay when no listeners remain. */
     private scheduleConnectionCleanup;
     /**
      * Replaces the WebSocket URL and re-establishes the connection.
@@ -456,7 +690,7 @@ export declare class WebsocketConnection {
      * Shows user notifications after the threshold number of attempts.
      * Only attempts reconnection when the browser is online.
      * When closeCode is 1013 (Try Again Later), waits an extra delay before reconnecting.
-     * Stops after {@link RECONNECTION_CONFIG.MAX_RETRY_ATTEMPTS} and shows a permanent error with a manual retry button.
+     * Stops after configured MAX_RETRY_ATTEMPTS and shows a permanent error with a manual retry button.
      *
      * @param closeCode - Optional WebSocket close code; used to apply TRY_AGAIN_LATER delay when 1013
      */
@@ -547,7 +781,7 @@ export declare class WebsocketConnection {
     private clearPongTimeout;
     /**
      * Schedules a timeout to detect missing pong. If no pong arrives within
-     * {@link HEARTBEAT_CONFIG.PONG_TIMEOUT_MS}, force-closes the socket to trigger reconnection.
+     * configured pong timeout, force-closes the socket to trigger reconnection.
      */
     private schedulePongTimeout;
     /**
@@ -576,8 +810,6 @@ export declare class WebsocketConnection {
     private forEachMatchingListener;
 }
 
-export declare const websocketConnectionsReconnect: () => void;
-
 /**
  * Common interface for WebSocket listeners registered with {@link WebsocketConnection}.
  *
@@ -606,19 +838,44 @@ export declare interface WebsocketListener {
     hasWaitingUri?(uri: string): boolean;
     /** Message listeners: delivers a response for a pending request */
     deliverMessage?(uri: string, data: unknown): void;
+    readonly type: 'subscription' | 'message';
 }
 
 /**
  * Optional custom logger for WebSocket connection events.
- * Set via {@link WebsocketConnection.setCustomLogger}.
+ * Set via {@link WebsocketConfig.setCustomLogger}.
  */
 export declare interface WebsocketLogger {
     /** Logs connection events (e.g. ws-connect, ws-close, ws-error, ws-reconnect) */
-    log?(level: 'debug' | 'info' | 'warn' | 'error', message: string, context?: Record<string, unknown>): void;
     /** Called when max retry attempts exceeded; use to trigger token refresh or other recovery */
-    connectionFailed?: (url: string, retries: number, subscriptions: number) => void;
+    connectionEvents?: (event: WebsocketLoggerConnectionEvent) => void;
 }
 
+/* Excluded from this release type: WebsocketLoggerCleanupEvent */
+
+/* Excluded from this release type: WebsocketLoggerCloseEvent */
+
+/** Union of all connection event types passed to {@link WebsocketClientOverrides.connectionEvent}. */
+export declare type WebsocketLoggerConnectionEvent = WebsocketLoggerCloseEvent | WebsocketLoggerOpenEvent | WebsocketLoggerMessageEvent | WebsocketLoggerErrorEvent | WebsocketLoggerReconnectingEvent | WebsocketLoggerPongTimeoutEvent | WebsocketLoggerInvalidMessageEvent | WebsocketLoggerMessageErrorEvent | WebsocketLoggerParseErrorEvent | WebsocketLoggerSendMessageEvent | WebsocketLoggerCleanupEvent;
+
+/* Excluded from this release type: WebsocketLoggerErrorEvent */
+
+/* Excluded from this release type: WebsocketLoggerInvalidMessageEvent */
+
+/* Excluded from this release type: WebsocketLoggerMessageErrorEvent */
+
+/* Excluded from this release type: WebsocketLoggerMessageEvent */
+
+/* Excluded from this release type: WebsocketLoggerOpenEvent */
+
+/* Excluded from this release type: WebsocketLoggerParseErrorEvent */
+
+/* Excluded from this release type: WebsocketLoggerPongTimeoutEvent */
+
+/* Excluded from this release type: WebsocketLoggerReconnectingEvent */
+
+/* Excluded from this release type: WebsocketLoggerSendMessageEvent */
+
 /**
  * Manages WebSocket request/response messaging without subscription.
  *
@@ -669,9 +926,18 @@ export declare class WebsocketMessageApi implements WebsocketListener {
     private _pendingMessages;
     private _registeredHooks;
     private _hookRemovalTimeout;
-    constructor(options: WebsocketMessageOptions);
+    private _client;
+    readonly type = "message";
+    /**
+     * Creates a new WebsocketMessageApi.
+     *
+     * @param options - Configuration options (url, key, callbacks, etc.)
+     * @param client - The {@link WebsocketClient} for timeout defaults and connection management
+     */
+    constructor(options: WebsocketMessageOptions, client: WebsocketClient);
     /** Unique key identifier for this Message API. */
     get key(): string;
+    /** WebSocket URL for Datadog tracking. */
     get url(): string;
     /** Whether this Message API is enabled. */
     get isEnabled(): boolean;
@@ -889,11 +1155,18 @@ export declare class WebsocketSubscriptionApi<TData = unknown, TBody = unknown>
     private _hookRemovalTimeout;
     private _sendToConnection;
     private _pendingMessages;
+    readonly type = "subscription";
+    /**
+     * Creates a new WebsocketSubscriptionApi.
+     *
+     * @param options - Configuration options (url, uri, key, callbacks, etc.)
+     */
     constructor(options: WebsocketSubscriptionOptions<TData, TBody>);
     /** Unique key identifier for this WebSocket URI API. */
     get key(): string;
     /** URI path for this WebSocket subscription. */
     get uri(): string;
+    /** WebSocket URL for Datadog tracking. */
     get url(): string;
     /** Configuration options for this WebSocket URI. */
     get options(): WebsocketSubscriptionOptions<TData, TBody>;
@@ -1078,9 +1351,9 @@ export declare interface WebsocketSubscriptionOptions<TData = unknown, TBody = u
      */
     onError?: (error: WebsocketTransportError) => void;
     /**
-     * A callback function called when an error occurs with a subscription or message.
+     * Callback invoked when a server error message is received for this subscription.
      *
-     * @param event - The error event object.
+     * @param error - Server error with parsed message body (`error.type === 'server'`, `error.message` contains the incoming message)
      */
     onMessageError?: (error: WebsocketServerError<TBody>) => void;
     /**