emdash 0.35.0 → 0.37.0

package/src/api/schemas/content.ts

@@ -8,6 +8,16 @@ import { cursorPaginationQuery, httpUrl, localeCode } from "./common.js";
 // Content: Input schemas
 // ---------------------------------------------------------------------------
 
+const contentDateTime = z.iso
+	.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+	.or(
+		z.iso.datetime({
+			offset: true,
+			precision: -1,
+			message: "must be an ISO 8601 datetime",
+		}),
+	);
+
 /** SEO input — per-content meta fields */
 export const contentSeoInput = z
 	.object({
@@ -21,10 +31,7 @@ export const contentSeoInput = z
 
 /** ISO 8601 date or datetime bound for the content-list date range filter. */
 const contentDateBound = z
-	.union([
-		z.iso.datetime({ offset: true, message: "must be an ISO 8601 datetime" }),
-		z.iso.date({ message: "must be an ISO 8601 date" }),
-	])
+	.union([contentDateTime, z.iso.date({ message: "must be an ISO 8601 date" })])
 	.optional();
 
 /**
@@ -61,7 +68,7 @@ const booleanParam = z
 	.optional()
 	.transform((value) => value === "1" || value === "true");
 
-const contentFieldComparable = z.union([z.string().max(2048), z.number().finite()]);
+const contentFieldComparable = z.union([z.string().max(2048), z.number()]);
 const contentFieldFilterScalar = z.union([contentFieldComparable, z.boolean(), z.null()]);
 const contentFieldFilterValue = z.union([
 	contentFieldFilterScalar,
@@ -167,9 +174,7 @@ export const contentListQuery = cursorPaginationQuery
 	.meta({ id: "ContentListQuery" });
 
 /** ISO 8601 datetime for `publishedAt` / `createdAt`. Routes gate writes behind `content:publish_any`. */
-const contentDateOverride = z.iso
-	.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
-	.nullish();
+const contentDateOverride = contentDateTime.nullish();
 
 export const contentCreateBody = z
 	.object({
@@ -212,27 +217,34 @@ export const contentUpdateBody = z
 
 export const contentScheduleBody = z
 	.object({
-		scheduledAt: z.string().min(1, "scheduledAt is required").meta({
-			description: "ISO 8601 datetime for scheduled publishing",
-			example: "2025-06-15T09:00:00Z",
-		}),
+		scheduledAt: z
+			.string()
+			.min(1, "scheduledAt is required")
+			.meta({
+				description: "ISO 8601 datetime for scheduled publishing",
+				examples: ["2025-06-15T09:00:00Z"],
+			}),
 	})
 	.meta({ id: "ContentScheduleBody" });
 
-export const contentPublishBody = z
-	.object({
+export const contentRevisionConditionBody = z.object({
+	_rev: z
+		.string()
+		.optional()
+		.meta({ description: "Opaque revision token for optimistic concurrency" }),
+});
+
+export const contentPublishBody = contentRevisionConditionBody
+	.extend({
 		// .optional() rather than .nullish(): publishing has no semantic
 		// meaning for `null` (you can't "clear" a publish timestamp by
 		// publishing). Tightening the schema here means callers either
 		// pass a valid datetime or omit the field, and the route doesn't
 		// have to silently drop a null that snuck through.
-		publishedAt: z.iso
-			.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
-			.optional()
-			.meta({
-				description:
-					"Optional ISO 8601 datetime to backdate the publish (e.g. when migrating content). Requires content:publish_any permission. Without this, existing published_at is preserved on re-publish.",
-			}),
+		publishedAt: contentDateTime.optional().meta({
+			description:
+				"Optional ISO 8601 datetime to backdate the publish (e.g. when migrating content). Requires content:publish_any permission. Without this, existing published_at is preserved on re-publish.",
+		}),
 	})
 	.meta({ id: "ContentPublishBody" });
 
@@ -249,7 +261,49 @@ export const contentTermsBody = z
 	})
 	.meta({ id: "ContentTermsBody" });
 
-export const contentTrashQuery = cursorPaginationQuery;
+/** A single term variant returned as part of an entry's term assignments. */
+const contentEntryTermSchema = z
+	.object({
+		id: z.string(),
+		name: z.string().meta({ description: "Taxonomy name" }),
+		slug: z.string(),
+		label: z.string(),
+		parentId: z.string().nullable(),
+		locale: localeCode,
+		translationGroup: z.string().nullable(),
+	})
+	.meta({ id: "ContentEntryTerm" });
+
+/** Term assignments response for the content terms endpoint. */
+export const contentTermsResponseSchema = z
+	.object({
+		terms: z.array(contentEntryTermSchema),
+		unresolved: z.array(
+			z.object({
+				translationGroup: z.string(),
+				availableLocales: z.array(localeCode),
+				translations: z.array(
+					z.object({
+						id: z.string(),
+						slug: z.string(),
+						locale: localeCode,
+					}),
+				),
+			}),
+		),
+		entryLocale: localeCode,
+		defaultLocale: localeCode,
+		implicitDefaultLocale: z.boolean(),
+	})
+	.meta({ id: "ContentTermsResponse" });
+
+export const contentTrashQuery = cursorPaginationQuery
+	.extend({
+		locale: localeCode.optional().meta({
+			description: "Restrict the trash listing to entries in this locale",
+		}),
+	})
+	.meta({ id: "ContentTrashQuery" });
 
 // ---------------------------------------------------------------------------
 // Content: Response schemas
@@ -337,6 +391,8 @@ export const trashedContentItemSchema = z
 		type: z.string(),
 		slug: z.string().nullable(),
 		status: z.string(),
+		locale: z.string().nullable(),
+		translationGroup: z.string().nullable(),
 		data: z.record(z.string(), z.unknown()),
 		authorId: z.string().nullable(),
 		createdAt: z.string(),

package/src/api/schemas/media-usage.ts

@@ -13,6 +13,14 @@ export const mediaUsageCoverageSchema = z
 	})
 	.meta({ id: "MediaUsageCoverage" });
 
+export const mediaUsageProgressSchema = z
+	.object({
+		status: z.enum(["indexing", "ready", "needs_attention"]),
+		readyCollections: z.number().int().min(0),
+		totalCollections: z.number().int().min(0),
+	})
+	.meta({ id: "MediaUsageProgress" });
+
 export const mediaUsageSummarySchema = z
 	.object({
 		count: z.number().int().min(0).nullable(),
@@ -182,6 +190,66 @@ export const mediaUsageWorkRetryConflictSchema = z.object({
 	]),
 });
 
+export const mediaUsageActivationStateSchema = z
+	.enum(["expanded", "activating", "active"])
+	.meta({ id: "MediaUsageActivationState" });
+
+export const mediaUsageActivationStatusSchema = z
+	.object({
+		state: mediaUsageActivationStateSchema,
+		collectionCursor: z.string().nullable(),
+		attemptCount: z.number().int().min(0),
+		drainConfirmedAt: z.string().nullable(),
+		lastAttemptedAt: z.string().nullable(),
+		lastErrorCode: z.literal("MEDIA_USAGE_ACTIVATION_FAILED").nullable(),
+		leaseExpiresAt: z.string().nullable(),
+		activatedAt: z.string().nullable(),
+		updatedAt: z.string(),
+	})
+	.meta({ id: "MediaUsageActivationStatus" });
+
+export const mediaUsageActivationAdvanceBody = z
+	.object({
+		writersDrained: z.literal(true),
+	})
+	.strict()
+	.meta({ id: "MediaUsageActivationAdvanceBody" });
+
+export const mediaUsageActivationAdvanceResponseSchema = z
+	.object({
+		outcome: z.enum(["activating", "active"]),
+		processedCollections: z.number().int().min(0).max(1),
+		activation: mediaUsageActivationStatusSchema,
+	})
+	.meta({ id: "MediaUsageActivationAdvanceResponse" });
+
+export const mediaUsageProgressAdvanceResponseSchema = z
+	.object({
+		activation: mediaUsageActivationStatusSchema,
+		progress: mediaUsageProgressSchema.nullable(),
+		nextRequestInMs: z.union([z.literal(0), z.literal(30_000), z.null()]),
+	})
+	.meta({ id: "MediaUsageProgressAdvanceResponse" });
+
+export const mediaUsageActivationConflictSchema = z.object({
+	success: z.literal(false),
+	error: z.discriminatedUnion("code", [
+		z.object({
+			code: z.literal("MEDIA_USAGE_ACTIVATION_BUSY"),
+			message: z.string(),
+			details: z.object({ leaseExpiresAt: z.string() }),
+		}),
+		z.object({
+			code: z.literal("MEDIA_USAGE_ACTIVATION_CONFLICT"),
+			message: z.string(),
+		}),
+		z.object({
+			code: z.literal("MEDIA_USAGE_ACTIVATION_VERSION_MISMATCH"),
+			message: z.string(),
+		}),
+	]),
+});
+
 export const mediaUsageCollectionDeletionStateSchema = z
 	.enum(["pending", "retry", "leased", "failed"])
 	.meta({ id: "MediaUsageCollectionDeletionState" });
@@ -227,11 +295,20 @@ export const mediaUsageCollectionDeletionRetryResponseSchema = z
 
 export type MediaUsageRepairRequest = z.infer<typeof mediaUsageRepairBody>;
 export type MediaUsageRepairResponse = z.infer<typeof mediaUsageRepairResponseSchema>;
+export type MediaUsageProgress = z.infer<typeof mediaUsageProgressSchema>;
+export type MediaUsageProgressAdvanceResponse = z.infer<
+	typeof mediaUsageProgressAdvanceResponseSchema
+>;
 export type MediaUsageWorkListQuery = z.infer<typeof mediaUsageWorkListQuery>;
 export type MediaUsageWorkItem = z.infer<typeof mediaUsageWorkItemSchema>;
 export type MediaUsageWorkListResponse = z.infer<typeof mediaUsageWorkListResponseSchema>;
 export type MediaUsageWorkRetryRequest = z.infer<typeof mediaUsageWorkRetryBody>;
 export type MediaUsageWorkRetryResponse = z.infer<typeof mediaUsageWorkRetryResponseSchema>;
+export type MediaUsageActivationStatus = z.infer<typeof mediaUsageActivationStatusSchema>;
+export type MediaUsageActivationAdvanceRequest = z.infer<typeof mediaUsageActivationAdvanceBody>;
+export type MediaUsageActivationAdvanceResponse = z.infer<
+	typeof mediaUsageActivationAdvanceResponseSchema
+>;
 export type MediaUsageCollectionDeletionListQuery = z.infer<
 	typeof mediaUsageCollectionDeletionListQuery
 >;

package/src/api/schemas/media.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { isValidFocalPointUpdate } from "#media/focal-point.js";
+
 import { cursorPaginationQuery } from "./common.js";
 import { mediaUsageSummarySchema } from "./media-usage.js";
 
@@ -21,13 +23,25 @@ const mimeTypeFilter = z
 
 export const mediaListQuery = cursorPaginationQuery
 	.extend({
+		page: z.coerce.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
 		mimeType: mimeTypeFilter,
+		folderId: z
+			.union([z.literal("unfiled"), z.string().min(1).max(64)])
+			.optional()
+			.meta({
+				description:
+					"Filter by a media folder ID. Use `unfiled` for the Main library; omit for all media.",
+			}),
 		/** Case-insensitive filename substring search (also matches extensions). */
 		q: z.string().trim().min(1).max(200).optional(),
 		includeUsage: z.literal("1").optional().meta({
 			description: "Include a coverage-aware usage summary on each media item",
 		}),
 	})
+	.refine(({ cursor, page }) => cursor === undefined || page === undefined, {
+		message: "cursor and page cannot be used together",
+		path: ["page"],
+	})
 	.meta({ id: "MediaListQuery" });
 
 export const mediaGetQuery = z
@@ -44,9 +58,47 @@ export const mediaUpdateBody = z
 		caption: z.string().optional(),
 		width: z.number().int().positive().optional(),
 		height: z.number().int().positive().optional(),
+		folderId: z
+			.union([z.literal("unfiled"), z.string().min(1).max(64)])
+			.nullable()
+			.optional()
+			.transform((value) => (value === "unfiled" ? null : value))
+			.meta({
+				description:
+					"Assign a media folder ID, or use null or `unfiled` to return the item to the Main library.",
+			}),
+		focalX: z.number().min(0).max(1).nullable().optional(),
+		focalY: z.number().min(0).max(1).nullable().optional(),
+	})
+	.superRefine((value, context) => {
+		if (!isValidFocalPointUpdate(value)) {
+			context.addIssue({
+				code: "custom",
+				message: "focalX and focalY must both be numbers or both be null",
+				path: ["focalX"],
+			});
+		}
 	})
 	.meta({ id: "MediaUpdateBody" });
 
