@protobase/server 0.14.1 → 0.14.3

package/dist/aggregate-service.js

@@ -4,6 +4,7 @@ import { checkedFilter } from "./filter-input.js";
 import { readScope, requestAccess, requireOperation } from "./request-access.js";
 import { readTransaction } from "./transactions.js";
 import { parseParams } from "./params.js";
+import { labelRequests, relatedLabels } from "./related-labels.js";
 import { facetCounts, histogram, series } from "@protobase/query";
 import { sql } from "kysely";
 import { z } from "zod";
@@ -13,7 +14,8 @@ const filter = z.string().optional();
 const facetParams = z.object({
 	field,
 	filter,
-	limit: z.coerce.number().int().optional()
+	limit: z.coerce.number().int().optional(),
+	label: z.string().min(1).optional()
 });
 const seriesParams = z.object({
 	field,
@@ -56,19 +58,33 @@ const scoped = async (deps, entry, session, source) => {
 		scope: readScope(access)
 	};
 };
-/** Counts per value of a field, ignoring the filter's own terms on that field (AIP-160 filters, UI facet panels). */
+/**
+* Counts per value of a field, ignoring the filter's own terms on that field (AIP-160 filters, UI facet panels). With
+* `label`, a relation's values carry the `label` field of the record each points at, read as a list's `labels` reads it.
+*/
 const facets = async (deps, entry, session, input) => {
 	const params = parseParams(facetParams, input);
 	const { model, filter: checked, scope } = await scoped(deps, entry, session, params.filter);
-	const counts = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => facetCounts(trx, model, params.field, checked, {
-		statementTimeoutMs: deps.statementTimeoutMs,
-		...params.limit !== void 0 && { limit: params.limit },
-		scope
-	}));
-	return {
-		field: params.field,
-		facets: counts
-	};
+	const labels = params.label === void 0 ? [] : await labelRequests(deps, session, model, [params.field], `${params.field}.${params.label}`);
+	return readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		const counts = await facetCounts(trx, model, params.field, checked, {
+			statementTimeoutMs: deps.statementTimeoutMs,
+			...params.limit !== void 0 && { limit: params.limit },
+			scope
+		});
+		const names = (await relatedLabels(trx, labels, counts.map((facet) => ({ [params.field]: facet.value }))))[params.field] ?? {};
+		const named = counts.map((facet) => {
+			const label = facet.value === null ? void 0 : names[String(facet.value)];
+			return label === void 0 ? facet : {
+				...facet,
+				label
+			};
+		});
+		return {
+			field: params.field,
+			facets: named
+		};
+	});
 };
 const earliest = async (deps, access, fieldName, scope) => {
 	const target = access.model.fields[fieldName];

package/dist/check-views.js

@@ -1,5 +1,6 @@
 import { relatedErrors } from "./view-related.js";
 import { cardPhotosErrors } from "./view-card-photos.js";
+import { cardFavoriteErrors, favoriteOwnerErrors } from "./view-card-favorite.js";
 import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { addressErrors, addressPlaceholders, appHrefError, displayFields, fieldRefsIn, hrefPlaceholders } from "@protobase/schema/internal";
 //#region src/check-views.ts
@@ -57,11 +58,25 @@ const widgetErrors = (view, model, fieldTypes) => Object.entries(view.fields).fl
 	if (!of || !field || of.includes(field.type)) return [];
 	return [`field "${name}" is ${field.type}, and its field type "${hints.widget.name}" shows only ${of.join(", ")}`];
 });
+const sharedPhotosErrors = (view) => {
+	const shown = (view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? [{
+		name: display.name,
+		photos: display.photos
+	}] : []);
+	const same = (a, b) => a.resource === b.resource && a.field === b.field && a.image === b.image && a.sort === b.sort;
+	return shown.filter(({ photos }) => !same(photos, shown[0].photos)).map(({ name }) => `display "${name}" photos: the list's records load with one set of photos, so name those of display "${shown[0].name}"`);
+};
+const listOfErrors = (model, name, models) => {
+	const target = models[model.fields[name]?.relation?.resource ?? ""];
+	if (!target) return [`"${name}" points at no resource of the app`];
+	return target.primaryKey.length === 1 ? [] : [`${target.name} has a composite key, so its records cannot be listed by key`];
+};
 /**
 * Fails at startup when a view uses a sensitive field where it would show empty, a display or custom section names a
 * field the resource does not have, labels or colours values its enum does not have, shows a field with a field type of
 * `fieldTypes` (each with the storage types it shows) that does not show it,
-* has a related section or a cards display's photos that do not fit the resources, a map that cannot show the
+* has a related section, a cards display's photos or favorite button or a `listOf` that do not fit the resources, cards
+* displays of one list that name different photos, a map that cannot show the
 * record's position or a map display that cannot find the records in its view, or a link to an address the app does not have.
 */
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
@@ -71,7 +86,9 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		const model = models[view.resource];
 		if (!model) return [];
 		const related = view.layout.flatMap((item) => item.kind === "related" ? relatedErrors(item, view.resource, models).map((error) => `related "${item.title}": ${error}`) : []);
