@rebasepro/server 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/{openapi-generator-O_O24MAT.js → openapi-generator-BqoUh4Ij.js}

@@ -2,9 +2,207 @@ import { createRequire as __rebaseCreateRequire } from "module";
 import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
-import { B as fieldKeyForColumn, E as effectiveAccess, G as resolveCollectionRelations, R as getTenantConfig, U as isRelationRequired, V as findRelation, pt as isToMany } from "./src-pmvW7BFx.js";
-import "./src-vkcwKXbT.js";
+import { n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
+import "./strings.es-BeZWAodn.js";
+import "./src-CatHFUym.js";
+import { r as policy } from "./policy-PdzX-Opd.js";
+import { c as fieldKeyForColumn, f as isRelationRequired, l as findRelation, m as resolveCollectionRelations, n as HARD_DELETE_QUERY_PARAM, o as effectiveAccess, t as DELETED_QUERY_PARAM, u as getTableName } from "./soft-delete-params-47yBGs3_.js";
+//#region ../types/src/types/relations.ts
+/**
+* The key a junction row's own columns are carried under, in both directions.
+*
+* A read that includes a `manyToMany` relation serves each related row with its
+* link's columns nested here — `{ id: 5, name: "ts", _pivot: { role: "owner" } }`
+* — and a membership write may name the same key on an element to state what
+* the link should hold. One constant because the two have to be the same word:
+* a wire name that differs between the read and the write it round-trips
+* through is a shape no client can echo back.
+*
+* Leading underscore, like `_matches`: it reads as metadata about the row
+* rather than as one of its columns. A payload property may not be named
+* `_pivot` either — `checkJunctionPayload` refuses it — so the key means one
+* thing wherever it appears.
+*
+* @group Models
+*/
+var JUNCTION_PIVOT_KEY = "_pivot";
+/**
+* The key a row carries the totals of its counted relations under.
+*
+* An include that asks for a count — `include: { tags: { limit: 4, count: true } }`
+* — serves, beside the (capped) `tags`, how many related rows there are in all:
+* `{ id: 1, tags: [ …4 rows ], _count: { tags: 37 } }`. One object per row,
+* keyed by relation name, so counting a second relation adds a key rather than
+* a second top-level name.
+*
+* Leading underscore, like {@link JUNCTION_PIVOT_KEY} and `_matches`: it
+* describes the read, not the record, and no column or form writes it. A
+* collection with a property of this name cannot ask for a count — the read
+* answers 400 rather than writing over the column.
+*
+* @group Models
+*/
+var INCLUDE_COUNT_KEY = "_count";
+/** @group Models */
+function hasForeignKeyOnTarget(relation) {
+	return relation.kind === "hasOne" || relation.kind === "hasMany";
+}
+/** @group Models */
+function isManyToMany(relation) {
+	return relation.kind === "manyToMany";
+}
+/** @group Models */
+function isToMany(relation) {
+	return relation.cardinality === "many";
+}
+//#endregion
+//#region ../types/src/types/tenancy.ts
+/** Narrow a {@link TenantSource} to its claim form. @group Models */
+function isTenantClaimSource(source) {
+	return typeof source.claim === "string";
+}
+/**
+* The roles tenancy does not apply to, when the collection names none.
+*
+* `admin`, mirroring the security baseline every collection already carries
+* (`<table>_default_admin_read` / `_write`): the Studio, `dataAsAdmin` and a
+* support operator all run with it, and a tenancy rule that locked them out
+* would make the admin panel show an empty table on a collection full of rows.
+*
+* @group Models
+*/
+var DEFAULT_TENANT_BYPASS_ROLES = ["admin"];
+//#endregion
+//#region ../common/src/util/tenant.ts
+/**
+* The one reading of `collection.tenant`.
+*
+* Four things have to agree for a tenant-scoped collection to work — the
+* column, the RLS policy, the value stamped on insert and the index — and
+* before this they were four hand-written declarations that nothing compared.
+* The three that are schema become a {@link SecurityRule} and a column effect
+* derived here and in `planSchema`; the fourth, the write path, is
+* {@link resolveTenantWrite}.
+*
+* Everything in this module is pure. The policy it builds is a `SecurityRule`
+* like any other, which is what makes `db push`, the doctor, boot-ensure, the
+* drift detector and the Studio treat the tenancy policy as what it is —
+* generated, named, and recognisable — rather than as somebody's hand-written
+* SQL that a push should offer to drop.
+*/
+/**
+* The collection's tenancy declaration, or nothing.
+*
+* Read through this rather than off the object, so the one shape check —
+* `tenant` is an object carrying a `field` and a `from` — is in one place. A
+* config that is *wrong* is refused by `validateCollectionConfig` with a
+* message; this is only asking whether there is one.
+*/
+function getTenantConfig(collection) {
+	const tenant = collection?.tenant;
+	if (!tenant || typeof tenant !== "object") return void 0;
+	if (typeof tenant.field !== "string" || !tenant.field) return void 0;
+	if (!tenant.from || typeof tenant.from !== "object") return void 0;
+	return tenant;
+}
+/** The roles tenancy does not apply to, defaulted. */
+function tenantBypassRoles(tenant) {
+	return tenant.bypassRoles ?? DEFAULT_TENANT_BYPASS_ROLES;
+}
+/**
+* The name of the policy a tenant declaration compiles to.
+*
+* Explicit — not a `getPolicyNameHash` of the rule — precisely because the
+* rule's *body* is compiled with more information in some callers than in
+* others (`planSchema` can resolve a relation's target collection and so knows
+* the column's type; the Studio, asking only for names, cannot). A hashed name
+* would then differ between the two, and the same policy would read as drift.
+* A frozen identifier: see `contracts/derived-names.txt`.
+*/
+function tenantPolicyName(tableName) {
+	return `${tableName}_tenant_scope`;
+}
+/**
+* The condition a tenant declaration means, as a policy expression.
+*
+* `serverContext()` first, for the same reason every injected baseline rule
+* carries it: the trusted plane runs migrations, the auth flows and the boot,
+* and a restrictive policy that excluded it would not protect a tenant, it
+* would stop the server from starting.
+*
+* Then the bypass roles, then the tenancy test itself — a claim comparison or a
+* correlated `EXISTS` over the membership table, which are the two ways a
+* deployment answers "which tenant is this caller in".
+*/
+function tenantScopeExpression(tenant) {
+	const match = isTenantClaimSource(tenant.from) ? policy.compare(policy.field(tenant.field), "eq", policy.authClaim(tenant.from.claim)) : policy.existsIn({
+		collection: tenant.from.membership.collection,
+		where: policy.and(policy.compare(policy.field(tenant.from.membership.tenantField), "eq", policy.outerField(tenant.field)), policy.compare(policy.field(tenant.from.membership.userField), "eq", policy.authUid()))
+	});
+	const bypass = tenantBypassRoles(tenant);
+	return bypass.length > 0 ? policy.or(policy.serverContext(), policy.rolesOverlap(bypass), match) : policy.or(policy.serverContext(), match);
+}
+/**
+* The rule a tenant declaration compiles to, or nothing when there is none.
+*
+* **Restrictive**, and that is the whole design. A restrictive policy is ANDed
+* with every other policy on the table, so tenancy narrows what the
+* collection's own `securityRules` allow and can never widen it. A permissive
+* one would OR with them, and a single `access: "public"` rule elsewhere in the
+* file would take the entire tenancy boundary off without contradicting
+* anything a reader could see.
+*
+* One rule with `operation: "all"` rather than four with `operations: [...]`:
+* `FOR ALL` gives Postgres the USING clause for SELECT/UPDATE/DELETE and the
+* WITH CHECK clause for INSERT/UPDATE, which is exactly the coverage wanted,
+* as one policy with one name instead of four.
+*/
+function buildTenantSecurityRule(collection) {
+	const tenant = getTenantConfig(collection);
+	if (!tenant) return void 0;
+	const expression = tenantScopeExpression(tenant);
+	return {
+		name: tenantPolicyName(getTableName(collection)),
+		mode: "restrictive",
+		operation: "all",
+		condition: expression,
+		check: expression
+	};
+}
+/**
+* The property a `softDelete` collection records a deletion in — its wire
+* name, what a delete stamps and what a restore (an update to `null`) clears —
+* or `undefined` for a collection without soft delete.
+*
+* One reading of the declaration for every layer that needs it: the driver
+* that stamps and filters on it, and the REST route that has to recognise a
+* restore before it looks the row up.
+*/
+function softDeleteFieldOf(collection) {
+	const declared = collection && "softDelete" in collection ? collection.softDelete : void 0;
+	if (!declared) return void 0;
+	return typeof declared === "object" && declared.field || "deletedAt";
+}
+/**
+* Whether an update's values restore a soft-deleted row: they set the
+* soft-delete field back to `null`, the documented restore.
+*
+* A restore is an ordinary update of a row every default read hides, so a door
+* that looks the row up before updating it has to include the trashed rows for
+* this update — and only for this one: any other edit of a trashed row is a
+* 404.
+*/
+function restoresSoftDeletedRow(collection, values) {
+	const field = softDeleteFieldOf(collection);
+	return field !== void 0 && values?.[field] === null;
+}
+//#endregion
 //#region src/api/openapi-generator.ts
+var openapi_generator_exports = /* @__PURE__ */ __exportAll({
+	buildCollectionInputSchema: () => buildCollectionInputSchema,
+	buildCollectionSchema: () => buildCollectionSchema,
+	generateOpenApiSpec: () => generateOpenApiSpec
+});
 function generateOpenApiSpec(collections, options = {}) {
 	const basePath = options.basePath ?? "/api";
 	const requireAuth = options.requireAuth ?? true;
@@ -47,7 +245,7 @@ function generateOpenApiSpec(collections, options = {}) {
 				type: "integer",
 				minimum: 1
 			},
-			description: "Page number (alternative to offset). Calculates offset as (page-1)*limit"
+			description: "Page number (alternative to offset). Calculates offset as (page-1)*limit. Cannot be combined with `offset` (400 PAGE_WITH_OFFSET)."
 		},
 		{
 			name: "after",
@@ -108,9 +306,20 @@ function generateOpenApiSpec(collections, options = {}) {
 			name: "distinct",
 			in: "query",
 			schema: { type: "boolean" },
-			description: "`SELECT DISTINCT` over the returned columns. Only meaningful alongside `fields`: the primary key is always in the projection, so without narrowing it every row is already distinct. The response has no `meta.total` — the rows before deduplication are a different set, so their count would not describe the page — and `meta.hasMore` is true when the page came back full. Refused (400) alongside `searchString` or a vector search, which attach a per-row score that makes every row distinct by construction, and (400 DISTINCT_ORDER_BY_NOT_SELECTED) when `orderBy` names a column `fields` does not return.",
+			description: "`SELECT DISTINCT` over the returned columns. Only meaningful alongside `fields`: the primary key is always in the projection, so without narrowing it every row is already distinct. The response has no `meta.total` — the rows before deduplication are a different set, so their count would not describe the page — and `meta.hasMore` comes from reading one row past the page. Refused (400) alongside `searchString` or a vector search, which attach a per-row score that makes every row distinct by construction, and (400 DISTINCT_ORDER_BY_NOT_SELECTED) when `orderBy` names a column `fields` does not return.",
 			example: "true"
 		},
+		{
+			name: "count",
+			in: "query",
+			schema: {
+				type: "string",
+				enum: ["exact", "none"],
+				default: "exact"
+			},
+			description: "Whether to count every matching row for `meta.total`. `exact` (the default) runs a `COUNT(*)` beside the page, which on a large table costs more than the page itself; `none` skips it, and the response then has no `meta.total`. `meta.hasMore` is exact either way — without a count it comes from reading one row past the page — so a walk that pages until `hasMore` is false needs no count. Anything else is a 400 INVALID_COUNT.",
+			example: "none"
+		},
 		{
 			name: "searchString",
 			in: "query",
@@ -149,7 +358,7 @@ function generateOpenApiSpec(collections, options = {}) {
 			name: "vector_threshold",
 			in: "query",
 			schema: { type: "number" },
-			description: "Drop rows farther than this distance. Rows are returned closest-first with a `_distance` field."
+			description: "Drop rows farther than this distance. Rows are returned closest-first with a `_distance` field. The response then has no `meta.total`: counting the rows within a distance computes it for every row of the table. `meta.hasMore` is exact, from reading one row past the page."
 		}
 	];
 	const spec = {
@@ -183,7 +392,7 @@ function generateOpenApiSpec(collections, options = {}) {
 					properties: {
 						total: {
 							type: "integer",
-							description: "Total number of matching records. Absent on a `distinct` read, which has no count of the rows it returns."
+							description: "Total number of matching records. Absent on a `distinct` read, which has no count of the rows it returns, on a vector search with a `vector_threshold`, whose count would compute a distance for every row, and when the request asked for `count=none`."
 						},
 						limit: {
 							type: "integer",
@@ -220,7 +429,50 @@ function generateOpenApiSpec(collections, options = {}) {
 	const paths = spec.paths;
 	const schemas = spec.components.schemas;
 	const tags = spec.tags;
-	const reservedParameterNames = new Set(listQueryParameters().map((p) => p.name));
+	const reservedParameterNames = /* @__PURE__ */ new Set([...listQueryParameters().map((p) => p.name), DELETED_QUERY_PARAM]);
+	/**
+	* `?deleted=` on the reads of a `softDelete` collection. A delete there
+	* moves the row to the trash, and every read hides trashed rows unless it
+	* asks for them; the list, the single row, the count and the aggregate all
+	* honour this. Empty for any other collection.
+	*/
+	const deletedParameters = (collection) => {
+		const field = softDeleteFieldOf(collection);
+		if (!field) return [];
+		return [{
+			name: DELETED_QUERY_PARAM,
+			in: "query",
+			required: false,
+			schema: {
+				type: "string",
+				enum: ["include", "only"]
+			},
+			description: `Rows a delete moved to the trash (\`${field}\` set) are left out unless this asks for them: \`include\` reads them with the live rows, \`only\` reads them alone. Any other value is a 400 INVALID_DELETED_PARAM.`
+		}];
+	};
+	/**
+	* `?hard=` on the deletes of a `softDelete` collection: delete for good
+	* rather than move to the trash. Empty for any other collection.
+	*/
+	const hardDeleteParameters = (collection) => {
+		if (!softDeleteFieldOf(collection)) return [];
+		return [{
+			name: HARD_DELETE_QUERY_PARAM,
+			in: "query",
+			required: false,
+			schema: {
+				type: "boolean",
+				default: false
+			},
+			description: "`true` deletes for good instead of moving to the trash — a row already in the trash included, which is how the trash is emptied. Only `true`/`1` and `false`/`0` are accepted; anything else is a 400 INVALID_HARD_PARAM."
+		}];
+	};
+	/** What a delete does to a `softDelete` collection's row, for the delete operations' descriptions. */
+	const softDeleteBehaviour = (collection) => {
+		const field = softDeleteFieldOf(collection);
+		if (!field) return void 0;
+		return `This collection soft-deletes: a delete moves the row to the trash by stamping \`${field}\`, and every read leaves it out unless it passes \`?deleted=include\` or \`?deleted=only\`. A PATCH setting \`${field}\` back to \`null\` restores it. Pass \`?hard=true\` to delete for good.`;
+	};
 	const registeredSchemas = new Set((collections || []).map(schemaNameFor));
 	/**
 	* `Prefer: return=minimal`, on every route that would otherwise send a row
@@ -387,27 +639,59 @@ function generateOpenApiSpec(collections, options = {}) {
 		schemas[`${schemaName}Input`] = buildCollectionInputSchema(collection);
 		schemas[`${schemaName}Update`] = buildCollectionUpdateSchema(collection);
 		const dataPath = `/data/${slug}`;
-		paths[`${dataPath}/count`] = { get: {
-			tags: [collection.name],
-			summary: `Count ${collection.name}`,
-			description: "The number of rows the same filters would return, without returning them. Takes the filter and search parameters of the list endpoint; `limit`, `offset` and `orderBy` are not part of the question and are ignored.",
-			operationId: `count${schemaName}`,
-			parameters: [...listQueryParameters().filter((p) => p.name === "searchString"), ...buildFilterParameters(collection, reservedParameterNames)],
-			responses: {
-				200: {
-					description: "The number of matching rows",
-					content: { "application/json": { schema: {
-						type: "object",
-						required: ["count"],
-						properties: { count: {
-							type: "integer",
-							description: "Rows matching the filters"
-						} }
-					} } }
-				},
-				...errorResponses(requireAuth)
-			}
-		} };
+		const softDeleteNote = softDeleteBehaviour(collection);
+		const countNarrowing = /* @__PURE__ */ new Set([
+			"where",
+			"or",
+			"and",
+			"not",
+			"searchString",
+			"vector_search",
+			"vector",
+			"vector_distance",
+			"vector_threshold"
+		]);
+		const countParameters = [
+			...listQueryParameters().filter((p) => countNarrowing.has(p.name)).map((p) => p.name === "vector_threshold" ? {
+				...p,
+				description: "Count only the rows within this distance of `vector`."
+			} : p),
+			...deletedParameters(collection),
+			...buildFilterParameters(collection, reservedParameterNames)
+		];
+		const countResponses = {
+			200: {
+				description: "The number of matching rows",
+				content: { "application/json": { schema: {
+					type: "object",
+					required: ["count"],
+					properties: { count: {
+						type: "integer",
+						description: "Rows matching the filters"
+					} }
+				} } }
+			},
+			...errorResponses(requireAuth)
+		};
+		paths[`${dataPath}/count`] = {
+			get: {
+				tags: [collection.name],
+				summary: `Count ${collection.name}`,
+				description: "The number of rows the same filters would return, without returning them. Takes the filter and search parameters of the list endpoint; `limit`, `offset` and `orderBy` are not part of the question and are ignored.",
+				operationId: `count${schemaName}`,
+				parameters: countParameters,
+				responses: countResponses
+			},
+			post: queryOperation({
+				tags: [collection.name],
+				summary: `Count ${collection.name}, parameters in the body`,
+				description: "The count `GET` answers, with its query parameters in a JSON body instead of the URL: the same filters, search and vector search, the same row-level security, and the same errors. It reads and never writes, so a credential needs `data:read` for it. Use it when the URL would not fit: a vector search's embedding, a long `in` list. A parameter also on the URL is a 400 INVALID_QUERY_BODY.",
+				operationId: `count${schemaName}Query`,
+				parameters: countParameters,
+				responses: countResponses,
+				reserved: reservedParameterNames
+			})
+		};
 		paths[`${dataPath}/aggregate`] = { get: {
 			tags: [collection.name],
 			summary: `Aggregate ${collection.name}`,
@@ -439,6 +723,7 @@ function generateOpenApiSpec(collections, options = {}) {
 					schema: { type: "string" },
 					example: "count:desc"
 				},
+				...deletedParameters(collection),
 				...buildFilterParameters(collection, reservedParameterNames)
 			],
 			responses: {
@@ -474,28 +759,42 @@ function generateOpenApiSpec(collections, options = {}) {
 				...errorResponses(requireAuth)
 			}
 		} };
+		const listParameters = [
+			...listQueryParameters(),
+			...deletedParameters(collection),
+			...buildFilterParameters(collection, reservedParameterNames)
+		];
+		const listResponses = {
+			200: {
+				description: "Paginated list of entities",
+				content: { "application/json": { schema: {
+					type: "object",
+					properties: {
+						data: {
+							type: "array",
+							items: { $ref: `#/components/schemas/${schemaName}` }
+						},
+						meta: { $ref: "#/components/schemas/PaginationMeta" }
+					}
+				} } }
+			},
+			...errorResponses(requireAuth)
+		};
+		paths[`${dataPath}/query`] = { post: queryOperation({
+			tags: [collection.name],
+			summary: `List ${collection.name}, parameters in the body`,
+			operationId: `query${schemaName}`,
+			parameters: listParameters,
+			responses: listResponses,
+			reserved: reservedParameterNames
+		}) };
 		paths[dataPath] = {
 			get: {
 				tags: [collection.name],
 				summary: `List ${collection.name}`,
 				operationId: `list${schemaName}`,
-				parameters: [...listQueryParameters(), ...buildFilterParameters(collection, reservedParameterNames)],
-				responses: {
-					200: {
-						description: "Paginated list of entities",
-						content: { "application/json": { schema: {
-							type: "object",
-							properties: {
-								data: {
-									type: "array",
-									items: { $ref: `#/components/schemas/${schemaName}` }
-								},
-								meta: { $ref: "#/components/schemas/PaginationMeta" }
-							}
-						} } }
-					},
-					...errorResponses(requireAuth)
-				}
+				parameters: listParameters,
+				responses: listResponses
 			},
 			post: {
 				tags: [collection.name],
@@ -506,8 +805,8 @@ function generateOpenApiSpec(collections, options = {}) {
 					in: "query",
 					required: false,
 					schema: { type: "string" },
-					description: "Comma-separated columns to upsert on, turning the create into INSERT ... ON CONFLICT DO UPDATE. They must carry a declared uniqueness guarantee — `validation.unique`, a `unique` index, or the primary key — or the request is refused with a 400 naming the targets that do exist. Left off, this is a plain insert and a duplicate key still raises.",
-					example: "email"
+					description: "Comma-separated columns to upsert on, turning the create into INSERT ... ON CONFLICT DO UPDATE. They must carry a declared uniqueness guarantee — `validation.unique`, a `unique` index, or the primary key — or the request is refused with a 400 naming the targets that do exist. Left off, this is a plain insert and a duplicate key still raises. Refused (400 `INVALID_CONFLICT_TARGET`) on the auth collection, whose rows are the users: create them with a plain POST and change them with PATCH.",
+					example: "sku"
 				}, preferHeader],
 				requestBody: {
 					required: true,
@@ -564,7 +863,7 @@ function generateOpenApiSpec(collections, options = {}) {
 							},
 							upsert: {
 								type: "boolean",
-								description: "Write each row as INSERT ... ON CONFLICT DO UPDATE."
+								description: "Write each row as INSERT ... ON CONFLICT DO UPDATE. Refused (400 `INVALID_CONFLICT_TARGET`) on the auth collection, whose rows are the users."
 							},
 							onConflict: {
 								type: "array",
@@ -649,9 +948,9 @@ function generateOpenApiSpec(collections, options = {}) {
 		paths[`/data/${slug}/bulk/delete`] = { post: {
 			tags: [collection.name],
 			summary: `Delete many ${collection.name} in one transaction`,
-			description: "A POST, not `DELETE /bulk` with a body. Bodies on DELETE are permitted but widely dropped by proxies and CDNs, and several generators ignore `requestBody` on a DELETE operation — a generated client would send the request with no ids at all. Takes ids rather than a filter: a mistyped condition that empties a table cannot be reviewed at the call site the way an explicit list can. `beforeDelete`/`afterDelete` fire per row.",
+			description: "A POST, not `DELETE /bulk` with a body. Bodies on DELETE are permitted but widely dropped by proxies and CDNs, and several generators ignore `requestBody` on a DELETE operation — a generated client would send the request with no ids at all. Takes ids rather than a filter: a mistyped condition that empties a table cannot be reviewed at the call site the way an explicit list can. `beforeDelete`/`afterDelete` fire per row." + (softDeleteNote ? `\n\n${softDeleteNote}` : ""),
 			operationId: `deleteMany${schemaName}`,
-			parameters: [idempotencyHeader],
+			parameters: [idempotencyHeader, ...hardDeleteParameters(collection)],
 			requestBody: {
 				required: true,
 				content: { "application/json": { schema: {
@@ -665,7 +964,7 @@ function generateOpenApiSpec(collections, options = {}) {
 			},
 			responses: {
 				200: {
-					description: "How many rows were deleted",
+					description: softDeleteNote ? "How many rows were moved to the trash, or deleted for good with `?hard=true`" : "How many rows were deleted",
 					content: { "application/json": { schema: {
 						type: "object",
 						properties: { meta: {
@@ -708,7 +1007,8 @@ function generateOpenApiSpec(collections, options = {}) {
 						schema: { type: "string" },
 						description: "Comma-separated columns to return, as a SELECT projection. The primary key always survives and `excludeFromApi` columns stay hidden.",
 						example: "id,title"
-					}
+					},
+					...deletedParameters(collection)
 				],
 				responses: {
 					200: {
@@ -735,6 +1035,7 @@ function generateOpenApiSpec(collections, options = {}) {
 			delete: {
 				tags: [collection.name],
 				summary: `Delete ${collection.singularName || collection.name}`,
+				...softDeleteNote ? { description: softDeleteNote } : {},
 				operationId: `delete${schemaName}`,
 				parameters: [
 					{
@@ -751,10 +1052,11 @@ function generateOpenApiSpec(collections, options = {}) {
 						required: false,
 						schema: { type: "string" },
 						description: "Names this delete so a retry replays its answer. A delete replayed after the first attempt committed would otherwise answer 404 — which an offline queue reads as a permanent failure for a delete that in fact succeeded."
-					}
+					},
+					...hardDeleteParameters(collection)
 				],
 				responses: {
-					204: { description: "Deleted successfully" },
+					204: { description: softDeleteNote ? "Moved to the trash: the row still exists and can be restored. With `?hard=true`, deleted for good" : "Deleted successfully" },
 					404: {
 						description: "Entity not found",
 						content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } }
@@ -781,34 +1083,44 @@ function generateOpenApiSpec(collections, options = {}) {
 			const relationName = relation.relationName;
 			const targetSchema = schemaNameFor(relation.target());
 			const subPath = `/data/${slug}/{parentId}/${relationName}`;
+			const nestedParameters = [{
+				name: "parentId",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: `${collection.singularName || collection.name} ID`
+			}, ...listQueryParameters()];
+			const nestedResponses = {
+				200: {
+					description: `List of related ${relationName}`,
+					content: { "application/json": { schema: {
+						type: "object",
+						properties: {
+							data: {
+								type: "array",
+								items: schemas[targetSchema] ? { $ref: `#/components/schemas/${targetSchema}` } : { type: "object" }
+							},
+							meta: { $ref: "#/components/schemas/PaginationMeta" }
+						}
+					} } }
+				},
+				...errorResponses(requireAuth)
+			};
 			paths[subPath] = { get: {
 				tags: [collection.name],
 				summary: `List ${relationName} for ${withIndefiniteArticle(collection.singularName || collection.name)}`,
 				operationId: `list${schemaName}${toPascalCase(relationName)}`,
-				parameters: [{
-					name: "parentId",
-					in: "path",
-					required: true,
-					schema: { type: "string" },
-					description: `${collection.singularName || collection.name} ID`
-				}, ...listQueryParameters()],
-				responses: {
-					200: {
-						description: `List of related ${relationName}`,
-						content: { "application/json": { schema: {
-							type: "object",
-							properties: {
-								data: {
-									type: "array",
-									items: schemas[targetSchema] ? { $ref: `#/components/schemas/${targetSchema}` } : { type: "object" }
-								},
-								meta: { $ref: "#/components/schemas/PaginationMeta" }
-							}
-						} } }
-					},
-					...errorResponses(requireAuth)
-				}
+				parameters: nestedParameters,
+				responses: nestedResponses
 			} };
+			paths[`${subPath}/query`] = { post: queryOperation({
+				tags: [collection.name],
+				summary: `List ${relationName} for ${withIndefiniteArticle(collection.singularName || collection.name)}, parameters in the body`,
+				operationId: `query${schemaName}${toPascalCase(relationName)}`,
+				parameters: nestedParameters,
+				responses: nestedResponses,
+				reserved: reservedParameterNames
+			}) };
 		}
 	}
 	return spec;
@@ -1104,6 +1416,10 @@ function updateOperation(collection, schemaName, requireAuth, shared) {
 		responses: {
 			200: {
 				description: "Updated entity",
+				headers: { ETag: {
+					schema: { type: "string" },
+					description: "The version this write produced — the tag a `GET` of the row now answers. Send it as `If-Match` on the next write to chain conditional edits without reading the row back. Absent on an answer replayed from an `Idempotency-Key`."
+				} },
 				content: { "application/json": { schema: { $ref: `#/components/schemas/${schemaName}` } } }
 			},
 			404: {
@@ -1157,7 +1473,7 @@ function buildCollectionInputSchema(collection) {
 		if ("isId" in property && property.isId && property.isId !== "manual" && property.isId !== true) continue;
 		properties[key] = convertPropertyToSchema(property);
 		emitted.add(key);
-		if (property.validation?.required) required.push(key);
+		if (property.validation?.required && !property.databaseDefault) required.push(key);
 	}
 	if (!emitted.has(idKey)) {
 		properties[idKey] = {
@@ -1390,6 +1706,65 @@ function buildFilterParameters(collection, reservedNames = /* @__PURE__ */ new S
 	return params;
 }
 /**
+* A `POST …/query` operation: the listing whose `parameters` are given, with
+* its query parameters moved into a JSON body.
+*
+* Built from the `GET`'s own parameter list, so the body documents exactly
+* what the route accepts — it turns the body back into those parameters and
+* runs the `GET`'s parser (`query-body.ts`). A filter parameter takes a list
+* where the URL would repeat it, and the four parameters whose URL value is
+* JSON take the JSON value itself.
+*/
+function queryOperation(operation) {
+	const jsonValued = {
+		where: { oneOf: [{
+			type: "object",
+			additionalProperties: true
+		}, { type: "string" }] },
+		include: { oneOf: [{
+			type: "object",
+			additionalProperties: true
+		}, { type: "string" }] },
+		orderBy: { oneOf: [{
+			type: "array",
+			items: {}
+		}, { type: "string" }] },
+		vector: { oneOf: [{
+			type: "array",
+			items: { type: "number" }
+		}, { type: "string" }] }
+	};
+	const properties = {};
+	for (const parameter of operation.parameters) {
+		if (parameter.in !== "query") continue;
+		const name = String(parameter.name);
+		const schema = parameter.schema;
+		const isFilter = !operation.reserved.has(name);
+		properties[name] = {
+			...jsonValued[name] ?? (isFilter ? { oneOf: [schema, {
+				type: "array",
+				items: schema
+			}] } : schema),
+			...parameter.description ? { description: parameter.description } : {}
+		};
+	}
+	return {
+		tags: operation.tags,
+		summary: operation.summary,
+		description: operation.description ?? "The listing `GET` answers, with its query parameters in a JSON body instead of the URL: the same filters, page, count, cursor and includes, the same row-level security, and the same errors. It reads and never writes, so a credential needs `data:read` for it. Use it when the URL would not fit: a vector search's embedding is a JSON array in `vector`, and 768 dimensions of it is 17 KB of URL, past what Node and most proxies accept. A parameter also on the URL is a 400 INVALID_QUERY_BODY.",
+		operationId: operation.operationId,
+		parameters: operation.parameters.filter((parameter) => parameter.in !== "query"),
+		requestBody: {
+			required: true,
+			content: { "application/json": { schema: {
+				type: "object",
+				properties
+			} } }
+		},
+		responses: operation.responses
+	};
+}
+/**
 * Standard error responses included on every endpoint.
 */
 function errorResponses(requireAuth) {
@@ -1446,6 +1821,6 @@ function toPascalCase(str) {
 	return str.replace(/[^a-zA-Z0-9]+/g, " ").split(" ").filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
 }
 //#endregion
-export { generateOpenApiSpec };
+export { softDeleteFieldOf as a, JUNCTION_PIVOT_KEY as c, restoresSoftDeletedRow as i, hasForeignKeyOnTarget as l, buildCollectionSchema as n, buildTenantSecurityRule as o, openapi_generator_exports as r, INCLUDE_COUNT_KEY as s, buildCollectionInputSchema as t, isManyToMany as u };
 
-//# sourceMappingURL=openapi-generator-O_O24MAT.js.map
+//# sourceMappingURL=openapi-generator-BqoUh4Ij.js.map