@rebasepro/client 0.8.0 → 0.9.0

package/dist/index.umd.js

@@ -1,11 +1,11 @@
 (function(global, factory) {
-	typeof exports === "object" && typeof module !== "undefined" ? factory(exports, require("@rebasepro/common"), require("@rebasepro/types"), require("@rebasepro/utils")) : typeof define === "function" && define.amd ? define([
+	typeof exports === "object" && typeof module !== "undefined" ? factory(exports, require("@rebasepro/types"), require("@rebasepro/common"), require("@rebasepro/utils")) : typeof define === "function" && define.amd ? define([
 		"exports",
-		"@rebasepro/common",
 		"@rebasepro/types",
+		"@rebasepro/common",
 		"@rebasepro/utils"
-	], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global["Rebase Client"] = {}, global._rebasepro_common, global._rebasepro_types, global._rebasepro_utils));
-})(this, function(exports, _rebasepro_common, _rebasepro_types, _rebasepro_utils) {
+	], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global["Rebase Client"] = {}, global._rebasepro_types, global._rebasepro_common, global._rebasepro_utils));
+})(this, function(exports, _rebasepro_types, _rebasepro_common, _rebasepro_utils) {
 	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 	//#region src/reviver.ts
 	function rebaseReviver(_key, value) {
@@ -36,25 +36,16 @@
 	}
 	//#endregion
 	//#region src/transport.ts
-	var RebaseApiError = class extends Error {
-		status;
-		code;
-		details;
-		constructor(status, message, code, details) {
-			super(message);
-			this.name = "RebaseApiError";
-			this.status = status;
-			this.code = code;
-			this.details = details;
-		}
-	};
 	function buildQueryString(params) {
 		if (!params) return "";
 		const parts = [];
 		if (params.limit != null) parts.push(`limit=${params.limit}`);
 		if (params.offset != null) parts.push(`offset=${params.offset}`);
 		if (params.page != null) parts.push(`page=${params.page}`);
-		if (params.orderBy) parts.push(`orderBy=${encodeURIComponent(params.orderBy)}`);
+		if (params.orderBy) {
+			const wire = (0, _rebasepro_common.serializeOrderBy)(params.orderBy);
+			if (wire) parts.push(`orderBy=${encodeURIComponent(wire)}`);
+		}
 		if (params.searchString) parts.push(`searchString=${encodeURIComponent(params.searchString)}`);
 		if (params.include && params.include.length > 0) parts.push(`include=${encodeURIComponent(params.include.join(","))}`);
 		if (params.logical) {
@@ -103,8 +94,7 @@
 			} catch (e) {}
 			const getErrorField = (obj, field) => {
 				const err = obj?.error;
-				if (err && typeof err === "object" && err !== null && field in err) return err[field];
-				return obj?.[field];
+				if (err && typeof err === "object" && err !== null) return err[field];
 			};
 			if (res.status === 401 && onUnauthorizedHandler) {
 				if (await onUnauthorizedHandler()) {
@@ -127,7 +117,11 @@
 					if (!retryRes.ok) {
 						let fallbackMessage = retryRes.statusText;
 						if (retryRes.status === 404 && !fallbackMessage) fallbackMessage = `Endpoint not found (${init?.method || "GET"} ${path}). This usually means the collection is not registered on the backend, or the frontend API URL configuration (e.g. VITE_API_URL) is missing or pointing to the wrong host.`;
-						throw new RebaseApiError(retryRes.status, String(getErrorField(retryBody, "message") || fallbackMessage || `Request failed with status ${retryRes.status}`), getErrorField(retryBody, "code"), getErrorField(retryBody, "details"));
+						throw new _rebasepro_types.RebaseApiError(String(getErrorField(retryBody, "message") || fallbackMessage || `Request failed with status ${retryRes.status}`), {
+							status: retryRes.status,
+							code: getErrorField(retryBody, "code"),
+							details: getErrorField(retryBody, "details")
+						});
 					}
 					return retryBody;
 				}
@@ -135,7 +129,11 @@
 			if (!res.ok) {
 				let fallbackMessage = res.statusText;
 				if (res.status === 404 && !fallbackMessage) fallbackMessage = `Endpoint not found (${init?.method || "GET"} ${path}). This usually means the collection is not registered on the backend, or the frontend API URL configuration (e.g. VITE_API_URL) is missing or pointing to the wrong host.`;
-				throw new RebaseApiError(res.status, String(getErrorField(body, "message") || fallbackMessage || `Request failed with status ${res.status}`), getErrorField(body, "code"), getErrorField(body, "details"));
+				throw new _rebasepro_types.RebaseApiError(String(getErrorField(body, "message") || fallbackMessage || `Request failed with status ${res.status}`), {
+					status: res.status,
+					code: getErrorField(body, "code"),
+					details: getErrorField(body, "details")
+				});
 			}
 			return body;
 		}
@@ -171,6 +169,29 @@
 	}
 	//#endregion
 	//#region src/auth.ts
+	/** Map a raw user object from an auth response (`/login`, `/refresh`, `/me`) to a `User`. */
+	function mapRawUser(raw) {
+		return {
+			uid: raw.uid,
+			email: raw.email ?? null,
+			displayName: raw.displayName ?? null,
+			photoURL: raw.photoURL ?? null,
+			providerId: raw.providerId ?? "password",
+			isAnonymous: raw.isAnonymous ?? false,
+			emailVerified: raw.emailVerified,
+			roles: raw.roles,
+			metadata: raw.metadata
+		};
+	}
+	/** Placeholder user, used only as a last resort when none can be resolved. */
+	var EMPTY_USER = {
+		uid: "",
+		email: null,
+		displayName: null,
+		photoURL: null,
+		providerId: "password",
+		isAnonymous: false
+	};
 	function createMemoryStorage() {
 		const store = {};
 		return {
@@ -201,11 +222,20 @@
 		const authPath = opts.authPath || "/auth";
 		const autoRefresh = opts.autoRefresh !== false;
 		const persistSession = opts.persistSession !== false;
+		const authFlowMode = opts.authFlowMode || "json";
 		const STORAGE_KEY = "rebase_auth";
 		const REFRESH_BUFFER_MS = 12e4;
+		const MAX_REFRESH_RETRIES = 5;
+		const REFRESH_RETRY_BASE_MS = 1e3;
+		const REFRESH_RETRY_MAX_MS = 3e4;
 		let currentSession = null;
 		const listeners = /* @__PURE__ */ new Set();
 		let refreshTimeout = null;
+		let inFlightRefresh = null;
+		let resolveInitialized;
+		const isInitialized = new Promise((resolve) => {
+			resolveInitialized = resolve;
+		});
 		function authUrl(endpoint) {
 			return transport.baseUrl + transport.apiPath + authPath + endpoint;
 		}
@@ -213,7 +243,11 @@
 			return transport.fetchFn || globalThis.fetch;
 		}
 		function throwApiError(status, body, statusText) {
-			throw new RebaseApiError(status, body?.error?.message || body?.message || statusText, body?.error?.code || body?.code, body?.error?.details || body?.details);
+			throw new _rebasepro_types.RebaseApiError(body?.error?.message || body?.message || statusText, {
+				status,
+				code: body?.error?.code || body?.code,
+				details: body?.error?.details || body?.details
+			});
 		}
 		function emit(event, session) {
 			for (const fn of listeners) try {
@@ -221,7 +255,7 @@
 			} catch (e) {}
 		}
 		function saveSession(session) {
-			if (!persistSession) return;
+			if (!persistSession || authFlowMode === "cookie") return;
 			try {
 				storage.setItem(STORAGE_KEY, JSON.stringify(session));
 			} catch (e) {}
@@ -238,28 +272,53 @@
 			} catch (e) {}
 			return null;
 		}
+		/**
+		* A refresh failure is only fatal if the refresh token itself is rejected
+		* (expired / invalid / forbidden). Network blips, timeouts, and 5xx (e.g. a
+		* backend restart mid-session) are transient and must NOT log the user out.
+		*/
+		function isFatalRefreshError(err) {
+			if (!(err instanceof _rebasepro_types.RebaseApiError)) return false;
+			if (err.code === "INVALID_TOKEN" || err.code === "TOKEN_EXPIRED") return true;
+			return err.status === 401 || err.status === 403;
+		}
+		async function attemptScheduledRefresh(attempt) {
+			try {
+				await refreshSession();
+			} catch (err) {
+				if (isFatalRefreshError(err)) {
+					signOut();
+					return;
+				}
+				if (attempt >= MAX_REFRESH_RETRIES) {
+					signOut();
+					return;
+				}
+				const backoff = Math.min(REFRESH_RETRY_BASE_MS * 2 ** attempt, REFRESH_RETRY_MAX_MS);
+				refreshTimeout = setTimeout(() => {
+					attemptScheduledRefresh(attempt + 1);
+				}, backoff);
+			}
+		}
 		function scheduleRefresh(expiresAt) {
 			if (refreshTimeout) clearTimeout(refreshTimeout);
 			if (!autoRefresh) return;
 			const delay = expiresAt - REFRESH_BUFFER_MS - Date.now();
 			if (delay <= 0) {
-				refreshSession().catch(() => signOut());
+				attemptScheduledRefresh(0);
 				return;
 			}
-			refreshTimeout = setTimeout(async () => {
-				try {
-					await refreshSession();
-				} catch (e) {
-					signOut();
-				}
+			refreshTimeout = setTimeout(() => {
+				attemptScheduledRefresh(0);
 			}, delay);
 		}
 		function handleAuthResponse(data, event) {
+			const user = mapRawUser(data.user);
 			const session = {
 				accessToken: data.tokens.accessToken,
-				refreshToken: data.tokens.refreshToken,
+				refreshToken: data.tokens.refreshToken || currentSession?.refreshToken || "",
 				expiresAt: data.tokens.accessTokenExpiresAt,
-				user: data.user
+				user
 			};
 			currentSession = session;
 			saveSession(session);
@@ -275,7 +334,8 @@
 				body: JSON.stringify({
 					email,
 					password
-				})
+				}),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
@@ -296,7 +356,8 @@
 			const res = await fetchFn(authUrl("/register"), {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify(payload)
+				body: JSON.stringify(payload),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
@@ -319,7 +380,8 @@
 			const res = await getFetch()(authUrl("/google"), {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify(payload)
+				body: JSON.stringify(payload),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const responseBody = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, responseBody, res.statusText);
@@ -337,7 +399,8 @@
 				body: JSON.stringify({
 					code,
 					redirectUri
-				})
+				}),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
@@ -356,7 +419,8 @@
 			const res = await getFetch()(authUrl(`/${providerId}`), {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify(payload)
+				body: JSON.stringify(payload),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
@@ -432,10 +496,11 @@
 		async function signOut() {
 			const fetchFn = getFetch();
 			try {
-				if (currentSession?.refreshToken) await fetchFn(authUrl("/logout"), {
+				if (authFlowMode === "cookie" || currentSession?.refreshToken) await fetchFn(authUrl("/logout"), {
 					method: "POST",
 					headers: { "Content-Type": "application/json" },
-					body: JSON.stringify({ refreshToken: currentSession.refreshToken })
+					body: JSON.stringify({ refreshToken: currentSession?.refreshToken }),
+					credentials: authFlowMode === "cookie" ? "include" : void 0
 				});
 			} catch (e) {}
 			currentSession = null;
@@ -447,20 +512,35 @@
 			transport.setToken(null);
 			emit("SIGNED_OUT", null);
 		}
-		async function refreshSession() {
-			if (!currentSession?.refreshToken) throw new Error("No active session to refresh");
+		function refreshSession() {
+			if (inFlightRefresh) return inFlightRefresh;
+			inFlightRefresh = doRefreshSession().finally(() => {
+				inFlightRefresh = null;
+			});
+			return inFlightRefresh;
+		}
+		async function doRefreshSession() {
+			if (authFlowMode !== "cookie" && !currentSession?.refreshToken) throw new Error("No active session to refresh");
 			const res = await getFetch()(authUrl("/refresh"), {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ refreshToken: currentSession.refreshToken })
+				body: JSON.stringify({ refreshToken: currentSession?.refreshToken }),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
+			const accessToken = body.tokens.accessToken;
+			transport.setToken(accessToken);
+			let user = currentSession?.user;
+			if (body.user && typeof body.user.uid === "string") user = mapRawUser(body.user);
+			else if (!user || !user.uid) try {
+				user = await getUser();
+			} catch {}
 			const session = {
-				accessToken: body.tokens.accessToken,
-				refreshToken: body.tokens.refreshToken,
+				accessToken,
+				refreshToken: body.tokens.refreshToken || currentSession?.refreshToken || "",
 				expiresAt: body.tokens.accessTokenExpiresAt,
-				user: currentSession.user
+				user: user ?? EMPTY_USER
 			};
 			currentSession = session;
 			saveSession(session);
@@ -472,6 +552,18 @@
 		async function getUser() {
 			return (await transport.request(authPath + "/me", { method: "GET" })).user;
 		}
+		/**
+		* Resolve an email to a minimal public profile (`uid`, `displayName`,
+		* `photoURL`) for invite-by-email flows. Returns `null` when no account
+		* matches. Requires the backend to opt in via `auth.allowUserLookup`;
+		* otherwise the endpoint is absent and this rejects.
+		*/
+		async function findUserByEmail(email) {
+			return (await transport.request(authPath + "/find-user", {
+				method: "POST",
+				body: JSON.stringify({ email })
+			})).user;
+		}
 		async function updateUser(updates) {
 			const data = await transport.request(authPath + "/me", {
 				method: "PATCH",
@@ -545,7 +637,8 @@
 			const res = await getFetch()(authUrl("/magic-link/verify"), {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ token })
+				body: JSON.stringify({ token }),
+				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 			const body = await res.json().catch(() => ({}));
 			if (!res.ok) throwApiError(res.status, body, res.statusText);
@@ -592,21 +685,29 @@
 		}
 		if (persistSession) {
 			const stored = loadStoredSession();
-			if (stored && stored.accessToken && stored.refreshToken) {
-				if (stored.expiresAt > Date.now()) {
-					currentSession = stored;
-					transport.setToken(stored.accessToken);
-					scheduleRefresh(stored.expiresAt);
-				} else if (stored.refreshToken) {
-					currentSession = stored;
-					refreshSession().catch(() => {
-						currentSession = null;
-						clearStoredSession();
-						transport.setToken(null);
-					});
-				}
-			}
-		}
+			if (stored && stored.accessToken) if (stored.expiresAt > Date.now()) {
+				currentSession = stored;
+				transport.setToken(stored.accessToken);
+				scheduleRefresh(stored.expiresAt);
+				resolveInitialized();
+			} else if (authFlowMode === "cookie" || stored.refreshToken) {
+				currentSession = stored;
+				refreshSession().then(() => {
+					resolveInitialized();
+				}).catch(() => {
+					currentSession = null;
+					clearStoredSession();
+					transport.setToken(null);
+					resolveInitialized();
+				});
+			} else resolveInitialized();
+			else if (authFlowMode === "cookie") refreshSession().then(() => {
+				resolveInitialized();
+			}).catch(() => {
+				resolveInitialized();
+			});
+			else resolveInitialized();
+		} else resolveInitialized();
 		return {
 			signInWithEmail,
 			signUp,
@@ -626,6 +727,7 @@
 			signOut,
 			refreshSession,
 			getUser,
+			findUserByEmail,
 			updateUser,
 			resetPasswordForEmail,
 			resetPassword,
@@ -639,7 +741,8 @@
 			revokeAllSessions,
 			getAuthConfig,
 			getSession,
-			onAuthStateChange
+			onAuthStateChange,
+			isInitialized: () => isInitialized
 		};
 	}
 	function createCookieStorage(options = {}) {
@@ -816,20 +919,108 @@
 		};
 	}
 	//#endregion
-	//#region src/collection.ts
+	//#region src/sdk_query_builder.ts
 	/**
-	* Wrap a flat row (returned by the REST API as `{ id, ...fields }`) into
-	* a proper `Entity<M>` structure expected by the core framework.
-	* The `id` is kept inside `values` as well, since collection properties
-	* may define an `isId` field that the form binds to `formex.values`.
+	* SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
+	* Entity-wrapped results (`FindResponse<M>`).
+	*
+	* @example
+	* const { data } = await rebase.data.posts
+	*     .where("status", "==", "published")
+	*     .orderBy("created_at", "desc")
+	*     .limit(10)
+	*     .find();
+	*
+	* console.log(data[0].title); // flat access
 	*/
-	function rowToEntity(row, slug) {
-		return {
-			id: row.id,
-			path: slug,
-			values: row
-		};
-	}
+	var SDKQueryBuilder = class {
+		collection;
+		params = { where: {} };
+		constructor(collection) {
+			this.collection = collection;
+		}
+		where(columnOrCondition, operator, value) {
+			if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
+				this.params.logical = columnOrCondition;
+				return this;
+			}
+			if (!this.params.where) this.params.where = {};
+			const column = columnOrCondition;
+			const condition = [operator, value];
+			const existing = this.params.where[column];
+			if (existing === void 0) this.params.where[column] = condition;
+			else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) this.params.where[column].push(condition);
+			else {
+				let firstCondition;
+				if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") firstCondition = existing;
+				else firstCondition = ["==", existing];
+				this.params.where[column] = [firstCondition, condition];
+			}
+			return this;
+		}
+		/**
+		* Order the results by a specific column.
+		*/
+		orderBy(column, direction = "asc") {
+			this.params.orderBy = [column, direction];
+			return this;
+		}
+		/**
+		* Limit the number of results returned.
+		*/
+		limit(count) {
+			this.params.limit = count;
+			return this;
+		}
+		/**
+		* Skip the first N results.
+		*/
+		offset(count) {
+			this.params.offset = count;
+			return this;
+		}
+		/**
+		* Set a free-text search string if supported by the backend.
+		*/
+		search(searchString) {
+			this.params.searchString = searchString;
+			return this;
+		}
+		/**
+		* Include related entities in the response.
+		* Relations will be populated with full data instead of just IDs.
+		*
+		* @param relations - Relation names to include, or "*" for all.
+		* @example
+		* client.data.posts.include("tags", "author").find()
+		*/
+		include(...relations) {
+			this.params.include = relations;
+			return this;
+		}
+		/**
+		* Execute the find query and return the results as flat rows.
+		*/
+		async find() {
+			return this.collection.find(this.params);
+		}
+		/**
+		* Count the records matching this query.
+		*/
+		async count() {
+			if (!this.collection.count) throw new Error("count() is not supported by this collection client.");
+			return this.collection.count(this.params);
+		}
+		/**
+		* Listen to realtime updates matching this query.
+		*/
+		listen(onUpdate, onError) {
+			if (!this.collection.listen) throw new Error("Listen is only available when RebaseClient is configured with a websocketUrl.");
+			return this.collection.listen(this.params, onUpdate, onError);
+		}
+	};
+	//#endregion
+	//#region src/collection.ts
 	function createCollectionClient(transport, slug, ws) {
 		const basePath = `/data/${slug}`;
 		const client = {
@@ -837,7 +1028,7 @@
 				const qs = buildQueryString(params);
 				const raw = await transport.request(basePath + qs, { method: "GET" });
 				return {
-					data: (raw.data || []).map((row) => rowToEntity(row, slug)),
+					data: raw.data || [],
 					meta: raw.meta
 				};
 			},
@@ -845,28 +1036,28 @@
 				try {
 					const raw = await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "GET" });
 					if (!raw) return void 0;
-					return rowToEntity(raw, slug);
+					return raw;
 				} catch (err) {
-					if (err instanceof RebaseApiError && err.status === 404) return;
+					if (err instanceof _rebasepro_types.RebaseApiError && err.status === 404) return;
 					throw err;
 				}
 			},
 			async create(data, id) {
 				const body = { ...data };
 				if (id !== void 0) body.id = id;
-				return rowToEntity(await transport.request(basePath, {
+				return await transport.request(basePath, {
 					method: "POST",
 					body: JSON.stringify(body)
-				}), slug);
+				});
 			},
 			async update(id, data) {
-				return rowToEntity(await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
+				return await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
 					method: "PUT",
 					body: JSON.stringify(data)
-				}), slug);
+				});
 			},
 			async delete(id) {
-				return transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "DELETE" });
+				await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "DELETE" });
 			},
 			async count(params) {
 				const qs = buildQueryString({
@@ -877,24 +1068,24 @@
 				return (await transport.request(basePath + "/count" + qs, { method: "GET" })).count ?? 0;
 			},
 			where(columnOrCondition, operator, value) {
-				const builder = new _rebasepro_common.QueryBuilder(client);
+				const builder = new SDKQueryBuilder(client);
 				if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
 				return builder.where(columnOrCondition, operator, value);
 			},
 			orderBy(column, direction) {
-				return new _rebasepro_common.QueryBuilder(client).orderBy(column, direction);
+				return new SDKQueryBuilder(client).orderBy(column, direction);
 			},
 			limit(count) {
-				return new _rebasepro_common.QueryBuilder(client).limit(count);
+				return new SDKQueryBuilder(client).limit(count);
 			},
 			offset(count) {
-				return new _rebasepro_common.QueryBuilder(client).offset(count);
+				return new SDKQueryBuilder(client).offset(count);
 			},
 			search(searchString) {
-				return new _rebasepro_common.QueryBuilder(client).search(searchString);
+				return new SDKQueryBuilder(client).search(searchString);
 			},
 			include(...relations) {
-				return new _rebasepro_common.QueryBuilder(client).include(...relations);
+				return new SDKQueryBuilder(client).include(...relations);
 			}
 		};
 		if (ws) {
@@ -906,33 +1097,46 @@
 					filter: params?.where,
 					limit: params?.limit,
 					startAfter: params?.offset ? String(params.offset) : void 0,
-					orderBy: params?.orderBy?.split(":")[0],
-					order: params?.orderBy?.split(":")[1],
+					orderBy: params?.orderBy?.[0],
+					order: params?.orderBy?.[1],
 					searchString: params?.searchString
-				}, (entities) => {
+				}, (incomingRows) => {
 					const currentUpdateId = ++lastUpdateId;
 					const requestedLimit = params?.limit || 20;
 					const offset = params?.offset || 0;
-					onUpdate({
-						data: entities,
-						meta: {
-							total: entities.length,
-							limit: requestedLimit,
-							offset,
-							hasMore: entities.length >= requestedLimit
-						}
-					});
+					const rows = incomingRows;
+					const heuristicTotal = rows.length;
+					const heuristicHasMore = rows.length >= requestedLimit;
 					if (client.count) client.count(params).then((total) => {
 						if (active && currentUpdateId === lastUpdateId) onUpdate({
-							data: entities,
+							data: rows,
 							meta: {
 								total,
 								limit: requestedLimit,
 								offset,
-								hasMore: offset + entities.length < total
+								hasMore: offset + rows.length < total
+							}
+						});
+					}).catch(() => {
+						if (active && currentUpdateId === lastUpdateId) onUpdate({
+							data: rows,
+							meta: {
+								total: heuristicTotal,
+								limit: requestedLimit,
+								offset,
+								hasMore: heuristicHasMore
 							}
 						});
-					}).catch(() => {});
+					});
+					else onUpdate({
+						data: rows,
+						meta: {
+							total: heuristicTotal,
+							limit: requestedLimit,
+							offset,
+							hasMore: heuristicHasMore
+						}
+					});
 				}, onError);
 				return () => {
 					active = false;
@@ -940,11 +1144,11 @@
 				};
 			};
 			client.listenById = (id, onUpdate, onError) => {
-				return ws.listenEntity({
+				return ws.listenOne({
 					path: slug,
-					entityId: String(id)
-				}, (entity) => {
-					if (entity) onUpdate(entity);
+					id: String(id)
+				}, (row) => {
+					if (row) onUpdate(row);
 					else onUpdate(void 0);
 				}, onError);
 			};
@@ -992,10 +1196,12 @@
 			if (!storageId) return path;
 			return `${path}${path.includes("?") ? "&" : "?"}storageId=${encodeURIComponent(storageId)}`;
 		};
-		async function putObject({ file, key, metadata, bucket }) {
+		async function putObject({ file, key, metadata, bucket, public: isPublic }) {
 			const formData = new FormData();
 			formData.append("file", file);
-			if (key) formData.append("key", key);
+			let effectiveKey = key;
+			if (isPublic && effectiveKey && !(0, _rebasepro_types.isPublicStoragePath)(effectiveKey)) effectiveKey = `${_rebasepro_types.PUBLIC_STORAGE_PREFIX}${effectiveKey.replace(/^\/+/, "")}`;
+			if (effectiveKey) formData.append("key", effectiveKey);
 			if (bucket) formData.append("bucket", bucket);
 			if (storageId) formData.append("storageId", storageId);
 			if (metadata) {
@@ -1009,8 +1215,11 @@
 		}
 		async function getSignedUrl(keyOrUrl, bucket) {
 			const cacheKey = bucket ? `${bucket}/${keyOrUrl}` : keyOrUrl;
-			const cached = urlsCache.get(cacheKey);
-			if (cached) return cached;
+			const cachedEntry = urlsCache.get(cacheKey);
+			if (cachedEntry) {
+				if (!cachedEntry.expiresAt || cachedEntry.expiresAt > Date.now()) return cachedEntry.config;
+				urlsCache.delete(cacheKey);
+			}
 			let filePath = keyOrUrl;
 			if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://") || filePath.startsWith("gs://"))) filePath = filePath.substring(filePath.indexOf("://") + 3);
 			if (bucket && filePath && !filePath.startsWith(bucket)) filePath = `${bucket}/${filePath}`;
@@ -1018,15 +1227,32 @@
 				url: null,
 				fileNotFound: true
 			};
+			if ((0, _rebasepro_types.isPublicStoragePath)(filePath)) {
+				const publicConfig = { url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`) };
+				urlsCache.set(cacheKey, { config: publicConfig });
+				return publicConfig;
+			}
 			try {
 				const result = await transport.request(withStorageId(`/storage/metadata/${filePath}`));
-				const activeToken = await transport.resolveToken();
-				const tokenQuery = activeToken ? `?token=${activeToken}` : "";
+				if (result.data.public) {
+					const publicConfig = {
+						url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`),
+						metadata: result.data
+					};
+					urlsCache.set(cacheKey, { config: publicConfig });
+					return publicConfig;
+				}
+				const scopedToken = result.data.token;
+				const tokenQuery = scopedToken ? `?token=${scopedToken}` : "";
 				const downloadConfig = {
 					url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}${tokenQuery}`),
 					metadata: result.data
 				};
-				urlsCache.set(cacheKey, downloadConfig);
+				const expiresAt = result.data.tokenExpiresIn ? Date.now() + (result.data.tokenExpiresIn - 10) * 1e3 : void 0;
+				urlsCache.set(cacheKey, {
+					config: downloadConfig,
+					expiresAt
+				});
 				return downloadConfig;
 			} catch (e) {
 				if (e instanceof Error && "status" in e && e.status === 404) return {
@@ -1037,16 +1263,13 @@
 			}
 		}
 		async function getObject(key, bucket) {
-			let filePath = key;
-			if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://") || filePath.startsWith("gs://"))) filePath = filePath.substring(filePath.indexOf("://") + 3);
-			if (bucket && filePath && !filePath.startsWith(bucket)) filePath = `${bucket}/${filePath}`;
-			if (!filePath || filePath.trim() === "" || filePath === "/") return null;
-			const url = withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`);
-			const response = await transport.fetchFn(url, { headers: transport.getHeaders ? transport.getHeaders() : {} });
+			const downloadConfig = await getSignedUrl(key, bucket);
+			if (downloadConfig.fileNotFound || !downloadConfig.url) return null;
+			const response = await transport.fetchFn(downloadConfig.url, { headers: {} });
 			if (response.status === 404) return null;
 			if (!response.ok) throw new Error("Failed to get file");
 			const blob = await response.blob();
-			const fileName = filePath.split("/").pop() || "file";
+			const fileName = (bucket ? `${bucket}/${key}` : key).split("/").pop() || "file";
 			return new File([blob], fileName, { type: blob.type });
 		}
 		async function deleteObject(key, bucket) {
@@ -1148,16 +1371,15 @@
 			errorCode: typeof errPayload === "object" ? errPayload.code : payload?.code
 		};
 	}