+export const mediaFolderIdSchema = z.string().min(1).max(64);
+
+export const mediaFolderListQuery = cursorPaginationQuery
+	.extend({ q: z.string().trim().min(1).max(200).optional() })
+	.meta({ id: "MediaFolderListQuery" });
+
+const mediaFolderNameSchema = z.string().refine(
+	(value) => {
+		const length = value.trim().length;
+		return length >= 1 && length <= 200;
+	},
+	{ message: "Folder name must be between 1 and 200 characters" },
+);
+
+export const mediaFolderBody = z
+	.object({ name: mediaFolderNameSchema })
+	.meta({ id: "MediaFolderBody" });
+
 /** Default maximum allowed file upload size (50 MB). */
 export const DEFAULT_MAX_UPLOAD_SIZE = 50 * 1024 * 1024;
 
@@ -78,10 +130,51 @@ export function mediaUploadUrlBody(maxSize: number) {
 				.max(maxSize, `File size must not exceed ${formatFileSize(maxSize)}`),
 			contentHash: z.string().optional(),
 			fieldId: z.string().optional(),
+			deduplicate: z.boolean().optional(),
+			ensureUniqueFilename: z.boolean().optional(),
+			folderId: mediaFolderIdSchema.nullable().optional(),
 		})
 		.meta({ id: "MediaUploadUrlBody" });
 }
 
