@occluze/tether 0.6.8 → 0.7.0

package/src/server.js

@@ -1,215 +0,0 @@
-/**
- * `@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.js';
-import { request, withContext, TetherError } from './client.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, formatMoney, productKey };
-
-export { TetherError, plans, withContext };
-
-/**
- * @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`.
- */
-
-/**
- * @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.
- */
-
-/** @typedef {TetherConfig & ServerOptions} ServerConfig */
-
-/** @typedef {{ card?: boolean, images?: number }} HydrateOptions */
-
-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;
-
-/**
- * @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);
-}
-
-/**
- * @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 '';
-}
-
-/**
- * @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;
-}
-
-/**
- * @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;
-
-/**
- * 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 })) },
-  };
-}
-
-/**
- * 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 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.
-   */
-  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>`;
-  }
-
-  /**
-   * @param {Product | null | undefined} product
-   * @param {JsonLdOptions} [jsonLdOptions]
-   * @returns {string} The `<script type="application/ld+json">` tag, `''` without a product.
-   */
-  function jsonLd(product, jsonLdOptions = {}) {
-    if (!product) return '';
-    return `<script type="application/ld+json">${scriptJson(jsonLdData(product, jsonLdOptions, site))}</script>`;
-  }
-
-  return {
-    config: conf,
-    /**
-     * @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),
-    /**
-     * @param {number} percentage
-     * @param {string | undefined} [locale]
-     */
-    formatPercent: (percentage, locale = conf.locale) => formatPercent(percentage, locale),
-    imageUrl,
-    jsonLd,
-    /**
-     * @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,
-  };
-}

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/types/astro.d.ts

@@ -1,28 +0,0 @@
-import type { TetherConfig } from './index.js';
-
-type Serializable<T> = {
-  [
-    K in keyof T as T[K] extends ((...args: any[]) => any) | null | undefined
-      ? Exclude<T[K], null | undefined> extends (...args: any[]) => any
-        ? never
-        : K
-      : K
-  ]: T[K];
-};
-
-export interface TetherAstroOptions extends Partial<Serializable<TetherConfig>> {
-  /** Add the Tether script to every page (default true). False: import and init it yourself. */
-  inject?: boolean;
-  /** Files that restart the dev server when they change (default: src/shop.config.js/.mjs/.ts). */
-  watch?: string[];
-}
-
-/**
- * Astro integration: Tether on every page, store and token from .env
- * (PUBLIC_SHOPIFY_DOMAIN, PUBLIC_SHOPIFY_STOREFRONT_TOKEN). Functions (onError, hooks) go in
- * window.TETHER_CONFIG in your layout.
- */
-export default function tether(options?: TetherAstroOptions): {
-  name: string;
-  hooks: Record<string, (...args: any[]) => unknown>;
-};

package/types/barba.d.ts

@@ -1,16 +0,0 @@
-import type { TetherConfig } from './index.js';
-
-export interface BarbaPresetOptions {
-  gsap?: () => unknown;
-  lenis?: (() => { resize?(): void; stop?(): void; start?(): void } | null | undefined) | null;
-  scrollTrigger?: () => unknown;
-  lockScroll?: ((drawer: HTMLElement) => void) | null;
-  unlockScroll?: (() => void) | null;
-  onResize?: (() => void) | null;
-  onValueChange?: ((el: HTMLElement, previousText: string) => void) | null;
-  animateLines?: boolean;
-  lineDuration?: number;
-}
-
-/** Hooks for sites with page transitions, smooth scroll and GSAP: spread into Tether.init(). */
-export declare function barbaPreset(options?: BarbaPresetOptions): Partial<TetherConfig>;