@rebasepro/server 0.9.1-canary.1d2d8b5 → 0.9.1-canary.58368ce

package/dist/api/rest/api-generator.d.ts

@@ -5,12 +5,15 @@ import { HonoEnv } from "../types";
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
  * Supports `include` query parameter for eager-loading relations via Drizzle.
  */
+/** Rows accepted by a single POST /<collection>/bulk. See `maxBulkRows`. */
+export declare const DEFAULT_MAX_BULK_ROWS = 1000;
 export declare class RestApiGenerator {
     private collections;
     private router;
     private driver;
+    private maxBulkRows;
     private authAdapter?;
-    constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter);
+    constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter, maxBulkRows?: number);
     /**
      * Generate REST routes using existing DataDriver
      */

package/dist/index.es.js

@@ -1,10 +1,9 @@
 import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
-import { a as __require, i as __exportAll, n as __commonJSMin, s as __toESM } from "./ms-DnYXB-Wd.js";
-import { _ as RebaseClientError, a as getCollectionDataPath, c as CANONICAL_TO_REST, d as toCanonicalOp, f as EntityReference, g as RebaseApiError, h as Vector, i as isSQLAdmin, l as NULL_OPS, m as GeoPoint, o as getDeclaredSubcollections, p as EntityRelation, r as getDataSourceCapabilities, s as isPostgresCollectionConfig, t as DEFAULT_STORAGE_SOURCE_KEY, u as REST_TO_CANONICAL } from "./src-B4OLmNVa.js";
+import { a as getAccessTokenExpiry, d as require_jsonwebtoken, f as __commonJSMin, h as __toESM, i as generateRefreshToken, l as verifyAccessToken, m as __require, n as generateAccessToken, o as getRefreshTokenExpiry, p as __exportAll, r as generateDownloadToken, s as hashRefreshToken, t as configureJwt, u as verifyDownloadToken } from "./jwt-C6pbGtvf.js";
+import { _ as RebaseApiError, a as policy, c as isPostgresCollectionConfig, d as REST_TO_CANONICAL, f as toCanonicalOp, g as Vector, h as GeoPoint, i as isSQLAdmin, l as CANONICAL_TO_REST, m as EntityRelation, o as getCollectionDataPath, p as EntityReference, r as getDataSourceCapabilities, s as getDeclaredSubcollections, t as DEFAULT_STORAGE_SOURCE_KEY, u as NULL_OPS, v as RebaseClientError } from "./src-CsHhSKbi.js";
 import { t as logger } from "./logger-BYU66ENZ.js";
-import { a as getAccessTokenExpiry, d as require_jsonwebtoken, i as generateRefreshToken, l as verifyAccessToken, n as generateAccessToken, o as getRefreshTokenExpiry, r as generateDownloadToken, s as hashRefreshToken, t as configureJwt, u as verifyDownloadToken } from "./jwt-BwIn8xmk.js";
 import { t as nativeDynamicImport } from "./dynamic-import-Dvh-K5fl.js";
 import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
 import * as fs$2 from "fs";
@@ -1109,6 +1108,76 @@ function normalizeToEntityRelation(value, propertyType) {
 	if (!(obj.__type === "relation" || obj.__type === "reference" || typeof obj.isEntityRelation === "function" && obj.isEntityRelation() || typeof obj.isEntityReference === "function" && obj.isEntityReference() || propertyType === "relation" && typeof obj.id !== "undefined" && typeof obj.path === "string")) return null;
 	return new EntityRelation(obj.id, obj.path, obj.data);
 }
