@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/lib/marketing-params.ts

@@ -0,0 +1,213 @@
+/**
+ * The marketing signals a landing URL carries (#1596).
+ *
+ * A shopper arriving from an ad brings the entire attribution story in the
+ * query string and nowhere else: the platform's CLICK ID identifies that exact
+ * click to the platform's conversion API, and the UTM tags say which campaign
+ * paid for it. Both are gone the moment the visitor reaches a second page — no
+ * cookie, no header and no backend record carries them — so they are read on
+ * landing or they are lost.
+ *
+ * This module only READS them. It turns a query string into what it found;
+ * WHERE those values go — the identity mutation for the click IDs, the track
+ * event for the UTM tags — is the caller's decision, taken somewhere that has a
+ * session and can talk to the backend. Keeping the two apart is what lets the
+ * reading rules be a table of vectors rather than a browser scenario.
+ *
+ * PURE by construction, and that is a requirement rather than a preference: it
+ * imports nothing, touches no browser global and reads no environment. This
+ * template tree sits outside the repository's lint, typecheck and test graph
+ * (`eslint.config.mts` ignores it, `package/cli/tsconfig.lib.json` excludes it)
+ * and is copied verbatim into every merchant's store, so
+ * `tool/storefront-template-spec` — which imports modules like this one by
+ * relative path — is the only thing standing between this file and production.
+ * A module that stops being pure stops being testable from there, which is an
+ * alarm rather than an inconvenience.
+ */
+
+/** A captured click ID, shaped for the backend's `MarketingIdentifierInput`. */
+export interface MarketingIdentifier {
+  /** The registered identifier key this value is stored under. */
+  key: string;
+  /** The click ID exactly as the ad platform wrote it into the URL. */
+  value: string;
+}
+
+/**
+ * The captured UTM tags, shaped to be spread straight into `TrackEventInput`.
+ *
+ * Every field is optional and an absent tag is OMITTED rather than set to an
+ * empty string, because those are different claims: the backend treats a
+ * present `''` as a blank dimension and writes it to ClickHouse, where it can
+ * no longer be told apart from a campaign that genuinely has no medium.
+ */
+export interface UtmParams {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}
+
+/**
+ * What a landing URL turned out to carry.
+ *
+ * A discriminated union rather than a pair of possibly-empty collections,
+ * because "this visitor came from an ad" and "this visitor typed the address"
+ * are different situations and the second is by far the common one. The union
+ * makes the empty case impossible to walk past: nothing can reach `identifiers`
+ * or `utm` without answering the question first, so a visitor with no query
+ * parameters produces exactly the tracking behaviour that existed before this
+ * module — no extra request, no blank row.
+ *
+ * The `captured` arm carries at least one signal, though not necessarily both:
+ * an ad link with a click ID and no tags yields an empty `utm`, and a
+ * hand-written newsletter link yields empty `identifiers`. A caller skips the
+ * empty side rather than sending it.
+ */
+export type MarketingParams =
+  | { kind: 'none' }
+  | { kind: 'captured'; identifiers: readonly MarketingIdentifier[]; utm: UtmParams };
+
+/** One click ID: what the platform appends, and what we store it as. */
+interface ClickIdParam {
+  /** The parameter name an ad platform writes into the landing URL. */
+  readonly param: string;
+  /** The backend identifier key it is stored under. */
+  readonly key: string;
+}
+
+/** One UTM tag: the URL parameter, and the field it becomes. */
+interface UtmParam {
+  readonly param: string;
+  readonly field: keyof UtmParams;
+}
+
+/**
+ * The click IDs this storefront captures.
+ *
+ * Each `key` is byte-identical to one the backend pre-registers, in
+ * `package/core/src/marketing-identity/marketing-identity.module.ts:85`, and
+ * that exactness is load-bearing: the shop mutation looks the key up and
+ * REJECTS an unknown one — reporting it in `rejected` rather than failing — so
+ * a single typo here loses the attribution silently, behind a response that
+ * still looks accepted.
+ *
+ * Three of the six registered click IDs appear below. The other three
+ * (`msclkid`, `liClickId`, `impact_click_id`) are registered backend-side, but
+ * an identifier's KEY and its URL-parameter spelling are two separate facts,
+ * and for those three they are not the same string — two are not even
+ * URL-shaped. Guessing the missing spellings would buy nothing and could cost
+ * real data: a guess that never matches is dead code, and a guess that happens
+ * to match another platform's parameter writes a foreign click's value into a
+ * real shopper's identity. Capturing one of them later is one row here, which
+ * is why the two spellings are held apart even where they coincide.
+ */
+const CLICK_ID_PARAMS: readonly ClickIdParam[] = [
+  { param: 'gclid', key: 'gclid' },
+  { param: 'fbclid', key: 'fbclid' },
+  { param: 'ttclid', key: 'ttclid' },
+];
+
+/**
+ * All five UTM tags, not the three everyone names.
+ *
+ * `utm_term` and `utm_content` are the two dropped as an afterthought, and
+ * dropping them here would be a pure loss for zero saving: the chain downstream
+ * already carries five, from `TrackEventInput` through the relay's allowlist in
+ * `src/app/__fc/track/route.ts` to the ClickHouse columns and the
+ * `MarketingTouchpoint` row. They are also what tells two ads in one ad group
+ * apart, which is the granularity a merchant actually optimises at.
+ */
+const UTM_PARAMS: readonly UtmParam[] = [
+  { param: 'utm_source', field: 'utmSource' },
+  { param: 'utm_medium', field: 'utmMedium' },
+  { param: 'utm_campaign', field: 'utmCampaign' },
+  { param: 'utm_term', field: 'utmTerm' },
+  { param: 'utm_content', field: 'utmContent' },
+];
+
+/**
+ * Unicode control characters (C0, DEL, C1), stripped from every value.
+ *
+ * The same expression the server applies in
+ * `package/core/src/marketing-event/service/marketing-event.service.ts:38`.
+ * Repeating it here is not belt-and-braces — it is what keeps the value SENT
+ * identical to the value STORED, so the two can never be reported differently.
+ */
+const CONTROL_CHARS_REGEX = /\p{Cc}/gu;
+
+/**
+ * The cap the server applies to every UTM value (that same service, line 39),
+ * mirrored here so a tag cannot change shape in transit. These land in
+ * `LowCardinality(String)` ClickHouse columns, where the cap is what stops
+ * client garbage from inflating the column dictionary; truncating at the same
+ * boundary means the campaign name a merchant reads in a report is the one this
+ * module sent.
+ */
+export const UTM_VALUE_MAX_LENGTH = 128;
+
+/**
+ * The cap for a click ID — deliberately NOT the UTM one.
+ *
+ * There is nothing to mirror here: an identifier value lands in an unbounded
+ * `varchar` and the identity path validates the KEY while storing the value
+ * exactly as given, so this bound is a garbage fence rather than a truncation
+ * the server would reproduce. It therefore has to sit well clear of every real
+ * click ID: Meta's `fbclid` routinely runs past 128 characters, and a click ID
+ * short by even one character matches nothing at the platform that issued it.
+ * That failure is silent — the conversion simply never attributes — and
+ * preventing it is the reason this module exists.
+ */
+export const CLICK_ID_VALUE_MAX_LENGTH = 512;
+
+/**
+ * Read the marketing signals out of a landing URL's query string.
+ *
+ * Accepts the string with or without its leading `?`, so `window.location.
+ * search` and a hand-built query read alike. Never throws: this runs on the
+ * first render of every page a visitor can land on, and an unreadable query is
+ * a reason to capture nothing, never a reason to fail the page the shopper came
+ * for.
+ *
+ * A repeated parameter keeps its FIRST occurrence. `?gclid=a&gclid=b` has no
+ * honest reading — one of the two belongs to somebody else's click — and the
+ * first is the one the ad platform appended before any later redirect had the
+ * chance to add its own.
+ */
+export function parseMarketingParams(search: string): MarketingParams {
+  const params = new URLSearchParams(search);
+
+  const identifiers: MarketingIdentifier[] = [];
+  for (const { param, key } of CLICK_ID_PARAMS) {
+    const value = sanitize(params.get(param), CLICK_ID_VALUE_MAX_LENGTH);
+    if (value === undefined) continue;
+    identifiers.push({ key, value });
+  }
+
+  const utm: UtmParams = {};
+  for (const { param, field } of UTM_PARAMS) {
+    const value = sanitize(params.get(param), UTM_VALUE_MAX_LENGTH);
+    if (value === undefined) continue;
+    utm[field] = value;
+  }
+
+  if (identifiers.length === 0 && Object.keys(utm).length === 0) return { kind: 'none' };
+  return { kind: 'captured', identifiers, utm };
+}
+
+/**
+ * Clean one raw parameter value, or report it absent.
+ *
+ * The order matters and matches the server's `sanitizeLowCardinalityValue`
+ * (`marketing-event.service.ts:343`): strip control characters, trim, drop what
+ * remains if it is empty, and only then cap. Capping first would let trailing
+ * whitespace eat the budget, and treating a blank as present would send
+ * `?utm_source=` upstream as a campaign whose source is the empty string.
+ */
+function sanitize(raw: string | null, maxLength: number): string | undefined {
+  if (raw === null) return undefined;
+  const stripped = raw.replace(CONTROL_CHARS_REGEX, '').trim();
+  if (stripped.length === 0) return undefined;
+  return stripped.slice(0, maxLength);
+}

