@rebasepro/client 0.8.0 → 0.9.1-canary.09aaf62

package/dist/index.es.js

@@ -1,5 +1,5 @@
-import { QueryBuilder, and, cond, or, serializeFilter, serializeLogicalCondition } from "@rebasepro/common";
-import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
+import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, Vector, isPublicStoragePath } from "@rebasepro/types";
+import { COMPOSITE_ID_SEPARATOR, QueryBuilder, and, buildCompositeId, cond, or, serializeFilter, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
 import { toSnakeCase } from "@rebasepro/utils";
 //#region src/reviver.ts
 function rebaseReviver(_key, value) {
@@ -30,25 +30,16 @@ function rebaseReviver(_key, value) {
 }
 //#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 = 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) {
@@ -97,8 +88,7 @@ function createTransport(config) {
 		} 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()) {
@@ -121,7 +111,11 @@ function createTransport(config) {
 				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 RebaseApiError$1(String(getErrorField(retryBody, "message") || fallbackMessage || `Request failed with status ${retryRes.status}`), {
+						status: retryRes.status,
+						code: getErrorField(retryBody, "code"),
+						details: getErrorField(retryBody, "details")
+					});
 				}
 				return retryBody;
 			}
@@ -129,7 +123,11 @@ function createTransport(config) {
 		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 RebaseApiError$1(String(getErrorField(body, "message") || fallbackMessage || `Request failed with status ${res.status}`), {
+				status: res.status,
+				code: getErrorField(body, "code"),
+				details: getErrorField(body, "details")
+			});
 		}
 		return body;
 	}
@@ -165,6 +163,29 @@ function createTransport(config) {
 }
 //#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 {
@@ -195,11 +216,20 @@ function createAuth(transport, options) {
 	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;
 	}
