@0k/kal-sse-client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# @0k/kal-sse-client
+
+[![](https://img.shields.io/npm/v/@0k/kal-sse-client.svg)](https://www.npmjs.com/package/@0k/kal-sse-client)
+
+## Overview
+
+A kal-sse data channel pairs a REST snapshot with an SSE stream. The
+snapshot registers or refreshes the subscription, the server owns its
+`sub` id, and each stream event carries an SSE `id:`. On reconnect, the
+client can send the last applied event id so the server can replay from
+that point.
+
+`@0k/kal-sse-client` owns the `EventSource` lifecycle, reconnect
+backoff, snapshot registration, and resume-first recovery. Your
+application owns endpoint paths, URL resolution, parsing event payloads,
+and rendering or otherwise updating application state. It supports
+Chrome 91 and later.
+
+## Installation
+
+``` bash
+npm install @0k/kal-sse-client
+```
+
+## Usage
+
+### Snapshot and cursor channel
+
+Use `createSnapshotCursorSse` for the usual kal-sse data channel: fetch
+a snapshot, render it, then apply changes from its SSE stream.
+
+``` ts
+import { createSnapshotCursorSse } from "@0k/kal-sse-client";
+
+type Archive = { items: Array<{ id: string; title: string }> };
+type ArchiveChange = { id: string; title: string };
+
+const archive = createSnapshotCursorSse<Archive>({
+  snapshotPath: "/api/archive",
+  streamPath: "/api/archive/events",
+  applySnapshot: (snapshot) => renderArchive(snapshot),
+  onMessage: (event) => applyArchiveChange(JSON.parse(event.data) as ArchiveChange),
+});
+
+await archive.start();
+
+// Later, for example when the view is disposed:
+archive.stop();
+```
+
+`start()` begins the snapshot request and returns one shared promise.
+That promise resolves when the first snapshot succeeds, or when its
+first attempt fails. Later snapshot retries continue in the background,
+so a resolved promise does not by itself mean a stream is already open.
+
+The snapshot response must provide a non-empty `x-sub-id` header. For a
+cross-origin snapshot endpoint, expose it to browser JavaScript with
+`Access-Control-Expose-Headers: x-sub-id`. Once the client knows this
+id, each later snapshot request adds `?sub=<id>` (or `&sub=<id>` when
+the path already has a query string). The stream URL always appends
+`sub=<id>` as a query parameter.
+
+### Plain SSE endpoint
+
+Use `createResilientSse` when the endpoint is not a snapshot cursor
+channel. By default it calls `onBeforeReconnect` before every reconnect,
+which is a place to refetch application state.
+
+``` ts
+import { createResilientSse } from "@0k/kal-sse-client";
+
+const notifications = createResilientSse({
+  url: () => "/api/notifications/events",
+  onMessage: (event) => showNotification(JSON.parse(event.data)),
+  onBeforeReconnect: async () => {
+    const response = await fetch("/api/notifications");
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    replaceNotifications(await response.json());
+  },
+});
+
+notifications.start();
+// Later:
+notifications.stop();
+```
+
+## Reconnection behavior
+
+The first reconnect attempt opens immediately. After that, reconnect
+delay starts at 250 ms, doubles after each attempt, and is capped at 30
+s. A delivered event starts a 5 s healthy timer; when that timer
+elapses, the retry delay resets. Keep-alive comments do not count as
+delivered events and never reset the delay.
+
+`createSnapshotCursorSse` always resumes first, using its `sub` id and
+the last applied `last_event_id`. `createResilientSse` does this only
+when `resumeFromLastEventId: true`. An event id is remembered only after
+the relevant message callback returns normally.
+
+The client fetches a fresh snapshot if no event was applied since the
+last snapshot, or if a resume attempt fails before the stream opens.
+This is deliberately conservative: `EventSource` does not expose the
+HTTP response status, so `409 needs_snapshot` cannot be distinguished
+from other HTTP errors such as a proxy's `502`. A network drop differs:
+the browser retries with `readyState` set to `CONNECTING`. The client
+nevertheless treats any resume attempt that fails before opening the
+same way. While snapshot recovery is pending, the last successfully
+applied snapshot stays rendered.
+
+This resume protocol needs a `kal-sse` server version 0.2 or later,
+which accepts `last_event_id`. With a 0.1 server, typical Axum handlers
+ignore that unknown query parameter, so the connection silently falls
+back to the server cursor instead of client-directed replay.
+
+## Option reference
+
+### `createResilientSse(options)`
+
+| Option                  | Type                                            | Default  | Meaning                                                                                                                                       |
+|-------------------------|-------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `url`                   | `() => string`                                  | Required | Returns the SSE URL for each new connection.                                                                                                  |
+| `onMessage`             | `(event: MessageEvent) => void`                 | Required | Handles unnamed SSE messages. A non-empty event id is remembered only after this callback returns when resume is enabled.                     |
+| `onEvents`              | `Record<string, (event: MessageEvent) => void>` | None     | Handles named SSE events. Use custom event names only, never the reserved names `open`, `error`, or `message`.                                |
+| `onBeforeReconnect`     | `() => void \| Promise<void>`                   | None     | Runs before a non-resume reconnect. Use it to refetch state for a plain SSE endpoint. A rejected promise is retried with the reconnect delay. |
+| `resumeFromLastEventId` | `boolean`                                       | `false`  | When true, reconnect after an applied id and an opened stream with `last_event_id=<id>` appended as a query parameter.                        |
+| `onError`               | `() => void`                                    | None     | Runs when the current `EventSource` reports an error, before reconnect scheduling. Exceptions from this notification are swallowed.           |
+| `initialDelayMs`        | `number`                                        | `250`    | First delayed reconnect interval in milliseconds. The first reconnect attempt itself is immediate.                                            |
+| `maxDelayMs`            | `number`                                        | `30000`  | Maximum reconnect interval in milliseconds.                                                                                                   |
+| `healthyWindowMs`       | `number`                                        | `5000`   | Milliseconds after a delivered event before the reconnect delay resets.                                                                       |
+
+### `createSnapshotCursorSse<S>(options)`
+
+| Option                   | Type                            | Default  | Meaning                                                                                                                                                                |
+|--------------------------|---------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `snapshotPath`           | `string`                        | Required | Snapshot endpoint path. After receiving a subscription id, later requests add `sub`.                                                                                   |
+| `streamPath`             | `string`                        | Required | SSE endpoint path. The client adds the server-owned `sub` id.                                                                                                          |
+| `resolveUrl`             | `(path: string) => string`      | Identity | Resolves endpoint paths, for example below a reverse-proxy prefix. It is used for both snapshot fetches and stream URLs.                                               |
+| `applySnapshot`          | `(body: S) => void`             | Required | Applies a successful snapshot after its non-empty `x-sub-id` header is read.                                                                                           |
+| `onMessage`              | `(event: MessageEvent) => void` | Required | Handles stream messages. Parse the event payload and update state here.                                                                                                |
+| `retrySnapshotAfter`     | `(body: S) => number \| null`   | None     | Returns a non-negative delay in milliseconds to retry this otherwise successful snapshot without applying it. Return `null` or no value to apply it.                   |
+| `onSnapshotError`        | `(reason: unknown) => void`     | None     | Receives failed snapshot fetch, HTTP, header, JSON, callback, or retry-delay validation errors before snapshot retry. Exceptions from this notification are swallowed. |
+| `onStreamError`          | `() => void`                    | None     | Receives errors reported by the underlying stream before its reconnect logic runs. Exceptions from this notification are swallowed.                                    |
+| `initialSnapshotRetryMs` | `number`                        | `250`    | First retry delay for a failed snapshot in milliseconds.                                                                                                               |
+| `maxSnapshotRetryMs`     | `number`                        | `30000`  | Maximum snapshot retry delay in milliseconds.                                                                                                                          |
+
+## Development
+
+Run the checks separately when working on the package:
+
+``` bash
+npm test
+npm run typecheck
+npm run build
+```
+
+For a local consumer, run `npm link` in this repository, then run
+`npm link @0k/kal-sse-client` in the consumer repository. The release
+process generates `README.md` from this file; do not commit that
+generated file.
+
+## License
+
+MIT, see `LICENSE`.
+
+
+## Changelog
+
+
+### 0.2.0 (2026-10-10)
+
+#### New
+
+* Publish on npm instead of a vendored tarball. [Valentin Lab]
+
+  Consumers depended on a tarball committed into each of their
+  repositories and refreshed by ``scripts/vendor.mjs``. The package is now
+  released to npm as ``@0k/kal-sse-client`` with ``pkg`` (version from the
+  git tag, ``%%version%%`` in ``package.json``); consumers depend on the
+  published version and use ``npm link`` against this checkout locally.
+  ``README.md`` is generated from ``README.org`` at release, with an npm
+  badge and an install section.
+
+  Contract:
+  - ``@0k/kal-sse-client`` is a public npm package (no ``private`` flag,
+    ``publishConfig.access`` is ``public``); its version is the release
+    tag, substituted for ``%%version%%`` in ``package.json`` and
+    ``package-lock.json``.
+  - The package ships ``dist``, ``README.md`` and ``LICENSE``; ``prepack``
+    builds ``dist`` first. Entry points and exports are unchanged.
+  - ``npm run vendor`` and ``scripts/vendor.mjs`` are removed: nothing is
+    packed into or installed from a consumer's repository any more.
+  - No runtime change and no automated test: packaging only.
+
+* Resume a dropped stream from the last applied event instead of re-snapshotting. [Valentin Lab]
+
+  The server cursor of a ``kal-sse`` channel advances when the server hands
+  an event to its HTTP stack, so after a silent disconnect it can be ahead
+  of what the client applied: resuming from it lost events. Re-taking the
+  snapshot on every reconnect avoided that, at the cost of a full snapshot
+  per network blip.
+
+  ``createSnapshotCursorSse`` now remembers the ``id`` of the last applied
+  event and reconnects with ``last_event_id``, which ``kal-sse`` 0.2 replays
+  from. It re-takes the snapshot only when no event was applied since the
+  last one, or when the resume attempt fails before opening (an
+  ``EventSource`` hides the HTTP status, so a ``409`` looks like that).
+
+  ``createResilientSse`` gains the opt-in ``resumeFromLastEventId`` option
+  behind this; without it nothing changes.
+
+  Contract:
+  - ``createSnapshotCursorSse`` always resumes first; ``createResilientSse``
+    resumes only with ``resumeFromLastEventId: true`` and otherwise still
+    runs ``onBeforeReconnect`` before every reconnect.
+  - An event id is remembered only once its ``onMessage`` or ``onEvents``
+    callback has returned normally; an empty id never replaces it.
+  - After a stream that opened, with a remembered id, the reconnect URL
+    gets ``last_event_id=<id>`` (URL-encoded) and ``onBeforeReconnect`` is
+    skipped: a snapshot channel fetches no snapshot.
+  - With no remembered id, or when a resume fails before opening, the id is
+    forgotten and ``onBeforeReconnect`` runs: a snapshot channel re-takes
+    its snapshot, adopts the new ``x-sub-id``, and keeps showing the last
+    applied snapshot until then.
+  - Resume keeps the bounded backoff, the healthy-window reset, and the
+    cancellation on ``stop()``.
+  - Tests: ``test/resilient.test.ts``, ``test/snapshot-cursor.test.ts``.
+
+* Live-update client that reconnects and resumes without gaps. [Valentin Lab]
+
+  Wraps the ``kal-sse`` snapshot and server-owned cursor contract: bounded
+  reconnect backoff, and a fresh snapshot before every reconnect so no
+  update is lost while the last applied snapshot stays visible.
+
+#### Changes
+
+* Document usage, reconnection and every option in the README. [Valentin Lab]
+
+  The README described the package's internal acceptance ledger instead of
+  how to use it. It now gives usage examples for both channel kinds, the
+  exact reconnection and resume behavior, a reference table of every
+  option (including the ``x-sub-id`` header a snapshot must expose), the
+  server requirement and browser support. The acceptance ledger is gone.
+
+#### Fix
+
+* Keep reconnecting when a notification callback throws, and wait once per retry. [Valentin Lab]
+
+  - A host ``onError`` or ``onStreamError`` that threw skipped the
+    reconnect, and a throwing ``onSnapshotError`` left ``start()`` unresolved
+    and stopped the snapshot retries: recovery ended for good.
+  - When ``onBeforeReconnect`` rejected, the retry timer waited the backoff
+    delay and ``reconnect`` then waited it again, so retries were spaced
+    twice the documented delay (up to 60 s with defaults).
+
+  Contract:
+  - Exceptions thrown by ``onError``, ``onStreamError`` and ``onSnapshotError``
+    are swallowed; reconnection and snapshot retries continue.
+  - After a rejected ``onBeforeReconnect``, the next attempt starts after one
+    backoff delay; the delay doubles up to ``maxDelayMs``; ``stop()`` cancels.
+  - Tests: ``test/resilient.test.ts``, ``test/snapshot-cursor.test.ts``.
+
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/README.org

@@ -0,0 +1,159 @@
+#+TITLE: @0k/kal-sse-client
+
+[[https://www.npmjs.com/package/@0k/kal-sse-client][https://img.shields.io/npm/v/@0k/kal-sse-client.svg]]
+
+* Overview
+
+A kal-sse data channel pairs a REST snapshot with an SSE stream. The snapshot
+registers or refreshes the subscription, the server owns its ~sub~ id, and each
+stream event carries an SSE ~id:~. On reconnect, the client can send the last
+applied event id so the server can replay from that point.
+
+=@0k/kal-sse-client= owns the =EventSource= lifecycle, reconnect backoff,
+snapshot registration, and resume-first recovery. Your application owns endpoint
+paths, URL resolution, parsing event payloads, and rendering or otherwise
+updating application state. It supports Chrome 91 and later.
+
+* Installation
+
+#+begin_src sh
+npm install @0k/kal-sse-client
+#+end_src
+
+* Usage
+
+** Snapshot and cursor channel
+
+Use =createSnapshotCursorSse= for the usual kal-sse data channel: fetch a
+snapshot, render it, then apply changes from its SSE stream.
+
+#+begin_src ts
+import { createSnapshotCursorSse } from "@0k/kal-sse-client";
+
+type Archive = { items: Array<{ id: string; title: string }> };
+type ArchiveChange = { id: string; title: string };
+
+const archive = createSnapshotCursorSse<Archive>({
+  snapshotPath: "/api/archive",
+  streamPath: "/api/archive/events",
+  applySnapshot: (snapshot) => renderArchive(snapshot),
+  onMessage: (event) => applyArchiveChange(JSON.parse(event.data) as ArchiveChange),
+});
+
+await archive.start();
+
+// Later, for example when the view is disposed:
+archive.stop();
+#+end_src
+
+=start()= begins the snapshot request and returns one shared promise. That
+promise resolves when the first snapshot succeeds, or when its first attempt
+fails. Later snapshot retries continue in the background, so a resolved promise
+does not by itself mean a stream is already open.
+
+The snapshot response must provide a non-empty =x-sub-id= header. For a
+cross-origin snapshot endpoint, expose it to browser JavaScript with
+=Access-Control-Expose-Headers: x-sub-id=. Once the client knows this id, each
+later snapshot request adds ~?sub=<id>~ (or ~&sub=<id>~ when the path already
+has a query string). The stream URL always appends ~sub=<id>~ as a query
+parameter.
+
+** Plain SSE endpoint
+
+Use =createResilientSse= when the endpoint is not a snapshot cursor channel.
+By default it calls =onBeforeReconnect= before every reconnect, which is a
+place to refetch application state.
+
+#+begin_src ts
+import { createResilientSse } from "@0k/kal-sse-client";
+
+const notifications = createResilientSse({
+  url: () => "/api/notifications/events",
+  onMessage: (event) => showNotification(JSON.parse(event.data)),
+  onBeforeReconnect: async () => {
+    const response = await fetch("/api/notifications");
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    replaceNotifications(await response.json());
+  },
+});
+
+notifications.start();
+// Later:
+notifications.stop();
+#+end_src
+
+* Reconnection behavior
+
+The first reconnect attempt opens immediately. After that, reconnect delay
+starts at 250 ms, doubles after each attempt, and is capped at 30 s. A delivered
+event starts a 5 s healthy timer; when that timer elapses, the retry delay
+resets. Keep-alive comments do not count as delivered events and never reset
+the delay.
+
+=createSnapshotCursorSse= always resumes first, using its =sub= id and the
+last applied =last_event_id=. =createResilientSse= does this only when
+=resumeFromLastEventId: true=. An event id is remembered only after the relevant
+message callback returns normally.
+
+The client fetches a fresh snapshot if no event was applied since the last
+snapshot, or if a resume attempt fails before the stream opens. This is
+deliberately conservative: =EventSource= does not expose the HTTP response
+status, so =409 needs_snapshot= cannot be distinguished from other HTTP errors
+such as a proxy's =502=. A network drop differs: the browser retries with
+~readyState~ set to ~CONNECTING~. The client nevertheless treats any resume
+attempt that fails before opening the same way. While snapshot recovery is
+pending, the last successfully applied snapshot stays rendered.
+
+This resume protocol needs a =kal-sse= server version 0.2 or later, which
+accepts =last_event_id=. With a 0.1 server, typical Axum handlers ignore that
+unknown query parameter, so the connection silently falls back to the server
+cursor instead of client-directed replay.
+
+* Option reference
+
+** =createResilientSse(options)=
+
+| Option | Type | Default | Meaning |
+|-
+| ~url~ | ~() => string~ | Required | Returns the SSE URL for each new connection. |
+| ~onMessage~ | ~(event: MessageEvent) => void~ | Required | Handles unnamed SSE messages. A non-empty event id is remembered only after this callback returns when resume is enabled. |
+| ~onEvents~ | ~Record<string, (event: MessageEvent) => void>~ | None | Handles named SSE events. Use custom event names only, never the reserved names ~open~, ~error~, or ~message~. |
+| ~onBeforeReconnect~ | ~() => void \| Promise<void>~ | None | Runs before a non-resume reconnect. Use it to refetch state for a plain SSE endpoint. A rejected promise is retried with the reconnect delay. |
+| ~resumeFromLastEventId~ | ~boolean~ | ~false~ | When true, reconnect after an applied id and an opened stream with ~last_event_id=<id>~ appended as a query parameter. |
+| ~onError~ | ~() => void~ | None | Runs when the current =EventSource= reports an error, before reconnect scheduling. Exceptions from this notification are swallowed. |
+| ~initialDelayMs~ | ~number~ | ~250~ | First delayed reconnect interval in milliseconds. The first reconnect attempt itself is immediate. |
+| ~maxDelayMs~ | ~number~ | ~30000~ | Maximum reconnect interval in milliseconds. |
+| ~healthyWindowMs~ | ~number~ | ~5000~ | Milliseconds after a delivered event before the reconnect delay resets. |
+
+** =createSnapshotCursorSse<S>(options)=
+
+| Option | Type | Default | Meaning |
+|-
+| ~snapshotPath~ | ~string~ | Required | Snapshot endpoint path. After receiving a subscription id, later requests add =sub=. |
+| ~streamPath~ | ~string~ | Required | SSE endpoint path. The client adds the server-owned =sub= id. |
+| ~resolveUrl~ | ~(path: string) => string~ | Identity | Resolves endpoint paths, for example below a reverse-proxy prefix. It is used for both snapshot fetches and stream URLs. |
+| ~applySnapshot~ | ~(body: S) => void~ | Required | Applies a successful snapshot after its non-empty =x-sub-id= header is read. |
+| ~onMessage~ | ~(event: MessageEvent) => void~ | Required | Handles stream messages. Parse the event payload and update state here. |
+| ~retrySnapshotAfter~ | ~(body: S) => number \| null~ | None | Returns a non-negative delay in milliseconds to retry this otherwise successful snapshot without applying it. Return ~null~ or no value to apply it. |
+| ~onSnapshotError~ | ~(reason: unknown) => void~ | None | Receives failed snapshot fetch, HTTP, header, JSON, callback, or retry-delay validation errors before snapshot retry. Exceptions from this notification are swallowed. |
+| ~onStreamError~ | ~() => void~ | None | Receives errors reported by the underlying stream before its reconnect logic runs. Exceptions from this notification are swallowed. |
+| ~initialSnapshotRetryMs~ | ~number~ | ~250~ | First retry delay for a failed snapshot in milliseconds. |
+| ~maxSnapshotRetryMs~ | ~number~ | ~30000~ | Maximum snapshot retry delay in milliseconds. |
+
+* Development
+
+Run the checks separately when working on the package:
+
+#+begin_src sh
+npm test
+npm run typecheck
+npm run build
+#+end_src
+
+For a local consumer, run ~npm link~ in this repository, then run
+~npm link @0k/kal-sse-client~ in the consumer repository. The release process
+generates ~README.md~ from this file; do not commit that generated file.
+
+* License
+
+MIT, see ~LICENSE~.

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function M(e){const y=e.initialDelayMs??250,c=e.maxDelayMs??3e4,S=e.healthyWindowMs??5e3;let a=null,t=0,r=null,o=null,l=null,d=!1,v=!1,n=!1,u=null,w=!1;function E(){a?.close(),a=null,o!==null&&clearTimeout(o),o=null}function f(m,i){n||(w=!0,t>0&&o===null&&(o=setTimeout(()=>{t=0,o=null},S)),m(i),e.resumeFromLastEventId&&i.lastEventId&&(u=i.lastEventId))}function b(m=!1){if(n)return;E(),w=!1;const i=e.url();a=new EventSource(m?g(i,"last_event_id",u):i),e.resumeFromLastEventId&&(a.onopen=()=>{w=!0}),a.onmessage=s=>f(e.onMessage,s),a.onerror=()=>{if(!n){try{e.onError?.()}catch{}h()}};for(const[s,T]of Object.entries(e.onEvents??{}))a.addEventListener(s,I=>f(T,I))}async function h(m=!0){if(d||n)return;d=!0;const i=!!(e.resumeFromLastEventId&&u!==null&&w);E();try{if(m&&t>0&&await new Promise(s=>{l=s,r=setTimeout(()=>{r=null,l=null,s()},t)}),n)return;t=Math.min(t===0?y:t*2,c),i||(u=null,await e.onBeforeReconnect?.()),n||b(i)}catch{if(!n){r=setTimeout(()=>{r=null,d=!1,h(!1)},t);return}}finally{(r===null||l!==null)&&(d=!1)}}return{start(){v||n||(v=!0,b())},stop(){n||(n=!0,E(),r!==null&&clearTimeout(r),r=null,l?.(),l=null)}}}function g(e,y,c){return`${e}${e.includes("?")?"&":"?"}${y}=${encodeURIComponent(c)}`}function p(e){const y=e.resolveUrl??(n=>n);let c=null,S=null,a=null,t=null,r=null,o=null,l=!1;function d(n){return new Promise(u=>{r=u,t=setTimeout(()=>{t=null,r=null,u()},n)})}async function v(n){let u=e.initialSnapshotRetryMs??250;const w=e.maxSnapshotRetryMs??3e4;let E=!1;for(;!l;){const f=new AbortController;a=f;try{const b=c===null?e.snapshotPath:g(e.snapshotPath,"sub",c),h=await fetch(y(b),{signal:f.signal});if(!h.ok)throw new Error(`HTTP ${h.status}`);const m=await h.json(),i=h.headers.get("x-sub-id")?.trim();if(!i)throw new Error("Snapshot response missing non-empty x-sub-id");const s=e.retrySnapshotAfter?.(m)??null;if(s!==null){if(!Number.isFinite(s)||s<0)throw new Error("Invalid snapshot retry delay");await d(s);continue}if(l||f.signal.aborted)return;c=i,e.applySnapshot(m);return}catch(b){if(l||f.signal.aborted)return;try{e.onSnapshotError?.(b)}catch{}E||n?.(),E=!0,await d(u),u=Math.min(u*2,w)}finally{a===f&&(a=null)}}}return{start(){return o!==null?o:l?Promise.resolve():(o=new Promise(n=>{(async()=>(await v(n),!l&&c!==null&&(S=M({url:()=>y(g(e.streamPath,"sub",c)),onMessage:e.onMessage,resumeFromLastEventId:!0,...e.onStreamError?{onError:e.onStreamError}:{},onBeforeReconnect:()=>v()}),S.start()),n()))()}),o)},stop(){l||(l=!0,a?.abort(),S?.stop(),t!==null&&clearTimeout(t),t=null,r?.(),r=null)}}}exports.createResilientSse=M;exports.createSnapshotCursorSse=p;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["export interface ResilientSseOptions {\n  url: () => string;\n  onMessage: (event: MessageEvent) => void;\n  onEvents?: Record<string, (event: MessageEvent) => void>;\n  onBeforeReconnect?: () => void | Promise<void>;\n  resumeFromLastEventId?: boolean;\n  onError?: () => void;\n  initialDelayMs?: number;\n  maxDelayMs?: number;\n  healthyWindowMs?: number;\n}\n\nexport interface ResilientSseSubscription {\n  start(): void;\n  stop(): void;\n}\n\nexport function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription {\n  const initial = opts.initialDelayMs ?? 250;\n  const maximum = opts.maxDelayMs ?? 30_000;\n  const healthyWindow = opts.healthyWindowMs ?? 5_000;\n  let source: EventSource | null = null;\n  let delay = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let healthyTimer: ReturnType<typeof setTimeout> | null = null;\n  let wake: (() => void) | null = null;\n  let running = false;\n  let started = false;\n  let stopped = false;\n  let lastEventId: string | null = null;\n  let opened = false;\n\n  function close(): void {\n    source?.close();\n    source = null;\n    if (healthyTimer !== null) clearTimeout(healthyTimer);\n    healthyTimer = null;\n  }\n\n  function receive(callback: (event: MessageEvent) => void, event: MessageEvent): void {\n    if (stopped) return;\n    opened = true;\n    if (delay > 0 && healthyTimer === null) {\n      healthyTimer = setTimeout(() => {\n        delay = 0;\n        healthyTimer = null;\n      }, healthyWindow);\n    }\n    callback(event);\n    if (opts.resumeFromLastEventId && event.lastEventId) lastEventId = event.lastEventId;\n  }\n\n  function open(resume = false): void {\n    if (stopped) return;\n    close();\n    opened = false;\n    const url = opts.url();\n    source = new EventSource(resume ? joinQuery(url, \"last_event_id\", lastEventId!) : url);\n    if (opts.resumeFromLastEventId) source.onopen = () => { opened = true; };\n    source.onmessage = (event) => receive(opts.onMessage, event);\n    source.onerror = () => {\n      if (stopped) return;\n      try {\n        opts.onError?.();\n      } catch {\n        // Notification failures must not interrupt recovery.\n      }\n      void reconnect();\n    };\n    for (const [name, callback] of Object.entries(opts.onEvents ?? {})) {\n      source.addEventListener(name, (event) => receive(callback, event as MessageEvent));\n    }\n  }\n\n  async function reconnect(waitBeforeAttempt = true): Promise<void> {\n    if (running || stopped) return;\n    running = true;\n    const resume = Boolean(opts.resumeFromLastEventId && lastEventId !== null && opened);\n    close();\n    try {\n      if (waitBeforeAttempt && delay > 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n          timer = setTimeout(() => {\n            timer = null;\n            wake = null;\n            resolve();\n          }, delay);\n        });\n      }\n      if (stopped) return;\n      delay = Math.min(delay === 0 ? initial : delay * 2, maximum);\n      if (!resume) {\n        lastEventId = null;\n        await opts.onBeforeReconnect?.();\n      }\n      if (!stopped) open(resume);\n    } catch {\n      if (!stopped) {\n        timer = setTimeout(() => {\n          timer = null;\n          running = false;\n          void reconnect(false);\n        }, delay);\n        return;\n      }\n    } finally {\n      if (timer === null || wake !== null) running = false;\n    }\n  }\n\n  return {\n    start(): void {\n      if (started || stopped) return;\n      started = true;\n      open();\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      close();\n      if (timer !== null) clearTimeout(timer);\n      timer = null;\n      wake?.();\n      wake = null;\n    },\n  };\n}\n\nexport interface SnapshotCursorSseOptions<S> {\n  snapshotPath: string;\n  streamPath: string;\n  resolveUrl?: (path: string) => string;\n  applySnapshot: (body: S) => void;\n  onMessage: (event: MessageEvent) => void;\n  retrySnapshotAfter?: (body: S) => number | null;\n  onSnapshotError?: (reason: unknown) => void;\n  onStreamError?: () => void;\n  initialSnapshotRetryMs?: number;\n  maxSnapshotRetryMs?: number;\n}\n\nexport interface SnapshotCursorSseChannel {\n  start(): Promise<void>;\n  stop(): void;\n}\n\nfunction joinQuery(path: string, key: string, value: string): string {\n  return `${path}${path.includes(\"?\") ? \"&\" : \"?\"}${key}=${encodeURIComponent(value)}`;\n}\n\nexport function createSnapshotCursorSse<S>(opts: SnapshotCursorSseOptions<S>): SnapshotCursorSseChannel {\n  const resolveUrl = opts.resolveUrl ?? ((path: string) => path);\n  let subId: string | null = null;\n  let subscription: ResilientSseSubscription | null = null;\n  let controller: AbortController | null = null;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let wake: (() => void) | null = null;\n  let started: Promise<void> | null = null;\n  let stopped = false;\n\n  function wait(milliseconds: number): Promise<void> {\n    return new Promise<void>((resolve) => {\n      wake = resolve;\n      timer = setTimeout(() => {\n        timer = null;\n        wake = null;\n        resolve();\n      }, milliseconds);\n    });\n  }\n\n  async function snapshot(onFirstFailure?: () => void): Promise<void> {\n    let delay = opts.initialSnapshotRetryMs ?? 250;\n    const maxDelay = opts.maxSnapshotRetryMs ?? 30_000;\n    let failed = false;\n    while (!stopped) {\n      const abort = new AbortController();\n      controller = abort;\n      try {\n        const path = subId === null ? opts.snapshotPath : joinQuery(opts.snapshotPath, \"sub\", subId);\n        const response = await fetch(resolveUrl(path), { signal: abort.signal });\n        if (!response.ok) throw new Error(`HTTP ${response.status}`);\n        const body = (await response.json()) as S;\n        const id = response.headers.get(\"x-sub-id\")?.trim();\n        if (!id) throw new Error(\"Snapshot response missing non-empty x-sub-id\");\n        const retry = opts.retrySnapshotAfter?.(body) ?? null;\n        if (retry !== null) {\n          if (!Number.isFinite(retry) || retry < 0) throw new Error(\"Invalid snapshot retry delay\");\n          await wait(retry);\n          continue;\n        }\n        if (stopped || abort.signal.aborted) return;\n        subId = id;\n        opts.applySnapshot(body);\n        return;\n      } catch (reason) {\n        if (stopped || abort.signal.aborted) return;\n        try {\n          opts.onSnapshotError?.(reason);\n        } catch {\n          // Notification failures must not interrupt recovery.\n        }\n        if (!failed) onFirstFailure?.();\n        failed = true;\n        await wait(delay);\n        delay = Math.min(delay * 2, maxDelay);\n      } finally {\n        if (controller === abort) controller = null;\n      }\n    }\n  }\n\n  return {\n    start(): Promise<void> {\n      if (started !== null) return started;\n      if (stopped) return Promise.resolve();\n      started = new Promise<void>((resolve) => {\n        void (async () => {\n          await snapshot(resolve);\n          if (!stopped && subId !== null) {\n            subscription = createResilientSse({\n              url: () => resolveUrl(joinQuery(opts.streamPath, \"sub\", subId!)),\n              onMessage: opts.onMessage,\n              resumeFromLastEventId: true,\n              ...(opts.onStreamError ? { onError: opts.onStreamError } : {}),\n              onBeforeReconnect: () => snapshot(),\n            });\n            subscription.start();\n          }\n          resolve();\n        })();\n      });\n      return started;\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      controller?.abort();\n      subscription?.stop();\n      if (timer !== null) clearTimeout(timer);\n      timer = null;\n      wake?.();\n      wake = null;\n    },\n  };\n}\n"],"names":["createResilientSse","opts","initial","maximum","healthyWindow","source","delay","timer","healthyTimer","wake","running","started","stopped","lastEventId","opened","close","receive","callback","event","open","resume","url","joinQuery","reconnect","name","waitBeforeAttempt","resolve","path","key","value","createSnapshotCursorSse","resolveUrl","subId","subscription","controller","wait","milliseconds","snapshot","onFirstFailure","maxDelay","failed","abort","response","body","id","retry","reason"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export interface ResilientSseOptions {
+    url: () => string;
+    onMessage: (event: MessageEvent) => void;
+    onEvents?: Record<string, (event: MessageEvent) => void>;
+    onBeforeReconnect?: () => void | Promise<void>;
+    resumeFromLastEventId?: boolean;
+    onError?: () => void;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    healthyWindowMs?: number;
+}
+export interface ResilientSseSubscription {
+    start(): void;
+    stop(): void;
+}
+export declare function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription;
+export interface SnapshotCursorSseOptions<S> {
+    snapshotPath: string;
+    streamPath: string;
+    resolveUrl?: (path: string) => string;
+    applySnapshot: (body: S) => void;
+    onMessage: (event: MessageEvent) => void;
+    retrySnapshotAfter?: (body: S) => number | null;
+    onSnapshotError?: (reason: unknown) => void;
+    onStreamError?: () => void;
+    initialSnapshotRetryMs?: number;
+    maxSnapshotRetryMs?: number;
+}
+export interface SnapshotCursorSseChannel {
+    start(): Promise<void>;
+    stop(): void;
+}
+export declare function createSnapshotCursorSse<S>(opts: SnapshotCursorSseOptions<S>): SnapshotCursorSseChannel;

package/dist/index.js

@@ -0,0 +1,129 @@
+function T(e) {
+  const y = e.initialDelayMs ?? 250, c = e.maxDelayMs ?? 3e4, v = e.healthyWindowMs ?? 5e3;
+  let a = null, t = 0, r = null, u = null, l = null, d = !1, S = !1, n = !1, o = null, w = !1;
+  function E() {
+    a?.close(), a = null, u !== null && clearTimeout(u), u = null;
+  }
+  function f(m, i) {
+    n || (w = !0, t > 0 && u === null && (u = setTimeout(() => {
+      t = 0, u = null;
+    }, v)), m(i), e.resumeFromLastEventId && i.lastEventId && (o = i.lastEventId));
+  }
+  function b(m = !1) {
+    if (n) return;
+    E(), w = !1;
+    const i = e.url();
+    a = new EventSource(m ? g(i, "last_event_id", o) : i), e.resumeFromLastEventId && (a.onopen = () => {
+      w = !0;
+    }), a.onmessage = (s) => f(e.onMessage, s), a.onerror = () => {
+      if (!n) {
+        try {
+          e.onError?.();
+        } catch {
+        }
+        h();
+      }
+    };
+    for (const [s, I] of Object.entries(e.onEvents ?? {}))
+      a.addEventListener(s, (M) => f(I, M));
+  }
+  async function h(m = !0) {
+    if (d || n) return;
+    d = !0;
+    const i = !!(e.resumeFromLastEventId && o !== null && w);
+    E();
+    try {
+      if (m && t > 0 && await new Promise((s) => {
+        l = s, r = setTimeout(() => {
+          r = null, l = null, s();
+        }, t);
+      }), n) return;
+      t = Math.min(t === 0 ? y : t * 2, c), i || (o = null, await e.onBeforeReconnect?.()), n || b(i);
+    } catch {
+      if (!n) {
+        r = setTimeout(() => {
+          r = null, d = !1, h(!1);
+        }, t);
+        return;
+      }
+    } finally {
+      (r === null || l !== null) && (d = !1);
+    }
+  }
+  return {
+    start() {
+      S || n || (S = !0, b());
+    },
+    stop() {
+      n || (n = !0, E(), r !== null && clearTimeout(r), r = null, l?.(), l = null);
+    }
+  };
+}
+function g(e, y, c) {
+  return `${e}${e.includes("?") ? "&" : "?"}${y}=${encodeURIComponent(c)}`;
+}
+function p(e) {
+  const y = e.resolveUrl ?? ((n) => n);
+  let c = null, v = null, a = null, t = null, r = null, u = null, l = !1;
+  function d(n) {
+    return new Promise((o) => {
+      r = o, t = setTimeout(() => {
+        t = null, r = null, o();
+      }, n);
+    });
+  }
+  async function S(n) {
+    let o = e.initialSnapshotRetryMs ?? 250;
+    const w = e.maxSnapshotRetryMs ?? 3e4;
+    let E = !1;
+    for (; !l; ) {
+      const f = new AbortController();
+      a = f;
+      try {
+        const b = c === null ? e.snapshotPath : g(e.snapshotPath, "sub", c), h = await fetch(y(b), { signal: f.signal });
+        if (!h.ok) throw new Error(`HTTP ${h.status}`);
+        const m = await h.json(), i = h.headers.get("x-sub-id")?.trim();
+        if (!i) throw new Error("Snapshot response missing non-empty x-sub-id");
+        const s = e.retrySnapshotAfter?.(m) ?? null;
+        if (s !== null) {
+          if (!Number.isFinite(s) || s < 0) throw new Error("Invalid snapshot retry delay");
+          await d(s);
+          continue;
+        }
+        if (l || f.signal.aborted) return;
+        c = i, e.applySnapshot(m);
+        return;
+      } catch (b) {
+        if (l || f.signal.aborted) return;
+        try {
+          e.onSnapshotError?.(b);
+        } catch {
+        }
+        E || n?.(), E = !0, await d(o), o = Math.min(o * 2, w);
+      } finally {
+        a === f && (a = null);
+      }
+    }
+  }
+  return {
+    start() {
+      return u !== null ? u : l ? Promise.resolve() : (u = new Promise((n) => {
+        (async () => (await S(n), !l && c !== null && (v = T({
+          url: () => y(g(e.streamPath, "sub", c)),
+          onMessage: e.onMessage,
+          resumeFromLastEventId: !0,
+          ...e.onStreamError ? { onError: e.onStreamError } : {},
+          onBeforeReconnect: () => S()
+        }), v.start()), n()))();
+      }), u);
+    },
+    stop() {
+      l || (l = !0, a?.abort(), v?.stop(), t !== null && clearTimeout(t), t = null, r?.(), r = null);
+    }
+  };
+}
+export {
+  T as createResilientSse,
+  p as createSnapshotCursorSse
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["export interface ResilientSseOptions {\n  url: () => string;\n  onMessage: (event: MessageEvent) => void;\n  onEvents?: Record<string, (event: MessageEvent) => void>;\n  onBeforeReconnect?: () => void | Promise<void>;\n  resumeFromLastEventId?: boolean;\n  onError?: () => void;\n  initialDelayMs?: number;\n  maxDelayMs?: number;\n  healthyWindowMs?: number;\n}\n\nexport interface ResilientSseSubscription {\n  start(): void;\n  stop(): void;\n}\n\nexport function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription {\n  const initial = opts.initialDelayMs ?? 250;\n  const maximum = opts.maxDelayMs ?? 30_000;\n  const healthyWindow = opts.healthyWindowMs ?? 5_000;\n  let source: EventSource | null = null;\n  let delay = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let healthyTimer: ReturnType<typeof setTimeout> | null = null;\n  let wake: (() => void) | null = null;\n  let running = false;\n  let started = false;\n  let stopped = false;\n  let lastEventId: string | null = null;\n  let opened = false;\n\n  function close(): void {\n    source?.close();\n    source = null;\n    if (healthyTimer !== null) clearTimeout(healthyTimer);\n    healthyTimer = null;\n  }\n\n  function receive(callback: (event: MessageEvent) => void, event: MessageEvent): void {\n    if (stopped) return;\n    opened = true;\n    if (delay > 0 && healthyTimer === null) {\n      healthyTimer = setTimeout(() => {\n        delay = 0;\n        healthyTimer = null;\n      }, healthyWindow);\n    }\n    callback(event);\n    if (opts.resumeFromLastEventId && event.lastEventId) lastEventId = event.lastEventId;\n  }\n\n  function open(resume = false): void {\n    if (stopped) return;\n    close();\n    opened = false;\n    const url = opts.url();\n    source = new EventSource(resume ? joinQuery(url, \"last_event_id\", lastEventId!) : url);\n    if (opts.resumeFromLastEventId) source.onopen = () => { opened = true; };\n    source.onmessage = (event) => receive(opts.onMessage, event);\n    source.onerror = () => {\n      if (stopped) return;\n      try {\n        opts.onError?.();\n      } catch {\n        // Notification failures must not interrupt recovery.\n      }\n      void reconnect();\n    };\n    for (const [name, callback] of Object.entries(opts.onEvents ?? {})) {\n      source.addEventListener(name, (event) => receive(callback, event as MessageEvent));\n    }\n  }\n\n  async function reconnect(waitBeforeAttempt = true): Promise<void> {\n    if (running || stopped) return;\n    running = true;\n    const resume = Boolean(opts.resumeFromLastEventId && lastEventId !== null && opened);\n    close();\n    try {\n      if (waitBeforeAttempt && delay > 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n          timer = setTimeout(() => {\n            timer = null;\n            wake = null;\n            resolve();\n          }, delay);\n        });\n      }\n      if (stopped) return;\n      delay = Math.min(delay === 0 ? initial : delay * 2, maximum);\n      if (!resume) {\n        lastEventId = null;\n        await opts.onBeforeReconnect?.();\n      }\n      if (!stopped) open(resume);\n    } catch {\n      if (!stopped) {\n        timer = setTimeout(() => {\n          timer = null;\n          running = false;\n          void reconnect(false);\n        }, delay);\n        return;\n      }\n    } finally {\n      if (timer === null || wake !== null) running = false;\n    }\n  }\n\n  return {\n    start(): void {\n      if (started || stopped) return;\n      started = true;\n      open();\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      close();\n      if (timer !== null) clearTimeout(timer);\n      timer = null;\n      wake?.();\n      wake = null;\n    },\n  };\n}\n\nexport interface SnapshotCursorSseOptions<S> {\n  snapshotPath: string;\n  streamPath: string;\n  resolveUrl?: (path: string) => string;\n  applySnapshot: (body: S) => void;\n  onMessage: (event: MessageEvent) => void;\n  retrySnapshotAfter?: (body: S) => number | null;\n  onSnapshotError?: (reason: unknown) => void;\n  onStreamError?: () => void;\n  initialSnapshotRetryMs?: number;\n  maxSnapshotRetryMs?: number;\n}\n\nexport interface SnapshotCursorSseChannel {\n  start(): Promise<void>;\n  stop(): void;\n}\n\nfunction joinQuery(path: string, key: string, value: string): string {\n  return `${path}${path.includes(\"?\") ? \"&\" : \"?\"}${key}=${encodeURIComponent(value)}`;\n}\n\nexport function createSnapshotCursorSse<S>(opts: SnapshotCursorSseOptions<S>): SnapshotCursorSseChannel {\n  const resolveUrl = opts.resolveUrl ?? ((path: string) => path);\n  let subId: string | null = null;\n  let subscription: ResilientSseSubscription | null = null;\n  let controller: AbortController | null = null;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let wake: (() => void) | null = null;\n  let started: Promise<void> | null = null;\n  let stopped = false;\n\n  function wait(milliseconds: number): Promise<void> {\n    return new Promise<void>((resolve) => {\n      wake = resolve;\n      timer = setTimeout(() => {\n        timer = null;\n        wake = null;\n        resolve();\n      }, milliseconds);\n    });\n  }\n\n  async function snapshot(onFirstFailure?: () => void): Promise<void> {\n    let delay = opts.initialSnapshotRetryMs ?? 250;\n    const maxDelay = opts.maxSnapshotRetryMs ?? 30_000;\n    let failed = false;\n    while (!stopped) {\n      const abort = new AbortController();\n      controller = abort;\n      try {\n        const path = subId === null ? opts.snapshotPath : joinQuery(opts.snapshotPath, \"sub\", subId);\n        const response = await fetch(resolveUrl(path), { signal: abort.signal });\n        if (!response.ok) throw new Error(`HTTP ${response.status}`);\n        const body = (await response.json()) as S;\n        const id = response.headers.get(\"x-sub-id\")?.trim();\n        if (!id) throw new Error(\"Snapshot response missing non-empty x-sub-id\");\n        const retry = opts.retrySnapshotAfter?.(body) ?? null;\n        if (retry !== null) {\n          if (!Number.isFinite(retry) || retry < 0) throw new Error(\"Invalid snapshot retry delay\");\n          await wait(retry);\n          continue;\n        }\n        if (stopped || abort.signal.aborted) return;\n        subId = id;\n        opts.applySnapshot(body);\n        return;\n      } catch (reason) {\n        if (stopped || abort.signal.aborted) return;\n        try {\n          opts.onSnapshotError?.(reason);\n        } catch {\n          // Notification failures must not interrupt recovery.\n        }\n        if (!failed) onFirstFailure?.();\n        failed = true;\n        await wait(delay);\n        delay = Math.min(delay * 2, maxDelay);\n      } finally {\n        if (controller === abort) controller = null;\n      }\n    }\n  }\n\n  return {\n    start(): Promise<void> {\n      if (started !== null) return started;\n      if (stopped) return Promise.resolve();\n      started = new Promise<void>((resolve) => {\n        void (async () => {\n          await snapshot(resolve);\n          if (!stopped && subId !== null) {\n            subscription = createResilientSse({\n              url: () => resolveUrl(joinQuery(opts.streamPath, \"sub\", subId!)),\n              onMessage: opts.onMessage,\n              resumeFromLastEventId: true,\n              ...(opts.onStreamError ? { onError: opts.onStreamError } : {}),\n              onBeforeReconnect: () => snapshot(),\n            });\n            subscription.start();\n          }\n          resolve();\n        })();\n      });\n      return started;\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      controller?.abort();\n      subscription?.stop();\n      if (timer !== null) clearTimeout(timer);\n      timer = null;\n      wake?.();\n      wake = null;\n    },\n  };\n}\n"],"names":["createResilientSse","opts","initial","maximum","healthyWindow","source","delay","timer","healthyTimer","wake","running","started","stopped","lastEventId","opened","close","receive","callback","event","open","resume","url","joinQuery","reconnect","name","waitBeforeAttempt","resolve","path","key","value","createSnapshotCursorSse","resolveUrl","subId","subscription","controller","wait","milliseconds","snapshot","onFirstFailure","maxDelay","failed","abort","response","body","id","retry","reason"],"mappings":"AAiBO,SAASA,EAAmBC,GAAqD;AACtF,QAAMC,IAAUD,EAAK,kBAAkB,KACjCE,IAAUF,EAAK,cAAc,KAC7BG,IAAgBH,EAAK,mBAAmB;AAC9C,MAAII,IAA6B,MAC7BC,IAAQ,GACRC,IAA8C,MAC9CC,IAAqD,MACrDC,IAA4B,MAC5BC,IAAU,IACVC,IAAU,IACVC,IAAU,IACVC,IAA6B,MAC7BC,IAAS;AAEb,WAASC,IAAc;AACrB,IAAAV,GAAQ,MAAA,GACRA,IAAS,MACLG,MAAiB,QAAM,aAAaA,CAAY,GACpDA,IAAe;AAAA,EACjB;AAEA,WAASQ,EAAQC,GAAyCC,GAA2B;AACnF,IAAIN,MACJE,IAAS,IACLR,IAAQ,KAAKE,MAAiB,SAChCA,IAAe,WAAW,MAAM;AAC9B,MAAAF,IAAQ,GACRE,IAAe;AAAA,IACjB,GAAGJ,CAAa,IAElBa,EAASC,CAAK,GACVjB,EAAK,yBAAyBiB,EAAM,oBAA2BA,EAAM;AAAA,EAC3E;AAEA,WAASC,EAAKC,IAAS,IAAa;AAClC,QAAIR,EAAS;AACb,IAAAG,EAAA,GACAD,IAAS;AACT,UAAMO,IAAMpB,EAAK,IAAA;AACjB,IAAAI,IAAS,IAAI,YAAYe,IAASE,EAAUD,GAAK,iBAAiBR,CAAY,IAAIQ,CAAG,GACjFpB,EAAK,0BAAuBI,EAAO,SAAS,MAAM;AAAE,MAAAS,IAAS;AAAA,IAAM,IACvET,EAAO,YAAY,CAACa,MAAUF,EAAQf,EAAK,WAAWiB,CAAK,GAC3Db,EAAO,UAAU,MAAM;AACrB,UAAI,CAAAO,GACJ;AAAA,YAAI;AACF,UAAAX,EAAK,UAAA;AAAA,QACP,QAAQ;AAAA,QAER;AACA,QAAKsB,EAAA;AAAA;AAAA,IACP;AACA,eAAW,CAACC,GAAMP,CAAQ,KAAK,OAAO,QAAQhB,EAAK,YAAY,CAAA,CAAE;AAC/D,MAAAI,EAAO,iBAAiBmB,GAAM,CAACN,MAAUF,EAAQC,GAAUC,CAAqB,CAAC;AAAA,EAErF;AAEA,iBAAeK,EAAUE,IAAoB,IAAqB;AAChE,QAAIf,KAAWE,EAAS;AACxB,IAAAF,IAAU;AACV,UAAMU,IAAS,GAAQnB,EAAK,yBAAyBY,MAAgB,QAAQC;AAC7E,IAAAC,EAAA;AACA,QAAI;AAWF,UAVIU,KAAqBnB,IAAQ,KAC/B,MAAM,IAAI,QAAc,CAACoB,MAAY;AACnC,QAAAjB,IAAOiB,GACPnB,IAAQ,WAAW,MAAM;AACvB,UAAAA,IAAQ,MACRE,IAAO,MACPiB,EAAA;AAAA,QACF,GAAGpB,CAAK;AAAA,MACV,CAAC,GAECM,EAAS;AACb,MAAAN,IAAQ,KAAK,IAAIA,MAAU,IAAIJ,IAAUI,IAAQ,GAAGH,CAAO,GACtDiB,MACHP,IAAc,MACd,MAAMZ,EAAK,oBAAA,IAERW,KAASO,EAAKC,CAAM;AAAA,IAC3B,QAAQ;AACN,UAAI,CAACR,GAAS;AACZ,QAAAL,IAAQ,WAAW,MAAM;AACvB,UAAAA,IAAQ,MACRG,IAAU,IACLa,EAAU,EAAK;AAAA,QACtB,GAAGjB,CAAK;AACR;AAAA,MACF;AAAA,IACF,UAAA;AACE,OAAIC,MAAU,QAAQE,MAAS,UAAMC,IAAU;AAAA,IACjD;AAAA,EACF;AAEA,SAAO;AAAA,IACL,QAAc;AACZ,MAAIC,KAAWC,MACfD,IAAU,IACVQ,EAAA;AAAA,IACF;AAAA,IACA,OAAa;AACX,MAAIP,MACJA,IAAU,IACVG,EAAA,GACIR,MAAU,QAAM,aAAaA,CAAK,GACtCA,IAAQ,MACRE,IAAA,GACAA,IAAO;AAAA,IACT;AAAA,EAAA;AAEJ;AAoBA,SAASa,EAAUK,GAAcC,GAAaC,GAAuB;AACnE,SAAO,GAAGF,CAAI,GAAGA,EAAK,SAAS,GAAG,IAAI,MAAM,GAAG,GAAGC,CAAG,IAAI,mBAAmBC,CAAK,CAAC;AACpF;AAEO,SAASC,EAA2B7B,GAA6D;AACtG,QAAM8B,IAAa9B,EAAK,eAAe,CAAC0B,MAAiBA;AACzD,MAAIK,IAAuB,MACvBC,IAAgD,MAChDC,IAAqC,MACrC3B,IAA8C,MAC9CE,IAA4B,MAC5BE,IAAgC,MAChCC,IAAU;AAEd,WAASuB,EAAKC,GAAqC;AACjD,WAAO,IAAI,QAAc,CAACV,MAAY;AACpC,MAAAjB,IAAOiB,GACPnB,IAAQ,WAAW,MAAM;AACvB,QAAAA,IAAQ,MACRE,IAAO,MACPiB,EAAA;AAAA,MACF,GAAGU,CAAY;AAAA,IACjB,CAAC;AAAA,EACH;AAEA,iBAAeC,EAASC,GAA4C;AAClE,QAAIhC,IAAQL,EAAK,0BAA0B;AAC3C,UAAMsC,IAAWtC,EAAK,sBAAsB;AAC5C,QAAIuC,IAAS;AACb,WAAO,CAAC5B,KAAS;AACf,YAAM6B,IAAQ,IAAI,gBAAA;AAClB,MAAAP,IAAaO;AACb,UAAI;AACF,cAAMd,IAAOK,MAAU,OAAO/B,EAAK,eAAeqB,EAAUrB,EAAK,cAAc,OAAO+B,CAAK,GACrFU,IAAW,MAAM,MAAMX,EAAWJ,CAAI,GAAG,EAAE,QAAQc,EAAM,QAAQ;AACvE,YAAI,CAACC,EAAS,GAAI,OAAM,IAAI,MAAM,QAAQA,EAAS,MAAM,EAAE;AAC3D,cAAMC,IAAQ,MAAMD,EAAS,KAAA,GACvBE,IAAKF,EAAS,QAAQ,IAAI,UAAU,GAAG,KAAA;AAC7C,YAAI,CAACE,EAAI,OAAM,IAAI,MAAM,8CAA8C;AACvE,cAAMC,IAAQ5C,EAAK,qBAAqB0C,CAAI,KAAK;AACjD,YAAIE,MAAU,MAAM;AAClB,cAAI,CAAC,OAAO,SAASA,CAAK,KAAKA,IAAQ,EAAG,OAAM,IAAI,MAAM,8BAA8B;AACxF,gBAAMV,EAAKU,CAAK;AAChB;AAAA,QACF;AACA,YAAIjC,KAAW6B,EAAM,OAAO,QAAS;AACrC,QAAAT,IAAQY,GACR3C,EAAK,cAAc0C,CAAI;AACvB;AAAA,MACF,SAASG,GAAQ;AACf,YAAIlC,KAAW6B,EAAM,OAAO,QAAS;AACrC,YAAI;AACF,UAAAxC,EAAK,kBAAkB6C,CAAM;AAAA,QAC/B,QAAQ;AAAA,QAER;AACA,QAAKN,KAAQF,IAAA,GACbE,IAAS,IACT,MAAML,EAAK7B,CAAK,GAChBA,IAAQ,KAAK,IAAIA,IAAQ,GAAGiC,CAAQ;AAAA,MACtC,UAAA;AACE,QAAIL,MAAeO,MAAOP,IAAa;AAAA,MACzC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL,QAAuB;AACrB,aAAIvB,MAAY,OAAaA,IACzBC,IAAgB,QAAQ,QAAA,KAC5BD,IAAU,IAAI,QAAc,CAACe,MAAY;AACvC,SAAM,aACJ,MAAMW,EAASX,CAAO,GAClB,CAACd,KAAWoB,MAAU,SACxBC,IAAejC,EAAmB;AAAA,UAChC,KAAK,MAAM+B,EAAWT,EAAUrB,EAAK,YAAY,OAAO+B,CAAM,CAAC;AAAA,UAC/D,WAAW/B,EAAK;AAAA,UAChB,uBAAuB;AAAA,UACvB,GAAIA,EAAK,gBAAgB,EAAE,SAASA,EAAK,cAAA,IAAkB,CAAA;AAAA,UAC3D,mBAAmB,MAAMoC,EAAA;AAAA,QAAS,CACnC,GACDJ,EAAa,MAAA,IAEfP,EAAA;AAAA,MAEJ,CAAC,GACMf;AAAA,IACT;AAAA,IACA,OAAa;AACX,MAAIC,MACJA,IAAU,IACVsB,GAAY,MAAA,GACZD,GAAc,KAAA,GACV1B,MAAU,QAAM,aAAaA,CAAK,GACtCA,IAAQ,MACRE,IAAA,GACAA,IAAO;AAAA,IACT;AAAA,EAAA;AAEJ;"}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@0k/kal-sse-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Framework-agnostic browser client for kal-sse snapshot and server-owned cursor channels.",
+  "keywords": [
+    "sse",
+    "server-sent-events",
+    "eventsource",
+    "kal-sse",
+    "reconnect",
+    "resume",
+    "snapshot"
+  ],
+  "author": "Valentin Lab <valentin.lab@kalysto.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/0k/kal-sse-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0k/kal-sse-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0k/kal-sse-client/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "check": "npm run test && npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.5",
+    "jsdom": "25.0.1",
+    "typescript": "5.7.3",
+    "vite": "6.4.4",
+    "vitest": "4.1.11"
+  }
+}