@ragable/sdk 0.6.14 → 0.6.16

package/dist/index.mjs

@@ -2196,6 +2196,51 @@ var RagableBrowserAuthClient = class {
     return this.auth.getSession();
   }
 };
+var BrowserCollectionApi = class {
+  constructor(database, name, databaseInstanceId) {
+    this.database = database;
+    this.name = name;
+    this.databaseInstanceId = databaseInstanceId;
+    __publicField(this, "find", (whereOrParams = {}) => {
+      const hasQueryKeys = ["where", "filters", "limit", "offset", "orderBy", "orderDirection"].some(
+        (key) => Object.prototype.hasOwnProperty.call(whereOrParams, key)
+      );
+      const body = hasQueryKeys ? whereOrParams : { where: whereOrParams };
+      return asPostgrestResponse(
+        () => this.database._requestCollection(
+          "POST",
+          `/${encodeURIComponent(this.name)}/find`,
+          body,
+          this.databaseInstanceId
+        )
+      );
+    });
+    __publicField(this, "insert", (data) => asPostgrestResponse(
+      () => this.database._requestCollection(
+        "POST",
+        `/${encodeURIComponent(this.name)}/records`,
+        { data },
+        this.databaseInstanceId
+      )
+    ));
+    __publicField(this, "update", (where, patch, options) => asPostgrestResponse(
+      () => this.database._requestCollection(
+        "PATCH",
+        `/${encodeURIComponent(this.name)}/records`,
+        { where, patch, ...options?.limit ? { limit: options.limit } : {} },
+        this.databaseInstanceId
+      )
+    ));
+    __publicField(this, "delete", (where, options) => asPostgrestResponse(
+      () => this.database._requestCollection(
+        "DELETE",
+        `/${encodeURIComponent(this.name)}/records`,
+        { where, ...options?.limit ? { limit: options.limit } : {} },
+        this.databaseInstanceId
+      )
+    ));
+  }
+};
 var RagableBrowserDatabaseClient = class {
   constructor(options, ragableAuth = null) {
     this.options = options;
@@ -2255,6 +2300,25 @@ var RagableBrowserDatabaseClient = class {
       };
       return new PostgrestTableApi(pgFetch, id, table);
     });
+    __publicField(this, "collection", (name, databaseInstanceId) => {
+      return new BrowserCollectionApi(this, name, databaseInstanceId);
+    });
+    __publicField(this, "defineCollection", (name, schema, databaseInstanceId) => asPostgrestResponse(
+      () => this._requestCollection(
+        "POST",
+        "/",
+        { name, ...schema ? { schema } : {} },
+        databaseInstanceId
+      )
+    ));
+    __publicField(this, "listCollections", (databaseInstanceId) => asPostgrestResponse(
+      () => this._requestCollection(
+        "GET",
+        "/",
+        void 0,
+        databaseInstanceId
+      )
+    ));
     __publicField(this, "query", async (params) => {
       return asPostgrestResponse(async () => {
         const gid = requireAuthGroupId(this.options);
@@ -2298,6 +2362,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,
@@ -2315,6 +2393,36 @@ var RagableBrowserDatabaseClient = class {
   toUrl(path) {
     return `${normalizeBrowserApiBase()}${path.startsWith("/") ? path : `/${path}`}`;
   }
+  async _requestCollection(method, path, body, databaseInstanceId) {
+    const gid = requireAuthGroupId(this.options);
+    const token = await resolveDatabaseAuthBearer(this.options, this.ragableAuth);
+    const id = databaseInstanceId?.trim() || this.options.databaseInstanceId?.trim();
+    if (!id) {
+      throw new RagableError(
+        "db.collection() requires databaseInstanceId in client options or as an argument",
+        400,
+        { code: "SDK_MISSING_DATABASE_INSTANCE_ID" }
+      );
+    }
+    const headers = this.baseHeaders();
+    headers.set("Authorization", `Bearer ${token}`);
+    headers.set("X-Database-Instance-Id", id);
+    if (body !== void 0) headers.set("Content-Type", "application/json");
+    const response = await this.fetchImpl(
+      this.toUrl(`/auth-groups/${gid}/data/collections${path}`),
+      {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      }
+    );
+    const payload = await parseMaybeJsonBody(response);
+    if (!response.ok) {
+      const message = extractErrorMessage(payload, response.statusText);
+      throw new RagableError(message, response.status, payload);
+    }
+    return payload;
+  }
   baseHeaders() {
     return new Headers(this.options.headers);
   }
@@ -2327,9 +2435,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 +2457,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 +2538,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) {
@@ -2446,6 +2655,7 @@ var RagableBrowser = class {
     __publicField(this, "agents");
     __publicField(this, "auth");
     __publicField(this, "database");
+    __publicField(this, "db");
     __publicField(this, "transport");
     __publicField(this, "_ragableAuth");
     /** Delegates to `database.from()`. Kept for back-compat — prefer `database.from()`. */
@@ -2485,6 +2695,7 @@ var RagableBrowser = class {
       this._ragableAuth
     );
     this.database._setTransport(this.transport);
+    this.db = this.database;
   }
   destroy() {
     this._ragableAuth?.destroy();
@@ -2558,7 +2769,7 @@ function createClient(options) {
   if (isServerClientOptions(options)) {
     if (typeof options === "object" && options !== null && "organizationId" in options && typeof options.organizationId === "string") {
       console.warn(
-        "[@ragable/sdk] createClient: `apiKey` is set, so the server client is returned. It has no `database` or `auth` \u2014 only `agents` and `shift`. For `database.from()` / `auth.*`, use the browser client without `apiKey` (e.g. createClient({ organizationId, authGroupId, databaseInstanceId, ... }))."
+        "[@ragable/sdk] createClient: `apiKey` is set, so the server client is returned. It has no `database` or `auth` \u2014 only `agents` and `shift`. For `db.collection()` / `database.from()` / `auth.*`, use the browser client without `apiKey` (e.g. createClient({ organizationId, authGroupId, databaseInstanceId, ... }))."
       );
     }
     return new Ragable(options);