+export const mediaUploadDeduplicateForm = z
+	.enum(["true", "false"])
+	.default("true")
+	.transform((value) => value === "true");
+
+export const mediaUploadEnsureUniqueFilenameForm = z
+	.enum(["true", "false"])
+	.default("false")
+	.transform((value) => value === "true");
+
+export const mediaReplaceMetadataForm = z.object({
+	width: z.coerce.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+	height: z.coerce.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+});
+
+const binaryFileSchema = z.string().meta({ format: "binary" });
+
+export const mediaDirectUploadBody = z
+	.object({
+		file: binaryFileSchema,
+		width: z.string().optional(),
+		height: z.string().optional(),
+		thumbnail: binaryFileSchema.optional(),
+		fieldId: z.string().optional(),
+		deduplicate: z.enum(["true", "false"]).optional(),
+		ensureUniqueFilename: z.enum(["true", "false"]).optional(),
+		folderId: z.union([mediaFolderIdSchema, z.literal("unfiled")]).optional(),
+	})
+	.meta({ id: "MediaDirectUploadBody" });
+
+export const mediaReplaceBody = z
+	.object({
+		file: binaryFileSchema,
+		width: z.number().int().positive(),
+		height: z.number().int().positive(),
+	})
+	.meta({ id: "MediaReplaceBody" });
+
 export const mediaConfirmBody = z
 	.object({
 		size: z.number().int().nonnegative().optional(),
@@ -111,6 +204,8 @@ export const mediaItemSchema = z
 		size: z.number().nullable(),
 		width: z.number().nullable(),
 		height: z.number().nullable(),
+		focalX: z.number().nullable(),
+		focalY: z.number().nullable(),
 		alt: z.string().nullable(),
 		caption: z.string().nullable(),
 		storageKey: z.string(),
@@ -120,9 +215,22 @@ export const mediaItemSchema = z
 		dominantColor: z.string().nullable(),
 		createdAt: z.string(),
 		authorId: z.string().nullable(),
+		folderId: z.string().nullable(),
 	})
 	.meta({ id: "MediaItem" });
 
