tempest-react-sdk 0.61.0 → 0.62.0

package/README.md

@@ -273,8 +273,8 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `sse`                                                                                             | `createEventStream`, `useEventStream` (`onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `sse`                                                                                             | `createEventStream`, `useEventStream` (`schema` valida cada frame — zod/valibot/arktype via Standard Schema — e `onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato não é entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `webrtc`                                                                                          | `tuneOpus` (Opus `fmtp` per audio m-line: per-key merge, `stereo` + `sprop-stereo`, inserts a missing `fmtp`), `setTunedLocalDescription` (falls back to the untouched SDP when the browser refuses the edit), `setSenderBitrate`, `createLinkStatsSampler` / `useLinkStats` / `readRoundTripMs` (throughput as a delta, round trip from the **selected** candidate pair)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -308,8 +308,8 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `sse`                                                                                             | `createEventStream`, `useEventStream` (`onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `sse`                                                                                             | `createEventStream`, `useEventStream` (`schema` valida cada frame — zod/valibot/arktype via Standard Schema — e `onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato não é entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `webrtc`                                                                                          | `tuneOpus` (Opus `fmtp` per audio m-line: per-key merge, `stereo` + `sprop-stereo`, inserts a missing `fmtp`), `setTunedLocalDescription` (falls back to the untouched SDP when the browser refuses the edit), `setSenderBitrate`, `createLinkStatsSampler` / `useLinkStats` / `readRoundTripMs` (throughput as a delta, round trip from the **selected** candidate pair)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -654,15 +654,17 @@ export async function getUser(id: string) {
 
 On validation failure `parseResponse` throws an `Error` whose `message` includes the request label and the zod issues — exactly the diagnostic you want during a wire-protocol drift.
 
-**Under Vite that report needs one line to turn on.** The SDK detects a dev build by reading `process.env.NODE_ENV`, which webpack, Rspack and Parcel substitute while building your app; Vite substitutes neither half, and a browser bundle has no `process` at all, so the read fails and the SDK stays on the safe side — the generic sentence, `vite dev` included. Say so once at bootstrap:
+**Under Vite the report turns itself on.** The SDK detects a dev build by reading `process.env.NODE_ENV`, and every supported bundler substitutes that expression while building your app — Vite included, measured on 5.4.21, 6.4.3, 7.3.6 and 8.2.2, in `vite dev` and in `vite build`, with the SDK installed both as a packed tarball and as a `file:` link. (This paragraph said the opposite until 0.62.0; the belief survived because the expression is not substituted in a browser console, which is where it is natural to check.)
+
+`setDevBuild` remains for what nothing compiles or nothing configures — a raw service-worker script, a plain `<script type="module">`, or a staging build that never sets `NODE_ENV=production` and would otherwise embed the raw response body in an error a real user sees:
 
 ```ts
 import { setDevBuild } from "tempest-react-sdk";
 
-setDevBuild(import.meta.env.DEV);
+setDevBuild(false); // staging talking to real data
 ```
 
-The SDK cannot read `import.meta.env.DEV` for you: Vite would replace it while building _this package_ and the published artifact would carry the constant. The same line un-mutes every other development-only diagnostic in the SDK.
+The SDK cannot read `import.meta.env.DEV` for you: Vite would replace it while building _this package_ and the published artifact would carry the constant.
 
 ### Upload with progress recipe
 

package/dist/sse/create-event-stream.cjs

@@ -1,2 +1,2 @@
-const e=require("../utils/json-frame.cjs");function t(t,n={}){let{withCredentials:r=!1,namedEvents:i=[],heartbeatEvents:a=[`ping`],maxRetries:o=10,initialBackoff:s=1e3,maxBackoff:c=3e4,parser:l,onOpen:u,onMessage:d,onError:f,onParseError:p,onStatusChange:m}=n,h=null,g=null,_=0,v=`idle`,y=!1;function b(e){v!==e&&(v=e,m?.(e))}function x(t,n){if(a.includes(t))return;let r=e.decodeFrame(typeof n.data==`string`?n.data:``,l,p,`createEventStream`);r.delivered&&d?.({event:t,data:r.data,id:n.lastEventId||void 0,raw:n})}function S(){if(y)return;if(_>=o){b(`error`);return}let e=Math.min(s*2**_,c);_+=1,g=setTimeout(C,e)}function C(){if(y)return;h&&h.close(),b(`connecting`);let e=new EventSource(t,{withCredentials:r});h=e,e.onopen=()=>{_=0,b(`open`),u?.()},e.onmessage=e=>x(`message`,e);for(let t of i)e.addEventListener(t,e=>x(t,e));for(let t of a)e.addEventListener(t,()=>{});e.onerror=t=>{f?.(t),e.close(),h=null,b(`closed`),S()}}function w(){y=!0,g&&=(clearTimeout(g),null),_=0,h&&=(h.close(),null),b(`closed`)}function T(){g&&=(clearTimeout(g),null),_=0,y=!1,C()}return C(),{close:w,reconnect:T,get status(){return v}}}exports.createEventStream=t;
+const e=require("../utils/json-frame.cjs");function t(t,n={}){let{withCredentials:r=!1,namedEvents:i=[],heartbeatEvents:a=[`ping`],maxRetries:o=10,initialBackoff:s=1e3,maxBackoff:c=3e4,parser:l,onOpen:u,onMessage:d,onError:f,onParseError:p,schema:m,onValidationError:h,onStatusChange:g}=n,_=null,v=null,y=0,b=`idle`,x=!1;function S(e){b!==e&&(b=e,g?.(e))}function C(t,n){if(a.includes(t))return;let r=e.decodeFrame(typeof n.data==`string`?n.data:``,`createEventStream`,{parser:l,onParseError:p,schema:m,onValidationError:h});r.delivered&&d?.({event:t,data:r.data,id:n.lastEventId||void 0,raw:n})}function w(){if(x)return;if(y>=o){S(`error`);return}let e=Math.min(s*2**y,c);y+=1,v=setTimeout(T,e)}function T(){if(x)return;_&&_.close(),S(`connecting`);let e=new EventSource(t,{withCredentials:r});_=e,e.onopen=()=>{y=0,S(`open`),u?.()},e.onmessage=e=>C(`message`,e);for(let t of i)e.addEventListener(t,e=>C(t,e));for(let t of a)e.addEventListener(t,()=>{});e.onerror=t=>{f?.(t),e.close(),_=null,S(`closed`),w()}}function E(){x=!0,v&&=(clearTimeout(v),null),y=0,_&&=(_.close(),null),S(`closed`)}function D(){v&&=(clearTimeout(v),null),y=0,x=!1,T()}return T(),{close:E,reconnect:D,get status(){return b}}}exports.createEventStream=t;
 //# sourceMappingURL=create-event-stream.cjs.map

package/dist/sse/create-event-stream.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"create-event-stream.cjs","names":[],"sources":["../../src/sse/create-event-stream.ts"],"sourcesContent":["/**\n * @tempest-limits function-lines — the body is the SSE line protocol — accumulate\n * `data:` lines until a blank line, track `id:` for Last-Event-ID, honour `retry:` —\n * plus the reconnect that uses the id it just tracked.\n */\nimport { decodeFrame } from \"../utils/json-frame\";\nexport type EventStreamStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\" | \"error\";\n\nexport interface EventStreamMessage<T> {\n    /** Server-named event (default `\"message\"`). */\n    event: string;\n    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** Server-supplied id, if any. */\n    id?: string;\n    /** Raw `MessageEvent` for advanced cases. */\n    raw: MessageEvent;\n}\n\nexport interface CreateEventStreamOptions<T> {\n    /** Send cookies with the EventSource handshake. Default: false. */\n    withCredentials?: boolean;\n    /** Subscribe to named events in addition to `message`. */\n    namedEvents?: readonly string[];\n    /** Treat these named events as heartbeat-only (no callback). Default: `[\"ping\"]`. */\n    heartbeatEvents?: readonly string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable reconnect. */\n    maxRetries?: number;\n    /** Initial backoff in ms; doubles per attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff in ms. Default: 30000. */\n    maxBackoff?: number;\n    /** Parse `event.data`. Defaults to 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?: () => void;\n    onMessage?: (message: EventStreamMessage<T>) => void;\n    onError?: (error: Event) => void;\n    onStatusChange?: (status: EventStreamStatus) => void;\n}\n\nexport interface EventStreamController {\n    close: () => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: EventStreamStatus;\n}\n\n/**\n * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.\n *\n * Heartbeat events (default `\"ping\"`) keep the socket alive without firing\n * `onMessage`. Pass `withCredentials: true` when the backend authenticates via\n * cookies. Call `close()` from the returned controller to tear down.\n *\n * @param url - Full SSE endpoint URL.\n * @param options - Stream configuration and callbacks.\n * @returns A controller exposing `close`, `reconnect` and the current `status`.\n */\nexport function createEventStream<T = unknown>(\n    url: string,\n    options: CreateEventStreamOptions<T> = {},\n): EventStreamController {\n    const {\n        withCredentials = false,\n        namedEvents = [],\n        heartbeatEvents = [\"ping\"],\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        parser,\n        onOpen,\n        onMessage,\n        onError,\n        onParseError,\n        onStatusChange,\n    } = options;\n\n    let source: EventSource | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let retries = 0;\n    let status: EventStreamStatus = \"idle\";\n    let closed = false;\n\n    function setStatus(next: EventStreamStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function emit(eventName: string, event: MessageEvent): void {\n        if (heartbeatEvents.includes(eventName)) return;\n        const decoded = decodeFrame<T>(\n            typeof event.data === \"string\" ? event.data : \"\",\n            parser,\n            onParseError,\n            \"createEventStream\",\n        );\n        if (!decoded.delivered) return;\n        onMessage?.({\n            event: eventName,\n            data: decoded.data,\n            id: event.lastEventId || undefined,\n            raw: event,\n        });\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 (source) source.close();\n        setStatus(\"connecting\");\n\n        const es = new EventSource(url, { withCredentials });\n        source = es;\n\n        es.onopen = () => {\n            retries = 0;\n            setStatus(\"open\");\n            onOpen?.();\n        };\n\n        es.onmessage = (event) => emit(\"message\", event);\n        for (const name of namedEvents) {\n            es.addEventListener(name, (event) => emit(name, event as MessageEvent));\n        }\n        for (const name of heartbeatEvents) {\n            es.addEventListener(name, () => {\n                /* heartbeat — keep socket alive */\n            });\n        }\n\n        es.onerror = (event) => {\n            onError?.(event);\n            es.close();\n            source = null;\n            setStatus(\"closed\");\n            scheduleReconnect();\n        };\n    }\n\n    function close(): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        if (source) {\n            source.close();\n            source = 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        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":"2CAqEA,SAAgB,EACZ,EACA,EAAuC,CAAC,EACnB,CACrB,GAAM,CACF,kBAAkB,GAClB,cAAc,CAAC,EACf,kBAAkB,CAAC,MAAM,EACzB,aAAa,GACb,iBAAiB,IACjB,aAAa,IACb,SACA,SACA,YACA,UACA,eACA,kBACA,EAEA,EAA6B,KAC7B,EAAmD,KACnD,EAAU,EACV,EAA4B,OAC5B,EAAS,GAEb,SAAS,EAAU,EAA+B,CAC1C,IAAW,IACf,EAAS,EACT,IAAiB,CAAI,EACzB,CAEA,SAAS,EAAK,EAAmB,EAA2B,CACxD,GAAI,EAAgB,SAAS,CAAS,EAAG,OACzC,IAAM,EAAU,EAAA,YACZ,OAAO,EAAM,MAAS,SAAW,EAAM,KAAO,GAC9C,EACA,EACA,mBACJ,EACK,EAAQ,WACb,IAAY,CACR,MAAO,EACP,KAAM,EAAQ,KACd,GAAI,EAAM,aAAe,IAAA,GACzB,IAAK,CACT,CAAC,CACL,CAEA,SAAS,GAA0B,CAC/B,GAAI,EAAQ,OACZ,GAAI,GAAW,EAAY,CACvB,EAAU,OAAO,EACjB,MACJ,CACA,IAAM,EAAQ,KAAK,IAAI,EAAiB,GAAK,EAAS,CAAU,EAChE,GAAW,EACX,EAAa,WAAW,EAAS,CAAK,CAC1C,CAEA,SAAS,GAAgB,CACrB,GAAI,EAAQ,OACR,GAAQ,EAAO,MAAM,EACzB,EAAU,YAAY,EAEtB,IAAM,EAAK,IAAI,YAAY,EAAK,CAAE,iBAAgB,CAAC,EACnD,EAAS,EAET,EAAG,WAAe,CACd,EAAU,EACV,EAAU,MAAM,EAChB,IAAS,CACb,EAEA,EAAG,UAAa,GAAU,EAAK,UAAW,CAAK,EAC/C,IAAK,IAAM,KAAQ,EACf,EAAG,iBAAiB,EAAO,GAAU,EAAK,EAAM,CAAqB,CAAC,EAE1E,IAAK,IAAM,KAAQ,EACf,EAAG,iBAAiB,MAAY,CAEhC,CAAC,EAGL,EAAG,QAAW,GAAU,CACpB,IAAU,CAAK,EACf,EAAG,MAAM,EACT,EAAS,KACT,EAAU,QAAQ,EAClB,EAAkB,CACtB,CACJ,CAEA,SAAS,GAAc,CACnB,EAAS,GACT,AAEI,KADA,aAAa,CAAU,EACV,MAEjB,EAAU,EACV,AAEI,KADA,EAAO,MAAM,EACJ,MAEb,EAAU,QAAQ,CACtB,CAEA,SAAS,GAAkB,CACvB,AAEI,KADA,aAAa,CAAU,EACV,MAEjB,EAAU,EACV,EAAS,GACT,EAAQ,CACZ,CAIA,OAFA,EAAQ,EAED,CACH,QACA,YACA,IAAI,QAAS,CACT,OAAO,CACX,CACJ,CACJ"}
+{"version":3,"file":"create-event-stream.cjs","names":[],"sources":["../../src/sse/create-event-stream.ts"],"sourcesContent":["/**\n * @tempest-limits function-lines — the body is the SSE line protocol — accumulate\n * `data:` lines until a blank line, track `id:` for Last-Event-ID, honour `retry:` —\n * plus the reconnect that uses the id it just tracked.\n */\nimport { decodeFrame } from \"../utils/json-frame\";\nimport type { SchemaIssue, SchemaLike } from \"../utils/schema-like\";\nexport type EventStreamStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\" | \"error\";\n\nexport interface EventStreamMessage<T> {\n    /** Server-named event (default `\"message\"`). */\n    event: string;\n    /** Parsed payload — validated when `schema` is set, JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** Server-supplied id, if any. */\n    id?: string;\n    /** Raw `MessageEvent` for advanced cases. */\n    raw: MessageEvent;\n}\n\nexport interface CreateEventStreamOptions<T> {\n    /** Send cookies with the EventSource handshake. Default: false. */\n    withCredentials?: boolean;\n    /** Subscribe to named events in addition to `message`. */\n    namedEvents?: readonly string[];\n    /** Treat these named events as heartbeat-only (no callback). Default: `[\"ping\"]`. */\n    heartbeatEvents?: readonly string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable reconnect. */\n    maxRetries?: number;\n    /** Initial backoff in ms; doubles per attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff in ms. Default: 30000. */\n    maxBackoff?: number;\n    /** Parse `event.data`. Defaults to 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    /**\n     * Schema every decoded frame must satisfy, from zod, valibot, arktype or\n     * anything else exposing `~standard` or `.safeParse`.\n     *\n     * Without it nothing changes: the payload reaches `onMessage` announced as\n     * `T` on the strength of the type argument alone, which is a promise about\n     * the server that TypeScript cannot keep. With it, a frame that does not\n     * match is **not** delivered — the same rule `onParseError` already follows —\n     * and `onValidationError` hears why. The value delivered is the schema's\n     * output, so coercions and defaults are honoured.\n     *\n     * When `parser` is also supplied, it decodes first and the schema validates\n     * what it returned.\n     *\n     * The validation must be synchronous. A frame is decoded inside the\n     * `message` handler and delivered from it, so an async schema would deliver\n     * frames in whatever order their validations settled; that case is reported\n     * through `onValidationError` instead of awaited.\n     */\n    schema?: SchemaLike<T>;\n    /**\n     * A frame was decoded but the `schema` refused it, so it was dropped.\n     *\n     * The one signal that does not depend on how the app's bundler resolves\n     * `process`: the one-time development warning behind `onParseError` needs\n     * `isDevBuild()` to be able to answer, and this callback is the app's own.\n     */\n    onValidationError?: (issues: SchemaIssue[], raw: string) => void;\n    onOpen?: () => void;\n    onMessage?: (message: EventStreamMessage<T>) => void;\n    onError?: (error: Event) => void;\n    onStatusChange?: (status: EventStreamStatus) => void;\n}\n\nexport interface EventStreamController {\n    close: () => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: EventStreamStatus;\n}\n\n/**\n * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.\n *\n * Heartbeat events (default `\"ping\"`) keep the socket alive without firing\n * `onMessage`. Pass `withCredentials: true` when the backend authenticates via\n * cookies. Call `close()` from the returned controller to tear down.\n *\n * @param url - Full SSE endpoint URL.\n * @param options - Stream configuration and callbacks.\n * @returns A controller exposing `close`, `reconnect` and the current `status`.\n */\nexport function createEventStream<T = unknown>(\n    url: string,\n    options: CreateEventStreamOptions<T> = {},\n): EventStreamController {\n    const {\n        withCredentials = false,\n        namedEvents = [],\n        heartbeatEvents = [\"ping\"],\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        parser,\n        onOpen,\n        onMessage,\n        onError,\n        onParseError,\n        schema,\n        onValidationError,\n        onStatusChange,\n    } = options;\n\n    let source: EventSource | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let retries = 0;\n    let status: EventStreamStatus = \"idle\";\n    let closed = false;\n\n    function setStatus(next: EventStreamStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function emit(eventName: string, event: MessageEvent): void {\n        if (heartbeatEvents.includes(eventName)) return;\n        const decoded = decodeFrame<T>(\n            typeof event.data === \"string\" ? event.data : \"\",\n            \"createEventStream\",\n            { parser, onParseError, schema, onValidationError },\n        );\n        if (!decoded.delivered) return;\n        onMessage?.({\n            event: eventName,\n            data: decoded.data,\n            id: event.lastEventId || undefined,\n            raw: event,\n        });\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 (source) source.close();\n        setStatus(\"connecting\");\n\n        const es = new EventSource(url, { withCredentials });\n        source = es;\n\n        es.onopen = () => {\n            retries = 0;\n            setStatus(\"open\");\n            onOpen?.();\n        };\n\n        es.onmessage = (event) => emit(\"message\", event);\n        for (const name of namedEvents) {\n            es.addEventListener(name, (event) => emit(name, event as MessageEvent));\n        }\n        for (const name of heartbeatEvents) {\n            es.addEventListener(name, () => {\n                /* heartbeat — keep socket alive */\n            });\n        }\n\n        es.onerror = (event) => {\n            onError?.(event);\n            es.close();\n            source = null;\n            setStatus(\"closed\");\n            scheduleReconnect();\n        };\n    }\n\n    function close(): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        if (source) {\n            source.close();\n            source = 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        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":"2CAkGA,SAAgB,EACZ,EACA,EAAuC,CAAC,EACnB,CACrB,GAAM,CACF,kBAAkB,GAClB,cAAc,CAAC,EACf,kBAAkB,CAAC,MAAM,EACzB,aAAa,GACb,iBAAiB,IACjB,aAAa,IACb,SACA,SACA,YACA,UACA,eACA,SACA,oBACA,kBACA,EAEA,EAA6B,KAC7B,EAAmD,KACnD,EAAU,EACV,EAA4B,OAC5B,EAAS,GAEb,SAAS,EAAU,EAA+B,CAC1C,IAAW,IACf,EAAS,EACT,IAAiB,CAAI,EACzB,CAEA,SAAS,EAAK,EAAmB,EAA2B,CACxD,GAAI,EAAgB,SAAS,CAAS,EAAG,OACzC,IAAM,EAAU,EAAA,YACZ,OAAO,EAAM,MAAS,SAAW,EAAM,KAAO,GAC9C,oBACA,CAAE,SAAQ,eAAc,SAAQ,mBAAkB,CACtD,EACK,EAAQ,WACb,IAAY,CACR,MAAO,EACP,KAAM,EAAQ,KACd,GAAI,EAAM,aAAe,IAAA,GACzB,IAAK,CACT,CAAC,CACL,CAEA,SAAS,GAA0B,CAC/B,GAAI,EAAQ,OACZ,GAAI,GAAW,EAAY,CACvB,EAAU,OAAO,EACjB,MACJ,CACA,IAAM,EAAQ,KAAK,IAAI,EAAiB,GAAK,EAAS,CAAU,EAChE,GAAW,EACX,EAAa,WAAW,EAAS,CAAK,CAC1C,CAEA,SAAS,GAAgB,CACrB,GAAI,EAAQ,OACR,GAAQ,EAAO,MAAM,EACzB,EAAU,YAAY,EAEtB,IAAM,EAAK,IAAI,YAAY,EAAK,CAAE,iBAAgB,CAAC,EACnD,EAAS,EAET,EAAG,WAAe,CACd,EAAU,EACV,EAAU,MAAM,EAChB,IAAS,CACb,EAEA,EAAG,UAAa,GAAU,EAAK,UAAW,CAAK,EAC/C,IAAK,IAAM,KAAQ,EACf,EAAG,iBAAiB,EAAO,GAAU,EAAK,EAAM,CAAqB,CAAC,EAE1E,IAAK,IAAM,KAAQ,EACf,EAAG,iBAAiB,MAAY,CAEhC,CAAC,EAGL,EAAG,QAAW,GAAU,CACpB,IAAU,CAAK,EACf,EAAG,MAAM,EACT,EAAS,KACT,EAAU,QAAQ,EAClB,EAAkB,CACtB,CACJ,CAEA,SAAS,GAAc,CACnB,EAAS,GACT,AAEI,KADA,aAAa,CAAU,EACV,MAEjB,EAAU,EACV,AAEI,KADA,EAAO,MAAM,EACJ,MAEb,EAAU,QAAQ,CACtB,CAEA,SAAS,GAAkB,CACvB,AAEI,KADA,aAAa,CAAU,EACV,MAEjB,EAAU,EACV,EAAS,GACT,EAAQ,CACZ,CAIA,OAFA,EAAQ,EAED,CACH,QACA,YACA,IAAI,QAAS,CACT,OAAO,CACX,CACJ,CACJ"}

package/dist/sse/create-event-stream.js

@@ -1,13 +1,18 @@
 import { decodeFrame as e } from "../utils/json-frame.js";
 //#region src/sse/create-event-stream.ts
 function t(t, n = {}) {
-	let { withCredentials: r = !1, namedEvents: i = [], heartbeatEvents: a = ["ping"], maxRetries: o = 10, initialBackoff: s = 1e3, maxBackoff: c = 3e4, parser: l, onOpen: u, onMessage: d, onError: f, onParseError: p, onStatusChange: m } = n, h = null, g = null, _ = 0, v = "idle", y = !1;
-	function b(e) {
-		v !== e && (v = e, m?.(e));
+	let { withCredentials: r = !1, namedEvents: i = [], heartbeatEvents: a = ["ping"], maxRetries: o = 10, initialBackoff: s = 1e3, maxBackoff: c = 3e4, parser: l, onOpen: u, onMessage: d, onError: f, onParseError: p, schema: m, onValidationError: h, onStatusChange: g } = n, _ = null, v = null, y = 0, b = "idle", x = !1;
+	function S(e) {
+		b !== e && (b = e, g?.(e));
 	}
-	function x(t, n) {
+	function C(t, n) {
 		if (a.includes(t)) return;
-		let r = e(typeof n.data == "string" ? n.data : "", l, p, "createEventStream");
+		let r = e(typeof n.data == "string" ? n.data : "", "createEventStream", {
+			parser: l,
+			onParseError: p,
+			schema: m,
+			onValidationError: h
+		});
 		r.delivered && d?.({
 			event: t,
 			data: r.data,
@@ -15,39 +20,39 @@ function t(t, n = {}) {
 			raw: n
 		});
 	}
-	function S() {
-		if (y) return;
-		if (_ >= o) {
-			b("error");
+	function w() {
+		if (x) return;
+		if (y >= o) {
+			S("error");
 			return;
 		}
-		let e = Math.min(s * 2 ** _, c);
-		_ += 1, g = setTimeout(C, e);
+		let e = Math.min(s * 2 ** y, c);
+		y += 1, v = setTimeout(T, e);
 	}
-	function C() {
-		if (y) return;
-		h && h.close(), b("connecting");
+	function T() {
+		if (x) return;
+		_ && _.close(), S("connecting");
 		let e = new EventSource(t, { withCredentials: r });
-		h = e, e.onopen = () => {
-			_ = 0, b("open"), u?.();
-		}, e.onmessage = (e) => x("message", e);
-		for (let t of i) e.addEventListener(t, (e) => x(t, e));
+		_ = e, e.onopen = () => {
+			y = 0, S("open"), u?.();
+		}, e.onmessage = (e) => C("message", e);
+		for (let t of i) e.addEventListener(t, (e) => C(t, e));
 		for (let t of a) e.addEventListener(t, () => {});
 		e.onerror = (t) => {
-			f?.(t), e.close(), h = null, b("closed"), S();
+			f?.(t), e.close(), _ = null, S("closed"), w();
 		};
 	}
-	function w() {
-		y = !0, g &&= (clearTimeout(g), null), _ = 0, h &&= (h.close(), null), b("closed");
+	function E() {
+		x = !0, v &&= (clearTimeout(v), null), y = 0, _ &&= (_.close(), null), S("closed");
 	}
-	function T() {
-		g &&= (clearTimeout(g), null), _ = 0, y = !1, C();
+	function D() {
+		v &&= (clearTimeout(v), null), y = 0, x = !1, T();
 	}
-	return C(), {
-		close: w,
-		reconnect: T,
+	return T(), {
+		close: E,
+		reconnect: D,
 		get status() {
-			return v;
+			return b;
 		}
 	};
 }

package/dist/sse/create-event-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-event-stream.js","names":[],"sources":["../../src/sse/create-event-stream.ts"],"sourcesContent":["/**\n * @tempest-limits function-lines — the body is the SSE line protocol — accumulate\n * `data:` lines until a blank line, track `id:` for Last-Event-ID, honour `retry:` —\n * plus the reconnect that uses the id it just tracked.\n */\nimport { decodeFrame } from \"../utils/json-frame\";\nexport type EventStreamStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\" | \"error\";\n\nexport interface EventStreamMessage<T> {\n    /** Server-named event (default `\"message\"`). */\n    event: string;\n    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** Server-supplied id, if any. */\n    id?: string;\n    /** Raw `MessageEvent` for advanced cases. */\n    raw: MessageEvent;\n}\n\nexport interface CreateEventStreamOptions<T> {\n    /** Send cookies with the EventSource handshake. Default: false. */\n    withCredentials?: boolean;\n    /** Subscribe to named events in addition to `message`. */\n    namedEvents?: readonly string[];\n    /** Treat these named events as heartbeat-only (no callback). Default: `[\"ping\"]`. */\n    heartbeatEvents?: readonly string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable reconnect. */\n    maxRetries?: number;\n    /** Initial backoff in ms; doubles per attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff in ms. Default: 30000. */\n    maxBackoff?: number;\n    /** Parse `event.data`. Defaults to 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?: () => void;\n    onMessage?: (message: EventStreamMessage<T>) => void;\n    onError?: (error: Event) => void;\n    onStatusChange?: (status: EventStreamStatus) => void;\n}\n\nexport interface EventStreamController {\n    close: () => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: EventStreamStatus;\n}\n\n/**\n * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.\n *\n * Heartbeat events (default `\"ping\"`) keep the socket alive without firing\n * `onMessage`. Pass `withCredentials: true` when the backend authenticates via\n * cookies. Call `close()` from the returned controller to tear down.\n *\n * @param url - Full SSE endpoint URL.\n * @param options - Stream configuration and callbacks.\n * @returns A controller exposing `close`, `reconnect` and the current `status`.\n */\nexport function createEventStream<T = unknown>(\n    url: string,\n    options: CreateEventStreamOptions<T> = {},\n): EventStreamController {\n    const {\n        withCredentials = false,\n        namedEvents = [],\n        heartbeatEvents = [\"ping\"],\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        parser,\n        onOpen,\n        onMessage,\n        onError,\n        onParseError,\n        onStatusChange,\n    } = options;\n\n    let source: EventSource | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let retries = 0;\n    let status: EventStreamStatus = \"idle\";\n    let closed = false;\n\n    function setStatus(next: EventStreamStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function emit(eventName: string, event: MessageEvent): void {\n        if (heartbeatEvents.includes(eventName)) return;\n        const decoded = decodeFrame<T>(\n            typeof event.data === \"string\" ? event.data : \"\",\n            parser,\n            onParseError,\n            \"createEventStream\",\n        );\n        if (!decoded.delivered) return;\n        onMessage?.({\n            event: eventName,\n            data: decoded.data,\n            id: event.lastEventId || undefined,\n            raw: event,\n        });\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 (source) source.close();\n        setStatus(\"connecting\");\n\n        const es = new EventSource(url, { withCredentials });\n        source = es;\n\n        es.onopen = () => {\n            retries = 0;\n            setStatus(\"open\");\n            onOpen?.();\n        };\n\n        es.onmessage = (event) => emit(\"message\", event);\n        for (const name of namedEvents) {\n            es.addEventListener(name, (event) => emit(name, event as MessageEvent));\n        }\n        for (const name of heartbeatEvents) {\n            es.addEventListener(name, () => {\n                /* heartbeat — keep socket alive */\n            });\n        }\n\n        es.onerror = (event) => {\n            onError?.(event);\n            es.close();\n            source = null;\n            setStatus(\"closed\");\n            scheduleReconnect();\n        };\n    }\n\n    function close(): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        if (source) {\n            source.close();\n            source = 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        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":";;AAqEA,SAAgB,EACZ,GACA,IAAuC,CAAC,GACnB;CACrB,IAAM,EACF,qBAAkB,IAClB,iBAAc,CAAC,GACf,qBAAkB,CAAC,MAAM,GACzB,gBAAa,IACb,oBAAiB,KACjB,gBAAa,KACb,WACA,WACA,cACA,YACA,iBACA,sBACA,GAEA,IAA6B,MAC7B,IAAmD,MACnD,IAAU,GACV,IAA4B,QAC5B,IAAS;CAEb,SAAS,EAAU,GAA+B;EAC1C,MAAW,MACf,IAAS,GACT,IAAiB,CAAI;CACzB;CAEA,SAAS,EAAK,GAAmB,GAA2B;EACxD,IAAI,EAAgB,SAAS,CAAS,GAAG;EACzC,IAAM,IAAU,EACZ,OAAO,EAAM,QAAS,WAAW,EAAM,OAAO,IAC9C,GACA,GACA,mBACJ;EACK,EAAQ,aACb,IAAY;GACR,OAAO;GACP,MAAM,EAAQ;GACd,IAAI,EAAM,eAAe,KAAA;GACzB,KAAK;EACT,CAAC;CACL;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;EAEZ,AADI,KAAQ,EAAO,MAAM,GACzB,EAAU,YAAY;EAEtB,IAAM,IAAK,IAAI,YAAY,GAAK,EAAE,mBAAgB,CAAC;EASnD,AARA,IAAS,GAET,EAAG,eAAe;GAGd,AAFA,IAAU,GACV,EAAU,MAAM,GAChB,IAAS;EACb,GAEA,EAAG,aAAa,MAAU,EAAK,WAAW,CAAK;EAC/C,KAAK,IAAM,KAAQ,GACf,EAAG,iBAAiB,IAAO,MAAU,EAAK,GAAM,CAAqB,CAAC;EAE1E,KAAK,IAAM,KAAQ,GACf,EAAG,iBAAiB,SAAY,CAEhC,CAAC;EAGL,EAAG,WAAW,MAAU;GAKpB,AAJA,IAAU,CAAK,GACf,EAAG,MAAM,GACT,IAAS,MACT,EAAU,QAAQ,GAClB,EAAkB;EACtB;CACJ;CAEA,SAAS,IAAc;EAWnB,AAVA,IAAS,IACT,AAEI,OADA,aAAa,CAAU,GACV,OAEjB,IAAU,GACV,AAEI,OADA,EAAO,MAAM,GACJ,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,IAAI,SAAS;GACT,OAAO;EACX;CACJ;AACJ"}
+{"version":3,"file":"create-event-stream.js","names":[],"sources":["../../src/sse/create-event-stream.ts"],"sourcesContent":["/**\n * @tempest-limits function-lines — the body is the SSE line protocol — accumulate\n * `data:` lines until a blank line, track `id:` for Last-Event-ID, honour `retry:` —\n * plus the reconnect that uses the id it just tracked.\n */\nimport { decodeFrame } from \"../utils/json-frame\";\nimport type { SchemaIssue, SchemaLike } from \"../utils/schema-like\";\nexport type EventStreamStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\" | \"error\";\n\nexport interface EventStreamMessage<T> {\n    /** Server-named event (default `\"message\"`). */\n    event: string;\n    /** Parsed payload — validated when `schema` is set, JSON-decoded when possible, raw string otherwise. */\n    data: T;\n    /** Server-supplied id, if any. */\n    id?: string;\n    /** Raw `MessageEvent` for advanced cases. */\n    raw: MessageEvent;\n}\n\nexport interface CreateEventStreamOptions<T> {\n    /** Send cookies with the EventSource handshake. Default: false. */\n    withCredentials?: boolean;\n    /** Subscribe to named events in addition to `message`. */\n    namedEvents?: readonly string[];\n    /** Treat these named events as heartbeat-only (no callback). Default: `[\"ping\"]`. */\n    heartbeatEvents?: readonly string[];\n    /** Max reconnect attempts. Default: 10. Pass 0 to disable reconnect. */\n    maxRetries?: number;\n    /** Initial backoff in ms; doubles per attempt, capped at `maxBackoff`. Default: 1000. */\n    initialBackoff?: number;\n    /** Maximum backoff in ms. Default: 30000. */\n    maxBackoff?: number;\n    /** Parse `event.data`. Defaults to 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    /**\n     * Schema every decoded frame must satisfy, from zod, valibot, arktype or\n     * anything else exposing `~standard` or `.safeParse`.\n     *\n     * Without it nothing changes: the payload reaches `onMessage` announced as\n     * `T` on the strength of the type argument alone, which is a promise about\n     * the server that TypeScript cannot keep. With it, a frame that does not\n     * match is **not** delivered — the same rule `onParseError` already follows —\n     * and `onValidationError` hears why. The value delivered is the schema's\n     * output, so coercions and defaults are honoured.\n     *\n     * When `parser` is also supplied, it decodes first and the schema validates\n     * what it returned.\n     *\n     * The validation must be synchronous. A frame is decoded inside the\n     * `message` handler and delivered from it, so an async schema would deliver\n     * frames in whatever order their validations settled; that case is reported\n     * through `onValidationError` instead of awaited.\n     */\n    schema?: SchemaLike<T>;\n    /**\n     * A frame was decoded but the `schema` refused it, so it was dropped.\n     *\n     * The one signal that does not depend on how the app's bundler resolves\n     * `process`: the one-time development warning behind `onParseError` needs\n     * `isDevBuild()` to be able to answer, and this callback is the app's own.\n     */\n    onValidationError?: (issues: SchemaIssue[], raw: string) => void;\n    onOpen?: () => void;\n    onMessage?: (message: EventStreamMessage<T>) => void;\n    onError?: (error: Event) => void;\n    onStatusChange?: (status: EventStreamStatus) => void;\n}\n\nexport interface EventStreamController {\n    close: () => void;\n    /** Force an immediate reconnect, resetting the retry counter. */\n    reconnect: () => void;\n    /** Current connection status. */\n    readonly status: EventStreamStatus;\n}\n\n/**\n * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.\n *\n * Heartbeat events (default `\"ping\"`) keep the socket alive without firing\n * `onMessage`. Pass `withCredentials: true` when the backend authenticates via\n * cookies. Call `close()` from the returned controller to tear down.\n *\n * @param url - Full SSE endpoint URL.\n * @param options - Stream configuration and callbacks.\n * @returns A controller exposing `close`, `reconnect` and the current `status`.\n */\nexport function createEventStream<T = unknown>(\n    url: string,\n    options: CreateEventStreamOptions<T> = {},\n): EventStreamController {\n    const {\n        withCredentials = false,\n        namedEvents = [],\n        heartbeatEvents = [\"ping\"],\n        maxRetries = 10,\n        initialBackoff = 1000,\n        maxBackoff = 30000,\n        parser,\n        onOpen,\n        onMessage,\n        onError,\n        onParseError,\n        schema,\n        onValidationError,\n        onStatusChange,\n    } = options;\n\n    let source: EventSource | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let retries = 0;\n    let status: EventStreamStatus = \"idle\";\n    let closed = false;\n\n    function setStatus(next: EventStreamStatus): void {\n        if (status === next) return;\n        status = next;\n        onStatusChange?.(next);\n    }\n\n    function emit(eventName: string, event: MessageEvent): void {\n        if (heartbeatEvents.includes(eventName)) return;\n        const decoded = decodeFrame<T>(\n            typeof event.data === \"string\" ? event.data : \"\",\n            \"createEventStream\",\n            { parser, onParseError, schema, onValidationError },\n        );\n        if (!decoded.delivered) return;\n        onMessage?.({\n            event: eventName,\n            data: decoded.data,\n            id: event.lastEventId || undefined,\n            raw: event,\n        });\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 (source) source.close();\n        setStatus(\"connecting\");\n\n        const es = new EventSource(url, { withCredentials });\n        source = es;\n\n        es.onopen = () => {\n            retries = 0;\n            setStatus(\"open\");\n            onOpen?.();\n        };\n\n        es.onmessage = (event) => emit(\"message\", event);\n        for (const name of namedEvents) {\n            es.addEventListener(name, (event) => emit(name, event as MessageEvent));\n        }\n        for (const name of heartbeatEvents) {\n            es.addEventListener(name, () => {\n                /* heartbeat — keep socket alive */\n            });\n        }\n\n        es.onerror = (event) => {\n            onError?.(event);\n            es.close();\n            source = null;\n            setStatus(\"closed\");\n            scheduleReconnect();\n        };\n    }\n\n    function close(): void {\n        closed = true;\n        if (retryTimer) {\n            clearTimeout(retryTimer);\n            retryTimer = null;\n        }\n        retries = 0;\n        if (source) {\n            source.close();\n            source = 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        close,\n        reconnect,\n        get status() {\n            return status;\n        },\n    };\n}\n"],"mappings":";;AAkGA,SAAgB,EACZ,GACA,IAAuC,CAAC,GACnB;CACrB,IAAM,EACF,qBAAkB,IAClB,iBAAc,CAAC,GACf,qBAAkB,CAAC,MAAM,GACzB,gBAAa,IACb,oBAAiB,KACjB,gBAAa,KACb,WACA,WACA,cACA,YACA,iBACA,WACA,sBACA,sBACA,GAEA,IAA6B,MAC7B,IAAmD,MACnD,IAAU,GACV,IAA4B,QAC5B,IAAS;CAEb,SAAS,EAAU,GAA+B;EAC1C,MAAW,MACf,IAAS,GACT,IAAiB,CAAI;CACzB;CAEA,SAAS,EAAK,GAAmB,GAA2B;EACxD,IAAI,EAAgB,SAAS,CAAS,GAAG;EACzC,IAAM,IAAU,EACZ,OAAO,EAAM,QAAS,WAAW,EAAM,OAAO,IAC9C,qBACA;GAAE;GAAQ;GAAc;GAAQ;EAAkB,CACtD;EACK,EAAQ,aACb,IAAY;GACR,OAAO;GACP,MAAM,EAAQ;GACd,IAAI,EAAM,eAAe,KAAA;GACzB,KAAK;EACT,CAAC;CACL;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;EAEZ,AADI,KAAQ,EAAO,MAAM,GACzB,EAAU,YAAY;EAEtB,IAAM,IAAK,IAAI,YAAY,GAAK,EAAE,mBAAgB,CAAC;EASnD,AARA,IAAS,GAET,EAAG,eAAe;GAGd,AAFA,IAAU,GACV,EAAU,MAAM,GAChB,IAAS;EACb,GAEA,EAAG,aAAa,MAAU,EAAK,WAAW,CAAK;EAC/C,KAAK,IAAM,KAAQ,GACf,EAAG,iBAAiB,IAAO,MAAU,EAAK,GAAM,CAAqB,CAAC;EAE1E,KAAK,IAAM,KAAQ,GACf,EAAG,iBAAiB,SAAY,CAEhC,CAAC;EAGL,EAAG,WAAW,MAAU;GAKpB,AAJA,IAAU,CAAK,GACf,EAAG,MAAM,GACT,IAAS,MACT,EAAU,QAAQ,GAClB,EAAkB;EACtB;CACJ;CAEA,SAAS,IAAc;EAWnB,AAVA,IAAS,IACT,AAEI,OADA,aAAa,CAAU,GACV,OAEjB,IAAU,GACV,AAEI,OADA,EAAO,MAAM,GACJ,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,IAAI,SAAS;GACT,OAAO;EACX;CACJ;AACJ"}

package/dist/sse/use-event-stream.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-event-stream.cjs","names":[],"sources":["../../src/sse/use-event-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { useLatestRef } from \"@/hooks/use-latest-ref\";\nimport {\n    createEventStream,\n    type CreateEventStreamOptions,\n    type EventStreamMessage,\n    type EventStreamStatus,\n} from \"./create-event-stream\";\n\nexport interface UseEventStreamOptions<T> extends Omit<\n    CreateEventStreamOptions<T>,\n    \"onStatusChange\"\n> {\n    /** When false, the stream is not opened. Useful for \"wait for auth\". Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseEventStreamResult<T> {\n    status: EventStreamStatus;\n    /** Last message received (excluding heartbeats). */\n    lastMessage: EventStreamMessage<T> | null;\n    /** Force a reconnect. */\n    reconnect: () => void;\n}\n\n/**\n * React hook wrapper around {@link createEventStream}. Connection lifecycle is\n * tied to the component (and the `url`/`enabled` dependencies); the stream\n * closes on unmount.\n *\n * @example\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     enabled: !!user,\n *     withCredentials: true,\n *     onMessage: ({ data }) => addNotification(data),\n * });\n */\nexport function useEventStream<T = unknown>(\n    url: string,\n    options: UseEventStreamOptions<T> = {},\n): UseEventStreamResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<EventStreamStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<EventStreamMessage<T> | null>(null);\n    const reconnectRef = useRef<(() => void) | null>(null);\n\n    const onMessageRef = useLatestRef(onMessage);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createEventStream<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        reconnectRef.current = controller.reconnect;\n\n        return () => {\n            controller.close();\n            reconnectRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    return {\n        status,\n        lastMessage,\n        reconnect: () => reconnectRef.current?.(),\n    };\n}\n"],"mappings":"6GAqCA,SAAgB,EACZ,EACA,EAAoC,CAAC,EACd,CACvB,GAAM,CAAE,UAAU,GAAM,YAAW,GAAG,GAAS,EACzC,CAAC,EAAQ,IAAA,EAAa,EAAA,SAAA,CAA4B,MAAM,EACxD,CAAC,EAAa,IAAA,EAAkB,EAAA,SAAA,CAAuC,IAAI,EAC3E,GAAA,EAAe,EAAA,OAAA,CAA4B,IAAI,EAE/C,EAAe,EAAA,aAAa,CAAS,EAyB3C,OAvBA,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,CAAC,EAAK,CAClB,EAAU,MAAM,EAChB,MACJ,CAEA,IAAM,EAAa,EAAA,kBAAqB,EAAK,CACzC,GAAG,EACH,eAAgB,EAChB,UAAY,GAAY,CACpB,EAAe,CAAO,EACtB,EAAa,UAAU,CAAO,CAClC,CACJ,CAAC,EAGD,MAFA,GAAa,QAAU,EAAW,cAErB,CACT,EAAW,MAAM,EACjB,EAAa,QAAU,IAC3B,CAEJ,EAAG,CAAC,EAAK,CAAO,CAAC,EAEV,CACH,SACA,cACA,cAAiB,EAAa,UAAU,CAC5C,CACJ"}
+{"version":3,"file":"use-event-stream.cjs","names":[],"sources":["../../src/sse/use-event-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { useLatestRef } from \"@/hooks/use-latest-ref\";\nimport {\n    createEventStream,\n    type CreateEventStreamOptions,\n    type EventStreamMessage,\n    type EventStreamStatus,\n} from \"./create-event-stream\";\n\nexport interface UseEventStreamOptions<T> extends Omit<\n    CreateEventStreamOptions<T>,\n    \"onStatusChange\"\n> {\n    /** When false, the stream is not opened. Useful for \"wait for auth\". Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseEventStreamResult<T> {\n    status: EventStreamStatus;\n    /** Last message received (excluding heartbeats). */\n    lastMessage: EventStreamMessage<T> | null;\n    /** Force a reconnect. */\n    reconnect: () => void;\n}\n\n/**\n * React hook wrapper around {@link createEventStream}. Connection lifecycle is\n * tied to the component (and the `url`/`enabled` dependencies); the stream\n * closes on unmount.\n *\n * Pass `schema` to have every frame validated before it reaches `onMessage`,\n * instead of trusting the type argument: without it `data` is announced as `T`\n * on the strength of the generic alone, which is a promise about the server\n * that TypeScript cannot keep. It is read when the stream opens, so declare it\n * outside the component rather than building one inline per render.\n *\n * @example\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     enabled: !!user,\n *     withCredentials: true,\n *     onMessage: ({ data }) => addNotification(data),\n * });\n *\n * @example\n * // Validated: a frame that does not match never reaches `onMessage`\n * const notificationSchema = z.object({ id: z.string(), message: z.string() });\n *\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     schema: notificationSchema,\n *     onValidationError: (issues) => logger.warn(\"stream drift\", { issues }),\n *     onMessage: ({ data }) => addNotification(data),\n * });\n */\nexport function useEventStream<T = unknown>(\n    url: string,\n    options: UseEventStreamOptions<T> = {},\n): UseEventStreamResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<EventStreamStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<EventStreamMessage<T> | null>(null);\n    const reconnectRef = useRef<(() => void) | null>(null);\n\n    const onMessageRef = useLatestRef(onMessage);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createEventStream<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        reconnectRef.current = controller.reconnect;\n\n        return () => {\n            controller.close();\n            reconnectRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    return {\n        status,\n        lastMessage,\n        reconnect: () => reconnectRef.current?.(),\n    };\n}\n"],"mappings":"6GAqDA,SAAgB,EACZ,EACA,EAAoC,CAAC,EACd,CACvB,GAAM,CAAE,UAAU,GAAM,YAAW,GAAG,GAAS,EACzC,CAAC,EAAQ,IAAA,EAAa,EAAA,SAAA,CAA4B,MAAM,EACxD,CAAC,EAAa,IAAA,EAAkB,EAAA,SAAA,CAAuC,IAAI,EAC3E,GAAA,EAAe,EAAA,OAAA,CAA4B,IAAI,EAE/C,EAAe,EAAA,aAAa,CAAS,EAyB3C,OAvBA,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,CAAC,EAAK,CAClB,EAAU,MAAM,EAChB,MACJ,CAEA,IAAM,EAAa,EAAA,kBAAqB,EAAK,CACzC,GAAG,EACH,eAAgB,EAChB,UAAY,GAAY,CACpB,EAAe,CAAO,EACtB,EAAa,UAAU,CAAO,CAClC,CACJ,CAAC,EAGD,MAFA,GAAa,QAAU,EAAW,cAErB,CACT,EAAW,MAAM,EACjB,EAAa,QAAU,IAC3B,CAEJ,EAAG,CAAC,EAAK,CAAO,CAAC,EAEV,CACH,SACA,cACA,cAAiB,EAAa,UAAU,CAC5C,CACJ"}

package/dist/sse/use-event-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-event-stream.js","names":[],"sources":["../../src/sse/use-event-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { useLatestRef } from \"@/hooks/use-latest-ref\";\nimport {\n    createEventStream,\n    type CreateEventStreamOptions,\n    type EventStreamMessage,\n    type EventStreamStatus,\n} from \"./create-event-stream\";\n\nexport interface UseEventStreamOptions<T> extends Omit<\n    CreateEventStreamOptions<T>,\n    \"onStatusChange\"\n> {\n    /** When false, the stream is not opened. Useful for \"wait for auth\". Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseEventStreamResult<T> {\n    status: EventStreamStatus;\n    /** Last message received (excluding heartbeats). */\n    lastMessage: EventStreamMessage<T> | null;\n    /** Force a reconnect. */\n    reconnect: () => void;\n}\n\n/**\n * React hook wrapper around {@link createEventStream}. Connection lifecycle is\n * tied to the component (and the `url`/`enabled` dependencies); the stream\n * closes on unmount.\n *\n * @example\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     enabled: !!user,\n *     withCredentials: true,\n *     onMessage: ({ data }) => addNotification(data),\n * });\n */\nexport function useEventStream<T = unknown>(\n    url: string,\n    options: UseEventStreamOptions<T> = {},\n): UseEventStreamResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<EventStreamStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<EventStreamMessage<T> | null>(null);\n    const reconnectRef = useRef<(() => void) | null>(null);\n\n    const onMessageRef = useLatestRef(onMessage);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createEventStream<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        reconnectRef.current = controller.reconnect;\n\n        return () => {\n            controller.close();\n            reconnectRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    return {\n        status,\n        lastMessage,\n        reconnect: () => reconnectRef.current?.(),\n    };\n}\n"],"mappings":";;;;AAqCA,SAAgB,EACZ,GACA,IAAoC,CAAC,GACd;CACvB,IAAM,EAAE,aAAU,IAAM,cAAW,GAAG,MAAS,GACzC,CAAC,GAAQ,KAAa,EAA4B,MAAM,GACxD,CAAC,GAAa,KAAkB,EAAuC,IAAI,GAC3E,IAAe,EAA4B,IAAI,GAE/C,IAAe,EAAa,CAAS;CAyB3C,OAvBA,QAAgB;EACZ,IAAI,CAAC,KAAW,CAAC,GAAK;GAClB,EAAU,MAAM;GAChB;EACJ;EAEA,IAAM,IAAa,EAAqB,GAAK;GACzC,GAAG;GACH,gBAAgB;GAChB,YAAY,MAAY;IAEpB,AADA,EAAe,CAAO,GACtB,EAAa,UAAU,CAAO;GAClC;EACJ,CAAC;EAGD,OAFA,EAAa,UAAU,EAAW,iBAErB;GAET,AADA,EAAW,MAAM,GACjB,EAAa,UAAU;EAC3B;CAEJ,GAAG,CAAC,GAAK,CAAO,CAAC,GAEV;EACH;EACA;EACA,iBAAiB,EAAa,UAAU;CAC5C;AACJ"}
+{"version":3,"file":"use-event-stream.js","names":[],"sources":["../../src/sse/use-event-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { useLatestRef } from \"@/hooks/use-latest-ref\";\nimport {\n    createEventStream,\n    type CreateEventStreamOptions,\n    type EventStreamMessage,\n    type EventStreamStatus,\n} from \"./create-event-stream\";\n\nexport interface UseEventStreamOptions<T> extends Omit<\n    CreateEventStreamOptions<T>,\n    \"onStatusChange\"\n> {\n    /** When false, the stream is not opened. Useful for \"wait for auth\". Default: true. */\n    enabled?: boolean;\n}\n\nexport interface UseEventStreamResult<T> {\n    status: EventStreamStatus;\n    /** Last message received (excluding heartbeats). */\n    lastMessage: EventStreamMessage<T> | null;\n    /** Force a reconnect. */\n    reconnect: () => void;\n}\n\n/**\n * React hook wrapper around {@link createEventStream}. Connection lifecycle is\n * tied to the component (and the `url`/`enabled` dependencies); the stream\n * closes on unmount.\n *\n * Pass `schema` to have every frame validated before it reaches `onMessage`,\n * instead of trusting the type argument: without it `data` is announced as `T`\n * on the strength of the generic alone, which is a promise about the server\n * that TypeScript cannot keep. It is read when the stream opens, so declare it\n * outside the component rather than building one inline per render.\n *\n * @example\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     enabled: !!user,\n *     withCredentials: true,\n *     onMessage: ({ data }) => addNotification(data),\n * });\n *\n * @example\n * // Validated: a frame that does not match never reaches `onMessage`\n * const notificationSchema = z.object({ id: z.string(), message: z.string() });\n *\n * useEventStream<Notification>(`${API}/notifications/stream`, {\n *     schema: notificationSchema,\n *     onValidationError: (issues) => logger.warn(\"stream drift\", { issues }),\n *     onMessage: ({ data }) => addNotification(data),\n * });\n */\nexport function useEventStream<T = unknown>(\n    url: string,\n    options: UseEventStreamOptions<T> = {},\n): UseEventStreamResult<T> {\n    const { enabled = true, onMessage, ...rest } = options;\n    const [status, setStatus] = useState<EventStreamStatus>(\"idle\");\n    const [lastMessage, setLastMessage] = useState<EventStreamMessage<T> | null>(null);\n    const reconnectRef = useRef<(() => void) | null>(null);\n\n    const onMessageRef = useLatestRef(onMessage);\n\n    useEffect(() => {\n        if (!enabled || !url) {\n            setStatus(\"idle\");\n            return;\n        }\n\n        const controller = createEventStream<T>(url, {\n            ...rest,\n            onStatusChange: setStatus,\n            onMessage: (message) => {\n                setLastMessage(message);\n                onMessageRef.current?.(message);\n            },\n        });\n        reconnectRef.current = controller.reconnect;\n\n        return () => {\n            controller.close();\n            reconnectRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [url, enabled]);\n\n    return {\n        status,\n        lastMessage,\n        reconnect: () => reconnectRef.current?.(),\n    };\n}\n"],"mappings":";;;;AAqDA,SAAgB,EACZ,GACA,IAAoC,CAAC,GACd;CACvB,IAAM,EAAE,aAAU,IAAM,cAAW,GAAG,MAAS,GACzC,CAAC,GAAQ,KAAa,EAA4B,MAAM,GACxD,CAAC,GAAa,KAAkB,EAAuC,IAAI,GAC3E,IAAe,EAA4B,IAAI,GAE/C,IAAe,EAAa,CAAS;CAyB3C,OAvBA,QAAgB;EACZ,IAAI,CAAC,KAAW,CAAC,GAAK;GAClB,EAAU,MAAM;GAChB;EACJ;EAEA,IAAM,IAAa,EAAqB,GAAK;GACzC,GAAG;GACH,gBAAgB;GAChB,YAAY,MAAY;IAEpB,AADA,EAAe,CAAO,GACtB,EAAa,UAAU,CAAO;GAClC;EACJ,CAAC;EAGD,OAFA,EAAa,UAAU,EAAW,iBAErB;GAET,AADA,EAAW,MAAM,GACjB,EAAa,UAAU;EAC3B;CAEJ,GAAG,CAAC,GAAK,CAAO,CAAC,GAEV;EACH;EACA;EACA,iBAAiB,EAAa,UAAU;CAC5C;AACJ"}

package/dist/tempest-react-sdk.d.ts

@@ -3236,6 +3236,34 @@ export declare interface CreateEventStreamOptions<T> {
      * kept, with a one-time warning in development builds.
      */
     onParseError?: (error: unknown, raw: string) => void;
+    /**
+     * Schema every decoded frame must satisfy, from zod, valibot, arktype or
+     * anything else exposing `~standard` or `.safeParse`.
+     *
+     * Without it nothing changes: the payload reaches `onMessage` announced as
+     * `T` on the strength of the type argument alone, which is a promise about
+     * the server that TypeScript cannot keep. With it, a frame that does not
+     * match is **not** delivered — the same rule `onParseError` already follows —
+     * and `onValidationError` hears why. The value delivered is the schema's
+     * output, so coercions and defaults are honoured.
+     *
+     * When `parser` is also supplied, it decodes first and the schema validates
+     * what it returned.
+     *
+     * The validation must be synchronous. A frame is decoded inside the
+     * `message` handler and delivered from it, so an async schema would deliver
+     * frames in whatever order their validations settled; that case is reported
+     * through `onValidationError` instead of awaited.
+     */
+    schema?: SchemaLike<T>;
+    /**
+     * A frame was decoded but the `schema` refused it, so it was dropped.
+     *
+     * The one signal that does not depend on how the app's bundler resolves
+     * `process`: the one-time development warning behind `onParseError` needs
+     * `isDevBuild()` to be able to answer, and this callback is the app's own.
+     */
+    onValidationError?: (issues: SchemaIssue[], raw: string) => void;
     onOpen?: () => void;
     onMessage?: (message: EventStreamMessage<T>) => void;
     onError?: (error: Event) => void;
@@ -4420,6 +4448,37 @@ export declare interface CreateWebSocketOptions<T> {
      * kept, with a one-time warning in development builds.
      */
     onParseError?: (error: unknown, raw: string) => void;
+    /**
+     * Schema every decoded frame must satisfy, from zod, valibot, arktype or
+     * anything else exposing `~standard` or `.safeParse`.
+     *
+     * Without it nothing changes: the payload reaches `onMessage` announced as
+     * `T` on the strength of the type argument alone, which is a promise about
+     * the server that TypeScript cannot keep. With it, a frame that does not
+     * match is **not** delivered — the same rule `onParseError` already follows —
+     * and `onValidationError` hears why. The value delivered is the schema's
+     * output, so coercions and defaults are honoured.
+     *
+     * When `parser` is also supplied, it decodes first and the schema validates
+     * what it returned.
+     *
+     * A server ping is still answered when the schema drops it: the heartbeat is
+     * the transport's contract with the server, not the app's with its payload,
+     * and a socket that stops sending `pong` is closed with `4408` once per
+     * timeout. The validation itself must be synchronous — a frame is decoded
+     * inside the `message` handler and delivered from it, so an async schema
+     * would deliver frames in whatever order their validations settled; that
+     * case is reported through `onValidationError` instead of awaited.
+     */
+    schema?: SchemaLike<T>;
+    /**
+     * A frame was decoded but the `schema` refused it, so it was dropped.
+     *
+     * The one signal that does not depend on how the app's bundler resolves
+     * `process`: the one-time development warning behind `onParseError` needs
+     * `isDevBuild()` to be able to answer, and this callback is the app's own.
+     */
+    onValidationError?: (issues: SchemaIssue[], raw: string) => void;
     onOpen?: (event: Event) => void;
     onMessage?: (message: WebSocketMessage<T>) => void;
     onClose?: (event: CloseEvent) => void;
@@ -5732,7 +5791,7 @@ export declare interface EventStreamController {
 export declare interface EventStreamMessage<T> {
     /** Server-named event (default `"message"`). */
     event: string;
-    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */
+    /** Parsed payload — validated when `schema` is set, JSON-decoded when possible, raw string otherwise. */
     data: T;
     /** Server-supplied id, if any. */
     id?: string;
@@ -7454,6 +7513,11 @@ export declare function isStandalone(): boolean;
  */
 export declare function isString(value: unknown): value is string;
 
+/** A path segment as Standard Schema reports it: a key, or an object holding one. */
+declare type IssuePathSegment = PropertyKey | {
+    readonly key: PropertyKey;
+};
+
 /** True when `value` is a finite latitude in `[-90, 90]`. */
 export declare function isValidLatitude(value: number): boolean;
 
@@ -10882,6 +10946,12 @@ export declare interface RatingStarsProps {
     className?: string;
 }
 
+/** One issue as either supported shape reports it. */
+declare interface RawIssue {
+    readonly message: string;
+    readonly path?: readonly IssuePathSegment[] | undefined;
+}
+
 /**
  * Pick the readable foreground for a background, by contrast ratio.
  *
@@ -11617,6 +11687,19 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/** A schema exposing zod's `.safeParse`, including versions older than `~standard`. */
+export declare interface SafeParseSchemaLike<T> {
+    readonly safeParse: (value: unknown) => {
+        readonly success: true;
+        readonly data: T;
+    } | {
+        readonly success: false;
+        readonly error: {
+            readonly issues: readonly RawIssue[];
+        };
+    };
+}
+
 /**
  * Divide the video caps by the size of the room.
  *
@@ -11720,6 +11803,36 @@ export declare interface SchedulerProps extends Omit<HTMLAttributes<HTMLDivEleme
     now?: Date;
 }
 
+/**
+ * The SDK's answer to "the caller handed me a schema" — one normalizer behind
+ * every option that takes one.
+ *
+ * Internal, and imported by path rather than through the `utils` barrel: the
+ * function exists so `decodeFrame` and anything else that validates a payload
+ * share one reading of the two shapes below, not so consumers can call it. The
+ * types are public, because an option typed `SchemaLike<T>` is a name the
+ * consumer has to be able to write down.
+ *
+ * Two shapes are accepted on purpose:
+ *
+ * - [Standard Schema](https://standardschema.dev) (`~standard`), which zod
+ *   (>=3.24), valibot and arktype all implement, so the SDK validates against
+ *   any of them without depending on one;
+ * - `.safeParse`, because the SDK's own zod range starts at `^3.23.0`, which
+ *   predates `~standard`, and because it is the method every zod user already
+ *   knows.
+ */
+/** One field-level complaint from a schema validation. */
+export declare interface SchemaIssue {
+    /** Dotted path to the offending field, or `"<root>"` for the value itself. */
+    path: string;
+    /** What the validator said was wrong. */
+    message: string;
+}
+
+/** Anything the SDK can validate a payload against. */
+export declare type SchemaLike<T> = StandardSchemaLike<T> | SafeParseSchemaLike<T>;
+
 /** Lifecycle of a screen share. */
 export declare type ScreenCaptureStatus = "idle" | "requesting" | "sharing" | "error";
 
@@ -11912,13 +12025,13 @@ export declare function setAudioOutput(element: HTMLMediaElement | null, sinkId:
  * the SDK routes through it — `grep -rn "dev-mode" src/` for the current list,
  * which an enumeration written here would only drift away from.
  *
- * {@link setDevBuild} is public, because the environment the SDK cannot read is
- * the one it most needs to: a Vite app. See its doc for why.
+ * {@link setDevBuild} is public, because a context nothing compiles cannot be
+ * detected from the inside. See its doc for when that is.
  */
 /**
  * Tell the SDK whether the app around it was built for development.
  *
- * Call it once, at bootstrap, from a build the SDK cannot inspect:
+ * Call it once, at bootstrap, from a context {@link isDevBuild} cannot read:
  *
  * ```ts
  * import { setDevBuild } from "tempest-react-sdk";
@@ -11926,20 +12039,29 @@ export declare function setAudioOutput(element: HTMLMediaElement | null, sinkId:
  * setDevBuild(import.meta.env.DEV);
  * ```
  *
- * **Why the SDK cannot work this out on its own in a Vite app.** The automatic
- * detection reads `process.env.NODE_ENV`, which webpack, Rspack and Parcel
- * replace with a literal while building the *app*. Vite replaces neither half:
- * `process` is not defined in a browser bundle, so the read throws and the
- * answer is `false` — including under `vite dev`. Its own signal,
- * `import.meta.env.DEV`, cannot be used here either, because Vite would replace
- * it while building *this package* and the published artifact would ship the
- * constant. Only the app is compiled at the moment the answer is knowable, so
- * only the app can supply it.
- *
- * The default stays `false` on purpose. `parseResponse` puts the raw response
- * payload in its message when this is on, so a wrong guess in the other
- * direction leaks a payload into a production error string. Silence is the safe
- * default; the report is one line away for anyone who wants it.
+ * **When you need it.** Not for an ordinary Vite, webpack, Rspack or Parcel
+ * app: all of them substitute `process.env.NODE_ENV` while building the app, so
+ * the automatic read already answers correctly there — measured for Vite 5
+ * through 8 in {@link isDevBuild}, whose doc carries the table. What is left is
+ * the context nothing compiles or nothing configures:
+ *
+ * - code no bundler transformed — a raw service-worker script registered as a
+ *   file of its own, a plain `<script type="module">`;
+ * - a staging or QA build that never sets `NODE_ENV=production`, where the
+ *   automatic answer is `true` and `parseResponse` would put the raw response
+ *   payload in an error string seen by real users. `setDevBuild(false)` closes
+ *   that;
+ * - a test that wants the other branch, and puts it back on the way out.
+ *
+ * `import.meta.env.DEV` cannot be read by the SDK on your behalf, which is why
+ * the signal is a parameter: Vite would replace it while building *this
+ * package*, and the published artifact would ship the constant.
+ *
+ * The default stays `false` when the read throws. `parseResponse` puts the raw
+ * response payload in its message when this is on, so guessing `true` in a
+ * context that cannot prove it leaks a payload into a production error string.
+ * Silence is the safe default; the report is one line away for anyone who wants
+ * it.
  *
  * Passing `undefined` clears the override and returns to automatic detection,
  * which is what a test that set it should do on the way out.
@@ -11948,8 +12070,8 @@ export declare function setAudioOutput(element: HTMLMediaElement | null, sinkId:
  *     `undefined` to go back to detecting it.
  *
  * @example
- * // Vite — the case this exists for
- * setDevBuild(import.meta.env.DEV);
+ * // A service worker, or any context no bundler transformed
+ * setDevBuild(false);
  *
  * @example
  * // A test that flips it, and puts it back
@@ -12621,6 +12743,23 @@ export declare const STALE_TIME: {
     readonly INFINITE: number;
 };
 
+/** A schema exposing the [Standard Schema](https://standardschema.dev) interface. */
+export declare interface StandardSchemaLike<T> {
+    readonly "~standard": {
+        readonly validate: (value: unknown) => {
+            readonly value: T;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: readonly RawIssue[];
+        } | Promise<{
+            readonly value: T;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: readonly RawIssue[];
+        }>;
+    };
+}
+
 /**
  * KPI card. Dashboard widget showing a label + big value + optional
  * delta/trend and hint.
@@ -14648,12 +14787,28 @@ export declare function useEventListener<K extends keyof HTMLElementEventMap>(ev
  * tied to the component (and the `url`/`enabled` dependencies); the stream
  * closes on unmount.
  *
+ * Pass `schema` to have every frame validated before it reaches `onMessage`,
+ * instead of trusting the type argument: without it `data` is announced as `T`
+ * on the strength of the generic alone, which is a promise about the server
+ * that TypeScript cannot keep. It is read when the stream opens, so declare it
+ * outside the component rather than building one inline per render.
+ *
  * @example
  * useEventStream<Notification>(`${API}/notifications/stream`, {
  *     enabled: !!user,
  *     withCredentials: true,
  *     onMessage: ({ data }) => addNotification(data),
  * });
+ *
+ * @example
+ * // Validated: a frame that does not match never reaches `onMessage`
+ * const notificationSchema = z.object({ id: z.string(), message: z.string() });
+ *
+ * useEventStream<Notification>(`${API}/notifications/stream`, {
+ *     schema: notificationSchema,
+ *     onValidationError: (issues) => logger.warn("stream drift", { issues }),
+ *     onMessage: ({ data }) => addNotification(data),
+ * });
  */
 export declare function useEventStream<T = unknown>(url: string, options?: UseEventStreamOptions<T>): UseEventStreamResult<T>;
 
@@ -16803,6 +16958,10 @@ export { useWatch }
  * baked into the connection, so changing one reopens it with the new value
  * rather than being silently ignored.
  *
+ * `schema` is read when the socket opens, so declare it outside the component
+ * (or memoize it): a schema built inline is a new object on every render, and
+ * the one in force is whichever existed at the last open.
+ *
  * @param url - Full ws:// or wss:// URL.
  * @param options - Connection configuration and callbacks.
  * @returns Status, last frame, and the `send` / `reconnect` controls.
@@ -17717,7 +17876,7 @@ export declare interface WebSocketController {
 export declare type WebSocketLostReason = "rejected" | "exhausted";
 
 export declare interface WebSocketMessage<T> {
-    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */
+    /** Parsed payload — validated when `schema` is set, JSON-decoded when possible, raw string otherwise. */
     data: T;
     /** The original `MessageEvent`. */
     raw: MessageEvent;