@occluze/tether 0.6.8 → 0.7.0

package/src/cart/store.ts

@@ -0,0 +1,279 @@
+/**
+ * The cart on this page: what Shopify last said about it (`CartStatus`), the quantities quick clicks asked for 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.ts';
+import { emit } from '../dom.ts';
+import { isOpen } from './drawer.ts';
+import { renderCart, quantityOf, showSavedCount } from './render.ts';
+import { getStored, removeStored, setStored } from '../storage.ts';
+import type { CartWarning } from '../config.ts';
+import type { Image } from '../fragments.ts';
+import type { Money } from '../shopify-values.ts';
+
+export interface Attribute {
+  key: string;
+  value: string;
+}
+
+/** A line's `merchandise`: Shopify's `Merchandise` union has only `ProductVariant`. */
+export interface CartVariant {
+  id: string;
+  title: string;
+  sku: string | null;
+  availableForSale: boolean;
+  requiresShipping: boolean;
+  /** Absent when the store's token can't read inventory. */
+  quantityAvailable?: number | null;
+  image: Image | null;
+  price: Money;
+  compareAtPrice: Money | null;
+  selectedOptions: { name: string; value: string }[];
+  product: { id: string; title: string; handle: string; vendor: string; featuredImage: Image | null };
+}
+
+interface LinePlanAllocation {
+  sellingPlan: {
+    id: string;
+    name: string;
+    description: string | null;
+    recurringDeliveries: boolean;
+    options: { name: string; value: string }[];
+  };
+  checkoutChargeAmount: Money;
+  priceAdjustments: { price: Money; compareAtPrice: Money; perDeliveryPrice: Money }[];
+}
+
+export interface ShopifyCartLine {
+  id: string;
+  quantity: number;
+  attributes: Attribute[];
+  cost: {
+    totalAmount: Money;
+    subtotalAmount: Money;
+    amountPerQuantity: Money;
+    compareAtAmountPerQuantity: Money | null;
+  };
+  discountAllocations: { discountedAmount: Money }[];
+  sellingPlanAllocation: LinePlanAllocation | null;
+  merchandise: CartVariant;
+  /** Only on a bundle (`ComponentizableCartLine`). */
+  lineComponents?: {
+    id: string;
+    quantity: number;
+    merchandise: { id: string; title: string; product: { title: string; handle: string } };
+  }[];
+}
+
+/** The fields of `fragment TetherCart`. */
+export interface ShopifyCart {
+  id: string;
+  checkoutUrl: string;
+  totalQuantity: number;
+  note: string | null;
+  createdAt: string;
+  updatedAt: string;
+  attributes: Attribute[];
+  buyerIdentity: { countryCode: string | null; email: string | null };
+  discountCodes: { code: string; applicable: boolean }[];
+  cost: { subtotalAmount: Money; totalAmount: Money; checkoutChargeAmount: Money };
+  lines: { nodes: ShopifyCartLine[] };
+}
+
+/**
+ * `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.
+ */
+export type CartStatus =
+  | { kind: 'unknown' }
+  | { kind: 'empty' }
+  | { kind: 'ready'; cart: ShopifyCart }
+  | { kind: 'error'; error: unknown; cart: ShopifyCart | null };
+
+/** What one quick +/- click asked for; a newer click replaces it. */
+export interface PendingQuantity {
+  quantity: number;
+}
+
+/** The second argument of a `subscribe` listener. */
+interface CartMeta {
+  open: boolean;
+  count: number;
+  loaded: boolean;
+  /** A copy of Shopify's notes on the last change. */
+  warnings: CartWarning[];
+}
+
+let status: CartStatus = { kind: 'unknown' };
+
+/** Shopify's notes on the last change. */
+let warnings: readonly CartWarning[] = [];
+
+/** Line id → what quick +/- clicks asked for, until Shopify has answered. */
+export const pendingQuantities = new Map<string, PendingQuantity>();
+
+export const cartStatus = (): CartStatus => status;
+
+/** The cart as Shopify last sent it. */
+export function currentCart(): ShopifyCart | null {
+  switch (status.kind) {
+    case 'ready':
+    case 'error':
+      return status.cart;
+    case 'unknown':
+    case 'empty':
+      return null;
+  }
+}
+
+export const currentWarnings = (): readonly CartWarning[] => warnings;
+
+const statusOf = (cart: ShopifyCart | null): CartStatus => (cart ? { kind: 'ready', cart } : { kind: 'empty' });
+
+const seenKey = () => `${cfg.storageKey}:seen`;
+
+/** The id of the visitor's cart, kept across pages. */
+export const savedCartId = (): string | null => getStored(cfg.storageKey) || null;
+
+/** Forgets the saved cart, which Shopify no longer has. */
+export function forgetSavedCart(): void {
+  removeStored(cfg.storageKey);
+}
+
+/** Keeps a cart Shopify sent without showing it, for an answer a newer change will replace. */
+export function keepQuietly(cart: ShopifyCart | null): void {
+  status = statusOf(cart);
+  if (cart) setStored(cfg.storageKey, cart.id);
+}
+
+/** Renders the document with the store's cart. */
+export function render(): void {
+  renderCart({
+    cart: currentCart(),
+    warnings,
+    pending: pendingQuantities,
+    failed: status.kind === 'error',
+  });
+}
+
+/** @param reason The `reason` of `tether:cart-updated`. */
+export function announce(reason: string): void {
+  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.
+ *
+ * @returns `cart`.
+ */
+export function commit(cart: ShopifyCart | null, reason: string): ShopifyCart | null {
+  keepQuietly(cart);
+  // Other tabs reload the cart on this storage event; the next page shows the count before its cart has loaded.
+  setStored(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. */
+export function settleLoad(
+  outcome: { kind: 'loaded'; cart: ShopifyCart | null } | { kind: 'failed'; error: unknown },
+): void {
+  status = outcome.kind === 'loaded' ? statusOf(outcome.cart) : { kind: 'error', error: outcome.error, cart: null };
+  announce('load');
+}
+
+/**
+ * The cart's count on the last page, from `<storageKey>:seen` (`<time>|<count>`).
+ *
+ * @returns `null` unless the count is a whole number: other scripts and other Tether versions write storage too.
+ */
+function lastKnownCount(): number | null {
+  const text = getStored(seenKey())?.split('|')[1] ?? '';
+  const count = Number(text);
+  return /^\d+$/.test(text) && Number.isSafeInteger(count) ? count : null;
+}
+
+/** 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(): void {
+  if (status.kind !== 'unknown') return;
+  const count = lastKnownCount();
+  if (count !== null) showSavedCount(count);
+}
+
+/** Sets Shopify's notes on the last change: each message once, in the site's words (`warningText`). */
+export function setWarnings(notes: readonly CartWarning[]): void {
+  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 A runner that starts each task once the one before has settled, whether it succeeded or failed. */
+export function serial(): <T>(task: () => Promise<T>) => Promise<T> {
+  let previous: Promise<unknown> = Promise.resolve();
+  return <T>(task: () => Promise<T>) => {
+    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.
+ */
+export function enqueue<T>(task: () => Promise<T>): Promise<T> {
+  return runInOrder(task).then(
+    (value) => {
+      if (status.kind === 'error') {
+        status = statusOf(status.cart);
+        render();
+      }
+      return value;
+    },
+    (error: unknown) => {
+      status = { kind: 'error', error, cart: currentCart() };
+      render();
+      emit('cart-error', { error });
+      throw error;
+    },
+  );
+}
+
+/** @returns The quantity to show for `line`. */
+export const pendingQuantityOf = (line: ShopifyCartLine): number => quantityOf(line, pendingQuantities);
+
+const meta = (): CartMeta => ({
+  open: isOpen(),
+  count: currentCart()?.totalQuantity ?? 0,
+  loaded: status.kind !== 'unknown',
+  warnings: [...warnings],
+});
+
+/**
+ * Calls `listener` now and after every change of the cart or the drawer.
+ *
+ * @returns Stops listening.
+ */
+export function subscribe(listener: (cart: ShopifyCart | null, meta: CartMeta) => void): () => void {
+  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/{cart.js → cart.ts}

@@ -1,11 +1,11 @@
 /**
  * The cart, as one object: `Tether.cart`. Every change goes through one queue (fast clicks never race) and resolves
- * with the cart Shopify sent back. The state lives in `cart/store.js`, the Cart API calls in `cart/mutations.js`, the
- * drawer in `cart/drawer.js`, the document rendering in `cart/render.js` and the checkout in `cart/checkout.js`.
+ * with the cart Shopify sent back. The state lives in `cart/store.ts`, the Cart API calls in `cart/mutations.ts`, the
+ * drawer in `cart/drawer.ts`, the document rendering in `cart/render.ts` and the checkout in `cart/checkout.ts`.
  */
-import { cfg, reportError } from './config.js';
-import { TetherError } from './client.js';
-import { emit, toAttributes } from './dom.js';
+import { cfg, reportError } from './config.ts';
+import { TetherError } from './client.ts';
+import { emit, toAttributes } from './dom.ts';
 import {
   fetchCart,
   isCartGone,
@@ -15,16 +15,15 @@ import {
   toLineInput,
   toLineUpdate,
   updateLines,
-} from './cart/mutations.js';
-import { checkout } from './cart/checkout.js';
-import { drawers, isOpen, openCart, closeCart, toggleCart, trapFocus } from './cart/drawer.js';
+} from './cart/mutations.ts';
+import { checkout, setCheckoutResolver } from './cart/checkout.ts';
+import { drawers, isOpen, openCart, closeCart, toggleCart, trapFocus } from './cart/drawer.ts';
 import {
   announce,
   cartStatus,
   commit,
   currentCart,
   currentWarnings,
-  customer,
   enqueue,
   forgetSavedCart,
   keepQuietly,
@@ -32,30 +31,26 @@ import {
   pendingQuantityOf,
   render,
   savedCartId,
-  setFailure,
   settleLoad,
   showLastKnownCount,
   subscribe,
-} from './cart/store.js';
-/** @import { CartWarning } from './config.js' */
-/** @import { Attributes, LineSpec, CartLineInput, LinePatch } from './cart/mutations.js' */
-/** @import { ShopifyCart, ShopifyCartLine, CustomerLink, CartStatus } from './cart/store.js' */
+} from './cart/store.ts';
+import type { CartWarning } from './config.ts';
+import type { Attributes, LineSpec, CartLineInput, LinePatch } from './cart/mutations.ts';
+import type { ShopifyCart, ShopifyCartLine, CartStatus } from './cart/store.ts';
 
 export { trapFocus };
 
-/** @returns {readonly ShopifyCartLine[]} */
-const currentLines = () => currentCart()?.lines.nodes ?? [];
+type DiscountCodes = string[] | string | ((current: string[]) => string[]);
+
+const currentLines = (): readonly ShopifyCartLine[] => currentCart()?.lines.nodes ?? [];
 
 /**
  * +1 / -1 for a line. Quick clicks add up: each builds on the quantity the click before asked for, which shows at once
  * (`tether-line="quantity"`, `quantityOf`) until Shopify has answered. Only the latest target is sent; the ones it
  * replaced are skipped.
- *
- * @param {string} lineId
- * @param {number} delta
- * @returns {Promise<ShopifyCart | null>}
  */
-function changeQuantity(lineId, delta) {
+function changeQuantity(lineId: string, delta: number): Promise<ShopifyCart | null> {
   const line = currentLines().find((candidate) => candidate.id === lineId);
   if (!line) return Promise.resolve(currentCart());
   const target = Math.max(0, pendingQuantityOf(line) + delta);
@@ -87,20 +82,16 @@ function changeQuantity(lineId, delta) {
 /**
  * The codes the cart has once a change is its turn in the queue.
  *
- * @param {string[] | string | ((current: string[]) => string[])} codes A function gets the codes as they are by then.
- * @returns {string[]}
+ * @param codes A function gets the codes as they are by then.
  */
-function discountCodesFrom(codes) {
+function discountCodesFrom(codes: DiscountCodes): string[] {
   const current = (currentCart()?.discountCodes ?? []).map((discount) => discount.code);
   const list = typeof codes === 'function' ? codes(current) : codes;
   return (Array.isArray(list) ? list : [list]).map((code) => code.trim()).filter(Boolean);
 }
 
-/**
- * @param {Attributes} attributes
- * @returns {{ key: string, value: string }[]} The cart's attributes with `attributes` merged in; `''` removes a key.
- */
-function mergedAttributes(attributes) {
+/** @returns The cart's attributes with `attributes` merged in; `''` removes a key. */
+function mergedAttributes(attributes: Attributes): { key: string; value: string }[] {
   const merged = new Map((currentCart()?.attributes ?? []).map((attribute) => [attribute.key, attribute.value]));
   toAttributes(attributes).forEach((attribute) => merged.set(attribute.key, attribute.value));
   return [...merged].filter(([, value]) => value !== '').map(([key, value]) => ({ key, value }));
@@ -109,10 +100,8 @@ function mergedAttributes(attributes) {
 /**
  * Loads the saved cart. A cart Shopify no longer has is forgotten; one it can't be asked about (the network, the
  * token) is kept, because it is probably fine.
- *
- * @returns {Promise<ShopifyCart | null>}
  */
-async function init() {
+async function init(): Promise<ShopifyCart | null> {
   const id = savedCartId();
   if (!id) {
     settleLoad({ kind: 'loaded', cart: null });
@@ -133,73 +122,59 @@ async function init() {
 
 export const Cart = {
   init,
-  /** @returns {string | null} The saved cart's id. */
+  /** The saved cart's id. */
   id: savedCartId,
 
-  /** @returns {CartStatus} */
-  get status() {
+  get status(): CartStatus {
     return cartStatus();
   },
-  /** @returns {ShopifyCart | null} */
-  get state() {
+  get state(): ShopifyCart | null {
     return currentCart();
   },
-  /** @returns {readonly ShopifyCartLine[]} */
-  get lines() {
-    return currentLines();
+  /** The cart's lines, a copy: changing it changes nothing in the cart. */
+  get lines(): ShopifyCartLine[] {
+    return [...currentLines()];
   },
-  /** @returns {number} */
-  get count() {
+  get count(): number {
     return currentCart()?.totalQuantity ?? 0;
   },
-  /** @returns {boolean} True once the saved cart, or that there is none, is known. */
-  get loaded() {
+  /** True once the saved cart, or that there is none, is known. */
+  get loaded(): boolean {
     return cartStatus().kind !== 'unknown';
   },
-  /** @returns {unknown} The failure of the last load or change, until a change succeeds. */
-  get lastError() {
+  /**
+   * The failure of the last load or change, until a change succeeds. Requests fail with an `Error`; anything else
+   * thrown is wrapped, so the public type holds.
+   */
+  get lastError(): Error | null {
     const current = cartStatus();
-    return current.kind === 'error' ? current.error : null;
-  },
-  set lastError(error) {
-    setFailure(error);
+    if (current.kind !== 'error') return null;
+    return current.error instanceof Error ? current.error : new Error(String(current.error));
   },
-  /** @returns {readonly CartWarning[]} Shopify's notes on the last change. */
-  get warnings() {
-    return currentWarnings();
+  /** Shopify's notes on the last change, a copy. */
+  get warnings(): CartWarning[] {
+    return [...currentWarnings()];
   },
-  /** @returns {ReadonlyMap<string, { quantity: number }>} Line id → the quantity quick clicks asked for. */
-  get pendingQty() {
+  /** Line id → the quantity quick clicks asked for. */
+  get pendingQty(): ReadonlyMap<string, { quantity: number }> {
     return pendingQuantities;
   },
 
-  /** @returns {string | null} The logged-in customer's Customer Account API token (set by the account part). */
-  get customerAccessToken() {
-    return customer.accessToken;
-  },
-  set customerAccessToken(token) {
-    customer.accessToken = token || null;
-  },
-  /** @returns {(() => Promise<string | null>) | null} The account's own checkout URL (set by the account part). */
-  get beforeCheckout() {
-    return customer.beforeCheckout;
-  },
-  set beforeCheckout(fetchUrl) {
-    customer.beforeCheckout = typeof fetchUrl === 'function' ? fetchUrl : null;
-  },
   /**
-   * Links the cart to a logged-in customer, or unlinks it with `null`s. Carts created from now on belong to the
-   * customer; `beforeCheckout` gives the checkout URL (`null` from it uses the cart's).
-   *
-   * @param {Partial<CustomerLink>} link Fields left out keep their value.
+   * Sets where a logged-in customer checks out, or clears it with `null`: the account part's resolver answers the
+   * customer's checkout URL for the cart (`null` uses the cart's own).
    */
-  setCustomer(link) {
-    if (link.accessToken !== undefined) customer.accessToken = link.accessToken;
-    if (link.beforeCheckout !== undefined) customer.beforeCheckout = link.beforeCheckout;
+  setCheckoutResolver,
+
+  /**
+   * Forgets the saved cart on this device, as if there were none: the page shows an empty cart and
+   * `tether:cart-updated` fires with reason `load`. The next add starts a new cart.
+   */
+  forgetSaved(): void {
+    forgetSavedCart();
+    settleLoad({ kind: 'loaded', cart: null });
   },
 
-  /** Keeps a cart and shows it, as a change does; tests seed the cart with it. */
-  _commit: commit,
   render,
   subscribe,
 
@@ -207,14 +182,16 @@ export const Cart = {
    * `add(variantId, 2)`, `add({ variantId, quantity, sellingPlanId, attributes })`, or `add([line, line])` for
    * bundles in one request. Creates the cart when there is none.
    *
-   * @param {string | number | LineSpec | (string | number | LineSpec)[]} input
-   * @param {number} [quantity]
-   * @param {Omit<LineSpec, 'variantId' | 'quantity'>} [options]
-   * @returns {Promise<ShopifyCart | null>}
+   * @throws {TetherError} (rejected) When the add fails, or Shopify answers it without a cart.
    */
-  add(input, quantity = 1, options = {}) {
-    /** @type {CartLineInput[]} */
-    const lines = (Array.isArray(input) ? input : [input]).map((line) => toLineInput(line, quantity, options));
+  add(
+    input: string | number | LineSpec | (string | number | LineSpec)[],
+    quantity = 1,
+    options: Omit<LineSpec, 'variantId' | 'quantity'> = {},
+  ): Promise<ShopifyCart> {
+    const lines: CartLineInput[] = (Array.isArray(input) ? input : [input]).map((line) =>
+      toLineInput(line, quantity, options),
+    );
     return enqueue(async () => {
       const cart = await mutateCart({
         name: 'cartLinesAdd',
@@ -223,6 +200,8 @@ export const Cart = {
         variables: { lines },
         createInput: { lines },
       });
+      // A mutation answers without a cart only beside user errors, which reject above; an add always has one.
+      if (!cart) throw new TetherError('Shopify answered the add without a cart');
       commit(cart, 'add');
       emit('added', { cart, lines });
       if (cfg.openCartOnAdd) openCart();
@@ -233,11 +212,9 @@ export const Cart = {
   /**
    * `updateLine(lineId, 3)` or `updateLine(lineId, { quantity, sellingPlanId, attributes })`.
    *
-   * @param {string} lineId
-   * @param {number | LinePatch} patch A quantity of 0 or less removes the line.
-   * @returns {Promise<ShopifyCart | null>}
+   * @param patch A quantity of 0 or less removes the line.
    */
-  updateLine(lineId, patch) {
+  updateLine(lineId: string, patch: number | LinePatch): Promise<ShopifyCart | null> {
     const quantity = typeof patch === 'number' ? patch : patch.quantity;
     if (quantity !== undefined && quantity <= 0) return Cart.removeLine(lineId);
     const line = toLineUpdate(lineId, patch);
@@ -246,33 +223,21 @@ export const Cart = {
 
   changeQuantity,
 
-  /**
-   * @param {ShopifyCartLine} line
-   * @returns {number} The quantity to show: the one asked for while an update is on its way.
-   */
+  /** The quantity to show: the one asked for while an update is on its way. */
   quantityOf: pendingQuantityOf,
 
-  /**
-   * @param {string | string[]} lineIds
-   * @returns {Promise<ShopifyCart | null>}
-   */
-  removeLine(lineIds) {
+  removeLine(lineIds: string | string[]): Promise<ShopifyCart | null> {
     const ids = Array.isArray(lineIds) ? lineIds : [lineIds];
     return enqueue(async () => commit(await removeLines(ids), 'remove'));
   },
 
-  /** @returns {Promise<ShopifyCart | null>} */
-  clear() {
+  clear(): Promise<ShopifyCart | null> {
     const ids = currentLines().map((line) => line.id);
     if (!ids.length) return Promise.resolve(currentCart());
     return Cart.removeLine(ids);
   },
 
-  /**
-   * @param {string | null | undefined} note
-   * @returns {Promise<ShopifyCart | null>}
-   */
-  setNote(note) {
+  setNote(note: string | null | undefined): Promise<ShopifyCart | null> {
     const variables = { note: note ?? '' };
     return enqueue(async () =>
       commit(
@@ -291,10 +256,9 @@ export const Cart = {
   /**
    * Cart attributes, merged with the cart's (as it is when the change runs, so quick calls don't drop each other).
    *
-   * @param {Attributes} attributes The value `''` removes a key.
-   * @returns {Promise<ShopifyCart | null>}
+   * @param attributes The value `''` removes a key.
    */
-  setAttributes(attributes) {
+  setAttributes(attributes: Attributes): Promise<ShopifyCart | null> {
     return enqueue(async () => {
       const variables = { attributes: mergedAttributes(attributes) };
       const cart = await mutateCart({
@@ -308,13 +272,8 @@ export const Cart = {
     });
   },
 
-  /**
-   * Replaces the discount codes; `[]` removes them all.
-   *
-   * @param {string[] | string | ((current: string[]) => string[])} codes
-   * @returns {Promise<ShopifyCart | null>}
-   */
-  setDiscountCodes(codes) {
+  /** Replaces the discount codes; `[]` removes them all. */
+  setDiscountCodes(codes: DiscountCodes): Promise<ShopifyCart | null> {
     return enqueue(async () => {
       const variables = { discountCodes: discountCodesFrom(codes) };
       const cart = await mutateCart({
@@ -331,11 +290,9 @@ export const Cart = {
   /**
    * Adds a code. A code Shopify doesn't accept is removed again, so it doesn't warn on every later change.
    *
-   * @param {string} code
-   * @returns {Promise<ShopifyCart | null>}
    * @throws {TetherError} `INVALID_DISCOUNT` (rejected) when Shopify doesn't accept the code.
    */
-  async applyDiscount(code) {
+  async applyDiscount(code: string): Promise<ShopifyCart | null> {
     const cart = await Cart.setDiscountCodes((current) => [...new Set([...current, code])]);
     const wanted = code.toLowerCase();
     const applied = (cart?.discountCodes ?? []).find((discount) => discount.code.toLowerCase() === wanted);
@@ -348,11 +305,7 @@ export const Cart = {
     throw new TetherError(`Discount code not valid: ${code}`, { code: 'INVALID_DISCOUNT' });
   },
 
-  /**
-   * @param {string} code
-   * @returns {Promise<ShopifyCart | null>}
-   */
-  removeDiscount(code) {
+  removeDiscount(code: string): Promise<ShopifyCart | null> {
     const unwanted = code.toLowerCase();
     return Cart.setDiscountCodes((current) => current.filter((existing) => existing.toLowerCase() !== unwanted));
   },
@@ -360,11 +313,12 @@ export const Cart = {
   /**
    * Sets who is buying; a country changes the cart's currency and prices to that market's.
    *
-   * @param {{ countryCode?: string, email?: string, phone?: string, customerAccessToken?: string | null }} buyerIdentity
-   * @param {{ create?: boolean }} [options] `create: false` forgets an expired cart instead of creating an empty one.
-   * @returns {Promise<ShopifyCart | null>}
+   * @param options `create: false` forgets an expired cart instead of creating an empty one.
    */
-  setBuyerIdentity(buyerIdentity, { create = true } = {}) {
+  setBuyerIdentity(
+    buyerIdentity: { countryCode?: string; email?: string; phone?: string },
+    { create = true }: { create?: boolean } = {},
+  ): Promise<ShopifyCart | null> {
     return enqueue(async () => {
       const cart = await mutateCart({
         name: 'cartBuyerIdentityUpdate',
@@ -372,7 +326,7 @@ export const Cart = {
         inner: 'buyerIdentity: $buyerIdentity',
         variables: { buyerIdentity },
         createInput: create ? { buyerIdentity } : null,
-      }).catch((/** @type {unknown} */ error) => {
+      }).catch((error: unknown) => {
         // mutateCart has forgotten the cart Shopify no longer has; without `create` that leaves no cart.
         if (create || !isCartGone(error)) throw error;
         return null;