@occluze/tether 0.6.8 → 0.7.0

package/src/cart/mutations.ts

@@ -0,0 +1,237 @@
+/**
+ * The Storefront Cart API: loading the saved cart, creating one, and the mutations that change it. Shopify forgets a
+ * cart some days after its last change and once it has been checked out; a change that needs a cart then creates a
+ * new one with the same input, so the visitor's click still lands.
+ */
+import { cfg, log } from '../config.ts';
+import { gql, orNull, shaped, unwrap, TetherError } from '../client.ts';
+import { cartFragment } from '../fragments.ts';
+import { GID } from '../selling-plans.ts';
+import { toAttributes } from '../dom.ts';
+import { CART } from './cart-shape.ts';
+import { savedCartId, forgetSavedCart, setWarnings } from './store.ts';
+import type { CartWarning } from '../config.ts';
+import type { QueryText, UserError } from '../client.ts';
+import type { AttributeValue } from '../dom.ts';
+import type { ShopifyCart, Attribute } from './store.ts';
+
+export type Attributes = Record<string, AttributeValue> | { key: string | number; value?: AttributeValue }[];
+
+/** A line to add, in any of the shapes `Cart.add` takes. */
+export interface LineSpec {
+  variantId?: string | number;
+  merchandiseId?: string | number;
+  id?: string | number;
+  quantity?: number | string;
+  sellingPlanId?: string | number | null;
+  sellingPlan?: string | number | null;
+  attributes?: Attributes | null;
+}
+
+/** Shopify's `CartLineInput`. */
+export interface CartLineInput {
+  merchandiseId: string;
+  quantity: number;
+  sellingPlanId?: string;
+  attributes?: Attribute[];
+}
+
+/** What every cart mutation answers. Its lists are read with a fallback, so `isPayloadOf` checks the cart alone. */
+interface CartPayload {
+  cart: ShopifyCart | null;
+  userErrors?: UserError[] | null;
+  warnings?: CartWarning[];
+}
+
+/**
+ * Shopify answers a cart id it can't resolve, in a mutation, with a top-level GraphQL error whose only detail is
+ * this message (no `extensions.code`). A user error on the `cartId` field is recognised by its shape instead.
+ */
+const UNKNOWN_CART_MESSAGE = /does not exist|not found|invalid id/i;
+
+/** @returns A check of a mutation's answer: a `null` payload (which `unwrap` refuses), or one with a cart or `null`. */
+const isPayloadOf = (name: string) =>
+  shaped<Record<string, CartPayload | null>>({ [name]: orNull({ cart: orNull(CART) }) });
+
+/**
+ * @returns True when `error` says Shopify doesn't have the cart, false for any other failure (the network, the token,
+ *   a line it refused), after which the saved cart is still good.
+ */
+export function isCartGone(error: unknown): boolean {
+  if (!(error instanceof TetherError)) return false;
+  if (error.userErrors?.some((userError) => userError.field?.[0] === 'cartId')) return true;
+  return (error.errors ?? []).some((graphQLError) => UNKNOWN_CART_MESSAGE.test(graphQLError.message));
+}
+
+/**
+ * @param input A variant id, or a line.
+ * @param quantity For a variant id.
+ * @param options For a variant id.
+ * @throws {TetherError} `ERROR` without a variant id.
+ */
+export function toLineInput(
+  input: string | number | LineSpec | null | undefined,
+  quantity = 1,
+  options: Omit<LineSpec, 'variantId' | 'quantity'> = {},
+): CartLineInput {
+  const spec: LineSpec =
+    typeof input === 'object' && input !== null
+      ? input
+      : { ...options, quantity, ...(input === null || input === undefined ? {} : { variantId: input }) };
+  const merchandiseId = GID.variant(spec.merchandiseId || spec.variantId || spec.id);
+  if (!merchandiseId) throw new TetherError('add(): variantId is required');
+  const asked = parseInt(String(spec.quantity ?? 1), 10);
+  const line: CartLineInput = { merchandiseId, quantity: Math.max(1, asked || 1) };
+  const planId = GID.sellingPlan(spec.sellingPlanId || spec.sellingPlan);
+  if (planId) line.sellingPlanId = planId;
+  const attributes = toAttributes(spec.attributes);
+  if (attributes.length) line.attributes = attributes;
+  return line;
+}
+
+/**
+ * @param name The mutation, which is also its payload's field.
+ * @param args The operation's variable definitions.
+ * @param inner The mutation field's arguments.
+ */
+function mutationText(name: string, args: string, inner: string): QueryText {
+  return (access) => `mutation Tether_${name}(${args}) {
+  ${name}(${inner}) { cart { ...TetherCart } userErrors { field message } warnings { code message target } }
+}
+${cartFragment(access)}`;
+}
+
+/**
+ * @returns The cart in Shopify's answer, after keeping its warnings.
+ * @throws {TetherError} For a failed request, or the mutation's user errors.
+ */
+async function send(
+  name: string,
+  args: string,
+  inner: string,
+  variables: Record<string, unknown>,
+): Promise<ShopifyCart | null> {
+  const data = await gql(mutationText(name, args, inner), variables, isPayloadOf(name));
+  const payload = unwrap(data[name], name);
+  setWarnings(payload.warnings ?? []);
+  return payload.cart;
+}
+
+/**
+ * A new cart in the visitor's market.
+ *
+ * @param input More of Shopify's `CartInput`, e.g. the first lines.
+ */
+function createCart(input: Record<string, unknown>): Promise<ShopifyCart | null> {
+  const withIdentity = cfg.country ? { buyerIdentity: { countryCode: cfg.country }, ...input } : input;
+  return send('cartCreate', '$input: CartInput!', 'input: $input', { input: withIdentity });
+}
+
+/** A mutation on the saved cart. */
+interface CartMutation {
+  /** The mutation, e.g. `cartLinesAdd`. */
+  name: string;
+  /** Its variable definitions besides `$cartId`. */
+  args: string;
+  /** Its arguments besides `cartId`. */
+  inner: string;
+  variables: Record<string, unknown>;
+  /**
+   * The `CartInput` of a new cart that does what the mutation asks, when there is no cart (or Shopify no longer has
+   * it); `null` leaves the visitor without a cart instead.
+   */
+  createInput: Record<string, unknown> | null;
+}
+
+/**
+ * Runs a mutation on the saved cart, or creates a cart from `createInput` when there is none to change.
+ *
+ * @returns The changed cart; `null` without a cart and without a `createInput`.
+ * @throws {TetherError} For a failed request or Shopify's user errors; also when the cart is gone and there is no
+ *   `createInput` (the saved cart is forgotten first).
+ */
+export async function mutateCart({
+  name,
+  args,
+  inner,
+  variables,
+  createInput,
+}: CartMutation): Promise<ShopifyCart | null> {
+  const cartId = savedCartId();
+  if (!cartId) return createInput ? createCart(createInput) : null;
+  try {
+    return await send(name, `$cartId: ID!, ${args}`, `cartId: $cartId, ${inner}`, { ...variables, cartId });
+  } catch (error) {
+    if (!isCartGone(error)) throw error;
+    forgetSavedCart();
+    if (!createInput) throw error;
+    log('cart expired, creating a new one');
+    return createCart(createInput);
+  }
+}
+
+/** @returns The cart, `null` when Shopify doesn't have it (expired or checked out). */
+export async function fetchCart(id: string): Promise<ShopifyCart | null> {
+  const data = await gql(
+    (access) => `query TetherCart($id: ID!) { cart(id: $id) { ...TetherCart } }\n${cartFragment(access)}`,
+    { id },
+    shaped<{ cart: ShopifyCart | null }>({ cart: orNull(CART) }),
+  );
+  return data.cart;
+}
+
+/** @returns The cart's current checkout URL, `null` when Shopify doesn't have the cart. */
+export async function fetchCheckoutUrl(id: string): Promise<string | null> {
+  const data = await gql(
+    'query TetherCheckout($id: ID!) { cart(id: $id) { checkoutUrl } }',
+    { id },
+    shaped<{ cart: { checkoutUrl: string } | null }>({ cart: orNull({ checkoutUrl: 'string' }) }),
+  );
+  return data.cart?.checkoutUrl ?? null;
+}
+
+/** A change to one line, for `updateLine`. */
+export interface LinePatch {
+  /** 0 or less removes the line. */
+  quantity?: number;
+  /** `null` switches the line back to one-time purchase. */
+  sellingPlanId?: string | number | null;
+  attributes?: Attributes;
+  merchandiseId?: string | number;
+  variantId?: string | number;
+}
+
+/** @returns Shopify's `CartLineUpdateInput`. */
+export function toLineUpdate(lineId: string, patch: number | LinePatch): Record<string, unknown> {
+  const change: LinePatch = typeof patch === 'number' ? { quantity: patch } : patch;
+  const line: Record<string, unknown> = { id: lineId };
+  if (change.quantity !== undefined) line['quantity'] = change.quantity;
+  if ('sellingPlanId' in change)
+    line['sellingPlanId'] = change.sellingPlanId ? GID.sellingPlan(change.sellingPlanId) : null;
+  if (change.attributes) line['attributes'] = toAttributes(change.attributes);
+  const variantId = change.merchandiseId || change.variantId;
+  if (variantId) line['merchandiseId'] = GID.variant(variantId);
+  return line;
+}
+
+export const updateLines = (lines: Record<string, unknown>[]): Promise<ShopifyCart | null> =>
+  mutateCart({
+    name: 'cartLinesUpdate',
+    args: '$lines: [CartLineUpdateInput!]!',
+    inner: 'lines: $lines',
+    variables: { lines },
+    createInput: null,
+  });
+
+export const removeLines = (lineIds: string[]): Promise<ShopifyCart | null> =>
+  mutateCart({
+    name: 'cartLinesRemove',
+    args: '$lineIds: [ID!]!',
+    inner: 'lineIds: $lineIds',
+    variables: { lineIds },
+    createInput: null,
+  });
+
+/** @returns The cart once `lineId` has `target` (0 removes it). */
+export const setLineQuantity = (lineId: string, target: number): Promise<ShopifyCart | null> =>
+  target > 0 ? updateLines([{ id: lineId, quantity: target }]) : removeLines([lineId]);