+/**
+* Derive a row's address from its key columns.
+*
+* Single key → the value as a string. Composite → each part joined by
+* {@link COMPOSITE_ID_SEPARATOR}, in primary-key order, which is what
+* {@link parseIdValues} expects to invert.
+*/
+function buildCompositeId(values, primaryKeys) {
+	if (primaryKeys.length === 0) return "";
+	if (primaryKeys.length === 1) return String(values[primaryKeys[0].fieldName] ?? "");
+	return primaryKeys.map((pk) => String(values[pk.fieldName] ?? "")).join(":::");
+}
+/**
+* The primary keys of a collection, as declared by its properties.
+*
+* This is the only tier both sides can read, because it is the only one written
+* in the config: the postgres driver can also infer keys from the Drizzle
+* schema, which the browser never sees and is never sent — the admin compiles
+* the collection files into its own bundle rather than being served them. A key
+* that lives only in the Drizzle schema is therefore invisible here, and the
+* server says so at boot (`warnOnKeysTheAdminCannotResolve`) naming the `isId`
+* to add.
+*
+* Returns an empty array when a collection declares none, which callers must
+* treat as "not addressable" rather than defaulting to `id`: guessing a key
+* that is not the real one produces confidently wrong addresses.
+*/
+function getDeclaredPrimaryKeys(collection) {
+	const properties = collection.properties;
+	if (!properties) return [];
+	const keys = [];
+	for (const [fieldName, propRaw] of Object.entries(properties)) {
+		const prop = propRaw;
+		if (!prop || typeof prop !== "object") continue;
+		if (!("isId" in prop) || !prop.isId) continue;
+		keys.push({
+			fieldName,
+			type: prop.type === "number" ? "number" : "string",
+			isUUID: prop.isId === "uuid"
+		});
+	}
+	return keys;
+}
+/**
+* The keys to address a collection's rows with, resolved the way the driver
+* resolves them — minus the tier the browser cannot reach.
+*
+* The postgres driver tries, in order: properties marked `isId`; the primary
+* keys of the Drizzle schema; and finally a column literally named `id`. Only
+* the first and last are visible in a `CollectionConfig`, which is what both
+* sides share.
+*
+* So the two agree except on a collection that declares no `isId` and whose key
+* is known only to Drizzle. There, the driver reads the real key, and this
+* either resolves nothing (reported to the console by the caller) or — if the
+* table happens to have an unrelated `id` property — resolves `id`, which is
+* the wrong key and cannot be detected from here: the addresses look right and
+* route wrong. Only the config can settle it, so the server names both cases
+* at boot (`warnOnKeysTheAdminCannotResolve`) with the `isId` to add.
+*/
+function resolvePrimaryKeys(collection) {
+	const declared = getDeclaredPrimaryKeys(collection);
+	if (declared.length > 0) return declared;
+	const idProp = collection.properties?.id;
+	if (idProp && typeof idProp === "object") return [{
+		fieldName: "id",
+		type: idProp.type === "number" ? "number" : "string"
+	}];
+	return [];
+}
 //#endregion
 //#region ../common/src/util/enums.ts
 function enumToObjectEntries(enumValues) {
@@ -1321,6 +1390,8 @@ function getSubcollections(collection) {
 	}
 	return [];
 }
