@octabits-io/nuxt-ui-kit 0.12.0 → 0.13.0

package/README.md

@@ -50,6 +50,15 @@ itself, so it has no Nuxt dependency, only `vue`.
   an app-side `useDateFormat`), plus source-shipped `./components/DateInput.vue`,
   `DateRangeInput.vue` (travel/booking end-date semantics, blocked dates via
   props, injected `availabilityCheck`), and `PeriodDisplay.vue`
+- **`./events`** — the browser side of `@octabits-io/framework/events`:
+  `createEventStreamClient`, a fetch-based SSE reader (the stream is
+  authenticated with an `Authorization` header, which native `EventSource`
+  cannot set — so reconnect, `Last-Event-ID` replay, and full-jitter backoff
+  live here), with a durable-only watermark, bounded seen-id dedupe, a
+  `degraded` state for honest fallback-polling UX, and a content-type guard
+  (a 200 `text/html` SPA fallback is a failure, not a stream);
+  `createSseFrameParser`; `useEventStream` (reactive connection state +
+  scope-bound lifecycle)
 - **`./ai`** — frontend AI-workflow engine: `useAiWorkflow` /
   `useAiWorkflowGuard` (poll-driven state over injected transport),
   `createAiProgressCore` (cross-page tracking + completion/applied signals —

package/dist/events/index.d.ts

@@ -0,0 +1,101 @@
+import { Ref } from "vue";
+//#region src/events/sseParser.d.ts
+/**
+ * Incremental SSE frame parser — pure logic, no I/O, exhaustively unit
+ * tested. Feed it decoded text chunks as they arrive; it returns completed
+ * frames (an empty line terminates a frame, per the SSE spec).
+ *
+ * Only the fields the event stream uses are surfaced (`id`, `event`, `data`,
+ * `retry`); comment lines (`: hb` heartbeats) and unknown fields are
+ * discarded. CRLF and bare-CR line endings are normalized.
+ */
+interface SseFrame {
+  /** The `id:` field — present only on durable events (the watermark rule). */
+  id?: string;
+  /** The `event:` field (the envelope type, informational). */
+  event?: string;
+  /** The `data:` field(s), newline-joined. */
+  data: string;
+  /** A `retry:` field, parsed to ms. */
+  retry?: number;
+}
+interface SseFrameParser {
+  /** Consume a chunk; returns every frame completed by it. */
+  push(chunk: string): SseFrame[];
+  /** Discard any partial frame state (call on reconnect). */
+  reset(): void;
+}
+declare function createSseFrameParser(): SseFrameParser;
+//#endregion
+//#region src/events/client.d.ts
+/**
+ * Structural duplicate of the framework's `EventEnvelope` — the kit has no
+ * dependency on `@octabits-io/framework`, and the wire format is the
+ * contract, not the type.
+ */
+interface StreamedEvent<T = unknown> {
+  id: string;
+  seq?: number;
+  type: string;
+  scopeKey: string;
+  at: string;
+  lane: 'durable' | 'ephemeral';
+  data: T;
+  actor?: {
+    type: string;
+    id?: string;
+    name?: string;
+  };
+  resources?: string[];
+}
+type EventStreamState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'degraded' | 'stopped';
+interface EventStreamRequest {
+  url: string;
+  /** Extra headers — put your `Authorization` here, fresh per attempt. */
+  headers?: Record<string, string>;
+}
+interface EventStreamClientOptions {
+  /**
+   * Build the request for each (re)connect attempt. Called every attempt so
+   * the auth token is always fresh. May be async (token refresh).
+   */
+  buildRequest: () => EventStreamRequest | Promise<EventStreamRequest>;
+  /** Deduped envelope delivery, both lanes. */
+  onEvent: (event: StreamedEvent) => void;
+  onStateChange?: (state: EventStreamState) => void;
+  /** Injected fetch (default `globalThis.fetch`). */
+  fetchImpl?: typeof fetch;
+  /** Base reconnect delay, overridden by the server's `retry:` hint (default 3 000 ms). */
+  retryMs?: number;
+  /** Reconnect delay ceiling under sustained failure (default 30 000 ms). */
+  maxRetryMs?: number;
+  /** Continuous failure duration before state turns `degraded` (default 60 000 ms). */
+  degradedAfterMs?: number;
+  /** Seen-id dedupe set bound (default 2 000). */
+  maxSeenIds?: number;
+  /** Resume watermark persisted from a previous session, if any. */
+  initialLastEventId?: string | null;
+}
+interface EventStreamClient {
+  start(): void;
+  stop(): void;
+  state(): EventStreamState;
+  /** The current watermark (last durable SSE id seen). */
+  lastEventId(): string | null;
+}
+declare function createEventStreamClient(options: EventStreamClientOptions): EventStreamClient;
+//#endregion
+//#region src/events/useEventStream.d.ts
+interface UseEventStreamReturn {
+  /** Reactive connection state — drive fallback-polling and UI hints off this. */
+  state: Readonly<Ref<EventStreamState>>;
+  /** Reactive count of events delivered (deduped) this session. */
+  received: Readonly<Ref<number>>;
+  start(): void;
+  stop(): void;
+  /** Current watermark (persist it to resume replay across page loads). */
+  lastEventId(): string | null;
+}
+declare function useEventStream(options: EventStreamClientOptions): UseEventStreamReturn;
+//#endregion
+export { type EventStreamClient, type EventStreamClientOptions, type EventStreamRequest, type EventStreamState, type SseFrame, type SseFrameParser, type StreamedEvent, type UseEventStreamReturn, createEventStreamClient, createSseFrameParser, useEventStream };

package/dist/events/index.js

@@ -0,0 +1,245 @@
+import { onScopeDispose, readonly, ref } from "vue";
+//#region src/events/sseParser.ts
+function createSseFrameParser() {
+	let buffer = "";
+	let id;
+	let event;
+	let retry;
+	let dataLines = [];
+	function resetFrame() {
+		id = void 0;
+		event = void 0;
+		retry = void 0;
+		dataLines = [];
+	}
+	function processLine(line, frames) {
+		if (line === "") {
+			if (dataLines.length > 0 || id !== void 0 || event !== void 0 || retry !== void 0) frames.push({
+				...id !== void 0 ? { id } : {},
+				...event !== void 0 ? { event } : {},
+				...retry !== void 0 ? { retry } : {},
+				data: dataLines.join("\n")
+			});
+			resetFrame();
+			return;
+		}
+		if (line.startsWith(":")) return;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		switch (field) {
+			case "id":
+				if (!value.includes("\0")) id = value;
+				break;
+			case "event":
+				event = value;
+				break;
+			case "data":
+				dataLines.push(value);
+				break;
+			case "retry": {
+				const parsed = Number.parseInt(value, 10);
+				if (Number.isInteger(parsed) && parsed >= 0) retry = parsed;
+				break;
+			}
+			default: break;
+		}
+	}
+	function push(chunk) {
+		buffer += chunk.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+		const frames = [];
+		let newline = buffer.indexOf("\n");
+		while (newline !== -1) {
+			const line = buffer.slice(0, newline);
+			buffer = buffer.slice(newline + 1);
+			processLine(line, frames);
+			newline = buffer.indexOf("\n");
+		}
+		return frames;
+	}
+	function reset() {
+		buffer = "";
+		resetFrame();
+	}
+	return {
+		push,
+		reset
+	};
+}
+//#endregion
+//#region src/events/client.ts
+/**
+* The fetch-based SSE event-stream client. A hand-rolled reader rather than
+* native `EventSource` because the stream is authenticated with an
+* `Authorization` header, which `new EventSource(url)` cannot set — so
+* reconnect, `Last-Event-ID`, and backoff are implemented here, once.
+*
+* Semantics baked in (mirroring the server contract in
+* `@octabits-io/framework/events`):
+*
+* - **Watermark**: only frames carrying an SSE `id:` advance the persisted
+*   watermark (the server sets `id:` on durable events only) — sent back as
+*   the `Last-Event-ID` header on every reconnect for replay.
+* - **Dedupe**: replay overlaps and at-least-once delivery mean duplicates
+*   are normal; a bounded seen-id set (envelope `id`, not `seq`) filters
+*   them before `onEvent`.
+* - **Reconnect is routine, not an error**: the server caps connection age
+*   (~5 min) so auth is re-evaluated; a server-side close re-connects after
+*   the server's `retry:` hint with **full jitter**. Only sustained failure
+*   moves the state to `degraded` (UI hint to resume fallback polling).
+*/
+function createEventStreamClient(options) {
+	const { buildRequest, onEvent, onStateChange, fetchImpl = globalThis.fetch.bind(globalThis), retryMs = 3e3, maxRetryMs = 3e4, degradedAfterMs = 6e4, maxSeenIds = 2e3, initialLastEventId = null } = options;
+	let state = "idle";
+	let lastEventId = initialLastEventId;
+	let serverRetryMs = null;
+	let abort = null;
+	let running = false;
+	let attempt = 0;
+	let failingSince = null;
+	let retryTimer;
+	const seen = /* @__PURE__ */ new Set();
+	const seenOrder = [];
+	function setState(next) {
+		if (state === next) return;
+		state = next;
+		onStateChange?.(next);
+	}
+	function markSeen(id) {
+		if (seen.has(id)) return false;
+		seen.add(id);
+		seenOrder.push(id);
+		if (seenOrder.length > maxSeenIds) {
+			const evicted = seenOrder.shift();
+			if (evicted !== void 0) seen.delete(evicted);
+		}
+		return true;
+	}
+	function scheduleReconnect() {
+		if (!running) return;
+		attempt += 1;
+		if (failingSince === null) failingSince = Date.now();
+		setState(Date.now() - failingSince >= degradedAfterMs ? "degraded" : "reconnecting");
+		const cap = Math.min(maxRetryMs, (serverRetryMs ?? retryMs) * 2 ** Math.min(attempt - 1, 8));
+		const delay = Math.random() * cap;
+		retryTimer = setTimeout(() => void connect(), delay);
+	}
+	function handleFrame(frame) {
+		if (frame.retry !== void 0) serverRetryMs = frame.retry;
+		if (frame.id !== void 0 && frame.id !== "") lastEventId = frame.id;
+		if (frame.data === "") return;
+		let envelope;
+		try {
+			envelope = JSON.parse(frame.data);
+		} catch {
+			return;
+		}
+		if (typeof envelope !== "object" || envelope === null || typeof envelope.id !== "string") return;
+		if (!markSeen(envelope.id)) return;
+		onEvent(envelope);
+	}
+	async function connect() {
+		if (!running) return;
+		if (state === "idle" || state === "stopped") setState("connecting");
+		abort = new AbortController();
+		const parser = createSseFrameParser();
+		try {
+			const request = await buildRequest();
+			const response = await fetchImpl(request.url, {
+				headers: {
+					accept: "text/event-stream",
+					...lastEventId !== null ? { "last-event-id": lastEventId } : {},
+					...request.headers
+				},
+				signal: abort.signal
+			});
+			const contentType = response.headers.get("content-type") ?? "";
+			if (!response.ok || !response.body || !contentType.includes("text/event-stream")) {
+				scheduleReconnect();
+				return;
+			}
+			setState("connected");
+			attempt = 0;
+			failingSince = null;
+			const reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			for (;;) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				for (const frame of parser.push(decoder.decode(value, { stream: true }))) handleFrame(frame);
+			}
+			if (running) {
+				setState("reconnecting");
+				retryTimer = setTimeout(() => void connect(), Math.random() * (serverRetryMs ?? retryMs));
+			}
+		} catch (error) {
+			if (!running || error instanceof DOMException && error.name === "AbortError") return;
+			scheduleReconnect();
+		}
+	}
+	function start() {
+		if (running) return;
+		running = true;
+		connect();
+	}
+	function stop() {
+		running = false;
+		if (retryTimer) clearTimeout(retryTimer);
+		abort?.abort();
+		abort = null;
+		setState("stopped");
+	}
+	return {
+		start,
+		stop,
+		state: () => state,
+		lastEventId: () => lastEventId
+	};
+}
+//#endregion
+//#region src/events/useEventStream.ts
+/**
+* Vue composable over {@link createEventStreamClient}: reactive connection
+* state, scope-bound lifecycle, and a typed per-event-type handler registry.
+*
+* The app owns *what to do* with events (invalidation registry, toasts, …);
+* this composable owns the connection. Typical wiring, once, in the app
+* shell:
+*
+* ```ts
+* const stream = useEventStream({
+*   buildRequest: () => ({
+*     url: `${apiBase}/events`,
+*     headers: { authorization: `Bearer ${auth.accessToken}` },
+*   }),
+*   onEvent: (event) => invalidation.dispatch(event),
+* });
+* watch(tenantReady, (ready) => (ready ? stream.start() : stream.stop()));
+* ```
+*/
+function useEventStream(options) {
+	const state = ref("idle");
+	const received = ref(0);
+	const client = createEventStreamClient({
+		...options,
+		onEvent: (event) => {
+			received.value += 1;
+			options.onEvent(event);
+		},
+		onStateChange: (next) => {
+			state.value = next;
+			options.onStateChange?.(next);
+		}
+	});
+	onScopeDispose(() => client.stop());
+	return {
+		state: readonly(state),
+		received: readonly(received),
+		start: client.start,
+		stop: client.stop,
+		lastEventId: client.lastEventId
+	};
+}
+//#endregion
+export { createEventStreamClient, createSseFrameParser, useEventStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octabits-io/nuxt-ui-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Frontend kit for Nuxt/Vue admin SPAs: OIDC session harness (oidc-client-ts), Eden Treaty client factory, auth/org store cores, and a route-guard builder — factory-style seams the app wires into its own plugins, stores, and middleware",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,11 @@
       "import": "./dist/ai/index.js",
       "default": "./dist/ai/index.js"
     },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "import": "./dist/events/index.js",
+      "default": "./dist/events/index.js"
+    },
     "./styles.css": "./src/styles.css",
     "./components/*": "./src/components/*"
   },
@@ -75,7 +80,7 @@
     "vitest": "^4.1.10",
     "vue": "^3.5.40",
     "zod": "^4.4.3",
-    "@octabits-io/framework": "^0.7.0"
+    "@octabits-io/framework": "^0.8.0"
   },
   "peerDependencies": {
     "@elysiajs/eden": "^1.4.0",