package/templates/storefront-shadcn/src/lib/money.ts

@@ -0,0 +1,50 @@
+/**
+ * Minor-unit money arithmetic — the one place the ISO-4217 exponent is decided.
+ *
+ * ForgeCart prices are integers in the currency's smallest denomination, and
+ * the divisor is NOT always a hundred: 2500 is $25.00 (two-decimal cents) but
+ * ¥2,500 (zero-decimal yen) and BHD 2.500 (three-decimal fils). A hardcoded
+ * hundred is therefore wrong for real currencies, silently, and only for
+ * merchants outside the two-decimal world.
+ *
+ * It lives here rather than inside the price formatter because there are now
+ * two consumers with different output: the shopper-facing string
+ * (`lib/format.ts`) and the machine-readable `Offer.price` a crawler reads
+ * (`lib/seo/json-ld.ts`). Those two disagreeing about what 2500 means would
+ * publish one price to people and another to search engines — a discrepancy
+ * that reads as deceptive pricing, and one nothing in the template would
+ * report. One derivation, two consumers, no room to drift.
+ *
+ * Pure by construction — no SDK types, no `next` — so it is a table of vectors
+ * rather than something only a rendered page can exercise.
+ */
+
+/**
+ * The currency's fraction digits, from the same CLDR data that renders it.
+ *
+ * Derived rather than tabulated: a hand-maintained exponent table is a second
+ * source of truth that goes stale silently. The fallback of 2 covers a
+ * formatter that resolves no digits at all (an unknown code), which is the
+ * only case CLDR cannot answer.
+ */
+export function currencyExponent(currency: string): number {
+  const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency });
+  return formatter.resolvedOptions().maximumFractionDigits ?? 2;
+}
+
+/** A minor-unit integer as its major-unit value — 2500 USD → 25, 2500 JPY → 2500. */
+export function toMajorUnits(minorUnits: number, currency: string): number {
+  return minorUnits / 10 ** currencyExponent(currency);
+}
+
+/**
+ * A minor-unit integer as the decimal string schema.org wants for a price.
+ *
+ * Fixed to the currency's own digit count, deliberately: `25` and `25.00` are
+ * the same number but not the same claim to a price parser, and a
+ * zero-decimal currency must not acquire cents it does not have.
+ */
+export function toPriceString(minorUnits: number, currency: string): string {
+  const exponent = currencyExponent(currency);
+  return (minorUnits / 10 ** exponent).toFixed(exponent);
+}

