@ragable/sdk 0.6.13 → 0.6.15

package/dist/index.mjs

@@ -2294,6 +2294,32 @@ var RagableBrowserDatabaseClient = class {
         return payload;
       });
     });
+    /**
+     * 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,
+        this.ragableAuth,
+        this.fetchImpl,
+        params
+      )
+    });
     this.fetchImpl = bindFetch(options.fetch);
   }
   /** @internal Called by RagableBrowser to share the Transport instance. */
@@ -2307,6 +2333,190 @@ var RagableBrowserDatabaseClient = class {
     return new Headers(this.options.headers);
   }
 };
+function followAbortSignal(parent, child) {
+  if (!parent) return;
+  if (parent.aborted) {
+    child.abort();
+    return;
+  }
+  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 databaseInstanceId = params.databaseInstanceId?.trim() || options.databaseInstanceId?.trim();
+  if (!databaseInstanceId) {
+    throw new RagableError(
+      "realtime.subscribe requires databaseInstanceId in params or on createBrowserClient({ databaseInstanceId })",
+      400,
+      { code: "SDK_MISSING_DATABASE_INSTANCE_ID" }
+    );
+  }
+  if (!Array.isArray(params.channels) || params.channels.length === 0) {
+    throw new RagableError(
+      "realtime.subscribe requires a non-empty channels array",
+      400,
+      { code: "SDK_REALTIME_CHANNELS_REQUIRED" }
+    );
+  }
+  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;
+    }
+  };
+  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
+      }
+    );
+    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 {
+      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)) : []
+          );
+        } else if (evt.type === "notify") {
+          params.onNotify?.({
+            channel: String(evt.channel ?? ""),
+            payload: evt.payload === void 0 || evt.payload === null ? null : String(evt.payload),
+            processId: Number(evt.processId ?? 0)
+          });
+        } 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");
+        }
+      }
+      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 subscription;
+}
 var RagableBrowserAgentsClient = class {
   constructor(options) {
     this.options = options;