-	var ApiError = class extends Error {
-		code;
-		error;
-		constructor(message, error, code) {
-			super(message);
-			this.name = "ApiError";
-			this.code = code;
-			this.error = error;
-		}
-	};
+	/**
+	* Low-level realtime WebSocket client.
+	*
+	* @internal Not a stable app-facing API. `createRebaseClient()` constructs and
+	* manages this internally (exposed as `client.ws`, typed by the minimal
+	* `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
+	* package root only because the `@rebasepro/client-postgresql` driver
+	* instantiates it directly; its surface may change without a major bump.
+	*/
 	var RebaseWebSocketClient = class {
 		websocketUrl;
 		ws = null;
@@ -1173,7 +1395,7 @@
 			if (this.listeners.has(event)) this.listeners.get(event).forEach((cb) => cb(...args));
 		}
 		collectionSubscriptions = /* @__PURE__ */ new Map();
-		entitySubscriptions = /* @__PURE__ */ new Map();
+		singleSubscriptions = /* @__PURE__ */ new Map();
 		backendToCollectionKey = /* @__PURE__ */ new Map();
 		backendToEntityKey = /* @__PURE__ */ new Map();
 		pendingRequests = /* @__PURE__ */ new Map();
@@ -1308,7 +1530,7 @@
 							request.message._queuedResolve = request.resolve;
 							request.message._queuedReject = request.reject;
 							this.messageQueue.push(request.message);
