@maxtroost/use-websocket 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1122 @@
+import { Store } from '@tanstack/react-store';
+import { Store as Store_2 } from '@tanstack/store';
+
+/** Creates the initial state for a WebsocketSubscriptionStore. */
+export declare function createInitialWebsocketSubscriptionStore<TData = unknown>(): WebsocketSubscriptionStore<TData>;
+
+/**
+ * Structure of incoming WebSocket messages.
+ *
+ * Messages must have a URI for routing to the correct handler and can include
+ * an optional body with the actual message data.
+ *
+ * @template TBody - The type of the message body payload
+ */
+export declare interface IncomingWebsocketMessage<TBody = unknown> {
+    /** URI path that identifies which handler should process this message */
+    uri: string;
+    /** Optional message body/payload */
+    body?: TBody;
+    /** HTTP-like method for the message (e.g., 'subscribe', 'unsubscribe', 'post') */
+    method?: string;
+}
+
+/**
+ * WebSocket connection ready states.
+ *
+ * Values match the WebSocket API readyState constants, with an additional
+ * UNINSTANTIATED state for connections that haven't been created yet.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState
+ */
+declare enum ReadyState_2 {
+    /** Connection has not been instantiated yet */
+    UNINSTANTIATED = -1,
+    /** Connection is being established */
+    CONNECTING = 0,
+    /** Connection is open and ready to communicate */
+    OPEN = 1,
+    /** Connection is in the process of closing */
+    CLOSING = 2,
+    /** Connection is closed or couldn't be opened */
+    CLOSED = 3
+}
+export { ReadyState_2 as ReadyState }
+
+/**
+ * Structure for outgoing WebSocket messages.
+ *
+ * Messages are sent with a method (HTTP-like), URI for routing, optional body,
+ * and an automatically generated correlation ID for tracking.
+ *
+ * @template TMethod - The type of the HTTP method (e.g., 'subscribe', 'unsubscribe', 'post')
+ * @template TUri - The type of the URI string
+ * @template TBody - The type of the message body payload
+ */
+export declare interface SendMessage<TMethod = string, TUri = string, TBody = unknown> {
+    /** HTTP-like method for the message (e.g., 'subscribe', 'unsubscribe', 'post') */
+    method?: TMethod;
+    /** URI path for routing the message to the correct handler */
+    uri?: TUri;
+    /** Optional message body/payload */
+    body?: TBody;
+    /** Correlation ID for tracking messages (automatically generated) */
+    correlation?: string;
+}
+
+/**
+ * Options for WebsocketMessageApi.sendMessage.
+ */
+export declare interface SendMessageOptions {
+    /** Timeout in ms when waiting for a response. Overrides the default from options. */
+    timeout?: number;
+}
+
+/**
+ * Callback function for sending messages from a {@link WebsocketSubscriptionApi} to its parent {@link WebsocketConnection}.
+ *
+ * This callback is injected by the connection when a URI API is registered,
+ * replacing the previous EventTarget/CustomEvent indirection with a direct,
+ * type-safe function call.
+ */
+export declare type SendToConnectionFn = (message: SendMessage<string, string, unknown>) => void;
+
+/**
+ * React hook that manages a WebSocket Message API for request/response style messaging.
+ *
+ * Use this for one-off commands (validate, modify, mark read) rather than streaming
+ * subscriptions. Send to any URI; optionally await a response.
+ *
+ * ## Key Features
+ *
+ * - **Request/Response**: `sendMessage(uri, method, body?, options?)` returns a Promise that resolves with the response
+ * - **Fire-and-forget**: `sendMessageNoWait(uri, method, body?)` for commands that don't need a response
+ * - **Any URI**: Not bound to a single URI like subscription APIs
+ * - **Shared Instance**: Multiple components with the same `key` share the same Message API
+ * - **Automatic Cleanup**: Removes from connection when the last hook unmounts
+ *
+ * @template TData - The type of data received in the response
+ * @template TBody - The type of message body sent to the WebSocket
+ *
+ * @param options - Configuration options including:
+ *   - `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)
+ *   - `onError`, `onMessageError`, `onClose`: Optional callbacks
+ * @returns {@link WebsocketMessageApiPublic} with `sendMessage`, `sendMessageNoWait`, `reset`, `url`, `key`, `isEnabled`
+ *
+ * @example
+ * ```typescript
+ * const api = useWebsocketMessage<ModifyVoyageUim, ModifyVoyageUim>({
+ *   key: 'voyages/modify',
+ *   url: '/api',
+ *   responseTimeoutMs: 5000
+ * });
+ *
+ * // Await response (full form: uri, method, body?, options?)
+ * const result = await api.sendMessage('voyages/modify/validate', 'post', formValues);
+ *
+ * // Fire-and-forget
+ * api.sendMessageNoWait(`notifications/${id}/read`, 'post');
+ * ```
+ *
+ * ## Edge Cases
+ *
+ * - **Overwrite**: Sending to the same URI while a request is pending cancels the previous
+ *   request (rejects with "WebSocket request overwritten for URI").
+ * - **Disabled**: When `enabled=false`, `sendMessage` rejects; `sendMessageNoWait` is a no-op.
+ * - **Connection closed**: Pending requests are rejected with "WebSocket connection closed".
+ *
+ * @see {@link WebsocketMessageApiPublic} - Public API surface
+ */
+export declare const useWebsocketMessage: (options: WebsocketMessageOptions) => WebsocketMessageApiPublic;
+
+/**
+ * React hook that manages a WebSocket subscription for a specific Subscription endpoint.
+ *
+ * This hook provides a reactive interface to the WebSocket connection system. It establishes
+ * the connection architecture by linking three key components:
+ *
+ * ## Architecture Overview
+ *
+ * The hook integrates with a two-layer class architecture:
+ *
+ * 1. **WebsocketConnection** (singleton per URL)
+ *    - 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
+ *      connection exists per WebSocket URL
+ *
+ * 2. **WebsocketSubscriptionApi** (one per subscription per connection)
+ *    - Manages subscription lifecycle for a specific URI endpoint
+ *    - Provides a TanStack Store for reactive data updates
+ *    - Handles subscribe/unsubscribe operations
+ *    - Registered via `connection.addListener(subscriptionApi)` which routes messages by URI
+ *
+ * ## How the Hook Links to Classes
+ *
+ * ```
+ * useWebsocketSubscription
+ *   │
+ *   ├─→ createWebsocketSubscriptionApi(key, options)
+ *   │     └─→ Returns/creates WebsocketSubscriptionApi singleton (per key)
+ *   │           ├─→ Manages subscription for this specific URI
+ *   │           ├─→ Provides reactive store for data updates
+ *   │           └─→ Handles subscribe/unsubscribe lifecycle
+ *   │
+ *   └─→ findOrCreateWebsocketConnection(url, url)
+ *         └─→ Returns/creates WebsocketConnection singleton (per URL)
+ *               ├─→ Manages WebSocket connection (connect, reconnect, heartbeat)
+ *               ├─→ Routes messages to registered listeners
+ *               └─→ connection.addListener(subscriptionApi) registers the listener
+ * ```
+ *
+ * ## Lifecycle Management
+ *
+ * - **URI API**: Created once via `useState` initializer (singleton per key via
+ *   `createWebsocketUriApi`). Multiple components can share the same URI API,
+ *   tracked via registered hook IDs.
+ *
+ * - **Connection**: Found or created in a `useIsomorphicLayoutEffect` that watches
+ *   `enabled`. The connection is a singleton per key, shared across all hooks using
+ *   the same base URL path.
+ *
+ * - **Options Updates**: `useIsomorphicLayoutEffect` synchronously updates URI API options
+ *   via the `options` setter when they change (deep-compared via `useDeepCompareMemoize`),
+ *   preventing rendering with stale configuration.
+ *
+ * - **URL Replacement**: A separate `useIsomorphicLayoutEffect` watches `wsUrl` and calls
+ *   `connection.replaceUrl()` when the URL changes (e.g. due to auth context changes).
+ *
+ * - **Cleanup**: `useEffect` registers this hook instance as a hook and provides cleanup
+ *   that removes it. When the last hook is removed, the URI API automatically unsubscribes
+ *   and is removed from the connection.
+ *
+ * @template TData - The type of data received from the WebSocket for this URI
+ * @template TBody - The type of message body sent to the WebSocket for this URI
+ *
+ * @param options - Configuration options including:
+ *   - `url`: The WebSocket URL
+ *   - `uri`: The specific URI endpoint for this subscription
+ *   - `key`: Unique identifier for this subscription (used to retrieve it elsewhere via `useWebsocketSubscriptionByKey`)
+ *   - `enabled`: Whether this subscription is enabled (default: true)
+ *   - `body`: Optional payload for subscription or initial message
+ *   - `onMessage`, `onSubscribe`, `onError`, `onMessageError`, `onClose`: Optional callbacks
+ * @returns The {@link WebsocketSubscriptionApiPublic} instance. Use `useStore(api.store, (s) => s.message)` to read data reactively.
+ *
+ * @example
+ * ```typescript
+ * // Create subscription and read data via TanStack Store
+ * const voyageApi = useWebsocketSubscription<Voyage[], VoyageFilters>({
+ *   key: 'voyages-list',
+ *   url: '/api',
+ *   uri: '/api/voyages',
+ *   body: { status: 'active' }
+ * });
+ * const voyages = useStore(voyageApi.store, (s) => s.message);
+ *
+ * // Or use useWebsocketSubscriptionByKey in children to access the same store
+ * const voyagesStore = useWebsocketSubscriptionByKey<Voyage[]>('voyages-list');
+ * const voyages = useStore(voyagesStore, (s) => s.message);
+ * ```
+ *
+ * ## Edge Cases
+ *
+ * - **Multiple initiators**: Using the same `key` in multiple components registers multiple hooks.
+ *   A console warning is emitted; multiple initiators can cause unexpected behavior.
+ * - **pendingSubscription**: Use `store.pendingSubscription` for loading states — it is `true`
+ *   from subscribe until the first message is received.
+ *
+ * @see {@link useWebsocketSubscriptionByKey} - Access the store when the subscription is created in a parent
+ * @see {@link WebsocketSubscriptionStore} - Store shape: `{ message, subscribed, connected, ... }`
+ */
+export declare function useWebsocketSubscription<TData = unknown, TBody = unknown>(options: WebsocketSubscriptionOptions<TData, TBody>): WebsocketSubscriptionApiPublic<TData, TBody>;
+
+/**
+ * React hook that returns the store of a WebSocket subscription by key.
+ *
+ * Use when a parent creates the subscription via `useWebsocketSubscription` and
+ * children need to read the data. The `key` must match the one used when creating
+ * the subscription.
+ *
+ * **Edge case**: Returns a fallback store (initial empty state) if the subscription
+ * does not exist yet (e.g. parent hasn't mounted). This avoids null checks but means
+ * children may briefly see empty data before the parent mounts and subscribes.
+ *
+ * @template TData - The type of data in the store's `message` field
+ * @param key - Unique key (must match `useWebsocketSubscription` options.key)
+ * @returns TanStack {@link Store} with shape {@link WebsocketSubscriptionStore}
+ *
+ * @example
+ * ```typescript
+ * // Parent creates subscription
+ * useWebsocketSubscription<Voyage[]>({ key: 'voyages-list', url: '...', uri: '...' });
+ *
+ * // Child reads store by key
+ * const voyagesStore = useWebsocketSubscriptionByKey<Voyage[]>('voyages-list');
+ * const voyages = useStore(voyagesStore, (s) => s.message);
+ * ```
+ *
+ * @see {@link WebsocketSubscriptionStore} - Store shape
+ */
+export declare const useWebsocketSubscriptionByKey: <TData = unknown>(key: string) => Store_2<WebsocketSubscriptionStore<TData>>;
+
+/**
+ * Manages a WebSocket connection with automatic reconnection, heartbeat monitoring, and URI-based message routing.
+ *
+ * This class provides:
+ * - Automatic reconnection with exponential backoff on connection loss
+ * - 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}
+ * - User notifications for connection status
+ *
+ * @example
+ * ```typescript
+ * const connection = new WebsocketConnection('ws://example.com/api');
+ * const uriApi = new WebsocketSubscriptionApi({
+ *   key: 'messages',
+ *   url: '/api',
+ *   uri: '/messages',
+ *   onMessage: ({ data }) => console.log('Received:', data),
+ *   onError: (error) => console.log('Error:', error),
+ *   onClose: (event) => console.log('Closed:', event)
+ * });
+ * connection.addListener(uriApi);
+ * ```
+ *
+ * @see {@link websocketConnectionsReconnect} - Reconnect all connections (e.g. on auth change)
+ * @see {@link setCustomLogger} - Configure logging and connection-failed callback
+ */
+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) */
+    private pongTimeOut;
+    /** Timeout for closing the connection when no URIs are registered */
+    private closeConnectionTimeOut;
+    /** Counter for reconnection attempts */
+    private reconnectTries;
+    /** Guard flag that prevents concurrent teardown-and-reconnect cycles (e.g. when both replaceUrl and reconnect fire in the same render). */
+    private _isReconnecting;
+    /** True when max retry attempts exceeded; stops automatic reconnection until manual retry. */
+    private _maxRetriesExceeded;
+    /**
+     * Queue of non-subscribe messages sent while the socket was not open.
+     * Flushed when the connection opens. Subscribe messages are NOT cached — they trigger connect only.
+     */
+    private cachedMessages;
+    /**
+     * Creates a new WebSocket connection instance.
+     * Note: The connection is not established until a URI API is added.
+     *
+     * @param url - The WebSocket URL to connect to
+     */
+    constructor(url: string);
+    /**
+     * Gets the current ready state of the WebSocket connection.
+     *
+     * @returns The WebSocket ready state (CONNECTING=0, OPEN=1, CLOSING=2, CLOSED=3) or undefined if no socket exists.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState | WebSocket.readyState}
+     */
+    get readyState(): number | undefined;
+    /**
+     * Gets the WebSocket URL for this connection.
+     *
+     * @returns The WebSocket URL string
+     */
+    get url(): string;
+    /**
+     * Gets the underlying WebSocket instance.
+     *
+     * @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.
+     *
+     * Initiates the WebSocket connection if not already connected. Sets up the send callback
+     * so the listener can transmit messages through this connection.
+     *
+     * If the socket is already open, immediately notifies subscription listeners via `onOpen`.
+     *
+     * @param listener - The {@link WebsocketListener} to register
+     * @returns The registered listener
+     */
+    addListener: (listener: WebsocketListener) => WebsocketListener;
+    /**
+     * 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
+     * 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. */
+    private scheduleConnectionCleanup;
+    /**
+     * Replaces the WebSocket URL and re-establishes the connection.
+     *
+     * Closes the current connection, resets all listeners, and reconnects using the new URL
+     * after a short delay (1 second) to allow cleanup to complete.
+     *
+     * @param newUrl - The new WebSocket URL to connect to
+     */
+    replaceUrl: (newUrl: string) => Promise<void>;
+    /**
+     * Reconnects the WebSocket connection.
+     *
+     * Tears down the current connection by removing all event listeners, closing the socket,
+     * and resetting all registered URI APIs. After a short delay (1 second) to allow cleanup,
+     * re-establishes the connection. Typically triggered by {@link websocketConnectionsReconnect}
+     * when {@link useReconnectWebsocketConnections} (from @mono-fleet/common-components) detects
+     * the user's authentication context (region/role) change.
+     *
+     * Guarded by {@link _isReconnecting} in {@link teardownAndReconnect} — if a `replaceUrl`
+     * layout effect already started a reconnect cycle in the same render, this call is a no-op.
+     */
+    reconnect: () => Promise<void>;
+    /**
+     * Resets the retry counter and re-establishes the connection.
+     *
+     * Used when the user manually retries after hitting {@link RECONNECTION_CONFIG.MAX_RETRY_ATTEMPTS}.
+     * Clears the max-retries-exceeded state and initiates a fresh connection attempt.
+     */
+    resetRetriesAndReconnect: () => void;
+    /**
+     * Establishes the WebSocket connection if not already connecting or connected.
+     * Only creates a socket if at least one registered listener (subscription or message API) is enabled.
+     * Sets up all event listeners and logs the connection attempt via the custom logger if configured.
+     */
+    private connect;
+    /**
+     * Tears down the current socket: clears all timers, removes all event listeners,
+     * closes the socket, and resets the socket reference.
+     */
+    private teardownSocket;
+    /**
+     * Tears down the current connection, resets all listeners, waits for cleanup to complete,
+     * and re-establishes the connection. Shared by {@link replaceUrl} and {@link reconnect}.
+     *
+     * Guarded by {@link _isReconnecting} to prevent concurrent cycles. When
+     * `selectedRegionRole` changes, both the hook's `replaceUrl` layout effect and
+     * `useReconnectWebsocketConnections`'s reconnect effect may fire. Because layout effects run
+     * before regular effects, `replaceUrl` wins and updates the URL first; the reconnect call
+     * is safely skipped.
+     */
+    private teardownAndReconnect;
+    /**
+     * Cleans up the WebSocket connection when no listeners are registered.
+     */
+    private cleanupConnection;
+    /**
+     * Clears all active timers (ping heartbeat, pong timeout, and connection cleanup).
+     */
+    private clearAllTimers;
+    /**
+     * Removes all event listeners from the WebSocket and window objects.
+     * Used during cleanup and reconnection processes.
+     */
+    private removeListeners;
+    /**
+     * Attempts to reconnect the WebSocket connection with exponential backoff.
+     * 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.
+     *
+     * @param closeCode - Optional WebSocket close code; used to apply TRY_AGAIN_LATER delay when 1013
+     */
+    private attemptReconnection;
+    /**
+     * Checks if the browser is offline and, if so, defers reconnection until it comes back online
+     * by registering a one-time 'online' event listener.
+     *
+     * @returns `true` if reconnection was deferred (browser is offline), `false` if browser is online
+     */
+    private deferReconnectionUntilOnline;
+    /**
+     * Handles WebSocket close events.
+     *
+     * Implements automatic reconnection for any non-intentional close (anything other than
+     * 1000 Normal Closure). This includes 1001 Going Away, 1011 Internal Error, 1012 Service
+     * Restart, 1013 Try Again Later, 1006 Abnormal Closure, and other server-initiated codes.
+     * Reconnection only occurs when listeners are still registered. Shows user notifications
+     * after {@link RECONNECTION_CONFIG.NOTIFICATION_THRESHOLD} failed attempts.
+     * Cleans up the connection if no listeners remain. Logs the close event via the custom logger if configured.
+     *
+     * @param event - The WebSocket close event containing code, reason, and whether the close was clean
+     */
+    private handleClose;
+    /**
+     * Handles WebSocket open/connected events.
+     *
+     * Sets up offline detection, dismisses reconnection notifications, shows success message
+     * for recovered connections (only if {@link RECONNECTION_CONFIG.NOTIFICATION_THRESHOLD}
+     * was exceeded), resets reconnection counter, notifies all listeners, flushes cached
+     * messages, and initiates the heartbeat ping sequence.
+     */
+    private handleOpen;
+    /**
+     * Handles incoming WebSocket messages.
+     *
+     * Routes messages to matching listeners: subscription APIs by URI, message APIs by pending request URI.
+     * Special handling for 'ping' messages to maintain heartbeat.
+     * Dispatches error-method messages to listener error handlers.
+     *
+     * @param event - The WebSocket message event containing JSON data
+     */
+    private handleMessage;
+    /**
+     * Handles WebSocket error events.
+     * Logs the error via the custom logger if configured and notifies all registered listeners.
+     *
+     * @param event - The WebSocket error event
+     */
+    private handleError;
+    /**
+     * Handles browser coming back online during offline detection.
+     * Removes the online listener and re-establishes the connection.
+     */
+    private handleOnline;
+    /**
+     * Handles browser coming back online during reconnection attempts.
+     * Removes the online listener and resumes reconnection with a decremented counter
+     * to avoid adding extra wait time from being offline.
+     */
+    private handleOnlineForReconnection;
+    /**
+     * Handles browser going offline.
+     *
+     * Notifies all listeners of the closure, tears down the socket, and sets up
+     * a listener to reconnect when the browser comes back online.
+     */
+    private handleOffline;
+    /**
+     * Handles outgoing messages from listeners.
+     *
+     * - If socket is OPEN: serializes with correlation ID and sends immediately.
+     * - If socket is not open: subscribe messages trigger connect only; other messages are
+     *   cached and sent when the connection opens.
+     *
+     * Passed to each listener via {@link WebsocketListener.setSendToConnection}.
+     */
+    private handleSendMessage;
+    /**
+     * Sends a heartbeat ping message to keep the connection alive and detect disconnections.
+     * Sets a pong timeout; if no pong arrives within HEARTBEAT_CONFIG.PONG_TIMEOUT_MS,
+     * the connection is force-closed to trigger reconnection.
+     */
+    private sendPing;
+    /**
+     * Clears the pong timeout (e.g. when a pong is received).
+     */
+    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.
+     */
+    private schedulePongTimeout;
+    /**
+     * Schedules the next heartbeat ping after the configured interval (40 seconds).
+     * @see {@link getPingTime}
+     */
+    private schedulePing;
+    /**
+     * Serializes a message with a unique correlation ID for WebSocket transmission.
+     * @param message - The message to serialize
+     * @returns JSON string for WebSocket send
+     */
+    private serializeMessage;
+    /**
+     * Executes a callback for each listener that matches the given URI.
+     *
+     * - **Subscription listeners**: Match when `listener.uri === uri`
+     * - **Message listeners**: Match when `listener.hasWaitingUri(uri)` (pending request/response)
+     *
+     * A single message can be delivered to multiple listeners if both a subscription
+     * and a message API are waiting for the same URI.
+     *
+     * @param uri - The URI from the incoming message
+     * @param callback - Callback invoked for each matching listener
+     */
+    private forEachMatchingListener;
+}
+
+export declare const websocketConnectionsReconnect: () => void;
+
+/**
+ * Common interface for WebSocket listeners registered with {@link WebsocketConnection}.
+ *
+ * Both {@link WebsocketSubscriptionApi} and {@link WebsocketMessageApi} implement this interface,
+ * allowing the connection to treat them uniformly via {@link addListener} / {@link removeListener}.
+ *
+ * - **Subscription listeners**: Have `uri`, `onOpen`, `onMessage` — route by URI match
+ * - **Message listeners**: Have `hasWaitingUri`, `deliverMessage` — route by pending URI
+ */
+export declare interface WebsocketListener {
+    readonly key: string;
+    readonly url: string;
+    readonly isEnabled: boolean;
+    setSendToConnection(callback: SendToConnectionFn | null): void;
+    onError(error: WebsocketTransportError): void;
+    onMessageError(error: WebsocketServerError<unknown>): void;
+    onClose(event: CloseEvent): void;
+    reset(): void;
+    /** Subscription listeners: fixed URI for this endpoint */
+    readonly uri?: string;
+    /** Subscription listeners: called when connection opens */
+    onOpen?(): void;
+    /** Subscription listeners: called when a message is received for this URI */
+    onMessage?(data: unknown): void;
+    /** Message listeners: returns true if waiting for a response for the given URI */
+    hasWaitingUri?(uri: string): boolean;
+    /** Message listeners: delivers a response for a pending request */
+    deliverMessage?(uri: string, data: unknown): void;
+}
+
+/**
+ * Optional custom logger for WebSocket connection events.
+ * Set via {@link WebsocketConnection.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;
+}
+
+/**
+ * Manages WebSocket request/response messaging without subscription.
+ *
+ * Use for one-off commands (validate, modify, mark read) rather than streaming.
+ * Send to any URI; optionally await a response. Tracks URIs only while waiting.
+ *
+ * ## Key Features
+ *
+ * - **Any URI**: Not bound to a single URI like {@link WebsocketSubscriptionApi}
+ * - **Request/Response**: `sendMessage` returns a Promise; optional per-call timeout
+ * - **Fire-and-forget**: `sendMessageNoWait` for commands that don't need a response
+ * - **No Subscription**: Use WebsocketSubscriptionApi for streaming data
+ *
+ * ## Edge Cases
+ *
+ * - **Overwrite**: Sending to the same URI while a request is pending cancels the previous
+ *   request — the previous Promise rejects with "WebSocket request overwritten for URI".
+ * - **Disabled**: When `enabled=false`, `sendMessage` rejects; `sendMessageNoWait` is a no-op.
+ * - **Connection closed**: All pending requests reject with "WebSocket connection closed".
+ * - **Queued messages**: If the connection is not yet open, messages are queued and sent
+ *   when the connection opens (via `setSendToConnection`).
+ *
+ * ## Cleanup
+ *
+ * {@link reset} is called by WebsocketConnection when the URL changes or during reconnection.
+ * When the last hook unmounts, {@link unregisterHook} triggers removal after
+ * {@link INITIATOR_REMOVAL_DELAY_MS}.
+ *
+ * @template TData - The type of data received in the response
+ * @template TBody - The type of message body sent to the WebSocket
+ *
+ * @example
+ * ```typescript
+ * const api = new WebsocketMessageApi<MyResponse, MyRequest>({
+ *   url: 'wss://example.com',
+ *   key: 'my-message-api',
+ *   responseTimeoutMs: 5000
+ * });
+ * connection.addListener(api);
+ *
+ * const response = await api.sendMessage('/api/command', 'post', { action: 'refresh' });
+ * ```
+ */
+export declare class WebsocketMessageApi implements WebsocketListener {
+    private _options;
+    private _sendToConnection;
+    private _pendingByUri;
+    private _pendingMessages;
+    private _registeredHooks;
+    private _hookRemovalTimeout;
+    constructor(options: WebsocketMessageOptions);
+    /** Unique key identifier for this Message API. */
+    get key(): string;
+    get url(): string;
+    /** Whether this Message API is enabled. */
+    get isEnabled(): boolean;
+    /**
+     * Returns whether this API is waiting for a response for the given URI.
+     *
+     * Used by {@link WebsocketConnection} to route incoming messages to the correct
+     * listener. Message API receives messages only for URIs with pending requests.
+     *
+     * @param uri - The URI to check
+     * @returns `true` if a request is pending for this URI
+     */
+    hasWaitingUri: (uri: string) => boolean;
+    /**
+     * Registers a hook (component) that is using this Message API.
+     *
+     * Tracks the hook ID so the API is only removed from the connection when
+     * the last hook unmounts.
+     *
+     * @param id - Unique identifier for the registering hook
+     */
+    registerHook: (id: string) => void;
+    /**
+     * Unregisters a hook from this Message API.
+     *
+     * After {@link INITIATOR_REMOVAL_DELAY_MS}, if no hooks remain, invokes the
+     * cleanup callback to remove this API from the connection. The delay prevents
+     * rapid subscribe/unsubscribe cycles during React re-renders.
+     *
+     * @param id - The hook ID to unregister
+     * @param onRemove - Callback invoked when the last hook is removed (after delay)
+     */
+    unregisterHook: (id: string, onRemove: () => void) => void;
+    /**
+     * Disconnects this Message API from the parent WebSocket connection.
+     *
+     * Called when the hook is disabled. After a delay, invokes the cleanup callback.
+     * Clears any pending hook-removal timeout to avoid duplicate cleanup.
+     *
+     * @param onRemoveFromSocket - Callback invoked after delay to remove from connection
+     */
+    disconnect: (onRemoveFromSocket: () => void) => void;
+    /**
+     * Sets or clears the callback used to send messages through the parent WebSocket connection.
+     *
+     * When setting a callback, flushes any queued messages. When clearing, cancels all
+     * pending requests and clears the hook removal timeout to avoid redundant cleanup.
+     *
+     * @param callback - The send function, or null to disconnect
+     */
+    setSendToConnection: (callback: SendToConnectionFn | null) => void;
+    /**
+     * Delivers an incoming message for a URI we're waiting on.
+     *
+     * Called by WebsocketConnection when a message arrives for a URI with a pending request.
+     *
+     * @param uri - The URI the response is for
+     * @param data - The response data
+     */
+    deliverMessage: (uri: string, data: unknown) => void;
+    /**
+     * Sends a message to the given URI and optionally waits for a response.
+     *
+     * **Overwrite behavior**: If a request is already pending for this URI, it is
+     * cancelled (rejected with "WebSocket request overwritten for URI") and replaced.
+     *
+     * @param uri - The URI to send the message to
+     * @param bodyOrMethod - Message body (short form) or HTTP method (full form)
+     * @param bodyOrOptions - Message body or options (full form)
+     * @param options - Per-call options when using full signature
+     * @returns Promise that resolves with the response data; rejects on timeout, overwrite, or disabled
+     *
+     * @example
+     * await api.sendMessage('/api/command', 'post', { action: 'refresh' });
+     * await api.sendMessage('/api/command', 'post', { action: 'refresh' }, { timeout: 5000 });
+     */
+    sendMessage<TData = unknown, TBody = unknown>(uri: string, method: string, body?: TBody, options?: SendMessageOptions): Promise<TData>;
+    /**
+     * Sends a message without waiting for a response (fire-and-forget).
+     *
+     * @param uri - The URI to send the message to
+     * @param methodOrBody - HTTP method (full form) or message body (short form)
+     * @param body - Message body when using full form
+     *
+     * @example
+     * api.sendMessageNoWait('/api/log', 'post', { event: 'click' });
+     */
+    sendMessageNoWait<TBody = unknown>(uri: string, method: string, body?: TBody): void;
+    /** @inheritdoc */
+    onError: (error: WebsocketTransportError) => void;
+    /** @inheritdoc */
+    onMessageError: (error: WebsocketServerError) => void;
+    /** @inheritdoc */
+    onClose: (event: CloseEvent) => void;
+    /**
+     * Resets this Message API, cancelling all pending requests.
+     *
+     * Called by WebsocketConnection when the URL changes or during reconnection.
+     * Clears the hook removal timeout to prevent stale cleanup callbacks.
+     */
+    reset: () => void;
+    private _clearHookRemovalTimeout;
+    private _scheduleHookRemoval;
+    private _flushPendingMessages;
+    private _sendOrQueue;
+    private _cancelPendingForUri;
+    private _cancelAllPending;
+}
+
+export declare type WebsocketMessageApiPublic = Pick<WebsocketMessageApi, 'sendMessage' | 'sendMessageNoWait' | 'reset' | 'url' | 'key' | 'isEnabled'>;
+
+/**
+ * Configuration options for WebSocket Message API.
+ *
+ * Message API is for request/response style communication: send a message to any URI
+ * and optionally wait for a response. No subscription support.
+ *
+ * @template TData - The type of data received in the response
+ * @template TBody - The type of message body sent to the WebSocket
+ */
+export declare interface WebsocketMessageOptions {
+    /** The base URL of the WebSocket connection. */
+    url: string;
+    /**
+     * Unique key for the Message API.
+     *
+     * Used to identify the API in the connection.
+     */
+    key: string;
+    /** Whether this Message API is enabled (default: true). When disabled, messages are not sent. */
+    enabled?: boolean;
+    /**
+     * Default timeout in ms when waiting for a response.
+     *
+     * Can be overridden per sendMessage call.
+     */
+    responseTimeoutMs?: number;
+    /**
+     * Callback invoked when a WebSocket transport error occurs.
+     */
+    onError?: (error: WebsocketTransportError) => void;
+    /**
+     * Callback invoked when a server error message is received.
+     */
+    onMessageError?: (error: WebsocketServerError) => void;
+    /**
+     * Callback invoked when the WebSocket connection closes.
+     */
+    onClose?: (event: CloseEvent) => void;
+}
+
+/**
+ * Error sent by the server via a message with method 'error', 'conflict', or 'exception'.
+ * Contains the parsed message body for application-level error handling.
+ *
+ * @template TBody - The type of the error body payload
+ */
+export declare interface WebsocketServerError<TBody = unknown> {
+    readonly type: 'server';
+    readonly message: IncomingWebsocketMessage<TBody>;
+}
+
+/**
+ * Manages a single WebSocket URI endpoint with subscription lifecycle and message handling.
+ *
+ * Use for streaming data (voyage list, notifications). Provides a TanStack Store for
+ * reactive updates. Multiple components share one instance via a unique key.
+ *
+ * ## Key Features
+ *
+ * - **Reactive Store**: TanStack Store updates when messages are received
+ * - **pendingSubscription**: `true` from subscribe until first message (use for loading states)
+ * - **Auto-subscribe**: Subscribes when the WebSocket connection opens
+ * - **Hook Tracking**: Tracks components; unsubscribes when the last hook unmounts
+ *
+ * ## Edge Cases
+ *
+ * - **Multiple initiators**: Using the same key in multiple components emits a console warning;
+ *   multiple initiators can cause unexpected behavior.
+ * - **Body change in subscribe-on-open**: When `options.body` changes, re-subscribes automatically.
+ * - **enabled=false**: Unsubscribes and disconnects; re-enabling triggers subscribe.
+ * - **reset**: Called by connection on URL change/reconnect; clears store state.
+ *
+ * ## Cleanup
+ *
+ * {@link reset} is called by WebsocketConnection on URL change or reconnection.
+ * {@link unregisterHook} triggers removal after {@link INITIATOR_REMOVAL_DELAY_MS}.
+ *
+ * @template TData - The type of data received from the WebSocket
+ * @template TBody - The type of message body sent
+ *
+ * @example
+ * ```typescript
+ * const api = new WebsocketSubscriptionApi<MyData, MyBody>({
+ *   url: 'wss://example.com',
+ *   uri: '/api/stream',
+ *   key: 'my-stream-key',
+ *   body: { filter: 'active' },
+ *   onMessage: (data) => console.log('Received:', data)
+ * });
+ *
+ * const data = useStore(api.store, (s) => s.message);
+ * const isPending = useStore(api.store, (s) => s.pendingSubscription);
+ * api.sendMessage({ method: 'refresh', body: { force: true } });
+ * ```
+ *
+ * @see {@link useWebsocketSubscription} - React hook
+ * @see {@link WebsocketConnection} - Connection manager
+ */
+export declare class WebsocketSubscriptionApi<TData = unknown, TBody = unknown> implements WebsocketListener {
+    private _options;
+    private _state;
+    private _registeredHooks;
+    private _disconnectTimeout;
+    private _hookRemovalTimeout;
+    private _sendToConnection;
+    private _pendingMessages;
+    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;
+    get url(): string;
+    /** Configuration options for this WebSocket URI. */
+    get options(): WebsocketSubscriptionOptions<TData, TBody>;
+    /**
+     * Current data from the store.
+     *
+     * **Do not use in React components** — it does not trigger re-renders. Use
+     * `useStore(api.store, (s) => s.message)` for reactive updates.
+     */
+    get data(): TData | undefined;
+    /** TanStack store containing subscription state (message, subscribed, connected, pendingSubscription, etc.). */
+    get store(): Store<WebsocketSubscriptionStore<TData>>;
+    /** Whether this WebSocket URI is enabled. */
+    get isEnabled(): boolean;
+    /**
+     * Updates the configuration options for this subscription.
+     *
+     * Handles lifecycle changes:
+     * - **Body change** (subscribe-on-open): Re-subscribes with new body
+     * - **Enabled: false → true**: Subscribes
+     * - **Enabled: true → false**: Unsubscribes
+     *
+     * Uses deep equality to skip no-op updates.
+     *
+     * @param options - New options (merged with existing)
+     */
+    set options(options: WebsocketSubscriptionOptions<TData, TBody>);
+    /**
+     * Sets or clears the callback used to send messages through the parent WebSocket connection.
+     *
+     * When clearing, flushes pending messages and clears removal timeouts to avoid redundant cleanup.
+     *
+     * @param callback - The send function, or null to disconnect
+     */
+    setSendToConnection: (callback: SendToConnectionFn | null) => void;
+    /**
+     * Registers a hook (component) that is using this subscription.
+     *
+     * Clears pending removal/disconnect timeouts and tracks the hook ID.
+     * Emits a console warning if more than one hook is registered (multiple initiators).
+     *
+     * @param id - Unique identifier for the registering hook
+     */
+    registerHook: (id: string) => void;
+    /**
+     * Unregisters a hook from this subscription.
+     *
+     * After {@link INITIATOR_REMOVAL_DELAY_MS}, if no hooks remain, unsubscribes
+     * and invokes the cleanup callback. The delay prevents rapid subscribe/unsubscribe
+     * during React re-renders.
+     *
+     * @param id - The hook ID to unregister
+     * @param onRemove - Callback invoked when the last hook is removed (after delay)
+     */
+    unregisterHook: (id: string, onRemove: () => void) => void;
+    /**
+     * Disconnects this subscription from the parent WebSocket connection.
+     *
+     * Immediately unsubscribes, then after {@link INITIATOR_REMOVAL_DELAY_MS} invokes
+     * the cleanup callback. Called when the hook is disabled (`enabled=false`).
+     *
+     * @param onRemoveFromSocket - Callback invoked after delay to remove from connection
+     */
+    disconnect: (onRemoveFromSocket: () => void) => void;
+    /**
+     * Resets this subscription to its initial state.
+     *
+     * Clears connection/subscription state, resets store data, and cancels pending timeouts.
+     * Only runs when currently connected. Called by WebsocketConnection on URL change
+     * or reconnection.
+     */
+    reset: () => void;
+    /**
+     * Sends a custom message through the WebSocket for this URI.
+     *
+     * Automatically appends the URI and method. Queues if connection not yet set.
+     *
+     * @param message - The message to send (uri and method may be overridden)
+     */
+    sendMessage: (message: SendMessage<string, string, TBody>) => void;
+    /**
+     * Subscribes to this WebSocket URI to start receiving messages.
+     *
+     * Only subscribes when enabled. Sends a 'subscribe' message through the parent connection.
+     *
+     * @param body - Optional body to send with the subscription
+     */
+    subscribe: (body?: TBody) => void;
+    /**
+     * Unsubscribes from this WebSocket URI to stop receiving messages.
+     *
+     * Only unsubscribes when currently subscribed.
+     */
+    unsubscribe: () => void;
+    /**
+     * Called by WebsocketConnection when the WebSocket connection opens.
+     *
+     * Subscribes with the configured body.
+     */
+    onOpen: () => void;
+    /**
+     * Called by WebsocketConnection when a message is received for this URI.
+     *
+     * @param data - The message data
+     */
+    onMessage: (data: TData) => void;
+    /** @inheritdoc */
+    onError: (error: WebsocketTransportError) => void;
+    /**
+     * Called by WebsocketConnection when a server error message is received.
+     *
+     * @param error - Server error with parsed message body
+     */
+    onMessageError: (error: WebsocketServerError<TBody>) => void;
+    /**
+     * Called by WebsocketConnection when the WebSocket connection closes.
+     *
+     * Resets subscription state to ensure a fresh subscription on reconnect.
+     */
+    onClose: (event: CloseEvent) => void;
+    private _clearPendingTimeouts;
+    private _scheduleHookRemoval;
+    private _flushPendingMessages;
+    private _sendOrQueue;
+    private _handleSubscriptionUpdates;
+    private _handleUnsubscribeOnDisable;
+}
+
+export declare type WebsocketSubscriptionApiPublic<TData = unknown, TBody = unknown> = Pick<WebsocketSubscriptionApi<TData, TBody>, 'reset' | 'url' | 'key' | 'isEnabled' | 'store'>;
+
+/**
+ * Configuration options for WebSocket URI APIs.
+ *
+ * Subscriptions automatically subscribe when the WebSocket connection opens.
+ *
+ * @template TData - The type of data received from the WebSocket
+ * @template TBody - The type of message body sent to the WebSocket
+ */
+export declare interface WebsocketSubscriptionOptions<TData = unknown, TBody = unknown> {
+    /** The base URL of the WebSocket connection. */
+    url: string;
+    /** The URI path for this subscription. */
+    uri: string;
+    /**
+     * Unique key for the URI API.
+     *
+     * Used to identify the URI API in the connection.
+     */
+    key: string;
+    /** Whether this URI API is enabled (default: true). When disabled, messages are not sent. */
+    enabled?: boolean;
+    /** Optional body payload to send with subscription or initial message */
+    body?: TBody;
+    /** Optional HTTP method for custom messages sent via sendMessage */
+    method?: string;
+    /**
+     * Callback invoked when subscription is successful.
+     *
+     * @param uri - The URI path that was subscribed to
+     * @param body - The body that was sent with the subscription
+     */
+    onSubscribe?: (props: {
+        uri: string;
+        body?: TBody;
+        uriApi: WebsocketSubscriptionApi<TData, TBody>;
+    }) => void;
+    /**
+     * Callback invoked when a message is received for this URI.
+     *
+     * @param data - The message data received from the WebSocket
+     * @param uriApi - The URI API instance that received the message
+     */
+    onMessage?: (props: {
+        data: TData;
+        uriApi: WebsocketSubscriptionApi<TData, TBody>;
+    }) => void;
+    /**
+     * Callback invoked when a WebSocket error occurs.
+     *
+     * @param error - Discriminated error: use `error.type === 'server'` for server-sent error messages
+     *                (parsed body in `error.message`), or `error.type === 'transport'` for connection failures.
+     */
+    onError?: (error: WebsocketTransportError) => void;
+    /**
+     * A callback function called when an error occurs with a subscription or message.
+     *
+     * @param event - The error event object.
+     */
+    onMessageError?: (error: WebsocketServerError<TBody>) => void;
+    /**
+     * Callback invoked when the WebSocket connection closes.
+     *
+     * @param event - The close event from the WebSocket connection
+     */
+    onClose?: (event: CloseEvent) => void;
+}
+
+export declare interface WebsocketSubscriptionStore<TData = unknown> {
+    message: TData | undefined;
+    subscribed: boolean;
+    /**
+     * Whether a subscription has been sent but no response received yet.
+     *
+     * - `true`: A subscribe message was sent and we are waiting for the first (or next) message.
+     * - `false`: No subscription is active, the connection is closed, or we have already received a response.
+     *
+     * Use this to show loading/placeholder UI while waiting for initial data after subscribing.
+     */
+    pendingSubscription: boolean;
+    subscribedAt: number | undefined;
+    receivedAt: number | undefined;
+    connected: boolean;
+    messageError: WebsocketTransportError | undefined;
+    serverError: WebsocketServerError<unknown> | undefined;
+}
+
+/**
+ * Error from the WebSocket transport layer (connection failure, network issues, etc.).
+ * Contains the raw Event from the WebSocket 'error' handler.
+ */
+export declare interface WebsocketTransportError {
+    readonly type: 'transport';
+    readonly event: Event;
+}
+
+export { }