-		const photos = (view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []);
+		const photos = [...(view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []), ...sharedPhotosErrors(view)];
+		const favorites = (view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.favorite ? [...cardFavoriteErrors(display.favorite, view.resource, models), ...favoriteOwnerErrors(display.favorite, models)].map((error) => `display "${display.name}" favorite: ${error}`) : []);
+		const listOf = view.listOf === void 0 ? [] : listOfErrors(model, view.listOf, models).map((error) => `listOf: ${error}`);
 		const maps = [...view.layout.flatMap((item) => item.kind === "map" ? mapErrors(item, model).map((error) => `map "${item.title}": ${error}`) : []), ...(view.list?.displays ?? []).flatMap((display) => display.kind === "map" ? mapDisplayErrors(display, model).map((error) => `display "${display.name}": ${error}`) : [])];
 		return [
 			...sensitiveErrors(view, model),
@@ -81,6 +98,8 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...widgetErrors(view, model, fieldTypes),
 			...related,
 			...photos,
+			...favorites,
+			...listOf,
 			...maps,
 			...linkErrors(view, model, models, pageNames)
 		].map((problem) => `View "${view.resource}": ${problem}`);

package/dist/list-photos.js

@@ -0,0 +1,101 @@
+import { badRequest } from "./problem.js";
+import { presentFiles } from "./files/present.js";
+import { exposeRow } from "./rows.js";
+import { checkedSort } from "./filter-input.js";
+import { readScope, requestAccess } from "./request-access.js";
+import { readTransaction } from "./transactions.js";
+import { cardPhotosErrors } from "./view-card-photos.js";
+import { checkFilter, createWhere } from "@protobase/schema";
+import { cardPhotoLimit } from "@protobase/schema/internal";
+import { relatedRows } from "@protobase/query";
+//#region src/list-photos.ts
+const where = createWhere();
+const invalid = (parameter, message) => badRequest("invalid-parameter", `Invalid ${parameter}: ${message}`, { errors: [{
+	parameter,
+	message
+}] });
+/**
+* Checks `photos` (`resource.field.image`) and `photos_order_by` against the listed resource and the caller's access
+* to the photos' resource. The caller gets photos only where a cards display would keep its `photos` for them: they
+* can list that resource, and read and use `field`, `image` and the sorted fields. Anything less answers no photos
+* rather than an error, so the parameter never tells a resource or field exists.
+*/
+const photosRequest = async (deps, session, model, photos, orderBy) => {
+	if (photos === void 0) {
+		if (orderBy !== void 0) throw invalid("photos_order_by", "Name the photos it orders with photos");
+		return;
+	}
+	const [resource, field, image, ...rest] = photos.split(".").map((part) => part.trim());
+	if (!resource || !field || !image || rest.length > 0) throw invalid("photos", "Name the photos' resource, its relation to this one and its file field, as resource.field.image");
+	const named = {
+		resource,
+		field,
+		image,
+		...orderBy?.trim() && { sort: orderBy }
+	};
+	const target = deps.registry.find(resource);
+	if (!target) return { photos: named };
+	const access = await requestAccess(deps, target, session);
+	const models = {
+		[resource]: access.model,
+		[model.name]: model
+	};
+	return access.resolved.operations.list && cardPhotosErrors(named, model.name, models).length === 0 ? {
+		photos: named,
+		access
+	} : { photos: named };
+};
+const photoColumns = ({ photos, access }) => {
+	const placeholder = access.model.fields[photos.image].file?.placeholder;
+	return [
+		...access.full.primaryKey,
+		photos.image,
+		...placeholder === void 0 ? [] : [placeholder]
+	].filter((name) => Object.hasOwn(access.model.fields, name));
+};
+/**
+* The first photos of each row, at most `cardPhotoLimit`, read as the caller lists the photos' resource: its tenant,
+* row filter, soft delete and readable fields apply, and its files are linked for them. One query reads them all, after
+* the scan guard has checked an index serves the lookup.
+*/
+const recordPhotos = async (deps, request, model, rows) => {
+	const keyField = model.primaryKey[0];
+	const keys = [...new Set(rows.map((row) => row[keyField]).filter((key) => key !== null && key !== void 0).map(String))];
+	if (!request.access || keys.length === 0) return { photos: {} };
+	const { photos, access } = request;
+	const sort = checkedSort(access.model, photos.sort);
+	const filter = checkFilter(access.model, where.in(photos.field, keys));
+	if (!filter.ok) throw new Error(`Keys of "${model.name}" do not make a filter of "${photos.resource}": ${filter.errors[0].message}`);
+	const scope = readScope(access);
+	const warning = await deps.guard(access.entry, {
+		filter: filter.filter,
+		...sort && { sort },
+		limit: cardPhotoLimit
+	}, {
+		model: access.model,
+		scope
+	});
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => relatedRows(trx, access.model, {
+		field: photos.field,
+		values: keys,
+		columns: photoColumns({
+			photos,
+			access
+		}),
+		...sort && { sort },
+		limit: cardPhotoLimit
+	}, scope));
+	const shown = await presentFiles(access, found.map((row) => exposeRow(access.model, row)));
+	const byRecord = {};
+	for (const row of shown) {
+		if (row[photos.image] === null || row[photos.image] === void 0) continue;
+		const key = String(row[photos.field]);
+		byRecord[key] = [...byRecord[key] ?? [], row[photos.image]];
+	}
+	return {
+		photos: byRecord,
+		...warning && { warning }
+	};
+};
+//#endregion
+export { photosRequest, recordPhotos };