-						} else request.reject(new ApiError("Connection closed", "Connection closed"));
+						} else request.reject(new _rebasepro_types.RebaseApiError("Connection closed"));
 						this.pendingRequests.delete(reqId);
 					}
 					this.attemptReconnect();
@@ -1375,7 +1597,7 @@
 			}
 		}
 		/**
-		* Shared logic for re-subscribing a collection or entity subscription
+		* Shared logic for re-subscribing a collection or row subscription
 		* after an auth error is resolved by refreshing credentials.
 		*/
 		resubscribeAfterAuthRefresh(message, subscription, subscriptionKey, idPrefix, backendKeyMap, messageType) {
@@ -1400,7 +1622,7 @@
 					});
 				} else {
 					const { errorMessage, errorCode } = extractMessageError(message);
-					const error = new ApiError(errorMessage, errorMessage, errorCode);
+					const error = new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode });
 					subscription.callbacks.forEach((callback) => {
 						if (callback.onError) callback.onError(error);
 					});
@@ -1421,7 +1643,7 @@
 						if (refreshed && pendingReq.message) this.doSendMessage(pendingReq.message, pendingReq.resolve, pendingReq.reject).catch(pendingReq.reject);
 						else {
 							const { errorMessage, errorCode } = extractMessageError(message);
-							pendingReq.reject(new ApiError(errorMessage, errorMessage, errorCode));
+							pendingReq.reject(new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode }));
 						}
 					}).catch((err) => {
 						pendingReq.reject(err);
@@ -1429,7 +1651,7 @@
 				} else {
 					this.pendingRequests.delete(requestId);
 					const { errorMessage, errorCode } = extractMessageError(message);
-					pendingReq.reject(new ApiError(errorMessage, errorMessage, errorCode));
+					pendingReq.reject(new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode }));
 				}
 				else {
 					this.pendingRequests.delete(requestId);
@@ -1442,14 +1664,14 @@
 				if (subscriptionKey) {
 					const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
 					if (collectionSub) {
-						const incomingEntities = message.entities || [];
-						const entities = this.mergeEntities(collectionSub.latestData, incomingEntities);
-						collectionSub.latestData = entities;
+						const incomingRows = message.rows || [];
+						const rows = this.mergeRows(collectionSub.latestData, incomingRows);
+						collectionSub.latestData = rows;
 						collectionSub.lastUpdated = Date.now();
 						collectionSub.isInitialDataReceived = true;
 						collectionSub.callbacks.forEach((callback) => {
 							try {
-								callback.onUpdate(entities);
+								callback.onUpdate(rows);
 							} catch (error) {
 								console.error("Error in collection subscription callback:", error);
 								if (callback.onError) callback.onError(error instanceof Error ? error : new Error(String(error)));
@@ -1459,21 +1681,22 @@
 					}
 				}
 			}
-			if (subscriptionId && type === "collection_entity_patch") {
+			if (subscriptionId && type === "collection_patch") {
 				const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
 				if (subscriptionKey) {
 					const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
 					if (collectionSub && collectionSub.isInitialDataReceived && collectionSub.latestData) {
-						const patchEntity = message.entity ?? null;
-						const patchEntityId = message.entityId;
+						const patchWireEntity = message.row ?? null;
+						const patchEntityId = message.id;
+						const patchRow = patchWireEntity ? patchWireEntity : null;
 						let updated;
-						if (patchEntity === null || patchEntity === void 0) updated = collectionSub.latestData.filter((e) => String(e.id) !== String(patchEntityId));
+						if (patchRow === null) updated = collectionSub.latestData.filter((e) => String(e.id) !== String(patchEntityId));
 						else {
-							const idx = collectionSub.latestData.findIndex((e) => String(e.id) === String(patchEntity.id));
+							const idx = collectionSub.latestData.findIndex((e) => String(e.id) === String(patchRow.id));
 							if (idx >= 0) {
 								updated = [...collectionSub.latestData];
-								updated[idx] = patchEntity;
-							} else updated = [patchEntity, ...collectionSub.latestData];
+								updated[idx] = patchRow;
+							} else updated = [patchRow, ...collectionSub.latestData];
 						}
 						collectionSub.latestData = updated;
 						collectionSub.lastUpdated = Date.now();
@@ -1489,20 +1712,21 @@
 					}
 				}
 			}
-			if (subscriptionId && type === "entity_update") {
+			if (subscriptionId && type === "single_update") {
 				const subscriptionKey = this.backendToEntityKey.get(subscriptionId);
 				if (subscriptionKey) {
-					const entitySub = this.entitySubscriptions.get(subscriptionKey);
+					const entitySub = this.singleSubscriptions.get(subscriptionKey);
 					if (entitySub) {
-						const entity = message.entity ?? null;
-						entitySub.latestData = entity;
+						const wireEntity = message.row ?? null;
+						const row = wireEntity ? wireEntity : null;
+						entitySub.latestData = row;
 						entitySub.lastUpdated = Date.now();
 						entitySub.isInitialDataReceived = true;
 						entitySub.callbacks.forEach((callback) => {
 							try {
-								callback.onUpdate(entity);
+								callback.onUpdate(row);
 							} catch (error) {
-								console.error("Error in entity subscription callback:", error);
+								console.error("Error in row subscription callback:", error);
 								if (callback.onError) callback.onError(error instanceof Error ? error : new Error(String(error)));
 							}
 						});
@@ -1520,7 +1744,7 @@
 							return;
 						}
 						const { errorMessage, errorCode } = extractMessageError(message);
-						const error = new ApiError(errorMessage, errorMessage, errorCode);
+						const error = new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode });
 						collectionSub.callbacks.forEach((callback) => {
 							if (callback.onError) callback.onError(error);
 						});
@@ -1529,14 +1753,14 @@
 				}
 				const entityKey = this.backendToEntityKey.get(subscriptionId);
 				if (entityKey) {
-					const entitySub = this.entitySubscriptions.get(entityKey);
+					const entitySub = this.singleSubscriptions.get(entityKey);
 					if (entitySub) {
 						if (this.isAuthError(message)) {
-							this.resubscribeAfterAuthRefresh(message, entitySub, entityKey, "entity", this.backendToEntityKey, "subscribe_entity");
+							this.resubscribeAfterAuthRefresh(message, entitySub, entityKey, "row", this.backendToEntityKey, "subscribe_one");
 							return;
 						}
 						const { errorMessage, errorCode } = extractMessageError(message);
-						const error = new ApiError(errorMessage, errorMessage, errorCode);
+						const error = new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode });
 						entitySub.callbacks.forEach((callback) => {
 							if (callback.onError) callback.onError(error);
 						});
@@ -1550,7 +1774,7 @@
 				if (message.type === "ERROR" || message.error) {
 					if (callback.onError) {
 						const { errorMessage, errorCode } = extractMessageError(message);
-						callback.onError(new ApiError(errorMessage, errorMessage, errorCode));
+						callback.onError(new _rebasepro_types.RebaseApiError(errorMessage, { code: errorCode }));
 					}
 				} else callback.onUpdate(message);
 			}
@@ -1624,15 +1848,14 @@
 			if (message.type !== "AUTHENTICATE" && this.getAuthToken && !this.isAuthenticated) try {
 				await this.ensureAuthenticated();
 			} catch (error) {
-				const errorMessage = error instanceof Error ? error.message : "Authentication required";
-				reject(new ApiError(errorMessage, errorMessage));
+				reject(new _rebasepro_types.RebaseApiError(error instanceof Error ? error.message : "Authentication required"));
 				return;
 			}
 			const requestId = message.requestId || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 			message.requestId = requestId;
 			const expectsResponse = ![
 				"subscribe_collection",
-				"subscribe_entity",
+				"subscribe_one",
 				"unsubscribe",
 				"join_channel",
 				"leave_channel",
@@ -1645,7 +1868,7 @@
 				const timeoutHandle = setTimeout(() => {
 					if (this.pendingRequests.has(requestId)) {
 						this.pendingRequests.delete(requestId);
-						reject(new ApiError("Request timed out", "Request timed out"));
+						reject(new _rebasepro_types.RebaseApiError("Request timed out"));
 					}
 				}, this.requestTimeoutMs);
 				this.pendingRequests.set(requestId, {
@@ -1665,30 +1888,30 @@
 				if (!expectsResponse) resolve(void 0);
 			} catch (error) {
 				if (expectsResponse) this.pendingRequests.delete(requestId);
-				reject(new ApiError("Failed to send message", error instanceof Error ? error.message : "Unknown error"));
+				reject(new _rebasepro_types.RebaseApiError("Failed to send message", { cause: error }));
 			}
 		}
 		async fetchCollection(props) {
 			return (await this.sendMessage({
 				type: "FETCH_COLLECTION",
 				payload: props
-			})).entities || [];
+			})).rows || [];
 		}
