@dokebi/sse 0.0.0-stage → 0.4.0

package/AI.md

@@ -0,0 +1,148 @@
+# AI guide — @dokebi/sse 0.4.0
+
+Server-sent events (SSE) for @dokebi/web apps. The server writes events to authenticated streams and, with `eventBus`, sends them through @dokebi/event-bus to the streams of other workers and servers too. The browser client is `./client` of the same package (plus `./client/vue`, `./client/react`, `./client/bundle`). At most once (no ACK, no resending, no retention). Node >=24.0.0, core ^0.4.0, @dokebi/web (required), @dokebi/event-bus (only with `eventBus`), @dokebi/health (check `sse` when present). The decision is [D-0060](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0060-sse.md); the human-oriented description is the [README](README.md).
+
+## 1. Install
+
+```sh
+npx dokebi add @dokebi/sse
+```
+
+> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package `dokebi` is not this CLI, so never use `npx -y dokebi`. Without an installed CLI use `npx -y @dokebi/cli …`.
+
+- With `eventBus` the CLI requires dokebi-event-bus (install module `requires`). Define the bus in `dokebi-event-bus.buses.<name>`. For several workers or servers use `driver: nats`.
+- For a single process, leave out `eventBus` (publish then reaches only this process's streams).
+
+## 2. Options `options.dokebi-sse`
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `eventBus` | string | none | event-bus bus name that carries publications to other processes (named `bus` before 0.4.0, D-0071) |
+| `bus` | string | — | deprecated name of `eventBus`: warns `OPTION_DEPRECATED`; setting both is `INVALID_OPTIONS` |
+| `busEvent` | string | `dokebi.sse` | the bus event name |
+| `allowInCluster` | boolean | `false` | allow starting in a cluster worker without a NATS bus (only for a single worker) |
+| `retryMs` | integer | 3000 | the first `retry:` sent (browser reconnect delay); also the client backoff's minimum |
+| `heartbeatMs` | integer | 15000 | interval of the `: ping` comment. Keep it shorter than the proxy idle limit |
+| `maxConnections` | integer | 1024 | streams per process (worker). Beyond it 503 `CAPACITY` |
+| `maxBufferedBytes` | integer | 1048576 | bytes waiting to be sent on one stream. Beyond it the stream is cut with warn `SLOW_CONSUMER` |
+| `maxRooms` | integer | 32 | rooms per stream |
+| `maxEventBytes` | integer | 65536 | bytes of an event's data (JSON). Keep it below the bus `maxPayloadBytes` |
+| `shutdownTimeoutMs` | integer | 2000 | how long drain waits for streams to end after `dokebi-restart` (named `closeTimeoutMs` before 0.4.0) |
+| `closeTimeoutMs` | integer | — | deprecated name of `shutdownTimeoutMs` (D-0071) |
+
+**Cluster check (`LOCAL_IN_CLUSTER`)**: in a node:cluster worker, the start fails with an error log (with `fix`) when there is no `eventBus` or its driver is not `nats`. The event-bus API does not report the driver, so **the app setting `dokebi-event-bus.buses.<eventBus>.driver` is read (and the old name `transport`)**. When the event-bus options were passed only in code, the driver is unknown (`unknown`) and the start is refused. Move them to the configuration file, or, if there really is only one worker, set `allowInCluster: true`.
+
+## 3. Server API
+
+```ts snippet
+import { createPlugin, dependency, type SseApi } from '@dokebi/sse';
+const sse = context.getDependency(dependency);          // created from this package when missing
+sse.route({
+  path: '/events',                                       // GET only (no HEAD)
+  constraints: { dokebiApp: 'shop' },                    // optional: @dokebi/app domain routing
+  origins: ['https://admin.example.com'],                // optional: allow other origins (CORS + credentials); '*' without credentials
+  version: APP_VERSION,                                  // optional: D-0033
+  authenticate: (request) => ({ tenant, member, rooms: ['r1'] }),  // undefined → 401
+  onOpen: (stream) => { stream.join(`user:${stream.member}`); stream.send('snapshot', data); },
+  onClose: (stream, reason) => {},                       // CLIENT_CLOSED, SERVER_CLOSED, SLOW_CONSUMER, DRAIN, ON_OPEN_FAILED, WRITE_FAILED
+});
+const { id, local } = await sse.publish({ tenant, member, room }, 'order.changed', { id: 42 });  // member and room are optional
+sse.connections({ tenant, room });                       // the count on this worker
+```
+
+- `route` works only in setup (`FROZEN` afterwards). `authenticate` and `onOpen` run on every reconnect.
+- Targets: `{tenant}` everyone, `{tenant, member}` all tabs of one person, `{tenant, room}` a room, `{tenant, room, member}` that person in the room. Strings are 1 to 256 characters.
+- Prefix targets (D-0061): with `tenantPrefix` instead of `tenant` (exactly one of them, otherwise `INVALID_TARGET`), every tenant whose name starts with that prefix (with the same `member` and `room` rules). Bus messages carry the same target, and each process scans its own tenant index once. @dokebi/app's namespaces `<ns>:` use it.
+- Event names: `^[A-Za-z][A-Za-z0-9._:-]{0,63}$`, not starting with `dokebi-` (reserved for the plugin). data is one line of JSON (`undefined` becomes `null`); functions, BigInt and cycles are `INVALID_DATA`.
+- `publish` order: check target, name and data → when the bus is not `ready`, `BUS_UNAVAILABLE` (nothing is sent anywhere, error log) → write to this process's streams → publish on the bus. A failed bus publish is `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`; this process already received it, other places are unknown; the error log has the full error). Whether to send again is the caller's choice (duplicates possible).
+- The sending process skips its own bus messages (`origin`): with a local or a NATS bus, that process's streams receive each event once.
+- `stream.send` writes to one connection only and returns true when written (false when closed or cut for being slow). Events get an `id` that increases in order within this process.
+- Rooms are per connection. After a reconnect they are empty, so join in `authenticate`'s `rooms` or in `onOpen`.
+- `parseOptions` (the options parser) and the API types (`SseApi`, `SseRoute`, `SseStream`, …) are exported too.
+
+## 3a. Mounting on @dokebi/app (D-0061)
+
+```ts snippet
+export default defineApp({
+  events: (app) => [{
+    path: '/events',
+    authenticate: async (request) => {
+      const user = await userOf(request);
+      return user && { tenant: user.shop, member: user.id };   // namespace?: one of the app's list (default the first)
+    },
+    onOpen: (stream) => stream.send('hello', { tenant: stream.tenant }),   // 'front:shop-1'
+  }],
+  async start(app) {
+    await app.realtime().publish({ tenant: 'shop-1' }, 'order.changed', { id: 42 });
+  },
+});
+```
+
+- Streams attach only to the app's domains (constraint `dokebiApp`), with the same module prefix rules as sockets (the module `events` hook, @dokebi/module 0.1.3). The tenant is `<namespace>:<tenant>` (the default namespace is the app name). An authenticated `namespace` outside the app's list gets 401 and warn `NAMESPACE_FORBIDDEN`. app removes `namespace`, so it is not in `stream.identity`.
+- Realtime contribution point `dokebi-web:realtime` (D-0063 §5, `realtime` of `@dokebi/web/points`): in setup this plugin contributes `{ kind: 'sse', mount(route, scope), handle(namespace) }`. `mount` adds `scope.path` and `scope.constraints`, turns the `authenticate` result into `scope.identity` and registers the route; `handle(ns).publish({ tenant?, member?, room? }, event, data)` sends with the `<ns>:` prefix. Until @dokebi/app collects the point it is unused and nothing changes.
+- The cluster worker check (`LOCAL_IN_CLUSTER`) uses core's `context.runtime.role === 'worker'` (it never reads `node:cluster` itself).
+- When an app has `events` but this package is missing, the start fails (`has event streams; add @dokebi/sse`), and `app.realtime().publish` throws `REALTIME_UNAVAILABLE`.
+
+## 4. Connection lifetime
+
+- Response: 200 `text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, `Connection: keep-alive`. The first lines are `retry: <retryMs>` and `event: dokebi-open` (data `{"retryMs":…}`). The Fastify response is hijacked and written directly, so no compression hook applies (dokebi-web does not compress).
+- Refusals: another origin (not listed) 403 `ORIGIN_FORBIDDEN`; before start or while stopping 503 (dokebi-web `STARTING`, `DRAINING`; this plugin `CLOSING`); full 503 `CAPACITY` (`Retry-After: 5`); no authentication 401. EventSource cannot see these statuses (the client below tells them apart with a probe).
+- `?dokebiProbe=1`: checks only origin, capacity and authentication and answers 204 (no stream is opened). The browser client uses it to find out why a connection failed.
+- Version (D-0033): when the route's `version` differs from the query `dokebiVersion` (or the `x-dokebi-version` header), it sends `retry: 60000` + `event: dokebi-reload` (data `{"version":…}`) and ends.
+- The `Last-Event-ID` header (when the browser reconnects by itself) or the query `lastEventId` (when the client reopens itself) becomes `stream.lastEventId`. The server keeps no events.
+- Heartbeat: `: ping` every `heartbeatMs`. Slow receivers: when the waiting bytes plus a new event exceed `maxBufferedBytes`, that stream is cut (`SLOW_CONSUMER`; other streams are unaffected).
+- Drain (stop, rolling restart): refuse new streams → unsubscribe from the bus → send `event: dokebi-restart` (data `{"retryMs":…}`) to every stream → end them → cut the remaining connections after `shutdownTimeoutMs` (or the core drain deadline) → wait for onClose. It drains before dokebi-web.
+- Health: with dokebi-health it registers the non-required check `sse`. When the bus is not `ready` the check is `failed` (`BUS_UNAVAILABLE`, warn log), and `ready` again when it returns (info log). It never drops readiness.
+
+## 5. Browser client
+
+```ts snippet
+import { connectEvents } from '@dokebi/sse/client';
+const events = connectEvents({
+  path: '/events',                 // or url: 'https://…'
+  query: { tab: 'orders' },
+  version: APP_VERSION,            // the dokebiVersion query
+  withCredentials: false,          // send cookies to another origin (that origin must be in the server's origins)
+  onReload: () => location.reload(),          // the default
+  reconnect: { minMs: 1000, maxMs: 30000 },   // false stays closed after a failure
+});
+const off = events.on<Order>('order.changed', (order, { id }) => {});
+events.onStatus((status) => {});   // connecting · open · reconnecting · paused · closed
+events.onError((error) => {});     // { code: UNAUTHORIZED, FORBIDDEN, UNAVAILABLE, CONNECTION_FAILED, BAD_DATA, HANDLER_FAILED, NO_EVENTSOURCE, status? }
+events.close(); events.reconnect();
+```
+
+- Importing touches neither window nor EventSource (SSR safe). It opens when you call `connectEvents`.
+- A listener is added to the EventSource only on the first `on` per event name. data is read as JSON (a failure is `BAD_DATA`).
+- `dokebi-reload` → `onReload` (default `location.reload()`); it does not reconnect.
+- `dokebi-restart` → close, then reopen after backoff with jitter (starting at `max(minMs, server retry)`, doubling up to `maxMs`, 50–100% of that value).
+- When EventSource reconnects by itself (the stream ended, network): left alone (`reconnecting`; the browser sends `Last-Event-ID`).
+- When EventSource gave up (HTTP error, wrong format, readyState CLOSED): close and ask why with `?dokebiProbe=1`. 401 or 403 → `closed` (permanent); anything else reopens after backoff. When reopening itself it sends the last id as the `lastEventId` query (it knows only the ids of events it listens to).
+- bfcache: closes on `pagehide` (persisted) (`paused`) and reopens on `pageshow` (persisted).
+- Vue `useEvents(options)` → `{ status, client, on, close, reconnect }` (connects on mount, closes at the end of the scope; outside a component it connects at once), `useEvent(events, name, handler)`.
+- React `useEvents(options)` → `{ status, client }` (the same url, path, query, version and withCredentials share one EventSource with reference counting; it closes on the tick after the last user is gone; the callbacks are those of whoever opened it first), `useEvent(name, handler, events?)` (without `events`, the nearest `<EventsProvider options>`).
+- Bundle: `@dokebi/sse/client/bundle` = `dist/browser/sse-client.js` (an ES module without dependencies). Serve it as a static file and use it from `<script type="module">` or an import map.
+
+## 5a. Seal hosts (D-0062)
+
+On streams of a seal host (@dokebi/app `domains.<host>.seal: true`) or of a `seal: true` web route, **the data of every event** (including `dokebi-open`, `dokebi-reload` and `dokebi-restart`) is sealed with that stream's path (`E:<ts>:<b64>`, dokebi-web `sealOf`). Event names and ids stay plain. Plain streams share one buffer; only sealed streams seal per receiver. A failed seal ends that stream (`SEAL_ENCODE_FAILED`; never sent in plain text). Browser: `connectEvents({ ..., seal: currentSealBridge() })` (`@dokebi/seal/http`; undefined on plain pages, so the same code works). With a bridge, plain data is refused as `SEAL_FAILED`; without one, sealed data is refused as `SEAL_BRIDGE_MISSING` (neither reaches the handler).
+
+## 6. Several workers and servers
+
+- No sticky sessions needed. A NATS bus is required. `maxConnections` is per worker.
+- Order: per publisher order is kept; there is no global order. During a NATS outage publish fails with `BUS_UNAVAILABLE`/`BUS_PUBLISH_FAILED` and that event is lost.
+- Rolling restart: streams of the stopping worker get `dokebi-restart`, and clients reconnect to other workers with jitter.
+- HTTP/1.1 browsers allow 6 connections per origin (one stream per tab) → with many tabs use HTTP/2 (TLS) at the proxy. Proxy idle limit > `heartbeatMs`, and turn response buffering off.
+
+## 7. Logs (D-0047)
+
+debug: route registration, stream open and close (reason, ms, open count), refusal reasons, version refusals, room join and leave, publish (id, local), bus deliveries received, drain begin and end. warn: `SLOW_CONSUMER`, `BUS_UNAVAILABLE` (state change). error (the full error; repeats once per 10 seconds with `repeated`): `BUS_PUBLISH_FAILED`, `BUS_UNAVAILABLE` (publish refused), `BUS_MESSAGE_INVALID`, `SSE_ON_OPEN_FAILED`, `SSE_ON_CLOSE_FAILED`, `STREAM_WRITE_FAILED`, `BUS_UNSUBSCRIBE_FAILED`, `SSE_LOCAL_IN_CLUSTER`. A bad `authenticate` result (`INVALID_IDENTITY`) is logged by dokebi-web as 500 with `WEB_REQUEST_FAILED`.
+
+## 8. Errors
+
+`SseError` (branch on `code`; never `instanceof`).
+
+<!-- docs-check: complete-error-codes SseErrorCode -->
+Configuration and registration: `INVALID_OPTIONS`, `INVALID_ROUTE` (`path`, `origins` and so on), `FROZEN` (`route` after setup), `LOCAL_IN_CLUSTER` (§2; `SSE_LOCAL_IN_CLUSTER` before 0.4.0, D-0071). Connections: `INVALID_IDENTITY` (a bad `authenticate` result, 500). Sending: `INVALID_TARGET`, `INVALID_EVENT` (event name), `INVALID_DATA`, `EVENT_TOO_LARGE` (`maxEventBytes`), `INVALID_ROOM`, `ROOM_LIMIT` (`maxRooms`), `BUS_UNAVAILABLE`, `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`, §3), `CLOSED` (`publish` after the app stopped).
+
+`SseError` is a `DokebiError` (D-0063): `plugin: 'dokebi-sse'` and a `fix` that says how to repair it. `INVALID_OPTIONS` carries per-path problems in `details.issues` (no values). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dokebi contributors
+
+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,88 @@
-# Temporary Holding Version
+# @dokebi/sse
 
-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.
+Server-sent events (SSE, `text/event-stream`) for Dokebi web apps (@dokebi/web). It opens a stream per authenticated user and sends events chosen by tenant, member and room. Given a NATS bus of @dokebi/event-bus, events also reach the streams of other workers and servers. The browser client (`@dokebi/sse/client`, Vue and React hooks, a bundle usable without a build) is in the same package. Node >=24.0.0, @dokebi/core ^0.4.0. The decision record is [D-0060](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0060-sse.md).
+
+The guarantee is **at most once** (no ACK, no resending, no retention; the same as [D-0057](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0057-websocket-broadcast-without-ack.md)). Keep state that must not be missed in a DB and use events as "it changed, read it again" notices.
+
+## Install
+
+```sh
+npx dokebi add @dokebi/sse
+```
+
+> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package `dokebi` is not this CLI, so never use `npx -y dokebi`. Without an installed CLI use `npx -y @dokebi/cli …`.
+
+A single process needs no settings. With several workers or servers a NATS bus is required:
+
+```yaml
+options:
+  dokebi-nats:
+    connections: { main: { servers: [nats://127.0.0.1:4222] } }
+  dokebi-event-bus:
+    buses: { sse: { driver: nats, connection: main } }
+  dokebi-sse:
+    eventBus: sse
+```
+
+Before 0.4.0 the key was `bus` (and `closeTimeoutMs` is now `shutdownTimeoutMs`); the old names still work with an `OPTION_DEPRECATED` warning ([D-0071](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0071-option-vocabulary.md)).
+
+## Server
+
+```ts snippet
+const events = context.get(sse);   // or context.getDependency(dependency)
+events.route({
+  path: '/events',
+  version: APP_VERSION,                         // a different one gets dokebi-reload (D-0033)
+  authenticate: async (request) => {            // undefined → 401
+    const user = await request.session.get('user');
+    return user ? { tenant: user.shop, member: user.id, rooms: [`shop:${user.shop}`] } : undefined;
+  },
+  onOpen: (stream) => stream.send('snapshot', { unread: 3 }),
+});
+
+await events.publish({ tenant: 'shop-1' }, 'order.changed', { id: 42 });               // the whole tenant
+await events.publish({ tenant: 'shop-1', member: 'u7' }, 'notice', { text: 'Hello' }); // one person
+await events.publish({ tenant: 'shop-1', room: 'order:42' }, 'order.changed', { id: 42 }); // a room
+await events.publish({ tenantPrefix: 'front:' }, 'notice', { text: 'Maintenance' });   // every tenant with the prefix
+```
+
+| API | Meaning |
+|---|---|
+| `route({ path, constraints?, origins?, version?, authenticate, onOpen?, onClose? })` | setup only. A GET stream route |
+| `publish(target, event, data)` | `{ id, local }`. To matching streams of every process (the sending process once). The target is `{ tenant }` or `{ tenantPrefix }` (exactly one) plus `member?` and `room?` |
+| `connections(filter?)` | the number of open streams of this process (worker). `{ tenant?, member?, room?, path? }` |
+| `stream.send(event, data)` · `join(room)` · `leave(room)` · `close()` | one connection only |
+
+**With @dokebi/app (D-0061):** an app's `events: (app) => [route, …]` attaches streams only to the app's domains (route constraint `dokebiApp`). The stream tenant is `<namespace>:<tenant>`; when `authenticate` returns `namespace`, it is chosen from the app's namespaces (outside the list: 401). Server code publishes to that space with `app.realtime(namespace).publish({ tenant?, member?, room? }, event, data)` (without a tenant it is `tenantPrefix: '<namespace>:'`). See "Realtime namespaces" in the @dokebi/app README.
+
+Branch on error `code`s: `INVALID_EVENT` (naming rule, `dokebi-` prefix), `INVALID_DATA`, `EVENT_TOO_LARGE`, `INVALID_TARGET`, `ROOM_LIMIT`, `BUS_UNAVAILABLE` (sent nowhere), `BUS_PUBLISH_FAILED` (sent to this process, other places unknown; with `id` and `local`).
+
+## Browser
+
+```ts snippet
+import { connectEvents } from '@dokebi/sse/client';
+const events = connectEvents({ path: '/events', version: APP_VERSION });
+const off = events.on('order.changed', (order) => refresh(order.id));   // data parsed as JSON
+events.onStatus((status) => badge(status));   // connecting · open · reconnecting · paused · closed
+```
+
+- Vue: `import { useEvents, useEvent } from '@dokebi/sse/client/vue'`. Opens on mount and closes when the scope ends (never opens during SSR).
+- React: `import { useEvents, useEvent, EventsProvider } from '@dokebi/sse/client/react'`. Hooks with the same settings share one EventSource (StrictMode safe).
+- Pages without a build: serve `@dokebi/sse/client/bundle` (`dist/browser/sse-client.js`, a single ES module without dependencies) as a static file and use `<script type="module">import { connectEvents } from '/sse-client.js'</script>`.
+- With the standard EventSource only: `es.addEventListener('dokebi-reload', () => location.reload())`, and reopen a little later after `dokebi-restart`.
+
+## Several workers and servers
+
+- No sticky sessions needed. Whatever worker a client connects to, it receives the same events through the NATS bus.
+- With several workers, `eventBus` (driver `nats`) is required. Without it a cluster worker does not start (`LOCAL_IN_CLUSTER`; with a deliberate single worker set `allowInCluster: true`).
+- `maxConnections` is per worker.
+- Rooms belong to their connection and are gone after a reconnect: join again in `authenticate`'s `rooms` or in `onOpen`.
+- Order: what one publisher sends arrives in order; there is no global order across publishers. When NATS is down, `publish` fails with a coded error and that event is lost.
+- Browsers allow 6 connections per origin over HTTP/1.1. With many tabs use HTTP/2 (TLS) at the proxy.
+- The proxy idle limit must be longer than `heartbeatMs` (default 15 seconds). nginx honours `X-Accel-Buffering: no`.
+
+Detailed settings and behaviour are in [AI.md](AI.md) and the [design notes](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/plugins/dokebi-sse/README.md); a runnable example is [examples/27-sse](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/27-sse/README.md).
+
+## Seal hosts (D-0062)
+
+On a seal host the data of every event is sealed. The browser opens it with `connectEvents({ path, seal: currentSealBridge() })` (`@dokebi/seal/http`). See [AI.md](AI.md) §5a and [D-0062](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0062-http-seal.md).

package/dist/browser/sse-client.js

@@ -0,0 +1,201 @@
+//#region client/index.ts
+var e = "dokebi-reload", t = "dokebi-restart", n = "dokebi-open";
+function r(e) {
+	let t = /^\{"retryMs":(\d{1,9})\}$/.exec(e);
+	return t ? Number(t[1]) : void 0;
+}
+function i(i) {
+	let a = i.EventSource ?? globalThis.EventSource, o = i.reconnect !== !1, s = i.reconnect === !1 ? 0 : Math.max(0, i.reconnect?.minMs ?? 1e3), c = i.reconnect === !1 ? 0 : Math.max(s, i.reconnect?.maxMs ?? 3e4), l = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Set(), p, m = "connecting", h, g = 0, _ = 0, v, y = !1, b = !1, x = !1, S = i.url ?? i.path;
+	if (typeof S != "string" || !S) throw TypeError("connectEvents needs url or path");
+	let C = i.seal;
+	if (C !== void 0 && typeof C?.unsealFrame != "function") throw TypeError("connectEvents seal needs unsealFrame(frame, url)");
+	let w;
+	function T(e) {
+		if (m !== e) {
+			m = e, i.onStatus?.(e);
+			for (let t of [...d]) t(e);
+		}
+	}
+	function E(e) {
+		if (!i.onError && !f.size) console.warn(`[dokebi-sse] ${e.code}`, e.error ?? e.status ?? "");
+		else {
+			i.onError?.(e);
+			for (let t of [...f]) t(e);
+		}
+	}
+	function D(e) {
+		let t = globalThis.location?.href, n = new URL(S, t);
+		for (let [e, t] of Object.entries(i.query ?? {})) t != null && n.searchParams.set(e, String(t));
+		i.version !== void 0 && n.searchParams.set("dokebiVersion", i.version), x && h !== void 0 && n.searchParams.set("lastEventId", h);
+		for (let [t, r] of Object.entries(e ?? {})) n.searchParams.set(t, r);
+		return w = n.pathname, n.href;
+	}
+	function O(e, t) {
+		let n = t.startsWith("E:");
+		if (C) try {
+			if (!n) throw Error("plain data on a sealed stream");
+			return C.unsealFrame(t, w ?? "/");
+		} catch (t) {
+			E({
+				code: "SEAL_FAILED",
+				event: e,
+				error: t
+			});
+			return;
+		}
+		if (!n) return t;
+		E({
+			code: "SEAL_BRIDGE_MISSING",
+			event: e
+		});
+	}
+	function k(e) {
+		return (t) => {
+			t.lastEventId && (h = t.lastEventId);
+			let n = O(e, t.data);
+			if (n === void 0) return;
+			let r;
+			try {
+				r = JSON.parse(n);
+			} catch (t) {
+				E({
+					code: "BAD_DATA",
+					event: e,
+					error: t
+				});
+				return;
+			}
+			let i = {
+				event: e,
+				id: t.lastEventId || void 0
+			};
+			for (let t of [...l.get(e) ?? []]) try {
+				t(r, i);
+			} catch (t) {
+				E({
+					code: "HANDLER_FAILED",
+					event: e,
+					error: t
+				});
+			}
+		};
+	}
+	function A() {
+		v !== void 0 && clearTimeout(v), v = void 0;
+	}
+	function j() {
+		p &&= (p.onopen = null, p.onerror = null, p.close(), void 0);
+	}
+	function M() {
+		if (A(), y || b) return;
+		if (!a) {
+			y = !0, T("closed"), E({ code: "NO_EVENTSOURCE" });
+			return;
+		}
+		let o = new a(D(), i.withCredentials ? { withCredentials: !0 } : void 0);
+		p = o, o.onopen = () => {
+			p === o && (_ = 0, T("open"));
+		}, o.onerror = () => {
+			p === o && N(o);
+		}, o.addEventListener(n, (e) => {
+			g = r(O(n, e.data) ?? "") ?? g;
+		}), o.addEventListener(e, (t) => {
+			p === o && O(e, t.data) !== void 0 && I();
+		}), o.addEventListener(t, (e) => {
+			p === o && (g = r(O(t, e.data) ?? "") ?? g, j(), T("reconnecting"), F());
+		});
+		for (let [e, t] of u) o.addEventListener(e, t);
+	}
+	function N(e) {
+		if (e.readyState !== 2) {
+			T("reconnecting");
+			return;
+		}
+		if (j(), !o) {
+			y = !0, T("closed"), E({ code: "CONNECTION_FAILED" });
+			return;
+		}
+		T("reconnecting");
+		let t = globalThis.fetch;
+		i.probe === !1 || !t ? (E({ code: "CONNECTION_FAILED" }), F()) : P(t);
+	}
+	async function P(e) {
+		let t;
+		try {
+			t = (await e(D({ dokebiProbe: "1" }), {
+				credentials: i.withCredentials ? "include" : "same-origin",
+				cache: "no-store"
+			})).status;
+		} catch (e) {
+			E({
+				code: "CONNECTION_FAILED",
+				error: e
+			}), F();
+			return;
+		}
+		y || b || (t === 401 || t === 403 ? (y = !0, A(), T("closed"), E({
+			code: t === 401 ? "UNAUTHORIZED" : "FORBIDDEN",
+			status: t
+		})) : (E({
+			code: t === 503 ? "UNAVAILABLE" : "CONNECTION_FAILED",
+			status: t
+		}), F()));
+	}
+	function F() {
+		if (A(), y || b) return;
+		if (!o) {
+			y = !0, T("closed");
+			return;
+		}
+		let e = Math.max(s, g), t = Math.min(Math.max(c, e), e * 2 ** _);
+		_ = Math.min(_ + 1, 20), x = !0, v = setTimeout(M, Math.round(t / 2 + Math.random() * t / 2));
+	}
+	function I() {
+		y = !0, j(), A(), T("closed"), i.onReload ? i.onReload() : globalThis.location?.reload();
+	}
+	let L = globalThis, R = (e) => {
+		e.persisted && !y && (b = !0, j(), A(), T("paused"));
+	}, z = (e) => {
+		e.persisted && !y && b && (b = !1, _ = 0, x = !0, T("connecting"), M());
+	};
+	return L.addEventListener?.("pagehide", R), L.addEventListener?.("pageshow", z), M(), {
+		get status() {
+			return m;
+		},
+		get lastEventId() {
+			return h;
+		},
+		on(e, t) {
+			if (typeof e != "string" || !e || typeof t != "function") throw TypeError("on(event, handler) needs an event name and a function");
+			let n = l.get(e);
+			if (!n) {
+				n = /* @__PURE__ */ new Set(), l.set(e, n);
+				let t = k(e);
+				u.set(e, t), p?.addEventListener(e, t);
+			}
+			let r = t;
+			return n.add(r), () => {
+				let t = l.get(e);
+				if (!t?.delete(r) || t.size) return;
+				l.delete(e);
+				let n = u.get(e);
+				u.delete(e), n && p?.removeEventListener(e, n);
+			};
+		},
+		onStatus(e) {
+			return d.add(e), () => d.delete(e);
+		},
+		onError(e) {
+			return f.add(e), () => f.delete(e);
+		},
+		close() {
+			y = !0, b = !1, j(), A(), L.removeEventListener?.("pagehide", R), L.removeEventListener?.("pageshow", z), T("closed");
+		},
+		reconnect() {
+			let e = y;
+			y = !1, b = !1, _ = 0, x = p !== void 0 || x, j(), e && (L.addEventListener?.("pagehide", R), L.addEventListener?.("pageshow", z)), T("connecting"), M();
+		}
+	};
+}
+//#endregion
+export { i as connectEvents };

package/dist/client/index.d.ts

@@ -0,0 +1,90 @@
+export type EventsStatus = 
+/** Opening the first time, or after reconnect(). */
+'connecting' | 'open'
+/** Lost; the browser or this client is opening it again. */
+ | 'reconnecting'
+/** The page went into the back/forward cache; reopened when it is shown again. */
+ | 'paused'
+/** close(), dokebi-reload, 401/403, or a failure with reconnect: false. */
+ | 'closed';
+export type EventsErrorCode = 'NO_EVENTSOURCE' | 'CONNECTION_FAILED' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'BAD_DATA' | 'HANDLER_FAILED'
+/** Sealed data arrived but no `seal` bridge was given (D-0062). */
+ | 'SEAL_BRIDGE_MISSING'
+/** With a `seal` bridge: data that is plain or does not open. Never handed on as plain. */
+ | 'SEAL_FAILED';
+export interface EventsError {
+    readonly code: EventsErrorCode;
+    /** The HTTP status the probe saw, when it saw one. */
+    readonly status?: number;
+    /** The event name, for BAD_DATA, HANDLER_FAILED and the SEAL_ codes. */
+    readonly event?: string;
+    readonly error?: unknown;
+}
+export interface EventMeta {
+    readonly event: string;
+    /** The event id (the server's `id:`), or undefined for events without one. */
+    readonly id: string | undefined;
+}
+export type EventHandler<T = unknown> = (data: T, meta: EventMeta) => void;
+/** The part of the standard EventSource this client uses (a test may pass its own). */
+export interface EventSourceLike {
+    readonly readyState: number;
+    onopen: ((event: unknown) => unknown) | null;
+    onerror: ((event: unknown) => unknown) | null;
+    addEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+    close(): void;
+}
+export interface MessageEventLike {
+    readonly data: string;
+    readonly lastEventId: string;
+}
+export type EventSourceConstructor = new (url: string, init?: {
+    withCredentials?: boolean;
+}) => EventSourceLike;
+export interface EventsOptions {
+    /** An absolute or page-relative stream URL. Use this or `path`. */
+    readonly url?: string;
+    /** A path on the page's origin, for example `/events`. */
+    readonly path?: string;
+    readonly query?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+    /** Sent as `dokebiVersion`; a server whose route has another version answers dokebi-reload. */
+    readonly version?: string;
+    /** Sends cookies on a cross-origin stream (the server must list the page's origin). */
+    readonly withCredentials?: boolean;
+    /** On `dokebi-reload` (the page's code is out of date). Default: `location.reload()`. */
+    readonly onReload?: () => void;
+    /** Backoff of this client's own reopens; false leaves a failed stream closed. */
+    readonly reconnect?: {
+        readonly minMs?: number;
+        readonly maxMs?: number;
+    } | false;
+    /** Ask the server why a stream was refused (default true where fetch exists). */
+    readonly probe?: boolean;
+    /** Another EventSource implementation (default: the browser's). */
+    readonly EventSource?: EventSourceConstructor;
+    readonly onStatus?: (status: EventsStatus) => void;
+    readonly onError?: (error: EventsError) => void;
+    /**
+     * The seal bridge of a seal host (D-0062): opens each event's sealed `data` with the stream
+     * path. `currentSealBridge()` of `@dokebi/seal/http` gives it on sealed pages only.
+     */
+    readonly seal?: {
+        unsealFrame(frame: string, url: string): string;
+    };
+}
+export interface EventsClient {
+    readonly status: EventsStatus;
+    /** The last event id seen on an event this client listens to. */
+    readonly lastEventId: string | undefined;
+    /** Listens to one event name; `data` is the parsed JSON. Returns a function that stops. */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    onStatus(handler: (status: EventsStatus) => void): () => void;
+    onError(handler: (error: EventsError) => void): () => void;
+    /** Closes the stream; nothing reopens it except reconnect(). */
+    close(): void;
+    /** Closes and opens the stream now (also after close()). */
+    reconnect(): void;
+}
+/** Opens an event stream (browser only). */
+export declare function connectEvents(options: EventsOptions): EventsClient;