package/dist/list-service.js

@@ -7,12 +7,16 @@ import { readScope, requestAccess, requireOperation } from "./request-access.js"
 import { rowPermissions } from "./row-permissions.js";
 import { readTransaction } from "./transactions.js";
 import { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields } from "./params.js";
+import { labelRequests, relatedLabels } from "./related-labels.js";
+import { photosRequest, recordPhotos } from "./list-photos.js";
 import { estimateCount, exactCount, listQuery, seekToPosition } from "@protobase/query";
 //#region src/list-service.ts
 /**
 * AIP-132 list, the `:search` variant and (with `jump`) `:seek`: both take the same parameters, from the query string or a JSON body.
 * Everything the caller names (filter, order_by, fields, search) is checked against the model as this caller sees it,
 * so a hidden field is refused exactly like an unknown one; the access row filter is applied by the query layer.
+* `labels` names the records the returned relations point at, each read under the related resource's own access, and
+* `photos` brings each record's first photos, read under the photos' resource's own access.
 */
 const listRecords = async (deps, entry, session, input, maxFilterLength, jump = false) => {
 	const params = jump ? parseParams(seekParams, input) : parseParams(listParams, input);
@@ -30,6 +34,8 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 	const filter = checkedFilter(model, params.filter, maxFilterLength);
 	const sort = checkedSort(model, params.order_by);
 	const columns = selectedFields(model, params.fields);
+	const labels = await labelRequests(deps, session, model, columns, params.labels);
+	const photos = await photosRequest(deps, session, model, params.photos, params.photos_order_by);
 	const limit = pageSizeOf(params.page_size);
 	const scope = readScope(access, full);
 	const etagField = entry.etag && !model.fields[entry.etag.field.name] ? full.fields[entry.etag.field.name] : void 0;
@@ -40,7 +46,7 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 			[etagField.name]: etagField
 		}
 	} : model;
-	const withKey = columns?.some((name) => model.fields[name].type === "file") ? [.../* @__PURE__ */ new Set([...columns, ...entry.model.primaryKey.filter((name) => model.fields[name])])] : columns;
+	const withKey = (photos !== void 0 || columns?.some((name) => model.fields[name].type === "file")) && columns ? [.../* @__PURE__ */ new Set([...columns, ...entry.model.primaryKey.filter((name) => model.fields[name])])] : columns;
 	const read = entry.etag && withKey ? withKey : Object.keys(model.fields);
 	const shape = {
 		...filter && { filter },
@@ -76,13 +82,16 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 			etags: await Promise.all(rows.map((row, i) => etagOf(entry, page.rows[i], row))),
 			permissions: deps.rowPermissions(entry.name) ? await rowPermissions(trx, access, rows) : void 0,
 			estimate: await estimateCount(trx, queryModel, filter, scope),
-			...params.count === "exact" && { total: await exactCount(trx, queryModel, filter, scope) }
+			...params.count === "exact" && { total: await exactCount(trx, queryModel, filter, scope) },
+			...params.labels !== void 0 && { labels: await relatedLabels(trx, labels, rows) }
 		};
 	});
