emdash 0.9.0 → 0.10.0

package/src/api/handlers/taxonomies.ts

@@ -1,16 +1,20 @@
 /**
- * Taxonomy and term CRUD handlers
+ * Taxonomy and term CRUD handlers.
+ *
+ * i18n: terms and defs are per-locale. `(name, slug, locale)` is unique for
+ * terms; `(name, locale)` for defs. Translations of the same term/def share a
+ * `translation_group`. The content_taxonomies pivot stores translation_groups
+ * so assignments span every locale of a post.
  */
 
-import type { Kysely } from "kysely";
+import type { Kysely, Selectable } from "kysely";
 import { ulid } from "ulidx";
 
 import { TaxonomyRepository } from "../../database/repositories/taxonomy.js";
-import type { Database } from "../../database/types.js";
+import type { Database, TaxonomyDefTable } from "../../database/types.js";
 import { invalidateTermCache } from "../../taxonomies/index.js";
 import type { ApiResult } from "../types.js";
 
-/** Taxonomy name validation pattern: lowercase alphanumeric + underscores, starts with letter */
 const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
 
 // ---------------------------------------------------------------------------
@@ -24,6 +28,8 @@ export interface TaxonomyDef {
 	labelSingular?: string;
 	hierarchical: boolean;
 	collections: string[];
+	locale: string;
+	translationGroup: string | null;
 }
 
 export interface TaxonomyListResponse {
@@ -37,6 +43,8 @@ export interface TermData {
 	label: string;
 	parentId: string | null;
 	description?: string;
+	locale: string;
+	translationGroup: string | null;
 }
 
 export interface TermWithCount extends TermData {
@@ -59,6 +67,26 @@ export interface TermGetResponse {
 	};
 }
 
+export interface TermTranslationsResponse {
+	translationGroup: string | null;
+	translations: Array<{
+		id: string;
+		slug: string;
+		label: string;
+		locale: string;
+	}>;
+}
+
+export interface TaxonomyDefTranslationsResponse {
+	translationGroup: string | null;
+	translations: Array<{
+		id: string;
+		name: string;
+		label: string;
+		locale: string;
+	}>;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -69,11 +97,7 @@ export interface TermGetResponse {
 function buildTree(flatTerms: TermWithCount[]): TermWithCount[] {
 	const map = new Map<string, TermWithCount>();
 	const roots: TermWithCount[] = [];
-
-	for (const term of flatTerms) {
-		map.set(term.id, term);
-	}
-
+	for (const term of flatTerms) map.set(term.id, term);
 	for (const term of flatTerms) {
 		if (term.parentId && map.has(term.parentId)) {
 			map.get(term.parentId)!.children.push(term);
@@ -81,38 +105,48 @@ function buildTree(flatTerms: TermWithCount[]): TermWithCount[] {
 			roots.push(term);
 		}
 	}
-
 	return roots;
 }
 
 /**
- * Look up a taxonomy definition by name, returning a NOT_FOUND error if missing.
+ * Look up a taxonomy definition by name (optionally scoped to a locale).
+ * Returns the lowest-locale match when no locale is provided.
  */
 async function requireTaxonomyDef(
 	db: Kysely<Database>,
 	name: string,
+	locale?: string,
 ): Promise<
-	| { success: true; def: { hierarchical: number } }
+	| { success: true; def: Selectable<TaxonomyDefTable> }
 	| { success: false; error: { code: string; message: string } }
 > {
-	const def = await db
-		.selectFrom("_emdash_taxonomy_defs")
-		.selectAll()
-		.where("name", "=", name)
-		.executeTakeFirst();
-
+	let query = db.selectFrom("_emdash_taxonomy_defs").selectAll().where("name", "=", name);
+	if (locale !== undefined) query = query.where("locale", "=", locale);
+	const def = await query.orderBy("locale", "asc").executeTakeFirst();
 	if (!def) {
 		return {
 			success: false,
 			error: { code: "NOT_FOUND", message: `Taxonomy '${name}' not found` },
 		};
 	}
-
 	return { success: true, def };
 }
 
+function rowToDef(row: Selectable<TaxonomyDefTable>): TaxonomyDef {
+	return {
+		id: row.id,
+		name: row.name,
+		label: row.label,
+		labelSingular: row.label_singular ?? undefined,
+		hierarchical: row.hierarchical === 1,
+		collections: row.collections ? JSON.parse(row.collections) : [],
+		locale: row.locale,
+		translationGroup: row.translation_group,
+	};
+}
+
 // ---------------------------------------------------------------------------
-// Handlers
+// Taxonomy definition handlers
 // ---------------------------------------------------------------------------
 
 /**
@@ -120,10 +154,13 @@ async function requireTaxonomyDef(
  */
 export async function handleTaxonomyList(
 	db: Kysely<Database>,
+	options: { locale?: string } = {},
 ): Promise<ApiResult<TaxonomyListResponse>> {
 	try {
+		let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
+		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
 		const [rows, collectionRows] = await Promise.all([
-			db.selectFrom("_emdash_taxonomy_defs").selectAll().execute(),
+			query.execute(),
 			db.selectFrom("_emdash_collections").select("slug").execute(),
 		]);
 
@@ -133,15 +170,8 @@ export async function handleTaxonomyList(
 		const realCollections = new Set(collectionRows.map((r) => r.slug));
 
 		const taxonomies: TaxonomyDef[] = rows.map((row) => {
-			const stored: string[] = row.collections ? JSON.parse(row.collections) : [];
-			return {
-				id: row.id,
-				name: row.name,
-				label: row.label,
-				labelSingular: row.label_singular ?? undefined,
-				hierarchical: row.hierarchical === 1,
-				collections: stored.filter((slug) => realCollections.has(slug)),
-			};
+			const def = rowToDef(row);
+			return { ...def, collections: def.collections.filter((slug) => realCollections.has(slug)) };
 		});
 
 		return { success: true, data: { taxonomies } };
@@ -158,10 +188,17 @@ export async function handleTaxonomyList(
  */
 export async function handleTaxonomyCreate(
 	db: Kysely<Database>,
-	input: { name: string; label: string; hierarchical?: boolean; collections?: string[] },
+	input: {
+		name: string;
+		label: string;
+		labelSingular?: string;
+		hierarchical?: boolean;
+		collections?: string[];
+		locale?: string;
+		translationOf?: string;
+	},
 ): Promise<ApiResult<{ taxonomy: TaxonomyDef }>> {
 	try {
-		// Validate name format
 		if (!NAME_PATTERN.test(input.name)) {
 			return {
 				success: false,
@@ -174,15 +211,12 @@ export async function handleTaxonomyCreate(
 		}
 
 		const collections = [...new Set(input.collections ?? [])];
-
-		// Validate that referenced collections exist
 		if (collections.length > 0) {
 			const existingCollections = await db
 				.selectFrom("_emdash_collections")
 				.select("slug")
 				.where("slug", "in", collections)
 				.execute();
-
 			const existingSlugs = new Set(existingCollections.map((c) => c.slug));
 			const invalid = collections.filter((c) => !existingSlugs.has(c));
 			if (invalid.length > 0) {
@@ -196,58 +230,68 @@ export async function handleTaxonomyCreate(
 			}
 		}
 
-		// Check for duplicate name
-		const existing = await db
-			.selectFrom("_emdash_taxonomy_defs")
-			.selectAll()
-			.where("name", "=", input.name)
-			.executeTakeFirst();
+		let translationGroup: string | null = null;
+		if (input.translationOf) {
+			const source = await db
+				.selectFrom("_emdash_taxonomy_defs")
+				.selectAll()
+				.where("id", "=", input.translationOf)
+				.executeTakeFirst();
+			if (!source) {
+				return {
+					success: false,
+					error: { code: "NOT_FOUND", message: "Source taxonomy for translation not found" },
+				};
+			}
+			translationGroup = source.translation_group ?? source.id;
+		}
 
-		if (existing) {
-			return {
-				success: false,
-				error: {
-					code: "CONFLICT",
-					message: `Taxonomy '${input.name}' already exists`,
-				},
-			};
+		// Duplicate guard scoped to locale (so the same name can exist in ES
+		// and EN).
+		if (input.locale !== undefined) {
+			const existing = await db
+				.selectFrom("_emdash_taxonomy_defs")
+				.select("id")
+				.where("name", "=", input.name)
+				.where("locale", "=", input.locale)
+				.executeTakeFirst();
+			if (existing) {
+				return {
+					success: false,
+					error: {
+						code: "CONFLICT",
+						message: `Taxonomy '${input.name}' already exists in locale '${input.locale}'`,
+					},
+				};
+			}
 		}
 
 		const id = ulid();
-
 		await db
 			.insertInto("_emdash_taxonomy_defs")
 			.values({
 				id,
 				name: input.name,
 				label: input.label,
-				label_singular: null,
+				label_singular: input.labelSingular ?? null,
 				hierarchical: input.hierarchical ? 1 : 0,
 				collections: JSON.stringify(collections),
+				...(input.locale !== undefined ? { locale: input.locale } : {}),
+				translation_group: translationGroup ?? id,
 			})
 			.execute();
 
-		return {
-			success: true,
-			data: {
-				taxonomy: {
-					id,
-					name: input.name,
-					label: input.label,
-					hierarchical: input.hierarchical ?? false,
-					collections,
-				},
-			},
-		};
+		const row = await db
+			.selectFrom("_emdash_taxonomy_defs")
+			.selectAll()
+			.where("id", "=", id)
+			.executeTakeFirstOrThrow();
+		return { success: true, data: { taxonomy: rowToDef(row) } };
 	} catch (error) {
-		// Handle UNIQUE constraint violation from concurrent duplicate inserts
 		if (error instanceof Error && error.message.includes("UNIQUE constraint failed")) {
 			return {
 				success: false,
-				error: {
-					code: "CONFLICT",
-					message: `Taxonomy '${input.name}' already exists`,
-				},
+				error: { code: "CONFLICT", message: `Taxonomy '${input.name}' already exists` },
 			};
 		}
 		return {
@@ -257,23 +301,81 @@ export async function handleTaxonomyCreate(
 	}
 }
 
+/**
+ * List every locale translation of a taxonomy def (by id or translation_group).
+ */
+export async function handleTaxonomyDefTranslations(
+	db: Kysely<Database>,
+	idOrGroup: string,
+): Promise<ApiResult<TaxonomyDefTranslationsResponse>> {
+	try {
+		const anchor = await db
+			.selectFrom("_emdash_taxonomy_defs")
+			.selectAll()
+			.where((eb) => eb.or([eb("id", "=", idOrGroup), eb("translation_group", "=", idOrGroup)]))
+			.executeTakeFirst();
+		if (!anchor) {
+			return {
+				success: false,
+				error: { code: "NOT_FOUND", message: "Taxonomy not found" },
+			};
+		}
+		const group = anchor.translation_group ?? anchor.id;
+		const rows = await db
+			.selectFrom("_emdash_taxonomy_defs")
+			.selectAll()
+			.where("translation_group", "=", group)
+			.orderBy("locale", "asc")
+			.execute();
+		return {
+			success: true,
+			data: {
+				translationGroup: group,
+				translations: rows.map((r) => ({
+					id: r.id,
+					name: r.name,
+					label: r.label,
+					locale: r.locale,
+				})),
+			},
+		};
+	} catch {
+		return {
+			success: false,
+			error: {
+				code: "TAXONOMY_TRANSLATIONS_ERROR",
+				message: "Failed to list taxonomy translations",
+			},
+		};
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Term handlers
+// ---------------------------------------------------------------------------
+
 /**
  * List all terms for a taxonomy (returns tree for hierarchical taxonomies)
  */
 export async function handleTermList(
 	db: Kysely<Database>,
 	taxonomyName: string,
+	options: { locale?: string } = {},
 ): Promise<ApiResult<TermListResponse>> {
 	try {
+		// Definitions are per-locale but terms aren't bound to the def's locale —
+		// just ensure the taxonomy exists somewhere.
 		const lookup = await requireTaxonomyDef(db, taxonomyName);
 		if (!lookup.success) return lookup;
 
 		const repo = new TaxonomyRepository(db);
-		const terms = await repo.findByName(taxonomyName);
+		const terms = await repo.findByName(taxonomyName, { locale: options.locale });
 
-		// Batch count entries per term in a single query (replaces N+1 pattern)
-		const termIds = terms.map((t) => t.id);
-		const counts = await repo.countEntriesForTerms(termIds);
+		// Batch count entries per term in a single query (replaces N+1 pattern).
+		// content_taxonomies.taxonomy_id stores the translation_group, so we
+		// look up by group and map back to each term's id.
+		const groups = terms.map((t) => t.translationGroup ?? t.id);
+		const countsByGroup = await repo.countEntriesForTerms(groups);
 
 		const termData: TermWithCount[] = terms.map((term) => ({
 			id: term.id,
@@ -283,12 +385,13 @@ export async function handleTermList(
 			parentId: term.parentId,
 			description: typeof term.data?.description === "string" ? term.data.description : undefined,
 			children: [],
-			count: counts.get(term.id) ?? 0,
+			count: countsByGroup.get(term.translationGroup ?? term.id) ?? 0,
+			locale: term.locale,
+			translationGroup: term.translationGroup,
 		}));
 
 		const isHierarchical = lookup.def.hierarchical === 1;
 		const result = isHierarchical ? buildTree(termData) : termData;
-
 		return { success: true, data: { terms: result } };
 	} catch {
 		return {
@@ -382,30 +485,60 @@ async function validateParentTerm(
 export async function handleTermCreate(
 	db: Kysely<Database>,
 	taxonomyName: string,
-	input: { slug: string; label: string; parentId?: string | null; description?: string },
+	input: {
+		slug: string;
+		label: string;
+		parentId?: string | null;
+		description?: string;
+		locale?: string;
+		translationOf?: string;
+	},
 ): Promise<ApiResult<TermResponse>> {
 	try {
+		// 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);
 		if (!lookup.success) return lookup;
 
 		const repo = new TaxonomyRepository(db);
 
 		// Coerce empty-string parentId to undefined (treat as "no parent").
-		const parentId =
+		let parentId =
 			input.parentId === "" || input.parentId === undefined ? undefined : input.parentId;
 
-		// Check for slug conflict
-		const existing = await repo.findBySlug(taxonomyName, input.slug);
+		// Conflict check is scoped to locale (per-locale slugs are unique).
+		const existing = await repo.findBySlug(taxonomyName, input.slug, input.locale);
 		if (existing) {
 			return {
 				success: false,
 				error: {
 					code: "CONFLICT",
-					message: `Term with slug '${input.slug}' already exists in taxonomy '${taxonomyName}'`,
+					message: input.locale
+						? `Term '${input.slug}' already exists in '${taxonomyName}' (${input.locale})`
+						: `Term with slug '${input.slug}' already exists in taxonomy '${taxonomyName}'`,
 				},
 			};
 		}
 
+		// If creating a translation whose parent is the translated sibling of
+		// the source's parent, try to resolve the parent in the same locale.
+		if (input.translationOf && parentId) {
+			const source = await repo.findById(input.translationOf);
+			if (source?.parentId === parentId && input.locale) {
+				const sourceParent = await repo.findById(parentId);
+				if (sourceParent?.translationGroup) {
+					const translatedParent = await db
+						.selectFrom("taxonomies")
+						.select("id")
+						.where("translation_group", "=", sourceParent.translationGroup)
+						.where("locale", "=", input.locale)
+						.executeTakeFirst();
+					if (translatedParent) parentId = translatedParent.id;
+				}
+			}
+		}
+
 		// Validate parentId: must exist AND belong to the same taxonomy.
 		// (Cycle check is N/A on create — the term doesn't exist yet.)
 		const parentError = await validateParentTerm(repo, taxonomyName, undefined, parentId);
@@ -419,10 +552,10 @@ export async function handleTermCreate(
 			label: input.label,
 			parentId: parentId ?? undefined,
 			data: input.description ? { description: input.description } : undefined,
+			locale: input.locale,
+			translationOf: input.translationOf,
 		});
 
-		// New term means `hasAnyTermAssignments` may flip from false->true next
-		// time an entry is tagged. Clear the cache so the next read re-probes.
 		invalidateTermCache();
 
 		return {
@@ -436,6 +569,8 @@ export async function handleTermCreate(
 					parentId: term.parentId,
 					description:
 						typeof term.data?.description === "string" ? term.data.description : undefined,
+					locale: term.locale,
+					translationGroup: term.translationGroup,
 				},
 			},
 		};
@@ -454,10 +589,11 @@ export async function handleTermGet(
 	db: Kysely<Database>,
 	taxonomyName: string,
 	termSlug: string,
+	options: { locale?: string } = {},
 ): Promise<ApiResult<TermGetResponse>> {
 	try {
 		const repo = new TaxonomyRepository(db);
-		const term = await repo.findBySlug(taxonomyName, termSlug);
+		const term = await repo.findBySlug(taxonomyName, termSlug, options.locale);
 
 		if (!term) {
 			return {
@@ -484,11 +620,9 @@ export async function handleTermGet(
 					description:
 						typeof term.data?.description === "string" ? term.data.description : undefined,
 					count,
-					children: children.map((c) => ({
-						id: c.id,
-						slug: c.slug,
-						label: c.label,
-					})),
+					children: children.map((c) => ({ id: c.id, slug: c.slug, label: c.label })),
+					locale: term.locale,
+					translationGroup: term.translationGroup,
 				},
 			},
 		};
@@ -500,6 +634,50 @@ export async function handleTermGet(
 	}
 }
 
+/** List every translation of a term (by id or translation_group). */
+export async function handleTermTranslations(
+	db: Kysely<Database>,
+	idOrGroup: string,
+): Promise<ApiResult<TermTranslationsResponse>> {
+	try {
+		const anchor = await db
+			.selectFrom("taxonomies")
+			.selectAll()
+			.where((eb) => eb.or([eb("id", "=", idOrGroup), eb("translation_group", "=", idOrGroup)]))
+			.executeTakeFirst();
+		if (!anchor) {
+			return {
+				success: false,
+				error: { code: "NOT_FOUND", message: "Term not found" },
+			};
+		}
+		const group = anchor.translation_group ?? anchor.id;
+		const rows = await db
+			.selectFrom("taxonomies")
+			.selectAll()
+			.where("translation_group", "=", group)
+			.orderBy("locale", "asc")
+			.execute();
+		return {
+			success: true,
+			data: {
+				translationGroup: group,
+				translations: rows.map((r) => ({
+					id: r.id,
+					slug: r.slug,
+					label: r.label,
+					locale: r.locale,
+				})),
+			},
+		};
+	} catch {
+		return {
+			success: false,
+			error: { code: "TERM_TRANSLATIONS_ERROR", message: "Failed to list term translations" },
+		};
+	}
+}
+
 /**
  * Update a term
  */
@@ -508,10 +686,11 @@ export async function handleTermUpdate(
 	taxonomyName: string,
 	termSlug: string,
 	input: { slug?: string; label?: string; parentId?: string | null; description?: string },
+	options: { locale?: string } = {},
 ): Promise<ApiResult<TermResponse>> {
 	try {
 		const repo = new TaxonomyRepository(db);
-		const term = await repo.findBySlug(taxonomyName, termSlug);
+		const term = await repo.findBySlug(taxonomyName, termSlug, options.locale);
 
 		if (!term) {
 			return {
@@ -529,9 +708,9 @@ export async function handleTermUpdate(
 		const newParentId =
 			input.parentId === "" || input.parentId === undefined ? undefined : input.parentId;
 
-		// Check if new slug conflicts
+		// Check if new slug conflicts (per-locale uniqueness).
 		if (newSlug !== undefined && newSlug !== termSlug) {
-			const existing = await repo.findBySlug(taxonomyName, newSlug);
+			const existing = await repo.findBySlug(taxonomyName, newSlug, options.locale);
 			if (existing && existing.id !== term.id) {
 				return {
 					success: false,
@@ -556,8 +735,6 @@ export async function handleTermUpdate(
 			data: input.description !== undefined ? { description: input.description } : undefined,
 		});
 
-		// Term label/slug changes are reflected in hydrated entry.data.terms —
-		// invalidate so the next read doesn't short-circuit on a stale probe.
 		invalidateTermCache();
 
 		if (!updated) {
@@ -578,6 +755,8 @@ export async function handleTermUpdate(
 					parentId: updated.parentId,
 					description:
 						typeof updated.data?.description === "string" ? updated.data.description : undefined,
+					locale: updated.locale,
+					translationGroup: updated.translationGroup,
 				},
 			},
 		};
@@ -596,10 +775,11 @@ export async function handleTermDelete(
 	db: Kysely<Database>,
 	taxonomyName: string,
 	termSlug: string,
+	options: { locale?: string } = {},
 ): Promise<ApiResult<{ deleted: true }>> {
 	try {
 		const repo = new TaxonomyRepository(db);
-		const term = await repo.findBySlug(taxonomyName, termSlug);
+		const term = await repo.findBySlug(taxonomyName, termSlug, options.locale);
 
 		if (!term) {
 			return {
@@ -611,7 +791,6 @@ export async function handleTermDelete(
 			};
 		}
 
-		// Prevent deletion of terms with children
 		const children = await repo.findChildren(term.id);
 		if (children.length > 0) {
 			return {
@@ -631,10 +810,7 @@ export async function handleTermDelete(
 			};
 		}
 
-		// Deleting a term cascades to content_taxonomies; invalidate so
-		// hydration no longer sees the stale assignments.
 		invalidateTermCache();
-
 		return { success: true, data: { deleted: true } };
 	} catch {
 		return {

package/src/api/schemas/common.ts

@@ -59,6 +59,13 @@ export const localeCode = z
 	.regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i, "Invalid locale code")
 	.transform((v) => v.toLowerCase());
 
+/** Shared `?locale=xx` query shape for endpoints that filter by locale. */
+export const localeFilterQuery = z
+	.object({
+		locale: z.string().min(1).optional(),
+	})
+	.meta({ id: "LocaleFilterQuery" });
+
 // ---------------------------------------------------------------------------
 // OpenAPI: Shared response schemas
 // ---------------------------------------------------------------------------