feat: subscribe to managed auth state via SSE instead of polling

.changeset/sse-auth-events.md

@@ -0,0 +1,5 @@
+---
+"@onkernel/managed-auth-react": minor
+---
+
+Subscribe to managed auth state via the `/auth/connections/{id}/events` SSE endpoint instead of polling `/auth/connections/{id}` every 2s. Removes the post-submit race where the UI could briefly snap back to `awaiting_input` after submission.

packages/managed-auth-react/src/lib/api.ts

@@ -1,4 +1,10 @@
-import type { ManagedAuthResponse, MFAType } from "./types";
+import type {
+  ManagedAuthResponse,
+  ManagedAuthStateEventData,
+  MFAType,
+} from "./types";
+
+export type { ManagedAuthStateEventData };
 
 export interface ApiClientOptions {
   baseUrl?: string;
@@ -10,11 +16,13 @@ const DEFAULT_BASE_URL = "https://api.onkernel.com";
 export class ManagedAuthApiError extends Error {
   public readonly status: number;
   public readonly body: string;
-  constructor(message: string, status: number, body: string) {
+  public readonly fatal: boolean;
+  constructor(message: string, status: number, body: string, fatal = false) {
     super(message);
     this.name = "ManagedAuthApiError";
     this.status = status;
     this.body = body;
+    this.fatal = fatal;
   }
 }
 
@@ -156,3 +164,116 @@ export function submitSignInOption(
     options,
   );
 }
+
+export interface ManagedAuthStreamHandlers {
+  onState: (event: ManagedAuthStateEventData) => void;
+  onError: (err: ManagedAuthApiError) => void;
+  onClose: () => void;
+}
+
+interface ParsedSSEMessage {
+  event?: string;
+  data: string;
+}
+
+function parseSSEMessage(raw: string): ParsedSSEMessage | null {
+  if (!raw.trim()) return null;
+  let event: string | undefined;
+  const dataLines: string[] = [];
+  for (const line of raw.split(/\r\n|\r|\n/)) {
+    if (!line || line.startsWith(":")) continue;
+    const colonIdx = line.indexOf(":");
+    const field = colonIdx === -1 ? line : line.slice(0, colonIdx);
+    let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (dataLines.length === 0) return null;
+  return { event, data: dataLines.join("\n") };
+}
+
+export function streamManagedAuthEvents(
+  id: string,
+  jwt: string,
+  handlers: ManagedAuthStreamHandlers,
+  options?: ApiClientOptions,
+): () => void {
+  const ac = new AbortController();
+  void (async () => {
+    try {
+      const f = getFetch(options);
+      const res = await f(
+        `${getBaseUrl(options)}/auth/connections/${id}/events`,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "text/event-stream",
+          },
+          signal: ac.signal,
+        },
+      );
+      if (!res.ok) {
+        const msg = await parseError(res);
+        handlers.onError(new ManagedAuthApiError(msg, res.status, msg));
+        return;
+      }
+      if (!res.body) {
+        handlers.onError(
+          new ManagedAuthApiError("SSE response has no body", 500, ""),
+        );
+        return;
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      // SSE message separator: blank line. Per spec, line endings can be
+      // \n, \r\n, or \r — so the separator can be \n\n, \r\n\r\n, or \r\r.
+      const SEPARATOR_RE = /\r\n\r\n|\r\r|\n\n/;
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        for (;;) {
+          const match = SEPARATOR_RE.exec(buf);
+          if (!match) break;
+          const raw = buf.slice(0, match.index);
+          buf = buf.slice(match.index + match[0].length);
+          const msg = parseSSEMessage(raw);
+          if (!msg) continue;
+          if (msg.event === "managed_auth_state") {
+            try {
+              handlers.onState(
+                JSON.parse(msg.data) as ManagedAuthStateEventData,
+              );
+            } catch {
+              /* ignore malformed payload */
+            }
+          } else if (msg.event === "error") {
+            let message = "Stream error";
+            try {
+              const data = JSON.parse(msg.data) as {
+                error?: { code?: string; message?: string };
+              };
+              if (data.error?.message) message = data.error.message;
+            } catch {
+              /* fall through with default message */
+            }
+            handlers.onError(
+              new ManagedAuthApiError(message, 500, message, true),
+            );
+            ac.abort();
+            return;
+          }
+        }
+      }
+      handlers.onClose();
+    } catch (err) {
+      if ((err as { name?: string })?.name === "AbortError") return;
+      const message = err instanceof Error ? err.message : "Stream failed";
+      handlers.onError(new ManagedAuthApiError(message, 0, message));
+    }
+  })();
+  return () => ac.abort();
+}

packages/managed-auth-react/src/lib/types.ts

@@ -73,6 +73,26 @@ export interface ManagedAuthResponse {
   error_code?: string | null;
 }
 
+// Mirrors @onkernel/sdk's ConnectionFollowResponse.ManagedAuthStateEvent.
+export interface ManagedAuthStateEventData {
+  event: "managed_auth_state";
+  timestamp: string;
+  flow_status: FlowStatus;
+  flow_step: FlowStep;
+  flow_type?: "LOGIN" | "REAUTH";
+  discovered_fields?: DiscoveredField[];
+  mfa_options?: MFAOption[];
+  sign_in_options?: SignInOption[];
+  pending_sso_buttons?: SSOButton[];
+  external_action_message?: string;
+  website_error?: string;
+  error_message?: string;
+  error_code?: string;
+  post_login_url?: string;
+  live_view_url?: string;
+  hosted_url?: string;
+}
+
 export type UIState =
   | "prime"
   | "discovering"