@occluze/tether 0.6.8 → 0.7.0

package/src/cart/store.js

@@ -1,326 +0,0 @@
-/**
- * The cart on this page: what Shopify last said about it (`CartStatus`), the quantities quick clicks asked for, the
- * customer it belongs to, and the one queue every change goes through. A change of what the page shows goes through
- * here, so the document (`renderCart`) and the listeners (`tether:cart-updated`) always see the store's cart.
- */
-import { cfg } from '../config.js';
-import { emit } from '../dom.js';
-import { isOpen } from './drawer.js';
-import { renderCart, quantityOf, showSavedCount } from './render.js';
-/** @import { CartWarning } from '../config.js' */
-/** @import { Image } from '../fragments.js' */
-/** @import { Money } from '../shopify-values.js' */
-
-/** @typedef {{ key: string, value: string }} Attribute */
-/**
- * @typedef {object} CartVariant A line's `merchandise`: Shopify's `Merchandise` union has only `ProductVariant`.
- * @property {string} id
- * @property {string} title
- * @property {string | null} sku
- * @property {boolean} availableForSale
- * @property {boolean} requiresShipping
- * @property {number | null} [quantityAvailable] Absent when the store's token can't read inventory.
- * @property {Image | null} image
- * @property {Money} price
- * @property {Money | null} compareAtPrice
- * @property {{ name: string, value: string }[]} selectedOptions
- * @property {{ id: string, title: string, handle: string, vendor: string, featuredImage: Image | null }} product
- */
-/**
- * @typedef {object} LinePlanAllocation
- * @property {{ id: string, name: string, description: string | null, recurringDeliveries: boolean,
- *   options: { name: string, value: string }[] }} sellingPlan
- * @property {Money} checkoutChargeAmount
- * @property {{ price: Money, compareAtPrice: Money, perDeliveryPrice: Money }[]} priceAdjustments
- */
-/**
- * @typedef {object} ShopifyCartLine
- * @property {string} id
- * @property {number} quantity
- * @property {Attribute[]} attributes
- * @property {{ totalAmount: Money, subtotalAmount: Money, amountPerQuantity: Money,
- *   compareAtAmountPerQuantity: Money | null }} cost
- * @property {{ discountedAmount: Money }[]} discountAllocations
- * @property {LinePlanAllocation | null} sellingPlanAllocation
- * @property {CartVariant} merchandise
- * @property {{ id: string, quantity: number, merchandise: { id: string, title: string,
- *   product: { title: string, handle: string } } }[]} [lineComponents] Only on a bundle (`ComponentizableCartLine`).
- */
-/**
- * @typedef {object} ShopifyCart The fields of `fragment TetherCart`.
- * @property {string} id
- * @property {string} checkoutUrl
- * @property {number} totalQuantity
- * @property {string | null} note
- * @property {string} createdAt
- * @property {string} updatedAt
- * @property {Attribute[]} attributes
- * @property {{ countryCode: string | null, email: string | null }} buyerIdentity
- * @property {{ code: string, applicable: boolean }[]} discountCodes
- * @property {{ subtotalAmount: Money, totalAmount: Money, checkoutChargeAmount: Money }} cost
- * @property {{ nodes: ShopifyCartLine[] }} lines
- */
-
-/**
- * @typedef {{ kind: 'unknown' }
- *   | { kind: 'empty' }
- *   | { kind: 'ready', cart: ShopifyCart }
- *   | { kind: 'error', error: unknown, cart: ShopifyCart | null }} CartStatus
- *   `unknown` until the saved cart has loaded (the page's own markup shows); `empty` without a cart (none saved, or
- *   Shopify no longer has it); `error` after a failed load or change, with the cart as Shopify last sent it.
- */
-
-/** @typedef {{ quantity: number }} PendingQuantity What one quick +/- click asked for; a newer click replaces it. */
-
-/**
- * @typedef {object} CustomerLink What the account part sets while a customer is logged in.
- * @property {string | null} accessToken The Customer Account API token: carts created now belong to the customer.
- * @property {(() => Promise<string | null>) | null} beforeCheckout The account's own checkout URL; `null` from it, or
- *   no function, uses the cart's.
- */
-
-/**
- * @typedef {object} CartMeta The second argument of a `subscribe` listener.
- * @property {boolean} open
- * @property {number} count
- * @property {boolean} loaded
- * @property {readonly CartWarning[]} warnings
- */
-
-/** @type {CartStatus} */
-let status = { kind: 'unknown' };
-
-/** @type {readonly CartWarning[]} Shopify's notes on the last change. */
-let warnings = [];
-
-/** @type {Map<string, PendingQuantity>} Line id → what quick +/- clicks asked for, until Shopify has answered. */
-export const pendingQuantities = new Map();
-
-/** @type {CustomerLink} */
-export const customer = { accessToken: null, beforeCheckout: null };
-
-/** @returns {CartStatus} */
-export const cartStatus = () => status;
-
-/** @returns {ShopifyCart | null} The cart as Shopify last sent it. */
-export function currentCart() {
-  switch (status.kind) {
-    case 'ready':
-    case 'error':
-      return status.cart;
-    case 'unknown':
-    case 'empty':
-      return null;
-  }
-}
-
-/** @returns {readonly CartWarning[]} */
-export const currentWarnings = () => warnings;
-
-/**
- * @param {ShopifyCart | null} cart
- * @returns {CartStatus}
- */
-const statusOf = (cart) => (cart ? { kind: 'ready', cart } : { kind: 'empty' });
-
-const seenKey = () => `${cfg.storageKey}:seen`;
-
-/**
- * localStorage throws in private mode and where the visitor blocks site data: the cart then lasts for this page.
- *
- * @param {string} key
- * @returns {string | null}
- */
-function readStorageIfAllowed(key) {
-  try {
-    return localStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Like `readStorageIfAllowed`: without storage, nothing is remembered.
- *
- * @param {string} key
- * @param {string | null} value `null` removes the key.
- */
-function writeStorageIfAllowed(key, value) {
-  try {
-    if (value === null) localStorage.removeItem(key);
-    else localStorage.setItem(key, value);
-  } catch {
-    // Private mode or blocked storage: see readStorageIfAllowed.
-  }
-}
-
-/** @returns {string | null} The id of the visitor's cart, kept across pages. */
-export const savedCartId = () => readStorageIfAllowed(cfg.storageKey) || null;
-
-/** Forgets the saved cart, which Shopify no longer has. */
-export function forgetSavedCart() {
-  writeStorageIfAllowed(cfg.storageKey, null);
-}
-
-/**
- * Keeps a cart Shopify sent without showing it, for an answer a newer change will replace.
- *
- * @param {ShopifyCart | null} cart
- */
-export function keepQuietly(cart) {
-  status = statusOf(cart);
-  if (cart) writeStorageIfAllowed(cfg.storageKey, cart.id);
-}
-
-/** Renders the document with the store's cart. */
-export function render() {
-  renderCart({
-    cart: currentCart(),
-    warnings,
-    pending: pendingQuantities,
-    failed: status.kind === 'error',
-  });
-}
-
-/**
- * @param {string} reason The `reason` of `tether:cart-updated`.
- */
-export function announce(reason) {
-  render();
-  emit('cart-updated', { cart: currentCart(), reason });
-}
-
-/**
- * Keeps a cart Shopify sent after a change, shows it, and tells this page and the visitor's other tabs.
- *
- * @param {ShopifyCart | null} cart
- * @param {string} reason
- * @returns {ShopifyCart | null} `cart`.
- */
-export function commit(cart, reason) {
-  keepQuietly(cart);
-  // Other tabs reload the cart on this storage event; the next page shows the count before its cart has loaded.
-  writeStorageIfAllowed(seenKey(), `${Date.now()}|${cart?.totalQuantity ?? 0}`);
-  announce(reason);
-  return cart;
-}
-
-/**
- * The outcome of loading the saved cart: the cart, `null` when there is none, or the failure.
- *
- * @param {{ kind: 'loaded', cart: ShopifyCart | null } | { kind: 'failed', error: unknown }} outcome
- */
-export function settleLoad(outcome) {
-  status = outcome.kind === 'loaded' ? statusOf(outcome.cart) : { kind: 'error', error: outcome.error, cart: null };
-  announce('load');
-}
-
-/**
- * Sets or clears the failure without rendering, for `Tether.cart.lastError`, which the public types declare writable.
- *
- * @param {unknown} error `null` or `undefined` clears it.
- */
-export function setFailure(error) {
-  const cart = currentCart();
-  status = error == null ? statusOf(cart) : { kind: 'error', error, cart };
-}
-
-/** Until the saved cart has loaded, the counts show the count it had on the last page instead of the page's 0. */
-export function showLastKnownCount() {
-  if (status.kind !== 'unknown') return;
-  const count = readStorageIfAllowed(seenKey())?.split('|')[1];
-  if (count) showSavedCount(count);
-}
-
-/**
- * Sets Shopify's notes on the last change: each message once, in the site's words (`warningText`).
- *
- * @param {readonly CartWarning[]} notes
- */
-export function setWarnings(notes) {
-  warnings = notes
-    .filter((note, index) => notes.findIndex((other) => other.message === note.message) === index)
-    .map((note) => ({ ...note, message: cfg.warningText?.(note) || note.message }));
-  if (warnings.length) emit('cart-warning', { warnings });
-}
-
-/** The queue only waits for a task: its result, or failure, reaches the caller through the promise `run` returns. */
-const waitOnly = () => undefined;
-
-/**
- * @returns {<T>(task: () => Promise<T>) => Promise<T>} A runner that starts each task once the one before has
- *   settled, whether it succeeded or failed.
- */
-export function serial() {
-  /** @type {Promise<unknown>} */
-  let previous = Promise.resolve();
-  return (task) => {
-    const run = previous.then(task);
-    previous = run.then(waitOnly, waitOnly);
-    return run;
-  };
-}
-
-const runInOrder = serial();
-
-/**
- * Runs a cart change after the ones before it, so quick clicks never race. A failure sets the `error` status (shown by
- * `tether-show="cart-error"` until the next change succeeds), emits `tether:cart-error` and rejects.
- *
- * @template T
- * @param {() => Promise<T>} task
- * @returns {Promise<T>}
- */
-export function enqueue(task) {
-  return runInOrder(task).then(
-    (value) => {
-      if (status.kind === 'error') {
-        status = statusOf(status.cart);
-        render();
-      }
-      return value;
-    },
-    (/** @type {unknown} */ error) => {
-      status = { kind: 'error', error, cart: currentCart() };
-      render();
-      emit('cart-error', { error });
-      throw error;
-    },
-  );
-}
-
-/**
- * @param {ShopifyCartLine} line
- * @returns {number} The quantity to show for `line`.
- */
-export const pendingQuantityOf = (line) => quantityOf(line, pendingQuantities);
-
-/** @returns {CartMeta} */
-const meta = () => ({
-  open: isOpen(),
-  count: currentCart()?.totalQuantity ?? 0,
-  loaded: status.kind !== 'unknown',
-  warnings,
-});
-
-/**
- * Calls `listener` now and after every change of the cart or the drawer.
- *
- * @param {(cart: ShopifyCart | null, meta: CartMeta) => void} listener
- * @returns {() => void} Stops listening.
- */
-export function subscribe(listener) {
-  const events = ['cart-updated', 'cart-toggled'].map((name) => `${cfg.prefix}:${name}`);
-  const call = () => {
-    listener(currentCart(), meta());
-  };
-  events.forEach((name) => {
-    document.addEventListener(name, call);
-  });
-  call();
-  return () => {
-    events.forEach((name) => {
-      document.removeEventListener(name, call);
-    });
-  };
-}

package/src/client.js

@@ -1,267 +0,0 @@
-/**
- * The one Storefront API client: a fetch wrapper that adds the market (`@inContext`), retries what Shopify asks to be
- * retried, and turns every failure into a `TetherError`. The browser (`gql`, also `Tether.query()`) and the server
- * helpers (`request` with their own config) share it.
- */
-import { cfg, log } from './config.js';
-import { toCountry, toLanguage } from './market-codes.js';
-/** @import { TetherConfig } from './config.js' */
-
-/**
- * @typedef {'NOT_FOUND' | 'NETWORK' | 'NOT_CONFIGURED' | 'NOT_LOGGED_IN' | 'NOT_ALLOWED' | 'INVALID'
- *   | 'INVALID_COUNTRY' | 'INVALID_DISCOUNT' | 'SESSION_ENDED' | 'TOKEN_FAILED' | 'ERROR' | `HTTP_${number}`}
- *   TetherErrorCode
- */
-/** @typedef {{ message: string, extensions?: { code?: string } }} GraphQLError */
-/** @typedef {{ data?: unknown, errors?: GraphQLError[] }} GraphQLResponse The response shape the GraphQL spec sets. */
-/** @typedef {{ message: string, field?: string[] | null, code?: string | null }} UserError */
-/**
- * @typedef {object} TetherErrorDetails
- * @property {TetherErrorCode} [code] Default `HTTP_<status>` with a status, else `ERROR`.
- * @property {number} [status] The HTTP status of the response that failed.
- * @property {GraphQLError[]} [errors] The GraphQL errors of that response.
- * @property {readonly UserError[]} [userErrors] A mutation's user errors.
- */
-
-export class TetherError extends Error {
-  /**
-   * @param {string} message
-   * @param {TetherErrorDetails} [details]
-   */
-  constructor(message, { status, errors, userErrors, code } = {}) {
-    super(message);
-    this.name = 'TetherError';
-    /** @type {TetherErrorCode} */
-    this.code = code ?? (status ? `HTTP_${status}` : 'ERROR');
-    /** @type {number | undefined} */
-    this.status = status;
-    /** @type {GraphQLError[] | undefined} */
-    this.errors = errors;
-    /** @type {readonly UserError[] | undefined} */
-    this.userErrors = userErrors;
-  }
-}
-
-/**
- * What a request needs from a config: the browser's `cfg`, or a config the server helpers build.
- *
- * @typedef {Pick<TetherConfig, 'domain' | 'token' | 'apiVersion' | 'country' | 'language' | 'maxAge' | 'retries'>
- *   & { fetch?: typeof fetch }} StorefrontConfig
- */
-/** @typedef {{ context?: boolean }} RequestOptions `context: false` sends the query without `@inContext`. */
-
-/**
- * @param {Pick<TetherConfig, 'domain' | 'apiVersion'>} [conf]
- * @returns {string} The Storefront GraphQL endpoint of `conf`'s store.
- */
-export function endpoint(conf = cfg) {
-  return `https://${conf.domain}/api/${conf.apiVersion}/graphql.json`;
-}
-
-/**
- * Adds @inContext(country, language) to the first operation in the document, so prices, currency and translations
- * follow the configured market. Operations are always written first, fragments after, so the first match is the
- * operation. A country or language that isn't a valid code is left out.
- *
- * @param {string} query
- * @param {{ country?: string | undefined, language?: string | undefined }} [ctx]
- * @returns {string}
- */
-export function withContext(query, ctx = cfg) {
-  const args = [];
-  const country = toCountry(ctx.country);
-  const language = toLanguage(ctx.language);
-  if (country) args.push(`country: ${country}`);
-  if (language) args.push(`language: ${language}`);
-  if (!args.length || query.includes('@inContext')) return query;
-
-  const tag = `@inContext(${args.join(', ')})`;
-  // Named (query Name($x: T)), anonymous (query { … }) and shorthand ({ … }) queries.
-  if (/^\s*\{/.test(query)) return `query ${tag} ${query.trimStart()}`;
-  return query.replace(/^(\s*(?:query|mutation)(?:\s+\w+)?\s*(?:\([^)]*\))?)/, `$1 ${tag}`);
-}
-
-/** Backoff after a network error or a 429/5xx: this times 2^attempt. */
-const RETRY_BACKOFF_MS = 300;
-/** Backoff after Shopify's `THROTTLED` error, which asks for a longer wait: this times 2^attempt. */
-const THROTTLE_BACKOFF_MS = 500;
-/** Shopify's status for a request its bot protection rejected; retrying doesn't help. */
-const SECURITY_REJECTION = 430;
-
-/**
- * `quantityAvailable` needs the token's `unauthenticated_read_product_inventory` scope; without it Shopify refuses the
- * whole query with an error naming the field. That refusal is learned once per page and store: every later query to
- * the store goes out without the field, so stock levels are unknown and everything else works for one extra request.
- */
-const INVENTORY_FIELD = 'quantityAvailable';
-
-/** @type {Set<string>} The stores (domain, version and token) whose token can't read inventory. */
-const storesWithoutInventory = new Set();
-
-/** @param {StorefrontConfig} conf */
-const storeOf = (conf) => `${conf.domain} ${conf.apiVersion} ${conf.token}`;
-
-/** @param {number} ms */
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * What a status means, for errors Shopify sends without a message (401/403 have none).
- *
- * @param {number} status
- * @param {StorefrontConfig} conf
- */
-function statusText(status, conf) {
-  if (status === 401 || status === 403) {
-    const adminHint = conf.token.startsWith('shpat_') ? ', not an Admin API token (shpat_…)' : '';
-    return `Shopify rejected the Storefront token for ${conf.domain} (${status}): use the public Storefront API token (Headless channel)${adminHint}`;
-  }
-  if (status === 404) {
-    return `Store or API version not found (404): check domain ${conf.domain} and apiVersion ${conf.apiVersion}`;
-  }
-  return `HTTP ${status} from ${conf.domain}`;
-}
-
-/**
- * @param {Response} res
- * @param {GraphQLError[]} errors
- * @param {StorefrontConfig} conf
- */
-function graphQLFailure(res, errors, conf) {
-  const message = errors
-    .map((error) => error.message)
-    .filter(Boolean)
-    .join(' | ');
-  let text = message || 'Storefront API error';
-  if (!res.ok) text = res.status === 401 || res.status === 403 || !message ? statusText(res.status, conf) : message;
-  return new TetherError(text, { status: res.status, errors });
-}
-
-/**
- * @typedef {{ kind: 'data', data: unknown }
- *   | { kind: 'retry', backoffMs: number }
- *   | { kind: 'inventory-refused' }} Attempt
- */
-
-/**
- * One request. Failures that retrying can't fix throw.
- *
- * @param {StorefrontConfig} conf
- * @param {string} query
- * @param {Record<string, unknown>} variables
- * @param {boolean} canRetry False on the last attempt: a retryable failure then throws too.
- * @returns {Promise<Attempt>}
- */
-async function attempt(conf, query, variables, canRetry) {
-  let res;
-  try {
-    res = await (conf.fetch ?? fetch)(endpoint(conf), {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'X-Shopify-Storefront-Access-Token': conf.token },
-      body: JSON.stringify({ query, variables }),
-    });
-  } catch (error) {
-    if (canRetry) return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
-    throw new TetherError(`Network error: ${error instanceof Error ? error.message : String(error)}`, {
-      code: 'NETWORK',
-    });
-  }
-  if (res.status === SECURITY_REJECTION) {
-    throw new TetherError('Shopify security rejection (430)', { status: SECURITY_REJECTION });
-  }
-  if (canRetry && (res.status === 429 || res.status >= 500)) {
-    return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
-  }
-
-  /** @type {unknown} */
-  let json;
-  try {
-    json = await res.json();
-  } catch {
-    const text = res.ok ? `Invalid response (${res.status})` : statusText(res.status, conf);
-    throw new TetherError(text, { status: res.status });
-  }
-  // The Storefront API answers in the shape the GraphQL spec sets, or with an error page that isn't JSON.
-  const { data, errors = [] } = /** @type {GraphQLResponse | null} */ (json) ?? {};
-  if (errors.length) {
-    if (query.includes(INVENTORY_FIELD) && errors.some((error) => error.message.includes(INVENTORY_FIELD))) {
-      return { kind: 'inventory-refused' };
-    }
-    if (canRetry && errors.some((error) => error.extensions?.code === 'THROTTLED')) {
-      return { kind: 'retry', backoffMs: THROTTLE_BACKOFF_MS };
-    }
-    throw graphQLFailure(res, errors, conf);
-  }
-  if (!res.ok) throw new TetherError(statusText(res.status, conf), { status: res.status });
-  return { kind: 'data', data };
-}
-
-/**
- * One Storefront API request, for any config: the browser's shared one (`gql`) or one the server helpers build.
- * Queries carry a time bucket so Shopify's cache of an identical query text is at most `maxAge` seconds old, and
- * leave out inventory for a store whose token can't read it (`INVENTORY_FIELD`).
- *
- * @template T The shape of the query's `data`, which the caller's query text decides.
- * @param {StorefrontConfig} conf
- * @param {string} query
- * @param {Record<string, unknown>} [variables]
- * @param {RequestOptions} [options]
- * @returns {Promise<T>}
- * @throws {TetherError} `NOT_CONFIGURED` without a domain or token, `NETWORK` when the store can't be reached,
- *   `HTTP_<status>` for an HTTP or GraphQL failure.
- */
-export async function request(conf, query, variables = {}, { context = true } = {}) {
-  if (!conf.domain || !conf.token) {
-    throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
-  }
-  let text = context ? withContext(query, conf) : query;
-  if (conf.maxAge > 0 && !/^\s*mutation\b/.test(text)) {
-    text += ` #${Math.floor(Date.now() / (conf.maxAge * 1000))}`;
-  }
-  const store = storeOf(conf);
-  let retries = 0;
-  for (;;) {
-    const sent = storesWithoutInventory.has(store) ? text.replaceAll(INVENTORY_FIELD, '') : text;
-    const outcome = await attempt(conf, sent, variables, retries < conf.retries);
-    switch (outcome.kind) {
-      case 'data':
-        // The query text decides the shape of `data`; the caller's `T` states it.
-        return /** @type {T} */ (outcome.data);
-      case 'inventory-refused':
-        log(`the token can't read inventory: ${INVENTORY_FIELD} is left out from now on`);
-        storesWithoutInventory.add(store);
-        break;
-      case 'retry':
-        retries += 1;
-        log('retry', retries);
-        await sleep(outcome.backoffMs * 2 ** retries);
-        break;
-    }
-  }
-}
-
-/**
- * `request` with the browser's shared config.
- *
- * @template T
- * @param {string} query
- * @param {Record<string, unknown>} [variables]
- * @param {RequestOptions} [options]
- * @returns {Promise<T>}
- */
-export const gql = (query, variables, options) => request(cfg, query, variables, options);
-
-/**
- * @template {{ userErrors?: readonly UserError[] | null }} Payload
- * @param {Payload | null | undefined} payload A mutation's payload.
- * @param {string} name The mutation, for the error message.
- * @returns {Payload}
- * @throws {TetherError} `ERROR` on an empty payload or on user errors (in `userErrors`).
- */
-export function unwrap(payload, name) {
-  if (!payload) throw new TetherError(`${name}: empty response`);
-  const userErrors = payload.userErrors ?? [];
-  if (userErrors.length) {
-    throw new TetherError(userErrors.map((error) => error.message).join(' | '), { userErrors });
-  }
-  return payload;
-}