emdash 0.37.0 → 0.39.0

package/src/api/handlers/taxonomies.ts

@@ -29,6 +29,15 @@ function isTermSlugUniqueViolation(error: unknown): boolean {
 	);
 }
 
+function isTermTranslationLocaleUniqueViolation(error: unknown): boolean {
+	const message = error instanceof Error ? error.message.toLowerCase() : "";
+	return (
+		(message.includes("unique constraint failed") || message.includes("duplicate key")) &&
+		(message.includes("translation_group") ||
+			message.includes("idx_taxonomies_translation_group_locale_unique"))
+	);
+}
+
 // ---------------------------------------------------------------------------
 // Response types
 // ---------------------------------------------------------------------------
@@ -191,6 +200,18 @@ async function requireTaxonomyDefWithFallback(
 	return def ? { success: true, def } : taxonomyDefNotFound(name, locale);
 }
 
+function validateHierarchicalParent(
+	def: Selectable<TaxonomyDefTable>,
+	taxonomyName: string,
+	parentId: string | null | undefined,
+): { code: "VALIDATION_ERROR"; message: string } | null {
+	if (parentId === undefined || parentId === null || def.hierarchical === 1) return null;
+	return {
+		code: "VALIDATION_ERROR",
+		message: `Taxonomy '${taxonomyName}' is not hierarchical and cannot have parent terms`,
+	};
+}
+
 /** The subset of `slugs` that still has a row in `_emdash_collections`. */
 async function findExistingCollections(
 	db: Kysely<Database>,
@@ -369,6 +390,15 @@ export async function handleTaxonomyCreate(
 					error: { code: "NOT_FOUND", message: "Source taxonomy for translation not found" },
 				};
 			}
+			if (source.name !== input.name) {
+				return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: `A translation of taxonomy '${source.name}' must use the same name`,
+					},
+				};
+			}
 			translationGroup = source.translation_group ?? source.id;
 			if (input.hierarchical === undefined) {
 				hierarchical = source.hierarchical === 1;
@@ -881,12 +911,11 @@ export async function handleTermCreate(
 	},
 ): Promise<ApiResult<TermResponse>> {
 	let attemptedSlug = input.slug;
+	let effectiveLocale = input.locale ?? getI18nConfig()?.defaultLocale ?? "en";
 	try {
 		const locale = resolveConfiguredLocale(input.locale ?? getI18nConfig()?.defaultLocale ?? "en");
-		// Taxonomy definitions are per-locale, but terms can exist in any locale
-		// regardless of whether the def has been translated there. Look up the
-		// def across all locales — we only care that it *exists*.
-		const lookup = await requireTaxonomyDef(db, taxonomyName);
+		effectiveLocale = locale;
+		const lookup = await requireTaxonomyDefWithFallback(db, taxonomyName, locale);
 		if (!lookup.success) return lookup;
 
 		const repo = new TaxonomyRepository(db);
@@ -894,6 +923,8 @@ export async function handleTermCreate(
 		// Coerce empty-string parentId to undefined (treat as "no parent").
 		const parentId =
 			input.parentId === "" || input.parentId === undefined ? undefined : input.parentId;
+		const hierarchyError = validateHierarchicalParent(lookup.def, taxonomyName, parentId);
+		if (hierarchyError) return { success: false, error: hierarchyError };
 
 		// Conflict check is scoped to locale (per-locale slugs are unique).
 		const existing =
@@ -919,7 +950,35 @@ export async function handleTermCreate(
 		let selfGroup: string | null = null;
 		if (input.translationOf) {
 			const source = await repo.findById(input.translationOf);
-			selfGroup = source ? (source.translationGroup ?? source.id) : null;
+			if (!source) {
+				return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: `Translation source '${input.translationOf}' not found`,
+					},
+				};
+			}
+			if (source.name !== taxonomyName) {
+				return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: `Translation source '${input.translationOf}' belongs to taxonomy '${source.name}', not '${taxonomyName}'`,
+					},
+				};
+			}
+			selfGroup = source.translationGroup ?? source.id;
+			const translations = await repo.findTranslations(selfGroup);
+			if (translations.some((translation) => translation.locale === locale)) {
+				return {
+					success: false,
+					error: {
+						code: "CONFLICT",
+						message: `Term translation already exists for locale '${locale}'`,
+					},
+				};
+			}
 		}
 
 		// Validate parentId: must exist AND belong to the same taxonomy.
