@tokenoftrust/storefront-runner 2.4.73 → 2.4.75

package/packages/cli/src/declared-config.mjs

@@ -17,7 +17,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -30,6 +30,115 @@ export const FEATURE_KEYS = [
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** Every `seo` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SEO_KEYS = Object.freeze(["trailingSlash", "structuredData"]);
+
+/** Every `seo.structuredData` key. */
+export const STRUCTURED_DATA_KEYS = Object.freeze(["graphs", "names", "reviews"]);
+
+/**
+ * The page types a structured-data profile declares a graph for. `productGroup` is a product
+ * with more than one variant; without its own graph it renders the `product` graph.
+ * `collection` covers every archive: a catalog collection, the collections index, and the
+ * blog index and its category/tag/author archives.
+ */
+export const STRUCTURED_DATA_PAGE_TYPES = Object.freeze([
+  "home", "product", "productGroup", "collection", "post", "page",
+]);
+
+/**
+ * The JSON-LD nodes a profile may list, as the `@type` each emits (a multi-type node joins its
+ * sorted types with `+`, the key a parity snapshot records). `Person:author` is the page's
+ * author; every other Organization/Person token is the site entity.
+ */
+export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
+  "Organization", "Person", "Organization+Person",
+  "WebSite", "ImageObject",
+  "WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage",
+  "Person:author",
+  "Article", "BlogPosting",
+  "Product", "ProductGroup",
+  "FAQPage", "BreadcrumbList", "ItemList",
+]);
+
+/** Node types whose `name` a profile may source, and the sources. */
+export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
+export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * What is wrong with a declared `seo` value, one sentence per problem; `[]` when it is valid.
+ * A profile that names a node or page type the renderer does not build is refused whole: a
+ * partly-applied profile emits a graph nobody declared.
+ *
+ * @param {unknown} seo
+ * @returns {string[]}
+ */
+export function seoDeclarationProblems(seo) {
+  if (!isPlainObject(seo)) return ["`seo` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (seo);
+  for (const key of Object.keys(source)) {
+    if (!SEO_KEYS.includes(key)) problems.push(`\`seo.${key}\` is not a seo key (${SEO_KEYS.join(", ")})`);
+  }
+  if (source.trailingSlash !== undefined && typeof source.trailingSlash !== "boolean") {
+    problems.push("`seo.trailingSlash` must be true or false");
+  }
+  const sd = source.structuredData;
+  if (sd === undefined) return problems;
+  if (!isPlainObject(sd)) return [...problems, "`seo.structuredData` must be an object"];
+  const data = /** @type {Record<string, unknown>} */ (sd);
+  for (const key of Object.keys(data)) {
+    if (!STRUCTURED_DATA_KEYS.includes(key)) {
+      problems.push(`\`seo.structuredData.${key}\` is not a structuredData key (${STRUCTURED_DATA_KEYS.join(", ")})`);
+    }
+  }
+  if (!isPlainObject(data.graphs) || Object.keys(/** @type {object} */ (data.graphs)).length === 0) {
+    problems.push("`seo.structuredData.graphs` must map at least one page type to its node list");
+  } else {
+    for (const [pageType, tokens] of Object.entries(/** @type {Record<string, unknown>} */ (data.graphs))) {
+      const at = `seo.structuredData.graphs.${pageType}`;
+      if (!STRUCTURED_DATA_PAGE_TYPES.includes(pageType)) {
+        problems.push(`\`${at}\`: unknown page type (${STRUCTURED_DATA_PAGE_TYPES.join(", ")})`);
+        continue;
+      }
+      if (!Array.isArray(tokens) || tokens.length === 0) {
+        problems.push(`\`${at}\` must be a non-empty array of node types`);
+        continue;
+      }
+      const seen = new Set();
+      for (const token of tokens) {
+        if (typeof token !== "string" || !STRUCTURED_DATA_NODE_TOKENS.includes(token)) {
+          problems.push(`\`${at}\`: ${JSON.stringify(token)} is not a node type the renderer builds (${STRUCTURED_DATA_NODE_TOKENS.join(", ")})`);
+        } else if (seen.has(token)) {
+          problems.push(`\`${at}\` lists ${token} twice`);
+        }
+        seen.add(token);
+      }
+    }
+  }
+  if (data.names !== undefined) {
+    if (!isPlainObject(data.names)) {
+      problems.push("`seo.structuredData.names` must map a node type to documentTitle or title");
+    } else {
+      for (const [type, from] of Object.entries(/** @type {Record<string, unknown>} */ (data.names))) {
+        if (!STRUCTURED_DATA_NAMED_TYPES.includes(type)) {
+          problems.push(`\`seo.structuredData.names.${type}\`: only ${STRUCTURED_DATA_NAMED_TYPES.join(", ")} take a declared name`);
+        } else if (typeof from !== "string" || !STRUCTURED_DATA_NAME_SOURCES.includes(from)) {
+          problems.push(`\`seo.structuredData.names.${type}\` must be one of ${STRUCTURED_DATA_NAME_SOURCES.join(", ")}`);
+        }
+      }
+    }
+  }
+  if (data.reviews !== undefined && typeof data.reviews !== "boolean") {
+    problems.push("`seo.structuredData.reviews` must be true or false");
+  }
+  return problems;
+}
+
+
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
   ruleProfile: "checkout compliance rules",
@@ -361,6 +470,11 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
     out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
   }
