@omg-dev/stream 0.4.24

package/dist/core.mjs

@@ -0,0 +1,95 @@
+//#region src/core.ts
+const enc = new TextEncoder();
+/**
+* Format a single event as one SSE block. Multiline data is split into
+* multiple `data:` lines per spec; JSON.stringify normally can't produce
+* one but defensive.
+*/
+function encodeEvent(id, data) {
+	const lines = data.split("\n").map((l) => `data: ${l}`).join("\n");
+	return enc.encode(`id: ${id}\n${lines}\n\n`);
+}
+/** SSE block representing a buffer-overflow gap. */
+function encodeGap(resumeId) {
+	return encodeEvent(resumeId, JSON.stringify({ type: "gap" }));
+}
+/** Comment-only frame, used for heartbeats. */
+function encodeHeartbeat() {
+	return enc.encode(":hb\n\n");
+}
+var Topic = class {
+	buffer = [];
+	nextId = 1;
+	subs = /* @__PURE__ */ new Set();
+	bufferMax;
+	bufferTtlMs;
+	constructor(opts = {}) {
+		this.bufferMax = opts.bufferMax ?? 500;
+		this.bufferTtlMs = opts.bufferTtlMs ?? 6e4;
+	}
+	/**
+	* Publish one event. Returns the assigned id so wrappers can include it
+	* in their HTTP response (`{ seq }` body, audit log, etc.).
+	*/
+	publish(data) {
+		const id = this.nextId++;
+		const json = JSON.stringify(data);
+		const ts = Date.now();
+		this.buffer.push({
+			id,
+			data: json,
+			ts
+		});
+		this.evictOld(ts);
+		const chunk = encodeEvent(id, json);
+		for (const w of [...this.subs]) w.write(chunk).catch(() => this.drop(w));
+		return id;
+	}
+	/**
+	* Attach a subscriber.
+	*   - If `sinceId` is provided and the buffer can fully replay events
+	*     after it, replay them in order, then go live.
+	*   - If `sinceId` is provided but the gap is too large (events fell
+	*     out of the buffer), emit one `{type:"gap"}` event so the client
+	*     can rehydrate from its durable source, then go live.
+	*   - If `sinceId` is absent (fresh connect), emit nothing and go live.
+	*
+	* Returns a `detach()` thunk so wrappers can clean up on disconnect.
+	*/
+	async attach(writer, sinceId) {
+		if (sinceId != null && Number.isFinite(sinceId)) {
+			const missed = this.buffer.filter((e) => e.id > sinceId);
+			const oldestBufferedId = this.buffer[0]?.id ?? this.nextId;
+			if (missed.length > 0 ? missed[0].id === sinceId + 1 : oldestBufferedId > sinceId) for (const e of missed) await writer.write(encodeEvent(e.id, e.data));
+			else await writer.write(encodeGap(this.nextId - 1));
+		}
+		this.subs.add(writer);
+		return () => this.drop(writer);
+	}
+	/** Drop a subscriber explicitly (e.g. on client disconnect). */
+	detach(writer) {
+		this.drop(writer);
+	}
+	/** Current subscriber count. */
+	size() {
+		return this.subs.size;
+	}
+	/**
+	* Id of the most recently published event, or 0 if none have been
+	* published yet. Useful for wrappers that want to tell fresh-connect
+	* subscribers where they're picking up (e.g. the CF worker's
+	* `:cursor <id>` comment for resume-ability).
+	*/
+	lastId() {
+		return this.nextId - 1;
+	}
+	drop(writer) {
+		if (!this.subs.delete(writer)) return;
+		if (writer.close) writer.close().catch(() => {});
+	}
+	evictOld(now) {
+		while (this.buffer.length > 0 && (this.buffer.length > this.bufferMax || now - this.buffer[0].ts > this.bufferTtlMs)) this.buffer.shift();
+	}
+};
+//#endregion
+export { Topic, encodeEvent, encodeGap, encodeHeartbeat };

package/dist/index.mjs

