@occluze/tether 0.6.8 → 0.7.0

package/src/{search.js → search.ts}

@@ -15,27 +15,52 @@
  * tether-search-state="idle|loading|ready|empty|error". Arrow keys move through the results, Escape closes.
  * tether-search-limit (default 6), tether-search-min (characters, default 2).
  */
-import { cfg, log, reportError } from './config.js';
-import { gql } from './client.js';
-import { attr, sel, get, qsa, setText, setImage, repeat, show, formatMoney, productUrl, emit } from './dom.js';
-import { within } from './mounting.js';
-/** @import { Money } from './shopify-values.js' */
+import { cfg, log, reportError } from './config.ts';
+import { gql, orNull, shaped } from './client.ts';
+import { attr, sel, get, qsa, setText, setImage, repeat, show, formatMoney, productUrl, emit } from './dom.ts';
+import { within } from './mounting.ts';
+import type { Money } from './shopify-values.ts';
 
-/** @typedef {{ url: string, altText: string | null }} SearchImage */
-/**
- * @typedef {object} SearchProduct
- * @property {string} id
- * @property {string} handle
- * @property {string} title
- * @property {boolean} availableForSale
- * @property {SearchImage | null} featuredImage
- * @property {{ minVariantPrice: Money }} priceRange
- */
-/** @typedef {{ handle: string, title: string, image: SearchImage | null }} SearchCollection */
-/** @typedef {{ text: string }} SearchQuery */
-/** @typedef {{ products: SearchProduct[], collections: SearchCollection[], queries: SearchQuery[] }} SearchResults */
-/** @typedef {'idle' | 'loading' | 'ready' | 'empty' | 'error'} SearchState */
-/** @typedef {{ title?: string, price?: string, text?: string, image?: SearchImage | null }} BindValues */
+interface SearchImage {
+  url: string;
+  altText: string | null;
+}
+interface SearchProduct {
+  id: string;
+  handle: string;
+  title: string;
+  availableForSale: boolean;
+  featuredImage: SearchImage | null;
+  priceRange: { minVariantPrice: Money };
+}
+interface SearchCollection {
+  handle: string;
+  title: string;
+  image: SearchImage | null;
+}
+interface SearchQuery {
+  text: string;
+}
+export interface SearchResults {
+  products: SearchProduct[];
+  collections: SearchCollection[];
+  queries: SearchQuery[];
+}
+/** No results, or lists whose items have what `render` reads without a fallback. */
+const isSearchAnswer = shaped<{ predictiveSearch: SearchResults | null }>({
+  predictiveSearch: orNull({
+    products: [{ priceRange: 'object' }],
+    collections: ['object'],
+    queries: [{ text: 'string' }],
+  }),
+});
+type SearchState = 'idle' | 'loading' | 'ready' | 'empty' | 'error';
+interface BindValues {
+  title?: string;
+  price?: string;
+  text?: string;
+  image?: SearchImage | null;
+}
 
 const QUERY = `query TetherPredictive($q: String!, $limit: Int!) {
   predictiveSearch(query: $q, limit: $limit, limitScope: EACH, types: [PRODUCT, COLLECTION, QUERY]) {
@@ -49,31 +74,18 @@ const DEFAULT_LIMIT = 6;
 const DEFAULT_MIN_CHARACTERS = 2;
 const DEFAULT_ACTION = '/search';
 
-/** @type {WeakSet<Element>} */
-const mounted = new WeakSet();
+const mounted = new WeakSet<Element>();
 let searchBoxCount = 0;
 
-/**
- * @param {Element} el
- * @param {string} name
- * @param {number} fallback
- * @returns {number} The attribute as an integer; `fallback` when it is missing, zero or not a number.
- */
-function integerAttribute(el, name, fallback) {
+/** @returns The attribute as an integer; `fallback` when it is missing, zero or not a number. */
+function integerAttribute(el: Element, name: string, fallback: number): number {
   return parseInt(get(el, name) || '', 10) || fallback;
 }
 
-/**
- * @param {Element} node
- * @returns {Element | null} `node` when it is a link, else its first link.
- */
-const linkIn = (node) => (node.tagName === 'A' ? node : node.querySelector('a'));
+/** @returns `node` when it is a link, else its first link. */
+const linkIn = (node: Element): Element | null => (node.tagName === 'A' ? node : node.querySelector('a'));
 
-/**
- * @param {HTMLElement} node
- * @param {BindValues} values
- */
-function bindValues(node, values) {
+function bindValues(node: HTMLElement, values: BindValues) {
   qsa(node, sel('search-bind')).forEach((el) => {
     const field = get(el, 'search-bind');
     if (field === 'image') setImage(el, values.image?.url, values.image?.altText || values.title);
@@ -83,25 +95,30 @@ function bindValues(node, values) {
   });
 }
 
-/**
- * @param {Element} node
- * @param {string} href
- */
-function linkOption(node, href) {
+/** @param href `null` for a product without a page: the option shows, without a link. */
+function linkOption(node: Element, href: string | null) {
   const link = linkIn(node);
   if (!link) return;
-  link.setAttribute('href', href);
+  if (href) link.setAttribute('href', href);
   link.setAttribute('role', 'option');
 }
 
 /** One `[tether-search]` root: its input, its results and the search in flight. */
 class SearchBox {
-  /**
-   * @param {HTMLElement} root
-   * @param {HTMLInputElement} input
-   * @param {HTMLElement} results
-   */
-  constructor(root, input, results) {
+  readonly root: HTMLElement;
+  readonly input: HTMLInputElement;
+  readonly results: HTMLElement;
+  readonly limit: number;
+  readonly minCharacters: number;
+  readonly resultsId: string;
+  /** Counts searches, so only the latest one renders. */
+  searchNumber = 0;
+  timer: ReturnType<typeof setTimeout> | undefined = undefined;
+  lastTerm = '';
+  /** Results per term, for typing back and forth. */
+  readonly cache = new Map<string, SearchResults | null>();
+
+  constructor(root: HTMLElement, input: HTMLInputElement, results: HTMLElement) {
     this.root = root;
     this.input = input;
     this.results = results;
@@ -112,13 +129,6 @@ class SearchBox {
       results.id = `${cfg.prefix}-search-${searchBoxCount}`;
     }
     this.resultsId = results.id;
-    /** Counts searches, so only the latest one renders. */
-    this.searchNumber = 0;
-    /** @type {ReturnType<typeof setTimeout> | undefined} */
-    this.timer = undefined;
-    this.lastTerm = '';
-    /** @type {Map<string, SearchResults | null>} Results per term, for typing back and forth. */
-    this.cache = new Map();
     this.setUpAria();
     this.listen();
   }
@@ -149,17 +159,15 @@ class SearchBox {
     });
     document.addEventListener('click', (event) => {
       // A click event's target is always a node.
-      if (!this.root.contains(/** @type {Node | null} */ (event.target))) this.open(false);
+      if (!this.root.contains(event.target as Node | null)) this.open(false);
     });
   }
 
-  /** @param {SearchState} state */
-  setState(state) {
+  setState(state: SearchState) {
     this.root.setAttribute(attr('search-state'), state);
   }
 
-  /** @param {boolean} open */
-  open(open) {
+  open(open: boolean) {
     this.root.classList.toggle('is-open', open);
     this.results.hidden = !open;
     this.input.setAttribute('aria-expanded', String(open));
@@ -170,21 +178,15 @@ class SearchBox {
     return qsa(this.results, '[role="option"]');
   }
 
-  /**
-   * @param {string} term
-   * @returns {Promise<SearchResults | null>}
-   */
-  async fetchResults(term) {
+  async fetchResults(term: string): Promise<SearchResults | null> {
     const cached = this.cache.get(term);
     if (cached) return cached;
-    /** @type {{ predictiveSearch: SearchResults | null }} */
-    const data = await gql(QUERY, { q: term, limit: this.limit });
+    const data = await gql(QUERY, { q: term, limit: this.limit }, isSearchAnswer);
     this.cache.set(term, data.predictiveSearch);
     return data.predictiveSearch;
   }
 
-  /** @param {string} term */
-  async search(term) {
+  async search(term: string) {
     this.searchNumber += 1;
     const searchNumber = this.searchNumber;
     if (term.length < this.minCharacters) {
@@ -207,31 +209,21 @@ class SearchBox {
     }
   }
 
-  /**
-   * @template Item
-   * @param {string} name The list attribute, e.g. `search-products`.
-   * @param {readonly Item[]} items
-   * @param {(node: HTMLElement, item: Item) => void} render
-   */
-  fillList(name, items, render) {
+  /** @param name The list attribute, e.g. `search-products`. */
+  fillList<Item>(name: string, items: readonly Item[], render: (node: HTMLElement, item: Item) => void) {
     qsa(this.results, sel(name)).forEach((list) => {
       repeat(list, items, render);
       show(list, items.length > 0);
     });
   }
 
-  /** @param {string} text */
-  queryUrl(text) {
+  queryUrl(text: string) {
     const action = this.root.getAttribute('action') || DEFAULT_ACTION;
     const separator = action.includes('?') ? '&' : '?';
     return `${action}${separator}${this.input.name || 'q'}=${encodeURIComponent(text)}`;
   }
 
-  /**
-   * @param {SearchResults | null} results
-   * @param {string} term
-   */
-  render(results, term) {
+  render(results: SearchResults | null, term: string) {
     const products = results?.products ?? [];
     const collections = results?.collections ?? [];
     const queries = (results?.queries ?? []).filter((query) => query.text.toLowerCase() !== term.toLowerCase());
@@ -256,8 +248,7 @@ class SearchBox {
     emit('search', { term, products, collections, queries }, this.root);
   }
 
-  /** @param {number} count */
-  showCount(count) {
+  showCount(count: number) {
     qsa(this.root, sel('show')).forEach((el) => {
       const condition = get(el, 'show');
       if (condition === 'search-empty') show(el, count === 0);
@@ -269,11 +260,7 @@ class SearchBox {
     });
   }
 
-  /**
-   * @param {HTMLElement[]} options
-   * @param {number} index
-   */
-  highlight(options, index) {
+  highlight(options: HTMLElement[], index: number) {
     options.forEach((option, optionIndex) => {
       option.setAttribute('aria-selected', String(optionIndex === index));
     });
@@ -281,11 +268,10 @@ class SearchBox {
     if (!option) return;
     this.input.setAttribute('aria-activedescendant', option.id);
     // jsdom has no scrollIntoView.
-    /** @type {Partial<Pick<HTMLElement, 'scrollIntoView'>>} */ (option).scrollIntoView?.({ block: 'nearest' });
+    (option as Partial<Pick<HTMLElement, 'scrollIntoView'>>).scrollIntoView?.({ block: 'nearest' });
   }
 
-  /** @param {KeyboardEvent} event */
-  onKeydown(event) {
+  onKeydown(event: KeyboardEvent) {
     const options = this.options();
     const current = options.findIndex((option) => option.getAttribute('aria-selected') === 'true');
     if (event.key === 'ArrowDown' && options.length) {
@@ -306,18 +292,14 @@ class SearchBox {
 
 /**
  * Sets up every `[tether-search]` in `root` (and `root` itself) once.
- *
- * @param {ParentNode & Partial<Pick<Element, 'matches'>>} [root]
  */
-export function mountSearch(root = document) {
+export function mountSearch(root: ParentNode & Partial<Pick<Element, 'matches'>> = document): void {
   for (const el of within(root, sel('search'))) {
     if (mounted.has(el)) continue;
     mounted.add(el);
     // The markup names an input element; a site without one gets the first input.
-    const input = /** @type {HTMLInputElement | null} */ (
-      el.querySelector(sel('search-input')) ?? el.querySelector('input')
-    );
-    const results = /** @type {HTMLElement | null} */ (el.querySelector(sel('search-results')));
+    const input = el.querySelector<HTMLInputElement>(sel('search-input')) ?? el.querySelector('input');
+    const results = el.querySelector<HTMLElement>(sel('search-results'));
     if (input && results) new SearchBox(el, input, results);
   }
 }

package/src/selling-plans.ts

@@ -0,0 +1,145 @@
+/**
+ * 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 { fromMinorUnits, toMinorUnits } from './amounts.ts';
+import type { Money } from './shopify-values.ts';
+import type { SellingPlan, SellingPlanGroup, SellingPlanAllocation } from './fragments.ts';
+
+const PERCENT = 100;
+
+/** A plan with the group it belongs to. */
+export type PlanInGroup = SellingPlan & { group: SellingPlanGroup };
+export interface ProductWithPlans {
+  sellingPlanGroups?: { nodes: SellingPlanGroup[] } | null;
+}
+/** A variant as far as plans go. A cart line's variant has no allocations. */
+export interface VariantWithPlans {
+  price: Money;
+  sellingPlanAllocations?: { nodes: SellingPlanAllocation[] } | null;
+}
+export type PlanAdjustment =
+  { type: 'percentage'; value: number } | { type: 'amount'; value: Money } | { type: 'price'; value: Money };
+
+/**
+ * @param value A gid, a numeric id, or anything else.
+ * @param type The Shopify type, e.g. `ProductVariant`.
+ * @returns The gid of a numeric id; a gid or other value as written; `null` when empty.
+ */
+export function toGid(value: unknown, type: string): string | null {
+  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;
+}
+
+export const GID = {
+  product: (value: unknown) => toGid(value, 'Product'),
+  variant: (value: unknown) => toGid(value, 'ProductVariant'),
+  sellingPlan: (value: unknown) => toGid(value, 'SellingPlan'),
+};
+
+/** @returns All plans of the product, flattened. */
+export function allPlans(product: ProductWithPlans | null | undefined): PlanInGroup[] {
+  const groups = product?.sellingPlanGroups?.nodes ?? [];
+  return groups.flatMap((group) => group.sellingPlans.nodes.map((plan) => ({ ...plan, group })));
+}
+
+export function hasPlans(product: ProductWithPlans | null | undefined): boolean {
+  return allPlans(product).length > 0;
+}
+
+/** @returns The variant's allocation on the plan; `null` when the variant isn't in it. */
+export function allocationFor(
+  variant: VariantWithPlans | null | undefined,
+  planId: string | null | undefined,
+): SellingPlanAllocation | null {
+  if (!variant || !planId) return null;
+  const allocations = variant.sellingPlanAllocations?.nodes ?? [];
+  return allocations.find((allocation) => allocation.sellingPlan.id === planId) ?? null;
+}
+
+/** @returns The plans this variant can be bought on. */
+export function plansForVariant(
+  product: ProductWithPlans | null | undefined,
+  variant: VariantWithPlans | null | undefined,
+): PlanInGroup[] {
+  return allPlans(product).filter((plan) => allocationFor(variant, plan.id));
+}
+
+/** @returns The price per delivery on the plan; the one-time price when the variant isn't on it. */
+export function planPrice(
+  variant: VariantWithPlans | null | undefined,
+  planId: string | null | undefined,
+): Money | null {
+  const adjustment = allocationFor(variant, planId)?.priceAdjustments[0];
+  return adjustment?.perDeliveryPrice ?? adjustment?.price ?? variant?.price ?? null;
+}
+
+/** @returns What the customer pays at checkout on the plan (prepaid plans charge more up front). */
+export function planCheckoutCharge(
+  variant: VariantWithPlans | null | undefined,
+  planId: string | null | undefined,
+): Money | null {
+  const allocation = allocationFor(variant, planId);
+  return allocation?.checkoutChargeAmount ?? allocation?.priceAdjustments[0]?.price ?? variant?.price ?? null;
+}
+
+/** @returns What the plan saves on the one-time price; no amount and 0% when it saves nothing. */
+export function planSavings(
+  variant: VariantWithPlans | null | undefined,
+  planId: string | null | undefined,
+): { amount: Money | null; percentage: number } {
+  const onPlanPrice = planPrice(variant, planId);
+  if (!variant || !onPlanPrice) return { amount: null, percentage: 0 };
+  const oneTime = parseFloat(variant.price.amount);
+  const onPlan = parseFloat(onPlanPrice.amount);
+  if (!Number.isFinite(oneTime) || !Number.isFinite(onPlan) || oneTime <= 0 || onPlan >= oneTime) {
+    return { amount: null, percentage: 0 };
+  }
+  const saved = toMinorUnits(variant.price) - toMinorUnits(onPlanPrice);
+  return {
+    amount: fromMinorUnits(saved, variant.price.currencyCode),
+    percentage: Math.round((1 - onPlan / oneTime) * PERCENT),
+  };
+}
+
+/**
+ * @returns The plan's own discount, whatever the variant: a percentage, a fixed amount off or a fixed price.
+ */
+export function planAdjustment(plan: Pick<SellingPlan, 'priceAdjustments'> | null | undefined): PlanAdjustment | 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"`.
+ */
+export function findPlan(
+  product: ProductWithPlans | null | undefined,
+  ref: string | null | undefined,
+): PlanInGroup | null {
+  if (!ref) return null;
+  const plans = allPlans(product);
+  const gid = GID.sellingPlan(ref);
+  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.ts

@@ -0,0 +1,211 @@
+/**
+ * `@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, resolveConfig } from './config.ts';
+import { request, hasData, withContext, TetherError } from './client.ts';
+import * as plans from './selling-plans.ts';
+import { imageUrl, formatPercent } from './dom.ts';
+import { initialState } from './initial.ts';
+import { STORE_ENV_NAMES, formatMoney, productKey, productUrl as productUrlFor } from './shopify-values.ts';
+import { createCatalog } from './storefront/catalog.ts';
+import { jsonLdData, scriptJson } from './storefront/json-ld.ts';
+import type { TetherConfig, TetherOptions } from './config.ts';
+import type { Product } from './fragments.ts';
+import type { Money } from './shopify-values.ts';
+import type { InitialOptions, InitialState } from './initial.ts';
+import type { JsonLdOptions } from './storefront/json-ld.ts';
+
+export { imageUrl, initialState, formatPercent, formatMoney, productKey };
+
+export { TetherError, plans, withContext };
+
+// The types a site uses by name, under the names the docs give them.
+export type { StorefrontOptions, HydrateOptions };
+export type { Money } from './shopify-values.ts';
+export type { Product as ShopifyProduct, ProductVariant as ShopifyVariant } from './fragments.ts';
+export type { ShopifyCart, ShopifyCartLine } from './cart/store.ts';
+export type { Collection as ShopifyCollection, ProductQuery } from './loader.ts';
+export type { InitialOptions, InitialState } from './initial.ts';
+export type { ImageSize } from './images.ts';
+export type { JsonLdOptions } from './storefront/json-ld.ts';
+/** What `createStorefront()` returns. */
+export type Storefront = ReturnType<typeof createStorefront>;
+
+/** The options only a storefront has. */
+interface ServerOptions {
+  /** Replaces the global `fetch` (tests, caching). */
+  fetch?: typeof fetch;
+  /** Products per request for `allProducts()` (default 25). */
+  pageSize?: number;
+  /** The site's address, for product URLs in `jsonLd()` without `url`. */
+  siteUrl?: string;
+}
+
+/**
+ * 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.
+ */
+type StorefrontOptions = TetherOptions & ServerOptions & StoreEnv;
+
+/** The environment names that give the domain and the token. */
+type StoreEnv = Partial<Record<(typeof STORE_ENV_NAMES)['domain' | 'token'][number], string>>;
+
+type ServerConfig = TetherConfig & ServerOptions;
+
+interface HydrateOptions {
+  card?: boolean;
+  images?: number;
+}
+
+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;
+
+/**
+ * @returns `productPath` `/products` → `/products/<handle>`; templates with `{handle}` and `{id}` work too. `null` when
+ *   the path needs a handle or an id that is empty.
+ */
+export function productUrl(
+  handle: string,
+  { productPath = DEFAULTS.productPath, id }: { productPath?: string; id?: string } = {},
+): string | null {
+  return productUrlFor(productPath, handle, id);
+}
+
+/** @returns The first of the `names` set in `options`, `''` without one. */
+function fromEnv(options: StoreEnv, names: readonly (keyof StoreEnv)[]): string {
+  for (const name of names) {
+    const value = options[name];
+    if (typeof value === 'string' && value) return value;
+  }
+  return '';
+}
+
+/**
+ * @returns 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: StorefrontOptions): ServerConfig {
+  const known: Record<string, unknown> = {};
+  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 : '';
+  const conf: ServerConfig = resolveConfig({
+    // Only config keys, each parsed by `resolveConfig`.
+    ...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;
+}
+
+/** @returns `pageSize` when it is a positive integer, else the default. */
+const validPageSize = (pageSize: number | undefined): number =>
+  typeof pageSize === 'number' && Number.isInteger(pageSize) && pageSize > 0 ? pageSize : DEFAULT_PAGE_SIZE;
+
+/**
+ * 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.
+ */
+function cardOf(product: Product, images: number): Product {
+  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 })) },
+  };
+}
+
+/**
+ * A storefront: the store's products and collections for the server, and the tags that hand them to the page.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without a domain and a token.
+ */
+export function createStorefront(options: StorefrontOptions = {}) {
+  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 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 options `card: true` for lists: about 40% smaller (see `cardOf`). The full product comes with the
+   *   background refresh.
+   */
+  function hydrate(
+    products: Product | null | undefined | (Product | null | undefined)[],
+    { card = false, images = DEFAULT_CARD_IMAGES }: HydrateOptions = {},
+  ): string {
+    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>`;
+  }
+
+  /** @returns The `<script type="application/ld+json">` tag, `''` without a product. */
+  function jsonLd(product: Product | null | undefined, jsonLdOptions: JsonLdOptions = {}): string {
+    if (!product) return '';
+    return `<script type="application/ld+json">${scriptJson(jsonLdData(product, jsonLdOptions, site))}</script>`;
+  }
+
+  /** `initialState()` with the storefront's `defaultPurchase` and `lowStock`. */
+  function storefrontInitialState(product: Product, initialOptions?: InitialOptions): InitialState;
+  function storefrontInitialState(
+    product: Product | null | undefined,
+    initialOptions?: InitialOptions,
+  ): InitialState | null;
+  function storefrontInitialState(
+    product: Product | null | undefined,
+    initialOptions: InitialOptions = {},
+  ): InitialState | null {
+    return initialState(product, { defaultPurchase: conf.defaultPurchase, lowStock: conf.lowStock, ...initialOptions });
+  }
+
+  return {
+    config: conf,
+    query: <T>(query: string, variables?: Record<string, unknown>, requestOptions?: { context?: boolean }) =>
+      // The caller's own query text decides the shape of `data`, and the caller's `T` states it.
+      request(conf, query, variables ?? {}, hasData, requestOptions) as Promise<T>,
+    ...catalog,
+    hydrate,
+    formatMoney: (money: Money | null | undefined, locale: string | undefined = conf.locale) =>
+      formatMoney(money, locale),
+    formatPercent: (percentage: number, locale: string | undefined = conf.locale) => formatPercent(percentage, locale),
+    imageUrl,
+    jsonLd,
+    jsonLdData: (product: Product | null | undefined, jsonLdOptions: JsonLdOptions = {}) =>
+      jsonLdData(product, jsonLdOptions, site),
+    initialState: storefrontInitialState,
+    productUrl: (handle: string, urlOptions: { productPath?: string; id?: string } = {}) =>
+      productUrl(handle, { productPath: conf.productPath, ...urlOptions }),
+    plans,
+  };
+}