+	const shown = await presentFiles(access, result.rows);
+	const included = photos && await recordPhotos(deps, photos, model, result.rows);
 	return {
-		warning,
+		warning: warning ?? included?.warning,
 		body: {
-			items: (await presentFiles(access, result.rows)).map((row, i) => ({
+			items: shown.map((row, i) => ({
 				...pickFields(row, columns),
 				etag: result.etags[i],
 				...result.permissions && { permissions: result.permissions[i] }
@@ -90,7 +99,9 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 			next_page_token: result.page.nextCursor ?? "",
 			...position !== void 0 && { prev_page_token: result.page.prevCursor ?? "" },
 			total_size_estimate: result.estimate,
-			...result.total !== void 0 && { total_size: result.total }
+			...result.total !== void 0 && { total_size: result.total },
+			...result.labels && { labels: result.labels },
+			...included && { photos: included.photos }
 		}
 	};
 };

package/dist/map-service.js

@@ -1,7 +1,9 @@
 import { checkedFilter } from "./filter-input.js";
 import { readScope, requestAccess, requireOperation } from "./request-access.js";
 import { readTransaction } from "./transactions.js";
-import { parseParams } from "./params.js";
+import { parseParams, selectedFields } from "./params.js";
+import { labelRequests } from "./related-labels.js";
+import { photosRequest } from "./list-photos.js";
 import { listRecords } from "./list-service.js";
 import { checkMapPosition, countUpTo, mapBuckets, maxMapZoom } from "@protobase/query";
 import { z } from "zod";
@@ -11,7 +13,10 @@ const mapParams = z.object({
 	zoom: z.coerce.number().int().min(0).max(maxMapZoom),
 	filter: z.string().optional(),
 	order_by: z.string().optional(),
-	fields: z.union([z.string(), z.array(z.string())]).optional()
+	fields: z.union([z.string(), z.array(z.string())]).optional(),
+	labels: z.string().optional(),
+	photos: z.string().optional(),
+	photos_order_by: z.string().optional()
 });
 /**
 * The matching records for a map at `zoom`, the bounding box being part of the filter: the records themselves when
@@ -31,10 +36,9 @@ const mapRecords = async (deps, entry, session, input) => {
 	const scope = readScope(access);
 	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => countUpTo(trx, access.model, 201, filter, scope));
 	if (found <= 200 || params.zoom >= 16) {
+		const { latitude: _latitude, longitude: _longitude, zoom: _zoom, ...asked } = params;
 		const list = {
-			filter: params.filter,
-			order_by: params.order_by,
-			fields: params.fields,
+			...asked,
 			page_size: 200,
 			...found > 200 && { count: "exact" }
 		};
@@ -44,17 +48,23 @@ const mapRecords = async (deps, entry, session, input) => {
 			body: {
 				items: body.items,
 				buckets: [],
-				total_size: body.total_size ?? found
+				total_size: body.total_size ?? found,
+				...body.labels && { labels: body.labels },
+				...body.photos && { photos: body.photos }
 			}
 		};
 	}
+	if (params.labels !== void 0) await labelRequests(deps, session, access.model, selectedFields(access.model, params.fields), params.labels);
+	await photosRequest(deps, session, access.model, params.photos, params.photos_order_by);
 	const result = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => mapBuckets(trx, access.model, position, params.zoom, filter, scope));
 	return {
 		warning: void 0,
 		body: {
 			items: [],
 			buckets: result.buckets,
-			total_size: result.total
+			total_size: result.total,
+			...params.labels !== void 0 && { labels: {} },
+			...params.photos !== void 0 && { photos: {} }
 		}
 	};
 };

package/dist/meta.js

@@ -10,21 +10,35 @@ import { prunePage } from "@protobase/layout";
 import { pickView } from "@protobase/schema";
 import { bottomBarFor } from "@protobase/schema/internal";
 //#region src/meta.ts
+const signInView = (view) => {
+	if (!view?.signIn) return [];
+	const { recent: _recent, ...nav } = view.nav ?? {};
+	return [{
+		resource: view.resource,
+		...view.names && { names: view.names },
+		...view.nav && { nav },
+		signIn: view.signIn
+	}];
+};
 const modelsHash = (deps) => sha256Hex(stableJson(deps.registry.entries.map((entry) => entry.model))).then((hash) => hash.slice(0, 32));
 /**
 * `/meta` as one caller sees it: the resources they can do anything with, each as the restricted model (hidden fields
 * absent, `readOnly` unless writable), the view for their roles with hidden fields pruned, what they may do, and the
-* user menu and their bottom bar without the resources they cannot see.
+* user menu and their bottom bar without the resources they cannot see. A visitor also gets the prompts of the resources
+* they could use once signed in, which keep their place in the bottom bar and the user menu.
 * The ETag hashes all of it, so it differs per user and per roles.
 */
 const createMeta = (deps) => {
 	const base = modelsHash(deps);
 	const forCaller = async (session) => {
-		const visible = (await Promise.all(deps.registry.entries.map((entry) => requestAccess(deps, entry, session)))).filter((access) => Object.values(access.resolved.operations).some(Boolean));
+		const accesses = await Promise.all(deps.registry.entries.map((entry) => requestAccess(deps, entry, session)));
+		const visible = accesses.filter((access) => Object.values(access.resolved.operations).some(Boolean));
 		const listed = Object.fromEntries(visible.map((access) => [access.entry.name, access.model]));
+		const signIn = session.anonymous ? accesses.filter((access) => !visible.includes(access)).flatMap((access) => signInView(pickView(deps.views, session.user.roles, access.entry.name))) : [];
+		const prompted = new Set(signIn.map((entry) => entry.resource));
 		const views = visible.flatMap((access) => {
 			const view = pickView(deps.views, session.user.roles, access.entry.name);
-			return view ? [pruneView(view, access.readable, listed)] : [];
+			return view ? [pruneView(view, access.readable, listed, prompted)] : [];
 		});
 		const callerAccess = {
 			models: listed,
@@ -35,7 +49,7 @@ const createMeta = (deps) => {
 			actions: (resource) => new Set(views.find((view) => view.resource === resource)?.actions.map((action) => action.name) ?? [])
 		};
 		const pages = deps.pages.flatMap((page) => prunePage(page, session.user.roles, callerAccess) ?? []);
-		const shown = (item) => item.kind === "link" || (item.kind === "resource" ? visible.some((access) => access.entry.name === item.resource) : pages.some((page) => page.name === item.page));
+		const shown = (item) => item.kind === "link" || (item.kind === "resource" ? visible.some((access) => access.entry.name === item.resource) || prompted.has(item.resource) : pages.some((page) => page.name === item.page));
 		const bar = bottomBarFor(deps.bottomBars, activeRole(session));
 		const barItems = bar?.items.filter(shown) ?? [];
 		const plugins = pluginsFor(deps.plugins, session.user.roles);
@@ -55,6 +69,7 @@ const createMeta = (deps) => {
 					"delete"
 				].filter((op) => resolved.operations[op] && (resolved.recordChecks.includes(op) || resolved.rowFilter[op] !== void 0))
 			}])),
+			...signIn.length > 0 && { signIn },
 			...deps.userMenu && { userMenu: { items: deps.userMenu.items.filter(shown) } },
 			...bar && barItems.length > 0 && { bottomBar: {
 				label: bar.label,

package/dist/openapi/components.js

@@ -1,3 +1,4 @@
+import { cardPhotoLimit } from "@protobase/schema/internal";
 //#region src/openapi/components.ts
 const problemContent = { "application/problem+json": { schema: { $ref: "#/components/schemas/Problem" } } };
 const problem = (description) => ({
@@ -98,6 +99,24 @@ const parameters = {
 			enum: ["exact"]
 		}
 	},
+	labels: {
+		name: "labels",
+		in: "query",
+		description: "Comma separated `relation.field` entries, such as `place_id.name`: the answer's `labels` maps each relation to the names of the records it points at, by key, each the `field` of that record. Only for returned relations to single-key resources. A related record the caller cannot list, or whose `field` they cannot read, is left out, so it goes by its key.",
+		schema: { type: "string" }
+	},
+	photos: {
+		name: "photos",
+		in: "query",
+		description: `A \`resource.field.image\` entry, such as \`listing_photos.listing_id.photo\`: the answer's \`photos\` maps each returned record's key to the \`image\` files of the first ${cardPhotoLimit} records of \`resource\` whose relation \`field\` points at it, read in one query as the caller lists \`resource\`. A record without any is left out, and so is every record when the caller cannot list \`resource\` or read and use \`field\`, \`image\` and the sorted fields. Only for resources with a single-field key.`,
+		schema: { type: "string" }
+	},
+	photosOrderBy: {
+		name: "photos_order_by",
+		in: "query",
+		description: "The order of each record's `photos`, as `order_by` on their resource: `position`. Their primary key breaks ties.",
+		schema: { type: "string" }
+	},
 	key: {
 		name: "key",
 		in: "path",
@@ -150,6 +169,19 @@ const searchBody = {
 			type: "string",
 			enum: ["exact"]
 		},
+		labels: {
+			type: "array",
+			items: { type: "string" },
+			description: parameters.labels.description
+		},
+		photos: {
+			type: "string",
+			description: parameters.photos.description
+		},
+		photos_order_by: {
+			type: "string",
+			description: parameters.photosOrderBy.description
+		},
 		show_deleted: {
 			type: "boolean",
 			description: "Soft-delete resources only"

package/dist/openapi/resource-paths.js

@@ -12,6 +12,9 @@ const listParameters = (entry) => [
 	"pageSize",
 	"pageToken",
 	"fields",
+	"labels",
+	"photos",
+	"photosOrderBy",
 	"count",
 	...entry.model.softDelete ? ["showDeleted"] : []
 ].map(param);
@@ -34,6 +37,22 @@ const record = (name, entry) => ({
 	headers: { ETag: { schema: { type: "string" } } },
 	content: json(ref(name))
 });
+const labels = {
+	type: "object",
+	description: "Only with `labels`: per relation, the names of the records it points at, by key",
+	additionalProperties: {
+		type: "object",
+		additionalProperties: { type: "string" }
+	}
+};
+const photos = {
+	type: "object",
+	description: "Only with `photos`: per record, by key, its first photos in their order, each as a file field returns it",
+	additionalProperties: {
+		type: "array",
+		items: { type: "object" }
+	}
+};
 const page = (name, seek = false) => json({
 	type: "object",
 	required: [
@@ -61,7 +80,9 @@ const page = (name, seek = false) => json({
 		total_size: {
 			type: "integer",
 			description: "Only with count=exact"
-		}
+		},
+		labels,
+		photos
 	}
 });
 const bounds = {
@@ -100,7 +121,9 @@ const mapResult = (name) => json({
 		total_size: {
 			type: "integer",
 			description: "How many records match"
-		}
+		},
+		labels,
+		photos
 	}
 });
 const needs = {
@@ -309,7 +332,8 @@ const resourcePaths = (access) => {
 			parameters: [
 				field("A filterable field"),
 				param("filter"),
-				query("limit", "Most values to return", { type: "integer" })
+				query("limit", "Most values to return", { type: "integer" }),
+				query("label", "For a relation to a single-key resource: the field of that resource whose value each facet carries as `label`, as a list's `labels` names records")
 			],
 			responses: {
 				200: {
@@ -324,7 +348,11 @@ const resourcePaths = (access) => {
 									type: "object",
 									properties: {
 										value: {},
-										count: { type: "integer" }
+										count: { type: "integer" },
+										label: {
+											type: "string",
+											description: "Only with `label`, for a record the caller may name"
+										}
 									}
 								}
 							}
@@ -442,7 +470,10 @@ const resourcePaths = (access) => {
 				}, true),
 				param("filter"),
 				param("orderBy"),
-				param("fields")
+				param("fields"),
+				param("labels"),
+				param("photos"),
+				param("photosOrderBy")
 			],
 			responses: {
 				200: {
@@ -467,6 +498,9 @@ const resourcePaths = (access) => {
 				param("filter"),
 				param("pageSize"),
 				param("fields"),
+				param("labels"),
+				param("photos"),
+				param("photosOrderBy"),
 				param("count")
 			],
 			responses: {

package/dist/params.js

@@ -18,6 +18,9 @@ const listParams = z.object({
 	page_token: z.string().optional(),
 	fields: z.union([z.string(), z.array(z.string())]).optional(),
 	count: z.literal("exact").optional(),
+	labels: z.union([z.string(), z.array(z.string())]).optional(),
+	photos: z.string().optional(),
+	photos_order_by: z.string().optional(),
 	show_deleted: z.union([z.boolean(), z.enum(["true", "false"]).transform((value) => value === "true")]).optional()
 });
 /** The list parameters plus the row position to jump to (`:seek`). */

package/dist/related-labels.js

@@ -0,0 +1,77 @@
+import { badRequest } from "./problem.js";
+import { exposeRow } from "./rows.js";
+import { readScope, requestAccess } from "./request-access.js";
+import { checkFilter, createWhere } from "@protobase/schema";
+import { listQuery } from "@protobase/query";
+//#region src/related-labels.ts
+const where = createWhere();
+const invalid = (entry, message) => badRequest("invalid-parameter", `Invalid labels entry "${entry}": ${message}`, { errors: [{
+	parameter: "labels",
+	message
+}] });
+const unnameable = /* @__PURE__ */ new Set(["file", "json"]);
+/**
+* Checks `labels` against the listed resource as the caller sees it: each entry names a returned relation to a
+* single-key resource, once. What the caller may read of the related resource is resolved here too, so a related
+* resource or field they cannot read answers no names rather than an error that would tell it exists.
+*/
+const labelRequests = async (deps, session, model, returned, labels) => {
+	if (labels === void 0) return [];
+	const entries = (Array.isArray(labels) ? labels : labels.split(",")).map((entry) => entry.trim()).filter(Boolean);
+	const seen = /* @__PURE__ */ new Set();
+	return Promise.all(entries.map(async (entry) => {
+		const [relation, field, ...rest] = entry.split(".");
+		if (!relation || !field || rest.length > 0) throw invalid(entry, "Name a relation and the field that names its records, as relation.field");
+		const owner = Object.hasOwn(model.fields, relation) ? model.fields[relation] : void 0;
+		if (!owner) throw invalid(entry, `Unknown field "${relation}"`);
+		const target = owner.type === "relation" && owner.relation ? deps.registry.find(owner.relation.resource) : void 0;
+		if (!target || target.model.primaryKey.length !== 1) throw invalid(entry, `"${relation}" is not a relation to a resource with a single-field key`);
+		if (returned && !returned.includes(relation)) throw invalid(entry, `"${relation}" is not among the returned fields`);
+		if (seen.has(relation)) throw invalid(entry, `"${relation}" is named twice`);
+		seen.add(relation);
+		const access = await requestAccess(deps, target, session);
+		const named = Object.hasOwn(access.model.fields, field) ? access.model.fields[field] : void 0;
+		if (!access.resolved.operations.list || !named) return {
+			relation,
+			field
+		};
+		if (unnameable.has(named.type)) throw invalid(entry, `"${field}" is a ${named.type} field, which cannot name a record`);
+		return {
+			relation,
+			field,
+			access
+		};
+	}));
+};
+const namesOf = async (trx, { field, access }, keys) => {
+	const key = access.full.primaryKey[0];
+	const model = {
+		...access.model,
+		fields: {
+			...access.model.fields,
+			[key]: {
+				...access.model.fields[key],
+				filterable: true
+			}
+		}
+	};
+	const filter = checkFilter(model, where.in(key, keys));
+	if (!filter.ok) throw new Error(`Keys of "${access.entry.name}" do not make a filter: ${filter.errors[0].message}`);
+	const named = (await listQuery(trx, model, {
+		filter: filter.filter,
+		columns: [key, field],
+		limit: keys.length
+	}, readScope(access))).rows.map((row) => exposeRow(model, row)).filter((row) => row[field] !== null && row[field] !== void 0);
+	return Object.fromEntries(named.map((row) => [String(row[key]), String(row[field])]));
+};
+/** The names of the records the rows' relations point at, one query per requested relation. */
+const relatedLabels = async (trx, requests, rows) => {
+	const labels = {};
+	for (const request of requests) {
+		const keys = [...new Set(rows.flatMap((row) => row[request.relation] === null || row[request.relation] === void 0 ? [] : [String(row[request.relation])]))];
+		labels[request.relation] = request.access && keys.length > 0 ? await namesOf(trx, request, keys) : {};
+	}
+	return labels;
+};
+//#endregion
+export { labelRequests, relatedLabels };

package/dist/view-access.js

@@ -1,5 +1,6 @@
 import { relatedErrors } from "./view-related.js";
 import { cardPhotosErrors } from "./view-card-photos.js";
+import { cardFavoriteErrors } from "./view-card-favorite.js";
 import { resolveFieldPath } from "@protobase/layout";
 import { addressErrors, hrefPlaceholders, navRecentErrors, pruneByShape, shapes, tableDisplay } from "@protobase/schema/internal";
 //#region src/view-access.ts
@@ -21,7 +22,7 @@ const keepDefault = ({ default: opens, displays, ...list }) => {
 		...opens !== void 0 && kept && { default: opens }
 	};
 };
-const listShape = (resource, models) => shapes.object({
+const listShape = (resource, models, prompted) => shapes.object({
 	columns: shapes.list(shapes.field),
 	sort: shapes.list(shapes.tuple(shapes.field, shapes.data)),
 	search: shapes.list(shapes.field),
@@ -40,7 +41,8 @@ const listShape = (resource, models) => shapes.object({
 			footer: shapes.list(shapes.field),
 			flags: shapes.list(shapes.field),
 			card: shapes.data,
-			photos: shapes.map((photos) => cardPhotosErrors(photos, resource, models).length === 0 ? photos : void 0)
+			photos: shapes.map((photos) => cardPhotosErrors(photos, resource, models).length === 0 ? photos : void 0),
+			favorite: shapes.map((favorite) => prompted.has(favorite.resource) || cardFavoriteErrors(favorite, resource, models).length === 0 ? favorite : void 0)
 		}),
 		map: shapes.object({
 			kind: shapes.data,
@@ -138,7 +140,7 @@ const actionShape = (model, models) => shapes.object({
 		link: linkShape(model, models)
 	})
 }, { requires: ["run"] });
-const viewShape = (resource, model, models) => shapes.object({
+const viewShape = (resource, model, models, prompted) => shapes.object({
 	resource: shapes.data,
 	roles: shapes.data,
 	title: shapes.field,
@@ -156,7 +158,7 @@ const viewShape = (resource, model, models) => shapes.object({
 	icon: shapes.data,
 	help: shapes.data,
 	fields: shapes.keys(),
-	list: listShape(resource, models),
+	list: listShape(resource, models, prompted),
 	filters: shapes.list(widgetShape),
 	layout: shapes.list(layoutShape(resource, models)),
 	chart: shapes.object({
@@ -165,16 +167,19 @@ const viewShape = (resource, model, models) => shapes.object({
 		granularity: shapes.data
 	}, { requires: ["field"] }),
 	saveFeedback: shapes.data,
-	actions: shapes.list(actionShape(model, models))
+	actions: shapes.list(actionShape(model, models)),
+	listOf: shapes.field,
+	signIn: shapes.data
 });
 /**
 * The view with every reference to a field the caller cannot read removed: list columns, sort, search and displays,
 * field hints, filter widgets, record sections, maps and custom components' props, the chart, title and search result, the
 * actions that set or read one, and the sidebar's `recent` group. Nothing in it may name a hidden field. Related sections
-* and links are checked against `models`, the caller's view of every resource.
+* and links are checked against `models`, the caller's view of every resource, and so are cards' favorite buttons,
+* which stay for a visitor when their resource is one of `prompted`, those that ask the visitor to sign in.
 */
-const pruneView = (view, model, models) => {
-	const pruned = pruneByShape(view, viewShape(view.resource, model, models), (name) => Object.hasOwn(model.fields, name));
+const pruneView = (view, model, models, prompted = /* @__PURE__ */ new Set()) => {
+	const pruned = pruneByShape(view, viewShape(view.resource, model, models, prompted), (name) => Object.hasOwn(model.fields, name));
 	if (!pruned) throw new Error(`The view of ${view.resource} is not an object`);
 	return pruned;
 };

package/dist/view-card-favorite.js

@@ -0,0 +1,23 @@
+import { matchErrors } from "./view-related.js";
+//#region src/view-card-favorite.ts
+/**
+* What is wrong with the favorite button of a cards display on `resource`, against these models; empty when the cards
+* can save to it. Against the full models it checks the config; against a caller's models, whether that caller can
+* list the saved records and write the field that points at the card.
+*/
+const cardFavoriteErrors = (favorite, resource, models) => {
+	const owner = models[resource];
+	const target = models[favorite.resource];
+	if (!owner || !target) return [`unknown resource "${owner ? favorite.resource : resource}"`];
+	if (owner.primaryKey.length !== 1) return [`${resource} has a composite key, so its cards cannot be saved`];
+	const match = matchErrors(target, favorite.field, resource);
+	if (match.length > 0) return match;
+	return target.fields[favorite.field].readOnly ? [`"${favorite.field}" on ${target.name} is read-only, so a press cannot save the card`] : [];
+};
+/** What is wrong with the favorite button's resource itself: it has an owner, so each user lists and saves their own. */
+const favoriteOwnerErrors = (favorite, models) => {
+	const target = models[favorite.resource];
+	return target && target.owner === void 0 ? [`${target.name} has no owner, so its records are not each user's own`] : [];
+};
+//#endregion
+export { cardFavoriteErrors, favoriteOwnerErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.14.1",
-    "@protobase/query": "0.14.1",
-    "@protobase/schema": "0.14.1",
+    "@protobase/layout": "0.14.3",
+    "@protobase/query": "0.14.3",
+    "@protobase/schema": "0.14.3",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
     "@simplewebauthn/server": "^13.3.1",