@@ -0,0 +1,129 @@
+import { fetchEventSource } from "@microsoft/fetch-event-source";
+//#region src/index.ts
+/**
+* @omg-dev/stream — client + server SDK for the Vibes stream service.
+*
+* Two surfaces:
+*   - `createStreamClient({ url, token })` — server-side publisher
+*   - `subscribe(topic, opts)` — client-side subscriber (raw promise API;
+*     React users should prefer `useStream` from `@omg-dev/stream/react`)
+*
+* The wire format is plain SSE with one event per `id:` block. Each event's
+* `data:` is JSON. See apps/infra/stream-worker for the server side.
+*
+* Resumability: the underlying fetch-event-source library sends
+* `Last-Event-ID` on reconnect; the stream service replays missed events
+* from its ring buffer, or emits `{type:"gap"}` if the gap is too large.
+* Callers should treat `gap` as a signal to refetch authoritative state.
+*/
+const DEFAULT_STREAM_URL = "https://stream.omg.dev";
+var FatalError = class extends Error {};
+/**
+* Subscribe to a topic. Returns an unsubscribe function.
+*
+* Reconnection, exponential backoff, Last-Event-ID, and tab-visibility
+* pause/resume are all handled by the underlying library.
+*/
+function subscribe(topic, opts) {
+	const url = `${(opts.url ?? "https://stream.omg.dev").replace(/\/+$/, "")}/${encodeURIComponent(topic)}`;
+	const ctl = new AbortController();
+	if (opts.signal) if (opts.signal.aborted) ctl.abort();
+	else opts.signal.addEventListener("abort", () => ctl.abort(), { once: true });
+	const getToken = typeof opts.token === "function" ? opts.token : () => opts.token;
+	let attempt = 0;
+	let authRetries = 0;
+	const MAX_AUTH_RETRIES = 4;
+	opts.onStatus?.({ state: "connecting" });
+	fetchEventSource(url, {
+		signal: ctl.signal,
+		fetch: async (input, init) => {
+			const token = await getToken();
+			const headers = new Headers(init?.headers);
+			headers.set("Authorization", `Bearer ${token}`);
+			return fetch(input, {
+				...init,
+				headers
+			});
+		},
+		async onopen(res) {
+			if (res.ok && res.headers.get("content-type")?.includes("text/event-stream")) {
+				attempt = 0;
+				authRetries = 0;
+				opts.onStatus?.({ state: "open" });
+				return;
+			}
+			if (res.status === 401 && authRetries < MAX_AUTH_RETRIES) {
+				authRetries += 1;
+				throw new Error(`401 (auth not ready, retry ${authRetries}/${MAX_AUTH_RETRIES})`);
+			}
+			if (res.status === 401 || res.status === 403 || res.status === 400) {
+				const body = await res.text().catch(() => "");
+				throw new FatalError(`${res.status}: ${body || res.statusText}`);
+			}
+			throw new Error(`unexpected status ${res.status}`);
+		},
+		onmessage(ev) {
+			if (!ev.data) return;
+			let parsed;
+			try {
+				parsed = JSON.parse(ev.data);
+			} catch {
+				return;
+			}
+			const id = ev.id ? Number(ev.id) : 0;
+			if (isGap(parsed)) {
+				opts.onGap?.();
+				return;
+			}
+			opts.onEvent({
+				id,
+				data: parsed
+			});
+		},
+		onclose() {
+			throw new Error("connection closed");
+		},
+		onerror(err) {
+			if (err instanceof FatalError) {
+				opts.onStatus?.({
+					state: "closed",
+					reason: err.message
+				});
+				throw err;
+			}
+			attempt += 1;
+			opts.onStatus?.({
+				state: "reconnecting",
+				attempt,
+				error: err
+			});
+			return Math.min(3e4, 500 * 2 ** Math.min(attempt - 1, 6));
+		}
+	}).catch(() => {});
+	return () => ctl.abort();
+}
+function isGap(data) {
+	return typeof data === "object" && data !== null && data.type === "gap";
+}
+function createStreamClient(opts) {
+	const baseUrl = (opts.url ?? "https://stream.omg.dev").replace(/\/+$/, "");
+	const getToken = typeof opts.token === "function" ? opts.token : () => opts.token;
+	return { async publish(topic, event) {
+		const token = await getToken();
+		const res = await fetch(`${baseUrl}/${encodeURIComponent(topic)}`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${token}`
+			},
+			body: JSON.stringify(event)
+		});
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new Error(`publish ${topic} failed: ${res.status} ${body}`);
+		}
+		return { seq: (await res.json()).seq };
+	} };
+}
+//#endregion
+export { DEFAULT_STREAM_URL, createStreamClient, subscribe };

package/dist/react.mjs

@@ -0,0 +1,56 @@
+import { subscribe } from "./index.mjs";
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/react.ts
+/**
+* React bindings for @omg-dev/stream.
+*
+* `useStream(topic, opts)` opens a subscription on mount, cleans up on
+* unmount, and exposes connection status + an event callback. Token can
+* be a sync string or an async thunk; the underlying library re-fetches
+* on every (re)connect so rotation is free.
+*
+* This hook intentionally does NOT buffer events in React state — token
+* deltas at 30/s would thrash. Callers consume each event in `onEvent`
+* (typically appending to a `useRef` and flushing via RAF — see
+* apps/web/src/components/InflightAssistantBubble.tsx for the pattern).
+*/
+function useStream(topic, opts) {
+	const [status, setStatus] = useState({ state: "connecting" });
+	const [nonce, setNonce] = useState(0);
+	const onEventRef = useRef(opts.onEvent);
+	const onGapRef = useRef(opts.onGap);
+	onEventRef.current = opts.onEvent;
+	onGapRef.current = opts.onGap;
+	useEffect(() => {
+		if (opts.enabled === false) {
+			setStatus({
+				state: "closed",
+				reason: "disabled"
+			});
+			return;
+		}
+		const unsub = subscribe(topic, {
+			url: opts.url,
+			token: opts.token,
+			onEvent: (e) => onEventRef.current(e),
+			onGap: () => onGapRef.current?.(),
+			onStatus: setStatus
+		});
+		return () => {
+			unsub();
+		};
+	}, [
+		topic,
+		opts.enabled,
+		nonce
+	]);
+	return {
+		status,
+		reconnect: useCallback(() => {
+			setStatus({ state: "connecting" });
+			setNonce((n) => n + 1);
+		}, [])
+	};
+}
+//#endregion
+export { useStream };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@omg-dev/stream",
+  "version": "0.4.24",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./core": {
+      "types": "./src/core.ts",
+      "default": "./dist/core.mjs"
+    },
+    "./react": {
+      "types": "./src/react.ts",
+      "default": "./dist/react.mjs"
+    }
+  },
+  "dependencies": {
+    "@microsoft/fetch-event-source": "^2.0.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.4.5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BennyKok/vibes.git"
+  },
+  "homepage": "https://docs.omg.dev",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/core.ts

@@ -0,0 +1,162 @@
+/**
+ * @omg-dev/stream/core — environment-agnostic SSE topic.
+ *
+ * `Topic` is the shared primitive behind both:
+ *   - apps/infra/stream-worker (one Topic per Durable Object, used by all
+ *     omg.dev streaming + cross-process Vibes app channels)
+ *   - packages/server (one Topic per Vibes app server, in-process fan-out
+ *     for CRUD invalidation)
+ *
+ * It owns a monotonic id counter, a ring buffer for Last-Event-ID replay,
+ * and a set of subscriber writers. It does NOT know about HTTP, JWTs,
+ * Durable Objects, or framework adapters — wrappers add those.
+ *
+ * Wire format (per event): `id: <n>\ndata: <json>\n\n`.
+ * Heartbeats and SSE response headers are the wrapper's responsibility
+ * because they're transport-specific (CF Workers vs Node http vs Hono).
+ */
+
+/**
+ * Minimum interface a wrapper needs to supply for a subscriber. Compatible
+ * with `WritableStreamDefaultWriter<Uint8Array>` (web streams) and with
+ * hand-rolled adapters around legacy callback-style sinks.
+ */
+export interface TopicWriter {
+  write(chunk: Uint8Array): Promise<void>;
+  /** Optional. Called when the topic drops the writer. */
+  close?(): Promise<void>;
+}
+
+export interface BufferedEvent {
+  id: number;
+  /** Already-stringified JSON payload (what landed on the wire). */
+  data: string;
+  /** Wall-clock when published, used for TTL eviction. */
+  ts: number;
+}
+
+export interface TopicOptions {
+  /** Max events retained in the ring buffer. Default 500. */
+  bufferMax?: number;
+  /** Max age of an event before eviction, in ms. Default 60 000. */
+  bufferTtlMs?: number;
+}
+
+const enc = new TextEncoder();
+
+/**
+ * Format a single event as one SSE block. Multiline data is split into
+ * multiple `data:` lines per spec; JSON.stringify normally can't produce
+ * one but defensive.
+ */
+export function encodeEvent(id: number, data: string): Uint8Array {
+  const lines = data.split("\n").map((l) => `data: ${l}`).join("\n");
+  return enc.encode(`id: ${id}\n${lines}\n\n`);
+}
+
+/** SSE block representing a buffer-overflow gap. */
+export function encodeGap(resumeId: number): Uint8Array {
+  return encodeEvent(resumeId, JSON.stringify({ type: "gap" }));
+}
+
+/** Comment-only frame, used for heartbeats. */
+export function encodeHeartbeat(): Uint8Array {
+  return enc.encode(":hb\n\n");
+}
+
+export class Topic {
+  private buffer: BufferedEvent[] = [];
+  private nextId = 1;
+  private subs = new Set<TopicWriter>();
+  private readonly bufferMax: number;
+  private readonly bufferTtlMs: number;
+
+  constructor(opts: TopicOptions = {}) {
+    this.bufferMax = opts.bufferMax ?? 500;
+    this.bufferTtlMs = opts.bufferTtlMs ?? 60_000;
+  }
+
+  /**
+   * Publish one event. Returns the assigned id so wrappers can include it
+   * in their HTTP response (`{ seq }` body, audit log, etc.).
+   */
+  publish(data: unknown): number {
+    const id = this.nextId++;
+    const json = JSON.stringify(data);
+    const ts = Date.now();
+    this.buffer.push({ id, data: json, ts });
+    this.evictOld(ts);
+    const chunk = encodeEvent(id, json);
+    for (const w of [...this.subs]) {
+      w.write(chunk).catch(() => this.drop(w));
+    }
+    return id;
+  }
+
+  /**
+   * Attach a subscriber.
+   *   - If `sinceId` is provided and the buffer can fully replay events
+   *     after it, replay them in order, then go live.
+   *   - If `sinceId` is provided but the gap is too large (events fell
+   *     out of the buffer), emit one `{type:"gap"}` event so the client
+   *     can rehydrate from its durable source, then go live.
+   *   - If `sinceId` is absent (fresh connect), emit nothing and go live.
+   *
+   * Returns a `detach()` thunk so wrappers can clean up on disconnect.
+   */
+  async attach(writer: TopicWriter, sinceId?: number): Promise<() => void> {
+    if (sinceId != null && Number.isFinite(sinceId)) {
+      const missed = this.buffer.filter((e) => e.id > sinceId);
+      const oldestBufferedId = this.buffer[0]?.id ?? this.nextId;
+      const canFullyReplay =
+        missed.length > 0
+          ? missed[0].id === sinceId + 1
+          : oldestBufferedId > sinceId;
+      if (canFullyReplay) {
+        for (const e of missed) {
+          await writer.write(encodeEvent(e.id, e.data));
+        }
+      } else {
+        await writer.write(encodeGap(this.nextId - 1));
+      }
+    }
+    this.subs.add(writer);
+    return () => this.drop(writer);
+  }
+
+  /** Drop a subscriber explicitly (e.g. on client disconnect). */
+  detach(writer: TopicWriter): void {
+    this.drop(writer);
+  }
+
+  /** Current subscriber count. */
+  size(): number {
+    return this.subs.size;
+  }
+
+  /**
+   * Id of the most recently published event, or 0 if none have been
+   * published yet. Useful for wrappers that want to tell fresh-connect
+   * subscribers where they're picking up (e.g. the CF worker's
+   * `:cursor <id>` comment for resume-ability).
+   */
+  lastId(): number {
+    return this.nextId - 1;
+  }
+
+  private drop(writer: TopicWriter): void {
+    if (!this.subs.delete(writer)) return;
+    if (writer.close) {
+      writer.close().catch(() => {});
+    }
+  }
+
+  private evictOld(now: number): void {
+    while (
+      this.buffer.length > 0 &&
+      (this.buffer.length > this.bufferMax || now - this.buffer[0].ts > this.bufferTtlMs)
+    ) {
+      this.buffer.shift();
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,211 @@
+/**
+ * @omg-dev/stream — client + server SDK for the Vibes stream service.
+ *
+ * Two surfaces:
+ *   - `createStreamClient({ url, token })` — server-side publisher
+ *   - `subscribe(topic, opts)` — client-side subscriber (raw promise API;
+ *     React users should prefer `useStream` from `@omg-dev/stream/react`)
+ *
+ * The wire format is plain SSE with one event per `id:` block. Each event's
+ * `data:` is JSON. See apps/infra/stream-worker for the server side.
+ *
+ * Resumability: the underlying fetch-event-source library sends
+ * `Last-Event-ID` on reconnect; the stream service replays missed events
+ * from its ring buffer, or emits `{type:"gap"}` if the gap is too large.
+ * Callers should treat `gap` as a signal to refetch authoritative state.
+ */
+
+import {
+  fetchEventSource,
+  type EventSourceMessage,
+} from "@microsoft/fetch-event-source";
+
+export const DEFAULT_STREAM_URL = "https://stream.omg.dev";
+
+export interface StreamEvent {
+  /** Monotonic per-topic sequence number assigned by the server. */
+  id: number;
+  /** Whatever the publisher sent. Type-narrowed by the caller. */
+  data: unknown;
+}
+
+/** Reasons the subscription closed or transitioned state. */
+export type StreamStatus =
+  | { state: "connecting" }
+  | { state: "open" }
+  | { state: "reconnecting"; attempt: number; error?: unknown }
+  | { state: "closed"; reason?: string };
+
+export interface SubscribeOptions {
+  /** Stream service base URL. Defaults to https://stream.omg.dev. */
+  url?: string;
+  /** Bearer token, or a thunk that returns one (called on each connect). */
+  token: string | (() => string | Promise<string>);
+  /** Called for every event published while subscribed. */
+  onEvent: (event: StreamEvent) => void;
+  /**
+   * Called when the server says we missed too many events to replay.
+   * Hook for refetching the durable source-of-truth (e.g. Convex query).
+   */
+  onGap?: () => void;
+  /** Called whenever the connection state changes. */
+  onStatus?: (status: StreamStatus) => void;
+  /**
+   * Optional AbortSignal to terminate the subscription. The returned
+   * unsubscribe() does the same thing more idiomatically.
+   */
+  signal?: AbortSignal;
+}
+
+class FatalError extends Error {}
+
+/**
+ * Subscribe to a topic. Returns an unsubscribe function.
+ *
+ * Reconnection, exponential backoff, Last-Event-ID, and tab-visibility
+ * pause/resume are all handled by the underlying library.
+ */
+export function subscribe(topic: string, opts: SubscribeOptions): () => void {
+  const url = `${(opts.url ?? DEFAULT_STREAM_URL).replace(/\/+$/, "")}/${encodeURIComponent(topic)}`;
+  const ctl = new AbortController();
+  if (opts.signal) {
+    if (opts.signal.aborted) ctl.abort();
+    else opts.signal.addEventListener("abort", () => ctl.abort(), { once: true });
+  }
+  const getToken = typeof opts.token === "function" ? opts.token : () => opts.token as string;
+
+  let attempt = 0;
+  // 401 is recoverable when the consumer's auth state is still hydrating
+  // after a page reload — the token thunk returns null for ~hundreds of ms
+  // and the stream worker rejects until the session arrives. Treating
+  // those as fatal on the first try caused the bubble to stay closed
+  // for the rest of the page session even after the token became valid.
+  // Bound retries so a genuinely-unauthorised topic still fails fast.
+  let authRetries = 0;
+  const MAX_AUTH_RETRIES = 4;
+  opts.onStatus?.({ state: "connecting" });
+
+  void fetchEventSource(url, {
+    signal: ctl.signal,
+    // Custom fetch lets us stamp the token fresh on every (re)connection
+    // so callers can rotate tokens without re-subscribing.
+    fetch: async (input, init) => {
+      const token = await getToken();
+      const headers = new Headers(init?.headers);
+      headers.set("Authorization", `Bearer ${token}`);
+      return fetch(input, { ...init, headers });
+    },
+    async onopen(res) {
+      if (res.ok && res.headers.get("content-type")?.includes("text/event-stream")) {
+        attempt = 0;
+        authRetries = 0;
+        opts.onStatus?.({ state: "open" });
+        return;
+      }
+      // 401 — let it retry a bounded number of times to ride out an
+      // un-hydrated auth state on the consumer. The token thunk is
+      // re-invoked on each reconnect, so a fresh token will be picked
+      // up automatically.
+      if (res.status === 401 && authRetries < MAX_AUTH_RETRIES) {
+        authRetries += 1;
+        throw new Error(`401 (auth not ready, retry ${authRetries}/${MAX_AUTH_RETRIES})`);
+      }
+      // After the budget is spent, OR for the always-fatal cases
+      // (403 = ready-but-denied, 400 = bad topic), stop retrying.
+      if (res.status === 401 || res.status === 403 || res.status === 400) {
+        const body = await res.text().catch(() => "");
+        throw new FatalError(`${res.status}: ${body || res.statusText}`);
+      }
+      // Anything else (5xx, network) → let the library retry.
+      throw new Error(`unexpected status ${res.status}`);
+    },
+    onmessage(ev: EventSourceMessage) {
+      if (!ev.data) return; // heartbeat comments arrive as empty messages
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(ev.data);
+      } catch {
+        return; // Non-JSON line, ignore
+      }
+      const id = ev.id ? Number(ev.id) : 0;
+      if (isGap(parsed)) {
+        opts.onGap?.();
+        return;
+      }
+      opts.onEvent({ id, data: parsed });
+    },
+    onclose() {
+      // The library calls this on intentional close. Treat as transient
+      // (it'll re-call openWhenHidden semantics on visibility change) by
+      // throwing — the loop will reconnect with backoff.
+      throw new Error("connection closed");
+    },
+    onerror(err) {
+      if (err instanceof FatalError) {
+        opts.onStatus?.({ state: "closed", reason: err.message });
+        throw err; // stop retrying
+      }
+      attempt += 1;
+      opts.onStatus?.({ state: "reconnecting", attempt, error: err });
+      return Math.min(30_000, 500 * 2 ** Math.min(attempt - 1, 6)); // exp backoff capped at 30s
+    },
+    // Default behavior: pause on tab hidden, resume on visible.
+    // openWhenHidden left at default false.
+  })
+    .catch(() => {
+      // Fatal errors bubble out of fetchEventSource as rejections.
+      // onerror has already reported them via onStatus; nothing else to do.
+    });
+
+  // Tokens are fetched lazily and stamped onto each request via a
+  // wrapper. fetch-event-source doesn't give us a per-request hook for
+  // headers, so we shim through a custom fetch.
+  return () => ctl.abort();
+}
+
+function isGap(data: unknown): boolean {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as { type?: unknown }).type === "gap"
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Publisher
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CreateStreamClientOptions {
+  url?: string;
+  /** Bearer token. Function form is called per publish so it can refresh. */
+  token: string | (() => string | Promise<string>);
+}
+
+export interface StreamClient {
+  publish(topic: string, event: unknown): Promise<{ seq: number }>;
+}
+
+export function createStreamClient(opts: CreateStreamClientOptions): StreamClient {
+  const baseUrl = (opts.url ?? DEFAULT_STREAM_URL).replace(/\/+$/, "");
+  const getToken = typeof opts.token === "function" ? opts.token : () => opts.token as string;
+
+  return {
+    async publish(topic: string, event: unknown) {
+      const token = await getToken();
+      const res = await fetch(`${baseUrl}/${encodeURIComponent(topic)}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(event),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`publish ${topic} failed: ${res.status} ${body}`);
+      }
+      const json = (await res.json()) as { seq: number };
+      return { seq: json.seq };
+    },
+  };
+}

