ghost 6.55.0 → 6.56.0

package/core/server/services/route-settings/route-settings-parser.js

@@ -36,11 +36,11 @@ const SHORTFORM_HELP = 'e.g. data: tag.recipes';
  */
 function validateDataShortForm(value, path) {
     if (!/^[a-zA-Z0-9_]+\.(?:%s|[a-zA-Z0-9_-]+)$/.test(value)) {
-        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `"${value}" is not a valid data shorthand. Please use resource.slug, e.g. tag.recipes.`, SHORTFORM_HELP);
+        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `"${value}" is not a valid data shorthand. Please use resource.slug, e.g. tag.recipes.`, { help: SHORTFORM_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
     }
     const resource = value.split('.')[0];
     if (!VALID_SHORTFORM_RESOURCES.includes(resource)) {
-        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `resource "${resource}" is not supported. Please use ${(0, validation_errors_1.humanList)(VALID_SHORTFORM_RESOURCES)}.`, SHORTFORM_HELP);
+        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `resource "${resource}" is not supported. Please use ${(0, validation_errors_1.humanList)(VALID_SHORTFORM_RESOURCES)}.`, { help: SHORTFORM_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE });
     }
 }
 const DataReadEntrySchema = zod_1.z.object({
@@ -82,20 +82,20 @@ function parseDataEntry(value, path) {
             // is free to change.
             if (issue.code === 'invalid_union' && issue.path[0] === 'type') {
                 if (record.type === undefined) {
-                    throw (0, validation_errors_1.validationError)(at, 'type is required. Please use read or browse.', DATA_ENTRY_HELP);
+                    throw (0, validation_errors_1.validationError)(at, 'type is required. Please use read or browse.', { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
                 }
-                throw (0, validation_errors_1.validationError)(at, `type "${record.type}" is not supported. Please use read or browse.`, DATA_ENTRY_HELP);
+                throw (0, validation_errors_1.validationError)(at, `type "${record.type}" is not supported. Please use read or browse.`, { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
             }
             if (issue.path.includes('resource')) {
                 if (record.resource === undefined) {
-                    throw (0, validation_errors_1.validationError)(at, `resource is required. Please use ${(0, validation_errors_1.humanList)(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
+                    throw (0, validation_errors_1.validationError)(at, `resource is required. Please use ${(0, validation_errors_1.humanList)(VALID_LONGFORM_RESOURCES)}.`, { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE });
                 }
-                throw (0, validation_errors_1.validationError)(at, `resource "${record.resource}" is not supported. Please use ${(0, validation_errors_1.humanList)(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
+                throw (0, validation_errors_1.validationError)(at, `resource "${record.resource}" is not supported. Please use ${(0, validation_errors_1.humanList)(VALID_LONGFORM_RESOURCES)}.`, { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE });
             }
             if (issue.path.includes('slug') && !record.slug) {
-                throw (0, validation_errors_1.validationError)(at, 'slug is required for read data entries.', DATA_ENTRY_HELP);
+                throw (0, validation_errors_1.validationError)(at, 'slug is required for read data entries.', { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
             }
-            throw (0, validation_errors_1.toValidationError)(result.error, path, value);
+            throw (0, validation_errors_1.toValidationError)(result.error, path, value, validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA);
         }
         // Fields set to an explicitly empty value parse to undefined — drop the
         // keys so "unset" means absent in the domain model and serialized output.
@@ -107,7 +107,7 @@ function parseDataEntry(value, path) {
         }
         return result.data;
     }
-    throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `a data entry must be a shorthand like tag.recipes, or a map with type and resource, but ${(0, validation_errors_1.describeValue)(value)} was provided.`, DATA_ENTRY_HELP);
+    throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `a data entry must be a shorthand like tag.recipes, or a map with type and resource, but ${(0, validation_errors_1.describeValue)(value)} was provided.`, { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
 }
 function parseRouteData(data, path) {
     if (typeof data === 'string') {
@@ -115,15 +115,15 @@ function parseRouteData(data, path) {
         return data;
     }
     if (typeof data !== 'object' || data === null || Array.isArray(data)) {
-        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `data must be a shorthand like tag.recipes, or a map of named data entries, but ${(0, validation_errors_1.describeValue)(data)} was provided.`, DATA_ENTRY_HELP);
+        throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(path), `data must be a shorthand like tag.recipes, or a map of named data entries, but ${(0, validation_errors_1.describeValue)(data)} was provided.`, { help: DATA_ENTRY_HELP, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
     }
     const record = data;
     for (const key of Object.keys(record)) {
         if (RESERVED_DATA_KEYS.includes(key)) {
-            throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)([...path, key]), (0, tpl_1.default)(messages.badDataError, { key }), messages.badDataHelp);
+            throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)([...path, key]), (0, tpl_1.default)(messages.badDataError, { key }), { help: messages.badDataHelp, code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
         }
         if (key === 'author') {
-            throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)([...path, key]), messages.authorDeprecatedError);
+            throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)([...path, key]), messages.authorDeprecatedError, { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA });
         }
     }
     const parsed = {};
@@ -159,8 +159,8 @@ const routeObjectSchema = (path) => zod_1.z.object({
             templates
         };
         // Preserve rss only when the author set it explicitly — the domain model
-        // mirrors user intent (unset vs true vs false), so the activation bridge
-        // reproduces validate.js output byte-for-byte.
+        // mirrors user intent (unset vs true vs false), so serializing never
+        // writes back an `rss` key the author never wrote.
         if (val.rss !== undefined) {
             route.rss = val.rss;
         }
@@ -237,18 +237,18 @@ const RouteSettingsSchema = zod_1.z.object({
  * rejecting :param there would break the former, and the suggested rewrite would
  * silently produce the latter.
  */
-function validatePath(value, path, example, { allowParamNotation = false } = {}) {
+function validatePath(value, path, example, { allowParamNotation = false, code = validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_PATH } = {}) {
     const at = (0, validation_errors_1.formatLocation)(path);
     if (!value.startsWith('/')) {
-        throw (0, validation_errors_1.validationError)(at, `"${value}" is missing a leading slash. Please use e.g. ${example}.`);
+        throw (0, validation_errors_1.validationError)(at, `"${value}" is missing a leading slash. Please use e.g. ${example}.`, { code });
     }
     if (!value.endsWith('/')) {
-        throw (0, validation_errors_1.validationError)(at, `"${value}" is missing a trailing slash. Please use e.g. ${example}.`);
+        throw (0, validation_errors_1.validationError)(at, `"${value}" is missing a trailing slash. Please use e.g. ${example}.`, { code });
     }
     if (!allowParamNotation && /\/:\w+/.test(value)) {
         // Suggest the same path in the notation Ghost expects, rather than a
         // generic example the author then has to translate.
-        throw (0, validation_errors_1.validationError)(at, `"${value}" uses the :param notation. Please use "${value.replace(/\/:(\w+)/g, '/{$1}')}".`);
+        throw (0, validation_errors_1.validationError)(at, `"${value}" uses the :param notation. Please use "${value.replace(/\/:(\w+)/g, '/{$1}')}".`, { code });
     }
 }
 function parseRouteSettings(raw, yamlSource) {
@@ -264,7 +264,7 @@ function parseRouteSettings(raw, yamlSource) {
             const routeLocation = ['routes', path];
             validatePath(path, routeLocation, '/about/', { allowParamNotation: true });
             if (value === null || value === undefined) {
-                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(routeLocation), 'Please define a template, e.g. /about/: about.');
+                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(routeLocation), 'Please define a template, e.g. /about/: about.', { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_TEMPLATE });
             }
             if (typeof value === 'string') {
                 routes.push({ type: 'template', path, templates: [value] });
@@ -276,7 +276,7 @@ function parseRouteSettings(raw, yamlSource) {
             }
             const route = routeResult.data;
             if (route.type === 'template' && (!route.templates || route.templates.length === 0) && !route.data && !route.contentType) {
-                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(routeLocation), 'Please define a template, e.g. /about/: about.');
+                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(routeLocation), 'Please define a template, e.g. /about/: about.', { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_TEMPLATE });
             }
             routes.push({ ...route, path });
         }
@@ -292,9 +292,9 @@ function parseRouteSettings(raw, yamlSource) {
             }
             const collection = collectionResult.data;
             if (!collection.permalink) {
-                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(collectionLocation), 'Please define a permalink route, e.g. permalink: /{slug}/.');
+                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(collectionLocation), 'Please define a permalink route, e.g. permalink: /{slug}/.', { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK });
             }
-            validatePath(collection.permalink, [...collectionLocation, 'permalink'], '/{slug}/');
+            validatePath(collection.permalink, [...collectionLocation, 'permalink'], '/{slug}/', { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK });
             collections.push({ ...collection, path });
         }
     }
@@ -303,12 +303,12 @@ function parseRouteSettings(raw, yamlSource) {
         for (const [key, value] of Object.entries(rawTaxonomies)) {
             const taxonomyLocation = ['taxonomies', key];
             if (!['tag', 'author'].includes(key)) {
-                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(taxonomyLocation), 'Unknown taxonomy. Please use tag or author.');
+                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(taxonomyLocation), 'Unknown taxonomy. Please use tag or author.', { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_TAXONOMY });
             }
             if (!value) {
-                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(taxonomyLocation), `Please define a taxonomy permalink route, e.g. ${key}: /${key}/{slug}/.`);
+                throw (0, validation_errors_1.validationError)((0, validation_errors_1.formatLocation)(taxonomyLocation), `Please define a taxonomy permalink route, e.g. ${key}: /${key}/{slug}/.`, { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK });
             }
-            validatePath(value, taxonomyLocation, `/${key}/{slug}/`);
+            validatePath(value, taxonomyLocation, `/${key}/{slug}/`, { code: validation_errors_1.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK });
             if (key === 'tag') {
                 taxonomies.tag = value;
             }

package/core/server/services/route-settings/route-settings-parser.ts

@@ -12,8 +12,8 @@ import type {
 } from '@tryghost/adapter-base-route-settings';
 import {z} from 'zod';
 import tpl from '@tryghost/tpl';
-import type {PathSegment} from './validation-errors';
-import {describeValue, formatLocation, humanList, toValidationError, validationError} from './validation-errors';
+import type {PathSegment, RouteSettingsErrorCode} from './validation-errors';
+import {describeValue, formatLocation, humanList, ROUTE_SETTINGS_ERROR_CODES, toValidationError, validationError} from './validation-errors';
 
 const messages = {
     badDataError: '"{key}" is a reserved key. Please wrap the data definition into a custom name.',
@@ -49,7 +49,7 @@ function validateDataShortForm(value: string, path: PathSegment[]): void {
         throw validationError(
             formatLocation(path),
             `"${value}" is not a valid data shorthand. Please use resource.slug, e.g. tag.recipes.`,
-            SHORTFORM_HELP
+            {help: SHORTFORM_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA}
         );
     }
 
@@ -58,7 +58,7 @@ function validateDataShortForm(value: string, path: PathSegment[]): void {
         throw validationError(
             formatLocation(path),
             `resource "${resource}" is not supported. Please use ${humanList(VALID_SHORTFORM_RESOURCES)}.`,
-            SHORTFORM_HELP
+            {help: SHORTFORM_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE}
         );
     }
 }
@@ -108,20 +108,20 @@ function parseDataEntry(value: unknown, path: PathSegment[]): DataEntry {
             // is free to change.
             if (issue.code === 'invalid_union' && issue.path[0] === 'type') {
                 if (record.type === undefined) {
-                    throw validationError(at, 'type is required. Please use read or browse.', DATA_ENTRY_HELP);
+                    throw validationError(at, 'type is required. Please use read or browse.', {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA});
                 }
-                throw validationError(at, `type "${record.type}" is not supported. Please use read or browse.`, DATA_ENTRY_HELP);
+                throw validationError(at, `type "${record.type}" is not supported. Please use read or browse.`, {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA});
             }
             if (issue.path.includes('resource')) {
                 if (record.resource === undefined) {
-                    throw validationError(at, `resource is required. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
+                    throw validationError(at, `resource is required. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE});
                 }
-                throw validationError(at, `resource "${record.resource}" is not supported. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
+                throw validationError(at, `resource "${record.resource}" is not supported. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_RESOURCE});
             }
             if (issue.path.includes('slug') && !record.slug) {
-                throw validationError(at, 'slug is required for read data entries.', DATA_ENTRY_HELP);
+                throw validationError(at, 'slug is required for read data entries.', {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA});
             }
-            throw toValidationError(result.error, path, value);
+            throw toValidationError(result.error, path, value, ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA);
         }
         // Fields set to an explicitly empty value parse to undefined — drop the
         // keys so "unset" means absent in the domain model and serialized output.
@@ -137,7 +137,7 @@ function parseDataEntry(value: unknown, path: PathSegment[]): DataEntry {
     throw validationError(
         formatLocation(path),
         `a data entry must be a shorthand like tag.recipes, or a map with type and resource, but ${describeValue(value)} was provided.`,
-        DATA_ENTRY_HELP
+        {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA}
     );
 }
 
@@ -151,7 +151,7 @@ function parseRouteData(data: unknown, path: PathSegment[]): RouteData {
         throw validationError(
             formatLocation(path),
             `data must be a shorthand like tag.recipes, or a map of named data entries, but ${describeValue(data)} was provided.`,
-            DATA_ENTRY_HELP
+            {help: DATA_ENTRY_HELP, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA}
         );
     }
 
@@ -159,10 +159,10 @@ function parseRouteData(data: unknown, path: PathSegment[]): RouteData {
 
     for (const key of Object.keys(record)) {
         if (RESERVED_DATA_KEYS.includes(key)) {
-            throw validationError(formatLocation([...path, key]), tpl(messages.badDataError, {key}), messages.badDataHelp);
+            throw validationError(formatLocation([...path, key]), tpl(messages.badDataError, {key}), {help: messages.badDataHelp, code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA});
         }
         if (key === 'author') {
-            throw validationError(formatLocation([...path, key]), messages.authorDeprecatedError);
+            throw validationError(formatLocation([...path, key]), messages.authorDeprecatedError, {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_DATA});
         }
     }
 
@@ -202,8 +202,8 @@ const routeObjectSchema = (path: PathSegment[]) => z.object({
             templates
         };
         // Preserve rss only when the author set it explicitly — the domain model
-        // mirrors user intent (unset vs true vs false), so the activation bridge
-        // reproduces validate.js output byte-for-byte.
+        // mirrors user intent (unset vs true vs false), so serializing never
+        // writes back an `rss` key the author never wrote.
         if (val.rss !== undefined) {
             route.rss = val.rss;
         }
@@ -284,19 +284,19 @@ const RouteSettingsSchema = z.object({
  * rejecting :param there would break the former, and the suggested rewrite would
  * silently produce the latter.
  */
-function validatePath(value: string, path: PathSegment[], example: string, {allowParamNotation = false}: {allowParamNotation?: boolean} = {}): void {
+function validatePath(value: string, path: PathSegment[], example: string, {allowParamNotation = false, code = ROUTE_SETTINGS_ERROR_CODES.INVALID_PATH}: {allowParamNotation?: boolean, code?: RouteSettingsErrorCode} = {}): void {
     const at = formatLocation(path);
 
     if (!value.startsWith('/')) {
-        throw validationError(at, `"${value}" is missing a leading slash. Please use e.g. ${example}.`);
+        throw validationError(at, `"${value}" is missing a leading slash. Please use e.g. ${example}.`, {code});
     }
     if (!value.endsWith('/')) {
-        throw validationError(at, `"${value}" is missing a trailing slash. Please use e.g. ${example}.`);
+        throw validationError(at, `"${value}" is missing a trailing slash. Please use e.g. ${example}.`, {code});
     }
     if (!allowParamNotation && /\/:\w+/.test(value)) {
         // Suggest the same path in the notation Ghost expects, rather than a
         // generic example the author then has to translate.
-        throw validationError(at, `"${value}" uses the :param notation. Please use "${value.replace(/\/:(\w+)/g, '/{$1}')}".`);
+        throw validationError(at, `"${value}" uses the :param notation. Please use "${value.replace(/\/:(\w+)/g, '/{$1}')}".`, {code});
     }
 }
 
@@ -317,7 +317,7 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
             validatePath(path, routeLocation, '/about/', {allowParamNotation: true});
 
             if (value === null || value === undefined) {
-                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.');
+                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.', {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_TEMPLATE});
             }
 
             if (typeof value === 'string') {
@@ -332,7 +332,7 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
 
             const route = routeResult.data;
             if (route.type === 'template' && (!route.templates || route.templates.length === 0) && !route.data && !(route as Omit<TemplateRoute, 'path'>).contentType) {
-                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.');
+                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.', {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_TEMPLATE});
             }
 
             routes.push({...route, path} as Route);
@@ -352,9 +352,9 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
 
             const collection = collectionResult.data;
             if (!collection.permalink) {
-                throw validationError(formatLocation(collectionLocation), 'Please define a permalink route, e.g. permalink: /{slug}/.');
+                throw validationError(formatLocation(collectionLocation), 'Please define a permalink route, e.g. permalink: /{slug}/.', {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK});
             }
-            validatePath(collection.permalink, [...collectionLocation, 'permalink'], '/{slug}/');
+            validatePath(collection.permalink, [...collectionLocation, 'permalink'], '/{slug}/', {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK});
 
             collections.push({...collection, path});
         }
@@ -365,12 +365,12 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
         for (const [key, value] of Object.entries(rawTaxonomies)) {
             const taxonomyLocation: PathSegment[] = ['taxonomies', key];
             if (!['tag', 'author'].includes(key)) {
-                throw validationError(formatLocation(taxonomyLocation), 'Unknown taxonomy. Please use tag or author.');
+                throw validationError(formatLocation(taxonomyLocation), 'Unknown taxonomy. Please use tag or author.', {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_TAXONOMY});
             }
             if (!value) {
-                throw validationError(formatLocation(taxonomyLocation), `Please define a taxonomy permalink route, e.g. ${key}: /${key}/{slug}/.`);
+                throw validationError(formatLocation(taxonomyLocation), `Please define a taxonomy permalink route, e.g. ${key}: /${key}/{slug}/.`, {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK});
             }
-            validatePath(value, taxonomyLocation, `/${key}/{slug}/`);
+            validatePath(value, taxonomyLocation, `/${key}/{slug}/`, {code: ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK});
             if (key === 'tag') {
                 taxonomies.tag = value;
             }

package/core/server/services/route-settings/validation-errors.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTE_SETTINGS_ERROR_CODES = void 0;
 exports.formatLocation = formatLocation;
 exports.describeValue = describeValue;
 exports.humanList = humanList;
@@ -15,6 +16,37 @@ const messages = {
 };
 const DOCS_URL = 'https://ghost.org/docs/themes/routing/';
 const MAX_SHOWN_LENGTH = 40;
+/**
+ * Stable, machine-readable codes describing the class of a routes.yaml failure.
+ *
+ * The human-readable message is authored for the person editing the file and is
+ * free to change; the code is the contract a caller can branch on. Every
+ * validation error carries one — the default is the generic
+ * `INVALID_ROUTE_SETTINGS`.
+ *
+ * Codes name the *kind* of thing that is wrong, independent of which section it
+ * was found in, so a caller can branch on the failure class without also
+ * knowing whether it came from a route, a collection or a taxonomy:
+ *
+ * - `INVALID_ROUTE_SETTINGS` — the overall document/section shape is wrong (the
+ *   schema rejected it); also the default for anything not otherwise classified.
+ * - `INVALID_PATH` — a mount path key (a `routes:`/`collections:` key) is malformed.
+ * - `INVALID_PERMALINK` — a permalink value is missing or malformed, wherever it
+ *   appears (a collection `permalink` or a taxonomy permalink).
+ * - `INVALID_TAXONOMY` — the taxonomy itself is not one Ghost supports (not tag/author).
+ * - `INVALID_TEMPLATE` — a route/collection has no template, data or content type.
+ * - `INVALID_RESOURCE` — a data entry names an unsupported resource.
+ * - `INVALID_DATA` — a data definition's shape is otherwise invalid.
+ */
+exports.ROUTE_SETTINGS_ERROR_CODES = {
+    INVALID_ROUTE_SETTINGS: 'INVALID_ROUTE_SETTINGS',
+    INVALID_PATH: 'INVALID_PATH',
+    INVALID_PERMALINK: 'INVALID_PERMALINK',
+    INVALID_TAXONOMY: 'INVALID_TAXONOMY',
+    INVALID_TEMPLATE: 'INVALID_TEMPLATE',
+    INVALID_RESOURCE: 'INVALID_RESOURCE',
+    INVALID_DATA: 'INVALID_DATA'
+};
 /**
  * Renders the path to the offending value the way an author would find it in
  * their file, e.g. `routes['/about/'].template[1]`.
@@ -140,6 +172,33 @@ function describeExpectation(path) {
     const expectation = lookup(FIELD_EXPECTATIONS, fieldKey(path));
     return expectation ? { subject: String(fieldKey(path)), expectation } : null;
 }
+/**
+ * Codes that follow from the key a schema failure landed on, so a failure the
+ * schema catches is classified the same as the equivalent one caught by hand.
+ *
+ * Without this, which code an author gets depends on how they happened to write
+ * the mistake: `permalink: ""` is caught by an explicit check and coded
+ * `INVALID_PERMALINK`, while `permalink:` (empty in YAML, so `null`) and
+ * `permalink: 42` are rejected by the schema one step earlier and would fall
+ * back to the generic code. The empty form is the common one, so the most
+ * frequent permalink mistake would be the one carrying the least useful code.
+ */
+const FIELD_CODES = {
+    permalink: exports.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK
+};
+/**
+ * The code implied by `path`, or undefined when the key implies nothing more
+ * specific than "the schema rejected it".
+ */
+function codeForPath(path) {
+    // A taxonomy's value *is* its permalink, so the key is the taxonomy name
+    // (`taxonomies.tag`) rather than a `permalink` field.
+    if (path.length === 2 && path[0] === 'taxonomies') {
+        return exports.ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK;
+    }
+    const key = fieldKey(path);
+    return typeof key === 'string' && Object.prototype.hasOwnProperty.call(FIELD_CODES, key) ? FIELD_CODES[key] : undefined;
+}
 function valueAtPath(value, path) {
     return path.reduce((current, segment) => {
         if (current === null || typeof current !== 'object') {
@@ -148,9 +207,10 @@ function valueAtPath(value, path) {
         return current[segment];
     }, value);
 }
-function validationError(at, reason, help) {
+function validationError(at, reason, { help, code = exports.ROUTE_SETTINGS_ERROR_CODES.INVALID_ROUTE_SETTINGS } = {}) {
     return new errors_1.default.ValidationError({
         message: (0, tpl_1.default)(messages.validationError, { at, reason }),
+        code,
         ...(help ? { help } : {})
     });
 }
@@ -162,17 +222,21 @@ function validationError(at, reason, help) {
  * @param error  the schema failure
  * @param basePath path of the value that was handed to the schema
  * @param value  that same value, used to describe what the author wrote
+ * @param code   forces the code; omit to infer it from the failing key, which
+ *               is what callers covering a whole section (a route, a
+ *               collection) want — the failure could be about any field in it.
  */
-function toValidationError(error, basePath = [], value) {
+function toValidationError(error, basePath = [], value, code) {
     const issue = error.issues[0];
     const issuePath = issue.path;
     const path = [...basePath, ...issuePath];
+    const resolvedCode = code ?? codeForPath(path) ?? exports.ROUTE_SETTINGS_ERROR_CODES.INVALID_ROUTE_SETTINGS;
     const expectation = describeExpectation(path);
     if (!expectation) {
-        return validationError(formatLocation(path), issue.message, DOCS_URL);
+        return validationError(formatLocation(path), issue.message, { help: DOCS_URL, code: resolvedCode });
     }
     const provided = valueAtPath(value, issuePath);
     const listProblem = Array.isArray(provided) ? lookup(LIST_ENTRY_PROBLEMS, fieldKey(path)) : undefined;
     const found = listProblem ?? `${describeValue(provided)} was provided`;
-    return validationError(formatLocation(path), `${expectation.subject} must be ${expectation.expectation}, but ${found}.`, DOCS_URL);
+    return validationError(formatLocation(path), `${expectation.subject} must be ${expectation.expectation}, but ${found}.`, { help: DOCS_URL, code: resolvedCode });
 }

package/core/server/services/route-settings/validation-errors.ts

@@ -11,6 +11,40 @@ const MAX_SHOWN_LENGTH = 40;
 
 export type PathSegment = string | number;
 
+/**
+ * Stable, machine-readable codes describing the class of a routes.yaml failure.
+ *
+ * The human-readable message is authored for the person editing the file and is
+ * free to change; the code is the contract a caller can branch on. Every
+ * validation error carries one — the default is the generic
+ * `INVALID_ROUTE_SETTINGS`.
+ *
+ * Codes name the *kind* of thing that is wrong, independent of which section it
+ * was found in, so a caller can branch on the failure class without also
+ * knowing whether it came from a route, a collection or a taxonomy:
+ *
+ * - `INVALID_ROUTE_SETTINGS` — the overall document/section shape is wrong (the
+ *   schema rejected it); also the default for anything not otherwise classified.
+ * - `INVALID_PATH` — a mount path key (a `routes:`/`collections:` key) is malformed.
+ * - `INVALID_PERMALINK` — a permalink value is missing or malformed, wherever it
+ *   appears (a collection `permalink` or a taxonomy permalink).
+ * - `INVALID_TAXONOMY` — the taxonomy itself is not one Ghost supports (not tag/author).
+ * - `INVALID_TEMPLATE` — a route/collection has no template, data or content type.
+ * - `INVALID_RESOURCE` — a data entry names an unsupported resource.
+ * - `INVALID_DATA` — a data definition's shape is otherwise invalid.
+ */
+export const ROUTE_SETTINGS_ERROR_CODES = {
+    INVALID_ROUTE_SETTINGS: 'INVALID_ROUTE_SETTINGS',
+    INVALID_PATH: 'INVALID_PATH',
+    INVALID_PERMALINK: 'INVALID_PERMALINK',
+    INVALID_TAXONOMY: 'INVALID_TAXONOMY',
+    INVALID_TEMPLATE: 'INVALID_TEMPLATE',
+    INVALID_RESOURCE: 'INVALID_RESOURCE',
+    INVALID_DATA: 'INVALID_DATA'
+} as const;
+
+export type RouteSettingsErrorCode = typeof ROUTE_SETTINGS_ERROR_CODES[keyof typeof ROUTE_SETTINGS_ERROR_CODES];
+
 /**
  * Renders the path to the offending value the way an author would find it in
  * their file, e.g. `routes['/about/'].template[1]`.
@@ -153,6 +187,37 @@ function describeExpectation(path: readonly PathSegment[]): {subject: string, ex
     return expectation ? {subject: String(fieldKey(path)), expectation} : null;
 }
 
+/**
+ * Codes that follow from the key a schema failure landed on, so a failure the
+ * schema catches is classified the same as the equivalent one caught by hand.
+ *
+ * Without this, which code an author gets depends on how they happened to write
+ * the mistake: `permalink: ""` is caught by an explicit check and coded
+ * `INVALID_PERMALINK`, while `permalink:` (empty in YAML, so `null`) and
+ * `permalink: 42` are rejected by the schema one step earlier and would fall
+ * back to the generic code. The empty form is the common one, so the most
+ * frequent permalink mistake would be the one carrying the least useful code.
+ */
+const FIELD_CODES: Record<string, RouteSettingsErrorCode> = {
+    permalink: ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK
+};
+
+/**
+ * The code implied by `path`, or undefined when the key implies nothing more
+ * specific than "the schema rejected it".
+ */
+function codeForPath(path: readonly PathSegment[]): RouteSettingsErrorCode | undefined {
+    // A taxonomy's value *is* its permalink, so the key is the taxonomy name
+    // (`taxonomies.tag`) rather than a `permalink` field.
+    if (path.length === 2 && path[0] === 'taxonomies') {
+        return ROUTE_SETTINGS_ERROR_CODES.INVALID_PERMALINK;
+    }
+
+    const key = fieldKey(path);
+
+    return typeof key === 'string' && Object.prototype.hasOwnProperty.call(FIELD_CODES, key) ? FIELD_CODES[key] : undefined;
+}
+
 function valueAtPath(value: unknown, path: readonly PathSegment[]): unknown {
     return path.reduce<unknown>((current, segment) => {
         if (current === null || typeof current !== 'object') {
@@ -162,9 +227,14 @@ function valueAtPath(value: unknown, path: readonly PathSegment[]): unknown {
     }, value);
 }
 
-export function validationError(at: string, reason: string, help?: string): errors.ValidationError {
+export function validationError(
+    at: string,
+    reason: string,
+    {help, code = ROUTE_SETTINGS_ERROR_CODES.INVALID_ROUTE_SETTINGS}: {help?: string, code?: RouteSettingsErrorCode} = {}
+): errors.ValidationError {
     return new errors.ValidationError({
         message: tpl(messages.validationError, {at, reason}),
+        code,
         ...(help ? {help} : {})
     });
 }
@@ -177,20 +247,25 @@ export function validationError(at: string, reason: string, help?: string): erro
  * @param error  the schema failure
  * @param basePath path of the value that was handed to the schema
  * @param value  that same value, used to describe what the author wrote
+ * @param code   forces the code; omit to infer it from the failing key, which
+ *               is what callers covering a whole section (a route, a
+ *               collection) want — the failure could be about any field in it.
  */
-export function toValidationError(error: z.ZodError, basePath: readonly PathSegment[] = [], value?: unknown): errors.ValidationError {
+export function toValidationError(error: z.ZodError, basePath: readonly PathSegment[] = [], value?: unknown, code?: RouteSettingsErrorCode): errors.ValidationError {
     const issue = error.issues[0];
     const issuePath = issue.path as PathSegment[];
     const path = [...basePath, ...issuePath];
 
+    const resolvedCode = code ?? codeForPath(path) ?? ROUTE_SETTINGS_ERROR_CODES.INVALID_ROUTE_SETTINGS;
+
     const expectation = describeExpectation(path);
     if (!expectation) {
-        return validationError(formatLocation(path), issue.message, DOCS_URL);
+        return validationError(formatLocation(path), issue.message, {help: DOCS_URL, code: resolvedCode});
     }
 
     const provided = valueAtPath(value, issuePath);
     const listProblem = Array.isArray(provided) ? lookup(LIST_ENTRY_PROBLEMS, fieldKey(path)) : undefined;
     const found = listProblem ?? `${describeValue(provided)} was provided`;
 
-    return validationError(formatLocation(path), `${expectation.subject} must be ${expectation.expectation}, but ${found}.`, DOCS_URL);
+    return validationError(formatLocation(path), `${expectation.subject} must be ${expectation.expectation}, but ${found}.`, {help: DOCS_URL, code: resolvedCode});
 }

package/core/server/services/stats/posts-stats-service.js

@@ -399,29 +399,33 @@ class PostsStatsService {
 
     async getGrowthStatsForPost(postId) {
         try {
-            const freeMembers = await this.knex('members_created_events as mce')
-                .countDistinct('mce.member_id as free_members')
-                .leftJoin('members_subscription_created_events as msce', function () {
-                    this.on('mce.member_id', '=', 'msce.member_id')
-                        .andOn('mce.attribution_id', '=', 'msce.attribution_id');
-                })
-                .where('mce.attribution_id', postId)
-                .whereIn('mce.attribution_type', ['post', 'page'])
-                .where('msce.id', null);
-
-            const paidMembers = await this.knex('members_subscription_created_events as msce')
-                .countDistinct('msce.member_id as paid_members')
-                .where('msce.attribution_id', postId)
-                .whereIn('msce.attribution_type', ['post', 'page']);
-
-            const mrr = await this.knex('members_subscription_created_events as msce')
-                .sum('mpse.mrr_delta as mrr')
-                .join('members_paid_subscription_events as mpse', function () {
-                    this.on('mpse.subscription_id', '=', 'msce.subscription_id');
-                    this.andOn('mpse.member_id', '=', 'msce.member_id');
-                })
-                .where('msce.attribution_id', postId)
-                .whereIn('msce.attribution_type', ['post', 'page']);
+            // The three aggregates only depend on postId, so run them together:
+            // the wait becomes the slowest query instead of the sum of all three.
+            const [freeMembers, paidMembers, mrr] = await Promise.all([
+                this.knex('members_created_events as mce')
+                    .countDistinct('mce.member_id as free_members')
+                    .leftJoin('members_subscription_created_events as msce', function () {
+                        this.on('mce.member_id', '=', 'msce.member_id')
+                            .andOn('mce.attribution_id', '=', 'msce.attribution_id');
+                    })
+                    .where('mce.attribution_id', postId)
+                    .whereIn('mce.attribution_type', ['post', 'page'])
+                    .where('msce.id', null),
+
+                this.knex('members_subscription_created_events as msce')
+                    .countDistinct('msce.member_id as paid_members')
+                    .where('msce.attribution_id', postId)
+                    .whereIn('msce.attribution_type', ['post', 'page']),
+
+                this.knex('members_subscription_created_events as msce')
+                    .sum('mpse.mrr_delta as mrr')
+                    .join('members_paid_subscription_events as mpse', function () {
+                        this.on('mpse.subscription_id', '=', 'msce.subscription_id');
+                        this.andOn('mpse.member_id', '=', 'msce.member_id');
+                    })
+                    .where('msce.attribution_id', postId)
+                    .whereIn('msce.attribution_type', ['post', 'page'])
+            ]);
 
             return {
                 data: [

package/core/server/services/stripe/services/webhook/charge-refunded-event-service.js

@@ -50,7 +50,7 @@ module.exports = class ChargeRefundedEventService {
      * @private
      */
     async handleGiftRefundEvent(paymentIntentId) {
-        const refunded = await this.deps.giftService.refund(paymentIntentId);
+        const refunded = await this.deps.giftService.handlePaymentRefund({paymentIntentId});
 
         if (!refunded) {
             logging.info(`charge.refunded: no gift found for payment_intent ${paymentIntentId}, skipping`);