package/templates/storefront-shadcn/src/lib/seo/alternates.ts

@@ -0,0 +1,123 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+
+/**
+ * Self-canonical + reciprocal hreflang (#1347, epic launch#54 W1-9).
+ *
+ * PURE, with no env read of its own: the origin arrives as a parameter and the
+ * only caller is `metadata.ts`, which composes these claims together with the
+ * title, the robots directive and the social card. Routes do not call in here
+ * directly — five separate claims about one address, assembled separately, can
+ * disagree in ways nothing in the template would notice.
+ *
+ * Two claims, and both are claims about OTHER URLs, which is what makes them
+ * dangerous to derive loosely:
+ *
+ *  - the canonical says "this content lives at exactly this address", which
+ *    tells a crawler to collapse every other URL that serves it;
+ *  - each hreflang says "the same content exists, in that language, over
+ *    there" — and search engines require reciprocity, so an alternate pointing
+ *    at a page that does not point back is discarded, taking the whole cluster's
+ *    credibility with it.
+ *
+ * Reciprocity is therefore achieved BY CONSTRUCTION rather than by asserting
+ * it: every locale in the set is rendered from the same `pathsByLocale` map, so
+ * each page in a cluster emits an identical alternate set. Two pages built from
+ * one map cannot disagree.
+ */
+
+/** Unprefixed path per language that genuinely HAS this content. */
+export type PathsByLocale = Readonly<Record<string, string>>;
+
+export interface AlternatesInput {
+  /** The locale this page is being rendered in. */
+  binding: LocaleBinding;
+  /**
+   * Every language with real content, mapped to its own unprefixed path.
+   *
+   * Membership is the ONLY thing that decides which alternates are emitted:
+   * a language a merchant has not translated must never appear, or the cluster
+   * advertises a page that answers a fallback copy.
+   */
+  pathsByLocale: PathsByLocale;
+  /** The deployment's public origin, or null when it has none. */
+  publicOrigin: string | null;
+}
+
+/** What a page declares about its own address and its siblings. */
+export interface Alternates {
+  canonical: string;
+  languages: Record<string, string>;
+}
+
+/**
+ * The alternates for this page, or undefined when it must not make the claim.
+ *
+ * Undefined in exactly one case: this locale is not in `pathsByLocale`, which
+ * means the shopper is looking at a derived fallback copy. Such a page has no
+ * address of its own to be canonical about, and pointing hreflang at the
+ * languages that DO have the content would invite a crawler to treat the
+ * fallback as part of a reciprocal set it is not a member of. Asserting
+ * nothing is the honest answer — the same posture the preview deployment takes.
+ */
+export function buildAlternates({
+  binding,
+  pathsByLocale,
+  publicOrigin,
+}: AlternatesInput): Alternates | undefined {
+  const ownPath = pathsByLocale[binding.locale];
+  if (ownPath === undefined) return undefined;
+
+  const languages: Record<string, string> = {};
+  for (const [languageCode, path] of Object.entries(pathsByLocale)) {
+    languages[languageCode] = absolute(
+      localizedPath(path, { locale: languageCode, defaultLocale: binding.defaultLocale }),
+      publicOrigin,
+    );
+  }
+
+  // `x-default` names where an unmatched visitor should land, and the channel's
+  // default language is the only defensible answer — it is the copy served
+  // unprefixed. Emitted only when that language actually has the content:
+  // pointing x-default at a page that does not exist is worse than omitting it.
+  const defaultPath = pathsByLocale[binding.defaultLocale];
+  if (defaultPath !== undefined) {
+    languages['x-default'] = absolute(
+      localizedPath(defaultPath, { locale: binding.defaultLocale, defaultLocale: binding.defaultLocale }),
+      publicOrigin,
+    );
+  }
+
+  return { canonical: absolute(localizedPath(ownPath, binding), publicOrigin), languages };
+}
+
+/**
+ * The path map for a route that exists in EVERY language — the home page, the
+ * catalog, and any page a merchant scaffolds.
+ *
+ * Structural routes are not translated content: `/products` is the same route
+ * in every cluster, so every offered language has it and each one is a genuine
+ * alternate. That is the opposite of a product, where membership has to be
+ * earned per language (see `productPathsByLocale`). An ACF page sits between
+ * the two: its route is this same address in every language, but its content
+ * is translated, so the map is narrowed by the page's sidecar before it is
+ * advertised (`advertisedPathsByLocale`, #1375).
+ */
+export function staticPathsByLocale(
+  languageCodes: readonly string[],
+  path: string,
+): Record<string, string> {
+  return Object.fromEntries(languageCodes.map((languageCode) => [languageCode, path]));
+}
+
+/**
+ * Absolute against the public origin, relative without one.
+ *
+ * A relative canonical is valid and resolves against the document's own URL, so
+ * it stays truthful on a preview host — where an absolute URL would either name
+ * an origin we do not have or invent one. Those pages are noindex anyway
+ * (`noindex.ts`), so this is belt and braces rather than the primary defence.
+ */
+function absolute(path: string, publicOrigin: string | null): string {
+  return publicOrigin === null ? path : `${publicOrigin}${path}`;
+}