+  if (config.seo !== undefined) {
+    for (const problem of seoDeclarationProblems(config.seo)) {
+      out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
+    }
+  }
   return out;
 }
 

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -1,7 +1,7 @@
 /** Types for the dependency-free declared-tenant-config module (declared-tenant-config.mjs). */
 import type { TenantConfig } from "./tenant.js";
 
-export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds";
+export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds" | "seo";
 export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
 
 export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];
@@ -9,6 +9,13 @@ export const TOT_CONFIG_KEYS: readonly string[];
 export const COMPLIANCE_KEYS: readonly string[];
 export const FEATURE_KEYS: readonly string[];
 export const SITE_TYPES_LIST: readonly string[];
+export const SEO_KEYS: readonly string[];
+export const STRUCTURED_DATA_KEYS: readonly string[];
+export const STRUCTURED_DATA_PAGE_TYPES: readonly import("./tenant.js").StructuredDataPageType[];
+export const STRUCTURED_DATA_NODE_TOKENS: readonly import("./tenant.js").StructuredDataNodeToken[];
+export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
+export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
+export function seoDeclarationProblems(seo: unknown): string[];
 export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
 export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;
 export function applyDeclaredTenantConfig<T extends Partial<Pick<TenantConfig, DeclaredTenantConfigField>>>(

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -25,6 +25,7 @@ export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
   "capabilities",
   "features",
   "embeds",
+  "seo",
 ]);
 
 /**
@@ -73,11 +74,116 @@ export const FEATURE_KEYS = Object.freeze([
 /** Every `siteType` value (SiteType, tenant.ts). */
 export const SITE_TYPES_LIST = Object.freeze(["commerce", "marketing"]);
 
+/** Every `seo` key (SeoDeclaration, tenant.ts). */
+export const SEO_KEYS = Object.freeze(["trailingSlash", "structuredData"]);
+
+/** Every `seo.structuredData` key. */
+export const STRUCTURED_DATA_KEYS = Object.freeze(["graphs", "names", "reviews"]);
+
+/**
+ * The page types a structured-data profile declares a graph for. `productGroup` is a product
+ * with more than one variant; without its own graph it renders the `product` graph.
+ * `collection` covers every archive: a catalog collection, the collections index, and the
+ * blog index and its category/tag/author archives.
+ */
+export const STRUCTURED_DATA_PAGE_TYPES = Object.freeze([
+  "home", "product", "productGroup", "collection", "post", "page",
+]);
+
+/**
+ * The JSON-LD nodes a profile may list, as the `@type` each emits (a multi-type node joins its
+ * sorted types with `+`, the key a parity snapshot records). `Person:author` is the page's
+ * author; every other Organization/Person token is the site entity.
+ */
+export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
+  "Organization", "Person", "Organization+Person",
+  "WebSite", "ImageObject",
+  "WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage",
+  "Person:author",
+  "Article", "BlogPosting",
+  "Product", "ProductGroup",
+  "FAQPage", "BreadcrumbList", "ItemList",
+]);
+
+/** Node types whose `name` a profile may source, and the sources. */
+export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
+export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
+
 const SITE_TYPES = new Set(SITE_TYPES_LIST);
 
 const isPlainObject = (value) =>
   value !== null && typeof value === "object" && !Array.isArray(value);
 
