@rebasepro/client 0.9.1-canary.fd3754b → 0.10.0

package/dist/index.es.js

@@ -1,5 +1,5 @@
 import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, Vector, isPublicStoragePath } from "@rebasepro/types";
-import { QueryBuilder, and, cond, or, serializeFilter, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
+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) {
@@ -54,6 +54,28 @@ function buildQueryString(params) {
 	}
 	return parts.length > 0 ? "?" + parts.join("&") : "";
 }
+/**
+* The base every request and every caller-built URL resolves against.
+*
+* `baseUrl` is optional because the common production shape is a Rebase
+* backend serving its own SPA, where the API is simply the page's origin.
+* Leaving it unset is therefore the *correct* configuration there — and the
+* one that keeps working when a second hostname (a custom domain) points at
+* the same app.
+*
+* When unset in a browser this resolves to the page origin rather than "".
+* Requests behave identically either way, but the empty string is a trap for
+* anything that builds a URL from `client.baseUrl`: `new URL("" + path)`
+* throws, so apps "fixed" it by baking an absolute host into their bundle —
+* which is exactly what breaks the day a custom domain is added, and which no
+* amount of CORS configuration repairs, because a SameSite=Lax auth cookie is
+* not sent cross-site either.
+*/
+function resolveBaseUrl(configured) {
+	if (configured) return configured.replace(/\/$/, "");
+	if (typeof window !== "undefined" && window.location?.origin) return window.location.origin;
+	return "";
+}
 function createTransport(config) {
 	const fetchFn = config.fetch || globalThis.fetch;
 	const apiPath = config.apiPath || "/api";
@@ -68,7 +90,7 @@ function createTransport(config) {
 		};
 	}
 	async function request(path, init) {
-		const url = (config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "") + apiPath + path;
+		const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 		let activeToken = token;
 		if (tokenGetter) try {
 			const fetched = await tokenGetter();
@@ -143,7 +165,7 @@ function createTransport(config) {
 			onUnauthorizedHandler = handler;
 		},
 		get baseUrl() {
-			return config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "";
+			return resolveBaseUrl(config.baseUrl);
 		},
 		get apiPath() {
 			return apiPath;
@@ -605,6 +627,30 @@ function createAuth(transport, options) {
 			})
 		});
 	}
+	/**
+	* Link an OAuth provider to the **currently signed-in** account.
+	*
+	* Use this when `signIn*` failed with `EMAIL_NOT_VERIFIED` — an account
+	* with that email already exists under a different sign-in method — or to
+	* attach a provider whose email differs from the account's.
+	*
+	* The payload is the same one the provider's sign-in method takes, e.g.
+	* `linkProvider("google", { idToken })`.
+	*
+	* Unlike sign-in, this does not require the provider to have verified the
+	* email, and the emails need not match: the active session already proves
+	* account ownership.
+	*
+	* Throws `IDENTITY_ALREADY_LINKED` (409) if that provider identity is
+	* attached to a different user. Succeeds idempotently (`alreadyLinked:
+	* true`) if it is already attached to the current one.
+	*/
+	async function linkProvider(providerId, payload) {
+		return transport.request(authPath + "/link/" + providerId, {
+			method: "POST",
+			body: JSON.stringify(payload)
+		});
+	}
 	async function sendVerificationEmail() {
 		return transport.request(authPath + "/send-verification", { method: "POST" });
 	}
@@ -726,6 +772,7 @@ function createAuth(transport, options) {
 		resetPasswordForEmail,
 		resetPassword,
 		changePassword,
+		linkProvider,
 		sendVerificationEmail,
 		verifyEmail,
 		sendMagicLink,
@@ -1035,7 +1082,7 @@ var SDKQueryBuilder = class {
 	* 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.");
+		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);
 	}
 };
@@ -1070,6 +1117,17 @@ function createCollectionClient(transport, slug, ws) {
 				body: JSON.stringify(body)
 			});
 		},
+		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 await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
 				method: "PUT",
