@occluze/tether 0.7.0 → 0.7.1

package/src/server.ts

@@ -1,211 +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.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,
-  };
-}

package/src/shopify-values.ts

@@ -1,91 +0,0 @@
-/**
- * Conversions of Shopify values that the browser script and the server helpers (`src/server.ts`, `src/astro.ts`)
- * share, so a server-rendered page and the script that takes it over agree. Pure: no config, no DOM.
- */
-
-/** A Storefront API `MoneyV2`. */
-export interface Money {
-  amount: string;
-  currencyCode: string;
-}
-
-/** 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'],
-} as const;
-
-/**
- * True for an absolute https URL. Links and redirects that come from Shopify (checkout, status pages,
- * tracking) are only used when this holds.
- */
-export function isHttpsUrl(url: unknown): url is string {
-  if (typeof url !== 'string') return false;
-  try {
-    return new URL(url).protocol === 'https:';
-  } catch {
-    // Not an absolute URL, so not an https one.
-    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.
- */
-export function isSecretShopifyToken(token: string): boolean {
-  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 locale An `Intl` locale; the runtime's own when absent.
- * @returns `''` without money or with an amount that isn't a number.
- */
-export function formatMoney(money: Money | null | undefined, locale: string | undefined): string {
-  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 id A product gid or numeric id.
- * @returns `null` when the path needs a handle or an id the product lacks: no link beats a wrong one.
- */
-export function productUrl(productPath: string, handle: string | null | undefined, id?: string | null): string | null {
-  if (!/\{(handle|id)\}/.test(productPath)) {
-    return handle ? `${productPath.replace(/\/$/, '')}/${encodeURIComponent(handle)}` : null;
-  }
-  const numericId = id ? (id.split('/').at(-1) ?? '') : '';
-  if (productPath.includes('{handle}') && !handle) return null;
-  if (productPath.includes('{id}') && !numericId) return null;
-  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 raw A handle, a numeric id, a gid or a product URL (`…/products/<handle>`).
- */
-export function productKey(raw: string | number | null | undefined): string | null {
-  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.ts

@@ -1,106 +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.ts';
-
-interface ProductKeySource {
-  /** The product to load; `null` when the attribute or the page URL has none. */
-  key: string | null;
-  /** The key comes from the page URL (`url:…`). */
-  fromUrl: boolean;
-  /** The attribute's value as written. */
-  raw: string;
-}
-
-type ScopeStatus = 'loading' | 'ready' | 'error' | 'not-found';
-
-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. */
-function decodePathSegment(segment: string): string {
-  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 name The attribute, without prefix.
- */
-export function resolveProductKey(
-  el: Element,
-  location: Pick<Location, 'pathname' | 'search'> = window.location,
-  name = 'product',
-): ProductKeySource {
-  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 };
-}
-
-/** The values of `tether-show` that follow the scope's state. */
-export const STATUS_KEYS: readonly ScopeStatus[] = ['loading', 'ready', 'error', 'not-found'];
-
-const isScopeStatus = (value: unknown): value is ScopeStatus => STATUS_KEYS.some((status) => status === value);
-
-/** @returns The error's `code` (a `TetherError` has one). */
-const codeOf = (error: unknown): unknown =>
-  typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
-
-/** @returns True for a `TetherError` with code `NOT_FOUND`. */
-export const isNotFound = (error: unknown): boolean => codeOf(error) === 'NOT_FOUND';
-
-/** @returns The selector of every scope that owns its state elements; the nearest one wins. */
-export const boundary = (): string =>
-  ['product', 'collection', 'products', 'recommendations'].map((name) => sel(name)).join(',');
-
-/** @returns True when `el` belongs to the scope `root`, not to a scope nested in it. */
-export const ownedBy = (el: Element, root: Element): boolean =>
-  el === root || el.parentElement?.closest(boundary()) === root;
-
-/** @returns The error's code for `tether-error`, `error` without one. */
-function errorCode(error: unknown): string {
-  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.
- */
-export function setScopeStatus(root: Element, status: ScopeStatus, error?: unknown): void {
-  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/storage.ts

@@ -1,34 +0,0 @@
-/**
- * The browser's `localStorage` and `sessionStorage`, which may be blocked: accessing them throws in private mode, in
- * sandboxed frames and where the visitor blocks site data, and writing throws when they are full. Tether then keeps
- * nothing between pages: a read finds nothing, and a write or removal does nothing. Each call catches on its own, so a
- * blocked area never stops a call on the other.
- */
-
-type StorageArea = 'localStorage' | 'sessionStorage';
-
-/** @returns `null` when nothing is stored under `key`, or the storage is blocked. */
-export function getStored(key: string, area: StorageArea = 'localStorage'): string | null {
-  try {
-    return window[area].getItem(key);
-  } catch {
-    // Blocked storage holds nothing: see the file's comment.
-    return null;
-  }
-}
-
-export function setStored(key: string, value: string, area: StorageArea = 'localStorage'): void {
-  try {
-    window[area].setItem(key, value);
-  } catch {
-    // Blocked or full storage keeps nothing: see the file's comment.
-  }
-}
-
-export function removeStored(key: string, area: StorageArea = 'localStorage'): void {
-  try {
-    window[area].removeItem(key);
-  } catch {
-    // Blocked storage has nothing to remove: see the file's comment.
-  }
-}