@occluze/tether 0.6.8 → 0.7.1

package/src/shopify-values.js

@@ -1,89 +0,0 @@
-/**
- * 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,126 +0,0 @@
-/**
- * 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';
-
-/**
- * @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_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(source || 'handle');
-  }
-  return { key: key?.trim() || null, fromUrl: true, raw };
-}
-
-/** @type {readonly ScopeStatus[]} The values of `tether-show` that follow the scope's state. */
-export const STATUS_KEYS = ['loading', 'ready', 'error', 'not-found'];
-
-/**
- * @param {unknown} value
- * @returns {value is ScopeStatus}
- */
-const isScopeStatus = (value) => STATUS_KEYS.some((status) => status === value);
-
-/**
- * @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';
-
-/** @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;
-
-/**
- * @param {unknown} error
- * @returns {string} The error's code for `tether-error`, `error` without one.
- */
-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 (failed) root.setAttribute(attr('error'), notFound ? 'not-found' : errorCode(error));
-  else root.removeAttribute(attr('error'));
-
-  scoped(root, sel('show'), boundary()).forEach((el) => {
-    const shows = get(el, 'show');
-    if (isScopeStatus(shows)) show(el, shows === status);
-  });
-
-  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

@@ -1,199 +0,0 @@
-/**
- * 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

@@ -1,167 +0,0 @@
-/**
- * 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)),
-  });
-}