@ragable/sdk 0.8.0 → 0.8.2

package/dist/index.js

@@ -53,6 +53,7 @@ __export(index_exports, {
   RagableError: () => RagableError,
   RagableNetworkError: () => RagableNetworkError,
   RagableSdkError: () => RagableSdkError,
+  RagableServerClient: () => RagableServerClient,
   RagableTimeoutError: () => RagableTimeoutError,
   SessionStorageAdapter: () => SessionStorageAdapter,
   Transport: () => Transport,
@@ -67,6 +68,7 @@ __export(index_exports, {
   createBrowserClient: () => createBrowserClient,
   createClient: () => createClient,
   createRagableBrowserClient: () => createRagableBrowserClient,
+  createServerClient: () => createServerClient,
   createStreamResultFromParts: () => createStreamResultFromParts,
   detectStorage: () => detectStorage,
   effectiveDataAuth: () => effectiveDataAuth,
@@ -760,7 +762,11 @@ function generateIdempotencyKey() {
   return `idk-${Date.now()}-${_uuidCounter}-${Math.random().toString(36).slice(2, 10)}`;
 }
 function requestCacheKey(req) {
-  return `${req.method}:${req.url}`;
+  const auth = req.headers.get("authorization") ?? "";
+  const dbInstance = req.headers.get("x-database-instance-id") ?? "";
+  return `${req.method}:${req.url}
+${auth}
+${dbInstance}`;
 }
 var Transport = class {
   constructor(options = {}) {
@@ -787,13 +793,16 @@ var Transport = class {
   async execute(req) {
     if (req.method === "GET") {
       const key = requestCacheKey(req);
-      const existing = this.inflightGets.get(key);
-      if (existing) return existing;
-      const promise = this._executeWithRetry(req).finally(() => {
-        this.inflightGets.delete(key);
-      });
-      this.inflightGets.set(key, promise);
-      return promise;
+      let base = this.inflightGets.get(key);
+      if (!base) {
+        base = this._executeWithRetry(req);
+        this.inflightGets.set(key, base);
+        const clear = () => {
+          if (this.inflightGets.get(key) === base) this.inflightGets.delete(key);
+        };
+        base.then(clear, clear);
+      }
+      return base.then((r) => r.clone());
     }
     return this._executeWithRetry(req);
   }
@@ -813,6 +822,8 @@ var Transport = class {
     let lastError;
     const maxAttempts = 1 + retryOpts.maxRetries;
     let did401Refresh = false;
+    const isIdempotent = req.method === "GET" || req.method === "HEAD";
+    const retryEnabled = retryOpts.maxRetries > 0 && (isIdempotent || req.retry !== void 0);
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       try {
         const response = await this._singleFetch(finalReq, timeoutMs);
@@ -825,7 +836,7 @@ var Transport = class {
             continue;
           }
         }
-        if (!response.ok && retryOpts.retryOn.includes(response.status) && attempt < maxAttempts - 1) {
+        if (retryEnabled && !response.ok && retryOpts.retryOn.includes(response.status) && attempt < maxAttempts - 1) {
           let delayMs = jitteredDelay(retryOpts.baseDelayMs, attempt, retryOpts.maxDelayMs);
           if (retryOpts.respectRetryAfter) {
             const ra = parseRetryAfter(response.headers.get("retry-after"));
@@ -841,7 +852,7 @@ var Transport = class {
           throw e;
         }
         lastError = e;
-        if (attempt < maxAttempts - 1) {
+        if (retryEnabled && attempt < maxAttempts - 1) {
           const delayMs = jitteredDelay(retryOpts.baseDelayMs, attempt, retryOpts.maxDelayMs);
           this.onRetry?.(finalReq, attempt + 1, delayMs, e.message);
           await sleep(delayMs);
@@ -973,13 +984,29 @@ function extractPostgRESTErrorMessage(payload, status, statusText) {
   return msg;
 }
 async function parsePostgRESTResponse(response) {
-  if (response.status === 204) return null;
+  if (response.status === 204 && response.ok) return null;
   const text = await response.text();
-  if (!text) return null;
+  if (!text) {
+    if (!response.ok) {
+      throw new RagableError(
+        response.statusText || `HTTP ${response.status}`,
+        response.status,
+        null
+      );
+    }
+    return null;
+  }
   let payload;
   try {
     payload = JSON.parse(text);
   } catch {
+    if (!response.ok) {
+      throw new RagableError(
+        extractPostgRESTErrorMessage(text, response.status, response.statusText),
+        response.status,
+        null
+      );
+    }
     throw new RagableError(
       `PostgREST response parse error: ${text.slice(0, 200)}`,
       response.status,
@@ -1948,6 +1975,7 @@ var AuthBroadcastChannel = class {
 };
 
 // src/auth.ts
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
 function parseExpiresInSeconds(raw) {
   if (typeof raw === "number") return raw;
   const s = raw.trim().toLowerCase();
@@ -1994,7 +2022,14 @@ var RagableAuth = class {
     __publicField(this, "listeners", /* @__PURE__ */ new Map());
     __publicField(this, "broadcast", null);
     __publicField(this, "visibilityHandler", null);
-    __publicField(this, "initialized", false);
+    /** Memoizes the one-shot restore so concurrent callers (constructor eager init,
+     *  every `onAuthStateChange` subscriber, `getSession`) share a single result.
+     *  Non-null also means "restore has started", replacing the old boolean flag. */
+    __publicField(this, "initializePromise", null);
+    /** Bumped on every explicit session change (sign-in/out, refresh). The async
+     *  restore captures this and refuses to overwrite a newer session op that
+     *  landed while it was reading storage (e.g. a sign-out during page load). */
+    __publicField(this, "sessionEpoch", 0);
     this.baseUrl = DEFAULT_RAGABLE_API_BASE.replace(/\/+$/, "");
     this.authGroupId = config.authGroupId;
     this.fetchImpl = bindFetch(config.fetch);
@@ -2028,33 +2063,43 @@ var RagableAuth = class {
     if (this.debug) console.debug("[RagableAuth]", ...args);
   }
   // ── Lifecycle ──────────────────────────────────────────────────────────────
-  async initialize() {
-    if (this.initialized) return this.currentSession;
-    this.initialized = true;
-    if (this.persistSession) {
-      try {
-        const raw = await this.storage.getItem(this.storageKey);
-        if (raw) {
-          const session = JSON.parse(raw);
-          if (session.expires_at && session.expires_at > nowSeconds()) {
-            this.currentSession = session;
-            this.scheduleRefresh(session);
-            this.log("Restored session from storage");
-          } else if (session.refresh_token) {
-            this.log("Stored session expired, attempting refresh");
-            const refreshed = await this._doRefresh(session.refresh_token);
-            if (refreshed) {
-              this.currentSession = refreshed;
-            } else {
-              await this.storage.removeItem(this.storageKey);
-            }
-          }
-        }
-      } catch (e) {
-        this.log("Failed to restore session", e);
+  /**
+   * Restore a persisted session (once). Memoized: every caller awaits the same
+   * promise, so the eager constructor init, `getSession`, and each
+   * `onAuthStateChange` subscriber's INITIAL_SESSION replay never race or
+   * double-restore. Does NOT emit `INITIAL_SESSION` globally — that event is
+   * delivered per-subscriber by `onAuthStateChange` (Supabase-parity), so a
+   * listener attached after restore still sees the existing session.
+   */
+  initialize() {
+    if (this.initializePromise) return this.initializePromise;
+    this.initializePromise = this._initialize();
+    return this.initializePromise;
+  }
+  async _initialize() {
+    if (!this.persistSession) return this.currentSession;
+    const epoch = this.sessionEpoch;
+    try {
+      const raw = await this.storage.getItem(this.storageKey);
+      if (!raw) return this.currentSession;
+      if (this.sessionEpoch !== epoch) return this.currentSession;
+      const session = JSON.parse(raw);
+      const stillValid = !!session.expires_at && session.expires_at > nowSeconds();
+      if (stillValid) {
+        this.currentSession = session;
+        this.scheduleRefresh(session);
+        this.log("Restored session from storage");
+      } else if (session.refresh_token) {
+        this.currentSession = session;
+        this.log("Stored session expired, attempting refresh");
+        const refreshed = await this.singleFlightRefresh(session.refresh_token);
+        if (refreshed) this.currentSession = refreshed;
+      } else {
+        await this.storage.removeItem(this.storageKey);
       }
+    } catch (e) {
+      this.log("Failed to restore session", e);
     }
-    this.emit("INITIAL_SESSION", this.currentSession);
     return this.currentSession;
   }
   // ── Auth methods ───────────────────────────────────────────────────────────
@@ -2084,6 +2129,7 @@ var RagableAuth = class {
     });
   }
   async signOut(_options) {
+    this.sessionEpoch++;
     this.currentSession = null;
     this.clearRefreshTimer();
     if (this.persistSession) {
@@ -2103,12 +2149,12 @@ var RagableAuth = class {
     });
   }
   async getSession() {
-    if (!this.initialized) await this.initialize();
+    await this.initialize();
     return { data: { session: this.currentSession }, error: null };
   }
   async getUser() {
     return asPostgrestResponse(async () => {
-      const token = this.currentSession?.access_token;
+      const token = await this.getValidAccessToken();
       if (!token) throw new RagableError("Not authenticated", 401, null);
       return this.fetchAuthWithBearer("/me", "GET", token);
     });
@@ -2153,6 +2199,15 @@ var RagableAuth = class {
     _subCounter++;
     const id = `sub-${_subCounter}`;
     this.listeners.set(id, callback);
+    void this.initialize().then((session) => {
+      const cb = this.listeners.get(id);
+      if (!cb) return;
+      try {
+        cb("INITIAL_SESSION", session);
+      } catch (e) {
+        this.log("Listener threw", e);
+      }
+    });
     const unsubscribe = () => {
       this.listeners.delete(id);
     };
@@ -2162,12 +2217,19 @@ var RagableAuth = class {
   getAccessToken() {
     return this.currentSession?.access_token ?? null;
   }
-  async getValidAccessToken() {
-    if (!this.initialized) await this.initialize();
+  /**
+   * Returns an access token guaranteed fresh for at least `refreshSkewSeconds`,
+   * refreshing (single-flight) if needed. Pass `force: true` to bypass the skew
+   * check and refresh now — used by the transport's 401 handler so a token the
+   * server rejected (key rotation, clock skew, early revocation) self-heals on
+   * retry instead of failing the call.
+   */
+  async getValidAccessToken(force = false) {
+    await this.initialize();
     const session = this.currentSession;
     if (!session) return null;
     const secondsUntilExpiry = session.expires_at - nowSeconds();
-    if (secondsUntilExpiry <= this.refreshSkewSeconds) {
+    if (force || secondsUntilExpiry <= this.refreshSkewSeconds) {
       const refreshed = await this.singleFlightRefresh(session.refresh_token);
       return refreshed?.access_token ?? null;
     }
@@ -2260,6 +2322,7 @@ var RagableAuth = class {
     };
   }
   async setSessionInternal(session, event) {
+    this.sessionEpoch++;
     this.currentSession = session;
     await this.persistCurrentSession();
     this.broadcast?.postSessionUpdated(JSON.stringify(session));
@@ -2290,12 +2353,13 @@ var RagableAuth = class {
     if (!this.autoRefreshToken) return;
     const secondsUntilExpiry = session.expires_at - nowSeconds();
     const refreshIn = Math.max(0, secondsUntilExpiry - this.refreshSkewSeconds);
-    this.log(`Scheduling refresh in ${refreshIn}s`);
+    const delayMs = Math.min(refreshIn * 1e3, MAX_TIMEOUT_MS);
+    this.log(`Scheduling refresh in ${Math.round(delayMs / 1e3)}s`);
     this.refreshTimer = setTimeout(() => {
       this.singleFlightRefresh(session.refresh_token).catch((e) => {
         this.log("Scheduled refresh failed", e);
       });
-    }, refreshIn * 1e3);
+    }, delayMs);
   }
   clearRefreshTimer() {
     if (this.refreshTimer !== null) {
@@ -2303,16 +2367,57 @@ var RagableAuth = class {
       this.refreshTimer = null;
     }
   }
+  /**
+   * Refresh the session, deduplicating concurrent callers onto one in-flight
+   * request. Side effects (persisting the new session, or clearing it and
+   * emitting SIGNED_OUT / TOKEN_REFRESH_FAILED) run exactly once inside the
+   * shared promise, so two callers can't double-emit. Resolves to the new
+   * session, or `null` when the refresh failed.
+   */
   async singleFlightRefresh(refreshToken) {
     if (this.refreshPromise) return this.refreshPromise;
-    this.refreshPromise = this._doRefresh(refreshToken).finally(() => {
+    this.refreshPromise = (async () => {
+      const outcome = await this._doRefresh(refreshToken);
+      if (outcome.ok) return outcome.session;
+      if (outcome.terminal) {
+        await this.handleTerminalRefreshFailure();
+      } else {
+        this.emit("TOKEN_REFRESH_FAILED", this.currentSession);
+      }
+      return null;
+    })().finally(() => {
       this.refreshPromise = null;
     });
     return this.refreshPromise;
   }
+  /** Clear the session locally and emit SIGNED_OUT after a definitively-rejected
+   *  refresh, so onAuthStateChange-driven UI redirects to login. */
+  async handleTerminalRefreshFailure() {
+    this.sessionEpoch++;
+    this.currentSession = null;
+    this.clearRefreshTimer();
+    if (this.persistSession) {
+      try {
+        await this.storage.removeItem(this.storageKey);
+      } catch (e) {
+        this.log("Failed to clear session after terminal refresh failure", e);
+      }
+    }
+    this.broadcast?.postSessionRemoved();
+    this.emit("TOKEN_REFRESH_FAILED", null);
+    this.emit("SIGNED_OUT", null);
+  }
   async _doRefresh(refreshToken) {
+    let raw;
+    try {
+      raw = await this.fetchAuth("/refresh", "POST", { refreshToken });
+    } catch (e) {
+      const status = e instanceof RagableError ? e.status : 0;
+      const terminal = status === 400 || status === 401 || status === 403;
+      this.log("Refresh request failed", { status, terminal });
+      return { ok: false, terminal, error: e };
+    }
     try {
-      const raw = await this.fetchAuth("/refresh", "POST", { refreshToken });
       const me = await this.fetchAuthWithBearer("/me", "GET", raw.accessToken);
       const expiresIn = parseExpiresInSeconds(raw.expiresIn);
       const session = {
@@ -2324,10 +2429,10 @@ var RagableAuth = class {
         user: me.user
       };
       await this.setSessionInternal(session, "TOKEN_REFRESHED");
-      return session;
+      return { ok: true, session };
     } catch (e) {
-      this.log("Refresh failed", e);
-      return null;
+      this.log("Post-refresh /me failed", e);
+      return { ok: false, terminal: false, error: e };
     }
   }
   // ─── Visibility listener ───────────────────────────────────────────────────
@@ -3104,6 +3209,8 @@ function normalizeBrowserApiBase() {
 function effectiveDataAuth(options) {
   if (options.dataAuth) return options.dataAuth;
   const hasStatic = Boolean(options.dataStaticKey?.trim()) || typeof options.getDataStaticKey === "function";
+  const canUserAuth = Boolean(options.authGroupId?.trim()) || typeof options.getAccessToken === "function";
+  if (hasStatic && canUserAuth) return "auto";
   if (hasStatic) return "publicAnon";
   return "user";
 }
@@ -3118,16 +3225,26 @@ function requireAuthGroupId(options) {
   }
   return id;
 }
-async function requireAccessToken(options, ragableAuth) {
+async function tryGetUserAccessToken(options, ragableAuth) {
   if (ragableAuth) {
-    const token = await ragableAuth.getValidAccessToken();
-    if (token) return token;
+    const token = await ragableAuth.getValidAccessToken().catch(() => null);
+    if (token?.trim()) return token.trim();
   }
   const getter = options.getAccessToken;
   if (getter) {
     const token = await getter();
     if (token?.trim()) return token.trim();
   }
+  return null;
+}
+async function resolveStaticDataKey(options) {
+  const fromGetter = options.getDataStaticKey ? await options.getDataStaticKey() : null;
+  const key = (fromGetter?.trim() || options.dataStaticKey?.trim()) ?? "";
+  return key || null;
+}
+async function requireAccessToken(options, ragableAuth) {
+  const token = await tryGetUserAccessToken(options, ragableAuth);
+  if (token) return token;
   throw new RagableError(
     "No access token available. Sign in first with auth.signInWithPassword() or provide getAccessToken callback.",
     401,
@@ -3139,8 +3256,18 @@ async function resolveDatabaseAuthBearer(options, ragableAuth) {
   if (mode === "user") {
     return requireAccessToken(options, ragableAuth);
   }
-  const fromGetter = options.getDataStaticKey ? await options.getDataStaticKey() : null;
-  const key = (fromGetter?.trim() || options.dataStaticKey?.trim()) ?? "";
+  if (mode === "auto") {
+    const userTok = await tryGetUserAccessToken(options, ragableAuth);
+    if (userTok) return userTok;
+    const key2 = await resolveStaticDataKey(options);
+    if (key2) return key2;
+    throw new RagableError(
+      "No access token or data key available. Sign in with auth.signInWithPassword() or configure dataStaticKey.",
+      401,
+      { code: "SDK_NO_ACCESS_TOKEN" }
+    );
+  }
+  const key = await resolveStaticDataKey(options);
   if (!key) {
     throw new RagableError(
       mode === "publicAnon" ? "dataAuth publicAnon requires getDataStaticKey or dataStaticKey" : "dataAuth admin requires getDataStaticKey or dataStaticKey",
@@ -3244,6 +3371,14 @@ var RagableBrowserAuthClient = class {
   getSession() {
     return this.auth.getSession();
   }
+  /**
+   * Returns a valid (auto-refreshed) access token for the current session, or
+   * `null` if signed out. The sanctioned way to obtain a token for a hand-rolled
+   * `fetch` to a custom endpoint — never read tokens out of storage yourself.
+   */
+  getValidAccessToken() {
+    return this.ragableAuth ? this.ragableAuth.getValidAccessToken() : Promise.resolve(null);
+  }
 };
 function collectionRecordToRowWithMeta(record) {
   const { data, id, createdAt, updatedAt } = record;
@@ -3282,13 +3417,11 @@ var BrowserCollectionApi = class {
       const { returnMode, body } = this.normalizeFindArgs(whereOrParams);
       const res = await this.requestFind(body);
       if (res.error) return res;
-      if (returnMode === "flat") {
-        return {
-          data: collectionRecordsToRowWithMeta(res.data),
-          error: null
-        };
-      }
-      return res;
+      const data = returnMode === "flat" ? collectionRecordsToRowWithMeta(res.data) : res.data;
+      return {
+        data,
+        error: null
+      };
     });
     /**
      * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
@@ -3477,7 +3610,16 @@ var RagableBrowserDatabaseClient = class {
         const headers = this.baseHeaders();
         headers.set("Authorization", `Bearer ${token}`);
         headers.set("Content-Type", "application/json");
-        const readOnly = effectiveDataAuth(this.options) === "publicAnon" ? true : params.readOnly !== false;
+        const dataMode = effectiveDataAuth(this.options);
+        let readOnly;
+        if (dataMode === "publicAnon") {
+          readOnly = true;
+        } else if (dataMode === "auto") {
+          const userTok = await tryGetUserAccessToken(this.options, this.ragableAuth);
+          readOnly = userTok ? params.readOnly !== false : true;
+        } else {
+          readOnly = params.readOnly !== false;
+        }
         const response = await this.fetchImpl(
           this.toUrl(`/auth-groups/${gid}/data/query`),
           {
@@ -3770,10 +3912,11 @@ async function subscribeBrowserRealtime(options, ragableAuth, fetchImpl, params)
   return subscription;
 }
 var BrowserStorageBucketClient = class {
-  constructor(options, fetchImpl, bucketId) {
+  constructor(options, fetchImpl, bucketId, ragableAuth = null) {
     this.options = options;
     this.fetchImpl = fetchImpl;
     this.bucketId = bucketId;
+    this.ragableAuth = ragableAuth;
   }
   get authGroupId() {
     const id = this.options.authGroupId?.trim();
@@ -3783,14 +3926,28 @@ var BrowserStorageBucketClient = class {
   base() {
     return `${normalizeBrowserApiBase()}/auth-groups/${this.authGroupId}/storage/buckets/${encodeURIComponent(this.bucketId)}`;
   }
+  /**
+   * Same credential resolution as the database client (see resolveDatabaseAuthBearer):
+   * in the generated-site default (`auto`), a signed-in user's auto-refreshed JWT
+   * is used so storage calls carry the user's identity; logged-out visitors fall
+   * back to the anon key. Previously storage ignored the managed session entirely.
+   */
   async bearerToken() {
-    const staticKey = this.options.dataStaticKey?.trim() || (this.options.getDataStaticKey ? await this.options.getDataStaticKey() : null)?.trim() || null;
-    if (staticKey) return staticKey;
-    if (this.options.getAccessToken) {
-      const tok = await this.options.getAccessToken();
-      if (tok?.trim()) return tok.trim();
+    return resolveDatabaseAuthBearer(this.options, this.ragableAuth);
+  }
+  /**
+   * The storage backend has historically returned HTTP 200 with an `{ error }`
+   * body on some failures; without this guard the SDK would resolve those as
+   * successful uploads/deletes. Treat any 2xx whose body carries a non-empty
+   * `error` as a failure.
+   */
+  assertNoEmbeddedError(payload, status) {
+    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+      const err = payload.error;
+      if (typeof err === "string" && err.trim()) {
+        throw new RagableError(err, status, payload);
+      }
     }
-    throw new RagableError("No auth token for storage. Provide dataStaticKey or getAccessToken.", 401, { code: "SDK_NO_ACCESS_TOKEN" });
   }
   async req(method, path, body) {
     const token = await this.bearerToken();
@@ -3803,7 +3960,8 @@ var BrowserStorageBucketClient = class {
       body: body instanceof FormData ? body : body !== void 0 ? JSON.stringify(body) : void 0
     });
     const payload = await res.json().catch(() => ({}));
-    if (!res.ok) throw new RagableError(payload?.error ?? res.statusText, res.status, payload);
+    if (!res.ok) throw new RagableError(extractErrorMessage(payload, res.statusText), res.status, payload);
+    this.assertNoEmbeddedError(payload, res.status);
     return payload;
   }
   list(params = {}) {
@@ -3827,7 +3985,8 @@ var BrowserStorageBucketClient = class {
     if (params.cacheControl) form.set("cacheControl", params.cacheControl);
     const res = await this.fetchImpl(`${this.base()}/upload`, { method: "POST", headers, body: form });
     const payload = await res.json().catch(() => ({}));
-    if (!res.ok) throw new RagableError(payload?.error ?? res.statusText, res.status, payload);
+    if (!res.ok) throw new RagableError(extractErrorMessage(payload, res.statusText), res.status, payload);
+    this.assertNoEmbeddedError(payload, res.status);
     return payload;
   }
   download(params) {
@@ -3868,12 +4027,18 @@ var BrowserStorageBucketClient = class {
   }
 };
 var RagableBrowserStorageClient = class {
-  constructor(options, fetchImpl) {
+  constructor(options, fetchImpl, ragableAuth = null) {
     this.options = options;
     this.fetchImpl = fetchImpl;
+    this.ragableAuth = ragableAuth;
   }
   from(bucketId) {
-    return new BrowserStorageBucketClient(this.options, this.fetchImpl, bucketId);
+    return new BrowserStorageBucketClient(
+      this.options,
+      this.fetchImpl,
+      bucketId,
+      this.ragableAuth
+    );
   }
 };
 var RagableBrowserMailClient = class {
@@ -4434,13 +4599,12 @@ var RagableBrowser = class {
         auth: options.auth
       });
       this.transport.setRefreshHandler(async () => {
-        if (effectiveDataAuth(options) !== "user") return null;
-        return this._ragableAuth.getValidAccessToken();
+        const mode = effectiveDataAuth(options);
+        if (mode !== "user" && mode !== "auto") return null;
+        return this._ragableAuth.getValidAccessToken(true).catch(() => null);
+      });
+      this._ragableAuth.initialize().catch(() => {
       });
-      if (!options.getAccessToken && effectiveDataAuth(options) === "user") {
-        this._ragableAuth.initialize().catch(() => {
-        });
-      }
     } else {
       this._ragableAuth = null;
     }
@@ -4459,13 +4623,26 @@ var RagableBrowser = class {
     );
     this.database._setTransport(this.transport);
     this.db = this.database;
-    this.storage = new RagableBrowserStorageClient(options, bindFetch(options.fetch));
+    this.storage = new RagableBrowserStorageClient(
+      options,
+      bindFetch(options.fetch),
+      this._ragableAuth
+    );
     this.mail = new RagableBrowserMailClient(options, this._ragableAuth);
     this.functions = new RagableBrowserFunctionsClient(
       options,
       this._ragableAuth
     ).asInvoker();
   }
+  /**
+   * Resolves once the persisted session has been restored (and refreshed if it
+   * was expired). Await this before reading auth state at startup to avoid a
+   * logged-out flash, e.g. `const session = await client.ready()`. Resolves
+   * `null` when no auth group is configured or no session is stored.
+   */
+  ready() {
+    return this._ragableAuth ? this._ragableAuth.initialize() : Promise.resolve(null);
+  }
   destroy() {
     this._ragableAuth?.destroy();
   }
@@ -4475,6 +4652,91 @@ function createBrowserClient(options) {
 }
 var createRagableBrowserClient = createBrowserClient;
 
+// src/server.ts
+function optionsForPrivilege(config, privilege) {
+  const base = {
+    organizationId: config.organizationId,
+    ...config.websiteId !== void 0 ? { websiteId: config.websiteId } : {},
+    ...config.authGroupId !== void 0 ? { authGroupId: config.authGroupId } : {},
+    ...config.databaseInstanceId !== void 0 ? { databaseInstanceId: config.databaseInstanceId } : {},
+    ...config.fetch !== void 0 ? { fetch: config.fetch } : {},
+    ...config.headers !== void 0 ? { headers: config.headers } : {}
+  };
+  if (privilege === "admin") {
+    const key = config.adminKey?.trim();
+    if (!key) {
+      throw new RagableError(
+        "Admin privilege requires `adminKey` (the auth group's data-admin key). It is not available \u2014 admin functions may be disabled for this project.",
+        403,
+        { code: "SDK_ADMIN_KEY_REQUIRED" }
+      );
+    }
+    return { ...base, dataAuth: "admin", dataStaticKey: key };
+  }
+  return {
+    ...base,
+    dataAuth: "auto",
+    getAccessToken: () => config.callerToken ?? null,
+    ...config.publicAnonKey !== void 0 ? { dataStaticKey: config.publicAnonKey } : {}
+  };
+}
+var RagableServerClient = class _RagableServerClient {
+  constructor(config, privilege) {
+    this.config = config;
+    __publicField(this, "database");
+    __publicField(this, "db");
+    __publicField(this, "storage");
+    __publicField(this, "mail");
+    __publicField(this, "functions");
+    __publicField(this, "ai");
+    __publicField(this, "agents");
+    /** Which credential this client is using. */
+    __publicField(this, "privilege");
+    this.privilege = privilege;
+    const options = optionsForPrivilege(config, privilege);
+    const transport = new Transport({
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      ...options.transport
+    });
+    this.database = new RagableBrowserDatabaseClient(options, null);
+    this.database._setTransport(transport);
+    this.db = this.database;
+    this.storage = new RagableBrowserStorageClient(options, bindFetch(options.fetch), null);
+    this.mail = new RagableBrowserMailClient(options, null);
+    this.functions = new RagableBrowserFunctionsClient(options, null).asInvoker();
+    this.ai = new RagableBrowserAiClient({
+      organizationId: options.organizationId,
+      ...options.websiteId !== void 0 ? { websiteId: options.websiteId } : {},
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      apiBase: normalizeBrowserApiBase()
+    });
+    this.agents = new RagableBrowserAgentsClient(options);
+  }
+  /**
+   * A client authenticated with the **data-admin key** — bypasses collection
+   * security (owner/group/claim grants do not apply) and can write protected
+   * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+   */
+  asAdmin() {
+    return new _RagableServerClient(this.config, "admin");
+  }
+  /**
+   * A client scoped to the invoking end user's identity (respects collection
+   * security). This is already the default; use it to drop back from `asAdmin()`.
+   */
+  asCaller() {
+    return new _RagableServerClient(this.config, "caller");
+  }
+};
+function createServerClient(config) {
+  return new RagableServerClient(
+    config,
+    config.defaultPrivilege ?? "caller"
+  );
+}
+
 // src/index.ts
 function createClient(options) {
   return createBrowserClient(options);
@@ -4512,6 +4774,7 @@ function createClient(options) {
   RagableError,
   RagableNetworkError,
   RagableSdkError,
+  RagableServerClient,
   RagableTimeoutError,
   SessionStorageAdapter,
   Transport,
@@ -4526,6 +4789,7 @@ function createClient(options) {
   createBrowserClient,
   createClient,
   createRagableBrowserClient,
+  createServerClient,
   createStreamResultFromParts,
   detectStorage,
   effectiveDataAuth,