@occluze/tether 0.6.6 → 0.6.8

package/src/selling-plans.js

@@ -1,94 +1,154 @@
 /**
- * Pure helpers for Shopify selling plans (subscriptions). No DOM, easy to test.
+ * Shopify selling plans (subscriptions): which plans a product and a variant have, and what each costs. Pure, no DOM,
+ * shared by the browser script and the server helpers.
  */
+/** @import { Money } from './shopify-values.js' */
+/** @import { SellingPlan, SellingPlanGroup, SellingPlanAllocation } from './fragments.js' */
 
-export const GID = {
-  product: (v) => toGid(v, 'Product'),
-  variant: (v) => toGid(v, 'ProductVariant'),
-  sellingPlan: (v) => toGid(v, 'SellingPlan'),
-};
+/** @typedef {SellingPlan & { group: SellingPlanGroup }} PlanInGroup A plan with the group it belongs to. */
+/** @typedef {{ sellingPlanGroups?: { nodes: SellingPlanGroup[] } | null }} ProductWithPlans */
+/**
+ * A variant as far as plans go. A cart line's variant has no allocations.
+ *
+ * @typedef {{ price: Money, sellingPlanAllocations?: { nodes: SellingPlanAllocation[] } | null }} VariantWithPlans
+ */
+/**
+ * @typedef {{ type: 'percentage', value: number } | { type: 'amount', value: Money } | { type: 'price', value: Money }}
+ *   PlanAdjustment
+ */
 
+/**
+ * @param {unknown} value A gid, a numeric id, or anything else.
+ * @param {string} type The Shopify type, e.g. `ProductVariant`.
+ * @returns {string | null} The gid of a numeric id; a gid or other value as written; `null` when empty.
+ */
 export function toGid(value, type) {
-  const v = String(value ?? '').trim();
-  if (!v) return null;
-  if (v.startsWith('gid://')) return v;
-  if (/^\d+$/.test(v)) return `gid://shopify/${type}/${v}`;
-  return v;
+  const text = typeof value === 'string' || typeof value === 'number' ? String(value).trim() : '';
+  if (!text) return null;
+  if (text.startsWith('gid://')) return text;
+  if (/^\d+$/.test(text)) return `gid://shopify/${type}/${text}`;
+  return text;
 }
 
-/** All plans of a product, flattened, each with its group attached. */
+export const GID = {
+  /** @param {unknown} value */
+  product: (value) => toGid(value, 'Product'),
+  /** @param {unknown} value */
+  variant: (value) => toGid(value, 'ProductVariant'),
+  /** @param {unknown} value */
+  sellingPlan: (value) => toGid(value, 'SellingPlan'),
+};
+
+/**
+ * @param {ProductWithPlans | null | undefined} product
+ * @returns {PlanInGroup[]} All plans of the product, flattened.
+ */
 export function allPlans(product) {
-  const groups = product?.sellingPlanGroups?.nodes || [];
-  return groups.flatMap((g) => (g.sellingPlans?.nodes || []).map((p) => ({ ...p, group: g })));
+  const groups = product?.sellingPlanGroups?.nodes ?? [];
+  return groups.flatMap((group) => group.sellingPlans.nodes.map((plan) => ({ ...plan, group })));
 }
 
+/** @param {ProductWithPlans | null | undefined} product */
 export function hasPlans(product) {
   return allPlans(product).length > 0;
 }
 
-/** The allocation of `planId` on `variant`, or null when the variant isn't in that plan. */
+/**
+ * @param {VariantWithPlans | null | undefined} variant
+ * @param {string | null | undefined} planId
+ * @returns {SellingPlanAllocation | null} The variant's allocation on the plan; `null` when the variant isn't in it.
+ */
 export function allocationFor(variant, planId) {
   if (!variant || !planId) return null;
-  return (variant.sellingPlanAllocations?.nodes || []).find((a) => a.sellingPlan?.id === planId) || null;
+  const allocations = variant.sellingPlanAllocations?.nodes ?? [];
+  return allocations.find((allocation) => allocation.sellingPlan.id === planId) ?? null;
 }
 