+export const mediaFolderSchema = z
+	.object({ id: z.string(), name: z.string() })
+	.meta({ id: "MediaFolder" });
+
+export const mediaFolderResponseSchema = z
+	.object({ item: mediaFolderSchema })
+	.meta({ id: "MediaFolderResponse" });
+
+export const mediaFolderListResponseSchema = z
+	.object({ items: z.array(mediaFolderSchema), nextCursor: z.string().optional() })
+	.meta({ id: "MediaFolderListResponse" });
+
 export const mediaResponseSchema = z
 	.object({ item: mediaItemSchema })
 	.meta({ id: "MediaResponse" });
@@ -143,6 +251,7 @@ export const mediaListReadResponseSchema = z
 	.object({
 		items: z.array(mediaListReadItemSchema),
 		nextCursor: z.string().optional(),
+		totalCount: z.number().int().nonnegative().optional(),
 	})
 	.meta({ id: "MediaListReadResponse" });
 
@@ -150,6 +259,7 @@ export const mediaListResponseSchema = z
 	.object({
 		items: z.array(mediaItemSchema),
 		nextCursor: z.string().optional(),
+		totalCount: z.number().int().nonnegative().optional(),
 	})
 	.meta({ id: "MediaListResponse" });
 
@@ -179,6 +289,17 @@ export const mediaConfirmResponseSchema = z
 	})
 	.meta({ id: "MediaConfirmResponse" });
 
