@ragable/sdk 0.7.10 → 0.8.1

package/dist/index.mjs

@@ -666,7 +666,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 = {}) {
@@ -693,13 +697,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);
   }
@@ -719,6 +726,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);
@@ -731,7 +740,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"));
@@ -747,7 +756,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);
@@ -879,13 +888,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,
@@ -1854,6 +1879,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();
@@ -1900,7 +1926,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);
@@ -1934,33 +1967,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 ───────────────────────────────────────────────────────────
@@ -1990,6 +2033,7 @@ var RagableAuth = class {
     });
   }
   async signOut(_options) {
+    this.sessionEpoch++;
     this.currentSession = null;
     this.clearRefreshTimer();
     if (this.persistSession) {
@@ -2009,12 +2053,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);
     });
@@ -2059,6 +2103,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);
     };
@@ -2068,12 +2121,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;
     }
@@ -2166,6 +2226,7 @@ var RagableAuth = class {
     };
   }
   async setSessionInternal(session, event) {
+    this.sessionEpoch++;
     this.currentSession = session;
     await this.persistCurrentSession();
     this.broadcast?.postSessionUpdated(JSON.stringify(session));
@@ -2196,12 +2257,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) {
@@ -2209,16 +2271,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 = {
@@ -2230,10 +2333,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 ───────────────────────────────────────────────────
@@ -2335,95 +2438,6 @@ function stripTrailingCommas(text) {
   return text.replace(/,(\s*[}\]])/g, "$1").replace(/,\s*$/, "");
 }
 