-		async fetchEntity(props) {
+		async fetchOne(props) {
 			return (await this.sendMessage({
-				type: "FETCH_ENTITY",
+				type: "FETCH_ONE",
 				payload: props
-			})).entity ?? void 0;
+			})).row ?? void 0;
 		}
-		async saveEntity(props) {
+		async save(props) {
 			return (await this.sendMessage({
-				type: "SAVE_ENTITY",
+				type: "SAVE",
 				payload: props
-			})).entity;
+			})).row;
 		}
-		async deleteEntity(props) {
+		async delete(props) {
 			await this.sendMessage({
-				type: "DELETE_ENTITY",
+				type: "DELETE",
 				payload: props
 			});
 		}
@@ -1713,21 +1936,21 @@
 		async fetchCurrentDatabase() {
 			return (await this.sendMessage({ type: "FETCH_CURRENT_DATABASE" })).database;
 		}
-		async checkUniqueField(path, name, value, entityId, collection) {
+		async checkUniqueField(path, name, value, id, collection) {
 			return (await this.sendMessage({
 				type: "CHECK_UNIQUE_FIELD",
 				payload: {
 					path,
 					name,
 					value,
-					entityId,
+					id,
 					collection
 				}
 			})).isUnique;
 		}
-		async countEntities(props) {
+		async count(props) {
 			return (await this.sendMessage({
-				type: "COUNT_ENTITIES",
+				type: "COUNT",
 				payload: props
 			})).count;
 		}
@@ -1819,33 +2042,31 @@
 			return val;
 		}
 		/**
-		* Merge incoming entities with cached data, preserving cached references
-		* for entities whose values haven't changed. This avoids unnecessary
-		* React re-renders when the server refetches all entities but most
+		* Merge incoming rows with cached data, preserving cached references
+		* for rows whose values haven't changed. This avoids unnecessary
+		* React re-renders when the server refetches all rows but most
 		* haven't actually changed.
 		*/
-		mergeEntities(cached, incoming) {
+		mergeRows(cached, incoming) {
 			if (!cached || cached.length === 0) return incoming;
 			const cachedById = /* @__PURE__ */ new Map();
-			for (const entity of cached) cachedById.set(entity.id, entity);
-			return incoming.map((incomingEntity) => {
-				const cachedEntity = cachedById.get(incomingEntity.id);
-				if (!cachedEntity) return incomingEntity;
-				if (cachedEntity.path === incomingEntity.path) {
-					const normCached = this.normalizeForComparison(cachedEntity.values);
-					const normIncoming = this.normalizeForComparison(incomingEntity.values);
-					if (this.deepEqual(normCached, normIncoming)) return cachedEntity;
-					else {
-						const mismatches = {};
-						const allKeys = new Set([...Object.keys(normCached), ...Object.keys(normIncoming)]);
-						for (const key of allKeys) if (!this.deepEqual(normCached[key], normIncoming[key])) mismatches[key] = {
-							cached: normCached[key],
-							incoming: normIncoming[key]
-						};
-						console.debug(`[RebaseWS] Row ${incomingEntity.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
-					}
+			for (const row of cached) cachedById.set(row.id, row);
+			return incoming.map((incomingRow) => {
+				const cachedRow = cachedById.get(incomingRow.id);
+				if (!cachedRow) return incomingRow;
+				const normCached = this.normalizeForComparison(cachedRow);
+				const normIncoming = this.normalizeForComparison(incomingRow);
+				if (this.deepEqual(normCached, normIncoming)) return cachedRow;
+				else {
+					const mismatches = {};
+					const allKeys = new Set([...Object.keys(normCached), ...Object.keys(normIncoming)]);
+					for (const key of allKeys) if (!this.deepEqual(normCached[key], normIncoming[key])) mismatches[key] = {
+						cached: normCached[key],
+						incoming: normIncoming[key]
+					};
+					console.debug(`[RebaseWS] Row ${incomingRow.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
 				}
-				return incomingEntity;
+				return incomingRow;
 			});
 		}
 		listenCollection(props, onUpdate, onError) {
@@ -1913,10 +2134,10 @@
 				}
 			};
 		}
-		listenEntity(props, onUpdate, onError) {
-			const subscriptionKey = this.createEntitySubscriptionKey(props);
+		listenOne(props, onUpdate, onError) {
+			const subscriptionKey = this.createSingleSubscriptionKey(props);
 			const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-			const existingSubscription = this.entitySubscriptions.get(subscriptionKey);
+			const existingSubscription = this.singleSubscriptions.get(subscriptionKey);
 			if (existingSubscription) {
 				const callbackMap = existingSubscription.callbacks;
 				callbackMap.set(callbackId, {
@@ -1926,13 +2147,13 @@
 				if (existingSubscription.latestData !== void 0 && existingSubscription.isInitialDataReceived) try {
 					onUpdate(existingSubscription.latestData);
 				} catch (error) {
-					console.error("Error in entity subscription callback:", error);
+					console.error("Error in row subscription callback:", error);
 					if (onError) onError(error instanceof Error ? error : new Error(String(error)));
 				}
 				return () => {
 					callbackMap.delete(callbackId);
 					if (callbackMap.size === 0) {
-						this.entitySubscriptions.delete(subscriptionKey);
+						this.singleSubscriptions.delete(subscriptionKey);
 						this.backendToEntityKey.delete(existingSubscription.backendSubscriptionId);
 						if (this.isConnected && this.ws) this.sendMessage({
 							type: "unsubscribe",
@@ -1947,14 +2168,14 @@
 				onUpdate,
 				onError
 			});
-			this.entitySubscriptions.set(subscriptionKey, {
+			this.singleSubscriptions.set(subscriptionKey, {
 				backendSubscriptionId,
 				callbacks: callbackMap,
 				props
 			});
 			this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
 			this.sendMessage({
-				type: "subscribe_entity",
+				type: "subscribe_one",
 				payload: {
 					...props,
 					subscriptionId: backendSubscriptionId
@@ -1963,12 +2184,12 @@
 				if (onError) onError(error);
 			});
 			return () => {
-				const subscription = this.entitySubscriptions.get(subscriptionKey);
+				const subscription = this.singleSubscriptions.get(subscriptionKey);
 				if (subscription) {
 					const callbacks = subscription.callbacks;
 					callbacks.delete(callbackId);
 					if (callbacks.size === 0) {
-						this.entitySubscriptions.delete(subscriptionKey);
+						this.singleSubscriptions.delete(subscriptionKey);
 						this.backendToEntityKey.delete(subscription.backendSubscriptionId);
 						if (this.isConnected && this.ws) this.sendMessage({
 							type: "unsubscribe",
@@ -1984,7 +2205,7 @@
 		* we need to re-register everything to resume receiving updates.
 		*/
 		resubscribeAll() {
-			console.debug(`[WS] Re-subscribing: ${this.collectionSubscriptions.size} collection(s), ${this.entitySubscriptions.size} entity(ies)`);
+			console.debug(`[WS] Re-subscribing: ${this.collectionSubscriptions.size} collection(s), ${this.singleSubscriptions.size} row(ies)`);
 			for (const [key, sub] of this.collectionSubscriptions.entries()) {
 				const oldBackendId = sub.backendSubscriptionId;
 				const newBackendId = `collection_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
@@ -2001,20 +2222,20 @@
 					console.error("[WS] Failed to re-subscribe collection:", key, error);
 				});
 			}
-			for (const [key, sub] of this.entitySubscriptions.entries()) {
+			for (const [key, sub] of this.singleSubscriptions.entries()) {
 				const oldBackendId = sub.backendSubscriptionId;
 				const newBackendId = `entity_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 				sub.backendSubscriptionId = newBackendId;
 				this.backendToEntityKey.delete(oldBackendId);
 				this.backendToEntityKey.set(newBackendId, key);
 				this.sendMessage({
-					type: "subscribe_entity",
+					type: "subscribe_one",
 					payload: {
 						...sub.props,
 						subscriptionId: newBackendId
 					}
 				}).catch((error) => {
-					console.error("[WS] Failed to re-subscribe entity:", key, error);
+					console.error("[WS] Failed to re-subscribe row:", key, error);
 				});
 			}
 		}
@@ -2037,8 +2258,8 @@
 				return value;
 			});
 		}
-		createEntitySubscriptionKey(props) {
-			return `${props.path}|${props.entityId}`;
+		createSingleSubscriptionKey(props) {
+			return `${props.path}|${props.id}`;
 		}
 	};
 	//#endregion
@@ -2126,7 +2347,45 @@
 				return false;
 			}
 		});
+		/**
+		* Suggest the closest known collection key for a mistyped accessor.
+		* Uses edit-distance-1 and prefix matching — no external dependency.
+		*/
+		function suggestCollection(prop, knownKeys) {
+			const prefixMatch = knownKeys.find((k) => k.startsWith(prop) || prop.startsWith(k));
+			if (prefixMatch) return prefixMatch;
+			for (const key of knownKeys) {
+				if (Math.abs(key.length - prop.length) > 1) continue;
+				let diffs = 0;
+				const longer = key.length >= prop.length ? key : prop;
+				const shorter = key.length >= prop.length ? prop : key;
+				if (longer.length === shorter.length) for (let i = 0; i < longer.length; i++) {
+					if (longer[i] !== shorter[i]) {
+						if (i + 1 < longer.length && longer[i] === shorter[i + 1] && longer[i + 1] === shorter[i]) {
+							diffs++;
+							i++;
+							if (diffs > 1) break;
+							continue;
+						}
+						diffs++;
+					}
+					if (diffs > 1) break;
+				}
+				else {
+					let li = 0;
+					let si = 0;
+					while (li < longer.length) {
+						if (si < shorter.length && longer[li] === shorter[si]) si++;
+						else diffs++;
+						li++;
+						if (diffs > 1) break;
+					}
+				}
+				if (diffs <= 1) return key;
+			}
+		}
 		const collectionClients = /* @__PURE__ */ new Map();
+		let untypedWarned = false;
 		function collection(slug) {
 			if (!collectionClients.has(slug)) collectionClients.set(slug, createCollectionClient(transport, slug, ws));
 			return collectionClients.get(slug);
@@ -2135,7 +2394,19 @@
 			if (prop === "collection") return collection;
 			if (typeof prop === "symbol") return void 0;
 			if (typeof prop === "string" && prop !== "then" && prop !== "toJSON" && prop !== "$$typeof") {
-				if (options.collections && prop in options.collections) return collection(options.collections[prop]);
+				if (options.collections) {
+					if (prop in options.collections) return collection(options.collections[prop]);
+					const knownKeys = Object.keys(options.collections);
+					const suggestion = suggestCollection(prop, knownKeys);
+					let msg = `Unknown collection accessor "${prop}". Known collections: ${knownKeys.join(", ")}.`;
+					if (suggestion) msg += ` Did you mean "${suggestion}"?`;
+					msg += ` Use data.collection("<slug>") for dynamic slugs.`;
+					throw new _rebasepro_types.RebaseClientError(msg);
+				}
+				if (!untypedWarned) {
+					untypedWarned = true;
+					console.warn(`[Rebase] Untyped data access detected (client.data.${prop}). Collection names are resolved via snake_case conversion, which may cause silent 404s at request time. Pass a \`collections\` dictionary to createRebaseClient() or use the generated SDK for type-safe access.`);
+				}
 				return collection((0, _rebasepro_utils.toSnakeCase)(prop));
 			}
 		} });
@@ -2164,20 +2435,28 @@
 				});
 				return res.data ?? res;
 			},
-			data: dataProxy,
-			email: void 0
+			data: dataProxy
 		};
 	}
 	//#endregion
-	exports.ApiError = ApiError;
-	exports.ClientStorageSourceRegistry = ClientStorageSourceRegistry;
 	Object.defineProperty(exports, "QueryBuilder", {
 		enumerable: true,
 		get: function() {
 			return _rebasepro_common.QueryBuilder;
 		}
 	});
-	exports.RebaseApiError = RebaseApiError;
+	Object.defineProperty(exports, "RebaseApiError", {
+		enumerable: true,
+		get: function() {
+			return _rebasepro_types.RebaseApiError;
+		}
+	});
+	Object.defineProperty(exports, "RebaseClientError", {
+		enumerable: true,
+		get: function() {
+			return _rebasepro_types.RebaseClientError;
+		}
+	});
 	exports.RebaseWebSocketClient = RebaseWebSocketClient;
 	Object.defineProperty(exports, "and", {
 		enumerable: true,
@@ -2185,31 +2464,21 @@
 			return _rebasepro_common.and;
 		}
 	});
-	exports.buildQueryString = buildQueryString;
 	Object.defineProperty(exports, "cond", {
 		enumerable: true,
 		get: function() {
 			return _rebasepro_common.cond;
 		}
 	});
-	exports.createAdmin = createAdmin;
-	exports.createApiKeys = createApiKeys;
-	exports.createAuth = createAuth;
-	exports.createCollectionClient = createCollectionClient;
 	exports.createCookieStorage = createCookieStorage;
-	exports.createCron = createCron;
-	exports.createFunctionsClient = createFunctionsClient;
 	exports.createMemoryStorage = createMemoryStorage;
 	exports.createRebaseClient = createRebaseClient;
-	exports.createStorage = createStorage;
-	exports.createTransport = createTransport;
 	Object.defineProperty(exports, "or", {
 		enumerable: true,
 		get: function() {
 			return _rebasepro_common.or;
 		}
 	});
-	exports.rebaseReviver = rebaseReviver;
 });
 
 //# sourceMappingURL=index.umd.js.map