package/src/cart/{render.js → render.ts}

@@ -3,10 +3,10 @@
  * codes and the `[tether-cart-lines]` repeaters. It renders what it is given (a `CartView`) and holds no state, so
  * every render shows the cart as the store has it at that moment.
  */
-import { cfg, reportError } from '../config.js';
-import { getProduct } from '../loader.js';
-import { allPlans } from '../selling-plans.js';
-import { isGreaterAmount } from '../amounts.js';
+import { cfg, reportError } from '../config.ts';
+import { getProduct } from '../loader.ts';
+import { allPlans } from '../selling-plans.ts';
+import { isGreaterAmount } from '../amounts.ts';
 import {
   attr,
   sel,
@@ -21,40 +21,36 @@ import {
   repeatKeyed,
   productUrl,
   notifyLayoutChanged,
-} from '../dom.js';
-import { isOpen, syncDrawerAria } from './drawer.js';
-/** @import { CartWarning } from '../config.js' */
-/** @import { Product } from '../fragments.js' */
-/** @import { ShopifyCart, ShopifyCartLine, PendingQuantity } from './store.js' */
+} from '../dom.ts';
+import { isOpen, syncDrawerAria } from './drawer.ts';
+import type { CartWarning } from '../config.ts';
+import type { Product } from '../fragments.ts';
+import type { ShopifyCart, ShopifyCartLine, PendingQuantity } from './store.ts';
 
