tempest-react-sdk 0.57.0 → 0.58.0

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":["/**\n * @tempest-limits file-lines, function-lines — reconnect with backoff, heartbeat,\n * the handshake and silence timers that detect a link which never fails out loud,\n * the send queue that survives a disconnect and the listener set that must be re-\n * attached to each new socket — one connection's lifetime, one closure. The queue\n * and the reconnect timer are the same decision seen twice.\n */\nimport {\n    backoffDelay,\n    isRejectionCloseCode,\n    shouldRetryClose,\n    type WebSocketLostReason,\n} from \"./resilience\";\nimport { decodeFrame } from \"../utils/json-frame\";\n\nexport 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     * Fraction of each backoff delay added at random, 0–1. Default: 0.3.\n     *\n     * Matters when the *server* is what went down: every client retries on the\n     * same schedule, so the box comes back up into a synchronized stampede. Pass\n     * `0` for a fixed schedule.\n     */\n    jitter?: number;\n    /**\n     * How long one handshake may stay in `CONNECTING` before the attempt is\n     * abandoned and retried (ms). Default: 8000. Pass 0 to disable.\n     *\n     * A `WebSocket` that cannot reach its server does not necessarily fail: it\n     * sits in `CONNECTING` firing neither `open` nor `close` nor `error`. A retry\n     * chain built only on those events stops on its first hung attempt and never\n     * moves again — and hung, rather than refused, is precisely how a bad mobile\n     * link behaves, which is the case reconnection exists for.\n     */\n    handshakeTimeout?: number;\n    /**\n     * Silence tolerated on an open socket before the link is treated as dead (ms).\n     * Default: 0 (off).\n     *\n     * The socket only reports a connection that closes cleanly. A link that dies\n     * mid-flight leaves `readyState` at `OPEN` on this side with nothing ever\n     * arriving again, so silence is the only symptom available. The timer is\n     * re-armed by **any** inbound frame, not just by pings — traffic is traffic.\n     *\n     * Set it to a comfortable multiple of the server's ping interval (2.5× is a\n     * good default) so one dropped ping is not mistaken for an outage. When the\n     * server announces its own interval in the handshake, feed that back with\n     * {@link WebSocketController.setSilenceTimeout} instead of hard-coding the\n     * value on both ends.\n     */\n    silenceTimeout?: number;\n    /**\n     * Suspend the retry schedule while `navigator.onLine` is false, and resume on\n     * the `online` event. Default: true.\n     *\n     * Burning retries against a radio that is switched off is how a phone\n     * exhausts its budget inside a tunnel and gives up exactly when it comes out\n     * the other side.\n     */\n    waitForOnline?: boolean;\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    /**\n     * A frame arrived that is not valid JSON, and no `parser` was supplied.\n     *\n     * Registering this drops the frame instead of delivering it: the previous\n     * behaviour handed `onMessage` the raw `string` announced as your message\n     * type, so the failure surfaced later, at the first property access, with\n     * nothing left pointing at the parse. Leave it out and that behaviour is\n     * kept, with a one-time warning in development builds.\n     */\n    onParseError?: (error: unknown, raw: string) => void;\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     * A retry has been scheduled. `attempt` is 1-based, `total` is `maxRetries`.\n     *\n     * Reconnecting is not an error and reads badly as one: announcing every\n     * attempt puts a fresh \"the connection dropped\" in front of someone whose\n     * session is in the middle of coming back on its own. Show a quiet\n     * reconnecting state here and treat {@link CreateWebSocketOptions.onLost} as\n     * the failure.\n     */\n    onReconnecting?: (attempt: number, total: number) => void;\n    /**\n     * The socket is back up after at least one retry.\n     *\n     * Nothing is resumed for you: a server that keys state by connection sees a\n     * brand-new client, so this is where the caller re-subscribes, re-joins or\n     * refetches whatever the gap invalidated.\n     */\n    onReconnected?: () => void;\n    /**\n     * No further attempt will be made — `\"rejected\"` when the server refused the\n     * client outright (close code 4400–4499, minus the 4408 heartbeat timeout),\n     * `\"exhausted\"` when the schedule ran out.\n     *\n     * This is the one that deserves UI, because it is the only state the caller\n     * can act on: offer a \"try again\" that calls\n     * {@link WebSocketController.reconnect}.\n     */\n    onLost?: (reason: WebSocketLostReason) => 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    /**\n     * Change the silence watchdog at runtime, in ms. `0` disables it.\n     *\n     * For the common case where the server announces its heartbeat interval in\n     * the first frame, so the tolerated silence is not hard-coded on both ends:\n     *\n     * ```ts\n     * onMessage: ({ data }) => {\n     *   if (data.type === \"welcome\") socket.setSilenceTimeout(data.heartbeat_seconds * 2500);\n     * }\n     * ```\n     */\n    setSilenceTimeout: (ms: number) => void;\n    /**\n     * Resolves on the first successful open, rejects when the socket is lost\n     * before ever opening.\n     *\n     * Joining and dropping are different events: a call that never connected has\n     * to be reported, while one that dropped mid-session should reconnect\n     * quietly. Await this for the join, handle\n     * {@link CreateWebSocketOptions.onLost} for the drop. Pair it with\n     * `maxRetries: 0` when the first attempt should fail fast instead of\n     * spending the whole schedule on a server that is not there.\n     */\n    opened: Promise<void>;\n    /** Current connection status. */\n    readonly status: WebSocketStatus;\n}\n\n/**\n * Open a WebSocket that survives a bad network: exponential backoff with jitter,\n * a handshake timeout, a silence watchdog, optional heartbeat pings and typed\n * JSON parsing.\n *\n * Three failure modes are covered that an event-driven retry loop misses on its\n * own, because none of them fire an event: a handshake that hangs instead of\n * failing, an open socket whose link died mid-flight, and a device with its\n * radio off burning the retry budget. See `handshakeTimeout`, `silenceTimeout`\n * and `waitForOnline`.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Controller exposing `send`, `close`, `reconnect`, `setSilenceTimeout`,\n *   `opened` and `status`.\n *\n * @example\n * const socket = createWebSocket(url, {\n *   silenceTimeout: 75_000,\n *   onReconnecting: (n, total) => setBanner(`Reconectando ${n}/${total}…`),\n *   onReconnected: () => refetchEverything(),\n *   onLost: (reason) => setBanner(reason === \"rejected\" ? \"Acesso negado\" : \"Sem conexão\"),\n * });\n * await socket.opened;\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        jitter = 0.3,\n        handshakeTimeout = 8000,\n        silenceTimeout = 0,\n        waitForOnline = true,\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,\n        onOpen,\n        onMessage,\n        onClose,\n        onError,\n        onParseError,\n        onStatusChange,\n        onReconnecting,\n        onReconnected,\n        onLost,\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 handshakeTimer: ReturnType<typeof setTimeout> | null = null;\n    let silenceTimer: ReturnType<typeof setTimeout> | null = null;\n    let onlineListener: (() => void) | null = null;\n    let silenceWindow = silenceTimeout;\n    let retries = 0;\n    let status: WebSocketStatus = \"idle\";\n    let closed = false;\n    let everOpened = false;\n    const outbox: Array<string | Blob | BufferSource> = [];\n\n    let settleOpen: (() => void) | null = null;\n    let failOpen: ((error: Error) => void) | null = null;\n    const opened = new Promise<void>((resolve, reject) => {\n        settleOpen = resolve;\n        failOpen = reject;\n    });\n    opened.catch(() => undefined);\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 clearHandshake(): void {\n        if (handshakeTimer) {\n            clearTimeout(handshakeTimer);\n            handshakeTimer = null;\n        }\n    }\n\n    function clearSilence(): void {\n        if (silenceTimer) {\n            clearTimeout(silenceTimer);\n            silenceTimer = 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    /**\n     * Restart the silence timer, because something just arrived.\n     *\n     * Armed off any inbound frame rather than off pongs alone: a busy exchange\n     * already proves the link is carrying data, and a protocol whose pings the\n     * client never sees would otherwise reconnect in the middle of working\n     * traffic.\n     */\n    function armSilence(): void {\n        clearSilence();\n        if (closed || silenceWindow <= 0) return;\n        silenceTimer = setTimeout(onSilence, silenceWindow);\n    }\n\n    /**\n     * Treat a socket that went quiet as dead and start reconnecting.\n     *\n     * Handlers are detached before closing so the synthetic `close` does not also\n     * schedule a retry — that would advance the backoff twice for one failure and\n     * halve the time the connection is given to recover.\n     */\n    function onSilence(): void {\n        clearSilence();\n        if (closed || !socket) return;\n        detach(socket);\n        socket = null;\n        setStatus(\"closed\");\n        scheduleReconnect();\n    }\n\n    /**\n     * Abandon a handshake that never resolved either way.\n     *\n     * The socket is closed while still `CONNECTING`, which is the one case the\n     * console warns about — and the right trade here, because the alternative is\n     * deferring the close to an `open` event that by definition is not coming.\n     */\n    function abandonHandshake(ws: WebSocket): void {\n        clearHandshake();\n        if (closed || ws.readyState !== WebSocket.CONNECTING) return;\n        detach(ws);\n        if (socket === ws) socket = null;\n        setStatus(\"closed\");\n        scheduleReconnect();\n    }\n\n    /** Drop every handler and close, so the socket can die without being heard. */\n    function detach(ws: WebSocket): void {\n        ws.onopen = null;\n        ws.onmessage = null;\n        ws.onerror = null;\n        ws.onclose = null;\n        try {\n            ws.close();\n        } catch {\n            /* already unusable — nothing to release and nothing to report */\n        }\n    }\n\n    /** Stop for good, telling the caller which of the two dead ends it is. */\n    function lose(reason: WebSocketLostReason): void {\n        clearSilence();\n        clearHandshake();\n        clearNetworkWait();\n        if (reason === \"rejected\") closed = true;\n        setStatus(\"error\");\n        if (!everOpened && failOpen) {\n            const reject = failOpen;\n            failOpen = null;\n            settleOpen = null;\n            reject(new Error(`websocket_${reason}`));\n        }\n        onLost?.(reason);\n    }\n\n    /**\n     * Queue the next attempt, or wait for the network when there is none.\n     *\n     * While the browser reports no connectivity the schedule is suspended and the\n     * `online` event drives the next attempt instead, so a device in a tunnel\n     * does not spend its whole budget before coming out the other side.\n     */\n    function scheduleReconnect(): void {\n        if (closed) return;\n        if (retries >= maxRetries) {\n            lose(\"exhausted\");\n            return;\n        }\n        const delay = backoffDelay(retries, { initialBackoff, maxBackoff, jitter });\n        retries += 1;\n        onReconnecting?.(retries, maxRetries);\n\n        if (waitForOnline && typeof navigator !== \"undefined\" && navigator.onLine === false) {\n            waitForNetwork();\n            return;\n        }\n        retryTimer = setTimeout(connect, delay);\n    }\n\n    function waitForNetwork(): void {\n        if (onlineListener || typeof window === \"undefined\") return;\n        const listener = (): void => {\n            clearNetworkWait();\n            if (!closed) connect();\n        };\n        onlineListener = listener;\n        window.addEventListener(\"online\", listener);\n    }\n\n    function clearNetworkWait(): void {\n        if (!onlineListener || typeof window === \"undefined\") return;\n        window.removeEventListener(\"online\", onlineListener);\n        onlineListener = null;\n    }\n\n    /**\n     * Open a socket, replacing whatever is there.\n     *\n     * The handshake timer is cleared first because it belongs to the socket\n     * being replaced, and it holds a reference to it: left armed, it fires later\n     * against a connection nobody is waiting for, clears the *new* socket's\n     * timer on its way through, and schedules a retry that drops a connection\n     * still in flight. `reconnect()` on a hung socket is the path that reaches\n     * it.\n     */\n    function connect(): void {\n        if (closed) return;\n        retryTimer = null;\n        clearHandshake();\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        if (handshakeTimeout > 0) {\n            handshakeTimer = setTimeout(() => abandonHandshake(ws), handshakeTimeout);\n        }\n\n        ws.onopen = (event) => {\n            clearHandshake();\n            const recovered = retries > 0;\n            retries = 0;\n            everOpened = true;\n            setStatus(\"open\");\n            startPing();\n            armSilence();\n            flushOutbox(ws);\n            if (settleOpen) {\n                const resolve = settleOpen;\n                settleOpen = null;\n                failOpen = null;\n                resolve();\n            }\n            onOpen?.(event);\n            if (recovered) onReconnected?.();\n        };\n\n        ws.onmessage = (event) => {\n            armSilence();\n            const raw = typeof event.data === \"string\" ? event.data : \"\";\n            const decoded = decodeFrame<T>(raw, parser, onParseError, \"createWebSocket\");\n            if (!decoded.delivered) return;\n            const data = decoded.data;\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        /**\n         * Classify the close before deciding anything.\n         *\n         * Three outcomes, in order: a refusal never gets better by trying again;\n         * a died-in-flight or temporarily-unavailable close is retried; an\n         * ordinary goodbye (a clean 1000) is the session ending on purpose and\n         * deserves no error. The one exception is a goodbye on a socket that\n         * never opened — the server hung up during the handshake, which the\n         * caller awaiting `opened` has to hear about.\n         */\n        ws.onclose = (event) => {\n            clearHandshake();\n            clearPing();\n            clearSilence();\n            onClose?.(event);\n            socket = null;\n            setStatus(\"closed\");\n            if (closed) return;\n            if (isRejectionCloseCode(event.code)) {\n                lose(\"rejected\");\n                return;\n            }\n            if (shouldRetryClose(event.code, event.wasClean)) {\n                scheduleReconnect();\n                return;\n            }\n            if (!everOpened) lose(\"rejected\");\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        clearHandshake();\n        clearSilence();\n        clearNetworkWait();\n        retries = 0;\n        outbox.length = 0;\n        if (failOpen) {\n            const reject = failOpen;\n            failOpen = null;\n            settleOpen = null;\n            reject(new Error(\"websocket_closed\"));\n        }\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        clearNetworkWait();\n        retries = 0;\n        closed = false;\n        connect();\n    }\n\n    function setSilenceTimeout(ms: number): void {\n        silenceWindow = Number.isFinite(ms) && ms > 0 ? ms : 0;\n        if (socket?.readyState === WebSocket.OPEN) armSilence();\n        else clearSilence();\n    }\n\n    connect();\n\n    return {\n        send,\n        close,\n        reconnect,\n        setSilenceTimeout,\n        opened,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":"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"}
+{"version":3,"file":"create-web-socket.js","names":[],"sources":["../../src/ws/create-web-socket.ts"],"sourcesContent":["/**\n * @tempest-limits file-lines, function-lines — reconnect with backoff, heartbeat,\n * the handshake and silence timers that detect a link which never fails out loud,\n * the send queue that survives a disconnect and the listener set that must be re-\n * attached to each new socket — one connection's lifetime, one closure. The queue\n * and the reconnect timer are the same decision seen twice.\n */\nimport {\n    backoffDelay,\n    isRejectionCloseCode,\n    shouldRetryClose,\n    type WebSocketLostReason,\n} from \"./resilience\";\nimport { decodeFrame } from \"../utils/json-frame\";\n\nexport 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     * Fraction of each backoff delay added at random, 0–1. Default: 0.3.\n     *\n     * Matters when the *server* is what went down: every client retries on the\n     * same schedule, so the box comes back up into a synchronized stampede. Pass\n     * `0` for a fixed schedule.\n     */\n    jitter?: number;\n    /**\n     * How long one handshake may stay in `CONNECTING` before the attempt is\n     * abandoned and retried (ms). Default: 8000. Pass 0 to disable.\n     *\n     * A `WebSocket` that cannot reach its server does not necessarily fail: it\n     * sits in `CONNECTING` firing neither `open` nor `close` nor `error`. A retry\n     * chain built only on those events stops on its first hung attempt and never\n     * moves again — and hung, rather than refused, is precisely how a bad mobile\n     * link behaves, which is the case reconnection exists for.\n     */\n    handshakeTimeout?: number;\n    /**\n     * Silence tolerated on an open socket before the link is treated as dead (ms).\n     * Default: 0 (off).\n     *\n     * The socket only reports a connection that closes cleanly. A link that dies\n     * mid-flight leaves `readyState` at `OPEN` on this side with nothing ever\n     * arriving again, so silence is the only symptom available. The timer is\n     * re-armed by **any** inbound frame, not just by pings — traffic is traffic.\n     *\n     * Set it to a comfortable multiple of the server's ping interval (2.5× is a\n     * good default) so one dropped ping is not mistaken for an outage. When the\n     * server announces its own interval in the handshake, feed that back with\n     * {@link WebSocketController.setSilenceTimeout} instead of hard-coding the\n     * value on both ends.\n     */\n    silenceTimeout?: number;\n    /**\n     * Suspend the retry schedule while `navigator.onLine` is false, and resume on\n     * the `online` event. Default: true.\n     *\n     * Burning retries against a radio that is switched off is how a phone\n     * exhausts its budget inside a tunnel and gives up exactly when it comes out\n     * the other side.\n     */\n    waitForOnline?: boolean;\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    /**\n     * A frame arrived that is not valid JSON, and no `parser` was supplied.\n     *\n     * Registering this drops the frame instead of delivering it: the previous\n     * behaviour handed `onMessage` the raw `string` announced as your message\n     * type, so the failure surfaced later, at the first property access, with\n     * nothing left pointing at the parse. Leave it out and that behaviour is\n     * kept, with a one-time warning in development builds.\n     */\n    onParseError?: (error: unknown, raw: string) => void;\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     * A retry has been scheduled. `attempt` is 1-based, `total` is `maxRetries`.\n     *\n     * Reconnecting is not an error and reads badly as one: announcing every\n     * attempt puts a fresh \"the connection dropped\" in front of someone whose\n     * session is in the middle of coming back on its own. Show a quiet\n     * reconnecting state here and treat {@link CreateWebSocketOptions.onLost} as\n     * the failure.\n     */\n    onReconnecting?: (attempt: number, total: number) => void;\n    /**\n     * The socket is back up after at least one retry.\n     *\n     * Nothing is resumed for you: a server that keys state by connection sees a\n     * brand-new client, so this is where the caller re-subscribes, re-joins or\n     * refetches whatever the gap invalidated.\n     */\n    onReconnected?: () => void;\n    /**\n     * No further attempt will be made — `\"rejected\"` when the server refused the\n     * client outright (close code 4400–4499, minus the 4408 heartbeat timeout),\n     * `\"exhausted\"` when the schedule ran out.\n     *\n     * This is the one that deserves UI, because it is the only state the caller\n     * can act on: offer a \"try again\" that calls\n     * {@link WebSocketController.reconnect}.\n     */\n    onLost?: (reason: WebSocketLostReason) => 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    /**\n     * Change the silence watchdog at runtime, in ms. `0` disables it.\n     *\n     * For the common case where the server announces its heartbeat interval in\n     * the first frame, so the tolerated silence is not hard-coded on both ends:\n     *\n     * ```ts\n     * onMessage: ({ data }) => {\n     *   if (data.type === \"welcome\") socket.setSilenceTimeout(data.heartbeat_seconds * 2500);\n     * }\n     * ```\n     */\n    setSilenceTimeout: (ms: number) => void;\n    /**\n     * Resolves on the first successful open, rejects when the socket is lost\n     * before ever opening.\n     *\n     * Joining and dropping are different events: a call that never connected has\n     * to be reported, while one that dropped mid-session should reconnect\n     * quietly. Await this for the join, handle\n     * {@link CreateWebSocketOptions.onLost} for the drop. Pair it with\n     * `maxRetries: 0` when the first attempt should fail fast instead of\n     * spending the whole schedule on a server that is not there.\n     */\n    opened: Promise<void>;\n    /** Current connection status. */\n    readonly status: WebSocketStatus;\n}\n\n/**\n * Open a WebSocket that survives a bad network: exponential backoff with jitter,\n * a handshake timeout, a silence watchdog, optional heartbeat pings and typed\n * JSON parsing.\n *\n * Three failure modes are covered that an event-driven retry loop misses on its\n * own, because none of them fire an event: a handshake that hangs instead of\n * failing, an open socket whose link died mid-flight, and a device with its\n * radio off burning the retry budget. See `handshakeTimeout`, `silenceTimeout`\n * and `waitForOnline`.\n *\n * @param url - Full ws:// or wss:// URL.\n * @param options - Connection configuration and callbacks.\n * @returns Controller exposing `send`, `close`, `reconnect`, `setSilenceTimeout`,\n *   `opened` and `status`.\n *\n * @example\n * const socket = createWebSocket(url, {\n *   silenceTimeout: 75_000,\n *   onReconnecting: (n, total) => setBanner(`Reconectando ${n}/${total}…`),\n *   onReconnected: () => refetchEverything(),\n *   onLost: (reason) => setBanner(reason === \"rejected\" ? \"Acesso negado\" : \"Sem conexão\"),\n * });\n * await socket.opened;\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        jitter = 0.3,\n        handshakeTimeout = 8000,\n        silenceTimeout = 0,\n        waitForOnline = true,\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,\n        onOpen,\n        onMessage,\n        onClose,\n        onError,\n        onParseError,\n        onStatusChange,\n        onReconnecting,\n        onReconnected,\n        onLost,\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 handshakeTimer: ReturnType<typeof setTimeout> | null = null;\n    let silenceTimer: ReturnType<typeof setTimeout> | null = null;\n    let onlineListener: (() => void) | null = null;\n    let silenceWindow = silenceTimeout;\n    let retries = 0;\n    let status: WebSocketStatus = \"idle\";\n    let closed = false;\n    let everOpened = false;\n    const outbox: Array<string | Blob | BufferSource> = [];\n\n    let settleOpen: (() => void) | null = null;\n    let failOpen: ((error: Error) => void) | null = null;\n    const opened = new Promise<void>((resolve, reject) => {\n        settleOpen = resolve;\n        failOpen = reject;\n    });\n    opened.catch(() => undefined);\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 clearHandshake(): void {\n        if (handshakeTimer) {\n            clearTimeout(handshakeTimer);\n            handshakeTimer = null;\n        }\n    }\n\n    function clearSilence(): void {\n        if (silenceTimer) {\n            clearTimeout(silenceTimer);\n            silenceTimer = 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    /**\n     * Restart the silence timer, because something just arrived.\n     *\n     * Armed off any inbound frame rather than off pongs alone: a busy exchange\n     * already proves the link is carrying data, and a protocol whose pings the\n     * client never sees would otherwise reconnect in the middle of working\n     * traffic.\n     */\n    function armSilence(): void {\n        clearSilence();\n        if (closed || silenceWindow <= 0) return;\n        silenceTimer = setTimeout(onSilence, silenceWindow);\n    }\n\n    /**\n     * Treat a socket that went quiet as dead and start reconnecting.\n     *\n     * Handlers are detached before closing so the synthetic `close` does not also\n     * schedule a retry — that would advance the backoff twice for one failure and\n     * halve the time the connection is given to recover.\n     */\n    function onSilence(): void {\n        clearSilence();\n        if (closed || !socket) return;\n        detach(socket);\n        socket = null;\n        setStatus(\"closed\");\n        scheduleReconnect();\n    }\n\n    /**\n     * Abandon a handshake that never resolved either way.\n     *\n     * The socket is closed while still `CONNECTING`, which is the one case the\n     * console warns about — and the right trade here, because the alternative is\n     * deferring the close to an `open` event that by definition is not coming.\n     */\n    function abandonHandshake(ws: WebSocket): void {\n        clearHandshake();\n        if (closed || ws.readyState !== WebSocket.CONNECTING) return;\n        detach(ws);\n        if (socket === ws) socket = null;\n        setStatus(\"closed\");\n        scheduleReconnect();\n    }\n\n    /** Drop every handler and close, so the socket can die without being heard. */\n    function detach(ws: WebSocket): void {\n        ws.onopen = null;\n        ws.onmessage = null;\n        ws.onerror = null;\n        ws.onclose = null;\n        try {\n            ws.close();\n        } catch {\n            /* already unusable — nothing to release and nothing to report */\n        }\n    }\n\n    /** Stop for good, telling the caller which of the two dead ends it is. */\n    function lose(reason: WebSocketLostReason): void {\n        clearSilence();\n        clearHandshake();\n        clearNetworkWait();\n        if (reason === \"rejected\") closed = true;\n        setStatus(\"error\");\n        if (!everOpened && failOpen) {\n            const reject = failOpen;\n            failOpen = null;\n            settleOpen = null;\n            reject(new Error(`websocket_${reason}`));\n        }\n        onLost?.(reason);\n    }\n\n    /**\n     * Queue the next attempt, or wait for the network when there is none.\n     *\n     * While the browser reports no connectivity the schedule is suspended and the\n     * `online` event drives the next attempt instead, so a device in a tunnel\n     * does not spend its whole budget before coming out the other side.\n     */\n    function scheduleReconnect(): void {\n        if (closed) return;\n        if (retries >= maxRetries) {\n            lose(\"exhausted\");\n            return;\n        }\n        const delay = backoffDelay(retries, { initialBackoff, maxBackoff, jitter });\n        retries += 1;\n        onReconnecting?.(retries, maxRetries);\n\n        if (waitForOnline && typeof navigator !== \"undefined\" && navigator.onLine === false) {\n            waitForNetwork();\n            return;\n        }\n        retryTimer = setTimeout(connect, delay);\n    }\n\n    function waitForNetwork(): void {\n        if (onlineListener || typeof window === \"undefined\") return;\n        const listener = (): void => {\n            clearNetworkWait();\n            if (!closed) connect();\n        };\n        onlineListener = listener;\n        window.addEventListener(\"online\", listener);\n    }\n\n    function clearNetworkWait(): void {\n        if (!onlineListener || typeof window === \"undefined\") return;\n        window.removeEventListener(\"online\", onlineListener);\n        onlineListener = null;\n    }\n\n    /**\n     * Open a socket, replacing whatever is there.\n     *\n     * The handshake timer is cleared first because it belongs to the socket\n     * being replaced, and it holds a reference to it: left armed, it fires later\n     * against a connection nobody is waiting for, clears the *new* socket's\n     * timer on its way through, and schedules a retry that drops a connection\n     * still in flight. `reconnect()` on a hung socket is the path that reaches\n     * it.\n     */\n    function connect(): void {\n        if (closed) return;\n        retryTimer = null;\n        clearHandshake();\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        if (handshakeTimeout > 0) {\n            handshakeTimer = setTimeout(() => abandonHandshake(ws), handshakeTimeout);\n        }\n\n        ws.onopen = (event) => {\n            clearHandshake();\n            const recovered = retries > 0;\n            retries = 0;\n            everOpened = true;\n            setStatus(\"open\");\n            startPing();\n            armSilence();\n            flushOutbox(ws);\n            if (settleOpen) {\n                const resolve = settleOpen;\n                settleOpen = null;\n                failOpen = null;\n                resolve();\n            }\n            onOpen?.(event);\n            if (recovered) onReconnected?.();\n        };\n\n        ws.onmessage = (event) => {\n            armSilence();\n            const raw = typeof event.data === \"string\" ? event.data : \"\";\n            const decoded = decodeFrame<T>(raw, parser, onParseError, \"createWebSocket\");\n            if (!decoded.delivered) return;\n            const data = decoded.data;\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        /**\n         * Classify the close before deciding anything.\n         *\n         * Three outcomes, in order: a refusal never gets better by trying again;\n         * a died-in-flight or temporarily-unavailable close is retried; an\n         * ordinary goodbye (a clean 1000) is the session ending on purpose and\n         * deserves no error. The one exception is a goodbye on a socket that\n         * never opened — the server hung up during the handshake, which the\n         * caller awaiting `opened` has to hear about.\n         */\n        ws.onclose = (event) => {\n            clearHandshake();\n            clearPing();\n            clearSilence();\n            onClose?.(event);\n            socket = null;\n            setStatus(\"closed\");\n            if (closed) return;\n            if (isRejectionCloseCode(event.code)) {\n                lose(\"rejected\");\n                return;\n            }\n            if (shouldRetryClose(event.code, event.wasClean)) {\n                scheduleReconnect();\n                return;\n            }\n            if (!everOpened) lose(\"rejected\");\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        clearHandshake();\n        clearSilence();\n        clearNetworkWait();\n        retries = 0;\n        outbox.length = 0;\n        if (failOpen) {\n            const reject = failOpen;\n            failOpen = null;\n            settleOpen = null;\n            reject(new Error(\"websocket_closed\"));\n        }\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        clearNetworkWait();\n        retries = 0;\n        closed = false;\n        connect();\n    }\n\n    function setSilenceTimeout(ms: number): void {\n        silenceWindow = Number.isFinite(ms) && ms > 0 ? ms : 0;\n        if (socket?.readyState === WebSocket.OPEN) armSilence();\n        else clearSilence();\n    }\n\n    connect();\n\n    return {\n        send,\n        close,\n        reconnect,\n        setSilenceTimeout,\n        opened,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":"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"}

package/package.json

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