@bobbykim/manguito-cms-api 0.4.3 → 0.5.0

package/dist/index.js

@@ -30,6 +30,93 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/field-keys.ts
+function isColumnBacked(field) {
+  const col = field.db_column;
+  if (col === null) return false;
+  if (col.column_name === "") return false;
+  if (col.junction) return false;
+  return true;
+}
+function buildFieldKeyMap(pairs, allLabels, droppedKeys) {
+  const labelToColumn = /* @__PURE__ */ new Map();
+  const columnToLabel = /* @__PURE__ */ new Map();
+  for (const { label, column } of pairs) {
+    labelToColumn.set(label, column);
+    columnToLabel.set(column, label);
+  }
+  for (const label of allLabels) {
+    const columnOwner = columnToLabel.get(label);
+    if (columnOwner !== void 0 && columnOwner !== label) {
+      throw new Error(
+        `Fatal: field key map failed to build \u2014 field label "${label}" collides with the storage column of field "${columnOwner}". A field label may not reuse another field's column name. Rename the field, then run \`manguito validate\` to check your schema.`
+      );
+    }
+  }
+  for (const label of labelToColumn.keys()) {
+    if (droppedKeys.has(label)) labelToColumn.delete(label);
+  }
+  for (const column of columnToLabel.keys()) {
+    if (droppedKeys.has(column)) columnToLabel.delete(column);
+  }
+  const diverges = [...labelToColumn].some(([label, column]) => label !== column);
+  function remap(input, lookup) {
+    const out = {};
+    for (const key of Object.keys(input)) {
+      if (droppedKeys.has(key)) continue;
+      out[lookup.get(key) ?? key] = input[key];
+    }
+    return out;
+  }
+  return {
+    toStorage: (input) => remap(input, labelToColumn),
+    toLabels: (row) => remap(row, columnToLabel),
+    columnFor: (label) => labelToColumn.get(label),
+    labelFor: (column) => columnToLabel.get(column),
+    labels: [...labelToColumn.keys()],
+    diverges
+  };
+}
+function createFieldKeyMap(fields) {
+  const droppedKeys = /* @__PURE__ */ new Set();
+  const pairs = [];
+  for (const f of fields) {
+    if (!isColumnBacked(f)) continue;
+    pairs.push({ label: f.name, column: f.db_column.column_name });
+    if (f.removed === true) {
+      droppedKeys.add(f.name);
+      droppedKeys.add(f.db_column.column_name);
+    }
+  }
+  return buildFieldKeyMap(
+    pairs,
+    fields.map((f) => f.name),
+    droppedKeys
+  );
+}
+function createFieldKeyMapFromProjection(projectionType, allFields) {
+  const pairs = projectionType.fields.map((f) => ({ label: f.exposed_as, column: f.column_name }));
+  const projected = new Set(pairs.map((p) => p.label));
+  const dropped = /* @__PURE__ */ new Set();
+  for (const f of allFields) {
+    if (!isColumnBacked(f)) continue;
+    dropped.add(f.name);
+    dropped.add(f.db_column.column_name);
+  }
+  for (const p of pairs) dropped.delete(p.column);
+  for (const label of projected) dropped.delete(label);
+  return buildFieldKeyMap(
+    pairs,
+    allFields.map((f) => f.name),
+    dropped
+  );
+}
+var init_field_keys = __esm({
+  "src/field-keys.ts"() {
+    "use strict";
+  }
+});
+
 // src/relations.ts
 function quoteIdent(name) {
   if (!/^[a-z][a-z0-9_-]*$/.test(name)) throw new Error(`Unsafe identifier: ${name}`);
@@ -333,65 +420,6 @@ var init_relations = __esm({
   }
 });
 