-/**
- * @typedef {object} CartView What a render shows.
- * @property {ShopifyCart | null} cart
- * @property {readonly CartWarning[]} warnings
- * @property {ReadonlyMap<string, PendingQuantity>} pending Line id → the quantity quick clicks asked for.
- * @property {boolean} failed The last load or change failed (`tether-show="cart-error"`).
- */
+/** What a render shows. */
+interface CartView {
+  cart: ShopifyCart | null;
+  warnings: readonly CartWarning[];
+  /** Line id → the quantity quick clicks asked for. */
+  pending: ReadonlyMap<string, PendingQuantity>;
+  /** The last load or change failed (`tether-show="cart-error"`). */
+  failed: boolean;
+}
 
 /** Shopify's title of a variant of a product without options. */
 const DEFAULT_TITLE = 'Default Title';
 
-/**
- * @param {ShopifyCartLine} line
- * @param {ReadonlyMap<string, PendingQuantity>} pending
- * @returns {number} The quantity to show: the one asked for while an update is on its way.
- */
-export const quantityOf = (line, pending) => pending.get(line.id)?.quantity ?? line.quantity;
+/** @returns The quantity to show: the one asked for while an update is on its way. */
+export const quantityOf = (line: ShopifyCartLine, pending: ReadonlyMap<string, PendingQuantity>): number =>
+  pending.get(line.id)?.quantity ?? line.quantity;
 
-/** @param {string} gid */
-const numericId = (gid) => gid.split('/').pop() ?? gid;
+const numericId = (gid: string) => gid.split('/').pop() ?? gid;
 