package/src/react.ts

@@ -0,0 +1,76 @@
+/**
+ * React bindings for @omg-dev/stream.
+ *
+ * `useStream(topic, opts)` opens a subscription on mount, cleans up on
+ * unmount, and exposes connection status + an event callback. Token can
+ * be a sync string or an async thunk; the underlying library re-fetches
+ * on every (re)connect so rotation is free.
+ *
+ * This hook intentionally does NOT buffer events in React state — token
+ * deltas at 30/s would thrash. Callers consume each event in `onEvent`
+ * (typically appending to a `useRef` and flushing via RAF — see
+ * apps/web/src/components/InflightAssistantBubble.tsx for the pattern).
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { subscribe, type StreamEvent, type StreamStatus, type SubscribeOptions } from "./index";
+
+export interface UseStreamOptions
+  extends Pick<SubscribeOptions, "url" | "token" | "onEvent" | "onGap"> {
+  /**
+   * When false, skips the subscription. Useful for "only subscribe when
+   * the run is active" patterns.
+   */
+  enabled?: boolean;
+}
+
+export interface UseStreamResult {
+  status: StreamStatus;
+  /**
+   * Force-tear-down the current subscription and start a fresh one. Use
+   * to recover from "stuck" states a user surfaces via the UI:
+   *   - permanent FatalError closed (401 budget exhausted, 403)
+   *   - silent zombie open with no events
+   *   - reconnect storm grinding at the 30s cap
+   * Cheap to call; no-op if `enabled` is false at call time.
+   */
+  reconnect: () => void;
+}
+
+export function useStream(topic: string, opts: UseStreamOptions): UseStreamResult {
+  const [status, setStatus] = useState<StreamStatus>({ state: "connecting" });
+  const [nonce, setNonce] = useState(0);
+  // Latch callbacks in refs so we can change them without re-subscribing.
+  const onEventRef = useRef(opts.onEvent);
+  const onGapRef = useRef(opts.onGap);
+  onEventRef.current = opts.onEvent;
+  onGapRef.current = opts.onGap;
+
+  useEffect(() => {
+    if (opts.enabled === false) {
+      setStatus({ state: "closed", reason: "disabled" });
+      return;
+    }
+    const unsub = subscribe(topic, {
+      url: opts.url,
+      token: opts.token,
+      onEvent: (e: StreamEvent) => onEventRef.current(e),
+      onGap: () => onGapRef.current?.(),
+      onStatus: setStatus,
+    });
+    return () => {
+      unsub();
+    };
+    // The token thunk and url are captured at effect-run time; bump
+    // `nonce` via reconnect() to pick up a fresh thunk after the
+    // consumer's auth state has changed.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [topic, opts.enabled, nonce]);
+
+  const reconnect = useCallback(() => {
+    setStatus({ state: "connecting" });
+    setNonce((n) => n + 1);
+  }, []);
+
+  return { status, reconnect };
+}