-/** Plans that can actually be bought with this variant. */
+/**
+ * @param {ProductWithPlans | null | undefined} product
+ * @param {VariantWithPlans | null | undefined} variant
+ * @returns {PlanInGroup[]} The plans this variant can be bought on.
+ */
 export function plansForVariant(product, variant) {
-  return allPlans(product).filter((p) => allocationFor(variant, p.id));
+  return allPlans(product).filter((plan) => allocationFor(variant, plan.id));
 }
 
-/** Price per delivery for a variant on a plan (falls back to the one-time price). */
+/**
+ * @param {VariantWithPlans | null | undefined} variant
+ * @param {string | null | undefined} planId
+ * @returns {Money | null} The price per delivery on the plan; the one-time price when the variant isn't on it.
+ */
 export function planPrice(variant, planId) {
-  const a = allocationFor(variant, planId);
-  const adj = a?.priceAdjustments?.[0];
-  return adj?.perDeliveryPrice || adj?.price || variant?.price || null;
+  const adjustment = allocationFor(variant, planId)?.priceAdjustments[0];
+  return adjustment?.perDeliveryPrice ?? adjustment?.price ?? variant?.price ?? null;
 }
 
-/** What the customer pays at checkout for this plan (prepaid plans charge more up front). */
+/**
+ * @param {VariantWithPlans | null | undefined} variant
+ * @param {string | null | undefined} planId
+ * @returns {Money | null} What the customer pays at checkout on the plan (prepaid plans charge more up front).
+ */
 export function planCheckoutCharge(variant, planId) {
-  const a = allocationFor(variant, planId);
-  return a?.checkoutChargeAmount || a?.priceAdjustments?.[0]?.price || variant?.price || null;
+  const allocation = allocationFor(variant, planId);
+  return allocation?.checkoutChargeAmount ?? allocation?.priceAdjustments[0]?.price ?? variant?.price ?? null;
 }
 