+/**
+ * What is wrong with a declared `seo` value, one sentence per problem; `[]` when it is valid.
+ * A profile that names a node or page type the renderer does not build is refused whole: a
+ * partly-applied profile emits a graph nobody declared.
+ *
+ * @param {unknown} seo
+ * @returns {string[]}
+ */
+export function seoDeclarationProblems(seo) {
+  if (!isPlainObject(seo)) return ["`seo` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (seo);
+  for (const key of Object.keys(source)) {
+    if (!SEO_KEYS.includes(key)) problems.push(`\`seo.${key}\` is not a seo key (${SEO_KEYS.join(", ")})`);
+  }
+  if (source.trailingSlash !== undefined && typeof source.trailingSlash !== "boolean") {
+    problems.push("`seo.trailingSlash` must be true or false");
+  }
+  const sd = source.structuredData;
+  if (sd === undefined) return problems;
+  if (!isPlainObject(sd)) return [...problems, "`seo.structuredData` must be an object"];
+  const data = /** @type {Record<string, unknown>} */ (sd);
+  for (const key of Object.keys(data)) {
+    if (!STRUCTURED_DATA_KEYS.includes(key)) {
+      problems.push(`\`seo.structuredData.${key}\` is not a structuredData key (${STRUCTURED_DATA_KEYS.join(", ")})`);
+    }
+  }
+  if (!isPlainObject(data.graphs) || Object.keys(/** @type {object} */ (data.graphs)).length === 0) {
+    problems.push("`seo.structuredData.graphs` must map at least one page type to its node list");
+  } else {
+    for (const [pageType, tokens] of Object.entries(/** @type {Record<string, unknown>} */ (data.graphs))) {
+      const at = `seo.structuredData.graphs.${pageType}`;
+      if (!STRUCTURED_DATA_PAGE_TYPES.includes(pageType)) {
+        problems.push(`\`${at}\`: unknown page type (${STRUCTURED_DATA_PAGE_TYPES.join(", ")})`);
+        continue;
+      }
+      if (!Array.isArray(tokens) || tokens.length === 0) {
+        problems.push(`\`${at}\` must be a non-empty array of node types`);
+        continue;
+      }
+      const seen = new Set();
+      for (const token of tokens) {
+        if (typeof token !== "string" || !STRUCTURED_DATA_NODE_TOKENS.includes(token)) {
+          problems.push(`\`${at}\`: ${JSON.stringify(token)} is not a node type the renderer builds (${STRUCTURED_DATA_NODE_TOKENS.join(", ")})`);
+        } else if (seen.has(token)) {
+          problems.push(`\`${at}\` lists ${token} twice`);
+        }
+        seen.add(token);
+      }
+    }
+  }
+  if (data.names !== undefined) {
+    if (!isPlainObject(data.names)) {
+      problems.push("`seo.structuredData.names` must map a node type to documentTitle or title");
+    } else {
+      for (const [type, from] of Object.entries(/** @type {Record<string, unknown>} */ (data.names))) {
+        if (!STRUCTURED_DATA_NAMED_TYPES.includes(type)) {
+          problems.push(`\`seo.structuredData.names.${type}\`: only ${STRUCTURED_DATA_NAMED_TYPES.join(", ")} take a declared name`);
+        } else if (typeof from !== "string" || !STRUCTURED_DATA_NAME_SOURCES.includes(from)) {
+          problems.push(`\`seo.structuredData.names.${type}\` must be one of ${STRUCTURED_DATA_NAME_SOURCES.join(", ")}`);
+        }
+      }
+    }
+  }
+  if (data.reviews !== undefined && typeof data.reviews !== "boolean") {
+    problems.push("`seo.structuredData.reviews` must be true or false");
+  }
+  return problems;
+}
+
 /**
  * The declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
  * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
@@ -88,7 +194,7 @@ export function declaredTenantConfig(config) {
   /** @type {Record<string, unknown>} */
   const out = {};
   if (!isPlainObject(config)) return out;
-  const { displayName, siteType, compliance, capabilities, features, embeds } = /** @type {Record<string, unknown>} */ (config);
+  const { displayName, siteType, compliance, capabilities, features, embeds, seo } = /** @type {Record<string, unknown>} */ (config);
   // The store's name as visitors read it: the `<title>` suffix, og:site_name,
   // Organization JSON-LD, breadcrumbs, the default blog heading, the copyright line.
   if (typeof displayName === "string" && displayName.trim()) out.displayName = displayName.trim();
@@ -97,6 +203,8 @@ export function declaredTenantConfig(config) {
   if (isPlainObject(capabilities)) out.capabilities = capabilities;
   if (isPlainObject(features)) out.features = features;
   if (Array.isArray(embeds) && embeds.every((slug) => typeof slug === "string")) out.embeds = embeds;
+  // URL form and the structured-data profile: refused whole when any part is malformed.
+  if (seo !== undefined && seoDeclarationProblems(seo).length === 0) out.seo = seo;
   return out;
 }
 

package/packages/public-runtime/src/tenant.ts

@@ -750,6 +750,46 @@ export interface TenantConfig {
    * `none` are ever set. It reaches the browser through the server-stamped plan.
    */
   euUkVisitors?: Exclude<EuUkVisitorPolicy, "count-only">;
+  /**
+   * URL form and structured data, declared in `.tot/config.json` (validated by
+   * `seoDeclarationProblems`, declared-tenant-config.mjs). A migrated store keeps the
+   * canonical URL shape and the JSON-LD graph its rankings were earned under.
+   */
+  seo?: SeoDeclaration;
+}
+
+/** Page types a structured-data profile declares a graph for (STRUCTURED_DATA_PAGE_TYPES). */
+export type StructuredDataPageType = "home" | "product" | "productGroup" | "collection" | "post" | "page";
+
+/** JSON-LD nodes a profile may list (STRUCTURED_DATA_NODE_TOKENS). */
+export type StructuredDataNodeToken =
+  | "Organization" | "Person" | "Organization+Person"
+  | "WebSite" | "ImageObject"
+  | "WebPage" | "ItemPage" | "CollectionPage" | "AboutPage" | "ContactPage"
+  | "Person:author"
+  | "Article" | "BlogPosting"
+  | "Product" | "ProductGroup"
+  | "FAQPage" | "BreadcrumbList" | "ItemList";
+
+export interface SeoDeclaration {
+  /**
+   * Canonicals, og:url, JSON-LD urls, sitemap locs and platform-generated page links end in
+   * `/` (`/products/foo/`). Absent or false ⇒ no trailing slash (`/products/foo`).
+   */
+  trailingSlash?: boolean;
+  /**
+   * The structured-data profile. When present it is the ONLY JSON-LD a declared page type
+   * emits: one `@graph` holding exactly the listed nodes, in order. A node whose data the
+   * page lacks (no image, no author, no FAQ) is omitted. A page type without a graph keeps
+   * the platform default.
+   */
+  structuredData?: {
+    graphs: Partial<Record<StructuredDataPageType, StructuredDataNodeToken[]>>;
+    /** Where a node's `name` comes from: the page's `<title>` or the entity's own title. */
+    names?: Partial<Record<"Product" | "ProductGroup" | "Article" | "BlogPosting", "documentTitle" | "title">>;
+    /** Emit real sourced aggregateRating/review on Product. Absent ⇒ false. */
+    reviews?: boolean;
+  };
 }
 
 /**