tempest-react-sdk 0.33.2 → 0.34.0

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.34.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(),
+});