-/** Savings of a plan vs the one-time price, as { amount, percentage }. */
+/**
+ * @param {VariantWithPlans | null | undefined} variant
+ * @param {string | null | undefined} planId
+ * @returns {{ amount: Money | null, percentage: number }} What the plan saves on the one-time price; no amount and
+ *   0% when it saves nothing.
+ */
 export function planSavings(variant, planId) {
-  const base = parseFloat(variant?.price?.amount);
-  const sub = parseFloat(planPrice(variant, planId)?.amount);
-  if (!Number.isFinite(base) || !Number.isFinite(sub) || base <= 0 || sub >= base) {
+  const oneTime = parseFloat(variant?.price.amount ?? '');
+  const onPlan = parseFloat(planPrice(variant, planId)?.amount ?? '');
+  if (!variant || !Number.isFinite(oneTime) || !Number.isFinite(onPlan) || oneTime <= 0 || onPlan >= oneTime) {
     return { amount: null, percentage: 0 };
   }
   return {
-    amount: { amount: (base - sub).toFixed(2), currencyCode: variant.price.currencyCode },
-    percentage: Math.round((1 - sub / base) * 100),
+    amount: { amount: (oneTime - onPlan).toFixed(2), currencyCode: variant.price.currencyCode },
+    percentage: Math.round((1 - onPlan / oneTime) * 100),
   };
 }
 
 /**
- * The plan's own discount description, independent of a variant:
- * '10%', or a fixed amount / fixed price.
+ * @param {Pick<SellingPlan, 'priceAdjustments'> | null | undefined} plan
+ * @returns {PlanAdjustment | null} The plan's own discount, whatever the variant: a percentage, a fixed amount off or
+ *   a fixed price.
  */
 export function planAdjustment(plan) {
-  const v = plan?.priceAdjustments?.[0]?.adjustmentValue;
-  if (!v) return null;
-  switch (v.__typename) {
-    case 'SellingPlanPercentagePriceAdjustment': return { type: 'percentage', value: v.adjustmentPercentage };
-    case 'SellingPlanFixedAmountPriceAdjustment': return { type: 'amount', value: v.adjustmentAmount };
-    case 'SellingPlanFixedPriceAdjustment': return { type: 'price', value: v.price };
-    default: return null;
+  const value = plan?.priceAdjustments[0]?.adjustmentValue;
+  if (!value) return null;
+  switch (value.__typename) {
+    case 'SellingPlanPercentagePriceAdjustment':
+      return { type: 'percentage', value: value.adjustmentPercentage };
+    case 'SellingPlanFixedAmountPriceAdjustment':
+      return { type: 'amount', value: value.adjustmentAmount };
+    case 'SellingPlanFixedPriceAdjustment':
+      return { type: 'price', value: value.price };
+    default:
+      // An adjustment type newer than the API version Tether was written for.
+      return null;
   }
 }
 
 /**
- * Finds a plan by id, numeric id, name or option value (case-insensitive),
- * so Webflow editors can write tether-default-plan="Every month".
+ * Finds a plan by id, numeric id, name or option value (case-insensitive), so Webflow editors can write
+ * `tether-default-plan="Every month"`.
+ *
+ * @param {ProductWithPlans | null | undefined} product
+ * @param {string | null | undefined} ref
+ * @returns {PlanInGroup | null}
  */
 export function findPlan(product, ref) {
   if (!ref) return null;
   const plans = allPlans(product);
   const gid = GID.sellingPlan(ref);
-  const needle = String(ref).trim().toLowerCase();
-  return plans.find((p) => p.id === gid)
-    || plans.find((p) => p.name.toLowerCase() === needle)
-    || plans.find((p) => (p.options || []).some((o) => String(o.value).toLowerCase() === needle))
-    || null;
+  const needle = ref.trim().toLowerCase();
+  return (
+    plans.find((plan) => plan.id === gid) ??
+    plans.find((plan) => plan.name.toLowerCase() === needle) ??
+    plans.find((plan) => plan.options.some((option) => option.value.toLowerCase() === needle)) ??
+    null
+  );
 }

package/src/server.js

@@ -1,252 +1,215 @@
 /**
- * @occluze/tether/server: Shopify product data at build time or on the server (Astro, Eleventy,
- * Node, Cloudflare Workers). No browser APIs. Uses the same queries as the browser script, so
- * products handed over with hydrate() are exactly what Tether expects and need no extra request.
+ * `@occluze/tether/server`: Shopify product data at build time or on the server (Astro, Eleventy, Node, Cloudflare
+ * Workers). No browser APIs. It sends the browser script's own queries, so products handed over with `hydrate()` are
+ * exactly what the script expects and need no request of their own.
  *
  *   import { createStorefront } from '@occluze/tether/server';
  *   const shop = createStorefront({ domain, token, country: 'NL' });
  *   const product = await shop.getProduct('coffee-box');
  *   const all = await shop.allProducts();
  */
-import { DEFAULTS } from './config.js';
+import { DEFAULTS, resolveConfig } from './config.js';
 import { request, withContext, TetherError } from './client.js';
-import { productFragment, collectionFields } from './fragments.js';
 import * as plans from './selling-plans.js';
 import { imageUrl, formatPercent } from './dom.js';
 import { initialState } from './initial.js';
+import { STORE_ENV_NAMES, formatMoney, productKey, productUrl as productUrlFor } from './shopify-values.js';
+import { createCatalog } from './storefront/catalog.js';
+import { jsonLdData, scriptJson } from './storefront/json-ld.js';
+/** @import { TetherConfig, TetherOptions } from './config.js' */
+/** @import { Product } from './fragments.js' */
+/** @import { Money } from './shopify-values.js' */
+/** @import { InitialOptions } from './initial.js' */
+/** @import { JsonLdOptions } from './storefront/json-ld.js' */
 
-export { imageUrl, initialState, formatPercent };
+export { imageUrl, initialState, formatPercent, formatMoney, productKey };
 
 export { TetherError, plans, withContext };
 
-const isGid = (v) => typeof v === 'string' && v.startsWith('gid://');
-
-/** Handle, numeric id, gid or product URL -> handle or gid. */
-export function productKey(raw) {
-  const v = String(raw ?? '').trim();
-  if (!v) return null;
-  if (isGid(v)) return v;
-  if (/^\d+$/.test(v)) return `gid://shopify/Product/${v}`;
-  const m = v.match(/\/products\/([^/?#]+)/);
-  return m ? m[1] : v;
-}
+/**
+ * @typedef {object} ServerOptions The options only a storefront has.
+ * @property {typeof fetch} [fetch] Replaces the global `fetch` (tests, caching).
+ * @property {number} [pageSize] Products per request for `allProducts()` (default 25).
+ * @property {string} [siteUrl] The site's address, for product URLs in `jsonLd()` without `url`.
+ */
 
-/** Money as text, e.g. formatMoney({ amount: '30.0', currencyCode: 'EUR' }, 'nl-NL') -> "€ 30,00". */
-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 {
-    return `${money.currencyCode} ${amount.toFixed(2)}`;
-  }
-}
+/**
+ * @typedef {TetherOptions & ServerOptions & Record<string, unknown>} StorefrontOptions The config options, or an
+ *   `import.meta.env` spread into them: its `PUBLIC_SHOPIFY_*` names give the domain and token, its other keys are
+ *   ignored.
+ */
 
-/** productPath '/products' -> /products/<handle>; templates '/p?handle={handle}' and '{id}' work too. */
-export function productUrl(handle, { productPath = '/product', id } = {}) {
-  if (!/\{(handle|id)\}/.test(productPath)) return `${productPath.replace(/\/$/, '')}/${handle}`;
-  return productPath.replace(/\{handle\}/g, encodeURIComponent(handle || '')).replace(/\{id\}/g, encodeURIComponent(id ? String(id).split('/').pop() : ''));
-}
+/** @typedef {TetherConfig & ServerOptions} ServerConfig */
 
-/** JSON for a <script> tag: escapes < so product text can never close the tag. */
-const safeJson = (v) => JSON.stringify(v).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+/** @typedef {{ card?: boolean, images?: number }} HydrateOptions */
 
-// createStorefront(import.meta.env) works too: these env names map to domain and token.
-const ENV = {
-  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
-  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
-};
+const DEFAULT_PAGE_SIZE = 25;
+/** The images a card keeps: the main one and a hover image (`tether-bind="image:2"`). */
+const DEFAULT_CARD_IMAGES = 2;
+/** The version of the `data-tether-hydrate` payload, for the browser script reading it. */
+const HYDRATE_VERSION = 1;
 
-export function createStorefront(options = {}) {
-  const known = Object.fromEntries(Object.entries(options).filter(([k]) => k in DEFAULTS || k === 'fetch' || k === 'pageSize' || k === 'siteUrl'));
-  const conf = { ...DEFAULTS, ...known };
-  for (const [key, names] of Object.entries(ENV)) if (!conf[key]) conf[key] = names.map((n) => options[n]).find(Boolean) || '';
-  conf.domain = String(conf.domain || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '');
-  if (!conf.domain || !conf.token) {
-    throw new TetherError('createStorefront needs domain and token: pass them, or import.meta.env with PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN', { code: 'NOT_CONFIGURED' });
-  }
-  const pageSize = options.pageSize || 25;
-  const q = (query, variables, opts) => request(conf, query, variables, opts);
-  const fragment = () => productFragment(conf);
-
-  async function getProduct(raw) {
-    const key = productKey(raw);
-    if (!key) return null;
-    const data = isGid(key)
-      ? await q(`query TetherServerProductById($id: ID!) { node(id: $id) { ... on Product { ...TetherProduct } } }\n${fragment()}`, { id: key })
-      : await q(`query TetherServerProduct($handle: String!) { product(handle: $handle) { ...TetherProduct } }\n${fragment()}`, { handle: key });
-    const p = isGid(key) ? data.node : data.product;
-    return p && p.id ? p : null;
-  }
-
-  async function getProducts({ collection, query, first = pageSize, after = null, sortKey, reverse = false, filters } = {}) {
-    if (collection) {
-      const data = await q(`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 }
-    }
-  }
-}
-${fragment()}`, { handle: collection, first, after, sortKey: sortKey || undefined, reverse, filters: filters || undefined });
-      if (!data.collection) return { collection: null, products: [], pageInfo: { hasNextPage: false, endCursor: null } };
-      const { products, ...rest } = data.collection;
-      return { collection: rest, products: products.nodes, pageInfo: products.pageInfo };
-    }
-    const data = await q(`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 }
-  }
+/**
+ * @param {string} handle
+ * @param {{ productPath?: string, id?: string }} [options]
+ * @returns {string} `productPath` `/products` → `/products/<handle>`; templates with `{handle}` and `{id}` work too.
+ */
+export function productUrl(handle, { productPath = DEFAULTS.productPath, id } = {}) {
+  return productUrlFor(productPath, handle, id);
 }
-${fragment()}`, { 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(). */
-  async function allProducts(opts = {}) {
-    const out = [];
-    let after = null;
-    for (let i = 0; i < 500; i++) {
-      const page = await getProducts({ ...opts, first: pageSize, after });
-      out.push(...page.products);
-      if (!page.pageInfo.hasNextPage) break;
-      after = page.pageInfo.endCursor;
-    }
-    return out;
+/**
+ * @param {Record<string, unknown>} options
+ * @param {readonly string[]} names
+ * @returns {string} The first of the `names` set in `options`, `''` without one.
+ */
+function fromEnv(options, names) {
+  for (const name of names) {
+    const value = options[name];
+    if (typeof value === 'string' && value) return value;
   }
+  return '';
+}
 
-  async function getCollection(handle, opts = {}) {
-    const page = await getProducts({ ...opts, collection: handle });
-    return page.collection ? { ...page.collection, products: page.products, pageInfo: page.pageInfo } : null;
+/**
+ * @param {StorefrontOptions} options
+ * @returns {ServerConfig} The config options of `options`, resolved and validated as the browser's are, with the
+ *   domain and token from the environment names when they aren't set.
+ */
+function storefrontConfig(options) {
+  /** @type {Record<string, unknown>} */
+  const known = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (key in DEFAULTS) known[key] = value;
   }
+  const domain = typeof options.domain === 'string' && options.domain ? options.domain : '';
+  const token = typeof options.token === 'string' && options.token ? options.token : '';
+  /** @type {ServerConfig} */
+  const conf = resolveConfig({
+    // Only config keys: `resolveConfig` checks each value.
+    .../** @type {TetherOptions} */ (known),
+    domain: domain || fromEnv(options, STORE_ENV_NAMES.domain),
+    token: token || fromEnv(options, STORE_ENV_NAMES.token),
+  });
+  if (options.fetch) conf.fetch = options.fetch;
+  if (options.pageSize !== undefined) conf.pageSize = options.pageSize;
+  if (options.siteUrl !== undefined) conf.siteUrl = options.siteUrl;
+  return conf;
+}
 
-  async function allCollections() {
-    const out = [];
-    let after = null;
-    for (let i = 0; i < 100; i++) {
-      const data = await q(`query TetherServerCollections($first: Int!, $after: String) {
-  collections(first: $first, after: $after) { nodes { ${collectionFields()} } pageInfo { hasNextPage endCursor } }
-}`, { first: 100, after });
-      out.push(...data.collections.nodes);
-      if (!data.collections.pageInfo.hasNextPage) break;
-      after = data.collections.pageInfo.endCursor;
-    }
-    return out;
-  }
+/**
+ * @param {number | undefined} pageSize
+ * @returns {number} `pageSize` when it is a positive integer, else the default.
+ */
+const validPageSize = (pageSize) =>
+  typeof pageSize === 'number' && Number.isInteger(pageSize) && pageSize > 0 ? pageSize : DEFAULT_PAGE_SIZE;
 
-  /** By product id (gid or numeric) or handle, so it can run next to getProduct(handle). */
-  async function getRecommendations(product, intent = 'RELATED') {
-    const key = productKey(typeof product === 'object' ? product?.id : product);
-    const byId = key?.startsWith('gid://');
-    const data = await q(`query TetherServerRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
-  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
+/**
+ * A product for a list (home, collections, recommendations): without descriptions and variant images, and only its
+ * first `images` images. Prices, stock and plans per variant stay.
+ *
+ * @param {Product} product
+ * @param {number} images
+ * @returns {Product}
+ */
+function cardOf(product, images) {
+  return {
+    ...product,
+    description: '',
+    descriptionHtml: '',
+    images: { nodes: product.images.nodes.slice(0, Math.max(1, images)) },
+    variants: { nodes: product.variants.nodes.map((variant) => ({ ...variant, image: null })) },
+  };
 }
-${fragment()}`, byId ? { id: key, intent } : { handle: key, intent });
-    return data.productRecommendations || [];
+
+/**
+ * A storefront: the store's products and collections for the server, and the tags that hand them to the page.
+ *
+ * @param {StorefrontOptions} [options]
+ * @throws {TetherError} `NOT_CONFIGURED` without a domain and a token.
+ */
+export function createStorefront(options = {}) {
+  const conf = storefrontConfig(options);
+  if (!conf.domain || !conf.token) {
+    throw new TetherError(
+      'createStorefront needs domain and token: pass them, or import.meta.env with PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN',
+      { code: 'NOT_CONFIGURED' },
+    );
   }
+  const catalog = createCatalog(conf, validPageSize(conf.pageSize));
+  const site = { productPath: conf.productPath, siteUrl: conf.siteUrl };
 
   /**
-   * A <script> tag that hands products to the browser script: Tether renders them at once,
-   * without its own request, then refreshes prices and stock in the background.
-   * Put it anywhere in the page (Astro: <Fragment set:html={shop.hydrate(products)} />).
+   * A `<script type="application/json" data-tether-hydrate>` tag that hands products to the browser script: it renders
+   * them at once, without a request of its own, then refreshes prices and stock once in the background. Astro:
+   * `<Fragment set:html={shop.hydrate(products)} />`.
+   *
+   * @param {Product | null | undefined | (Product | null | undefined)[]} products
+   * @param {HydrateOptions} [options] `card: true` for lists: about 40% smaller (see `cardOf`). The full product
+   *   comes with the background refresh.
    */
-  /**
-   * { card: true } for lists (home, collections, recommendations): about 40% smaller, without
-   * descriptions, variant images and images after the first two (a hover image, tether-bind="image:2";
-   * more with { card: true, images: 3 }). Price, stock and plans per variant stay. The full
-   * product comes with the background refresh.
-   */
-  function hydrate(products, { card = false, images = 2 } = {}) {
-    let list = (Array.isArray(products) ? products : [products]).filter(Boolean);
-    if (card) list = list.map((p) => slim(p, images));
-    const payload = { v: 1, at: new Date().toISOString(), country: conf.country || null, language: conf.language || null, products: list };
-    return `<script type="application/json" data-tether-hydrate>${safeJson(payload)}</script>`;
+  function hydrate(products, { card = false, images = DEFAULT_CARD_IMAGES } = {}) {
+    const present = (Array.isArray(products) ? products : [products]).filter((product) => product != null);
+    const payload = {
+      v: HYDRATE_VERSION,
+      at: new Date().toISOString(),
+      country: conf.country || null,
+      language: conf.language || null,
+      products: card ? present.map((product) => cardOf(product, images)) : present,
+    };
+    return `<script type="application/json" data-tether-hydrate>${scriptJson(payload)}</script>`;
   }
 
   /**
-   * schema.org data for search engines (Google's product rich results): a Product, or a ProductGroup
-   * with one Product per variant (price, currency, stock, sku, image, link to ?variant=).
-   * jsonLd(product, { url: 'https://shop.example/products/x' }) -> the <script> tag; jsonLdData() -> the object.
+   * @param {Product | null | undefined} product
+   * @param {JsonLdOptions} [jsonLdOptions]
+   * @returns {string} The `<script type="application/ld+json">` tag, `''` without a product.
    */
-  function jsonLdData(p, { url, brand } = {}) {
-    if (!p) return null;
-    const pageUrl = url || (conf.siteUrl ? new URL(productUrl(p.handle, { productPath: conf.productPath, id: p.id }), conf.siteUrl).toString() : undefined);
-    const vid = (v) => String(v.id).split('/').pop();
-    const withVariant = (v) => (pageUrl ? `${pageUrl}${pageUrl.includes('?') ? '&' : '?'}variant=${vid(v)}` : undefined);
-    const text = (p.description || '').trim() || undefined;
-    const images = (p.images?.nodes || []).map((i) => i.url).filter(Boolean);
-    const brandName = brand || p.vendor;
-    // Only buyable on a subscription: the plan price is the price (the first plan the variant has).
-    const priceOf = (v) => {
-      if (!p.requiresSellingPlan) return v.price;
-      const plan = plans.allPlans(p).find((pl) => plans.allocationFor(v, pl.id));
-      return plan ? plans.planPrice(v, plan.id) : v.price;
-    };
-    const offer = (v) => ({
-      '@type': 'Offer',
-      price: priceOf(v)?.amount,
-      priceCurrency: priceOf(v)?.currencyCode,
-      availability: `https://schema.org/${v.availableForSale ? (v.currentlyNotInStock ? 'BackOrder' : 'InStock') : 'OutOfStock'}`,
-      url: withVariant(v),
-    });
-    const vs = p.variants?.nodes || [];
-    const clean = (o) => JSON.parse(JSON.stringify(o)); // drops undefined
-    if (vs.length <= 1) {
-      const v = vs[0];
-      return clean({
-        '@context': 'https://schema.org', '@type': 'Product', name: p.title, description: text, url: pageUrl,
-        image: images, sku: v?.sku || undefined, brand: brandName ? { '@type': 'Brand', name: brandName } : undefined,
-        offers: v ? offer(v) : undefined,
-      });
-    }
-    const varies = { size: 'https://schema.org/size', color: 'https://schema.org/color', colour: 'https://schema.org/color', material: 'https://schema.org/material' };
-    return clean({
-      '@context': 'https://schema.org', '@type': 'ProductGroup', name: p.title, description: text, url: pageUrl,
-      productGroupID: String(p.id).split('/').pop(), image: images,
-      brand: brandName ? { '@type': 'Brand', name: brandName } : undefined,
-      variesBy: [...new Set((p.options || []).map((o) => varies[o.name.toLowerCase()]).filter(Boolean))],
-      hasVariant: vs.map((v) => ({
-        '@type': 'Product',
-        name: `${p.title} - ${v.title}`,
-        sku: v.sku || undefined,
-        image: v.image?.url || images[0],
-        ...Object.fromEntries((v.selectedOptions || []).filter((o) => varies[o.name.toLowerCase()]).map((o) => [varies[o.name.toLowerCase()].split('/').pop(), o.value])),
-        offers: offer(v),
-      })),
-    });
-  }
-  const jsonLd = (p, opts) => (p ? `<script type="application/ld+json">${safeJson(jsonLdData(p, opts))}</script>` : '');
-
-  function slim(p, keep = 2) {
-    return {
-      ...p,
-      description: '', descriptionHtml: '',
-      images: { nodes: (p.images?.nodes || []).slice(0, Math.max(1, keep)) },
-      variants: { nodes: (p.variants?.nodes || []).map((v) => ({ ...v, image: null })) },
-    };
+  function jsonLd(product, jsonLdOptions = {}) {
+    if (!product) return '';
+    return `<script type="application/ld+json">${scriptJson(jsonLdData(product, jsonLdOptions, site))}</script>`;
   }
 
   return {
     config: conf,
-    query: q,
-    getProduct,
-    getProducts,
-    allProducts,
-    getCollection,
-    allCollections,
-    getRecommendations,
+    /**
+     * @template T
+     * @param {string} query
+     * @param {Record<string, unknown>} [variables]
+     * @param {{ context?: boolean }} [requestOptions]
+     * @returns {Promise<T>}
+     */
+    query: (query, variables, requestOptions) => request(conf, query, variables, requestOptions),
+    ...catalog,
     hydrate,
+    /**
+     * @param {Money | null | undefined} money
+     * @param {string | undefined} [locale]
+     */
     formatMoney: (money, locale = conf.locale) => formatMoney(money, locale),
-    formatPercent: (n, locale = conf.locale) => formatPercent(n, locale),
+    /**
+     * @param {number} percentage
+     * @param {string | undefined} [locale]
+     */
+    formatPercent: (percentage, locale = conf.locale) => formatPercent(percentage, locale),
     imageUrl,
     jsonLd,
-    jsonLdData,
-    initialState: (product, opts = {}) => initialState(product, { defaultPurchase: conf.defaultPurchase, lowStock: conf.lowStock, ...opts }),
-    productUrl: (handle, opts = {}) => productUrl(handle, { productPath: conf.productPath, ...opts }),
+    /**
+     * @param {Product | null | undefined} product
+     * @param {JsonLdOptions} [jsonLdOptions]
+     */
+    jsonLdData: (product, jsonLdOptions = {}) => jsonLdData(product, jsonLdOptions, site),
+    /**
+     * @param {Product | null | undefined} product
+     * @param {InitialOptions} [initialOptions]
+     */
+    initialState: (product, initialOptions = {}) =>
+      initialState(product, { defaultPurchase: conf.defaultPurchase, lowStock: conf.lowStock, ...initialOptions }),
+    /**
+     * @param {string} handle
+     * @param {{ productPath?: string, id?: string }} [urlOptions]
+     */
+    productUrl: (handle, urlOptions = {}) => productUrl(handle, { productPath: conf.productPath, ...urlOptions }),
     plans,
   };
 }