+export const mediaUploadResponseSchema = z
+	.object({
+		item: mediaItemSchema.extend({ url: z.string() }),
+		deduplicated: z.literal(true).optional(),
+	})
+	.meta({ id: "MediaUploadResponse" });
+
+export const mediaReplaceResponseSchema = z
+	.object({ item: mediaItemSchema.extend({ url: z.string() }) })
+	.meta({ id: "MediaReplaceResponse" });
+
 export const mediaStreamUploadResponseSchema = z
 	.object({
 		uploaded: z.literal(true),

package/src/api/schemas/redirects.ts

@@ -98,7 +98,12 @@ export const notFoundSummaryQuery = z.object({
 
 export const notFoundPruneBody = z
 	.object({
-		olderThan: z.string().datetime({ message: "olderThan must be an ISO 8601 datetime" }),
+		olderThan: z.iso.datetime({ message: "olderThan must be an ISO 8601 datetime" }).or(
+			z.iso.datetime({
+				precision: -1,
+				message: "olderThan must be an ISO 8601 datetime",
+			}),
+		),
 	})
 	.meta({ id: "NotFoundPruneBody" });
 

package/src/api/schemas/schema.ts

@@ -176,6 +176,8 @@ export const updateCollectionBody = z
 		commentsModeration: z.enum(["all", "first_time", "none"]).optional(),
 		commentsClosedAfterDays: z.number().int().min(0).optional(),
 		commentsAutoApproveUsers: z.boolean().optional(),
+		titleField: z.string().min(1).max(63).regex(slugPattern, "Invalid field slug format").nullish(),
+		dateField: z.string().min(1).max(63).regex(slugPattern, "Invalid field slug format").nullish(),
 	})
 	.meta({ id: "UpdateCollectionBody" });
 
@@ -268,6 +270,8 @@ export const collectionSchema = z
 		sortOrder: z.number().int().nullable(),
 		createdAt: z.string(),
 		updatedAt: z.string(),
+		titleField: z.string().nullish(),
+		dateField: z.string().nullish(),
 	})
 	.meta({ id: "Collection" });
 

package/src/api/schemas/setup.ts

@@ -28,7 +28,7 @@ export const setupBody = z.object({
 });
 
 export const setupAdminBody = z.object({
-	email: z.string().email(),
+	email: z.email(),
 	name: z.string().optional(),
 });
 

package/src/api/schemas/taxonomies.ts

@@ -24,8 +24,8 @@ export const createTaxonomyDefBody = z
 			.regex(/^[a-z][a-z0-9_]*$/, "Name must be lowercase alphanumeric with underscores"),
 		label: z.string().min(1).max(200),
 		labelSingular: z.string().min(1).max(200).optional(),
