@ragable/sdk 0.6.14 → 0.6.15

package/dist/index.mjs

@@ -2298,6 +2298,20 @@ var RagableBrowserDatabaseClient = class {
      * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
      * Channels must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
      */
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     *
+     * Returns a `BrowserRealtimeSubscription` with:
+     * - `unsubscribe()` — permanently close the subscription (stops reconnects).
+     * - `status` — current connection state: `"connecting"` | `"connected"` | `"reconnecting"` | `"disconnected"`.
+     *
+     * The subscription automatically reconnects with exponential backoff when the
+     * stream drops. Server heartbeats (every 15 s) are monitored — if none arrive
+     * within `heartbeatTimeoutMs` (default 45 s), the connection is treated as dead
+     * and a reconnect is triggered. Auth errors (401/403/404) are non-retryable.
+     *
+     * Channel names must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
     __publicField(this, "realtime", {
       subscribe: (params) => subscribeBrowserRealtime(
         this.options,
@@ -2327,9 +2341,13 @@ function followAbortSignal(parent, child) {
   }
   parent.addEventListener("abort", () => child.abort(), { once: true });
 }
+function backoffDelay(attempt, baseMs, maxMs) {
+  const exp = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
+  const jitter = exp * (0.5 + Math.random() * 0.5);
+  return Math.round(jitter);
+}
 async function subscribeBrowserRealtime(options, ragableAuth, fetchImpl, params) {
   const gid = requireAuthGroupId(options);
-  const token = await resolveDatabaseAuthBearer(options, ragableAuth);
   const databaseInstanceId = params.databaseInstanceId?.trim() || options.databaseInstanceId?.trim();
   if (!databaseInstanceId) {
     throw new RagableError(
@@ -2345,41 +2363,75 @@ async function subscribeBrowserRealtime(options, ragableAuth, fetchImpl, params)
       { code: "SDK_REALTIME_CHANNELS_REQUIRED" }
     );
   }
-  const ac = new AbortController();
-  followAbortSignal(params.signal, ac);
-  const headers = new Headers(options.headers);
-  headers.set("Authorization", `Bearer ${token}`);
-  headers.set("Content-Type", "application/json");
-  const response = await fetchImpl(
-    `${normalizeBrowserApiBase()}/auth-groups/${gid}/data/realtime/stream`,
-    {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        databaseInstanceId,
-        channels: params.channels
-      }),
-      signal: ac.signal
+  const maxAttempts = params.maxReconnectAttempts ?? Infinity;
+  const baseDelay = params.reconnectBaseDelayMs ?? 1e3;
+  const maxDelay = params.reconnectMaxDelayMs ?? 3e4;
+  const heartbeatTimeout = params.heartbeatTimeoutMs ?? 45e3;
+  const lifecycleAc = new AbortController();
+  followAbortSignal(params.signal, lifecycleAc);
+  let currentStatus = "connecting";
+  const setStatus = (s) => {
+    if (s === currentStatus) return;
+    currentStatus = s;
+    params.onStatusChange?.(s);
+  };
+  const subscription = {
+    unsubscribe: () => lifecycleAc.abort(),
+    get status() {
+      return currentStatus;
     }
-  );
-  const payload = await parseMaybeJsonBody(response);
-  if (!response.ok) {
-    const message = extractErrorMessage(payload, response.statusText);
-    throw new RagableError(message, response.status, payload);
-  }
-  const streamBody = response.body;
-  if (!streamBody) {
-    throw new RagableError(
-      "Realtime stream has no body",
-      502,
-      { code: "SDK_REALTIME_NO_BODY" }
+  };
+  setStatus("connecting");
+  async function connectOnce(signal) {
+    const token = await resolveDatabaseAuthBearer(options, ragableAuth);
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    headers.set("Content-Type", "application/json");
+    const response = await fetchImpl(
+      `${normalizeBrowserApiBase()}/auth-groups/${gid}/data/realtime/stream`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          databaseInstanceId,
+          channels: params.channels
+        }),
+        signal
+      }
     );
-  }
-  void (async () => {
+    if (!response.ok) {
+      const payload = await parseMaybeJsonBody(response);
+      const message = extractErrorMessage(payload, response.statusText);
+      throw new RagableError(message, response.status, payload);
+    }
+    const streamBody = response.body;
+    if (!streamBody) {
+      throw new RagableError("Realtime stream has no body", 502, {
+        code: "SDK_REALTIME_NO_BODY"
+      });
+    }
+    let heartbeatTimer = null;
+    const resetHeartbeatTimer = () => {
+      if (heartbeatTimer) clearTimeout(heartbeatTimer);
+      heartbeatTimer = setTimeout(() => {
+        streamReader?.cancel().catch(() => void 0);
+      }, heartbeatTimeout);
+    };
+    let streamReader = null;
     try {
-      for await (const evt of readSseStream(streamBody)) {
+      streamReader = streamBody.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      resetHeartbeatTimer();
+      const processEvent = (evt) => {
+        if (evt.type === "realtime:heartbeat") {
+          resetHeartbeatTimer();
+          return;
+        }
+        resetHeartbeatTimer();
         if (evt.type === "realtime:ready") {
           const ch = evt.channels;
+          setStatus("connected");
           params.onReady?.(
             Array.isArray(ch) ? ch.map((c) => String(c)) : []
           );
@@ -2392,15 +2444,78 @@ async function subscribeBrowserRealtime(options, ragableAuth, fetchImpl, params)
         } else if (evt.type === "realtime:error") {
           params.onError?.(String(evt.message ?? "Realtime error"));
         }
+      };
+      while (true) {
+        const { done, value } = await streamReader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let boundary = buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+          const block = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          for (const line of block.split("\n")) {
+            const dataPrefix = "data: ";
+            if (!line.startsWith(dataPrefix)) continue;
+            const json = line.slice(dataPrefix.length).trim();
+            if (!json || json === "[DONE]") continue;
+            try {
+              processEvent(JSON.parse(json));
+            } catch {
+            }
+          }
+          boundary = buffer.indexOf("\n\n");
+        }
       }
-    } catch (e) {
-      if (e.name === "AbortError") return;
-      params.onError?.(e.message);
+      return "stream_ended";
+    } finally {
+      if (heartbeatTimer) clearTimeout(heartbeatTimer);
+      streamReader?.releaseLock();
     }
+  }
+  void (async () => {
+    let attempt = 0;
+    while (!lifecycleAc.signal.aborted) {
+      const iterAc = new AbortController();
+      followAbortSignal(lifecycleAc.signal, iterAc);
+      try {
+        const result = await connectOnce(iterAc.signal);
+        if (lifecycleAc.signal.aborted) break;
+        if (result === "stream_ended") {
+          attempt++;
+        }
+      } catch (e) {
+        if (lifecycleAc.signal.aborted) break;
+        if (e.name === "AbortError") break;
+        const status = e.status;
+        if (status === 400 || status === 401 || status === 403 || status === 404) {
+          params.onError?.(e.message);
+          break;
+        }
+        attempt++;
+      }
+      if (lifecycleAc.signal.aborted) break;
+      if (attempt > maxAttempts) {
+        params.onError?.(`Realtime: gave up after ${maxAttempts} reconnect attempts`);
+        break;
+      }
+      const delay = backoffDelay(attempt, baseDelay, maxDelay);
+      setStatus("reconnecting");
+      params.onDisconnect?.({ attempt, retryInMs: delay });
+      await new Promise((r) => {
+        const timer = setTimeout(r, delay);
+        const onAbort = () => {
+          clearTimeout(timer);
+          r();
+        };
+        lifecycleAc.signal.addEventListener("abort", onAbort, { once: true });
+      });
+      if (lifecycleAc.signal.aborted) break;
+      setStatus("connecting");
+      params.onReconnect?.({ attempt });
+    }
+    setStatus("disconnected");
   })();
-  return {
-    unsubscribe: () => ac.abort()
-  };
+  return subscription;
 }
 var RagableBrowserAgentsClient = class {
   constructor(options) {