@@ -207,7 +237,11 @@ function createAuth(transport, options) {
 		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 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 {
@@ -215,7 +249,7 @@ function createAuth(transport, options) {
 		} catch (e) {}
 	}
 	function saveSession(session) {
-		if (!persistSession) return;
+		if (!persistSession || authFlowMode === "cookie") return;
 		try {
 			storage.setItem(STORAGE_KEY, JSON.stringify(session));
 		} catch (e) {}
@@ -232,28 +266,53 @@ function createAuth(transport, options) {
 		} 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 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);
@@ -269,7 +328,8 @@ function createAuth(transport, options) {
 			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);
@@ -290,7 +350,8 @@ function createAuth(transport, options) {
 		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);
@@ -313,7 +374,8 @@ function createAuth(transport, options) {
 		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);
@@ -331,7 +393,8 @@ function createAuth(transport, options) {
 			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);
@@ -350,7 +413,8 @@ function createAuth(transport, options) {
 		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);
@@ -426,10 +490,11 @@ function createAuth(transport, options) {
 	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;
@@ -441,20 +506,35 @@ function createAuth(transport, options) {
 		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);
@@ -466,6 +546,18 @@ function createAuth(transport, options) {
 	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",
@@ -539,7 +631,8 @@ function createAuth(transport, options) {
 		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);
@@ -586,21 +679,29 @@ function createAuth(transport, options) {
 	}
 	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,
@@ -620,6 +721,7 @@ function createAuth(transport, options) {
 		signOut,
 		refreshSession,
 		getUser,
+		findUserByEmail,
 		updateUser,
 		resetPasswordForEmail,
 		resetPassword,
@@ -633,7 +735,8 @@ function createAuth(transport, options) {
 		revokeAllSessions,
 		getAuthConfig,
 		getSession,
-		onAuthStateChange
+		onAuthStateChange,
+		isInitialized: () => isInitialized
 	};
 }
 function createCookieStorage(options = {}) {
@@ -766,6 +869,32 @@ function createCron(transport, options) {
 	};
 }
 //#endregion
+//#region src/backups.ts
+function createBackups(transport, options) {
+	const backupsPath = options?.backupsPath || "/admin/backups";
+	async function list() {
+		return transport.request(backupsPath, { method: "GET" });
+	}
+	/**
+	* Download a backup's bytes. Uses an authenticated fetch (not the JSON
+	* transport) so the octet-stream response comes back as a Blob.
+	*/
+	async function download(key) {
+		const token = await transport.resolveToken();
+		const url = `${transport.baseUrl}${transport.apiPath}${backupsPath}/download?key=${encodeURIComponent(key)}`;
+		const res = await fetch(url, {
+			method: "GET",
+			headers: token ? { Authorization: `Bearer ${token}` } : {}
+		});
+		if (!res.ok) throw new Error(`Failed to download backup (${res.status})`);
+		return res.blob();
+	}
+	return {
+		list,
+		download
+	};
+}
+//#endregion
 //#region src/api-keys.ts
 /**
 * Creates a client for managing API keys via the admin routes.
@@ -810,20 +939,108 @@ function createApiKeys(transport, options) {
 	};
 }
 //#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, and not when it was created with realtime: false.");
+		return this.collection.listen(this.params, onUpdate, onError);
+	}
+};
+//#endregion
+//#region src/collection.ts
 function createCollectionClient(transport, slug, ws) {
 	const basePath = `/data/${slug}`;
 	const client = {
@@ -831,7 +1048,7 @@ function createCollectionClient(transport, slug, ws) {
 			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
 			};
 		},
@@ -839,7 +1056,7 @@ function createCollectionClient(transport, slug, ws) {
 			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;
 				throw err;
@@ -848,19 +1065,30 @@ function createCollectionClient(transport, slug, ws) {
 		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 createMany(data, options) {
+			if (!Array.isArray(data)) throw new TypeError("createMany expects an array of records.");
+			if (data.length === 0) return [];
+			return (await transport.request(`${basePath}/bulk`, {
+				method: "POST",
+				body: JSON.stringify({
+					rows: data,
+					...options?.upsert ? { upsert: true } : {}
+				})
+			})).data || [];
 		},
 		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({
@@ -871,24 +1099,24 @@ function createCollectionClient(transport, slug, ws) {
 			return (await transport.request(basePath + "/count" + qs, { method: "GET" })).count ?? 0;
 		},
 		where(columnOrCondition, operator, value) {
-			const builder = new 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 QueryBuilder(client).orderBy(column, direction);
+			return new SDKQueryBuilder(client).orderBy(column, direction);
 		},
 		limit(count) {
-			return new QueryBuilder(client).limit(count);
+			return new SDKQueryBuilder(client).limit(count);
 		},
 		offset(count) {
-			return new QueryBuilder(client).offset(count);
+			return new SDKQueryBuilder(client).offset(count);
 		},
 		search(searchString) {
-			return new QueryBuilder(client).search(searchString);
+			return new SDKQueryBuilder(client).search(searchString);
 		},
 		include(...relations) {
-			return new QueryBuilder(client).include(...relations);
+			return new SDKQueryBuilder(client).include(...relations);
 		}
 	};
 	if (ws) {
@@ -900,33 +1128,46 @@ function createCollectionClient(transport, slug, ws) {
 				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(() => {});
+				}).catch(() => {
+					if (active && currentUpdateId === lastUpdateId) onUpdate({
+						data: rows,
+						meta: {
+							total: heuristicTotal,
+							limit: requestedLimit,
+							offset,
+							hasMore: heuristicHasMore
+						}
+					});
+				});
+				else onUpdate({
+					data: rows,
+					meta: {
+						total: heuristicTotal,
+						limit: requestedLimit,
+						offset,
+						hasMore: heuristicHasMore
+					}
+				});
 			}, onError);
 			return () => {
 				active = false;
@@ -934,11 +1175,11 @@ function createCollectionClient(transport, slug, ws) {
 			};
 		};
 		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);
 		};
@@ -986,10 +1227,12 @@ function createStorage(transport, storageId) {
 		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 && !isPublicStoragePath(effectiveKey)) effectiveKey = `${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) {
@@ -1003,8 +1246,11 @@ function createStorage(transport, storageId) {
 	}
 	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}`;
@@ -1012,15 +1258,32 @@ function createStorage(transport, storageId) {
 			url: null,
 			fileNotFound: true
 		};
+		if (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 {
@@ -1031,16 +1294,13 @@ function createStorage(transport, storageId) {
 		}
 	}
 	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) {
@@ -1137,27 +1397,45 @@ var ClientStorageSourceRegistry = class ClientStorageSourceRegistry {
 function extractMessageError(message) {
 	const payload = message.payload;
 	const errPayload = payload?.error;
+	const errorMessage = typeof errPayload === "object" ? errPayload.message : payload?.message || (typeof errPayload === "string" ? errPayload : void 0) || message.error || "Unknown error";
+	const errorCode = typeof errPayload === "object" ? errPayload.code : payload?.code;
 	return {
-		errorMessage: typeof errPayload === "object" ? errPayload.message : payload?.message || (typeof errPayload === "string" ? errPayload : void 0) || message.error || "Unknown error",
-		errorCode: typeof errPayload === "object" ? errPayload.code : payload?.code
+		errorMessage: typeof errorMessage === "string" ? errorMessage : errorMessage == null ? "Unknown error" : JSON.stringify(errorMessage),
+		errorCode
 	};
 }
-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-postgres` driver
+* instantiates it directly; its surface may change without a major bump.
+*/
 var RebaseWebSocketClient = class {
 	websocketUrl;
 	ws = null;
 	getAuthToken;
 	subscriptions = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
+	/** Channel-name → handlers, for broadcast and presence frames. */
+	channelHandlers = /* @__PURE__ */ new Map();
+	/** Subscribe to broadcast/presence frames for one channel. */
+	onChannelMessage(channel, handler) {
+		if (!this.channelHandlers.has(channel)) this.channelHandlers.set(channel, /* @__PURE__ */ new Set());
+		this.channelHandlers.get(channel).add(handler);
+		return () => {
+			const handlers = this.channelHandlers.get(channel);
+			if (!handlers) return;
+			handlers.delete(handler);
+			if (handlers.size === 0) this.channelHandlers.delete(channel);
+		};
+	}
+	/** Notified after the socket comes back, so channels can re-join. */
+	onReconnect(handler) {
+		return this.on("reconnect", handler);
+	}
 	on(event, cb) {
 		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
 		this.listeners.get(event).add(cb);
@@ -1167,7 +1445,7 @@ var RebaseWebSocketClient = class {
 		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();
@@ -1176,6 +1454,7 @@ var RebaseWebSocketClient = class {
 	isConnected = false;
 	messageQueue = [];
 	requestTimeoutMs = 3e4;
+	subscriptionTimeoutMs = 3e4;
 	reconnectTimeout = null;
 	isAuthenticated = false;
 	authPromise = null;
@@ -1281,6 +1560,7 @@ var RebaseWebSocketClient = class {
 				this.emit(wasReconnect ? "reconnect" : "connect");
 				this.processMessageQueue();
 				if (wasReconnect) this.resubscribeAll();
+				this.armPendingSubscribeWatchdogs();
 			};
 			this.ws.onmessage = (event) => {
 				try {
@@ -1295,6 +1575,7 @@ var RebaseWebSocketClient = class {
 				this.isConnected = false;
 				this.isAuthenticated = false;
 				this.authPromise = null;
+				this.suspendSubscribeWatchdogs();
 				this.emit("disconnect");
 				for (const [reqId, request] of this.pendingRequests.entries()) {
 					if (reqId.startsWith("auth_")) request.reject(/* @__PURE__ */ new Error("Connection closed during authentication"));
@@ -1302,7 +1583,7 @@ var RebaseWebSocketClient = class {
 						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 RebaseApiError$1("Connection closed"));
 					this.pendingRequests.delete(reqId);
 				}
 				this.attemptReconnect();
@@ -1326,6 +1607,7 @@ var RebaseWebSocketClient = class {
 	attemptReconnect() {
 		if (this.reconnectAttempts >= this.maxReconnectAttempts) {
 			console.error("Max reconnection attempts reached");
+			this.failAllPendingSubscriptions(new RebaseApiError$1("Connection lost", { code: "CONNECTION_LOST" }));
 			return;
 		}
 		this.reconnectAttempts++;
@@ -1369,7 +1651,7 @@ var RebaseWebSocketClient = class {
 		}
 	}
 	/**
-	* 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) {
@@ -1380,29 +1662,18 @@ var RebaseWebSocketClient = class {
 				subscription.backendSubscriptionId = newBackendId;
 				backendKeyMap.delete(oldBackendId);
 				backendKeyMap.set(newBackendId, subscriptionKey);
-				this.sendMessage({
-					type: messageType,
-					payload: {
-						...subscription.props,
-						subscriptionId: newBackendId
-					}
-				}).catch((error) => {
-					console.error(`[WS] Failed to re-subscribe ${idPrefix} after auth refresh:`, subscriptionKey, error);
-					subscription.callbacks.forEach((callback) => {
-						if (callback.onError) callback.onError(error);
-					});
-				});
-			} else {
-				const { errorMessage, errorCode } = extractMessageError(message);
-				const error = new ApiError(errorMessage, errorMessage, errorCode);
-				subscription.callbacks.forEach((callback) => {
-					if (callback.onError) callback.onError(error);
-				});
+				if (messageType === "subscribe_collection") this.sendCollectionSubscribe(subscriptionKey);
+				else this.sendEntitySubscribe(subscriptionKey);
+				return;
 			}
+			const { errorMessage, errorCode } = extractMessageError(message);
+			const error = new RebaseApiError$1(errorMessage, { code: errorCode });
+			if (messageType === "subscribe_collection") this.failCollectionSubscription(subscriptionKey, error);
+			else this.failEntitySubscription(subscriptionKey, error);
 		}).catch((err) => {
-			subscription.callbacks.forEach((callback) => {
-				if (callback.onError) callback.onError(err);
-			});
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (messageType === "subscribe_collection") this.failCollectionSubscription(subscriptionKey, error);
+			else this.failEntitySubscription(subscriptionKey, error);
 		});
 	}
 	handleWebSocketMessage(message) {
@@ -1415,7 +1686,7 @@ var RebaseWebSocketClient = class {
 					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 RebaseApiError$1(errorMessage, { code: errorCode }));
 					}
 				}).catch((err) => {
 					pendingReq.reject(err);
@@ -1423,7 +1694,7 @@ var RebaseWebSocketClient = class {
 			} else {
 				this.pendingRequests.delete(requestId);
 				const { errorMessage, errorCode } = extractMessageError(message);
-				pendingReq.reject(new ApiError(errorMessage, errorMessage, errorCode));
+				pendingReq.reject(new RebaseApiError$1(errorMessage, { code: errorCode }));
 			}
 			else {
 				this.pendingRequests.delete(requestId);
@@ -1431,19 +1702,33 @@ var RebaseWebSocketClient = class {
 			}
 			return;
 		}
+		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff")) {
+			const handlers = this.channelHandlers.get(message.channel);
+			if (handlers) for (const handler of [...handlers]) try {
+				handler(message);
+			} catch (error) {
+				console.error("Error in channel handler:", error);
+			}
+			return;
+		}
 		if (subscriptionId && type === "collection_update") {
 			const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
 			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 updatePks = message.pks;
+					if (updatePks) collectionSub.pks = updatePks;
+					const rows = this.mergeRows(collectionSub.latestData, incomingRows, collectionSub.pks);
+					collectionSub.latestData = rows;
 					collectionSub.lastUpdated = Date.now();
 					collectionSub.isInitialDataReceived = true;
+					if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+					collectionSub.subscribeTimeout = void 0;
+					collectionSub.subscribeInFlight = false;
 					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)));
@@ -1453,21 +1738,24 @@ var RebaseWebSocketClient = class {
 				}
 			}
 		}
-		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 patchMessage = message;
+					const patchEntityId = patchMessage.id;
+					if (patchMessage.pks) collectionSub.pks = patchMessage.pks;
+					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) => this.rowAddress(e, collectionSub.pks) !== String(patchEntityId));
 					else {
-						const idx = collectionSub.latestData.findIndex((e) => String(e.id) === String(patchEntity.id));
+						const idx = collectionSub.latestData.findIndex((e) => this.rowAddress(e, collectionSub.pks) === String(patchEntityId));
 						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();
@@ -1483,20 +1771,24 @@ var RebaseWebSocketClient = class {
 				}
 			}
 		}
-		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;
+					if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+					entitySub.subscribeTimeout = void 0;
+					entitySub.subscribeInFlight = false;
 					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)));
 						}
 					});
@@ -1513,8 +1805,11 @@ var RebaseWebSocketClient = class {
 						this.resubscribeAfterAuthRefresh(message, collectionSub, collectionKey, "collection", this.backendToCollectionKey, "subscribe_collection");
 						return;
 					}
+					if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+					collectionSub.subscribeTimeout = void 0;
+					collectionSub.subscribeInFlight = false;
 					const { errorMessage, errorCode } = extractMessageError(message);
-					const error = new ApiError(errorMessage, errorMessage, errorCode);
+					const error = new RebaseApiError$1(errorMessage, { code: errorCode });
 					collectionSub.callbacks.forEach((callback) => {
 						if (callback.onError) callback.onError(error);
 					});
@@ -1523,14 +1818,17 @@ var RebaseWebSocketClient = class {
 			}
 			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;
 					}
+					if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+					entitySub.subscribeTimeout = void 0;
+					entitySub.subscribeInFlight = false;
 					const { errorMessage, errorCode } = extractMessageError(message);
-					const error = new ApiError(errorMessage, errorMessage, errorCode);
+					const error = new RebaseApiError$1(errorMessage, { code: errorCode });
 					entitySub.callbacks.forEach((callback) => {
 						if (callback.onError) callback.onError(error);
 					});
@@ -1544,7 +1842,7 @@ var RebaseWebSocketClient = class {
 			if (message.type === "ERROR" || message.error) {
 				if (callback.onError) {
 					const { errorMessage, errorCode } = extractMessageError(message);
-					callback.onError(new ApiError(errorMessage, errorMessage, errorCode));
+					callback.onError(new RebaseApiError$1(errorMessage, { code: errorCode }));
 				}
 			} else callback.onUpdate(message);
 		}
@@ -1601,6 +1899,10 @@ var RebaseWebSocketClient = class {
 			throw error;
 		}
 	}
+	/**
+	* Public because `RebaseRealtimeChannel` sends channel frames through it.
+	* Not part of the stable surface — prefer `client.realtime.channel(name)`.
+	*/
 	sendMessage(message) {
 		const queuedMsg = message;
 		if (queuedMsg._queuedResolve && queuedMsg._queuedReject) return this.doSendMessage(message, queuedMsg._queuedResolve, queuedMsg._queuedReject);
@@ -1618,15 +1920,14 @@ var RebaseWebSocketClient = class {
 		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 RebaseApiError$1(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",
@@ -1639,7 +1940,7 @@ var RebaseWebSocketClient = class {
 			const timeoutHandle = setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
 					this.pendingRequests.delete(requestId);
-					reject(new ApiError("Request timed out", "Request timed out"));
+					reject(new RebaseApiError$1("Request timed out"));
 				}
 			}, this.requestTimeoutMs);
 			this.pendingRequests.set(requestId, {
@@ -1659,30 +1960,30 @@ var RebaseWebSocketClient = class {
 			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 RebaseApiError$1("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
 		});
 	}
@@ -1707,21 +2008,21 @@ var RebaseWebSocketClient = class {
 	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;
 	}
@@ -1813,33 +2114,53 @@ var RebaseWebSocketClient = class {
 		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
+	* The address of a row, for matching it against another copy of itself.
+	*
+	* A row is exactly its columns and carries no address, so it is derived
+	* from the key columns the server named — including the ordinary case where
+	* that key is `id`, which the server reports like any other.
+	*
+	* Undefined when there are no keys, which means the server could not
+	* resolve any: such rows genuinely cannot be recognised, and guessing at a
+	* column called `id` would be inventing an identity for a table that has
+	* none.
+	*/
+	rowAddress(row, pks) {
+		if (!pks || pks.length === 0) return void 0;
+		const address = buildCompositeId(row, pks);
+		if (!address || address.split(COMPOSITE_ID_SEPARATOR).every((part) => part === "")) return void 0;
+		return address;
+	}
+	/**
+	* 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, pks) {
 		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) {
+			const address = this.rowAddress(row, pks);
+			if (address !== void 0) cachedById.set(address, row);
+		}
+		return incoming.map((incomingRow) => {
+			const address = this.rowAddress(incomingRow, pks);
+			const cachedRow = address === void 0 ? void 0 : cachedById.get(address);
+			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 ${address} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
 			}
-			return incomingEntity;
+			return incomingRow;
 		});
 	}
 	listenCollection(props, onUpdate, onError) {
@@ -1858,9 +2179,12 @@ var RebaseWebSocketClient = class {
 				console.error("Error in collection subscription callback:", error);
 				if (onError) onError(error instanceof Error ? error : new Error(String(error)));
 			}
+			else if (!existingSubscription.subscribeInFlight) this.sendCollectionSubscribe(subscriptionKey);
 			return () => {
 				callbackMap.delete(callbackId);
 				if (callbackMap.size === 0) {
+					if (this.collectionSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+					if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
 					this.collectionSubscriptions.delete(subscriptionKey);
 					this.backendToCollectionKey.delete(existingSubscription.backendSubscriptionId);
 					if (this.isConnected && this.ws) this.sendMessage({
@@ -1882,21 +2206,14 @@ var RebaseWebSocketClient = class {
 			props
 		});
 		this.backendToCollectionKey.set(backendSubscriptionId, subscriptionKey);
-		this.sendMessage({
-			type: "subscribe_collection",
-			payload: {
-				...props,
-				subscriptionId: backendSubscriptionId
-			}
-		}).catch((error) => {
-			if (onError) onError(error);
-		});
+		this.sendCollectionSubscribe(subscriptionKey);
 		return () => {
 			const subscription = this.collectionSubscriptions.get(subscriptionKey);
 			if (subscription) {
 				const callbacks = subscription.callbacks;
 				callbacks.delete(callbackId);
 				if (callbacks.size === 0) {
+					if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
 					this.collectionSubscriptions.delete(subscriptionKey);
 					this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
 					if (this.isConnected && this.ws) this.sendMessage({
@@ -1907,10 +2224,10 @@ var RebaseWebSocketClient = class {
 			}
 		};
 	}
-	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, {
@@ -1920,13 +2237,16 @@ var RebaseWebSocketClient = class {
 			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)));
 			}
+			else if (!existingSubscription.subscribeInFlight) this.sendEntitySubscribe(subscriptionKey);
 			return () => {
 				callbackMap.delete(callbackId);
 				if (callbackMap.size === 0) {
-					this.entitySubscriptions.delete(subscriptionKey);
+					if (this.singleSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+					if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
+					this.singleSubscriptions.delete(subscriptionKey);
 					this.backendToEntityKey.delete(existingSubscription.backendSubscriptionId);
 					if (this.isConnected && this.ws) this.sendMessage({
 						type: "unsubscribe",
@@ -1941,28 +2261,20 @@ var RebaseWebSocketClient = class {
 			onUpdate,
 			onError
 		});
-		this.entitySubscriptions.set(subscriptionKey, {
+		this.singleSubscriptions.set(subscriptionKey, {
 			backendSubscriptionId,
 			callbacks: callbackMap,
 			props
 		});
 		this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
-		this.sendMessage({
-			type: "subscribe_entity",
-			payload: {
-				...props,
-				subscriptionId: backendSubscriptionId
-			}
-		}).catch((error) => {
-			if (onError) onError(error);
-		});
+		this.sendEntitySubscribe(subscriptionKey);
 		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",
@@ -1973,43 +2285,178 @@ var RebaseWebSocketClient = class {
 		};
 	}
 	/**
+	* Send a `subscribe_collection` for an already-registered subscription and
+	* arm its watchdog.
+	*
+	* Every path that registers a collection subscription goes through here, so
+	* that a subscribe which never lands — a rejected send, or a server that
+	* never answers — always ends up in `failCollectionSubscription` rather than
+	* leaving the entry parked with `isInitialDataReceived === false` forever.
+	*/
+	sendCollectionSubscribe(subscriptionKey) {
+		const subscription = this.collectionSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		const backendSubscriptionId = subscription.backendSubscriptionId;
+		subscription.subscribeInFlight = true;
+		if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+		subscription.subscribeTimeout = void 0;
+		if (this.isConnected) this.sendCollectionSubscribeWatchdog(subscriptionKey);
+		this.sendMessage({
+			type: "subscribe_collection",
+			payload: {
+				...subscription.props,
+				subscriptionId: backendSubscriptionId
+			}
+		}).catch((error) => {
+			const current = this.collectionSubscriptions.get(subscriptionKey);
+			if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+			this.failCollectionSubscription(subscriptionKey, error instanceof Error ? error : new Error(String(error)));
+		});
+	}
+	/** The `listenOne` counterpart of {@link sendCollectionSubscribe}. */
+	sendEntitySubscribe(subscriptionKey) {
+		const subscription = this.singleSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		const backendSubscriptionId = subscription.backendSubscriptionId;
+		subscription.subscribeInFlight = true;
+		if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+		subscription.subscribeTimeout = void 0;
+		if (this.isConnected) this.sendEntitySubscribeWatchdog(subscriptionKey);
+		this.sendMessage({
+			type: "subscribe_one",
+			payload: {
+				...subscription.props,
+				subscriptionId: backendSubscriptionId
+			}
+		}).catch((error) => {
+			const current = this.singleSubscriptions.get(subscriptionKey);
+			if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+			this.failEntitySubscription(subscriptionKey, error instanceof Error ? error : new Error(String(error)));
+		});
+	}
+	/**
+	* Report a subscribe failure to every listener and drop the registration.
+	*
+	* Dropping it is the point: the callbacks stay live (their components are
+	* still mounted and have been told), but the next `listenCollection` for
+	* these params finds no entry and issues a fresh subscribe instead of
+	* silently attaching to a dead one.
+	*/
+	failCollectionSubscription(subscriptionKey, error) {
+		const subscription = this.collectionSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+		subscription.subscribeInFlight = false;
+		this.collectionSubscriptions.delete(subscriptionKey);
+		this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
+		subscription.callbacks.forEach((callback) => {
+			if (callback.onError) try {
+				callback.onError(error);
+			} catch (callbackError) {
+				console.error("Error in collection subscription error callback:", callbackError);
+			}
+		});
+	}
+	/** The `listenOne` counterpart of {@link failCollectionSubscription}. */
+	failEntitySubscription(subscriptionKey, error) {
+		const subscription = this.singleSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+		subscription.subscribeInFlight = false;
+		this.singleSubscriptions.delete(subscriptionKey);
+		this.backendToEntityKey.delete(subscription.backendSubscriptionId);
+		subscription.callbacks.forEach((callback) => {
+			if (callback.onError) try {
+				callback.onError(error);
+			} catch (callbackError) {
+				console.error("Error in row subscription error callback:", callbackError);
+			}
+		});
+	}
+	/**
+	* Stop the watchdogs without failing anything — used when the socket drops,
+	* since the reconnect path re-subscribes everything anyway and a watchdog
+	* firing mid-reconnect would tear down healthy subscriptions.
+	*/
+	suspendSubscribeWatchdogs() {
+		for (const sub of this.collectionSubscriptions.values()) {
+			if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+			sub.subscribeTimeout = void 0;
+			sub.subscribeInFlight = false;
+		}
+		for (const sub of this.singleSubscriptions.values()) {
+			if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+			sub.subscribeTimeout = void 0;
+			sub.subscribeInFlight = false;
+		}
+	}
+	/**
+	* Arm watchdogs for subscribes that were requested while offline and have
+	* just been flushed to the socket. Their timers were deliberately not set at
+	* request time, so without this they would have no timeout at all.
+	*/
+	armPendingSubscribeWatchdogs() {
+		for (const [key, sub] of this.collectionSubscriptions.entries()) if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendCollectionSubscribeWatchdog(key);
+		for (const [key, sub] of this.singleSubscriptions.entries()) if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendEntitySubscribeWatchdog(key);
+	}
+	sendCollectionSubscribeWatchdog(subscriptionKey) {
+		const subscription = this.collectionSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		const backendSubscriptionId = subscription.backendSubscriptionId;
+		subscription.subscribeTimeout = setTimeout(() => {
+			const current = this.collectionSubscriptions.get(subscriptionKey);
+			if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+			if (!current.subscribeInFlight) return;
+			this.failCollectionSubscription(subscriptionKey, new RebaseApiError$1("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" }));
+		}, this.subscriptionTimeoutMs);
+	}
+	sendEntitySubscribeWatchdog(subscriptionKey) {
+		const subscription = this.singleSubscriptions.get(subscriptionKey);
+		if (!subscription) return;
+		const backendSubscriptionId = subscription.backendSubscriptionId;
+		subscription.subscribeTimeout = setTimeout(() => {
+			const current = this.singleSubscriptions.get(subscriptionKey);
+			if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+			if (!current.subscribeInFlight) return;
+			this.failEntitySubscription(subscriptionKey, new RebaseApiError$1("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" }));
+		}, this.subscriptionTimeoutMs);
+	}
+	/**
+	* Fail every subscription that never received data. Called when reconnection
+	* is given up on, so views surface an error instead of spinning forever.
+	*/
+	failAllPendingSubscriptions(error) {
+		for (const key of [...this.collectionSubscriptions.keys()]) {
+			const sub = this.collectionSubscriptions.get(key);
+			if (sub && !sub.isInitialDataReceived) this.failCollectionSubscription(key, error);
+		}
+		for (const key of [...this.singleSubscriptions.keys()]) {
+			const sub = this.singleSubscriptions.get(key);
+			if (sub && !sub.isInitialDataReceived) this.failEntitySubscription(key, error);
+		}
+	}
+	/**
 	* Re-send all active subscriptions to the backend after a reconnect.
 	* The server wipes subscription state when a client disconnects, so
 	* 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)}`;
 			sub.backendSubscriptionId = newBackendId;
 			this.backendToCollectionKey.delete(oldBackendId);
 			this.backendToCollectionKey.set(newBackendId, key);
-			this.sendMessage({
-				type: "subscribe_collection",
-				payload: {
-					...sub.props,
-					subscriptionId: newBackendId
-				}
-			}).catch((error) => {
-				console.error("[WS] Failed to re-subscribe collection:", key, error);
-			});
+			this.sendCollectionSubscribe(key);
 		}
-		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",
-				payload: {
-					...sub.props,
-					subscriptionId: newBackendId
-				}
-			}).catch((error) => {
-				console.error("[WS] Failed to re-subscribe entity:", key, error);
-			});
+			this.sendEntitySubscribe(key);
 		}
 	}
 	createCollectionSubscriptionKey(props) {
@@ -2031,8 +2478,192 @@ var RebaseWebSocketClient = class {
 			return value;
 		});
 	}
-	createEntitySubscriptionKey(props) {
-		return `${props.path}|${props.entityId}`;
+	createSingleSubscriptionKey(props) {
+		return `${props.path}|${props.id}`;
+	}
+};
+//#endregion
+//#region src/realtime-channel.ts
+/**
+* Re-send presence comfortably inside the server's 30s expiry.
+*
+* Two-thirds of the window: one lost heartbeat still leaves time for the next
+* before the entry is reaped, so a single dropped frame is not a disappearance.
+*/
+var PRESENCE_HEARTBEAT_MS = 2e4;
+var RebaseRealtimeChannel = class {
+	name;
+	transport;
+	presenceHandlers = /* @__PURE__ */ new Set();
+	broadcastHandlers = /* @__PURE__ */ new Set();
+	unsubscribers = [];
+	/** Last known roster, kept so handlers always get a full picture. */
+	presences = {};
+	/** What this client last tracked, replayed on reconnect and heartbeat. */
+	trackedState = null;
+	heartbeat = null;
+	joined = false;
+	constructor(name, transport) {
+		this.name = name;
+		this.transport = transport;
+	}
+	/**
+	* Join the channel and ask for the current roster.
+	*
+	* Called automatically by `track`, `broadcast`, `onPresence` and
+	* `onBroadcast`; calling it directly is only needed to start receiving
+	* before there is anything to send.
+	*/
+	async join() {
+		if (this.joined) return;
+		this.joined = true;
+		this.unsubscribers.push(this.transport.onChannelMessage(this.name, (message) => this.handle(message)));
+		this.unsubscribers.push(this.transport.onReconnect(() => {
+			this.rejoin();
+		}));
+		await this.transport.sendMessage({
+			type: "join_channel",
+			channel: this.name
+		});
+		await this.transport.sendMessage({
+			type: "presence_state",
+			channel: this.name
+		});
+	}
+	async rejoin() {
+		try {
+			await this.transport.sendMessage({
+				type: "join_channel",
+				channel: this.name
+			});
+			await this.transport.sendMessage({
+				type: "presence_state",
+				channel: this.name
+			});
+			if (this.trackedState) await this.transport.sendMessage({
+				type: "presence_track",
+				channel: this.name,
+				state: this.trackedState
+			});
+		} catch {}
+	}
+	/**
+	* Publish this client's presence state, and keep publishing it.
+	*
+	* Calling `track` again replaces the state (and restarts the heartbeat),
+	* which is how you update e.g. a cursor position.
+	*/
+	async track(state) {
+		await this.join();
+		this.trackedState = state;
+		await this.transport.sendMessage({
+			type: "presence_track",
+			channel: this.name,
+			state
+		});
+		if (!this.heartbeat) {
+			this.heartbeat = setInterval(() => {
+				if (!this.trackedState) return;
+				this.transport.sendMessage({
+					type: "presence_track",
+					channel: this.name,
+					state: this.trackedState
+				}).catch(() => {});
+			}, PRESENCE_HEARTBEAT_MS);
+			this.heartbeat.unref?.();
+		}
+	}
+	/** Stop publishing presence, without leaving the channel. */
+	async untrack() {
+		this.stopHeartbeat();
+		this.trackedState = null;
+		if (this.joined) await this.transport.sendMessage({
+			type: "presence_untrack",
+			channel: this.name
+		});
+	}
+	/**
+	* Observe the roster. The handler fires immediately with what is already
+	* known, then on every change.
+	*/
+	onPresence(handler) {
+		this.presenceHandlers.add(handler);
+		this.join();
+		if (Object.keys(this.presences).length > 0) handler({ ...this.presences });
+		return () => this.presenceHandlers.delete(handler);
+	}
+	/** Send a broadcast. The sender does not receive its own message. */
+	async broadcast(event, payload) {
+		await this.join();
+		await this.transport.sendMessage({
+			type: "broadcast",
+			channel: this.name,
+			event,
+			payload
+		});
+	}
+	onBroadcast(eventOrHandler, maybeHandler) {
+		const wrapped = typeof eventOrHandler === "string" ? (e) => {
+			if (e.event === eventOrHandler) maybeHandler(e.payload);
+		} : eventOrHandler;
+		this.broadcastHandlers.add(wrapped);
+		this.join();
+		return () => this.broadcastHandlers.delete(wrapped);
+	}
+	/** Leave the channel and release every listener and timer. */
+	async leave() {
+		this.stopHeartbeat();
+		this.trackedState = null;
+		this.presences = {};
+		this.presenceHandlers.clear();
+		this.broadcastHandlers.clear();
+		for (const off of this.unsubscribers) off();
+		this.unsubscribers = [];
+		if (this.joined) {
+			this.joined = false;
+			await this.transport.sendMessage({
+				type: "leave_channel",
+				channel: this.name
+			});
+		}
+	}
+	stopHeartbeat() {
+		if (this.heartbeat) {
+			clearInterval(this.heartbeat);
+			this.heartbeat = null;
+		}
+	}
+	/** Fold an incoming frame into the roster and fan it out. */
+	handle(message) {
+		switch (message.type) {
+			case "presence_state":
+				this.presences = message.presences ?? {};
+				this.emitPresence();
+				break;
+			case "presence_diff": {
+				const joins = message.joins ?? {};
+				const leaves = message.leaves ?? {};
+				for (const [id, state] of Object.entries(joins)) this.presences[id] = state;
+				for (const id of Object.keys(leaves)) delete this.presences[id];
+				this.emitPresence({
+					joins,
+					leaves
+				});
+				break;
+			}
+			case "broadcast": {
+				const event = {
+					event: message.event,
+					payload: message.payload
+				};
+				for (const handler of this.broadcastHandlers) handler(event);
+				break;
+			}
+		}
+	}
+	emitPresence(diff) {
+		const snapshot = { ...this.presences };
+		for (const handler of this.presenceHandlers) handler(snapshot, diff);
 	}
 };
 //#endregion
@@ -2063,6 +2694,7 @@ function createRebaseClient(options) {
 	const auth = createAuth(transport, options.auth);
 	const admin = createAdmin(transport, options.admin);
 	const cron = createCron(transport, options.cron);
+	const backups = createBackups(transport);
 	const apiKeys = createApiKeys(transport, options.apiKeys);
 	const storage = createStorage(transport);
 	const functions = createFunctionsClient(transport);
@@ -2083,8 +2715,10 @@ function createRebaseClient(options) {
 		});
 		return storageSourcesPromise;
 	};
-	const resolvedWsUrl = options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl);
+	const resolvedWsUrl = options.realtime !== false ? options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl) : void 0;
 	let ws;
+	/** One channel object per name — see `realtime.channel`. */
+	const realtimeChannels = /* @__PURE__ */ new Map();
 	if (resolvedWsUrl) {
 		ws = new RebaseWebSocketClient({
 			websocketUrl: resolvedWsUrl,
@@ -2120,7 +2754,45 @@ function createRebaseClient(options) {
 			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);
@@ -2129,7 +2801,19 @@ function createRebaseClient(options) {
 		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 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(toSnakeCase(prop));
 		}
 	} });
@@ -2137,6 +2821,7 @@ function createRebaseClient(options) {
 		auth,
 		admin,
 		cron,
+		backups,
 		apiKeys,
 		functions,
 		storage,
@@ -2144,6 +2829,36 @@ function createRebaseClient(options) {
 		createStorageSource,
 		fetchStorageSources,
 		ws,
+		realtime: { 
+		/**
+		* Join a broadcast/presence channel.
+		*
+		* Repeated calls with the same name return the same channel, so
+		* separate components can attach handlers without each opening its
+		* own membership — and `leave()` from one would otherwise silently
+		* cut off the others.
+		*/
+channel: (name) => {
+			if (!ws) throw new RebaseClientError("Realtime is disabled on this client (realtime: false), so channels are unavailable.");
+			let existing = realtimeChannels.get(name);
+			if (!existing) {
+				existing = new RebaseRealtimeChannel(name, ws);
+				realtimeChannels.set(name, existing);
+			}
+			return existing;
+		} },
+		/**
+		* Release the realtime socket and its reconnect timer.
+		*
+		* Until this returns, the open socket keeps the Node event loop alive
+		* and the process will not exit on its own. Safe to call when realtime
+		* was never started, and safe to call twice.
+		*/
+		close: () => {
+			for (const channel of realtimeChannels.values()) channel.leave();
+			realtimeChannels.clear();
+			ws?.disconnect();
+		},
 		setToken: transport.setToken,
 		setAuthTokenGetter: transport.setAuthTokenGetter,
 		setOnUnauthorized: transport.setOnUnauthorized,
@@ -2158,11 +2873,10 @@ function createRebaseClient(options) {
 			});
 			return res.data ?? res;
 		},
-		data: dataProxy,
-		email: void 0
+		data: dataProxy
 	};
 }
 //#endregion
-export { ApiError, ClientStorageSourceRegistry, QueryBuilder, RebaseApiError, RebaseWebSocketClient, and, buildQueryString, cond, createAdmin, createApiKeys, createAuth, createCollectionClient, createCookieStorage, createCron, createFunctionsClient, createMemoryStorage, createRebaseClient, createStorage, createTransport, or, rebaseReviver };
+export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseRealtimeChannel, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
 
 //# sourceMappingURL=index.es.js.map