-		hierarchical: z.boolean().optional().default(false),
-		collections: z.array(collectionSlug).max(100).optional().default([]),
+		hierarchical: z.boolean().optional(),
+		collections: z.array(collectionSlug).max(100).optional(),
 		locale: localeCode.optional(),
 		translationOf: z.string().min(1).optional(),
 	})

package/src/api/schemas/users.ts

@@ -18,7 +18,7 @@ export const usersListQuery = z
 export const userUpdateBody = z
 	.object({
 		name: z.string().optional(),
-		email: z.string().email().optional(),
+		email: z.email().optional(),
 		role: roleLevel.optional(),
 	})
 	.meta({ id: "UserUpdateBody" });

package/src/api/types.ts

@@ -35,16 +35,7 @@ export interface ContentResponse {
 export interface ManifestResponse {
 	version: string;
 	hash: string;
-	collections: Record<
-		string,
-		{
-			label: string;
-			labelSingular: string;
-			supports: string[];
-			routable?: boolean;
-			fields: Record<string, FieldDescriptor>;
-		}
-	>;
+	collections: ManifestCollectionMap;
 	plugins: Record<
 		string,
 		{
@@ -54,6 +45,28 @@ export interface ManifestResponse {
 	>;
 }
 
+export type ManifestCollectionMap = Record<string, ManifestCollectionDescriptor>;
+
+export interface ManifestCollectionDescriptor {
+	label: string;
+	labelSingular: string;
+	supports: string[];
+	hasSeo: boolean;
+	urlPattern?: string;
+	routable?: boolean;
+	titleField?: string;
+	dateField?: string;
+	hidden?: boolean;
+	listColumns?: string[];
+	fields: Record<string, ManifestFieldDescriptor>;
+}
+
+export interface ManifestFieldDescriptor extends FieldDescriptor {
+	id?: string;
+	widget?: string;
+	validation?: Record<string, unknown>;
+}
+
 export interface FieldDescriptor {
 	kind: string;
 	label?: string;

package/src/astro/dev-typegen.ts

@@ -0,0 +1,35 @@
+/**
+ * Dev-only hook for regenerating `emdash-env.d.ts` when the schema changes.
+ *
+ * The Astro integration registers an environment-specific refresh function
+ * (filesystem + local HTTP in Node dev, no-op everywhere else). Schema
+ * mutation code just triggers the hook, so runtime modules stay free of
+ * Node-only I/O.
+ */
+
+const REFRESH_FN_KEY = "__emdashDevTypegenRefresh";
+
+export interface DevTypegenRefreshFn {
+	(db: unknown): void | Promise<void>;
+}
+
+export function setDevTypegenRefresh(fn: DevTypegenRefreshFn): void {
+	if (typeof globalThis !== "undefined") {
+		Reflect.set(globalThis, REFRESH_FN_KEY, fn);
+	}
+}
+
+export function refreshDevTypes(db: unknown): void {
+	if (typeof import.meta.env === "undefined" || !import.meta.env.DEV) return;
+
+	const fn = Reflect.get(globalThis, REFRESH_FN_KEY);
+	if (typeof fn !== "function") return;
+
+	try {
+		Promise.resolve(fn(db)).catch((error: unknown) => {
+			console.error("[emdash] dev typegen refresh failed:", error);
+		});
+	} catch (error) {
+		console.error("[emdash] dev typegen refresh failed:", error);
+	}
+}

package/src/astro/image-endpoint.ts

@@ -15,8 +15,8 @@ import { GET as genericGET } from "astro/assets/endpoint/generic";
 import { getConfiguredImageService, imageConfig } from "astro:assets";
 
 import {
-	IMMUTABLE_IMAGE_CACHE,
 	matchInternalMediaKey,
+	MUTABLE_MEDIA_CACHE_CONTROL,
 	originalMediaHeaders,
 } from "../media/image-endpoint.js";
 
@@ -72,7 +72,7 @@ export const GET: APIRoute = async (ctx) => {
 			status: 200,
 			headers: {
 				"Content-Type": FORMAT_MIME[format] ?? source.contentType,
-				"Cache-Control": IMMUTABLE_IMAGE_CACHE,
+				"Cache-Control": MUTABLE_MEDIA_CACHE_CONTROL,
 				"X-Content-Type-Options": "nosniff",
 			},
 		});