package/templates/storefront-shadcn/src/lib/seo/json-ld.ts

@@ -0,0 +1,266 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+import { toPriceString } from '../money';
+
+/**
+ * Structured data (#1347, epic launch#54 W1-9) — entity data only, ever.
+ *
+ * JSON-LD is where a storefront is most tempted to assert things it cannot
+ * know. `Organization` wants a legal name, a logo and `sameAs` social
+ * profiles; `WebSite` wants a `SearchAction` sitelinks searchbox. None of that
+ * is derivable from a product row — a template emitting it would be inventing
+ * facts about a real business, and an unearned `SearchAction` is a claim about
+ * a search endpoint that may not exist. Those types are refused **at the type
+ * level** rather than by review: {@link JsonLdNode} is a closed union, so an
+ * `Organization` node does not compile, and no amount of later editing can
+ * reintroduce one without deleting this sentence first.
+ *
+ * Everything here is pure — no `next`, no SDK types — so the shapes are a
+ * table of vectors instead of something only a rendered page could exercise.
+ * Inputs are declared structurally for the same reason.
+ */
+
+/** The only context this template speaks. */
+type SchemaContext = 'https://schema.org';
+
+/** schema.org availability, spelled as the full IRIs Google expects. */
+export const IN_STOCK = 'https://schema.org/InStock';
+export const OUT_OF_STOCK = 'https://schema.org/OutOfStock';
+
+export interface OfferNode {
+  '@type': 'Offer';
+  /** A decimal string in the currency's own digits — never a formatted price. */
+  price: string;
+  priceCurrency: string;
+  availability: typeof IN_STOCK | typeof OUT_OF_STOCK;
+  sku?: string;
+  url: string;
+}
+
+export interface ProductNode {
+  '@context': SchemaContext;
+  '@type': 'Product';
+  name: string;
+  description?: string;
+  image?: string;
+  sku?: string;
+  /** The page's canonical — the same URL its `<link rel="canonical">` claims. */
+  url: string;
+  offers: OfferNode[];
+}
+
+export interface ListItemNode {
+  '@type': 'ListItem';
+  position: number;
+  name: string;
+  /** Absent on the last crumb: it IS this page, and a self-link adds nothing. */
+  item?: string;
+}
+
+export interface BreadcrumbListNode {
+  '@context': SchemaContext;
+  '@type': 'BreadcrumbList';
+  itemListElement: ListItemNode[];
+}
+
+export interface PersonNode {
+  '@type': 'Person';
+  name: string;
+}
+
+/**
+ * A blog post, as the #1347 allowlist admits it (#1992): every field is entity
+ * data the post's own record carries — its name, its dek, its stamps and its
+ * cover — and nothing about the business publishing it.
+ */
+export interface BlogPostingNode {
+  '@context': SchemaContext;
+  '@type': 'BlogPosting';
+  headline: string;
+  description?: string;
+  /** Absolute, or absent: a crawler reads a relative image as no image at all. */
+  image?: string;
+  /** ISO-8601, as the shop API stamps the post's `createdAt` / `updatedAt`. */
+  datePublished: string;
+  dateModified: string;
+  /** The page's canonical — the same URL its `<link rel="canonical">` claims. */
+  url: string;
+  author?: PersonNode;
+}
+
+/**
+ * The allowlist, as a type.
+ *
+ * `Organization`, `WebSite`, `SearchAction`, `logo` and `sameAs` are absent by
+ * construction — not filtered at runtime, which would be a check someone can
+ * disable, but unrepresentable. `BlogPosting` joined with #1992 for #1041's
+ * content routes, which have a post record behind every node; the promote
+ * verifier judges each node's SHAPE under `SEO_SCHEMA_BLOGPOSTING_INVALID`.
+ */
+export type JsonLdNode = ProductNode | BreadcrumbListNode | BlogPostingNode;
+
+/** One variant, as much of it as structured data has any business knowing. */
+export interface OfferableVariant {
+  sku?: string | null;
+  priceWithTax: number;
+  currencyCode: string;
+  stockOnHand: number;
+  enabled: boolean;
+}
+
+export interface ProductJsonLdInput {
+  name: string;
+  description?: string | null;
+  image?: string | null;
+  canonical: string;
+  variants: readonly OfferableVariant[];
+}
+
+/**
+ * The `Product` node for a product page.
+ *
+ * `url` is the CANONICAL, not the requested address: structured data that
+ * named a redirecting or query-bearing URL would compete with the page's own
+ * canonical for the same content, which is the duplicate-content bug the
+ * canonical exists to prevent.
+ *
+ * Disabled variants are not offered. An offer is a statement that something
+ * can be bought, and a disabled variant cannot be.
+ */
+export function productJsonLd({
+  name,
+  description,
+  image,
+  canonical,
+  variants,
+}: ProductJsonLdInput): ProductNode {
+  const offers = variants
+    .filter((variant) => variant.enabled)
+    .map(
+      (variant): OfferNode => ({
+        '@type': 'Offer',
+        price: toPriceString(variant.priceWithTax, variant.currencyCode),
+        priceCurrency: variant.currencyCode,
+        availability: variant.stockOnHand > 0 ? IN_STOCK : OUT_OF_STOCK,
+        ...(variant.sku ? { sku: variant.sku } : {}),
+        url: canonical,
+      }),
+    );
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name,
+    // Omitted rather than emitted empty: an absent field is "not stated", an
+    // empty one is a stated blank, and only the first is true here.
+    ...(description ? { description } : {}),
+    ...(image ? { image } : {}),
+    url: canonical,
+    offers,
+  };
+}
+
+export interface BreadcrumbInput {
+  binding: LocaleBinding;
+  publicOrigin: string;
+  /** The trail's leaf — this page, named but not linked. */
+  leafName: string;
+  /** The structural ancestors, unprefixed; the locale is applied here. */
+  trail: readonly { name: string; path: string }[];
+}
+
+/**
+ * The `BreadcrumbList` for a page, locale-aware and absolute.
+ *
+ * The ancestor paths are localized through the same `localizedPath` the visible
+ * breadcrumbs use, so the trail a crawler reads and the trail a shopper clicks
+ * are the same trail — in the same language. A German page whose structured
+ * data pointed at the English catalog would be describing a different site.
+ */
+export function breadcrumbJsonLd({
+  binding,
+  publicOrigin,
+  leafName,
+  trail,
+}: BreadcrumbInput): BreadcrumbListNode {
+  const itemListElement: ListItemNode[] = trail.map(
+    (crumb, index): ListItemNode => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: `${publicOrigin}${localizedPath(crumb.path, binding)}`,
+    }),
+  );
+
+  itemListElement.push({
+    '@type': 'ListItem',
+    position: trail.length + 1,
+    name: leafName,
+  });
+
+  return { '@context': 'https://schema.org', '@type': 'BreadcrumbList', itemListElement };
+}
+
+export interface BlogPostingJsonLdInput {
+  headline: string;
+  description?: string | null;
+  image?: string | null;
+  /** The post's `createdAt` as the shop API stamps it — ISO-8601. */
+  publishedAt: string;
+  /** The post's `updatedAt`, the same way. */
+  updatedAt: string;
+  canonical: string;
+  authorName?: string | null;
+}
+
+/** An `http(s)` URL with an origin — the only image a crawler attaches to a post. */
+const ABSOLUTE_HTTP_URL = /^https?:\/\/\S+$/i;
+
+/**
+ * The `BlogPosting` node for a blog post — the ONE such node a post page emits.
+ *
+ * Every optional field is omitted rather than emitted empty, for the reason
+ * {@link productJsonLd} gives, and the image is omitted unless it is absolute:
+ * a relative `image` is read by a crawler as no image, and by the promote
+ * verifier as a defect (`SEO_SCHEMA_BLOGPOSTING_INVALID`), so emitting it would
+ * turn an undescribed cover into a refused promote. The dates pass through as
+ * the shop API stamped them — already ISO-8601 — because re-parsing a timestamp
+ * to re-print it can only lose precision or throw.
+ */
+export function blogPostingJsonLd({
+  headline,
+  description,
+  image,
+  publishedAt,
+  updatedAt,
+  canonical,
+  authorName,
+}: BlogPostingJsonLdInput): BlogPostingNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline,
+    ...(description ? { description } : {}),
+    ...(image && ABSOLUTE_HTTP_URL.test(image) ? { image } : {}),
+    datePublished: publishedAt,
+    dateModified: updatedAt,
+    url: canonical,
+    ...(authorName ? { author: { '@type': 'Person', name: authorName } } : {}),
+  };
+}
+
+/**
+ * A node as the text of a `<script type="application/ld+json">`.
+ *
+ * `<` becomes its JSON unicode escape, and that single substitution is the
+ * whole escape rule — necessary AND sufficient. Inside a script element only
+ * three sequences change how the parser behaves (`</script`, `<script` and
+ * `<!--`), every one of them begins with `<`, and a JSON parser decodes
+ * `<` straight back to `<`. So a product description containing
+ * `</script>` — rich text from the dashboard, which is exactly where such a
+ * string comes from — cannot close the element early and turn the rest of the
+ * document into markup.
+ */
+export function serializeJsonLd(node: JsonLdNode): string {
+  return JSON.stringify(node).replace(/</g, '\\u003c');
+}