@occluze/tether 0.6.6 → 0.6.8

package/src/shopify-values.js

@@ -0,0 +1,89 @@
+/**
+ * Conversions of Shopify values that the browser script and the server helpers (`src/server.js`, `src/astro.js`)
+ * share, so a server-rendered page and the script that takes it over agree. Pure: no config, no DOM.
+ */
+
+/** @typedef {{ amount: string, currencyCode: string }} Money A Storefront API `MoneyV2`. */
+
+/** The `.env` names a store's domain and public Storefront token are read from, first match wins. */
+export const STORE_ENV_NAMES = {
+  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
+  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
+};
+
+/**
+ * True for an absolute https URL. Links and redirects that come from Shopify (checkout, status pages,
+ * tracking) are only used when this holds.
+ *
+ * @param {unknown} url
+ */
+export function isHttpsUrl(url) {
+  if (typeof url !== 'string') return false;
+  try {
+    return new URL(url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True for a token Shopify issues as a secret (`shpat_` Admin, `shpss_` shared secret, `shpca_` client credentials,
+ * `shppa_` private app, `shpua_` user). The public Storefront token has no such prefix. A secret token must never
+ * reach a page.
+ *
+ * @param {string} token
+ */
+export function isSecretShopifyToken(token) {
+  return /^shp[a-z]{2}_/.test(token.trim());
+}
+
+/**
+ * Money as text in `locale`, e.g. `{ amount: '30.0', currencyCode: 'EUR' }` in `nl-NL` → `€ 30,00`.
+ *
+ * @param {Money | null | undefined} money
+ * @param {string | undefined} locale An `Intl` locale; the runtime's own when absent.
+ * @returns {string} `''` without money or with an amount that isn't a number.
+ */
+export function formatMoney(money, locale) {
+  if (!money) return '';
+  const amount = parseFloat(money.amount);
+  if (Number.isNaN(amount)) return '';
+  try {
+    return new Intl.NumberFormat(locale || undefined, { style: 'currency', currency: money.currencyCode }).format(
+      amount,
+    );
+  } catch {
+    // A currency code Intl doesn't know.
+    return `${money.currencyCode} ${amount.toFixed(2)}`;
+  }
+}
+
+/**
+ * A product page's path. `productPath` is a folder (`/product` → `/product/<handle>`) or a template with `{handle}`
+ * and `{id}` (the numeric product id), e.g. `/product?handle={handle}`.
+ *
+ * @param {string} productPath
+ * @param {string | null | undefined} handle
+ * @param {string | null | undefined} [id] A product gid or numeric id.
+ */
+export function productUrl(productPath, handle, id) {
+  if (!/\{(handle|id)\}/.test(productPath)) return `${productPath.replace(/\/$/, '')}/${handle ?? String(handle)}`;
+  const numericId = id ? (id.split('/').pop() ?? '') : '';
+  return productPath
+    .replace(/\{handle\}/g, encodeURIComponent(handle ?? ''))
+    .replace(/\{id\}/g, encodeURIComponent(numericId));
+}
+
+/**
+ * The key Tether loads a product by: a handle, or a product gid.
+ *
+ * @param {string | number | null | undefined} raw A handle, a numeric id, a gid or a product URL (`…/products/<handle>`).
+ * @returns {string | null}
+ */
+export function productKey(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) return null;
+  if (value.startsWith('gid://')) return value;
+  if (/^\d+$/.test(value)) return `gid://shopify/Product/${value}`;
+  return /\/products\/([^/?#]+)/.exec(value)?.[1] ?? value;
+}

package/src/status.js

@@ -1,66 +1,126 @@
 /**
- * Where a product scope gets its key from, and the loading / ready / error /
- * not-found state of a scope (so a failing API never leaves a broken page).
+ * Where a product scope gets its key from, and the state of a scope (loading, ready, error, not found), so a failing
+ * API never leaves a broken page.
  */
 import { attr, sel, get, scoped, show } from './dom.js';
 
 /**
- * tether-product values:
- *   "coffee-box"          handle, numeric id, gid or product URL (as before)
- *   "url:handle"          ?handle=... from the page URL (any param name: "url:p" -> ?p=)
- *   "url:path"            the last segment of the page path (/shop/coffee-box -> coffee-box)
- * Returns { key, fromUrl, raw }. key is null when the URL has no value.
+ * @typedef {object} ProductKeySource
+ * @property {string | null} key The product to load; `null` when the attribute or the page URL has none.
+ * @property {boolean} fromUrl The key comes from the page URL (`url:…`).
+ * @property {string} raw The attribute's value as written.
+ */
+
+/** @typedef {'loading' | 'ready' | 'error' | 'not-found'} ScopeStatus */
+
+const URL_SOURCE = 'url:';
+
+/**
+ * A path segment as text. A malformed escape (`%E0%A4%A`) is kept as written, which is how the browser shows it.
+ *
+ * @param {string} segment
+ */
+function decodePathSegment(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch (error) {
+    if (error instanceof URIError) return segment;
+    throw error;
+  }
+}
+
+/**
+ * Reads a `tether-product` value:
+ * - `coffee-box`: a handle, numeric id, gid or product URL;
+ * - `url:handle`: `?handle=` from the page URL (any parameter: `url:p` reads `?p=`);
+ * - `url:path`: the last segment of the page path (`/shop/coffee-box` → `coffee-box`).
+ *
+ * @param {Element} el
+ * @param {Pick<Location, 'pathname' | 'search'>} [location]
+ * @param {string} [name] The attribute, without prefix.
+ * @returns {ProductKeySource}
  */
 export function resolveProductKey(el, location = window.location, name = 'product') {
-  const raw = (get(el, name) || '').trim();
-  if (!raw.toLowerCase().startsWith('url:')) return { key: raw || null, fromUrl: false, raw };
-  const what = raw.slice(4).trim();
-  let key = null;
-  if (what.toLowerCase() === 'path') {
-    const parts = location.pathname.split('/').filter(Boolean);
-    key = parts.length ? safeDecode(parts[parts.length - 1]) : null;
+  const raw = (get(el, name) ?? '').trim();
+  if (!raw.toLowerCase().startsWith(URL_SOURCE)) return { key: raw || null, fromUrl: false, raw };
+  const source = raw.slice(URL_SOURCE.length).trim();
+  let key;
+  if (source.toLowerCase() === 'path') {
+    const segments = location.pathname.split('/').filter(Boolean);
+    const segment = segments[segments.length - 1];
+    key = segment === undefined ? null : decodePathSegment(segment);
   } else {
-    key = new URLSearchParams(location.search).get(what || 'handle');
+    key = new URLSearchParams(location.search).get(source || 'handle');
   }
-  key = key && key.trim() ? key.trim() : null;
-  return { key, fromUrl: true, raw };
+  return { key: key?.trim() || null, fromUrl: true, raw };
 }
 
-function safeDecode(s) { try { return decodeURIComponent(s); } catch { return s; } }
-
-/** Values of tether-show that follow the scope state. */
+/** @type {readonly ScopeStatus[]} The values of `tether-show` that follow the scope's state. */
 export const STATUS_KEYS = ['loading', 'ready', 'error', 'not-found'];
 
-export const isNotFound = (err) => err?.code === 'NOT_FOUND';
+/**
+ * @param {unknown} value
+ * @returns {value is ScopeStatus}
+ */
+const isScopeStatus = (value) => STATUS_KEYS.some((status) => status === value);
 
-/** Product scopes and lists both own their state elements; the nearest one wins. */
-export const boundary = () => ['product', 'collection', 'products', 'recommendations'].map((n) => sel(n)).join(',');
+/**
+ * @param {unknown} error
+ * @returns {unknown} The error's `code` (a `TetherError` has one).
+ */
+const codeOf = (error) => (typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined);
+
+/**
+ * @param {unknown} error
+ * @returns {boolean} True for a `TetherError` with code `NOT_FOUND`.
+ */
+export const isNotFound = (error) => codeOf(error) === 'NOT_FOUND';
 
-/** True when `el` belongs to the scope `root` (not to a nested product or list). */
+/** @returns {string} The selector of every scope that owns its state elements; the nearest one wins. */
+export const boundary = () =>
+  ['product', 'collection', 'products', 'recommendations'].map((name) => sel(name)).join(',');
+
+/**
+ * @param {Element} el
+ * @param {Element} root
+ * @returns {boolean} True when `el` belongs to the scope `root`, not to a scope nested in it.
+ */
 export const ownedBy = (el, root) => el === root || el.parentElement?.closest(boundary()) === root;
 
 /**
- * Sets tether-state (loading | ready | error) and tether-error (not-found or an
- * error code) on `root`, toggles tether-show="loading|ready|error|not-found"
- * inside it, and disables add-to-cart buttons when there's no product.
+ * @param {unknown} error
+ * @returns {string} The error's code for `tether-error`, `error` without one.
  */
-export function setScopeStatus(root, status, err) {
+function errorCode(error) {
+  const code = codeOf(error);
+  return typeof code === 'string' && code ? code : 'error';
+}
+
+/**
+ * Sets `tether-state` (loading | ready | error) and `tether-error` (not-found or an error code) on `root`, toggles
+ * `tether-show="loading|ready|error|not-found"` inside it, and disables its add-to-cart buttons when there's no
+ * product.
+ *
+ * @param {Element} root
+ * @param {ScopeStatus} status
+ * @param {unknown} [error]
+ */
+export function setScopeStatus(root, status, error) {
   const notFound = status === 'not-found';
+  const failed = status === 'error' || notFound;
   root.setAttribute(attr('state'), notFound ? 'error' : status);
-  if (status === 'error' || notFound) root.setAttribute(attr('error'), notFound ? 'not-found' : (err?.code || 'error'));
+  if (failed) root.setAttribute(attr('error'), notFound ? 'not-found' : errorCode(error));
   else root.removeAttribute(attr('error'));
 
   scoped(root, sel('show'), boundary()).forEach((el) => {
-    const k = get(el, 'show');
-    if (!STATUS_KEYS.includes(k)) return;
-    show(el, k === status);
+    const shows = get(el, 'show');
+    if (isScopeStatus(shows)) show(el, shows === status);
   });
 
-  if (status === 'error' || notFound) {
-    scoped(root, sel('add-to-cart'), boundary()).forEach((btn) => {
-      btn.classList.add('is-disabled');
-      btn.setAttribute('aria-disabled', 'true');
-      if ('disabled' in btn) btn.disabled = true;
-    });
-  }
+  if (!failed) return;
+  scoped(root, sel('add-to-cart'), boundary()).forEach((button) => {
+    button.classList.add('is-disabled');
+    button.setAttribute('aria-disabled', 'true');
+    if ('disabled' in button) button.disabled = true;
+  });
 }

package/src/storefront/catalog.js

@@ -0,0 +1,199 @@
+/**
+ * The catalog reads of `createStorefront()`: products, collections and recommendations, with the browser script's own
+ * product fragment, so what the server renders and hands over has the shape the script expects. Runs in Node and
+ * Workers: no DOM, no shared config.
+ */
+import { request } from '../client.js';
+import { productFragment, collectionFields } from '../fragments.js';
+import { productKey } from '../shopify-values.js';
+/** @import { StorefrontConfig } from '../client.js' */
+/** @import { ProductFragmentConfig, Product } from '../fragments.js' */
+/** @import { Collection, PageInfo, ProductPage } from '../loader.js' */
+
+/**
+ * @typedef {StorefrontConfig & ProductFragmentConfig} CatalogConfig What the catalog needs of a storefront's config.
+ */
+
+/**
+ * @typedef {object} CatalogQuery A page of a collection's products, or of a search.
+ * @property {string} [collection] A collection handle; without one, a search.
+ * @property {string | null} [query] Storefront search syntax; `null` or `''` is every product.
+ * @property {number} [first] Default the storefront's `pageSize`.
+ * @property {string | null} [after] The cursor of the page before.
+ * @property {string} [sortKey] `ProductCollectionSortKeys` for a collection, `ProductSortKeys` for a search.
+ * @property {boolean} [reverse]
+ * @property {unknown[]} [filters] `ProductFilter` values, for a collection.
+ */
+
+/** @typedef {Collection & { products: Product[], pageInfo: PageInfo }} CollectionWithProducts */
+/** @typedef {'RELATED' | 'COMPLEMENTARY'} RecommendationIntent */
+
+/** Stops a paging loop on a store that keeps answering `hasNextPage` (500 pages of 25 is 12,500 products). */
+const MAX_PRODUCT_PAGES = 500;
+const COLLECTIONS_PER_PAGE = 100;
+const MAX_COLLECTION_PAGES = 100;
+
+const PRODUCT_BY_ID = `query TetherServerProductById($id: ID!) { node(id: $id) { ... on Product { ...TetherProduct } } }`;
+const PRODUCT_BY_HANDLE = `query TetherServerProduct($handle: String!) { product(handle: $handle) { ...TetherProduct } }`;
+
+const collectionQuery =
+  () => `query TetherServerCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
+  collection(handle: $handle) {
+    ${collectionFields()}
+    products(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, filters: $filters) {
+      nodes { ...TetherProduct }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}`;
+
+const SEARCH_QUERY = `query TetherServerProducts($first: Int!, $after: String, $query: String, $sortKey: ProductSortKeys, $reverse: Boolean) {
+  products(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
+    nodes { ...TetherProduct }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+const collectionsQuery = () => `query TetherServerCollections($first: Int!, $after: String) {
+  collections(first: $first, after: $after) { nodes { ${collectionFields()} } pageInfo { hasNextPage endCursor } }
+}`;
+
+/** @param {boolean} byId */
+const recommendationsQuery = (
+  byId,
+) => `query TetherServerRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
+}`;
+
+/**
+ * @param {CatalogConfig} conf
+ * @param {number} pageSize Products per page when a query doesn't say.
+ */
+export function createCatalog(conf, pageSize) {
+  /**
+   * @template T The shape of the query's `data`.
+   * @param {string} operation The query, without the product fragment.
+   * @param {Record<string, unknown>} variables
+   * @returns {Promise<T>}
+   */
+  const send = (operation, variables) => request(conf, `${operation}\n${productFragment(conf)}`, variables);
+
+  /**
+   * @param {string | number | null | undefined} raw A handle, numeric id, gid or product URL.
+   * @returns {Promise<Product | null>} `null` when the store has no such product.
+   */
+  async function getProduct(raw) {
+    const key = productKey(raw);
+    if (!key) return null;
+    if (key.startsWith('gid://')) {
+      /** @type {{ node: Partial<Product> | null }} */
+      const data = await send(PRODUCT_BY_ID, { id: key });
+      // A gid of another type answers with a node that isn't a product: no fields of the fragment.
+      return data.node?.id ? /** @type {Product} */ (data.node) : null;
+    }
+    /** @type {{ product: Product | null }} */
+    const data = await send(PRODUCT_BY_HANDLE, { handle: key });
+    return data.product;
+  }
+
+  /**
+   * @param {string} handle
+   * @param {Omit<CatalogQuery, 'collection' | 'query'>} options
+   * @returns {Promise<ProductPage>} No collection and no products for a handle the store doesn't have.
+   */
+  async function getCollectionPage(handle, { first = pageSize, after = null, sortKey, reverse = false, filters }) {
+    /** @type {{ collection: (Collection & { products: { nodes: Product[], pageInfo: PageInfo } }) | null }} */
+    const data = await send(collectionQuery(), {
+      handle,
+      first,
+      after,
+      sortKey: sortKey || undefined,
+      reverse,
+      filters: filters ?? undefined,
+    });
+    if (!data.collection) return { collection: null, products: [], pageInfo: { hasNextPage: false, endCursor: null } };
+    const { products, ...collection } = data.collection;
+    return { collection, products: products.nodes, pageInfo: products.pageInfo };
+  }
+
+  /**
+   * @param {CatalogQuery} [options]
+   * @returns {Promise<ProductPage>}
+   */
+  async function getProducts(options = {}) {
+    const { collection, query, first = pageSize, after = null, sortKey, reverse = false } = options;
+    if (collection) return getCollectionPage(collection, options);
+    /** @type {{ products: { nodes: Product[], pageInfo: PageInfo } }} */
+    const data = await send(SEARCH_QUERY, {
+      first,
+      after,
+      query: query || undefined,
+      sortKey: sortKey || undefined,
+      reverse,
+    });
+    return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
+  }
+
+  /**
+   * Every product of a collection or a search, page by page: for `getStaticPaths()`.
+   *
+   * @param {Omit<CatalogQuery, 'first' | 'after'>} [options]
+   * @returns {Promise<Product[]>}
+   */
+  async function allProducts(options = {}) {
+    /** @type {Product[]} */
+    const products = [];
+    /** @type {string | null} */
+    let after = null;
+    for (let page = 0; page < MAX_PRODUCT_PAGES; page++) {
+      const result = await getProducts({ ...options, first: pageSize, after });
+      products.push(...result.products);
+      if (!result.pageInfo.hasNextPage) break;
+      after = result.pageInfo.endCursor;
+    }
+    return products;
+  }
+
+  /**
+   * @param {string} handle
+   * @param {Omit<CatalogQuery, 'collection'>} [options]
+   * @returns {Promise<CollectionWithProducts | null>} `null` for a handle the store doesn't have.
+   */
+  async function getCollection(handle, options = {}) {
+    const page = await getProducts({ ...options, collection: handle });
+    return page.collection ? { ...page.collection, products: page.products, pageInfo: page.pageInfo } : null;
+  }
+
+  /** @returns {Promise<Collection[]>} */
+  async function allCollections() {
+    /** @type {Collection[]} */
+    const collections = [];
+    /** @type {string | null} */
+    let after = null;
+    for (let page = 0; page < MAX_COLLECTION_PAGES; page++) {
+      /** @type {{ collections: { nodes: Collection[], pageInfo: PageInfo } }} */
+      const data = await request(conf, collectionsQuery(), { first: COLLECTIONS_PER_PAGE, after });
+      collections.push(...data.collections.nodes);
+      if (!data.collections.pageInfo.hasNextPage) break;
+      after = data.collections.pageInfo.endCursor;
+    }
+    return collections;
+  }
+
+  /**
+   * By product id (gid or numeric) or handle, so it can run next to `getProduct(handle)`.
+   *
+   * @param {string | number | { id: string } | null | undefined} product
+   * @param {RecommendationIntent} [intent]
+   * @returns {Promise<Product[]>}
+   */
+  async function getRecommendations(product, intent = 'RELATED') {
+    const key = productKey(typeof product === 'object' ? product?.id : product);
+    const byId = key?.startsWith('gid://') ?? false;
+    /** @type {{ productRecommendations: Product[] | null }} */
+    const data = await send(recommendationsQuery(byId), byId ? { id: key, intent } : { handle: key, intent });
+    return data.productRecommendations ?? [];
+  }
+
+  return { getProduct, getProducts, allProducts, getCollection, allCollections, getRecommendations };
+}

package/src/storefront/json-ld.js

@@ -0,0 +1,167 @@
+/**
+ * schema.org data for search engines (Google's product rich results): a `Product`, or a `ProductGroup` with one
+ * `Product` per variant, each with its price, currency, stock, sku, image and `?variant=` link. Products that are only
+ * sold on a subscription are priced at their first plan.
+ */
+import { allPlans, allocationFor, planPrice } from '../selling-plans.js';
+import { productUrl } from '../shopify-values.js';
+/** @import { Product, ProductVariant } from '../fragments.js' */
+/** @import { Money } from '../shopify-values.js' */
+
+/**
+ * @typedef {object} JsonLdOptions
+ * @property {string} [url] The product page's absolute URL; default from the storefront's `siteUrl`.
+ * @property {string} [brand] Default the product's vendor.
+ */
+
+/** @typedef {{ productPath: string, siteUrl: string | undefined }} JsonLdSite Where the product pages are. */
+
+/** The option names schema.org has a property for: a `ProductGroup` varies by them. */
+/** @type {Readonly<Record<string, string>>} */
+const VARIES_BY = {
+  size: 'https://schema.org/size',
+  color: 'https://schema.org/color',
+  colour: 'https://schema.org/color',
+  material: 'https://schema.org/material',
+};
+
+/**
+ * Text for a `<script>` tag: `<` is escaped so product text can never close the tag, and U+2028 / U+2029 so older
+ * JavaScript parsers read it.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export const scriptJson = (value) =>
+  JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+
+/**
+ * @param {Record<string, unknown>} value
+ * @returns {Record<string, unknown>} `value` without its `undefined` fields, nested ones too.
+ */
+function withoutUndefined(value) {
+  /** @type {unknown} */
+  const copy = JSON.parse(JSON.stringify(value));
+  // The JSON of an object is an object.
+  return /** @type {Record<string, unknown>} */ (copy);
+}
+
+/** @param {string} gid */
+const numericId = (gid) => gid.split('/').pop() ?? gid;
+
+/**
+ * @param {ProductVariant} variant
+ * @returns {string} The schema.org availability.
+ */
+function availability(variant) {
+  if (!variant.availableForSale) return 'https://schema.org/OutOfStock';
+  return variant.currentlyNotInStock ? 'https://schema.org/BackOrder' : 'https://schema.org/InStock';
+}
+
+/**
+ * @param {Product} product
+ * @param {ProductVariant} variant
+ * @returns {Money} The variant's price, or its first plan's for a product sold only on a subscription.
+ */
+function offeredPrice(product, variant) {
+  if (!product.requiresSellingPlan) return variant.price;
+  const plan = allPlans(product).find((candidate) => allocationFor(variant, candidate.id));
+  return (plan && planPrice(variant, plan.id)) ?? variant.price;
+}
+
+/**
+ * @param {Product} product
+ * @param {ProductVariant} variant
+ * @param {string | undefined} pageUrl
+ */
+function offer(product, variant, pageUrl) {
+  const price = offeredPrice(product, variant);
+  const separator = pageUrl?.includes('?') ? '&' : '?';
+  return {
+    '@type': 'Offer',
+    price: price.amount,
+    priceCurrency: price.currencyCode,
+    availability: availability(variant),
+    url: pageUrl ? `${pageUrl}${separator}variant=${numericId(variant.id)}` : undefined,
+  };
+}
+
+/**
+ * @param {Product} product
+ * @param {ProductVariant} variant
+ * @param {string | undefined} pageUrl
+ * @param {readonly string[]} images
+ */
+function variantProduct(product, variant, pageUrl, images) {
+  /** @type {[string, string][]} schema.org property name → the variant's value. */
+  const properties = variant.selectedOptions.flatMap((option) => {
+    const property = VARIES_BY[option.name.toLowerCase()];
+    return property ? [[property.split('/').pop() ?? property, option.value]] : [];
+  });
+  return {
+    '@type': 'Product',
+    name: `${product.title} - ${variant.title}`,
+    sku: variant.sku || undefined,
+    image: variant.image?.url || images[0],
+    ...Object.fromEntries(properties),
+    offers: offer(product, variant, pageUrl),
+  };
+}
+
+/**
+ * @param {Product} product
+ * @param {JsonLdOptions} options
+ * @param {JsonLdSite} site
+ * @returns {string | undefined}
+ */
+function pageUrlOf(product, { url }, site) {
+  if (url) return url;
+  if (!site.siteUrl) return undefined;
+  return new URL(productUrl(site.productPath, product.handle, product.id), site.siteUrl).toString();
+}
+
+/**
+ * @param {Product | null | undefined} product
+ * @param {JsonLdOptions} options
+ * @param {JsonLdSite} site
+ * @returns {Record<string, unknown> | null} The schema.org object, `null` without a product.
+ */
+export function jsonLdData(product, options, site) {
+  if (!product) return null;
+  const pageUrl = pageUrlOf(product, options, site);
+  const images = product.images.nodes.map((image) => image.url).filter(Boolean);
+  const brandName = options.brand || product.vendor;
+  const brand = brandName ? { '@type': 'Brand', name: brandName } : undefined;
+  const description = product.description.trim() || undefined;
+  const variants = product.variants.nodes;
+  if (variants.length <= 1) {
+    const [variant] = variants;
+    return withoutUndefined({
+      '@context': 'https://schema.org',
+      '@type': 'Product',
+      name: product.title,
+      description,
+      url: pageUrl,
+      image: images,
+      sku: variant?.sku || undefined,
+      brand,
+      offers: variant ? offer(product, variant, pageUrl) : undefined,
+    });
+  }
+  const variesBy = product.options.map((option) => VARIES_BY[option.name.toLowerCase()]).filter(Boolean);
+  return withoutUndefined({
+    '@context': 'https://schema.org',
+    '@type': 'ProductGroup',
+    name: product.title,
+    description,
+    url: pageUrl,
+    productGroupID: numericId(product.id),
+    image: images,
+    brand,
+    variesBy: [...new Set(variesBy)],
+    hasVariant: variants.map((variant) => variantProduct(product, variant, pageUrl, images)),
+  });
+}