@@ -982,6 +1041,15 @@ export async function handleTermCreate(
 			},
 		};
 	} catch (error) {
+		if (isTermTranslationLocaleUniqueViolation(error)) {
+			return {
+				success: false,
+				error: {
+					code: "CONFLICT",
+					message: `Term translation already exists for locale '${effectiveLocale}'`,
+				},
+			};
+		}
 		if (isTermSlugUniqueViolation(error)) {
 			return {
 				success: false,
@@ -1138,6 +1206,12 @@ export async function handleTermUpdate(
 		const newSlug = input.slug === "" || input.slug === undefined ? undefined : input.slug;
 		const newParentId =
 			input.parentId === "" || input.parentId === undefined ? undefined : input.parentId;
+		if (newParentId !== undefined && newParentId !== null) {
+			const lookup = await requireTaxonomyDefWithFallback(db, taxonomyName, term.locale);
+			if (!lookup.success) return lookup;
+			const hierarchyError = validateHierarchicalParent(lookup.def, taxonomyName, newParentId);
+			if (hierarchyError) return { success: false, error: hierarchyError };
+		}
 
 		// Check if new slug conflicts (per-locale uniqueness).
 		if (newSlug !== undefined && newSlug !== termSlug) {

package/src/api/handlers/validation.ts

@@ -8,12 +8,14 @@
  *  - select / multiSelect values must match the configured options
  *  - reference fields must resolve to a real, non-trashed target
  *
- * Errors surface as `{ code: "VALIDATION_ERROR", message }` with all
- * offending fields listed in one message so callers can fix everything in
- * a single round trip.
+ * Errors surface as `{ code: "VALIDATION_ERROR", message, details: { issues } }`.
+ * The message lists every offending field so callers can fix everything in a
+ * single round trip; `issues` carries the same failures one by one, with a
+ * code and any bound that failed, so the admin can word them for editors.
  */
 
 import { sql, type Kysely } from "kysely";
+import type { z } from "zod";
 
 import type { Database } from "../../database/types.js";
 import { validateIdentifier } from "../../database/validate.js";
@@ -23,9 +25,32 @@ import { generateZodSchema } from "../../schema/zod-generator.js";
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { isMissingTableError } from "../../utils/db-errors.js";
 
+/**
+ * One rejected value. `code` is `required`, `unknown_field`,
+ * `reference_not_found` or `invalid_reference_target`, or else the Zod issue
+ * code. Length, range and item-count failures carry `origin` and the bound,
+ * format failures carry `format`.
+ */
+export interface ContentValidationIssue {
+	path: string;
+	code: string;
+	message: string;
+	origin?: string;
+	minimum?: number;
+	maximum?: number;
+	format?: string;
+}
+
 type ValidationResult =
 	| { ok: true }
-	| { ok: false; error: { code: "VALIDATION_ERROR" | "COLLECTION_NOT_FOUND"; message: string } };
+	| {
+			ok: false;
+			error: {
+				code: "VALIDATION_ERROR" | "COLLECTION_NOT_FOUND" | "UNSUPPORTED_FIELD_TYPE";
+				message: string;
+				details?: { issues: ContentValidationIssue[] };
+			};
+	  };
 
 /** Treat `undefined`, `null`, and `""` as "not set". */
 function isMissing(value: unknown): boolean {
@@ -60,6 +85,59 @@ function formatIssuePath(path: ReadonlyArray<PropertyKey>): string {
 	return path.map((seg) => String(seg)).join(".");
 }
 
+function isSubFieldPath(
+	path: ReadonlyArray<PropertyKey>,
+	fieldTypes: ReadonlyMap<string, string>,
+): boolean {
+	return path.length === 3 && fieldTypes.get(String(path[0])) === "repeater";
+}
+
+function isFieldOrSubFieldPath(
+	path: ReadonlyArray<PropertyKey>,
+	fieldTypes: ReadonlyMap<string, string>,
+): boolean {
+	return path.length === 1 || isSubFieldPath(path, fieldTypes);
+}
+
+function fromZodIssue(
+	issue: z.core.$ZodIssue,
+	fieldTypes: ReadonlyMap<string, string>,
+): ContentValidationIssue {
+	const result: ContentValidationIssue = {
+		path: formatIssuePath(issue.path),
+		code: issue.code,
+		message: issue.message,
+	};
+	switch (issue.code) {
+		case "invalid_type":
+		case "invalid_union":
+		case "invalid_value":
+			// Zod reports a missing or null value as a type, union or option
+			// mismatch. A key missing inside a value, such as a Portable Text
+			// block's `_type`, leaves the value malformed rather than the field empty.
+			if (issue.input == null && isFieldOrSubFieldPath(issue.path, fieldTypes)) {
+				result.code = "required";
+			}
+			break;
+		case "too_small":
+			result.origin = issue.origin;
+			if (typeof issue.minimum === "number") result.minimum = issue.minimum;
+			// A required repeater sub-field rejects "" as a one-character minimum.
+			if (issue.input === "" && isSubFieldPath(issue.path, fieldTypes)) {
+				result.code = "required";
+			}
+			break;
+		case "too_big":
+			result.origin = issue.origin;
+			if (typeof issue.maximum === "number") result.maximum = issue.maximum;
+			break;
+		case "invalid_format":
+			result.format = issue.format;
+			break;
+	}
+	return result;
+}
+
 /**
  * Validate `data` against the collection's field definitions.
  *
@@ -86,7 +164,18 @@ export async function validateContentData(
 		};
 	}
 
-	const issues: string[] = [];
+	const issues: ContentValidationIssue[] = [];
+	const unsupportedField = collectionWithFields.fields.find((field) => field.unsupportedType);
+	if (unsupportedField?.unsupportedType) {
+		const { type, path } = unsupportedField.unsupportedType;
+		return {
+			ok: false,
+			error: {
+				code: "UNSUPPORTED_FIELD_TYPE",
+				message: `Collection '${collection}' field '${unsupportedField.slug}' uses unsupported field type '${type}' at '${path}'`,
+			},
+		};
+	}
 
 	// Detect unknown keys explicitly so callers get a useful error rather
 	// than silently dropped data. Leading-underscore keys (e.g. `_slug`,
@@ -96,7 +185,11 @@ export async function validateContentData(
 	for (const key of Object.keys(data)) {
 		if (key.startsWith("_")) continue;
 		if (!knownFields.has(key)) {
-			issues.push(`${key}: unknown field on collection '${collection}'`);
+			issues.push({
+				path: key,
+				code: "unknown_field",
+				message: `unknown field on collection '${collection}'`,
+			});
 		}
 	}
 
@@ -105,10 +198,11 @@ export async function validateContentData(
 	// done as a separate pass below since Zod's `z.string()` accepts "".
 	const baseSchema = generateZodSchema(collectionWithFields);
 	const schema = options.partial ? baseSchema.partial() : baseSchema;
-	const parsed = schema.safeParse(data);
+	const parsed = schema.safeParse(data, { reportInput: true });
 	if (!parsed.success) {
+		const fieldTypes = new Map(collectionWithFields.fields.map((f) => [f.slug, f.type]));
 		for (const issue of parsed.error.issues) {
-			issues.push(`${formatIssuePath(issue.path)}: ${issue.message}`);
+			issues.push(fromZodIssue(issue, fieldTypes));
 		}
 	}
 
@@ -121,7 +215,11 @@ export async function validateContentData(
 		const present = Object.hasOwn(data, field.slug);
 		if (options.partial && !present) continue;
 		if (data[field.slug] === "") {
-			issues.push(`${field.slug}: required (empty value not allowed)`);
+			issues.push({
+				path: field.slug,
+				code: "required",
+				message: "required (empty value not allowed)",
+			});
 		}
 	}
 
@@ -152,7 +250,11 @@ export async function validateContentData(
 			validateIdentifier(target, "reference target collection");
 		} catch {
 			for (const ref of refs) {
-				issues.push(`${ref.field}: invalid reference target collection '${target}'`);
+				issues.push({
+					path: ref.field,
+					code: "invalid_reference_target",
+					message: `invalid reference target collection '${target}'`,
+				});
 			}
 			continue;
 		}
@@ -188,15 +290,13 @@ export async function validateContentData(
 				throw error;
 			}
 		}
-		if (targetTableMissing) {
-			for (const ref of refs) {
-				issues.push(`${ref.field}: target '${ref.id}' not found in collection '${target}'`);
-			}
-			continue;
-		}
 		for (const ref of refs) {
-			if (!found.has(ref.id)) {
-				issues.push(`${ref.field}: target '${ref.id}' not found in collection '${target}'`);
+			if (targetTableMissing || !found.has(ref.id)) {
+				issues.push({
+					path: ref.field,
+					code: "reference_not_found",
+					message: `target '${ref.id}' not found in collection '${target}'`,
+				});
 			}
 		}
 	}
@@ -206,7 +306,8 @@ export async function validateContentData(
 		ok: false,
 		error: {
 			code: "VALIDATION_ERROR",
-			message: issues.join("; "),
+			message: issues.map((issue) => `${issue.path}: ${issue.message}`).join("; "),
+			details: { issues },
 		},
 	};
 }

package/src/api/openapi/document.ts

@@ -29,6 +29,9 @@ import {
 	contentItemSchema,
 	contentListQuery,
 	contentListResponseSchema,
+	contentPublishBody,
+	contentRestoreResponseSchema,
+	contentRevisionConditionBody,
 	contentResponseSchema,
 	contentScheduleBody,
 	contentTermsBody,
@@ -38,6 +41,12 @@ import {
 	contentUpdateBody,
 	trashedContentListResponseSchema,
 } from "../schemas/content.js";
+import {
+	entryLockAcquireBody,
+	entryMutationConflictSchema,
+	entryLockReleaseResponseSchema,
+	entryLockStatusSchema,
+} from "../schemas/entry-lock.js";
 import {
 	mediaUsageDetailsQuery,
 	mediaUsageDetailsResponseSchema,
@@ -210,6 +219,21 @@ function standardErrors(
 /** Common auth error responses (401 + 403) */
 const authErrors = standardErrors(401, 403);
 
+const entryPathParams = z.object({
+	collection: z.string().meta({ description: "Collection slug" }),
+	id: z.string().meta({ description: "Content ID or slug" }),
+});
+
+/** 409 for optimistic-concurrency or edit-lock conflicts. */
+const entryMutationConflict = {
+	"409": {
+		description: "The content changed or another editor holds its edit lock",
+		content: {
+			[JSON_CONTENT]: { schema: entryMutationConflictSchema },
+		},
+	},
+};
+
 // ---------------------------------------------------------------------------
 // Content routes
 // ---------------------------------------------------------------------------
@@ -330,9 +354,12 @@ const contentPaths = {
 				"Moves the content item to trash. Use the permanent delete endpoint to remove permanently.",
 			tags: ["Content"],
 			requestParams: {
-				path: z.object({
-					collection: z.string().meta({ description: "Collection slug" }),
-					id: z.string().meta({ description: "Content ID or slug" }),
+				path: entryPathParams,
+				query: z.object({
+					overrideLock: z.enum(["true", "false"]).optional().meta({
+						description:
+							"Delete even though another editor holds this entry's edit lock. Without it the delete is refused with 409 ENTRY_LOCKED.",
+					}),
 				}),
 			},
 			responses: {
@@ -346,6 +373,7 @@ const contentPaths = {
 				},
 				...authErrors,
 				...standardErrors(404, 500),
+				...entryMutationConflict,
 			},
 		},
 	},
@@ -354,6 +382,8 @@ const contentPaths = {
 		post: {
 			operationId: "publishContent",
 			summary: "Publish a content item",
+			description:
+				"Promotes the current draft to live content and clears any pending schedule. An optional revision token rejects stale publication attempts.",
 			tags: ["Content"],
 			requestParams: {
 				path: z.object({
@@ -361,6 +391,9 @@ const contentPaths = {
 					id: z.string().meta({ description: "Content ID or slug" }),
 				}),
 			},
+			requestBody: {
+				content: { [JSON_CONTENT]: { schema: contentPublishBody } },
+			},
 			responses: {
 				"200": {
 					description: "Published content item",
@@ -371,7 +404,8 @@ const contentPaths = {
 					},
 				},
 				...authErrors,
-				...standardErrors(404, 500),
+				...standardErrors(400, 404, 500),
+				...entryMutationConflict,
 			},
 		},
 	},
@@ -388,6 +422,9 @@ const contentPaths = {
 					id: z.string().meta({ description: "Content ID or slug" }),
 				}),
 			},
+			requestBody: {
+				content: { [JSON_CONTENT]: { schema: contentRevisionConditionBody } },
+			},
 			responses: {
 				"200": {
 					description: "Unpublished content item",
@@ -398,7 +435,8 @@ const contentPaths = {
 					},
 				},
 				...authErrors,
-				...standardErrors(404, 500),
+				...standardErrors(400, 404, 500),
+				...entryMutationConflict,
 			},
 		},
 	},
@@ -428,17 +466,22 @@ const contentPaths = {
 				},
 				...authErrors,
 				...standardErrors(400, 404, 500),
+				...entryMutationConflict,
 			},
 		},
 		delete: {
 			operationId: "unscheduleContent",
 			summary: "Cancel scheduled publishing",
-			description: "Reverts a scheduled item to draft status.",
+			description:
+				"Clears the scheduled publication time. A scheduled draft returns to draft status; a published item stays published.",
 			tags: ["Content"],
 			requestParams: {
-				path: z.object({
-					collection: z.string().meta({ description: "Collection slug" }),
-					id: z.string().meta({ description: "Content ID or slug" }),
+				path: entryPathParams,
+				query: z.object({
+					overrideLock: z.enum(["true", "false"]).optional().meta({
+						description:
+							"Unschedule even though another editor holds this entry's edit lock. Without it the request is refused with 409 ENTRY_LOCKED.",
+					}),
 				}),
 			},
 			responses: {
@@ -452,6 +495,7 @@ const contentPaths = {
 				},
 				...authErrors,
 				...standardErrors(404, 500),
+				...entryMutationConflict,
 			},
 		},
 	},
@@ -498,12 +542,12 @@ const contentPaths = {
 					description: "Restored",
 					content: {
 						[JSON_CONTENT]: {
-							schema: successEnvelope(z.object({ restored: z.literal(true) })),
+							schema: successEnvelope(contentRestoreResponseSchema),
 						},
 					},
 				},
 				...authErrors,
-				...standardErrors(404, 500),
+				...standardErrors(404, 409, 500),
 			},
 		},
 	},
