@rebasepro/client 0.9.0 → 0.9.1-canary.0fce67c

package/README.md

@@ -161,4 +161,4 @@ const unsubscribe = client.data.products.listen(
 - [`@rebasepro/common`](../common) — `QueryBuilder`, `buildRebaseData`, shared utilities
 - [`@rebasepro/types`](../types) — `Snapshot`, `FindResponse`, `CollectionAccessor`, etc.
 - [`@rebasepro/utils`](../utils) — `toSnakeCase` and other helpers
-- [`@rebasepro/auth`](../auth) — React hook adapter that wraps `client.auth` for CMS integration
+- [`@rebasepro/app`](../auth) — React hook adapter that wraps `client.auth` for CMS integration

package/dist/admin.d.ts

@@ -48,6 +48,7 @@ export declare function createAdmin(transport: Transport, options?: CreateAdminO
         user: AdminUser;
         temporaryPassword?: string;
         invitationSent?: boolean;
+        emailDeliveryFailed?: boolean;
     }>;
     listRoles: () => Promise<{
         roles: Array<{

package/dist/backups.d.ts

@@ -0,0 +1,13 @@
+import { Transport } from "./transport";
+import type { BackupInfo, BackupDestinationKind } from "@rebasepro/types";
+export interface CreateBackupsOptions {
+    backupsPath?: string;
+}
+export declare function createBackups(transport: Transport, options?: CreateBackupsOptions): {
+    list: () => Promise<{
+        backups: BackupInfo[];
+        destinationKind: BackupDestinationKind;
+        configured: boolean;
+    }>;
+    download: (key: string) => Promise<Blob>;
+};

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { RebaseClientConfig } from "./transport";
 import { createAuth, CreateAuthOptions } from "./auth";
 import { createAdmin, CreateAdminOptions } from "./admin";
 import { createCron, CreateCronOptions } from "./cron";
+import { createBackups } from "./backups";
 import { createApiKeys, CreateApiKeysOptions } from "./api-keys";
 import { CollectionClient } from "./collection";
 import { createFunctionsClient } from "./functions";
@@ -21,6 +22,8 @@ export type { RebaseUser, RebaseTokens } from "./auth";
 export type { CreateAdminOptions } from "./admin";
 export type { AdminUser } from "./admin";
 export type { CreateCronOptions } from "./cron";
+export { createBackups } from "./backups";
+export type { CreateBackupsOptions } from "./backups";
 export type { ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, CreateApiKeysOptions, UpdateApiKeyRequest } from "./api-keys";
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 export { RebaseWebSocketClient } from "./websocket";
@@ -67,14 +70,24 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     auth: ReturnType<typeof createAuth>;
     admin: ReturnType<typeof createAdmin>;
     cron: ReturnType<typeof createCron>;
+    backups: ReturnType<typeof createBackups>;
     apiKeys: ReturnType<typeof createApiKeys>;
     functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
+    /**
+     * Release the realtime socket and its reconnect timer.
+     *
+     * An open socket keeps the Node event loop alive, so a script that does not
+     * call this will not exit on its own. Safe when realtime was never started
+     * (`realtime: false`), and safe to call twice.
+     */
+    close: () => void;
     storage: StorageSource;
     storageRegistry: StorageSourceRegistry;
     createStorageSource: (storageId: string) => StorageSource;
     fetchStorageSources: () => Promise<StorageSourceDefinition[]>;
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
+    collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
     data: TypedDataLayer<DB>;
 };
 export declare function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB>;

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) {
@@ -869,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.
@@ -1009,7 +1035,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);
 	}
 };
@@ -1044,6 +1070,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",
@@ -1360,9 +1397,11 @@ 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
 	};
 }
 /**
@@ -1371,7 +1410,7 @@ function extractMessageError(message) {
 * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
 * manages this internally (exposed as `client.ws`, typed by the minimal
 * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
-* package root only because the `@rebasepro/client-postgresql` driver
+* package root only because the `@rebasepro/client-postgres` driver
 * instantiates it directly; its surface may change without a major bump.
 */
 var RebaseWebSocketClient = class {
@@ -1398,6 +1437,7 @@ var RebaseWebSocketClient = class {
 	isConnected = false;
 	messageQueue = [];
 	requestTimeoutMs = 3e4;
+	subscriptionTimeoutMs = 3e4;
 	reconnectTimeout = null;
 	isAuthenticated = false;
 	authPromise = null;
@@ -1503,6 +1543,7 @@ var RebaseWebSocketClient = class {
 				this.emit(wasReconnect ? "reconnect" : "connect");
 				this.processMessageQueue();
 				if (wasReconnect) this.resubscribeAll();
+				this.armPendingSubscribeWatchdogs();
 			};
 			this.ws.onmessage = (event) => {
 				try {
@@ -1517,6 +1558,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"));
@@ -1548,6 +1590,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++;
@@ -1602,29 +1645,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) {
@@ -1659,10 +1691,15 @@ var RebaseWebSocketClient = class {
 				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);
@@ -1681,12 +1718,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;
@@ -1716,6 +1755,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);
@@ -1737,6 +1779,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) => {
@@ -1753,6 +1798,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) => {
@@ -2036,17 +2084,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);
@@ -2058,7 +2128,7 @@ 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;
 		});
@@ -2079,9 +2149,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({
@@ -2103,21 +2176,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({
@@ -2144,9 +2210,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({
@@ -2168,15 +2237,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) {
@@ -2194,6 +2255,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.
@@ -2206,15 +2418,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;
@@ -2222,15 +2426,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) {
@@ -2284,6 +2480,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);
@@ -2304,7 +2501,7 @@ 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;
 	if (resolvedWsUrl) {
 		ws = new RebaseWebSocketClient({
@@ -2408,6 +2605,7 @@ function createRebaseClient(options) {
 		auth,
 		admin,
 		cron,
+		backups,
 		apiKeys,
 		functions,
 		storage,
@@ -2415,6 +2613,16 @@ function createRebaseClient(options) {
 		createStorageSource,
 		fetchStorageSources,
 		ws,
+		/**
+		* 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: () => {
+			ws?.disconnect();
+		},
 		setToken: transport.setToken,
 		setAuthTokenGetter: transport.setAuthTokenGetter,
 		setOnUnauthorized: transport.setOnUnauthorized,
@@ -2433,6 +2641,6 @@ function createRebaseClient(options) {
 	};
 }
 //#endregion
-export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseWebSocketClient, and, cond, createCookieStorage, createMemoryStorage, createRebaseClient, or };
+export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
 
 //# sourceMappingURL=index.es.js.map