+policy.or(policy.serverContext(), policy.rolesOverlap(["admin"]));
+policy.or(policy.serverContext(), policy.rolesOverlap(["admin"]));
 (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function(root, factory) {
 		if (typeof define === "function" && define.amd) define(factory);
@@ -2753,18 +2824,45 @@ function deserializeLogicalCondition(str) {
 }
 //#endregion
 //#region ../common/src/data/buildRebaseData.ts
+function createPrimaryKeyResolver(options) {
+	const cache = /* @__PURE__ */ new Map();
+	const warned = /* @__PURE__ */ new Set();
+	return function primaryKeysFor(slug) {
+		const cached = cache.get(slug);
+		if (cached) return cached;
+		const collection = options?.resolveCollection?.(slug);
+		if (!collection) return [];
+		const keys = resolvePrimaryKeys(collection);
+		if (keys.length > 0) {
+			cache.set(slug, keys);
+			return keys;
+		}
+		if (!warned.has(slug)) {
+			warned.add(slug);
+			console.warn(`[rebase] Collection '${slug}' declares no primary key, so its rows have no address: detail links, caching and relations will not work for it. Mark the key property with \`isId\` in its collection config — the server logs which column to mark at boot, if its schema knows the key.`);
+		}
+		return keys;
+	};
+}
 /**
-* Convert a flat REST record (e.g. from RestFetchService) to Entity<M> format.
-* Mirrors the client SDK's rowToEntity conversion.
+* Give a flat row the Entity view-model the admin renders.
+*
+* The address is *derived here* — it is not a column, and the row it came from
+* does not contain one. Rows carry exactly what the table has, with the types
+* Postgres returned; the id is this layer's invention, and this is the only
+* place it is minted.
+*
+* `primaryKeys` empty falls back to a literal `id` on the row: drivers other
+* than postgres still serve rows with one, and this keeps them working.
 */
-function rowToEntity(row, slug) {
+function rowToEntity(row, slug, primaryKeys = []) {
 	return {
-		id: row.id,
+		id: primaryKeys.length > 0 ? buildCompositeId(row, primaryKeys) : row.id,
 		path: slug,
 		values: row
 	};
 }
-function createDriverAccessor(driver, slug) {
+function createDriverAccessor(driver, slug, getPks = () => []) {
 	const accessor = {
 		async find(params) {
 			const filter = params?.where ? deserializeFilter(params.where) : void 0;
@@ -2797,7 +2895,7 @@ function createDriverAccessor(driver, slug) {
 				hasMore = offset + rows.length < total;
 			}
 			return {
-				data: rows.map((row) => rowToEntity(row, slug)),
+				data: rows.map((row) => rowToEntity(row, slug, getPks())),
 				meta: {
 					total,
 					limit,
@@ -2811,7 +2909,7 @@ function createDriverAccessor(driver, slug) {
 				path: slug,
 				id
 			});
-			return row ? rowToEntity(row, slug) : void 0;
+			return row ? rowToEntity(row, slug, getPks()) : void 0;
 		},
 		async create(data, id) {
 			return rowToEntity(await driver.save({
@@ -2819,15 +2917,22 @@ function createDriverAccessor(driver, slug) {
 				values: data,
 				id,
 				status: "new"
-			}), slug);
+			}), slug, getPks());
 		},
+		createMany: driver.saveMany ? async (data, options) => {
+			return (await driver.saveMany({
+				path: slug,
+				rows: data,
+				upsert: options?.upsert
+			})).map((row) => rowToEntity(row, slug, getPks()));
+		} : void 0,
 		async update(id, data) {
 			return rowToEntity(await driver.save({
 				path: slug,
 				values: data,
 				id,
 				status: "existing"
-			}), slug);
+			}), slug, getPks());
 		},
 		async delete(id) {
 			return driver.delete({ row: {
@@ -2856,7 +2961,7 @@ function createDriverAccessor(driver, slug) {
 				searchString: params?.searchString,
 				onUpdate: (entities) => {
 					onUpdate({
-						data: entities.map((row) => rowToEntity(row, slug)),
+						data: entities.map((row) => rowToEntity(row, slug, getPks())),
 						meta: {
 							total: entities.length,
 							limit,
@@ -2872,7 +2977,7 @@ function createDriverAccessor(driver, slug) {
 			return driver.listenOne({
 				path: slug,
 				id,
-				onUpdate: (entity) => onUpdate(entity ? rowToEntity(entity, slug) : void 0),
+				onUpdate: (entity) => onUpdate(entity ? rowToEntity(entity, slug, getPks()) : void 0),
 				onError
 			});
 		} : void 0,
@@ -2911,12 +3016,13 @@ function createDriverAccessor(driver, slug) {
 * await data.products.create({ name: "Camera", price: 299 });
 * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
 */
-function buildRebaseData(driver) {
+function buildRebaseData(driver, options) {
 	const cache = /* @__PURE__ */ new Map();
+	const primaryKeysFor = createPrimaryKeyResolver(options);
 	function getAccessor(slug) {
 		let accessor = cache.get(slug);
 		if (!accessor) {
-			accessor = createDriverAccessor(driver, slug);
+			accessor = createDriverAccessor(driver, slug, () => primaryKeysFor(slug));
 			cache.set(slug, accessor);
 		}
 		return accessor;
@@ -2929,8 +3035,9 @@ function buildRebaseData(driver) {
 	} });
 }
 /**
-* Unwrap a Entity into a flat row. `rowToEntity` stores the whole flat row
-* (id included) under `.values`, so this is just that payload.
+* Unwrap a Entity back into the flat row it was built from. `rowToEntity` keeps
+* the row untouched under `.values` and derives `.id` alongside it, so dropping
+* the wrapper is the whole operation — the address was never part of the row.
 */
 function entityToRow(entity) {
 	return entity.values;
@@ -3017,6 +3124,12 @@ function toSdkCollectionClient(snap) {
 		async create(data, id) {
 			return entityToRow(await snap.create(data, id));
 		},
+		async createMany(data, options) {
+			if (!Array.isArray(data)) throw new TypeError("createMany expects an array of records.");
+			if (data.length === 0) return [];
+			if (!snap.createMany) throw new Error("Bulk writes are not supported by this collection's data source. Fall back to create() per record.");
+			return (await snap.createMany(data, options)).map(entityToRow);
+		},
 		async update(id, data) {
 			return entityToRow(await snap.update(id, data));
 		},
@@ -3725,15 +3838,19 @@ async function parseJsonBody(c) {
 * Lightweight REST API generator that leverages existing Rebase DataDriver.
 * Supports `include` query parameter for eager-loading relations via Drizzle.
 */
+/** Rows accepted by a single POST /<collection>/bulk. See `maxBulkRows`. */
+var DEFAULT_MAX_BULK_ROWS = 1e3;
 var RestApiGenerator = class {
 	collections;
 	router;
 	driver;
+	maxBulkRows;
 	authAdapter;
-	constructor(collections, driver, authAdapter) {
+	constructor(collections, driver, authAdapter, maxBulkRows = DEFAULT_MAX_BULK_ROWS) {
 		this.collections = collections;
 		this.driver = driver;
 		this.authAdapter = authAdapter;
+		this.maxBulkRows = maxBulkRows;
 		this.router = new Hono();
 	}
 	/**
@@ -3818,6 +3935,32 @@ var RestApiGenerator = class {
 			if (!entity) throw ApiError.notFound("Entity not found");
 			return c.json(entity);
 		});
+		this.router.post(`${basePath}/bulk`, async (c) => {
+			this.enforceApiKeyPermission(c, collection.slug);
+			const driver = this.getScopedDriver(c);
+			const path = collection.slug;
+			const body = await parseJsonBody(c);
+			if (!Array.isArray(body?.rows)) throw ApiError.badRequest("Expected a JSON body of { rows: [...] }.", "INVALID_BULK_BODY");
+			if (body.rows.length === 0) return c.json({
+				data: [],
+				meta: { written: 0 }
+			});
+			if (body.rows.some((row) => typeof row !== "object" || row === null || Array.isArray(row))) throw ApiError.badRequest("Every entry in `rows` must be an object.", "INVALID_BULK_BODY");
+			if (body.upsert !== void 0 && typeof body.upsert !== "boolean") throw ApiError.badRequest("`upsert` must be a boolean.", "INVALID_BULK_BODY");
+			const maxRows = this.maxBulkRows;
+			if (body.rows.length > maxRows) throw ApiError.badRequest(`Too many rows: ${body.rows.length} exceeds the ${maxRows}-row limit for a single bulk write. Send it in chunks of ${maxRows} or fewer.`, "BULK_TOO_LARGE");
+			if (!driver.saveMany) throw ApiError.badRequest("This collection's data source does not support bulk writes.", "BULK_UNSUPPORTED");
+			const rows = await driver.saveMany({
+				path,
+				rows: body.rows,
+				collection: resolvedCollection,
+				upsert: body.upsert === true
+			});
+			return c.json({
+				data: rows.map((row) => this.formatResponse(row)),
+				meta: { written: rows.length }
+			});
+		});
 		this.router.post(basePath, async (c) => {
 			try {
 				this.enforceApiKeyPermission(c, collection.slug);
@@ -9549,7 +9692,7 @@ function mountSessionRoutes(opts) {
 		clearRefreshCookie(c, config.cookieAuth);
 		const authHeader = c.req.header("authorization");
 		if (ops.afterLogout && authHeader?.startsWith("Bearer ")) {
-			const { verifyAccessToken } = await import("./jwt-BwIn8xmk.js").then((n) => n.c);
+			const { verifyAccessToken } = await import("./jwt-C6pbGtvf.js").then((n) => n.c);
 			const payload = verifyAccessToken(authHeader.substring(7));
 			if (payload) ops.afterLogout(payload.userId).catch((err) => {
 				logger.error("[AuthHooks] afterLogout error", { error: err instanceof Error ? err.message : err });
@@ -10953,6 +11096,98 @@ function requestLogger(options) {
 	};
 }
 //#endregion
+//#region src/api/logs-routes.ts
+var logs_routes_exports = /* @__PURE__ */ __exportAll({
+	addLog: () => addLog,
+	default: () => app,
+	logBuffer: () => logBuffer,
+	logMiddleware: () => logMiddleware
+});
+var LogRingBuffer = class {
+	buffer = [];
+	maxSize;
+	idCounter = 0;
+	constructor(maxSize = 1e4) {
+		this.maxSize = maxSize;
+	}
+	push(entry) {
+		const id = `log_${++this.idCounter}`;
+		this.buffer.push({
+			...entry,
+			id
+		});
+		if (this.buffer.length > this.maxSize) this.buffer.shift();
+	}
+	query(options) {
+		let filtered = this.buffer;
+		if (options.level) filtered = filtered.filter((e) => e.level === options.level);
+		if (options.source) filtered = filtered.filter((e) => e.source === options.source);
+		if (options.search) {
+			const searchLower = options.search.toLowerCase();
+			filtered = filtered.filter((e) => e.message.toLowerCase().includes(searchLower));
+		}
+		if (options.since) {
+			const sinceValue = options.since;
+			filtered = filtered.filter((e) => e.timestamp >= sinceValue);
+		}
+		const sorted = [...filtered].reverse();
+		const total = sorted.length;
+		const limit = options.limit || 100;
+		const offset = options.offset || 0;
+		return {
+			entries: sorted.slice(offset, offset + limit),
+			total
+		};
+	}
+	getLatest(count = 50) {
+		return this.buffer.slice(-count).reverse();
+	}
+};
+var logBuffer = new LogRingBuffer();
+/** Add a log entry */
+function addLog(level, source, message, metadata) {
+	logBuffer.push({
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		level,
+		source,
+		message,
+		metadata
+	});
+}
+/** Hono middleware to log API requests */
+function logMiddleware() {
+	return async (c, next) => {
+		const start = Date.now();
+		await next();
+		const duration = Date.now() - start;
+		const reqId = c.get("requestId");
+		addLog("info", "api", `${c.req.method} ${c.req.path} ${c.res.status} ${duration}ms`, {
+			method: c.req.method,
+			path: c.req.path,
+			status: c.res.status,
+			duration,
+			...reqId && { requestId: reqId }
+		});
+	};
+}
+var app = new Hono();
+app.get("/", (c) => {
+	const query = c.req.query();
+	const result = logBuffer.query({
+		level: query.level,
+		source: query.source,
+		search: query.search,
+		limit: query.limit ? parseInt(query.limit) : void 0,
+		offset: query.offset ? parseInt(query.offset) : void 0,
+		since: query.since
+	});
+	return c.json(result);
+});
+app.get("/latest", (c) => {
+	const count = parseInt(c.req.query("count") || "50");
+	return c.json({ entries: logBuffer.getLatest(count) });
+});
+//#endregion
 //#region src/init/middlewares.ts
 function configureMiddlewares(app, basePath, isProduction, config) {
 	app.use(`${basePath}/*`, requestId());
@@ -10979,6 +11214,7 @@ function configureMiddlewares(app, basePath, isProduction, config) {
 	}
 	if (!isProduction && !process.env.CORS_ORIGINS && !process.env.FRONTEND_URL) logger.warn("No CORS configuration detected (CORS_ORIGINS / FRONTEND_URL not set). The API will accept requests from any origin. Set CORS_ORIGINS in your .env file to restrict access.");
 	app.use(`${basePath}/*`, requestLogger());
+	app.use(`${basePath}/*`, logMiddleware());
 }
 //#endregion
 //#region src/storage/types.ts
@@ -11518,7 +11754,7 @@ var gcsModule = null;
 async function loadGCS() {
 	if (gcsModule) return gcsModule;
 	try {
-		gcsModule = await import("./src-B9tjYmqP.js");
+		gcsModule = await import("@google-cloud/storage");
 		return gcsModule;
 	} catch {
 		throw new Error("Google Cloud Storage is required for the GCS storage controller. Install it with: pnpm add @google-cloud/storage");
@@ -14965,7 +15201,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);
 	}
 };
@@ -14998,6 +15234,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",
@@ -15605,7 +15852,9 @@ 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;
@@ -15627,12 +15876,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;
@@ -15982,17 +16233,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(":::").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);
@@ -16004,7 +16277,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;
 		});
@@ -16249,7 +16522,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({
@@ -16361,6 +16634,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,
@@ -17069,6 +17352,10 @@ async function _initializeRebaseBackend(config) {
 		dataAsAdmin: serverData
 	});
 	logger.info("Native data plane attached to singleton (bypasses HTTP loop)");
+	if (storageController) {
+		Object.assign(serverClient, { storage: storageController });
+		logger.info("Native storage attached to singleton (bypasses HTTP loop)");
+	}
 	let emailService;
 	if (authConfigResult?.emailService) emailService = authConfigResult.emailService;
 	else if (config.auth && !isAuthAdapter(config.auth) && config.auth.email) emailService = createEmailService(config.auth.email);
@@ -17169,6 +17456,17 @@ async function _initializeRebaseBackend(config) {
 		config.app.route(`${basePath}/admin/backups`, backupRouter);
 		logger.info("Backup admin routes mounted", { path: `${basePath}/admin/backups` });
 	}
+	{
+		const { default: logsRoutes } = await Promise.resolve().then(() => logs_routes_exports);
+		const logsRouter = new Hono();
+		if (authAdapter && !isAuthAdapter(config.auth)) {
+			const safeAuth = config.auth;
+			if (safeAuth.requireAuth !== false && !!safeAuth.jwtSecret) logsRouter.use("/*", requireAuth, requireAdmin);
+		} else if (authAdapter) logsRouter.use("/*", requireAuth, requireAdmin);
+		logsRouter.route("/", logsRoutes);
+		config.app.route(`${basePath}/logs`, logsRouter);
+		logger.info("Logs routes mounted", { path: `${basePath}/logs` });
+	}
 	const effectiveRealtimeService = Object.keys(realtimeServices).length > 1 ? createRoutedRealtimeService({
 		providers: realtimeServices,
 		defaultKey: defaultDriverId,
@@ -17182,9 +17480,34 @@ async function _initializeRebaseBackend(config) {
 		cronScheduler,
 		realtimeServices
 	});
+	/**
+	* Every registry a driver might resolve callbacks from, plus the backend's
+	* own. Each holds its own normalized copy of a collection, so callbacks have
+	* to be written to all of them.
+	*/
+	const callbackTargets = () => {
+		const targets = [collectionRegistry];
+		for (const key of [DEFAULT_DRIVER_ID, ...driverRegistry.list()]) {
+			const d = driverRegistry.get(key);
+			if (d?.registry && typeof d.registry.get === "function" && !targets.includes(d.registry)) targets.push(d.registry);
+		}
+		return targets;
+	};
+	const setCollectionCallbacks = (slug, callbacks) => {
+		let attached = 0;
+		for (const registry of callbackTargets()) {
+			const collection = registry.get(slug);
+			if (collection) {
+				collection.callbacks = callbacks;
+				attached++;
+			}
+		}
+		if (attached === 0) logger.warn(`[callbacks] Collection "${slug}" not found in any registry — callbacks not attached.`);
+	};
 	return {
 		driverRegistry,
 		driver: defaultDriver,
+		setCollectionCallbacks,
 		realtimeServices,
 		realtimeService: effectiveRealtimeService,
 		auth: authConfigResult,