@@ -573,6 +617,9 @@ const contentPaths = {
 					id: z.string().meta({ description: "Content ID or slug" }),
 				}),
 			},
+			requestBody: {
+				content: { [JSON_CONTENT]: { schema: contentRevisionConditionBody } },
+			},
 			responses: {
 				"200": {
 					description: "Content item reverted to live version",
@@ -583,6 +630,81 @@ const contentPaths = {
 					},
 				},
 				...authErrors,
+				...standardErrors(400, 404, 500),
+				...entryMutationConflict,
+			},
+		},
+	},
+
+	"/_emdash/api/content/{collection}/{id}/lock": {
+		get: {
+			operationId: "getEntryLock",
+			summary: "Read the entry's edit lock",
+			description: "Reports who is holding the entry, if anyone, without changing the lease.",
+			tags: ["Content"],
+			requestParams: {
+				path: entryPathParams,
+			},
+			responses: {
+				"200": {
+					description: "Current lock state",
+					content: {
+						[JSON_CONTENT]: { schema: successEnvelope(entryLockStatusSchema) },
+					},
+				},
+				...authErrors,
+				...standardErrors(404, 500),
+			},
+		},
+		post: {
+			operationId: "acquireEntryLock",
+			summary: "Take or refresh the entry's edit lock",
+			description:
+				"Takes the lock for the caller, or reports who holds it. `heldByCaller` " +
+				"tells the two apart. The lease lasts seven minutes; repeating this call " +
+				"and every save on the entry extend it. `takeover` claims the lock from " +
+				"whoever holds it; their next heartbeat or save reports the new holder.",
+			tags: ["Content"],
+			requestParams: {
+				path: entryPathParams,
+			},
+			requestBody: {
+				content: { [JSON_CONTENT]: { schema: entryLockAcquireBody } },
+			},
+			responses: {
+				"200": {
+					description: "Lock state after the attempt",
+					content: {
+						[JSON_CONTENT]: { schema: successEnvelope(entryLockStatusSchema) },
+					},
+				},
+				...authErrors,
+				...standardErrors(404, 500),
+			},
+		},
+		delete: {
+			operationId: "releaseEntryLock",
+			summary: "Release the caller's edit lock",
+			description:
+				"Releases the lock only when the caller holds it; `released` is false otherwise.",
+			tags: ["Content"],
+			requestParams: {
+				path: entryPathParams,
+				query: z.object({
+					token: z.string().optional().meta({
+						description:
+							"The session token sent on acquire. With it, only the tab that last claimed the lock releases it.",
+					}),
+				}),
+			},
+			responses: {
+				"200": {
+					description: "Whether a lock was released",
+					content: {
+						[JSON_CONTENT]: { schema: successEnvelope(entryLockReleaseResponseSchema) },
+					},
+				},
+				...authErrors,
 				...standardErrors(404, 500),
 			},
 		},

package/src/api/schemas/content.ts

@@ -176,6 +176,11 @@ export const contentListQuery = cursorPaginationQuery
 /** ISO 8601 datetime for `publishedAt` / `createdAt`. Routes gate writes behind `content:publish_any`. */
 const contentDateOverride = contentDateTime.nullish();
 
+const overrideLockFlag = z.boolean().optional().meta({
+	description:
+		"Write even though another editor holds this entry's edit lock. Without it the write is refused with 409 ENTRY_LOCKED.",
+});
+
 export const contentCreateBody = z
 	.object({
 		data: z.record(z.string(), z.unknown()),
@@ -206,6 +211,7 @@ export const contentUpdateBody = z
 			.optional()
 			.meta({ description: "Opaque revision token for optimistic concurrency" }),
 		skipRevision: z.boolean().optional(),
+		overrideLock: overrideLockFlag,
 		seo: contentSeoInput.optional(),
 		taxonomies: z.record(z.string(), z.array(z.string())).optional().meta({
 			description:
@@ -217,22 +223,27 @@ export const contentUpdateBody = z
 
 export const contentScheduleBody = z
 	.object({
-		scheduledAt: z
+		scheduledAt: contentDateTime.meta({
+			description: "ISO 8601 datetime with Z or an explicit offset for scheduled publishing",
+			examples: ["2025-06-15T09:00:00Z"],
+		}),
+		overrideLock: overrideLockFlag,
+		_rev: z
 			.string()
-			.min(1, "scheduledAt is required")
-			.meta({
-				description: "ISO 8601 datetime for scheduled publishing",
-				examples: ["2025-06-15T09:00:00Z"],
-			}),
+			.optional()
+			.meta({ description: "Opaque revision token for optimistic concurrency" }),
 	})
 	.meta({ id: "ContentScheduleBody" });
 
-export const contentRevisionConditionBody = z.object({
-	_rev: z
-		.string()
-		.optional()
-		.meta({ description: "Opaque revision token for optimistic concurrency" }),
-});
+export const contentRevisionConditionBody = z
+	.object({
+		_rev: z
+			.string()
+			.optional()
+			.meta({ description: "Opaque revision token for optimistic concurrency" }),
+		overrideLock: overrideLockFlag,
+	})
+	.meta({ id: "ContentRevisionConditionBody" });
 
 export const contentPublishBody = contentRevisionConditionBody
 	.extend({
@@ -358,6 +369,15 @@ export const contentResponseSchema = z
 	})
 	.meta({ id: "ContentResponse" });
 
+/** Response for restoring an item from trash */
+export const contentRestoreResponseSchema = z
+	.object({
+		restored: z.literal(true),
+		item: contentItemSchema,
+		_rev: z.string().meta({ description: "Opaque revision token for optimistic concurrency" }),
+	})
+	.meta({ id: "ContentRestoreResponse" });
+
 /** Response for content list endpoints */
 export const contentListResponseSchema = z
 	.object({