-/**
- * @param {ShopifyCartLine} line
- * @returns {string} The product page, with the line's variant and plan selected.
- */
-function lineUrl(line) {
+/** @returns The product page, with the line's variant and plan selected. */
+function lineUrl(line: ShopifyCartLine): string | null {
   const variant = line.merchandise;
   const base = productUrl(variant.product.handle, variant.product.id);
+  if (!base) return null;
   const query = new URLSearchParams();
   query.set('variant', numericId(variant.id));
   const planId = line.sellingPlanAllocation?.sellingPlan.id;
@@ -62,13 +58,12 @@ function lineUrl(line) {
   return `${base}${base.includes('?') ? '&' : '?'}${query.toString()}`;
 }
 
-/** @typedef {(line: ShopifyCartLine, view: CartView) => string | number} LineText */
+type LineText = (line: ShopifyCartLine, view: CartView) => string | number;
 
-/** @type {LineText} */
-const productTitle = (line) => line.merchandise.product.title;
+const productTitle: LineText = (line) => line.merchandise.product.title;
 
-/** @type {Record<string, LineText>} The text of each `tether-line` key. */
-const LINE_TEXT = {
+/** The text of each `tether-line` key. */
+const LINE_TEXT: Record<string, LineText> = {
   title: productTitle,
   'product-title': productTitle,
   'variant-title': (line) => (line.merchandise.title === DEFAULT_TITLE ? '' : line.merchandise.title),
@@ -95,12 +90,10 @@ const LINE_TEXT = {
 const ATTRIBUTE_KEY = 'attribute:';
 
 /**
- * @param {ShopifyCartLine} line
- * @param {string} key The `tether-line` value.
- * @param {CartView} view
- * @returns {string | number | undefined} The text for `key`, `undefined` for a key Tether doesn't know.
+ * @param key The `tether-line` value.
+ * @returns The text for `key`, `undefined` for a key Tether doesn't know.
  */
-function lineValue(line, key, view) {
+function lineValue(line: ShopifyCartLine, key: string, view: CartView): string | number | undefined {
   if (Object.hasOwn(LINE_TEXT, key)) return LINE_TEXT[key]?.(line, view);
   if (!key.startsWith(ATTRIBUTE_KEY)) return undefined;
   const name = key.slice(ATTRIBUTE_KEY.length);
@@ -110,12 +103,8 @@ function lineValue(line, key, view) {
 /**
  * Fills a `<select tether-line-plan>` with the product's plans (and one-time purchase, when the product allows it and
  * the select isn't `subscription-only`), keeping the options when they haven't changed.
- *
- * @param {HTMLSelectElement} select
- * @param {ShopifyCartLine} line
- * @param {Product} product
  */
-function fillPlanSelect(select, line, product) {
+function fillPlanSelect(select: HTMLSelectElement, line: ShopifyCartLine, product: Product) {
   const plans = allPlans(product);
   const allowOneTime = !product.requiresSellingPlan && get(select, 'line-plan') !== 'subscription-only';
   const oneTime = { value: '', label: select.getAttribute(attr('one-time-label')) || 'One-time purchase' };
@@ -136,12 +125,7 @@ function fillPlanSelect(select, line, product) {
   show(select, plans.length > 0);
 }
 
-/**
- * @param {HTMLElement} node
- * @param {ShopifyCartLine} line
- * @param {CartView} view
- */
-function renderLineState(node, line, view) {
+function renderLineState(node: HTMLElement, line: ShopifyCartLine, view: CartView) {
   const isSubscription = Boolean(line.sellingPlanAllocation);
   node.classList.toggle('is-subscription', isSubscription);
   // Shopify's note about this line, such as less stock than asked.
@@ -154,25 +138,21 @@ function renderLineState(node, line, view) {
   qsa(node, sel('line', 'warning')).forEach((el) => {
     setTextTracked(el, warning?.message ?? '');
   });
-  const conditions = {
-    subscription: isSubscription,
-    'one-time': !isSubscription,
-    'on-sale': isGreaterAmount(line.cost.compareAtAmountPerQuantity?.amount, line.cost.amountPerQuantity.amount),
-    'has-components': (line.lineComponents ?? []).length > 0,
-    warning: Boolean(warning),
-  };
+  const conditions = new Map([
+    ['subscription', isSubscription],
+    ['one-time', !isSubscription],
+    ['on-sale', isGreaterAmount(line.cost.compareAtAmountPerQuantity?.amount, line.cost.amountPerQuantity.amount)],
+    ['has-components', (line.lineComponents ?? []).length > 0],
+    ['warning', Boolean(warning)],
+  ]);
   qsa(node, sel('line-show')).forEach((el) => {
     const key = get(el, 'line-show');
-    if (key !== null && Object.hasOwn(conditions, key)) show(el, conditions[/** @type {keyof conditions} */ (key)]);
+    const visible = key === null ? undefined : conditions.get(key);
+    if (visible !== undefined) show(el, visible);
   });
 }
 
-/**
- * @param {HTMLElement} node
- * @param {ShopifyCartLine} line
- * @param {CartView} view
- */
-function renderLine(node, line, view) {
+function renderLine(node: HTMLElement, line: ShopifyCartLine, view: CartView) {
   const variant = line.merchandise;
   node.setAttribute(attr('line-id'), line.id);
   qsa(node, sel('line')).forEach((el) => {
@@ -182,7 +162,8 @@ function renderLine(node, line, view) {
       return;
     }
     if (key === 'url') {
-      el.setAttribute('href', lineUrl(line));
+      const url = lineUrl(line);
+      if (url) el.setAttribute('href', url);
       return;
     }
     const value = lineValue(line, key, view);
@@ -193,34 +174,31 @@ function renderLine(node, line, view) {
     getProduct(variant.product.handle)
       .then((product) => {
         // The selector matches only <select> elements.
-        fillPlanSelect(/** @type {HTMLSelectElement} */ (select), line, product);
+        fillPlanSelect(select as HTMLSelectElement, line, product);
       })
-      .catch((/** @type {unknown} */ error) => {
+      .catch((error: unknown) => {
         reportError(error, 'line plan options');
       });
   });
 }
 
-/**
- * @param {ShopifyCart | null} cart
- * @param {CartView} view
- */
-function renderConditions(cart, view) {
+function renderConditions(cart: ShopifyCart | null, view: CartView) {
   const count = cart?.totalQuantity ?? 0;
   const hasSubscription = (cart?.lines.nodes ?? []).some((line) => line.sellingPlanAllocation);
-  const conditions = {
-    'cart-empty': count === 0,
-    'cart-filled': count > 0,
-    'cart-has-subscription': hasSubscription,
-    'cart-no-subscription': !hasSubscription,
-    'cart-has-discount': (cart?.discountCodes ?? []).some((code) => code.applicable),
-    'cart-error': view.failed,
-    'cart-warning': view.warnings.length > 0,
-  };
+  const conditions = new Map([
+    ['cart-empty', count === 0],
+    ['cart-filled', count > 0],
+    ['cart-has-subscription', hasSubscription],
+    ['cart-no-subscription', !hasSubscription],
+    ['cart-has-discount', (cart?.discountCodes ?? []).some((code) => code.applicable)],
+    ['cart-error', view.failed],
+    ['cart-warning', view.warnings.length > 0],
+  ]);
   qsa(document, sel('show')).forEach((el) => {
     const key = get(el, 'show');
-    if (key === null || !Object.hasOwn(conditions, key) || el.closest(sel('product'))) return;
-    show(el, conditions[/** @type {keyof conditions} */ (key)]);
+    const visible = key === null ? undefined : conditions.get(key);
+    if (visible === undefined || el.closest(sel('product'))) return;
+    show(el, visible);
   });
   qsa(document, sel('checkout')).forEach((el) => {
     el.classList.toggle('is-disabled', !count);
@@ -228,8 +206,7 @@ function renderConditions(cart, view) {
   });
 }
 
-/** @param {ShopifyCart | null} cart */
-function renderFields(cart) {
+function renderFields(cart: ShopifyCart | null) {
   qsa(document, `textarea${sel('cart-note')},input${sel('cart-note')}`).forEach((el) => {
     // The visitor may be typing in it.
     if (document.activeElement !== el) setText(el, cart?.note ?? '');
@@ -244,11 +221,10 @@ function renderFields(cart) {
   });
 }
 
-/** @param {CartView} view */
-export function renderCart(view) {
+export function renderCart(view: CartView): void {
   const { cart } = view;
-  /** @param {'subtotalAmount' | 'totalAmount' | 'checkoutChargeAmount'} key */
-  const money = (key) => (cart ? formatMoney(cart.cost[key]) : '');
+  const money = (key: 'subtotalAmount' | 'totalAmount' | 'checkoutChargeAmount') =>
+    cart ? formatMoney(cart.cost[key]) : '';
 
   syncDrawerAria(isOpen());
   qsa(document, sel('cart-count')).forEach((el) => {
@@ -282,13 +258,9 @@ export function renderCart(view) {
   if (cart) notifyLayoutChanged('cart');
 }
 
-/**
- * Shows the count a saved cart had on the last page in the cart counts the page left at 0, until it has loaded.
- *
- * @param {string} count
- */
-export function showSavedCount(count) {
+/** Shows the count a saved cart had on the last page in the cart counts the page left at 0, until it has loaded. */
+export function showSavedCount(count: number): void {
   qsa(document, sel('cart-count')).forEach((el) => {
-    if (/^\s*0?\s*$/.test(el.textContent)) el.textContent = count;
+    if (/^\s*0?\s*$/.test(el.textContent)) el.textContent = String(count);
   });
 }