tempest-react-sdk 0.33.2 → 0.35.0

package/dist/ws/create-web-socket.js

@@ -7,60 +7,77 @@ function e(e) {
 	}
 }
 function t(t, n = {}) {
-	let { protocols: r, maxRetries: i = 10, initialBackoff: a = 1e3, maxBackoff: o = 3e4, pingInterval: s = 0, pingPayload: c = JSON.stringify({ type: "ping" }), parser: l = e, onOpen: u, onMessage: d, onClose: f, onError: p, onStatusChange: m } = n, h = null, g = null, _ = null, v = 0, y = "idle", b = !1;
-	function x(e) {
-		y !== e && (y = e, m?.(e));
+	let { protocols: r, maxRetries: i = 10, initialBackoff: a = 1e3, maxBackoff: o = 3e4, pingInterval: s = 0, pingPayload: c = JSON.stringify({ type: "ping" }), respondToPing: l = !0, pongPayload: u = JSON.stringify({ type: "pong" }), queueWhileClosed: d = !1, maxQueuedMessages: f = 100, parser: p = e, onOpen: m, onMessage: h, onClose: g, onError: _, onStatusChange: v } = n, y = null, b = null, x = null, S = 0, C = "idle", w = !1, T = [];
+	function E(e) {
+		return typeof e == "object" && !!e && e.type === "ping";
+	}
+	function D(e) {
+		for (; T.length > 0 && e.readyState === WebSocket.OPEN;) e.send(T.shift());
 	}
-	function S() {
-		_ &&= (clearInterval(_), null);
+	function O(e) {
+		C !== e && (C = e, v?.(e));
 	}
-	function C() {
-		!s || s <= 0 || (S(), _ = setInterval(() => {
-			h?.readyState === WebSocket.OPEN && h.send(c);
+	function k() {
+		x &&= (clearInterval(x), null);
+	}
+	function A() {
+		!s || s <= 0 || (k(), x = setInterval(() => {
+			y?.readyState === WebSocket.OPEN && y.send(c);
 		}, s));
 	}
-	function w() {
-		if (b) return;
-		if (v >= i) {
-			x("error");
+	function j() {
+		if (w) return;
+		if (S >= i) {
+			O("error");
 			return;
 		}
-		let e = Math.min(a * 2 ** v, o);
-		v += 1, g = setTimeout(T, e);
+		let e = Math.min(a * 2 ** S, o);
+		S += 1, b = setTimeout(M, e);
 	}
-	function T() {
-		if (b) return;
-		h && (h.onopen = null, h.onmessage = null, h.onclose = null, h.onerror = null, h.close()), x("connecting");
+	function M() {
+		if (w) return;
+		if (y) {
+			let e = y;
+			e.onmessage = null, e.onclose = null, e.onerror = null, e.readyState !== WebSocket.CONNECTING && (e.onopen = null), F(e);
+		}
+		O("connecting");
 		let e = new WebSocket(t, r);
-		h = e, e.onopen = (e) => {
-			v = 0, x("open"), C(), u?.(e);
-		}, e.onmessage = (e) => {
-			let t = typeof e.data == "string" ? e.data : "";
-			d?.({
-				data: l(t),
-				raw: e
+		y = e, e.onopen = (t) => {
+			S = 0, O("open"), A(), D(e), m?.(t);
+		}, e.onmessage = (t) => {
+			let n = typeof t.data == "string" ? t.data : "", r = p(n);
+			l && E(r) && e.readyState === WebSocket.OPEN && e.send(u), h?.({
+				data: r,
+				raw: t
 			});
 		}, e.onerror = (e) => {
-			p?.(e);
+			_?.(e);
 		}, e.onclose = (e) => {
-			S(), f?.(e), h = null, x("closed"), !b && !e.wasClean && w();
+			k(), g?.(e), y = null, O("closed"), !w && !e.wasClean && j();
 		};
 	}
-	function E(e) {
-		return h?.readyState === WebSocket.OPEN ? (h.send(e), !0) : !1;
+	function N(e) {
+		return y?.readyState === WebSocket.OPEN ? (y.send(e), !0) : !d || w ? !1 : (T.length >= f && T.shift(), T.push(e), !0);
+	}
+	function P(e, t) {
+		w = !0, b &&= (clearTimeout(b), null), k(), S = 0, T.length = 0, y &&= (O("closing"), F(y, e, t), null), O("closed");
 	}
-	function D(e, t) {
-		b = !0, g &&= (clearTimeout(g), null), S(), v = 0, h &&= (x("closing"), h.close(e, t), null), x("closed");
+	function F(e, t, n) {
+		if (e.readyState === WebSocket.CONNECTING) {
+			e.onopen = () => e.close(t, n), e.onmessage = null, e.onerror = null, e.onclose = null;
+			return;
+		}
+		e.close(t, n);
 	}
-	function O() {
-		g &&= (clearTimeout(g), null), v = 0, b = !1, T();
+	function I() {
+		b &&= (clearTimeout(b), null), S = 0, w = !1, M();
 	}
-	return T(), {
-		send: E,
-		close: D,
-		reconnect: O,
+	return M(), {
+		send: N,
+		close: P,
+		reconnect: I,
 		get status() {
-			return y;
+			return C;
 		}
 	};
 }

package/dist/ws/create-web-socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-web-socket.js","names":[],"sources":["../../src/ws/create-web-socket.ts"],"sourcesContent":["export type WebSocketStatus = \"idle\" | \"connecting\" | \"open\" | \"closing\" | \"closed\" | \"error\";\n\nexport interface WebSocketMessage<T> {\n    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** The original `MessageEvent`. */\n    raw: MessageEvent;\n}\n\nexport interface CreateWebSocketOptions<T> {\n    /** Subprotocol(s) forwarded to the `WebSocket` constructor. */\n    protocols?: string | string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable. */\n    maxRetries?: number;\n    /** Initial backoff (ms). Doubles each attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff (ms). Default: 30000. */\n    maxBackoff?: number;\n    /**\n     * Ping interval (ms). When set, the client sends `pingPayload` periodically\n     * to keep the socket alive. Default: 0 (disabled).\n     */\n    pingInterval?: number;\n    /** Payload sent on each ping. Default: `JSON.stringify({ type: \"ping\" })`. */\n    pingPayload?: string | Blob | BufferSource;\n    /** Parse incoming frames. Default: JSON with raw-string fallback. */\n    parser?: (raw: string) => T;\n    onOpen?: (event: Event) => void;\n    onMessage?: (message: WebSocketMessage<T>) => void;\n    onClose?: (event: CloseEvent) => void;\n    onError?: (event: Event) => void;\n    onStatusChange?: (status: WebSocketStatus) => void;\n}\n\nexport interface WebSocketController {\n    /** Send a payload over the current connection. No-op when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Close the connection and stop reconnecting. */\n    close: (code?: number, reason?: string) => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: WebSocketStatus;\n}\n\nfunction defaultParser<T>(raw: string): T {\n    try {\n        return JSON.parse(raw) as T;\n    } catch {\n        return raw as unknown as T;\n    }\n}\n\n/**\n * Open a WebSocket with automatic exponential-backoff reconnect, optional\n * heartbeat pings, and typed JSON parsing.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Controller exposing `send`, `close`, `reconnect`, and `status`.\n */\nexport function createWebSocket<T = unknown>(\n    url: string,\n    options: CreateWebSocketOptions<T> = {},\n): WebSocketController {\n    const {\n        protocols,\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        pingInterval = 0,\n        pingPayload = JSON.stringify({ type: \"ping\" }),\n        parser = defaultParser<T>,\n        onOpen,\n        onMessage,\n        onClose,\n        onError,\n        onStatusChange,\n    } = options;\n\n    let socket: WebSocket | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let pingTimer: ReturnType<typeof setInterval> | null = null;\n    let retries = 0;\n    let status: WebSocketStatus = \"idle\";\n    let closed = false;\n\n    function setStatus(next: WebSocketStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function clearPing(): void {\n        if (pingTimer) {\n            clearInterval(pingTimer);\n            pingTimer = null;\n        }\n    }\n\n    function startPing(): void {\n        if (!pingInterval || pingInterval <= 0) return;\n        clearPing();\n        pingTimer = setInterval(() => {\n            if (socket?.readyState === WebSocket.OPEN) {\n                socket.send(pingPayload);\n            }\n        }, pingInterval);\n    }\n\n    function scheduleReconnect(): void {\n        if (closed) return;\n        if (retries >= maxRetries) {\n            setStatus(\"error\");\n            return;\n        }\n        const delay = Math.min(initialBackoff * 2 ** retries, maxBackoff);\n        retries += 1;\n        retryTimer = setTimeout(connect, delay);\n    }\n\n    function connect(): void {\n        if (closed) return;\n        if (socket) {\n            socket.onopen = null;\n            socket.onmessage = null;\n            socket.onclose = null;\n            socket.onerror = null;\n            socket.close();\n        }\n        setStatus(\"connecting\");\n\n        const ws = new WebSocket(url, protocols);\n        socket = ws;\n\n        ws.onopen = (event) => {\n            retries = 0;\n            setStatus(\"open\");\n            startPing();\n            onOpen?.(event);\n        };\n\n        ws.onmessage = (event) => {\n            const raw = typeof event.data === \"string\" ? event.data : \"\";\n            onMessage?.({\n                data: parser(raw),\n                raw: event,\n            });\n        };\n\n        ws.onerror = (event) => {\n            onError?.(event);\n        };\n\n        ws.onclose = (event) => {\n            clearPing();\n            onClose?.(event);\n            socket = null;\n            setStatus(\"closed\");\n            if (!closed && !event.wasClean) {\n                scheduleReconnect();\n            }\n        };\n    }\n\n    function send(payload: string | Blob | BufferSource): boolean {\n        if (socket?.readyState !== WebSocket.OPEN) return false;\n        socket.send(payload);\n        return true;\n    }\n\n    function close(code?: number, reason?: string): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        clearPing();\n        retries = 0;\n        if (socket) {\n            setStatus(\"closing\");\n            socket.close(code, reason);\n            socket = null;\n        }\n        setStatus(\"closed\");\n    }\n\n    function reconnect(): void {\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        closed = false;\n        connect();\n    }\n\n    connect();\n\n    return {\n        send,\n        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":";AA6CA,SAAS,EAAiB,GAAgB;CACtC,IAAI;EACA,OAAO,KAAK,MAAM,CAAG;CACzB,QAAQ;EACJ,OAAO;CACX;AACJ;AAUA,SAAgB,EACZ,GACA,IAAqC,CAAC,GACnB;CACnB,IAAM,EACF,cACA,gBAAa,IACb,oBAAiB,KACjB,gBAAa,KACb,kBAAe,GACf,iBAAc,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC,GAC7C,YAAS,GACT,WACA,cACA,YACA,YACA,sBACA,GAEA,IAA2B,MAC3B,IAAmD,MACnD,IAAmD,MACnD,IAAU,GACV,IAA0B,QAC1B,IAAS;CAEb,SAAS,EAAU,GAA6B;EACxC,MAAW,MACf,IAAS,GACT,IAAiB,CAAI;CACzB;CAEA,SAAS,IAAkB;EACvB,AAEI,OADA,cAAc,CAAS,GACX;CAEpB;CAEA,SAAS,IAAkB;EACnB,CAAC,KAAgB,KAAgB,MACrC,EAAU,GACV,IAAY,kBAAkB;GAC1B,AAAI,GAAQ,eAAe,UAAU,QACjC,EAAO,KAAK,CAAW;EAE/B,GAAG,CAAY;CACnB;CAEA,SAAS,IAA0B;EAC/B,IAAI,GAAQ;EACZ,IAAI,KAAW,GAAY;GACvB,EAAU,OAAO;GACjB;EACJ;EACA,IAAM,IAAQ,KAAK,IAAI,IAAiB,KAAK,GAAS,CAAU;EAEhE,AADA,KAAW,GACX,IAAa,WAAW,GAAS,CAAK;CAC1C;CAEA,SAAS,IAAgB;EACrB,IAAI,GAAQ;EAQZ,AAPI,MACA,EAAO,SAAS,MAChB,EAAO,YAAY,MACnB,EAAO,UAAU,MACjB,EAAO,UAAU,MACjB,EAAO,MAAM,IAEjB,EAAU,YAAY;EAEtB,IAAM,IAAK,IAAI,UAAU,GAAK,CAAS;EAsBvC,AArBA,IAAS,GAET,EAAG,UAAU,MAAU;GAInB,AAHA,IAAU,GACV,EAAU,MAAM,GAChB,EAAU,GACV,IAAS,CAAK;EAClB,GAEA,EAAG,aAAa,MAAU;GACtB,IAAM,IAAM,OAAO,EAAM,QAAS,WAAW,EAAM,OAAO;GAC1D,IAAY;IACR,MAAM,EAAO,CAAG;IAChB,KAAK;GACT,CAAC;EACL,GAEA,EAAG,WAAW,MAAU;GACpB,IAAU,CAAK;EACnB,GAEA,EAAG,WAAW,MAAU;GAKpB,AAJA,EAAU,GACV,IAAU,CAAK,GACf,IAAS,MACT,EAAU,QAAQ,GACd,CAAC,KAAU,CAAC,EAAM,YAClB,EAAkB;EAE1B;CACJ;CAEA,SAAS,EAAK,GAAgD;EAG1D,OAFI,GAAQ,eAAe,UAAU,QACrC,EAAO,KAAK,CAAO,GACZ,MAF2C;CAGtD;CAEA,SAAS,EAAM,GAAe,GAAuB;EAajD,AAZA,IAAS,IACT,AAEI,OADA,aAAa,CAAU,GACV,OAEjB,EAAU,GACV,IAAU,GACV,AAGI,OAFA,EAAU,SAAS,GACnB,EAAO,MAAM,GAAM,CAAM,GAChB,OAEb,EAAU,QAAQ;CACtB;CAEA,SAAS,IAAkB;EAOvB,AANA,AAEI,OADA,aAAa,CAAU,GACV,OAEjB,IAAU,GACV,IAAS,IACT,EAAQ;CACZ;CAIA,OAFA,EAAQ,GAED;EACH;EACA;EACA;EACA,IAAI,SAAS;GACT,OAAO;EACX;CACJ;AACJ"}
+{"version":3,"file":"create-web-socket.js","names":[],"sources":["../../src/ws/create-web-socket.ts"],"sourcesContent":["export type WebSocketStatus = \"idle\" | \"connecting\" | \"open\" | \"closing\" | \"closed\" | \"error\";\n\nexport interface WebSocketMessage<T> {\n    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** The original `MessageEvent`. */\n    raw: MessageEvent;\n}\n\nexport interface CreateWebSocketOptions<T> {\n    /** Subprotocol(s) forwarded to the `WebSocket` constructor. */\n    protocols?: string | string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable. */\n    maxRetries?: number;\n    /** Initial backoff (ms). Doubles each attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff (ms). Default: 30000. */\n    maxBackoff?: number;\n    /**\n     * Ping interval (ms). When set, the client sends `pingPayload` periodically\n     * to keep the socket alive. Default: 0 (disabled).\n     *\n     * Leave it off against a `tempest-fastapi-sdk` server: that server pings on\n     * its own and answers a client-sent `{\"type\":\"ping\"}` with nothing, while a\n     * strict handler rejects the unknown frame. What it needs from the client\n     * is the `pong` reply, which `respondToPing` sends for you.\n     */\n    pingInterval?: number;\n    /** Payload sent on each ping. Default: `JSON.stringify({ type: \"ping\" })`. */\n    pingPayload?: string | Blob | BufferSource;\n    /**\n     * Reply to a server `{\"type\":\"ping\"}` with `pongPayload`. Default: true.\n     *\n     * `tempest-fastapi-sdk` closes a socket with code `4408` when no `pong`\n     * arrives within `WS_HEARTBEAT_TIMEOUT_SECONDS`, so a client that stays\n     * silent is dropped once per timeout. The ping is still forwarded to\n     * `onMessage` — the reply is sent before your handler runs.\n     */\n    respondToPing?: boolean;\n    /** Payload sent in reply to a server ping. Default: `JSON.stringify({ type: \"pong\" })`. */\n    pongPayload?: string | Blob | BufferSource;\n    /**\n     * Buffer payloads sent while the socket is not open and flush them on the\n     * next `open`. Default: false — `send()` returns false and drops.\n     *\n     * Without it, an action fired during reconnect backoff vanishes and the UI\n     * cannot tell \"never sent\" from \"sent and ignored\".\n     */\n    queueWhileClosed?: boolean;\n    /** Cap on buffered payloads when `queueWhileClosed` is on. Default: 100. */\n    maxQueuedMessages?: number;\n    /** Parse incoming frames. Default: JSON with raw-string fallback. */\n    parser?: (raw: string) => T;\n    onOpen?: (event: Event) => void;\n    onMessage?: (message: WebSocketMessage<T>) => void;\n    onClose?: (event: CloseEvent) => void;\n    onError?: (event: Event) => void;\n    onStatusChange?: (status: WebSocketStatus) => void;\n}\n\nexport interface WebSocketController {\n    /** Send a payload over the current connection. No-op when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Close the connection and stop reconnecting. */\n    close: (code?: number, reason?: string) => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: WebSocketStatus;\n}\n\nfunction defaultParser<T>(raw: string): T {\n    try {\n        return JSON.parse(raw) as T;\n    } catch {\n        return raw as unknown as T;\n    }\n}\n\n/**\n * Open a WebSocket with automatic exponential-backoff reconnect, optional\n * heartbeat pings, and typed JSON parsing.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Controller exposing `send`, `close`, `reconnect`, and `status`.\n */\nexport function createWebSocket<T = unknown>(\n    url: string,\n    options: CreateWebSocketOptions<T> = {},\n): WebSocketController {\n    const {\n        protocols,\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        pingInterval = 0,\n        pingPayload = JSON.stringify({ type: \"ping\" }),\n        respondToPing = true,\n        pongPayload = JSON.stringify({ type: \"pong\" }),\n        queueWhileClosed = false,\n        maxQueuedMessages = 100,\n        parser = defaultParser<T>,\n        onOpen,\n        onMessage,\n        onClose,\n        onError,\n        onStatusChange,\n    } = options;\n\n    let socket: WebSocket | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let pingTimer: ReturnType<typeof setInterval> | null = null;\n    let retries = 0;\n    let status: WebSocketStatus = \"idle\";\n    let closed = false;\n    const outbox: Array<string | Blob | BufferSource> = [];\n\n    /** True for a decoded frame that is the server's heartbeat ping. */\n    function isServerPing(data: unknown): boolean {\n        return (\n            typeof data === \"object\" &&\n            data !== null &&\n            (data as { type?: unknown }).type === \"ping\"\n        );\n    }\n\n    /** Send everything buffered while the socket was down, oldest first. */\n    function flushOutbox(ws: WebSocket): void {\n        while (outbox.length > 0 && ws.readyState === WebSocket.OPEN) {\n            ws.send(outbox.shift()!);\n        }\n    }\n\n    function setStatus(next: WebSocketStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function clearPing(): void {\n        if (pingTimer) {\n            clearInterval(pingTimer);\n            pingTimer = null;\n        }\n    }\n\n    function startPing(): void {\n        if (!pingInterval || pingInterval <= 0) return;\n        clearPing();\n        pingTimer = setInterval(() => {\n            if (socket?.readyState === WebSocket.OPEN) {\n                socket.send(pingPayload);\n            }\n        }, pingInterval);\n    }\n\n    function scheduleReconnect(): void {\n        if (closed) return;\n        if (retries >= maxRetries) {\n            setStatus(\"error\");\n            return;\n        }\n        const delay = Math.min(initialBackoff * 2 ** retries, maxBackoff);\n        retries += 1;\n        retryTimer = setTimeout(connect, delay);\n    }\n\n    function connect(): void {\n        if (closed) return;\n        if (socket) {\n            const previous = socket;\n            previous.onmessage = null;\n            previous.onclose = null;\n            previous.onerror = null;\n            if (previous.readyState !== WebSocket.CONNECTING) previous.onopen = null;\n            closeSocket(previous);\n        }\n        setStatus(\"connecting\");\n\n        const ws = new WebSocket(url, protocols);\n        socket = ws;\n\n        ws.onopen = (event) => {\n            retries = 0;\n            setStatus(\"open\");\n            startPing();\n            flushOutbox(ws);\n            onOpen?.(event);\n        };\n\n        ws.onmessage = (event) => {\n            const raw = typeof event.data === \"string\" ? event.data : \"\";\n            const data = parser(raw);\n            if (respondToPing && isServerPing(data) && ws.readyState === WebSocket.OPEN) {\n                ws.send(pongPayload);\n            }\n            onMessage?.({ data, raw: event });\n        };\n\n        ws.onerror = (event) => {\n            onError?.(event);\n        };\n\n        ws.onclose = (event) => {\n            clearPing();\n            onClose?.(event);\n            socket = null;\n            setStatus(\"closed\");\n            if (!closed && !event.wasClean) {\n                scheduleReconnect();\n            }\n        };\n    }\n\n    function send(payload: string | Blob | BufferSource): boolean {\n        if (socket?.readyState === WebSocket.OPEN) {\n            socket.send(payload);\n            return true;\n        }\n        if (!queueWhileClosed || closed) return false;\n        if (outbox.length >= maxQueuedMessages) outbox.shift();\n        outbox.push(payload);\n        return true;\n    }\n\n    function close(code?: number, reason?: string): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        clearPing();\n        retries = 0;\n        outbox.length = 0;\n        if (socket) {\n            setStatus(\"closing\");\n            closeSocket(socket, code, reason);\n            socket = null;\n        }\n        setStatus(\"closed\");\n    }\n\n    /**\n     * Close a socket without the \"closed before the connection is established\"\n     * console warning.\n     *\n     * A socket still in `CONNECTING` cannot be closed cleanly — the browser\n     * logs that warning on every attempt. React's StrictMode mounts, unmounts\n     * and remounts each component in development, so the first socket is\n     * always torn down mid-handshake and the message shows up in every dev\n     * session of every app using the hook. Deferring the close to `onopen`\n     * costs one round trip and keeps the console usable.\n     */\n    function closeSocket(ws: WebSocket, code?: number, reason?: string): void {\n        if (ws.readyState === WebSocket.CONNECTING) {\n            ws.onopen = () => ws.close(code, reason);\n            ws.onmessage = null;\n            ws.onerror = null;\n            ws.onclose = null;\n            return;\n        }\n        ws.close(code, reason);\n    }\n\n    function reconnect(): void {\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        closed = false;\n        connect();\n    }\n\n    connect();\n\n    return {\n        send,\n        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":"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"}

package/dist/ws/use-web-socket.cjs

@@ -1,2 +1,2 @@
-const e=require("./create-web-socket.cjs");let t=require("react");function n(n,r={}){let{enabled:i=!0,onMessage:a,...o}=r,[s,c]=(0,t.useState)(`idle`),[l,u]=(0,t.useState)(null),d=(0,t.useRef)(null),f=(0,t.useRef)(a);return(0,t.useEffect)(()=>{f.current=a},[a]),(0,t.useEffect)(()=>{if(!i||!n){c(`idle`);return}let t=e.createWebSocket(n,{...o,onStatusChange:c,onMessage:e=>{u(e),f.current?.(e)}});return d.current=t,()=>{t.close(),d.current=null}},[n,i]),{status:s,lastMessage:l,send:(0,t.useCallback)(e=>d.current?.send(e)??!1,[]),reconnect:(0,t.useCallback)(()=>{d.current?.reconnect()},[])}}exports.useWebSocket=n;
+const e=require("./create-web-socket.cjs");let t=require("react");function n(e){try{return JSON.parse(e)}catch{return e}}function r(r,i={}){let{enabled:a=!0,protocols:o,maxRetries:s,initialBackoff:c,maxBackoff:l,pingInterval:u,respondToPing:d,queueWhileClosed:f,maxQueuedMessages:p}=i,[m,h]=(0,t.useState)(`idle`),[g,_]=(0,t.useState)(null),v=(0,t.useRef)(null),y=(0,t.useRef)(i);return(0,t.useEffect)(()=>{y.current=i}),(0,t.useEffect)(()=>{if(!a||!r){h(`idle`);return}let t=e.createWebSocket(r,{protocols:y.current.protocols,maxRetries:s,initialBackoff:c,maxBackoff:l,pingInterval:u,pingPayload:y.current.pingPayload,respondToPing:d,pongPayload:y.current.pongPayload,queueWhileClosed:f,maxQueuedMessages:p,parser:e=>(y.current.parser??n)(e),onStatusChange:h,onOpen:e=>y.current.onOpen?.(e),onClose:e=>y.current.onClose?.(e),onError:e=>y.current.onError?.(e),onMessage:e=>{_(e),y.current.onMessage?.(e)}});return v.current=t,()=>{t.close(),v.current=null}},[r,a,Array.isArray(o)?o.join(`,`):o??``,s,c,l,u,d,f,p]),{status:m,lastMessage:g,send:(0,t.useCallback)(e=>v.current?.send(e)??!1,[]),reconnect:(0,t.useCallback)(()=>{v.current?.reconnect()},[])}}exports.useWebSocket=r;
 //# sourceMappingURL=use-web-socket.cjs.map

package/dist/ws/use-web-socket.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-web-socket.cjs","names":[],"sources":["../../src/ws/use-web-socket.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n    createWebSocket,\n    type CreateWebSocketOptions,\n    type WebSocketController,\n    type WebSocketMessage,\n    type WebSocketStatus,\n} from \"./create-web-socket\";\n\nexport interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOptions<T>, \"onStatusChange\"> {\n    /** When false, the socket is not opened. Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseWebSocketResult<T> {\n    status: WebSocketStatus;\n    /** Last decoded frame received. */\n    lastMessage: WebSocketMessage<T> | null;\n    /** Send a payload through the active connection. Returns false when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Force a reconnect, resetting the retry counter. */\n    reconnect: () => void;\n}\n\n/**\n * React hook around {@link createWebSocket}. Manages the connection lifecycle\n * for the host component and tears it down on unmount.\n */\nexport function useWebSocket<T = unknown>(\n    url: string,\n    options: UseWebSocketOptions<T> = {},\n): UseWebSocketResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<WebSocketStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<WebSocketMessage<T> | null>(null);\n    const controllerRef = useRef<WebSocketController | null>(null);\n\n    const onMessageRef = useRef(onMessage);\n    useEffect(() => {\n        onMessageRef.current = onMessage;\n    }, [onMessage]);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createWebSocket<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        controllerRef.current = controller;\n\n        return () => {\n            controller.close();\n            controllerRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    const send = useCallback((payload: string | Blob | BufferSource): boolean => {\n        return controllerRef.current?.send(payload) ?? false;\n    }, []);\n\n    const reconnect = useCallback((): void => {\n        controllerRef.current?.reconnect();\n    }, []);\n\n    return { status, lastMessage, send, reconnect };\n}\n"],"mappings":"kEA4BA,SAAgB,EACZ,EACA,EAAkC,CAAC,EACd,CACrB,GAAM,CAAE,UAAU,GAAM,YAAW,GAAG,GAAS,EACzC,CAAC,EAAQ,IAAA,EAAA,EAAA,SAAA,CAAuC,MAAM,EACtD,CAAC,EAAa,IAAA,EAAA,EAAA,SAAA,CAAuD,IAAI,EACzE,GAAA,EAAA,EAAA,OAAA,CAAmD,IAAI,EAEvD,GAAA,EAAA,EAAA,OAAA,CAAsB,CAAS,EAoCrC,OAnCA,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAa,QAAU,CAC3B,EAAG,CAAC,CAAS,CAAC,GAEd,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,CAAC,EAAK,CAClB,EAAU,MAAM,EAChB,MACJ,CAEA,IAAM,EAAa,EAAA,gBAAmB,EAAK,CACvC,GAAG,EACH,eAAgB,EAChB,UAAY,GAAY,CACpB,EAAe,CAAO,EACtB,EAAa,UAAU,CAAO,CAClC,CACJ,CAAC,EAGD,MAFA,GAAc,QAAU,MAEX,CACT,EAAW,MAAM,EACjB,EAAc,QAAU,IAC5B,CAEJ,EAAG,CAAC,EAAK,CAAO,CAAC,EAUV,CAAE,SAAQ,cAAa,MAAA,EAAA,EAAA,YAAA,CARJ,GACf,EAAc,SAAS,KAAK,CAAO,GAAK,GAChD,CAAC,CAM0B,EAAM,WAAA,EAAA,EAAA,YAAA,KAJM,CACtC,EAAc,SAAS,UAAU,CACrC,EAAG,CAAC,CAEgC,CAAU,CAClD"}
+{"version":3,"file":"use-web-socket.cjs","names":[],"sources":["../../src/ws/use-web-socket.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n    createWebSocket,\n    type CreateWebSocketOptions,\n    type WebSocketController,\n    type WebSocketMessage,\n    type WebSocketStatus,\n} from \"./create-web-socket\";\n\nexport interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOptions<T>, \"onStatusChange\"> {\n    /** When false, the socket is not opened. Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseWebSocketResult<T> {\n    status: WebSocketStatus;\n    /**\n     * Last decoded frame received.\n     *\n     * A snapshot, not a stream: two frames arriving in the same tick collapse\n     * into a single render and only the later one is ever visible. One server\n     * action often emits several frames in a row, so anything that must see\n     * every message has to use `onMessage`, which fires once per frame. Read\n     * `lastMessage` for \"what is the current state\" rendering only.\n     */\n    lastMessage: WebSocketMessage<T> | null;\n    /** Send a payload through the active connection. Returns false when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Force a reconnect, resetting the retry counter. */\n    reconnect: () => void;\n}\n\n/** Mirror of `createWebSocket`'s default parser: JSON, raw string on failure. */\nfunction defaultParse<T>(raw: string): T {\n    try {\n        return JSON.parse(raw) as T;\n    } catch {\n        return raw as unknown as T;\n    }\n}\n\n/**\n * React hook around {@link createWebSocket}. Manages the connection lifecycle\n * for the host component and tears it down on unmount.\n *\n * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /\n * `onError` always run the latest closure — an inline arrow function is fine\n * and never reopens the socket. Connection-shaping options (`protocols`,\n * `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`,\n * `queueWhileClosed`) are baked into the connection, so changing one reopens\n * it with the new value rather than being silently ignored.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Status, last frame, and the `send` / `reconnect` controls.\n */\nexport function useWebSocket<T = unknown>(\n    url: string,\n    options: UseWebSocketOptions<T> = {},\n): UseWebSocketResult<T> {\n    const {\n        enabled = true,\n        protocols,\n        maxRetries,\n        initialBackoff,\n        maxBackoff,\n        pingInterval,\n        respondToPing,\n        queueWhileClosed,\n        maxQueuedMessages,\n    } = options;\n    const [status, setStatus] = useState<WebSocketStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<WebSocketMessage<T> | null>(null);\n    const controllerRef = useRef<WebSocketController | null>(null);\n\n    const optionsRef = useRef(options);\n    useEffect(() => {\n        optionsRef.current = options;\n    });\n\n    const protocolsKey = Array.isArray(protocols) ? protocols.join(\",\") : (protocols ?? \"\");\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createWebSocket<T>(url, {\n            protocols: optionsRef.current.protocols,\n            maxRetries,\n            initialBackoff,\n            maxBackoff,\n            pingInterval,\n            pingPayload: optionsRef.current.pingPayload,\n            respondToPing,\n            pongPayload: optionsRef.current.pongPayload,\n            queueWhileClosed,\n            maxQueuedMessages,\n            parser: (raw) => (optionsRef.current.parser ?? defaultParse<T>)(raw),\n            onStatusChange: setStatus,\n            onOpen: (event) => optionsRef.current.onOpen?.(event),\n            onClose: (event) => optionsRef.current.onClose?.(event),\n            onError: (event) => optionsRef.current.onError?.(event),\n            onMessage: (message) => {\n                setLastMessage(message);\n                optionsRef.current.onMessage?.(message);\n            },\n        });\n        controllerRef.current = controller;\n\n        return () => {\n            controller.close();\n            controllerRef.current = null;\n        };\n    }, [\n        url,\n        enabled,\n        protocolsKey,\n        maxRetries,\n        initialBackoff,\n        maxBackoff,\n        pingInterval,\n        respondToPing,\n        queueWhileClosed,\n        maxQueuedMessages,\n    ]);\n\n    const send = useCallback((payload: string | Blob | BufferSource): boolean => {\n        return controllerRef.current?.send(payload) ?? false;\n    }, []);\n\n    const reconnect = useCallback((): void => {\n        controllerRef.current?.reconnect();\n    }, []);\n\n    return { status, lastMessage, send, reconnect };\n}\n"],"mappings":"kEAiCA,SAAS,EAAgB,EAAgB,CACrC,GAAI,CACA,OAAO,KAAK,MAAM,CAAG,CACzB,MAAQ,CACJ,OAAO,CACX,CACJ,CAiBA,SAAgB,EACZ,EACA,EAAkC,CAAC,EACd,CACrB,GAAM,CACF,UAAU,GACV,YACA,aACA,iBACA,aACA,eACA,gBACA,mBACA,qBACA,EACE,CAAC,EAAQ,IAAA,EAAA,EAAA,SAAA,CAAuC,MAAM,EACtD,CAAC,EAAa,IAAA,EAAA,EAAA,SAAA,CAAuD,IAAI,EACzE,GAAA,EAAA,EAAA,OAAA,CAAmD,IAAI,EAEvD,GAAA,EAAA,EAAA,OAAA,CAAoB,CAAO,EA6DjC,OA5DA,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAW,QAAU,CACzB,CAAC,GAID,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,CAAC,EAAK,CAClB,EAAU,MAAM,EAChB,MACJ,CAEA,IAAM,EAAa,EAAA,gBAAmB,EAAK,CACvC,UAAW,EAAW,QAAQ,UAC9B,aACA,iBACA,aACA,eACA,YAAa,EAAW,QAAQ,YAChC,gBACA,YAAa,EAAW,QAAQ,YAChC,mBACA,oBACA,OAAS,IAAS,EAAW,QAAQ,QAAU,EAAA,CAAiB,CAAG,EACnE,eAAgB,EAChB,OAAS,GAAU,EAAW,QAAQ,SAAS,CAAK,EACpD,QAAU,GAAU,EAAW,QAAQ,UAAU,CAAK,EACtD,QAAU,GAAU,EAAW,QAAQ,UAAU,CAAK,EACtD,UAAY,GAAY,CACpB,EAAe,CAAO,EACtB,EAAW,QAAQ,YAAY,CAAO,CAC1C,CACJ,CAAC,EAGD,MAFA,GAAc,QAAU,MAEX,CACT,EAAW,MAAM,EACjB,EAAc,QAAU,IAC5B,CACJ,EAAG,CACC,EACA,EArCiB,MAAM,QAAQ,CAAS,EAAI,EAAU,KAAK,GAAG,EAAK,GAAa,GAuChF,EACA,EACA,EACA,EACA,EACA,EACA,CACJ,CAAC,EAUM,CAAE,SAAQ,cAAa,MAAA,EAAA,EAAA,YAAA,CARJ,GACf,EAAc,SAAS,KAAK,CAAO,GAAK,GAChD,CAAC,CAM0B,EAAM,WAAA,EAAA,EAAA,YAAA,KAJM,CACtC,EAAc,SAAS,UAAU,CACrC,EAAG,CAAC,CAEgC,CAAU,CAClD"}

package/dist/ws/use-web-socket.js

@@ -1,35 +1,66 @@
 import { createWebSocket as e } from "./create-web-socket.js";
 import { useCallback as t, useEffect as n, useRef as r, useState as i } from "react";
 //#region src/ws/use-web-socket.ts
-function a(a, o = {}) {
-	let { enabled: s = !0, onMessage: c, ...l } = o, [u, d] = i("idle"), [f, p] = i(null), m = r(null), h = r(c);
+function a(e) {
+	try {
+		return JSON.parse(e);
+	} catch {
+		return e;
+	}
+}
+function o(o, s = {}) {
+	let { enabled: c = !0, protocols: l, maxRetries: u, initialBackoff: d, maxBackoff: f, pingInterval: p, respondToPing: m, queueWhileClosed: h, maxQueuedMessages: g } = s, [_, v] = i("idle"), [y, b] = i(null), x = r(null), S = r(s);
 	return n(() => {
-		h.current = c;
-	}, [c]), n(() => {
-		if (!s || !a) {
-			d("idle");
+		S.current = s;
+	}), n(() => {
+		if (!c || !o) {
+			v("idle");
 			return;
 		}
-		let t = e(a, {
-			...l,
-			onStatusChange: d,
+		let t = e(o, {
+			protocols: S.current.protocols,
+			maxRetries: u,
+			initialBackoff: d,
+			maxBackoff: f,
+			pingInterval: p,
+			pingPayload: S.current.pingPayload,
+			respondToPing: m,
+			pongPayload: S.current.pongPayload,
+			queueWhileClosed: h,
+			maxQueuedMessages: g,
+			parser: (e) => (S.current.parser ?? a)(e),
+			onStatusChange: v,
+			onOpen: (e) => S.current.onOpen?.(e),
+			onClose: (e) => S.current.onClose?.(e),
+			onError: (e) => S.current.onError?.(e),
 			onMessage: (e) => {
-				p(e), h.current?.(e);
+				b(e), S.current.onMessage?.(e);
 			}
 		});
-		return m.current = t, () => {
-			t.close(), m.current = null;
+		return x.current = t, () => {
+			t.close(), x.current = null;
 		};
-	}, [a, s]), {
-		status: u,
-		lastMessage: f,
-		send: t((e) => m.current?.send(e) ?? !1, []),
+	}, [
+		o,
+		c,
+		Array.isArray(l) ? l.join(",") : l ?? "",
+		u,
+		d,
+		f,
+		p,
+		m,
+		h,
+		g
+	]), {
+		status: _,
+		lastMessage: y,
+		send: t((e) => x.current?.send(e) ?? !1, []),
 		reconnect: t(() => {
-			m.current?.reconnect();
+			x.current?.reconnect();
 		}, [])
 	};
 }
 //#endregion
-export { a as useWebSocket };
+export { o as useWebSocket };
 
 //# sourceMappingURL=use-web-socket.js.map

package/dist/ws/use-web-socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-web-socket.js","names":[],"sources":["../../src/ws/use-web-socket.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n    createWebSocket,\n    type CreateWebSocketOptions,\n    type WebSocketController,\n    type WebSocketMessage,\n    type WebSocketStatus,\n} from \"./create-web-socket\";\n\nexport interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOptions<T>, \"onStatusChange\"> {\n    /** When false, the socket is not opened. Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseWebSocketResult<T> {\n    status: WebSocketStatus;\n    /** Last decoded frame received. */\n    lastMessage: WebSocketMessage<T> | null;\n    /** Send a payload through the active connection. Returns false when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Force a reconnect, resetting the retry counter. */\n    reconnect: () => void;\n}\n\n/**\n * React hook around {@link createWebSocket}. Manages the connection lifecycle\n * for the host component and tears it down on unmount.\n */\nexport function useWebSocket<T = unknown>(\n    url: string,\n    options: UseWebSocketOptions<T> = {},\n): UseWebSocketResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<WebSocketStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<WebSocketMessage<T> | null>(null);\n    const controllerRef = useRef<WebSocketController | null>(null);\n\n    const onMessageRef = useRef(onMessage);\n    useEffect(() => {\n        onMessageRef.current = onMessage;\n    }, [onMessage]);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createWebSocket<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        controllerRef.current = controller;\n\n        return () => {\n            controller.close();\n            controllerRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    const send = useCallback((payload: string | Blob | BufferSource): boolean => {\n        return controllerRef.current?.send(payload) ?? false;\n    }, []);\n\n    const reconnect = useCallback((): void => {\n        controllerRef.current?.reconnect();\n    }, []);\n\n    return { status, lastMessage, send, reconnect };\n}\n"],"mappings":";;;AA4BA,SAAgB,EACZ,GACA,IAAkC,CAAC,GACd;CACrB,IAAM,EAAE,aAAU,IAAM,cAAW,GAAG,MAAS,GACzC,CAAC,GAAQ,KAAa,EAA0B,MAAM,GACtD,CAAC,GAAa,KAAkB,EAAqC,IAAI,GACzE,IAAgB,EAAmC,IAAI,GAEvD,IAAe,EAAO,CAAS;CAoCrC,OAnCA,QAAgB;EACZ,EAAa,UAAU;CAC3B,GAAG,CAAC,CAAS,CAAC,GAEd,QAAgB;EACZ,IAAI,CAAC,KAAW,CAAC,GAAK;GAClB,EAAU,MAAM;GAChB;EACJ;EAEA,IAAM,IAAa,EAAmB,GAAK;GACvC,GAAG;GACH,gBAAgB;GAChB,YAAY,MAAY;IAEpB,AADA,EAAe,CAAO,GACtB,EAAa,UAAU,CAAO;GAClC;EACJ,CAAC;EAGD,OAFA,EAAc,UAAU,SAEX;GAET,AADA,EAAW,MAAM,GACjB,EAAc,UAAU;EAC5B;CAEJ,GAAG,CAAC,GAAK,CAAO,CAAC,GAUV;EAAE;EAAQ;EAAa,MARjB,GAAa,MACf,EAAc,SAAS,KAAK,CAAO,KAAK,IAChD,CAAC,CAM0B;EAAM,WAJlB,QAAwB;GACtC,EAAc,SAAS,UAAU;EACrC,GAAG,CAAC,CAEgC;CAAU;AAClD"}
+{"version":3,"file":"use-web-socket.js","names":[],"sources":["../../src/ws/use-web-socket.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n    createWebSocket,\n    type CreateWebSocketOptions,\n    type WebSocketController,\n    type WebSocketMessage,\n    type WebSocketStatus,\n} from \"./create-web-socket\";\n\nexport interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOptions<T>, \"onStatusChange\"> {\n    /** When false, the socket is not opened. Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseWebSocketResult<T> {\n    status: WebSocketStatus;\n    /**\n     * Last decoded frame received.\n     *\n     * A snapshot, not a stream: two frames arriving in the same tick collapse\n     * into a single render and only the later one is ever visible. One server\n     * action often emits several frames in a row, so anything that must see\n     * every message has to use `onMessage`, which fires once per frame. Read\n     * `lastMessage` for \"what is the current state\" rendering only.\n     */\n    lastMessage: WebSocketMessage<T> | null;\n    /** Send a payload through the active connection. Returns false when not open. */\n    send: (payload: string | Blob | BufferSource) => boolean;\n    /** Force a reconnect, resetting the retry counter. */\n    reconnect: () => void;\n}\n\n/** Mirror of `createWebSocket`'s default parser: JSON, raw string on failure. */\nfunction defaultParse<T>(raw: string): T {\n    try {\n        return JSON.parse(raw) as T;\n    } catch {\n        return raw as unknown as T;\n    }\n}\n\n/**\n * React hook around {@link createWebSocket}. Manages the connection lifecycle\n * for the host component and tears it down on unmount.\n *\n * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /\n * `onError` always run the latest closure — an inline arrow function is fine\n * and never reopens the socket. Connection-shaping options (`protocols`,\n * `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`,\n * `queueWhileClosed`) are baked into the connection, so changing one reopens\n * it with the new value rather than being silently ignored.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Status, last frame, and the `send` / `reconnect` controls.\n */\nexport function useWebSocket<T = unknown>(\n    url: string,\n    options: UseWebSocketOptions<T> = {},\n): UseWebSocketResult<T> {\n    const {\n        enabled = true,\n        protocols,\n        maxRetries,\n        initialBackoff,\n        maxBackoff,\n        pingInterval,\n        respondToPing,\n        queueWhileClosed,\n        maxQueuedMessages,\n    } = options;\n    const [status, setStatus] = useState<WebSocketStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<WebSocketMessage<T> | null>(null);\n    const controllerRef = useRef<WebSocketController | null>(null);\n\n    const optionsRef = useRef(options);\n    useEffect(() => {\n        optionsRef.current = options;\n    });\n\n    const protocolsKey = Array.isArray(protocols) ? protocols.join(\",\") : (protocols ?? \"\");\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createWebSocket<T>(url, {\n            protocols: optionsRef.current.protocols,\n            maxRetries,\n            initialBackoff,\n            maxBackoff,\n            pingInterval,\n            pingPayload: optionsRef.current.pingPayload,\n            respondToPing,\n            pongPayload: optionsRef.current.pongPayload,\n            queueWhileClosed,\n            maxQueuedMessages,\n            parser: (raw) => (optionsRef.current.parser ?? defaultParse<T>)(raw),\n            onStatusChange: setStatus,\n            onOpen: (event) => optionsRef.current.onOpen?.(event),\n            onClose: (event) => optionsRef.current.onClose?.(event),\n            onError: (event) => optionsRef.current.onError?.(event),\n            onMessage: (message) => {\n                setLastMessage(message);\n                optionsRef.current.onMessage?.(message);\n            },\n        });\n        controllerRef.current = controller;\n\n        return () => {\n            controller.close();\n            controllerRef.current = null;\n        };\n    }, [\n        url,\n        enabled,\n        protocolsKey,\n        maxRetries,\n        initialBackoff,\n        maxBackoff,\n        pingInterval,\n        respondToPing,\n        queueWhileClosed,\n        maxQueuedMessages,\n    ]);\n\n    const send = useCallback((payload: string | Blob | BufferSource): boolean => {\n        return controllerRef.current?.send(payload) ?? false;\n    }, []);\n\n    const reconnect = useCallback((): void => {\n        controllerRef.current?.reconnect();\n    }, []);\n\n    return { status, lastMessage, send, reconnect };\n}\n"],"mappings":";;;AAiCA,SAAS,EAAgB,GAAgB;CACrC,IAAI;EACA,OAAO,KAAK,MAAM,CAAG;CACzB,QAAQ;EACJ,OAAO;CACX;AACJ;AAiBA,SAAgB,EACZ,GACA,IAAkC,CAAC,GACd;CACrB,IAAM,EACF,aAAU,IACV,cACA,eACA,mBACA,eACA,iBACA,kBACA,qBACA,yBACA,GACE,CAAC,GAAQ,KAAa,EAA0B,MAAM,GACtD,CAAC,GAAa,KAAkB,EAAqC,IAAI,GACzE,IAAgB,EAAmC,IAAI,GAEvD,IAAa,EAAO,CAAO;CA6DjC,OA5DA,QAAgB;EACZ,EAAW,UAAU;CACzB,CAAC,GAID,QAAgB;EACZ,IAAI,CAAC,KAAW,CAAC,GAAK;GAClB,EAAU,MAAM;GAChB;EACJ;EAEA,IAAM,IAAa,EAAmB,GAAK;GACvC,WAAW,EAAW,QAAQ;GAC9B;GACA;GACA;GACA;GACA,aAAa,EAAW,QAAQ;GAChC;GACA,aAAa,EAAW,QAAQ;GAChC;GACA;GACA,SAAS,OAAS,EAAW,QAAQ,UAAU,EAAA,CAAiB,CAAG;GACnE,gBAAgB;GAChB,SAAS,MAAU,EAAW,QAAQ,SAAS,CAAK;GACpD,UAAU,MAAU,EAAW,QAAQ,UAAU,CAAK;GACtD,UAAU,MAAU,EAAW,QAAQ,UAAU,CAAK;GACtD,YAAY,MAAY;IAEpB,AADA,EAAe,CAAO,GACtB,EAAW,QAAQ,YAAY,CAAO;GAC1C;EACJ,CAAC;EAGD,OAFA,EAAc,UAAU,SAEX;GAET,AADA,EAAW,MAAM,GACjB,EAAc,UAAU;EAC5B;CACJ,GAAG;EACC;EACA;EArCiB,MAAM,QAAQ,CAAS,IAAI,EAAU,KAAK,GAAG,IAAK,KAAa;EAuChF;EACA;EACA;EACA;EACA;EACA;EACA;CACJ,CAAC,GAUM;EAAE;EAAQ;EAAa,MARjB,GAAa,MACf,EAAc,SAAS,KAAK,CAAO,KAAK,IAChD,CAAC,CAM0B;EAAM,WAJlB,QAAwB;GACtC,EAAc,SAAS,UAAU;EACrC,GAAG,CAAC,CAEgC;CAAU;AAClD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.33.2",
+  "version": "0.35.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",

package/template/src/lib/api.ts

@@ -1,15 +1,37 @@
 import { createApiClient, createQueryKeys } from "tempest-react-sdk";
 
-import { useAuth } from "@/stores/auth";
+/** Reads the current bearer token, or null when there is no session. */
+export type TokenProvider = () => string | null;
+
+let readToken: TokenProvider = () => null;
+let handleUnauthorized: () => void = () => {};
+
+/**
+ * Tell the client where the session lives.
+ *
+ * The client ships knowing nothing about auth so a project without accounts
+ * can delete `@/stores/auth` and touch nothing here: with no call to this
+ * function every request goes out unauthenticated and a 401 is just an error.
+ * `@/stores/auth` calls it at module load to wire the store in.
+ *
+ * @param options - Where to read the token and what to do on a 401.
+ */
+export function configureApiAuth(options: {
+    getToken: TokenProvider;
+    onUnauthorized?: () => void;
+}): void {
+    readToken = options.getToken;
+    handleUnauthorized = options.onUnauthorized ?? (() => {});
+}
 
 /**
- * Typed HTTP client. Reads the bearer token from the auth store on every
- * request and points at `VITE_API_URL`.
+ * Typed HTTP client pointed at `VITE_API_URL`, reading the bearer token
+ * through whatever `configureApiAuth` registered.
  */
 export const api = createApiClient({
     baseURL: import.meta.env.VITE_API_URL ?? "http://127.0.0.1:8000",
-    getToken: () => useAuth.getState().token,
-    onUnauthorized: () => useAuth.getState().logout(),
+    getToken: () => readToken(),
+    onUnauthorized: () => handleUnauthorized(),
 });
 
 /** Stable, namespaced query keys for TanStack Query. */

package/template/src/stores/auth.ts

@@ -1,5 +1,7 @@
 import { createAuthStore, createSelectors } from "tempest-react-sdk";
 
+import { configureApiAuth } from "@/lib/api";
+
 /** The user shape your backend returns. Adjust to match your API. */
 export interface User {
     id: string;
@@ -13,3 +15,15 @@ export interface User {
  * subscribe to a single slice.
  */
 export const useAuth = createSelectors(createAuthStore<User>({ name: "app-auth" }));
+
+/**
+ * Hand the store to the HTTP client.
+ *
+ * The dependency points this way on purpose: `@/lib/api` knows nothing about
+ * auth, so a project without accounts deletes this file and the client keeps
+ * working unauthenticated.
+ */
+configureApiAuth({
+    getToken: () => useAuth.getState().token,
+    onUnauthorized: () => useAuth.getState().logout(),
+});