@rebasepro/client 0.17.3 → 0.18.1

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, RebaseClientError as RebaseClientError$1, Vector, isPublicStoragePath, parseRelationAggregateSort, toCanonicalOp } from "@rebasepro/types";
+import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, RebaseClientError as RebaseClientError$1, SCHEMA_VERSION_HEADER, Vector, isPublicStoragePath, isUnsupported, parseRelationAggregateSort, sortKeyToString, toCanonicalOp, unsupportedMethod } from "@rebasepro/types";
 import { COMPOSITE_ID_SEPARATOR, QueryBuilder, RebasePaginationError, and, buildCompositeId, collectAllPages, cond, normalizeOrderBy, or, paginateFind, resolveFindWindow, serializeFilter, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
 import { toSnakeCase } from "@rebasepro/utils";
 //#region src/reviver.ts
@@ -67,7 +67,13 @@ var ANONYMOUS_SERVER_CLIENT_WARNING = "[rebase] This client was created outside
 */
 function assertNoUndefinedFilterValues(where) {
 	const reject = (field, op) => {
-		throw new RebaseClientError$1(`Filter on "${field}" has an undefined value (["${String(op)}", undefined]). Omit "${field}" from \`where\` to skip the filter, or use ["is-null", null] to match SQL NULL.`);
+		throw new RebaseClientError$1(`Filter on "${field}" has an undefined value (["${String(op)}", undefined]). Omit "${field}" from \`where\` to skip the filter, or use ["is-null", null] to match SQL NULL.`, {
+			code: "INVALID_FILTER",
+			details: {
+				field,
+				operator: String(op)
+			}
+		});
 	};
 	for (const [field, condition] of Object.entries(where)) {
 		if (condition === void 0) continue;
@@ -139,7 +145,40 @@ function resolveBaseUrl(configured) {
 	return "";
 }
 function createTransport(config, environment) {
-	const fetchFn = config.fetch || globalThis.fetch;
+	const rawFetch = config.fetch || globalThis.fetch;
+	/**
+	* `fetch`, but its rejection is a `RebaseApiError` like everything else
+	* this client throws.
+	*
+	* A transport failure — DNS, a refused connection, CORS, an aborted
+	* request — rejects with whatever the runtime's `fetch` felt like: a
+	* `TypeError` reading "Failed to fetch" in a browser, a `TypeError` with a
+	* `cause` in undici, a `DOMException` on abort. So the one class the SDK
+	* documents as "a `catch` block only ever needs to check for this" did not
+	* cover the most common failure of all, and `e.status` / `e.code` were
+	* undefined on the error every app hits first: the server being down.
+	*
+	* `status: 0` rather than a made-up 5xx. There was no response, and 0 is
+	* how `XMLHttpRequest` has always spelled that; a fabricated 503 would be
+	* indistinguishable from one the server actually sent. The original error
+	* is on `cause`, so nothing is hidden.
+	*
+	* Wrapped once, at construction, because the request path reads `fetchFn`
+	* twice — the first attempt and the post-refresh retry — and a wrapper
+	* applied at one call site is a wrapper missing from the other.
+	*/
+	const fetchFn = async (input, init) => {
+		try {
+			return await rawFetch(input, init);
+		} catch (e) {
+			if (e instanceof RebaseApiError$1) throw e;
+			throw new RebaseApiError$1(`Could not reach the server at ${typeof input === "string" ? input : String(input.url ?? input)}: ${e instanceof Error ? e.message : String(e)}`, {
+				status: 0,
+				code: "NETWORK_ERROR",
+				cause: e
+			});
+		}
+	};
 	const apiPath = config.apiPath || "/api";
 	for (const field of ["baseUrl", "storageUrlOrigin"]) {
 		const value = config[field];
@@ -170,9 +209,14 @@ function createTransport(config, environment) {
 		anonymousWarningIssued = true;
 		console.warn(ANONYMOUS_SERVER_CLIENT_WARNING);
 	}
+	const defaultHeaders = {
+		...config.headers ?? {},
+		...config.schemaVersion ? { [SCHEMA_VERSION_HEADER]: config.schemaVersion } : {}
+	};
 	function getHeaders(activeToken, init) {
 		return {
 			"Content-Type": "application/json",
+			...defaultHeaders,
 			...activeToken ? { Authorization: `Bearer ${activeToken}` } : {},
 			...init?.headers || {}
 		};
@@ -194,6 +238,52 @@ function createTransport(config, environment) {
 			code: "INVALID_JSON_RESPONSE"
 		});
 	}
+	/**
+	* The server always emits the canonical
+	* `{ error: { message, code, details?, requestId? } }` envelope (formatted
+	* by the central `errorHandler`), so a field is read strictly from
+	* `body.error.*` and never from the top level.
+	*/
+	function getErrorField(obj, field) {
+		const err = obj?.error;
+		if (err && typeof err === "object" && err !== null) return err[field];
+	}
+	/**
+	* `Retry-After` as whole seconds, or `undefined`.
+	*
+	* The header is either a number of seconds or an HTTP date; both spellings
+	* are legal and servers use both, so both are read. A date in the past —
+	* which happens on a clock skew — is clamped to 0 rather than negative.
+	*/
+	function parseRetryAfter(header) {
+		if (!header) return void 0;
+		const seconds = Number(header.trim());
+		if (Number.isFinite(seconds)) return Math.max(0, Math.floor(seconds));
+		const at = Date.parse(header);
+		if (Number.isNaN(at)) return void 0;
+		return Math.max(0, Math.round((at - Date.now()) / 1e3));
+	}
+	/**
+	* Everything a failed response says about itself, in one place.
+	*
+	* The request path reads a response twice — the first attempt and the
+	* post-refresh retry — and the two used to build their error separately.
+	* Which is how they came to disagree: both dropped `requestId` and
+	* `Retry-After`, and a fix applied to one would have missed the other.
+	*/
+	function errorFrom(res, body, fallbackMessage) {
+		const requestId = getErrorField(body, "requestId") ?? res.headers?.get("X-Request-ID") ?? void 0;
+		return 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"),
+			...typeof requestId === "string" && requestId ? { requestId } : {},
+			...(() => {
+				const retryAfter = parseRetryAfter(res.headers?.get("Retry-After") ?? null);
+				return retryAfter === void 0 ? {} : { retryAfterSeconds: retryAfter };
+			})()
+		});
+	}
 	async function request(path, init) {
 		const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 		let activeToken = token;
@@ -232,10 +322,6 @@ function createTransport(config, environment) {
 		} catch (e) {
 			unreadableBody = true;
 		}
-		const getErrorField = (obj, field) => {
-			const err = obj?.error;
-			if (err && typeof err === "object" && err !== null) return err[field];
-		};
 		if (res.status === 401 && onUnauthorizedHandler) {
 			if (await onUnauthorizedHandler()) {
 				let retryToken = token;
@@ -260,11 +346,7 @@ function createTransport(config, environment) {
 				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$1(String(getErrorField(retryBody, "message") || fallbackMessage || `Request failed with status ${retryRes.status}`), {
-						status: retryRes.status,
-						code: getErrorField(retryBody, "code"),
-						details: getErrorField(retryBody, "details")
-					});
+					throw errorFrom(retryRes, retryBody, fallbackMessage);
 				}
 				if (retryUnreadable) throw unreadableResponse(retryRes.status, retryText);
 				return retryBody;
@@ -273,11 +355,7 @@ function createTransport(config, environment) {
 		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$1(String(getErrorField(body, "message") || fallbackMessage || `Request failed with status ${res.status}`), {
-				status: res.status,
-				code: getErrorField(body, "code"),
-				details: getErrorField(body, "details")
-			});
+			throw errorFrom(res, body, fallbackMessage);
 		}
 		if (unreadableBody) throw unreadableResponse(res.status, text);
 		return body;
@@ -783,7 +861,7 @@ function createAuth(transport, options) {
 		return inFlightRefresh;
 	}
 	async function doRefreshSession() {
-		if (authFlowMode !== "cookie" && !currentSession?.refreshToken) throw new Error("No active session to refresh");
+		if (authFlowMode !== "cookie" && !currentSession?.refreshToken) throw new RebaseClientError$1("No active session to refresh. Sign in first, or set `authFlowMode: \"cookie\"` if the refresh token is held in an HttpOnly cookie.", { code: "NOT_SIGNED_IN" });
 		const res = await getFetch()(authUrl("/refresh"), {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
@@ -979,6 +1057,136 @@ function createAuth(transport, options) {
 			refreshToken: session.refreshToken
 		};
 	}
+	/**
+	* Sign in without credentials, as a throwaway account.
+	*
+	* The account is real — it has an id, roles and a session, so row-level
+	* security scopes its data exactly as it would a signed-up user's. What it
+	* does not have is a way back: nobody can sign in *as* it a second time, so
+	* everything it owns is lost when the session is. `linkAnonymous` is how it
+	* stops being throwaway.
+	*
+	* Refused with `ANONYMOUS_AUTH_DISABLED` unless the backend has it on.
+	*/
+	async function signInAnonymously() {
+		const res = await getFetch()(authUrl("/anonymous"), {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			credentials: authFlowMode === "cookie" ? "include" : void 0
+		});
+		const body = await res.json().catch(() => ({}));
+		if (!res.ok) throwApiError(res.status, body, res.statusText);
+		const session = handleAuthResponse(body, "SIGNED_IN");
+		return {
+			user: session.user,
+			accessToken: session.accessToken,
+			refreshToken: session.refreshToken
+		};
+	}
+	/**
+	* Put an email and password on the anonymous account this client holds.
+	*
+	* The user keeps their id, so everything they created while anonymous stays
+	* theirs — which is the point: the alternative is asking a visitor to sign
+	* up before they have any reason to.
+	*
+	* Requires a live anonymous session. `NOT_ANONYMOUS` (400) if the session
+	* belongs to an ordinary account, `EMAIL_EXISTS` (409) if the address is
+	* taken.
+	*/
+	async function linkAnonymous(email, password) {
+		const session = handleAuthResponse(await transport.request(authPath + "/anonymous/link", {
+			method: "POST",
+			body: JSON.stringify({
+				email,
+				password
+			})
+		}), "USER_UPDATED");
+		return {
+			user: session.user,
+			accessToken: session.accessToken,
+			refreshToken: session.refreshToken
+		};
+	}
+	/**
+	* Multi-factor authentication: TOTP factors, and the challenge that raises
+	* a session to `aal2`.
+	*
+	* The backend has served all six of these since MFA landed; the SDK exposed
+	* none of them, so every app that wanted MFA hand-wrote `fetch` calls
+	* against `/auth/mfa/*` — including the auth header and the cookie flag,
+	* which is exactly what a client is for.
+	*/
+	const mfa = {
+		/**
+		* Start enrolling a TOTP factor.
+		*
+		* Returns the secret and an `otpauth://` URI to render as a QR code,
+		* plus ten single-use recovery codes. **Show the recovery codes once
+		* and never again** — only their hashes are stored.
+		*
+		* The factor is not usable until `verify` confirms the user's
+		* authenticator produced a correct code from it.
+		*/
+		async enroll(options) {
+			return transport.request(authPath + "/mfa/enroll", {
+				method: "POST",
+				body: JSON.stringify(options ?? {})
+			});
+		},
+		/** Confirm an enrolment with a code from the authenticator app. */
+		async verify(factorId, code) {
+			return transport.request(authPath + "/mfa/verify", {
+				method: "POST",
+				body: JSON.stringify({
+					factorId,
+					code
+				})
+			});
+		},
+		/** The factors on this account, verified or not. */
+		async listFactors() {
+			return (await transport.request(authPath + "/mfa/factors", { method: "GET" })).factors;
+		},
+		/**
+		* Remove a factor. Requires an `aal2` session — one that has already
+		* answered a challenge — so a stolen `aal1` token cannot turn MFA off.
+		*/
+		async unenroll(factorId) {
+			return transport.request(authPath + "/mfa/unenroll", {
+				method: "DELETE",
+				body: JSON.stringify({ factorId })
+			});
+		},
+		/** Open a challenge against a verified factor. Expires in five minutes. */
+		async challenge(factorId) {
+			return transport.request(authPath + "/mfa/challenge", {
+				method: "POST",
+				body: JSON.stringify({ factorId })
+			});
+		},
+		/**
+		* Answer a challenge with a TOTP code or a recovery code.
+		*
+		* This is where an MFA-enrolled account's real session is minted, at
+		* `aal2` — so the returned tokens replace the ones the sign-in handed
+		* back, and this client adopts them.
+		*/
+		async verifyChallenge(challengeId, code) {
+			const session = handleAuthResponse(await transport.request(authPath + "/mfa/challenge/verify", {
+				method: "POST",
+				body: JSON.stringify({
+					challengeId,
+					code
+				})
+			}), "SIGNED_IN");
+			return {
+				user: session.user,
+				accessToken: session.accessToken,
+				refreshToken: session.refreshToken
+			};
+		}
+	};
 	async function getSessions() {
 		return (await transport.request(authPath + "/sessions", { method: "GET" })).sessions;
 	}
@@ -1054,6 +1262,9 @@ function createAuth(transport, options) {
 		signInWithBitbucket,
 		signInWithSlack,
 		signInWithSpotify,
+		signInAnonymously,
+		linkAnonymous,
+		mfa,
 		signOut,
 		stopAutoRefresh,
 		refreshSession,
@@ -1303,7 +1514,11 @@ var SDKQueryBuilder = class {
 	}
 	where(columnOrCondition, operator, value) {
 		if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
-			this.params.logical = columnOrCondition;
+			const next = columnOrCondition;
+			this.params.logical = this.params.logical ? {
+				type: "and",
+				conditions: [this.params.logical, next]
+			} : next;
 			return this;
 		}
 		if (!this.params.where) this.params.where = {};
@@ -1330,7 +1545,7 @@ var SDKQueryBuilder = class {
 	*/
 	orderBy(column, direction = "asc") {
 		const existing = normalizeOrderBy(this.params.orderBy) ?? [];
-		this.params.orderBy = [...existing, [column, direction]];
+		this.params.orderBy = [...existing, [sortKeyToString(column), direction]];
 		return this;
 	}
 	/**
@@ -1419,27 +1634,81 @@ var SDKQueryBuilder = class {
 		return this.collection.find(this.params);
 	}
 	/**
+	* Page through everything this query matches, one row at a time.
+	*
+	* `.limit()` on the builder becomes the page size, so the ceiling on a
+	* single `find()` is not a ceiling on what the query can read.
+	*/
+	iterate(options) {
+		return this.collection.iterate({
+			...this.params,
+			...this.params.limit !== void 0 && { pageSize: this.params.limit },
+			...options
+		});
+	}
+	/** Collect everything this query matches into one array. */
+	findAll(options) {
+		return this.collection.findAll({
+			...this.params,
+			...this.params.limit !== void 0 && { pageSize: this.params.limit },
+			...options
+		});
+	}
+	/**
 	* 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.
+	*
+	* The guard that used to stand here — `if (!this.collection.listen) throw`
+	* — has moved onto the client itself, which is where the same failure had
+	* to be diagnosed anyway: `client.data.posts.listen(…)`, one call short of
+	* this builder, answered `undefined is not a function`. The message is now
+	* the same either way.
 	*/
 	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
 /**
-* Counts currently in flight, keyed by the exact request they issue. Entries
-* live only for the duration of the request — see `count()` for why.
+* What `listen`/`listenById` say on a client that has no socket.
+*
+* One sentence, in one place: it used to live in `SDKQueryBuilder.listen` only,
+* so the same failure reached callers of `client.data.posts.listen` as
+* `undefined is not a function`.
 */
-var inflightCounts = /* @__PURE__ */ new Map();
+var NO_SOCKET = "Listen is only available when RebaseClient is configured with a websocketUrl, and not when it was created with realtime: false.";
+/**
+* Counts currently in flight, **per client**, keyed by the exact request they
+* issue. Entries live only for the duration of the request — see `count()` for
+* why they exist at all.
+*
+* The map used to be module-level, shared by every client in the process. A
+* request key is a path and a query string: it says nothing about *who* is
+* asking. So two clients holding different credentials — an admin panel beside
+* a signed-in user's client, a per-request server client in a Node process, a
+* test asserting one client's calls — counting the same collection would share
+* one request, and whichever arrived second was answered with the first one's
+* total. Row-level security makes those genuinely different numbers.
+*
+* Keyed on the transport instead, which is the object a credential lives on.
+* A `WeakMap`, so a closed client's entry goes with it.
+*/
+var inflightCounts = /* @__PURE__ */ new WeakMap();
+/** The in-flight map for one transport, created on first use. */
+function inflightCountsFor(transport) {
+	let map = inflightCounts.get(transport);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		inflightCounts.set(transport, map);
+	}
+	return map;
+}
 function createCollectionClient(transport, slug, ws) {
 	const basePath = `/data/${slug}`;
 	const client = {
@@ -1467,6 +1736,14 @@ function createCollectionClient(transport, slug, ws) {
 				throw err;
 			}
 		},
+		async get(id) {
+			const row = await client.findById(id);
+			if (row === void 0) throw new RebaseApiError(`No record with id ${JSON.stringify(String(id))} in "${slug}".`, {
+				status: 404,
+				code: "NOT_FOUND"
+			});
+			return row;
+		},
 		async create(data, id, options) {
 			const body = { ...data };
 			if (id !== void 0) body.id = id;
@@ -1497,10 +1774,11 @@ function createCollectionClient(transport, slug, ws) {
 		* and the route now name one verb, and a spec-validating gateway in
 		* front of the API sees the operation the server actually implements.
 		*/
-		async update(id, data) {
+		async update(id, data, options) {
 			return await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
 				method: "PATCH",
-				body: JSON.stringify(data)
+				body: JSON.stringify(data),
+				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
 			});
 		},
 		async updateMany(updates, options) {
@@ -1543,14 +1821,15 @@ function createCollectionClient(transport, slug, ws) {
 				include: void 0
 			});
 			const key = basePath + "/count" + qs;
-			const inflight = inflightCounts.get(key);
-			if (inflight) return inflight;
+			const inflight = inflightCountsFor(transport);
+			const existing = inflight.get(key);
+			if (existing) return existing;
 			const request = transport.request(key, { method: "GET" }).then((raw) => raw.count ?? 0);
-			inflightCounts.set(key, request);
+			inflight.set(key, request);
 			try {
 				return await request;
 			} finally {
-				inflightCounts.delete(key);
+				inflight.delete(key);
 			}
 		},
 		observe(params, onResult, onError, options) {
@@ -1574,7 +1853,7 @@ function createCollectionClient(transport, slug, ws) {
 			client.find(params).then((result) => deliver(result, false)).catch((error) => {
 				if (!closed) onError?.(error);
 			});
-			const live = options?.realtime !== false && client.listen ? client.listen(params, (result) => deliver(result, true), onError) : void 0;
+			const live = options?.realtime !== false && !isUnsupported(client.listen) ? client.listen(params, (result) => deliver(result, true), onError) : void 0;
 			return () => {
 				closed = true;
 				live?.();
@@ -1599,7 +1878,7 @@ function createCollectionClient(transport, slug, ws) {
 			client.findById(id).then((row) => deliver(row, false)).catch((error) => {
 				if (!closed) onError?.(error);
 			});
-			const live = options?.realtime !== false && client.listenById ? client.listenById(id, (row) => deliver(row, true), onError) : void 0;
+			const live = options?.realtime !== false && !isUnsupported(client.listenById) ? client.listenById(id, (row) => deliver(row, true), onError) : void 0;
 			return () => {
 				closed = true;
 				live?.();
@@ -1627,7 +1906,9 @@ function createCollectionClient(transport, slug, ws) {
 		},
 		include(...relations) {
 			return new SDKQueryBuilder(client).include(...relations);
-		}
+		},
+		listen: unsupportedMethod(NO_SOCKET),
+		listenById: unsupportedMethod(NO_SOCKET)
 	};
 	if (ws) {
 		client.listen = (params, onUpdate, onError) => {
@@ -1662,15 +1943,16 @@ function createCollectionClient(transport, slug, ws) {
 						}
 					});
 				};
-				const emitWithoutCount = () => emit(offset + rows.length, rows.length >= requestedLimit);
-				if (client.count) client.count(params).then((total) => {
+				client.count(params).then((total) => {
 					lastKnownTotal = total;
 					emit(total, offset + rows.length < total);
 				}).catch(() => {
-					if (lastKnownTotal !== void 0) emit(lastKnownTotal, offset + rows.length < lastKnownTotal);
-					else emitWithoutCount();
+					if (lastKnownTotal !== void 0) {
+						emit(lastKnownTotal, offset + rows.length < lastKnownTotal);
+						return;
+					}
+					emit(offset + rows.length, rows.length >= requestedLimit);
 				});
-				else emitWithoutCount();
 			}, onError);
 			return () => {
 				active = false;
@@ -1704,6 +1986,10 @@ function createCollectionClient(transport, slug, ws) {
 */
 function createFunctionsClient(transport) {
 	return { async invoke(name, payload, options) {
+		if (name.includes("/")) throw new RebaseClientError$1(`Invalid function name "${name}": a function name is a single path segment. Pass anything after it as \`options.path\` — invoke("${name.split("/")[0]}", payload, { path: "${name.split("/").slice(1).join("/")}" }).`, {
+			code: "INVALID_FUNCTION_NAME",
+			details: { name }
+		});
 		const method = options?.method ?? "POST";
 		const rawPath = options?.path;
 		const subPath = rawPath ? /^[?#]/.test(rawPath) ? rawPath : `/${rawPath.replace(/^\//, "")}` : "";
@@ -2325,7 +2611,7 @@ var RebaseWebSocketClient = class {
 			}
 			return;
 		}
-		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history")) {
+		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history" || type === "ERROR" || type === "error")) {
 			const handlers = this.channelHandlers.get(message.channel);
 			if (handlers) for (const handler of [...handlers]) try {
 				handler(message);
@@ -2361,39 +2647,6 @@ var RebaseWebSocketClient = class {
 				}
 			}
 		}
-		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 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 (patchRow === null) updated = collectionSub.latestData.filter((e) => this.rowAddress(e, collectionSub.pks) !== String(patchEntityId));
-					else {
-						const idx = collectionSub.latestData.findIndex((e) => this.rowAddress(e, collectionSub.pks) === String(patchEntityId));
-						if (idx >= 0) {
-							updated = [...collectionSub.latestData];
-							updated[idx] = patchRow;
-						} else updated = [patchRow, ...collectionSub.latestData];
-					}
-					collectionSub.latestData = updated;
-					collectionSub.lastUpdated = Date.now();
-					collectionSub.callbacks.forEach((callback) => {
-						try {
-							callback.onUpdate(updated);
-						} catch (error) {
-							console.error("Error in collection patch callback:", error);
-							if (callback.onError) callback.onError(error instanceof Error ? error : new Error(String(error)));
-						}
-					});
-					return;
-				}
-			}
-		}
 		if (subscriptionId && type === "single_update") {
 			const subscriptionKey = this.backendToEntityKey.get(subscriptionId);
 			if (subscriptionKey) {
@@ -3116,6 +3369,7 @@ var RebaseRealtimeChannel = class {
 	transport;
 	presenceHandlers = /* @__PURE__ */ new Set();
 	broadcastHandlers = /* @__PURE__ */ new Set();
+	errorHandlers = /* @__PURE__ */ new Set();
 	unsubscribers = [];
 	/** Last known roster, kept so handlers always get a full picture. */
 	presences = {};
@@ -3303,7 +3557,16 @@ var RebaseRealtimeChannel = class {
 		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. */
+	/**
+	* Send a broadcast. The sender does not receive its own message.
+	*
+	* Resolves when the frame is written to the socket, **not** when the server
+	* has accepted it. Channel frames are fire-and-forget by design — a
+	* collaborative app broadcasts a cursor position sixty times a second, and
+	* waiting for an acknowledgement on each would make that a round trip.
+	*
+	* A refusal therefore arrives on {@link onError}, not as a rejection here.
+	*/
 	async broadcast(event, payload) {
 		await this.join();
 		await this.send("broadcast", {
@@ -3311,6 +3574,27 @@ var RebaseRealtimeChannel = class {
 			payload
 		});
 	}
+	/**
+	* Observe refusals about this channel.
+	*
+	* `CHANNEL_FORBIDDEN` when an authorizer refuses a join, a broadcast or a
+	* history read; `RATE_LIMITED` past the channel frame budget;
+	* `CHANNEL_HISTORY_WRITE_FAILED` / `CHANNEL_HISTORY_READ_FAILED` when
+	* retention cannot be served; `CHANNEL_BUS_PAYLOAD_TOO_LARGE` when a
+	* broadcast on an ephemeral channel is too big to cross the bus.
+	*
+	* These used to be dropped on the floor — there is no promise to reject on
+	* a fire-and-forget frame, so a forbidden broadcast looked exactly like a
+	* delivered one. With no handler attached they are logged as a warning,
+	* because an unobserved refusal is the failure this exists for.
+	*
+	* @returns An unsubscribe function.
+	*/
+	onError(handler) {
+		this.errorHandlers.add(handler);
+		this.join();
+		return () => this.errorHandlers.delete(handler);
+	}
 	onBroadcast(eventOrHandler, maybeHandler) {
 		const wrapped = typeof eventOrHandler === "string" ? (e) => {
 			if (e.event === eventOrHandler) maybeHandler(e.payload);
@@ -3443,6 +3727,23 @@ var RebaseRealtimeChannel = class {
 				this.flushPendingLive();
 				break;
 			}
+			case "ERROR":
+			case "error": {
+				const raw = message.payload?.error;
+				const asObject = typeof raw === "object" && raw !== null ? raw : void 0;
+				const text = asObject?.message ?? (typeof raw === "string" ? raw : void 0) ?? (typeof message.error === "string" ? message.error : void 0) ?? "The server refused a channel operation.";
+				const error = new RebaseApiError$1(text, { ...asObject?.code ? { code: asObject.code } : {} });
+				if (this.errorHandlers.size === 0) {
+					console.warn(`[Rebase] Channel "${this.name}" error${asObject?.code ? ` (${asObject.code})` : ""}: ${text}. Attach \`channel.onError(...)\` to handle it.`);
+					break;
+				}
+				for (const handler of [...this.errorHandlers]) try {
+					handler(error);
+				} catch (e) {
+					console.error("Error in channel error handler:", e);
+				}
+				break;
+			}
 		}
 	}
 	/** Deliver everything held back during a catch-up, in sequence order. */
@@ -3552,12 +3853,20 @@ function hydrateRow(row) {
 * store immediately, which is the difference between an app that freezes when
 * the wifi drops and one that does not.
 */
-/** The request never reached the server, so nothing was decided by it. */
+/**
+* The request never reached the server, so nothing was decided by it.
+*
+* One question, one answer: `status === 0` is how a transport spells "there
+* was no response at all", and the transport now wraps every `fetch` rejection
+* into a `RebaseApiError` carrying it. This used to also sniff for the shapes
+* a raw `fetch` rejects with — a `TypeError` in a browser, an `AbortError`, a
+* `TimeoutError` — which is a list that has to be kept in step with three
+* runtimes and was wrong in both directions: it missed anything they add, and
+* it claimed a `TypeError` thrown by application code inside a callback was a
+* network failure, which quietly served a cached answer in its place.
+*/
 function isNetworkError(error) {
-	if (error instanceof RebaseApiError) return error.status === 0;
-	if (error instanceof TypeError) return true;
-	const name = error?.name;
-	return name === "AbortError" || name === "TimeoutError" || name === "NetworkError";
+	return error instanceof RebaseApiError && error.status === 0;
 }
 /**
 * Statuses that mean "not now" rather than "not ever": a queued write that
@@ -4326,20 +4635,51 @@ function runLocalQuery(rows, params) {
 }
 //#endregion
 //#region src/offline.ts
-/** True when a read failed because there was neither network nor local data. */
+/**
+* True when a read failed because there was neither network nor local data.
+*
+* The code is `OFFLINE`. It was `"offline"`, the one lowercase code in a
+* surface whose every other code is `SCREAMING_SNAKE_CASE` — including the
+* `NETWORK_ERROR` it sits next to — so `e.code === "OFFLINE"`, which is what
+* anyone writes, never matched.
+*/
 function isOfflineError(error) {
-	return error instanceof RebaseApiError && error.code === "offline";
+	return error instanceof RebaseApiError && error.code === "OFFLINE";
 }
 function offlineError(message) {
 	return new RebaseApiError(message, {
 		status: 0,
-		code: "offline"
+		code: "OFFLINE"
 	});
 }
-function generateOfflineId() {
+function generateOfflineStringId() {
 	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
 	return `off-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+/**
+* The last temporary numeric id minted, so the next one is smaller.
+*
+* Module-scoped and strictly decreasing: two temporary ids in the same session
+* must not collide, and neither must one minted a millisecond after another.
+*/
+var lastOfflineNumericId = 0;
+/**
+* A temporary id for a collection whose ids are numbers.
+*
+* **Negative**, which is the convention every local-first engine settles on for
+* the same reason: a real key is a positive integer or an identity sequence, so
+* the sign alone says "this one is not the server's yet" — and it stays a
+* number, which is what matters. A UUID string was minted for every collection,
+* so a `create` while offline handed back `{ id: "526e2faf-…" }` on a row the
+* generated types declare `id: number`. Anything that put that in a URL, a
+* foreign key or an `id.toFixed()` was wrong or threw until the replay
+* reconciled it — and the SDK's own types said it could not happen.
+*/
+function generateOfflineNumericId() {
+	const candidate = -Date.now();
+	lastOfflineNumericId = lastOfflineNumericId === 0 ? candidate : Math.min(candidate, lastOfflineNumericId - 1);
+	return lastOfflineNumericId;
+}
 var MISSING = "\0missing";
 /**
 * Replays to spend on a mutation whose idempotency key the server is still
@@ -4566,6 +4906,14 @@ var OfflineManager = class {
 				if (this.collections.get(slug)?.absent.has(String(id))) return void 0;
 				throw offlineError(`Offline: "${slug}" row ${String(id)} is not in the local database.`);
 			},
+			get: async (id) => {
+				const row = await wrapped.findById(id);
+				if (row === void 0) throw new RebaseApiError(`No record with id ${JSON.stringify(String(id))} in "${slug}".`, {
+					status: 404,
+					code: "NOT_FOUND"
+				});
+				return row;
+			},
 			create: async (data, id) => {
 				await this.ensureCollection(slug);
 				if (this.connectivity.shouldAttempt()) try {
@@ -4580,7 +4928,7 @@ var OfflineManager = class {
 					this.connectivity.markFailure();
 				}
 				const providedId = id ?? data.id;
-				const rowId = providedId ?? generateOfflineId();
+				const rowId = providedId ?? this.mintOfflineId(slug);
 				const row = {
 					...data,
 					id: rowId
@@ -4614,7 +4962,7 @@ var OfflineManager = class {
 				}
 				const rows = data.map((r) => ({
 					...r,
-					id: r.id ?? generateOfflineId()
+					id: r.id ?? this.mintOfflineId(slug)
 				}));
 				const rollback = {};
 				for (const row of rows) {
@@ -4778,13 +5126,15 @@ var OfflineManager = class {
 			offset: (count) => new SDKQueryBuilder(wrapped).offset(count),
 			search: (searchString, options) => new SDKQueryBuilder(wrapped).search(searchString, options),
 			vectorSearch: (property, vector, options) => new SDKQueryBuilder(wrapped).vectorSearch(property, vector, options),
-			include: (...relations) => new SDKQueryBuilder(wrapped).include(...relations)
+			include: (...relations) => new SDKQueryBuilder(wrapped).include(...relations),
+			listen: inner.listen,
+			listenById: inner.listenById
 		};
-		if (inner.listen) wrapped.listen = (params, onUpdate, onError) => inner.listen(params, (response) => {
+		if (!isUnsupported(inner.listen)) wrapped.listen = (params, onUpdate, onError) => inner.listen(params, (response) => {
 			this.ingest(slug, response.data ?? []).then(() => this.notifyCollection(slug, false));
 			onUpdate(response);
 		}, onError);
-		if (inner.listenById) wrapped.listenById = (id, onUpdate, onError) => inner.listenById(id, (row) => {
+		if (!isUnsupported(inner.listenById)) wrapped.listenById = (id, onUpdate, onError) => inner.listenById(id, (row) => {
 			if (row) this.ingest(slug, [row]).then(() => this.notifyCollection(slug, false));
 			onUpdate(row);
 		}, onError);
@@ -4829,7 +5179,7 @@ var OfflineManager = class {
 			}
 			if (!closed) observer.emit();
 		})();
-		if (options?.realtime !== false && inner.listen) unlisten = inner.listen(params, (response) => {
+		if (options?.realtime !== false && !isUnsupported(inner.listen)) unlisten = inner.listen(params, (response) => {
 			this.ingest(slug, response.data ?? []).then(() => {
 				this.recordSnapshot(slug, params, response);
 				this.notifyCollection(slug, false);
@@ -4881,7 +5231,7 @@ var OfflineManager = class {
 			}
 			if (!closed) observer.emit();
 		})();
-		if (options?.realtime !== false && inner.listenById) unlisten = inner.listenById(id, (row) => {
+		if (options?.realtime !== false && !isUnsupported(inner.listenById)) unlisten = inner.listenById(id, (row) => {
 			if (!row) {
 				if (!this.hasPending(slug, id)) this.removeLocalRow(slug, id, true);
 				this.notifyCollection(slug, false);
@@ -5067,6 +5417,28 @@ var OfflineManager = class {
 			partial: true
 		};
 	}
+	/**
+	* A temporary id of the type this collection's ids actually have.
+	*
+	* There is no schema here to read it off — the generated `Database` types
+	* are erased at compile time, and the whole point of this path is that the
+	* server is unreachable. So it is read off the rows the local database
+	* already holds: a collection whose cached ids are numbers gets a negative
+	* number, and everything else gets a UUID.
+	*
+	* A collection with nothing cached falls back to a UUID, which is the same
+	* guess as before — but that is a first write on a device that has never
+	* read the collection, which is also the case where nothing local can tell
+	* the difference. Reading one row first is enough to fix it.
+	*/
+	mintOfflineId(slug) {
+		for (const entry of this.collections.get(slug)?.rows.values() ?? []) {
+			const id = entry.row.id;
+			if (typeof id === "number") return generateOfflineNumericId();
+			if (typeof id === "string") break;
+		}
+		return generateOfflineStringId();
+	}
 	rawLocalRow(slug, id) {
 		const entry = this.collections.get(slug)?.rows.get(String(id));
 		return entry ? { ...entry.row } : void 0;
@@ -5829,7 +6201,13 @@ function createRebaseClient(options) {
 				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);
+				throw new RebaseClientError(msg, {
+					code: "UNKNOWN_COLLECTION",
+					details: {
+						accessor: prop,
+						known: knownKeys
+					}
+				});
 			}
 			if (!untypedWarned) {
 				untypedWarned = true;
@@ -5860,7 +6238,7 @@ function createRebaseClient(options) {
 		* cut off the others.
 		*/
 channel: (name, options) => {
-			if (!ws) throw new RebaseClientError(realtimeUnreachable ? `Realtime is enabled but ${unreachableReason}` : "Realtime is disabled on this client (realtime: false), so channels are unavailable.");
+			if (!ws) throw new RebaseClientError(realtimeUnreachable ? `Realtime is enabled but ${unreachableReason}` : "Realtime is disabled on this client (realtime: false), so channels are unavailable.", { code: "REALTIME_DISABLED" });
 			let existing = realtimeChannels.get(name);
 			if (!existing) {
 				existing = new RebaseRealtimeChannel(name, ws, options);
@@ -5891,11 +6269,10 @@ channel: (name, options) => {
 		collection,
 		call: async (endpoint, payload) => {
 			const prefix = endpoint.startsWith("/") ? "" : "/";
-			const res = await transport.request(`${prefix}${endpoint}`, {
+			return transport.request(`${prefix}${endpoint}`, {
 				method: "POST",
 				body: payload ? JSON.stringify(payload) : void 0
 			});
-			return res.data ?? res;
 		},
 		data: dataProxy,
 		...offlineManager ? { offline: offlineManager.api } : {}