@@ -1386,12 +1444,29 @@ 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
 	};
 }
 /**
+* Broadcast and presence frames.
+*
+* Fire-and-forget (the server sends no response envelope), and exempt from the
+* client-side auth gate — a public channel is usable without an account.
+*/
+var CHANNEL_MESSAGE_TYPES = new Set([
+	"join_channel",
+	"leave_channel",
+	"broadcast",
+	"presence_track",
+	"presence_untrack",
+	"presence_state",
+	"channel_history"
+]);
+/**
 * Low-level realtime WebSocket client.
 *
 * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
@@ -1406,6 +1481,36 @@ var RebaseWebSocketClient = class {
 	getAuthToken;
 	subscriptions = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
+	/** Channel-name → handlers, for broadcast and presence frames. */
+	channelHandlers = /* @__PURE__ */ new Map();
+	/** Set by `close()`. Blocks any later operation from silently redialling. */
+	closedByCaller = false;
+	/**
+	* Whether a socket exists at all (open or still opening).
+	*
+	* Lets callers distinguish "authenticate the live socket" from "there is
+	* nothing to authenticate yet", without that question forcing a dial.
+	*/
+	get hasSocket() {
+		return this.ws !== null;
+	}
+	/** So the "no WebSocket in this environment" warning is said once, not per call. */
+	warnedNoWebSocket = false;
+	/** 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);
@@ -1424,6 +1529,7 @@ var RebaseWebSocketClient = class {
 	isConnected = false;
 	messageQueue = [];
 	requestTimeoutMs = 3e4;
+	subscriptionTimeoutMs = 3e4;
 	reconnectTimeout = null;
 	isAuthenticated = false;
 	authPromise = null;
@@ -1435,8 +1541,25 @@ var RebaseWebSocketClient = class {
 		this.getAuthToken = config.getAuthToken;
 		this.onUnauthorized = config.onUnauthorized;
 		this.WebSocketConstructor = config.WebSocket || (typeof WebSocket !== "undefined" ? WebSocket : void 0);
-		if (!this.WebSocketConstructor) console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
-		else this.initWebSocket();
+	}
+	/**
+	* Open the socket if it is not open (or opening) already.
+	*
+	* Idempotent, synchronous, and safe to call on every operation that needs a
+	* live socket — `initWebSocket` already no-ops on an open socket and is
+	* re-entrant, since the reconnect path has always called it.
+	*/
+	ensureConnected() {
+		if (this.closedByCaller) return;
+		if (!this.WebSocketConstructor) {
+			if (!this.warnedNoWebSocket) {
+				this.warnedNoWebSocket = true;
+				console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
+			}
+			return;
+		}
+		if (this.ws || this.reconnectTimeout) return;
+		this.initWebSocket();
 	}
 	/**
 	* Authenticate the WebSocket connection
@@ -1486,7 +1609,16 @@ var RebaseWebSocketClient = class {
 			});
 		}
 	}
-	disconnect() {
+	/**
+	* Drop the socket.
+	*
+	* `permanent` distinguishes the two callers. Signing out drops the socket
+	* but the client stays usable — a later subscribe should reconnect
+	* anonymously. `client.close()` is the caller saying they are done, and
+	* must not be undone by a stray queued frame.
+	*/
+	disconnect(permanent = false) {
+		if (permanent) this.closedByCaller = true;
 		this.isAuthenticated = false;
 		this.authPromise = null;
 		if (this.reconnectTimeout) {
@@ -1529,6 +1661,7 @@ var RebaseWebSocketClient = class {
 				this.emit(wasReconnect ? "reconnect" : "connect");
 				this.processMessageQueue();
 				if (wasReconnect) this.resubscribeAll();
+				this.armPendingSubscribeWatchdogs();
 			};
 			this.ws.onmessage = (event) => {
 				try {
@@ -1543,6 +1676,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"));
@@ -1574,6 +1708,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++;
@@ -1628,29 +1763,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 RebaseApiError$1(errorMessage, { code: 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) {
@@ -1679,16 +1803,30 @@ var RebaseWebSocketClient = class {
 			}
 			return;
 		}
+		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history")) {
+			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 incomingRows = message.rows || [];
-					const rows = this.mergeRows(collectionSub.latestData, incomingRows);
+					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(rows);
@@ -1707,12 +1845,14 @@ var RebaseWebSocketClient = class {
 				const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
 				if (collectionSub && collectionSub.isInitialDataReceived && collectionSub.latestData) {
 					const patchWireEntity = message.row ?? null;
-					const patchEntityId = message.id;
+					const patchMessage = message;
+					const patchEntityId = patchMessage.id;
+					if (patchMessage.pks) collectionSub.pks = patchMessage.pks;
 					const patchRow = patchWireEntity ? patchWireEntity : null;
 					let updated;
-					if (patchRow === null) 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(patchRow.id));
+						const idx = collectionSub.latestData.findIndex((e) => this.rowAddress(e, collectionSub.pks) === String(patchEntityId));
 						if (idx >= 0) {
 							updated = [...collectionSub.latestData];
 							updated[idx] = patchRow;
@@ -1742,6 +1882,9 @@ var RebaseWebSocketClient = class {
 					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(row);
@@ -1763,6 +1906,9 @@ 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 RebaseApiError$1(errorMessage, { code: errorCode });
 					collectionSub.callbacks.forEach((callback) => {
@@ -1779,6 +1925,9 @@ var RebaseWebSocketClient = class {
 						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 RebaseApiError$1(errorMessage, { code: errorCode });
 					entitySub.callbacks.forEach((callback) => {
@@ -1851,21 +2000,28 @@ 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);
-		if (!this.isConnected || !this.ws) return new Promise((resolve, reject) => {
-			const queueable = message;
-			queueable._queuedResolve = resolve;
-			queueable._queuedReject = reject;
-			this.messageQueue.push(message);
-		});
+		if (!this.isConnected || !this.ws) {
+			this.ensureConnected();
+			return new Promise((resolve, reject) => {
+				const queueable = message;
+				queueable._queuedResolve = resolve;
+				queueable._queuedReject = reject;
+				this.messageQueue.push(message);
+			});
+		}
 		return new Promise((resolve, reject) => {
 			this.doSendMessage(message, resolve, reject);
 		});
 	}
 	async doSendMessage(message, resolve, reject) {
-		if (message.type !== "AUTHENTICATE" && this.getAuthToken && !this.isAuthenticated) try {
+		if (message.type !== "AUTHENTICATE" && !CHANNEL_MESSAGE_TYPES.has(message.type) && this.getAuthToken && !this.isAuthenticated) try {
 			await this.ensureAuthenticated();
 		} catch (error) {
 			reject(new RebaseApiError$1(error instanceof Error ? error.message : "Authentication required"));
@@ -1873,17 +2029,7 @@ var RebaseWebSocketClient = class {
 		}
 		const requestId = message.requestId || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		message.requestId = requestId;
-		const expectsResponse = ![
-			"subscribe_collection",
-			"subscribe_one",
-			"unsubscribe",
-			"join_channel",
-			"leave_channel",
-			"broadcast",
-			"presence_track",
-			"presence_untrack",
-			"presence_state"
-		].includes(message.type);
+		const expectsResponse = !(message.type === "subscribe_collection" || message.type === "subscribe_one" || message.type === "unsubscribe" || CHANNEL_MESSAGE_TYPES.has(message.type));
 		if (expectsResponse && !this.pendingRequests.has(requestId)) {
 			const timeoutHandle = setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
@@ -1953,6 +2099,9 @@ var RebaseWebSocketClient = class {
 	async fetchAvailableRoles() {
 		return (await this.sendMessage({ type: "FETCH_ROLES" })).roles || [];
 	}
+	async fetchApplicationRoles() {
+		return (await this.sendMessage({ type: "FETCH_APPLICATION_ROLES" })).roles || [];
+	}
 	async fetchCurrentDatabase() {
 		return (await this.sendMessage({ type: "FETCH_CURRENT_DATABASE" })).database;
 	}
@@ -2062,17 +2211,39 @@ var RebaseWebSocketClient = class {
 		return val;
 	}
 	/**
+	* 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.
 	*/
-	mergeRows(cached, incoming) {
+	mergeRows(cached, incoming, pks) {
 		if (!cached || cached.length === 0) return incoming;
 		const cachedById = /* @__PURE__ */ new Map();
-		for (const row of cached) cachedById.set(row.id, row);
+		for (const row of cached) {
+			const address = this.rowAddress(row, pks);
+			if (address !== void 0) cachedById.set(address, row);
+		}
 		return incoming.map((incomingRow) => {
-			const cachedRow = cachedById.get(incomingRow.id);
+			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);
@@ -2084,12 +2255,13 @@ var RebaseWebSocketClient = class {
 					cached: normCached[key],
 					incoming: normIncoming[key]
 				};
-				console.debug(`[RebaseWS] Row ${incomingRow.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
+				console.debug(`[RebaseWS] Row ${address} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
 			}
 			return incomingRow;
 		});
 	}
 	listenCollection(props, onUpdate, onError) {
+		this.ensureConnected();
 		const subscriptionKey = this.createCollectionSubscriptionKey(props);
 		const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		const existingSubscription = this.collectionSubscriptions.get(subscriptionKey);
@@ -2105,9 +2277,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({
@@ -2129,21 +2304,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({
@@ -2155,6 +2323,7 @@ var RebaseWebSocketClient = class {
 		};
 	}
 	listenOne(props, onUpdate, onError) {
+		this.ensureConnected();
 		const subscriptionKey = this.createSingleSubscriptionKey(props);
 		const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		const existingSubscription = this.singleSubscriptions.get(subscriptionKey);
@@ -2170,9 +2339,12 @@ var RebaseWebSocketClient = class {
 				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) {
+					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({
@@ -2194,15 +2366,7 @@ var RebaseWebSocketClient = class {
 			props
 		});
 		this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
-		this.sendMessage({
-			type: "subscribe_one",
-			payload: {
-				...props,
-				subscriptionId: backendSubscriptionId
-			}
-		}).catch((error) => {
-			if (onError) onError(error);
-		});
+		this.sendEntitySubscribe(subscriptionKey);
 		return () => {
 			const subscription = this.singleSubscriptions.get(subscriptionKey);
 			if (subscription) {
@@ -2220,6 +2384,157 @@ 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.
@@ -2232,15 +2547,7 @@ var RebaseWebSocketClient = class {
 			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.singleSubscriptions.entries()) {
 			const oldBackendId = sub.backendSubscriptionId;
@@ -2248,15 +2555,7 @@ var RebaseWebSocketClient = class {
 			sub.backendSubscriptionId = newBackendId;
 			this.backendToEntityKey.delete(oldBackendId);
 			this.backendToEntityKey.set(newBackendId, key);
-			this.sendMessage({
-				type: "subscribe_one",
-				payload: {
-					...sub.props,
-					subscriptionId: newBackendId
-				}
-			}).catch((error) => {
-				console.error("[WS] Failed to re-subscribe row:", key, error);
-			});
+			this.sendEntitySubscribe(key);
 		}
 	}
 	createCollectionSubscriptionKey(props) {
@@ -2283,6 +2582,379 @@ var RebaseWebSocketClient = class {
 	}
 };
 //#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;
+/**
+* How long live messages are held back waiting for a catch-up response.
+*
+* Short, because the cost of waiting is visible — on a collaborative document
+* this is a stall in everyone else's edits appearing. Long enough that a slow
+* replay of a busy channel is not abandoned needlessly.
+*/
+var CATCH_UP_TIMEOUT_MS = 1e4;
+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;
+	/** Whether this handle asks the server to replay missed messages. */
+	wantsHistory;
+	/**
+	* Highest sequence number delivered to handlers so far.
+	*
+	* This is the resume point sent as `sinceSeq`, and the watermark that makes
+	* replay idempotent: catch-up ranges overlap with what arrived live, and
+	* anything at or below this has already been seen.
+	*/
+	lastSeq = 0;
+	/**
+	* Live messages that arrived while a catch-up was in flight.
+	*
+	* Without this they would be delivered ahead of the older messages being
+	* fetched, and — worse — would advance {@link lastSeq} past them, so the
+	* catch-up response would then be discarded as already-seen and those
+	* messages would be lost for good. Held here and flushed, in order, once
+	* the replay lands.
+	*/
+	pendingLive = [];
+	catchUpInFlight = false;
+	/**
+	* Deadline for a catch-up response.
+	*
+	* Buffering live messages is only safe because the wait is bounded. A
+	* catch-up frame that never arrives — a server that dropped it, a socket
+	* that died between request and reply — would otherwise leave the channel
+	* silently holding every subsequent edit forever, which is a worse failure
+	* than the one replay was added to fix.
+	*/
+	catchUpTimeout = null;
+	/**
+	* Callers of {@link history} awaiting the next `channel_history` frame.
+	*
+	* These frames are addressed by channel rather than by request id, so they
+	* are matched in arrival order. Requests on one channel are serialized by
+	* the socket, so FIFO is the right correlation here.
+	*/
+	historyWaiters = [];
+	constructor(name, transport, options = {}) {
+		this.name = name;
+		this.transport = transport;
+		this.wantsHistory = options.history ?? false;
+	}
+	/**
+	* Turn on catch-up for a handle that was created without it.
+	*
+	* The client hands back the same channel object for a given name, so a
+	* later `channel(name, { history: true })` has no new object to configure —
+	* it upgrades this one instead. Idempotent, and never downgrades: one
+	* caller asking for history must not be switched off by another that did
+	* not ask.
+	*/
+	enableHistory() {
+		if (this.wantsHistory) return;
+		this.wantsHistory = true;
+		if (this.joined) this.requestHistory();
+	}
+	/**
+	* 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.
+	*/
+	/**
+	* Send a channel message.
+	*
+	* Every channel message is read by the server out of a `payload` envelope
+	* (`payload?.channel`, `payload?.state`, `payload?.event`). Sending those
+	* fields flat does not error: `payload?.channel` simply reads as
+	* `undefined`, so the client is registered into channel `undefined` with
+	* empty state, and the echo comes back with no `channel` for
+	* `onChannelMessage` to match — presence and broadcast both go quiet with
+	* nothing logged. Funnelled through one place so a new message type cannot
+	* reintroduce that.
+	*/
+	send(type, fields = {}) {
+		return this.transport.sendMessage({
+			type,
+			payload: {
+				channel: this.name,
+				...fields
+			}
+		});
+	}
+	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.send("join_channel");
+		await this.send("presence_state");
+		if (this.wantsHistory) await this.requestHistory();
+	}
+	async rejoin() {
+		try {
+			await this.send("join_channel");
+			await this.send("presence_state");
+			if (this.trackedState) await this.send("presence_track", { state: this.trackedState });
+			if (this.wantsHistory) await this.requestHistory();
+		} catch {}
+	}
+	/**
+	* Ask the server for everything after {@link lastSeq}.
+	*
+	* Live messages are buffered from here until the answer arrives — see
+	* {@link pendingLive}.
+	*/
+	async requestHistory(limit) {
+		this.catchUpInFlight = true;
+		if (this.catchUpTimeout) clearTimeout(this.catchUpTimeout);
+		this.catchUpTimeout = setTimeout(() => this.abandonCatchUp(), CATCH_UP_TIMEOUT_MS);
+		this.catchUpTimeout.unref?.();
+		try {
+			await this.send("channel_history", {
+				sinceSeq: this.lastSeq,
+				...limit !== void 0 ? { limit } : {}
+			});
+		} catch {
+			this.abandonCatchUp();
+		}
+	}
+	/**
+	* Give up waiting for a catch-up and release what was held back.
+	*
+	* The buffered messages are still the freshest thing this client has, so
+	* they are delivered rather than dropped. Callers of {@link history} are
+	* answered with `retained: false` — accurate in the sense that matters:
+	* this client has no history to work from and has to resync.
+	*/
+	abandonCatchUp() {
+		if (this.catchUpTimeout) {
+			clearTimeout(this.catchUpTimeout);
+			this.catchUpTimeout = null;
+		}
+		if (!this.catchUpInFlight) return;
+		this.catchUpInFlight = false;
+		for (const resolve of this.historyWaiters.splice(0)) resolve({
+			messages: [],
+			retained: false
+		});
+		this.flushPendingLive();
+	}
+	/**
+	* 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.send("presence_track", { state });
+		if (!this.heartbeat) {
+			this.heartbeat = setInterval(() => {
+				if (!this.trackedState) return;
+				this.send("presence_track", { 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.send("presence_untrack");
+	}
+	/**
+	* 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.send("broadcast", {
+			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);
+	}
+	/**
+	* The last sequence number this channel has delivered.
+	*
+	* Zero on a channel that retains nothing. Persist it if you want catch-up
+	* to survive a page reload as well as a reconnect, and pass it back via
+	* {@link history}.
+	*/
+	get sequence() {
+		return this.lastSeq;
+	}
+	/**
+	* Fetch retained messages explicitly, instead of waiting for join or
+	* reconnect to do it.
+	*
+	* Defaults to resuming from {@link sequence}. Messages are delivered to
+	* `onBroadcast` handlers as usual — the returned value is for callers that
+	* want to inspect the batch, or to learn from `retained` that the channel
+	* keeps no history at all.
+	*/
+	async history(options = {}) {
+		await this.join();
+		if (options.sinceSeq !== void 0) this.lastSeq = options.sinceSeq;
+		const result = new Promise((resolve) => {
+			this.historyWaiters.push(resolve);
+		});
+		await this.requestHistory(options.limit);
+		return result;
+	}
+	/** Leave the channel and release every listener and timer. */
+	async leave() {
+		this.stopHeartbeat();
+		this.trackedState = null;
+		this.presences = {};
+		this.presenceHandlers.clear();
+		this.broadcastHandlers.clear();
+		this.lastSeq = 0;
+		this.pendingLive = [];
+		this.catchUpInFlight = false;
+		if (this.catchUpTimeout) {
+			clearTimeout(this.catchUpTimeout);
+			this.catchUpTimeout = null;
+		}
+		for (const resolve of this.historyWaiters.splice(0)) resolve({
+			messages: [],
+			retained: false
+		});
+		for (const off of this.unsubscribers) off();
+		this.unsubscribers = [];
+		if (this.joined) {
+			this.joined = false;
+			await this.send("leave_channel");
+		}
+	}
+	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 seq = typeof message.seq === "number" ? message.seq : void 0;
+				const event = {
+					event: message.event,
+					payload: message.payload,
+					...seq !== void 0 ? { seq } : {}
+				};
+				if (seq === void 0) {
+					this.deliver(event);
+					break;
+				}
+				if (this.catchUpInFlight) {
+					this.pendingLive.push(event);
+					break;
+				}
+				if (seq <= this.lastSeq) break;
+				this.lastSeq = seq;
+				this.deliver(event);
+				break;
+			}
+			case "channel_history": {
+				this.catchUpInFlight = false;
+				if (this.catchUpTimeout) {
+					clearTimeout(this.catchUpTimeout);
+					this.catchUpTimeout = null;
+				}
+				const entries = message.messages ?? [];
+				const retained = message.retained === true;
+				const latestSeq = typeof message.latestSeq === "number" ? message.latestSeq : void 0;
+				for (const resolve of this.historyWaiters.splice(0)) resolve({
+					messages: entries,
+					retained,
+					latestSeq
+				});
+				for (const entry of entries) {
+					if (entry.seq <= this.lastSeq) continue;
+					this.lastSeq = entry.seq;
+					this.deliver({
+						event: entry.event,
+						payload: entry.payload,
+						seq: entry.seq,
+						replayed: true
+					});
+				}
+				this.flushPendingLive();
+				break;
+			}
+		}
+	}
+	/** Deliver everything held back during a catch-up, in sequence order. */
+	flushPendingLive() {
+		if (this.pendingLive.length === 0) return;
+		const buffered = this.pendingLive.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+		this.pendingLive = [];
+		for (const event of buffered) {
+			const seq = event.seq;
+			if (seq !== void 0) {
+				if (seq <= this.lastSeq) continue;
+				this.lastSeq = seq;
+			}
+			this.deliver(event);
+		}
+	}
+	deliver(event) {
+		for (const handler of [...this.broadcastHandlers]) handler(event);
+	}
+	emitPresence(diff) {
+		const snapshot = { ...this.presences };
+		for (const handler of this.presenceHandlers) handler(snapshot, diff);
+	}
+};
+//#endregion
 //#region src/index.ts
 /**
 * Derive a WebSocket URL from an HTTP base URL.
@@ -2331,8 +3003,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,
@@ -2356,7 +3030,7 @@ function createRebaseClient(options) {
 			if (!ws) return;
 			if (event === "SIGNED_OUT") ws.disconnect();
 			else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
-				if (session?.accessToken) ws.authenticate(session.accessToken).catch(console.warn);
+				if (session?.accessToken && ws.hasSocket) ws.authenticate(session.accessToken).catch(console.warn);
 			}
 		});
 	}
@@ -2443,6 +3117,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, options) => {
+			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, options);
+				realtimeChannels.set(name, existing);
+			} else if (options?.history) existing.enableHistory();
+			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(true);
+		},
 		setToken: transport.setToken,
 		setAuthTokenGetter: transport.setAuthTokenGetter,
 		setOnUnauthorized: transport.setOnUnauthorized,
@@ -2461,6 +3165,6 @@ function createRebaseClient(options) {
 	};
 }
 //#endregion
-export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
+export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseRealtimeChannel, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
 
 //# sourceMappingURL=index.es.js.map