-// src/field-keys.ts
-function isColumnBacked(field) {
-  const col = field.db_column;
-  if (col === null) return false;
-  if (col.column_name === "") return false;
-  if (col.junction) return false;
-  return true;
-}
-function createFieldKeyMap(fields) {
-  const labelToColumn = /* @__PURE__ */ new Map();
-  const columnToLabel = /* @__PURE__ */ new Map();
-  const droppedKeys = /* @__PURE__ */ new Set();
-  for (const f of fields) {
-    if (!isColumnBacked(f)) continue;
-    columnToLabel.set(f.db_column.column_name, f.name);
-    if (f.removed === true) {
-      droppedKeys.add(f.name);
-      droppedKeys.add(f.db_column.column_name);
-      continue;
-    }
-    labelToColumn.set(f.name, f.db_column.column_name);
-  }
-  for (const f of fields) {
-    const columnOwner = columnToLabel.get(f.name);
-    if (columnOwner !== void 0 && columnOwner !== f.name) {
-      throw new Error(
-        `Fatal: field key map failed to build \u2014 field label "${f.name}" collides with the storage column of field "${columnOwner}". A field label may not reuse another field's column name. Rename the field, then run \`manguito validate\` to check your schema.`
-      );
-    }
-  }
-  for (const f of fields) {
-    if (isColumnBacked(f) && f.removed === true) {
-      columnToLabel.delete(f.db_column.column_name);
-    }
-  }
-  const diverges = [...labelToColumn].some(([label, column]) => label !== column);
-  function remap(input, lookup) {
-    const out = {};
-    for (const key of Object.keys(input)) {
-      if (droppedKeys.has(key)) continue;
-      out[lookup.get(key) ?? key] = input[key];
-    }
-    return out;
-  }
-  return {
-    toStorage: (input) => remap(input, labelToColumn),
-    toLabels: (row) => remap(row, columnToLabel),
-    columnFor: (label) => labelToColumn.get(label),
-    labelFor: (column) => columnToLabel.get(column),
-    labels: [...labelToColumn.keys()],
-    diverges
-  };
-}
-var init_field_keys = __esm({
-  "src/field-keys.ts"() {
-    "use strict";
-  }
-});
-
 // src/graphql/scalars.ts
 var import_graphql, DateTimeScalar, JSONScalar;
 var init_scalars = __esm({
@@ -1069,15 +1097,20 @@ function normalizePrefix(prefix) {
 }
 function createPublicPaths(prefix) {
   return {
-    collection: (basePath) => `${prefix}/${basePath}`,
-    item: (basePath) => `${prefix}/${basePath}/:slug`,
-    taxonomyCollection: (typeName) => `${prefix}/taxonomy/${typeName}`,
-    taxonomyItem: (typeName) => `${prefix}/taxonomy/${typeName}/:id`,
     mediaCollection: () => `${prefix}/media`,
     mediaItem: () => `${prefix}/media/:id`,
     openapi: () => `${prefix}/openapi.json`
   };
 }
+function createVersionedPaths(prefix, version) {
+  const root = version === null ? prefix : `${prefix}/${version}`;
+  return {
+    collection: (basePath) => `${root}/${basePath}`,
+    item: (basePath) => `${root}/${basePath}/:slug`,
+    taxonomyCollection: (typeName) => `${root}/taxonomy/${typeName}`,
+    taxonomyItem: (typeName) => `${root}/taxonomy/${typeName}/:id`
+  };
+}
 
 // src/app.ts
 var import_hono = require("hono");
@@ -1673,7 +1706,7 @@ function nestedTargets(fields) {
   }
   return out;
 }
-function buildProjectors(registry, fieldKeyMaps) {
+function buildProjectors(registry, fieldKeyMaps, fallbacks) {
   const projectors = {};
   const sources = [
     registry.content_types,
@@ -1684,7 +1717,14 @@ function buildProjectors(registry, fieldKeyMaps) {
     for (const [typeName, type] of Object.entries(source)) {
       const map = fieldKeyMaps[typeName];
       if (!map) continue;
-      projectors[typeName] = { map, nested: nestedTargets(type.fields) };
+      const typeFallbacks = fallbacks?.[typeName];
+      projectors[typeName] = {
+        map,
+        nested: nestedTargets(type.fields),
+        // Spread rather than assign: with exactOptionalPropertyTypes, an optional
+        // property may be ABSENT but not present-and-undefined.
+        ...typeFallbacks !== void 0 && { fallbacks: typeFallbacks }
+      };
     }
   }
   return projectors;
@@ -1693,6 +1733,11 @@ function projectRow(row, typeName, projectors) {
   const p = projectors[typeName];
   if (!p) return row;
   const out = p.map.toLabels(row);
+  if (p.fallbacks !== void 0) {
+    for (const [label, value] of Object.entries(p.fallbacks)) {
+      if (out[label] === null || out[label] === void 0) out[label] = value;
+    }
+  }
   for (const { label, target } of p.nested) {
     const v = out[label];
     if (v === null || v === void 0) continue;
@@ -1705,6 +1750,9 @@ function projectRow(row, typeName, projectors) {
   return out;
 }
 
+// src/routes/content.ts
+init_field_keys();
+
 // src/routes/query-params.ts
 var SORTABLE_FIELDS = /* @__PURE__ */ new Set(["title", "created_at", "updated_at"]);
 var RELATION_FIELD_TYPES = /* @__PURE__ */ new Set([
@@ -1786,13 +1834,24 @@ function registerPublicContentRoutes(app, registry, repos, projectors, paths, li
     const basePath = contentType.default_base_path;
     const repo = repos[typeName];
     if (!repo) continue;
-    const relationFieldNames = new Set(
-      contentType.fields.filter((f) => RELATION_FIELD_TYPES.has(f.field_type)).map((f) => f.name)
-    );
+    const fieldKeys = projectors[typeName].map;
+    const relationFieldNames = /* @__PURE__ */ new Set();
+    for (const f of contentType.fields) {
+      if (!RELATION_FIELD_TYPES.has(f.field_type)) continue;
+      if (isColumnBacked(f)) {
+        const label = fieldKeys.labelFor(f.db_column.column_name);
+        if (label !== void 0) relationFieldNames.add(label);
+      } else {
+        relationFieldNames.add(f.name);
+      }
+    }
     const filterableFieldNames = /* @__PURE__ */ new Set([
-      ...contentType.fields.filter((f) => f.field_type !== "programmatic").map((f) => f.name),
+      ...fieldKeys.labels,
       ...contentType.system_fields.map((f) => f.name)
     ]);
+    const sortableFieldNames = new Set(
+      [...SORTABLE_FIELDS].filter((f) => filterableFieldNames.has(f))
+    );
     if (contentType.only_one) {
       app.get(paths.collection(basePath), async (c) => {
         const result = await repo.findMany({ published_only: true, page: 1, per_page: 1 });
@@ -1808,8 +1867,6 @@ function registerPublicContentRoutes(app, registry, repos, projectors, paths, li
       });
     } else {
       registerListRoute(paths.collection(basePath), async (c) => {
-        const projector = projectors[typeName];
-        const fieldKeys = projector.map;
         const pagination = parsePagination(c.req.query("page"), c.req.query("per_page"));
         if (!pagination.ok) {
           return c.json(
@@ -1824,13 +1881,13 @@ function registerPublicContentRoutes(app, registry, repos, projectors, paths, li
           );
         }
         const sortBy = c.req.query("sort_by") ?? "created_at";
-        if (!SORTABLE_FIELDS.has(sortBy)) {
+        if (!sortableFieldNames.has(sortBy)) {
           return c.json(
             {
               ok: false,
               error: {
                 code: "INVALID_SORT_FIELD",
-                message: `'${sortBy}' is not sortable. Allowed: title, created_at, updated_at`
+                message: `'${sortBy}' is not sortable. Allowed: ${[...sortableFieldNames].join(", ")}`
               }
             },
             400
@@ -1877,7 +1934,7 @@ function registerPublicContentRoutes(app, registry, repos, projectors, paths, li
             );
           }
         }
-        const sortColumn = fieldKeys.columnFor(sortBy) ?? sortBy;
+        const sortColumn = fieldKeys.labels.includes(sortBy) ? fieldKeys.columnFor(sortBy) : sortBy;
         const result = await repo.findMany({
           published_only: true,
           page: pagination.page,
@@ -3759,7 +3816,7 @@ function registerUserRoutes(app, db, requirePermission, requireHierarchy) {
 var import_drizzle_orm6 = require("drizzle-orm");
 var API_VERSION = (() => {
   try {
-    return "0.4.3";
+    return "0.5.0";
   } catch {
     return "0.0.0";
   }
@@ -4166,6 +4223,95 @@ function createMediaRepository(db) {
 
 // src/app.ts
 init_field_keys();
+
+// src/versions.ts
+init_field_keys();
+var VERSION_SEGMENT = /^v\d+$/;
+function versionNumber(version) {
+  return Number.parseInt(version.slice(1), 10);
+}
+function classifyVersion(segment, model) {
+  if (!VERSION_SEGMENT.test(segment)) return "not-a-version";
+  if (model.live.includes(segment)) return "live";
+  return versionNumber(segment) < versionNumber(model.current) ? "retired" : "unknown";
+}
+function fallbacksFor(projection) {
+  const out = {};
+  for (const [typeName, type] of Object.entries(projection.types)) {
+    const perLabel = {};
+    for (const f of type.fields) {
+      if (f.fallback !== void 0) perLabel[f.exposed_as] = f.fallback;
+    }
+    if (Object.keys(perLabel).length > 0) out[typeName] = perLabel;
+  }
+  return out;
+}
+function buildVersionSurface(input) {
+  const { version, projectionVersion, prefix, registry, model, makeRepo } = input;
+  const paths = createVersionedPaths(prefix, version);
+  const projection = model.projections[projectionVersion];
+  const fieldKeyMaps = {};
+  const sources = [
+    registry.content_types,
+    registry.taxonomy_types,
+    registry.paragraph_types
+  ];
+  for (const source of sources) {
+    for (const [typeName, type] of Object.entries(source)) {
+      const projectionType = projection?.types[typeName];
+      fieldKeyMaps[typeName] = projectionType ? createFieldKeyMapFromProjection(projectionType, type.fields) : createFieldKeyMap(type.fields);
+    }
+  }
+  const fallbacks = projection ? fallbacksFor(projection) : void 0;
+  const projectors = buildProjectors(registry, fieldKeyMaps, fallbacks);
+  const sortableColumnsFor = (typeName) => {
+    const map = fieldKeyMaps[typeName];
+    const type = registry.content_types[typeName] ?? registry.taxonomy_types[typeName];
+    const systemFieldNames = new Set((type?.system_fields ?? []).map((f) => f.name));
+    const out = /* @__PURE__ */ new Set();
+    for (const label of SORTABLE_FIELDS) {
+      const column = map.columnFor(label);
+      if (column !== void 0) out.add(column);
+      else if (systemFieldNames.has(label)) out.add(label);
+    }
+    return out;
+  };
+  const repos = {};
+  for (const [typeName, ct] of Object.entries(registry.content_types)) {
+    repos[typeName] = makeRepo(typeName, ct.db.table_name, sortableColumnsFor(typeName));
+  }
+  for (const [typeName, tt] of Object.entries(registry.taxonomy_types)) {
+    repos[typeName] = makeRepo(typeName, tt.db.table_name, sortableColumnsFor(typeName));
+  }
+  return { paths, fieldKeyMaps, projectors, repos };
+}
+function deprecationHeaders(input) {
+  const { requested, model, successor } = input;
+  const link = `<${successor}>; rel="successor-version"`;
+  if (requested === null) {
+    if (model.live.length <= 1) return null;
+    return {
+      Deprecation: "true",
+      Link: link,
+      Warning: `299 - "Unversioned path resolves to the latest version (${model.current}) and will change when a new version is cut. Pin a version."`
+    };
+  }
+  if (requested === model.current) return null;
+  return { Deprecation: "true", Link: link };
+}
+
+// src/app.ts
+function versionRoutePaths(registry, paths) {
+  const out = [paths.collection("content"), paths.collection("taxonomy")];
+  for (const ct of Object.values(registry.content_types)) {
+    out.push(paths.collection(ct.default_base_path));
+    if (!ct.only_one) out.push(paths.item(ct.default_base_path));
+  }
+  for (const tt of Object.values(registry.taxonomy_types)) {
+    out.push(paths.taxonomyCollection(tt.name), paths.taxonomyItem(tt.name));
+  }
+  return out;
+}
 var MISSING_STORAGE_ERROR = `\u2717 api.storage is required but not configured.
   Add a storage adapter to your manguito.config.ts:
 
@@ -4181,6 +4327,7 @@ function createCmsApp(options) {
   }
   const prefix = normalizePrefix(options.prefix);
   const publicPaths = createPublicPaths(prefix);
+  const versionedPaths = createVersionedPaths(prefix, null);
   const { storage, registry, db, rateLimit, media, cors } = options;
   const cmsName = options.name ?? "Manguito CMS";
   const maxFileSize = media?.max_file_size;
@@ -4229,9 +4376,18 @@ function createCmsApp(options) {
     ])
   ]);
   const projectors = buildProjectors(registry, fieldKeyMaps);
-  const sortableColumnsFor = (typeName) => new Set(
-    [...SORTABLE_FIELDS].map((label) => fieldKeyMaps[typeName].columnFor(label) ?? label)
-  );
+  const sortableColumnsFor = (typeName) => {
+    const map = fieldKeyMaps[typeName];
+    const type = registry.content_types[typeName] ?? registry.taxonomy_types[typeName];
+    const systemFieldNames = new Set((type?.system_fields ?? []).map((f) => f.name));
+    const out = /* @__PURE__ */ new Set();
+    for (const label of SORTABLE_FIELDS) {
+      const column = map.columnFor(label);
+      if (column !== void 0) out.add(column);
+      else if (systemFieldNames.has(label)) out.add(label);
+    }
+    return out;
+  };
   const contentRepos = Object.fromEntries(
     Object.entries(registry.content_types).map(([typeName, ct]) => [
       typeName,
@@ -4250,27 +4406,14 @@ function createCmsApp(options) {
   );
   const repos = { ...contentRepos, ...taxonomyRepos };
   const mediaRepo = createMediaRepository(db);
-  const publicContentRepos = Object.fromEntries(
-    Object.entries(registry.content_types).map(([typeName, ct]) => [
-      typeName,
-      createDrizzleContentRepository(db, ct.db.table_name, {
-        relations: buildRelationsMap(ct.fields, registry),
-        publishedRelations: true,
-        sortableColumns: sortableColumnsFor(typeName)
-      })
-    ])
-  );
-  const publicTaxonomyRepos = Object.fromEntries(
-    Object.entries(registry.taxonomy_types).map(([typeName, tt]) => [
-      typeName,
-      createDrizzleContentRepository(db, tt.db.table_name, {
-        relations: buildRelationsMap(tt.fields, registry),
-        publishedRelations: true,
-        sortableColumns: sortableColumnsFor(typeName)
-      })
-    ])
-  );
-  const publicRepos = { ...publicContentRepos, ...publicTaxonomyRepos };
+  const makeRepo = (typeName, tableName, sortableColumns) => {
+    const type = registry.content_types[typeName] ?? registry.taxonomy_types[typeName];
+    return createDrizzleContentRepository(db, tableName, {
+      relations: buildRelationsMap(type.fields, registry),
+      publishedRelations: true,
+      sortableColumns
+    });
+  };
   const graphqlRepos = Object.fromEntries([
     ...Object.entries(registry.content_types).map(([typeName, ct]) => [
       typeName,
@@ -4293,17 +4436,17 @@ function createCmsApp(options) {
     for (const ct of Object.values(registry.content_types)) {
       const base = ct.default_base_path;
       if (ct.only_one) {
-        paths[publicPaths.collection(base)] = { get: { summary: `Get ${ct.label}`, tags: [ct.label] } };
+        paths[versionedPaths.collection(base)] = { get: { summary: `Get ${ct.label}`, tags: [ct.label] } };
       } else {
-        paths[publicPaths.collection(base)] = { get: { summary: `List published ${ct.label}`, tags: [ct.label] } };
-        paths[publicPaths.item(base).replace(":slug", "{slug}")] = {
+        paths[versionedPaths.collection(base)] = { get: { summary: `List published ${ct.label}`, tags: [ct.label] } };
+        paths[versionedPaths.item(base).replace(":slug", "{slug}")] = {
           get: { summary: `Get ${ct.label} by slug`, tags: [ct.label] }
         };
       }
     }
     for (const tt of Object.values(registry.taxonomy_types)) {
-      paths[publicPaths.taxonomyCollection(tt.name)] = { get: { summary: `List published ${tt.label}`, tags: [tt.label] } };
-      paths[publicPaths.taxonomyItem(tt.name).replace(":id", "{id}")] = {
+      paths[versionedPaths.taxonomyCollection(tt.name)] = { get: { summary: `List published ${tt.label}`, tags: [tt.label] } };
+      paths[versionedPaths.taxonomyItem(tt.name).replace(":id", "{id}")] = {
         get: { summary: `Get ${tt.label} by id`, tags: [tt.label] }
       };
     }
@@ -4323,7 +4466,62 @@ function createCmsApp(options) {
       paths: {}
     })
   );
-  registerPublicContentRoutes(app, registry, publicRepos, projectors, publicPaths, listRateLimit, programmaticResolver);
+  const model = options.versions ?? {
+    current: "v1",
+    live: ["v1"],
+    projections: {}
+  };
+  const passes = [
+    ...options.versions !== void 0 ? model.live.map((v) => ({ version: v, projectionVersion: v })) : [],
+    { version: null, projectionVersion: model.current }
+  ];
+  for (const pass of passes) {
+    const surface = buildVersionSurface({ ...pass, prefix, registry, model, makeRepo });
+    const headers = deprecationHeaders({
+      requested: pass.version,
+      model,
+      // The version root, with no trailing slash — never
+      // createVersionedPaths(prefix, model.current).collection(''), which
+      // would yield `${prefix}/${model.current}/` in every Link header.
+      successor: `${prefix}/${model.current}`
+    });
+    if (headers !== null) {
+      const attachDeprecationHeaders = async (c, next) => {
+        await next();
+        for (const [key, value] of Object.entries(headers)) c.res.headers.set(key, value);
+      };
+      for (const path of versionRoutePaths(registry, surface.paths)) {
+        app.use(path, attachDeprecationHeaders);
+      }
+    }
+    registerPublicContentRoutes(app, registry, surface.repos, surface.projectors, surface.paths, listRateLimit, programmaticResolver);
+  }
+  if (options.versions !== void 0) {
+    app.all(`${prefix}/:version/*`, async (c, next) => {
+      const kind = classifyVersion(c.req.param("version"), model);
+      if (kind === "not-a-version" || kind === "live") return next();
+      const live = model.live.join(", ");
+      return kind === "retired" ? c.json(
+        {
+          ok: false,
+          error: {
+            code: "VERSION_RETIRED",
+            message: `Version ${c.req.param("version")} is no longer served. Live versions: ${live}.`
+          }
+        },
+        410
+      ) : c.json(
+        {
+          ok: false,
+          error: {
+            code: "VERSION_NOT_FOUND",
+            message: `No version ${c.req.param("version")} is served. Live versions: ${live}.`
+          }
+        },
+        404
+      );
+    });
+  }
   registerPublicMediaRoutes(app, mediaRepo, publicPaths, listRateLimit);
   if (options.graphql?.enabled) {
     const gqlOptions = options.graphql;