import { type HookErrorHandler } from '../utils/errors.js';
/** The lifecycle state of the current WebSocket connection. @public */
export type WebSocketStatus = 'closed' | 'connecting' | 'open' | 'closing';
/** Controls optional reconnect attempts after a server-initiated close, including clean closes. @public */
export interface WebSocketReconnectOptions {
    /** Maximum number of attempts after the initial connection (default: 3). */
    readonly maxAttempts?: number;
    /** Alias for `maxAttempts`. */
    readonly retries?: number;
    /** Delay before the first reconnect attempt in milliseconds (default: 1000). */
    readonly initialDelay?: number;
    /** Alias for `initialDelay`. */
    readonly delay?: number;
    /** Exponential delay multiplier (default: 2). */
    readonly factor?: number;
    /** Alias for `factor`. */
    readonly backoffFactor?: number;
    /** Maximum reconnect delay in milliseconds (default: 30000). */
    readonly maxDelay?: number;
}
/** Options accepted by {@link useWebSocket}. @public */
export interface UseWebSocketOptions {
    /** Protocol name or names passed to the native WebSocket constructor. */
    readonly protocols?: string | readonly string[];
    /** Disables connection management while false. Defaults to true. */
    readonly enabled?: boolean;
    /** Enables reconnecting after server-initiated closes, including clean closes, or supplies its policy. */
    readonly reconnect?: boolean | WebSocketReconnectOptions;
    /** Called when the socket opens. */
    readonly onOpen?: (event: Event) => void;
    /** Called for each message. The native event is passed unchanged. */
    readonly onMessage?: (event: MessageEvent) => void;
    /** Called when the socket closes. */
    readonly onClose?: (event: CloseEvent) => void;
    /** Observes native and callback failures. */
    readonly onError?: HookErrorHandler;
}
/** State and stable actions returned by {@link useWebSocket}. @public */
export interface UseWebSocketResult {
    /** Current socket lifecycle state. */
    readonly status: WebSocketStatus;
    /** Most recent raw `MessageEvent.data` value. */
    readonly data: MessageEvent['data'] | undefined;
    /** Most recent native, callback, or connection-management error. */
    readonly error: unknown;
    /** Sends data through the currently open socket; throws InvalidStateError otherwise. */
    readonly send: (data: Parameters<WebSocket['send']>[0]) => void;
    /** Closes the current socket and suppresses automatic reconnects. */
    readonly close: (code?: number, reason?: string) => void;
    /** Closes the current socket and starts a fresh connection immediately. */
    readonly reconnect: () => void;
}
/**
 * Manages a browser WebSocket connection with stable actions, SSR-safe
 * initialization, and optional bounded exponential reconnects after
 * server-initiated closes.
 * @public
 */
export declare function useWebSocket(url: string | URL | null, options?: UseWebSocketOptions): UseWebSocketResult;