-// src/content.ts
-var MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-function toWireUserContent(content) {
-  if (typeof content === "string") return content;
-  const out = [];
-  for (const part of content) {
-    if (!part) continue;
-    if (part.type === "text") {
-      out.push(toWireTextPart(part));
-    } else if (part.type === "image") {
-      out.push(toWireImagePart(part));
-    }
-  }
-  return out;
-}
-function toWireTextPart(part) {
-  return { type: "text", text: part.text };
-}
-function toWireImagePart(part) {
-  const url = imagePartToUrl(part);
-  const detail = part.detail;
-  return {
-    type: "image_url",
-    image_url: detail ? { url, detail } : { url }
-  };
-}
-function imagePartToUrl(part) {
-  const img = part.image;
-  if (img instanceof URL) return img.href;
-  if (typeof img === "string") {
-    if (img.startsWith("http://") || img.startsWith("https://")) return img;
-    if (img.startsWith("data:")) return img;
-    const mediaType = requireMediaType(part, "raw base64 string");
-    assertBase64SizeOk(img);
-    return `data:${mediaType};base64,${img}`;
-  }
-  if (img instanceof Uint8Array || img instanceof ArrayBuffer) {
-    const bytes = img instanceof Uint8Array ? img : new Uint8Array(img);
-    assertBinarySizeOk(bytes);
-    const mediaType = requireMediaType(part, "binary image data");
-    const b64 = bytesToBase64(bytes);
-    return `data:${mediaType};base64,${b64}`;
-  }
-  throw new RagableError(
-    "ImagePart.image must be a string, URL, Uint8Array, or ArrayBuffer",
-    400,
-    { code: "SDK_INVALID_IMAGE_PART" }
-  );
-}
-function requireMediaType(part, what) {
-  const m = part.mediaType?.trim();
-  if (!m) {
-    throw new RagableError(
-      `ImagePart.mediaType is required for ${what} (e.g. "image/png")`,
-      400,
-      { code: "SDK_IMAGE_MEDIA_TYPE_REQUIRED" }
-    );
-  }
-  return m;
-}
-function assertBinarySizeOk(bytes) {
-  if (bytes.byteLength > MAX_IMAGE_BYTES) {
-    throw new RagableError(
-      `Image exceeds 5MB limit (${bytes.byteLength} bytes)`,
-      400,
-      { code: "SDK_IMAGE_TOO_LARGE" }
-    );
-  }
-}
-function assertBase64SizeOk(b64) {
-  const approxBytes = Math.floor(b64.length * 3 / 4);
-  if (approxBytes > MAX_IMAGE_BYTES) {
-    throw new RagableError(
-      `Image exceeds 5MB limit (~${approxBytes} bytes decoded)`,
-      400,
-      { code: "SDK_IMAGE_TOO_LARGE" }
-    );
-  }
-}
-function bytesToBase64(bytes) {
-  const CHUNK = 32768;
-  let binary = "";
-  for (let i = 0; i < bytes.length; i += CHUNK) {
-    const slice = bytes.subarray(i, i + CHUNK);
-    binary += String.fromCharCode(...slice);
-  }
-  return btoa(binary);
-}
-
 // src/stream-parts.ts
 function normalizeFinishReason(raw) {
   switch (raw) {
@@ -2636,9 +2650,7 @@ var ZERO_USAGE = {
 function buildInferenceRequestBody(params, responseFormat) {
   const body = {
     model: params.model,
-    messages: params.messages.map(
-      (m) => m.role === "user" ? { role: "user", content: toWireUserContent(m.content) } : m
-    )
+    messages: params.messages
   };
   if (params.system !== void 0) body.system = params.system;
   if (typeof params.temperature === "number")
@@ -3101,6 +3113,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";
 }
@@ -3115,16 +3129,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,
@@ -3136,8 +3160,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",
@@ -3241,6 +3275,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;
@@ -3279,13 +3321,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.
@@ -3474,7 +3514,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`),
           {
@@ -3767,10 +3816,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();
@@ -3780,14 +3830,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();
@@ -3800,7 +3864,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 = {}) {
@@ -3824,7 +3889,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) {
@@ -3865,12 +3931,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 {
@@ -3987,6 +4059,99 @@ var RagableBrowserMailClient = class {
     return message;
   }
 };
+var RagableBrowserFunctionsClient = class {
+  constructor(options, auth) {
+    this.options = options;
+    this.auth = auth;
+    __publicField(this, "fetchImpl");
+    this.fetchImpl = bindFetch(options.fetch);
+  }
+  requireWebsiteId() {
+    const websiteId = this.options.websiteId?.trim();
+    if (!websiteId) {
+      throw new RagableError(
+        "websiteId is required for functions. Use createWebsiteRagableClient()/createAppClient() or pass createBrowserClient({ websiteId, ... }).",
+        400,
+        { code: "SDK_MISSING_WEBSITE_ID" }
+      );
+    }
+    return websiteId;
+  }
+  toUrl(name) {
+    const orgId = this.options.organizationId;
+    const websiteId = this.requireWebsiteId();
+    return `${normalizeBrowserApiBase()}/public/organizations/${orgId}/websites/${websiteId}/functions/${encodeURIComponent(
+      name
+    )}/invoke`;
+  }
+  /**
+   * Best-effort end-user bearer, forwarded to the function as `context.auth.token`.
+   * Functions are public, so this never throws — anonymous calls send no token.
+   */
+  async getOptionalToken() {
+    if (this.auth) {
+      const token = await this.auth.getValidAccessToken().catch(() => null);
+      if (token) return token;
+    }
+    const caller = await Promise.resolve(this.options.getAccessToken?.()).catch(
+      () => null
+    );
+    if (typeof caller === "string" && caller.trim()) return caller.trim();
+    const staticKey = this.options.dataStaticKey?.trim();
+    if (staticKey) return staticKey;
+    return null;
+  }
+  /**
+   * Invoke a function by name. Prefer the typed `client.functions.<name>(input)`
+   * accessors; use this when the name is dynamic.
+   */
+  async invoke(name, input, options) {
+    const fnName = String(name ?? "").trim();
+    if (!fnName) {
+      throw new RagableError(
+        "functions.invoke requires a function name",
+        400,
+        { code: "SDK_MISSING_FUNCTION_NAME" }
+      );
+    }
+    const headers = new Headers(options?.headers ?? this.options.headers);
+    headers.set("Content-Type", "application/json");
+    const token = await this.getOptionalToken();
+    if (token) headers.set("Authorization", `Bearer ${token}`);
+    const response = await this.fetchImpl(this.toUrl(fnName), {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ input: input ?? null }),
+      ...options?.signal ? { signal: options.signal } : {}
+    });
+    const payload = await parseMaybeJsonBody(response);
+    if (!response.ok) {
+      const message = extractErrorMessage(payload, response.statusText);
+      throw new RagableError(message, response.status, payload);
+    }
+    if (payload && typeof payload === "object" && !Array.isArray(payload) && "result" in payload) {
+      return payload.result;
+    }
+    return payload;
+  }
+  /** Build the typed Proxy exposed as `client.functions`. */
+  asInvoker() {
+    const invoke = this.invoke.bind(this);
+    return new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (typeof prop !== "string") return void 0;
+          if (prop === "then") return void 0;
+          if (prop === "invoke") {
+            return (name, input, options) => invoke(name, input, options);
+          }
+          return (input, options) => invoke(prop, input, options);
+        }
+      }
+    );
+  }
+};
 var RagableBrowserAgentsClient = class {
   constructor(options) {
     this.options = options;
@@ -4314,6 +4479,11 @@ var RagableBrowser = class {
     __publicField(this, "db");
     __publicField(this, "storage");
     __publicField(this, "mail");
+    /**
+     * Backend edge functions — call a `/functions/<name>.ts` handler with
+     * `client.functions.<name>(input)`. Runs server-side. See {@link FunctionInvoker}.
+     */
+    __publicField(this, "functions");
     __publicField(this, "transport");
     __publicField(this, "_ragableAuth");
     /** Delegates to `database.from()`. Kept for back-compat — prefer `database.from()`. */
@@ -4333,13 +4503,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;
     }
@@ -4358,8 +4527,25 @@ 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();
@@ -4400,6 +4586,7 @@ export {
   RagableBrowserAiClient,
   RagableBrowserAuthClient,
   RagableBrowserDatabaseClient,
+  RagableBrowserFunctionsClient,
   RagableBrowserMailClient,
   RagableBrowserStorageClient,
   RagableError,
@@ -4413,7 +4600,6 @@ export {
   bindFetch,
   buildInferenceRequestBody,
   buildResponseFormat,
-  bytesToBase64,
   collectAssistantTextFromUiSegments,
   collectionRecordToRowWithMeta,
   collectionRecordsToRowWithMeta,
@@ -4429,7 +4615,6 @@ export {
   formatPostgrestError,
   formatSdkError,
   generateIdempotencyKey,
-  imagePartToUrl,
   isIncompleteAgentStreamError,
   mapAgentEvent,
   mapFireworksChunk,
@@ -4444,7 +4629,6 @@ export {
   runAgentChatStreamLenient,
   streamObjectFromContext,
   toRagableResult,
-  toWireUserContent,
   tryParsePartialJson,
   unwrapPostgrest,
   wrapStreamTextAsObject