@occluze/tether 0.6.8 → 0.7.0

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@occluze/tether",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Free, open-source alternative to Smootify and Storesynk (Shopyflow): Shopify products, cart and subscriptions in Webflow with HTML attributes. Optional Shopify to Webflow CMS sync.",
   "type": "module",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
   "exports": {
     ".": {
-      "types": "./types/index.d.ts",
+      "types": "./dist/types/src/index.d.ts",
       "default": "./dist/esm/index.js"
     },
     "./server": {
-      "types": "./types/server.d.ts",
+      "types": "./dist/types/src/server.d.ts",
       "default": "./dist/esm/server.js"
     },
     "./astro": {
-      "types": "./types/astro.d.ts",
+      "types": "./dist/types/src/astro.d.ts",
       "default": "./dist/esm/astro.js"
     },
     "./presets/barba": {
-      "types": "./types/barba.d.ts",
+      "types": "./dist/types/src/presets/barba.d.ts",
       "default": "./dist/presets/barba.esm.js"
     },
     "./dist/*": "./dist/*"
@@ -28,48 +28,46 @@
     "dist",
     "src",
     "LICENSE",
-    "README.md",
-    "types/index.d.ts",
-    "types/barba.d.ts",
-    "types/server.d.ts",
-    "types/astro.d.ts"
+    "README.md"
   ],
   "scripts": {
-    "build": "node scripts/build.mjs",
-    "dev": "node scripts/build.mjs --watch",
+    "build": "node --experimental-strip-types scripts/build.ts",
+    "dev": "node --experimental-strip-types scripts/build.ts --watch",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.json",
+    "typecheck": "tsc -b",
     "knip": "knip",
     "deps": "depcruise src server/src server/bin server/scripts scripts",
     "check": "npm run format:check && npm run lint && npm run typecheck && npm run knip && npm run deps && npm test",
     "prepare": "lefthook install",
-    "test": "node --test test/*.test.js server/test/*.test.js && npm run test:types",
+    "test": "node --experimental-strip-types --test test/*.test.js server/test/*.test.js && npm run test:types",
     "test:types": "tsc -p types/tsconfig.json",
-    "smoke": "node scripts/smoke.mjs",
-    "pretest": "node scripts/build.mjs --out .test-dist",
-    "presmoke": "node scripts/build.mjs",
-    "release": "node scripts/release.mjs",
+    "smoke": "node --experimental-strip-types scripts/smoke.ts",
+    "pretest": "node --experimental-strip-types scripts/build.ts --out .test-dist",
+    "presmoke": "node --experimental-strip-types scripts/build.ts",
+    "release": "node --experimental-strip-types scripts/release.ts",
     "e2e:build": "npm run build && cd examples/astro && (test -f .env || cp .env.example .env) && npm install --no-audit --no-fund && npm install --no-save ../.. && npx astro build",
     "e2e": "npm run e2e:build && playwright test -c e2e/playwright.config.js"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@playwright/test": "^1.64.1",
+    "@playwright/test": "1.64.1",
     "@tsconfig/strictest": "2.0.8",
+    "@types/jsdom": "21.1.7",
     "@types/node": "24.19.2",
     "dependency-cruiser": "18.7.2",
-    "esbuild": "^0.25.0",
+    "esbuild": "0.25.12",
     "eslint": "10.14.0",
     "eslint-config-prettier": "10.1.8",
     "globals": "17.14.0",
-    "jsdom": "^26.0.0",
+    "jsdom": "26.1.0",
     "knip": "6.44.1",
     "lefthook": "2.2.2",
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.72.1"
+    "typescript-eslint": "8.72.1",
+    "yaml": "2.9.1"
   },
   "license": "MIT",
   "author": {
@@ -110,7 +108,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "types": "types/index.d.ts",
+  "types": "dist/types/src/index.d.ts",
   "peerDependencies": {
     "astro": ">=4"
   },
@@ -118,5 +116,8 @@
     "astro": {
       "optional": true
     }
+  },
+  "engines": {
+    "node": ">=22.18"
   }
 }

package/src/account/addresses-view.ts

@@ -0,0 +1,58 @@
+/**
+ * The customer's addresses (`tether-addresses`), with `tether-show="addresses-loading"`, `addresses-empty` and
+ * `addresses-error`. The last list rendered is kept, so an edit button can fill the address form from it.
+ */
+import { reportError } from '../config.ts';
+import { get, qsa, repeat, sel, setText } from '../dom.ts';
+import { addressText, bindsIn, ownValue, showIn } from './markup.ts';
+import { addresses } from './operations.ts';
+import type { CustomerAddress } from './page-answers.ts';
+
+let shown: readonly CustomerAddress[] = [];
+
+/** @returns The address with this id in the list shown last. */
+export const shownAddress = (id: string): CustomerAddress | undefined => shown.find((address) => address.id === id);
+
+/** @returns The text of each `tether-address-bind` value. */
+const addressTexts = (address: CustomerAddress): Record<string, string> => ({
+  formatted: addressText(address),
+  name: [address.firstName, address.lastName].filter(Boolean).join(' '),
+  company: address.company || '',
+  address1: address.address1 || '',
+  address2: address.address2 || '',
+  city: address.city || '',
+  zip: address.zip || '',
+  province: address.province || '',
+  country: address.country || '',
+  phone: address.phoneNumber || '',
+});
+
+function fillAddress(row: HTMLElement, address: CustomerAddress): void {
+  row.dataset['tetherAddress'] = address.id;
+  const texts = addressTexts(address);
+  bindsIn(row, 'address-bind').forEach((el) => {
+    const text = ownValue(texts, get(el, 'address-bind') ?? '');
+    if (text !== undefined) setText(el, text);
+  });
+  showIn(row, 'address-show', { default: address.isDefault, 'not-default': !address.isDefault });
+}
+
+/** Loads and renders the addresses. A failure is reported and shows `addresses-error`, never "no addresses yet". */
+export async function renderAddresses(root: ParentNode): Promise<void> {
+  const boxes = qsa(root, sel('addresses'));
+  if (!boxes.length) return;
+  showIn(root, 'show', { 'addresses-loading': true, 'addresses-empty': false });
+  let list: CustomerAddress[];
+  try {
+    list = await addresses();
+  } catch (error) {
+    reportError(error, 'addresses');
+    showIn(root, 'show', { 'addresses-loading': false, 'addresses-error': true });
+    return;
+  }
+  shown = list;
+  showIn(root, 'show', { 'addresses-loading': false, 'addresses-empty': list.length === 0, 'addresses-error': false });
+  boxes.forEach((box) => {
+    repeat(box, list, fillAddress);
+  });
+}

package/src/account/answers.ts

@@ -0,0 +1,79 @@
+/**
+ * The Worker's account answers as typed values. The Worker passes on what Shopify answers to its fixed documents, and
+ * each answer is read once, field by field. Every field a document selects is kept. One that is missing or of another
+ * type reads as `null` (a list as empty, a count as 0): a page with one blank field is better than no page. The ids
+ * the pages act on are required, and an answer without one is an error. This module reads what the account part
+ * shows (the customer, their orders through the reader the Worker shares, Shopify's `userErrors`); page-answers.ts
+ * reads the account pages' answers.
+ */
+import { TetherError } from '../client.ts';
+import type { UserError } from '../client.ts';
+import { field, isRecord, listOf, textList, textOrNull } from '../../server/src/shared/json.ts';
+import { readOrders } from '../../server/src/shared/account-orders.ts';
+import type { AccountOrder } from '../../server/src/shared/account-orders.ts';
+
+/** The logged-in customer. */
+export interface AccountCustomer {
+  /** The customer's gid; left out when the Worker's `/me` doesn't send it. */
+  id?: string;
+  firstName: string | null;
+  lastName: string | null;
+  displayName: string | null;
+  emailAddress: { emailAddress: string } | null;
+  defaultAddress: { formatted: string[] } | null;
+}
+
+export const unexpected = (what: string): TetherError =>
+  new TetherError(`Customer accounts: the answer has no ${what}`);
+
+/**
+ * @param what Named in the error.
+ * @throws {TetherError} Without an id.
+ */
+export function requiredId(value: unknown, what: string): string {
+  const id = textOrNull(value);
+  if (!id) throw unexpected(what);
+  return id;
+}
+
+/** @param value The `customer` of the Worker's `/me`, which flattens the email and the default address. */
+export function toAccountCustomer(value: unknown): AccountCustomer {
+  const customer = isRecord(value) ? value : {};
+  const id = textOrNull(customer['id']);
+  const email = textOrNull(customer['email']);
+  const address = customer['address'];
+  return {
+    ...(id === null ? {} : { id }),
+    firstName: textOrNull(customer['firstName']),
+    lastName: textOrNull(customer['lastName']),
+    displayName: textOrNull(customer['displayName']),
+    emailAddress: email === null ? null : { emailAddress: email },
+    defaultAddress: Array.isArray(address) ? { formatted: textList(address) } : null,
+  };
+}
+
+/**
+ * @param value The `orders` of the Worker's `/orders`.
+ * @throws {TetherError} For an order without an id.
+ */
+export function toAccountOrders(value: unknown): AccountOrder[] {
+  const reading = readOrders(value);
+  if (reading.kind === 'missing-id') throw unexpected('order id');
+  return reading.orders;
+}
+
+/** @returns `null` for an entry without a message, which has nothing to show. */
+function toUserError(value: unknown): UserError | null {
+  const message = textOrNull(field(value, 'message'));
+  if (message === null) return null;
+  const fieldPath = field(value, 'field');
+  return {
+    message,
+    field: Array.isArray(fieldPath) ? textList(fieldPath) : null,
+    code: textOrNull(field(value, 'code')),
+  };
+}
+
+/** @param value Shopify's `userErrors`, as Shopify or the Worker sends them. */
+export const toUserErrors = (value: unknown): UserError[] =>
+  listOf(value, toUserError).filter((error) => error !== null);

package/src/account/markup.ts

@@ -0,0 +1,36 @@
+/**
+ * The account markup's shared vocabulary: `tether-*-show` conditions, binds on a template row (the row itself may
+ * carry one), and how Shopify's enum values and formatted addresses read on the page.
+ */
+import { get, qsa, sel, show } from '../dom.ts';
+
+/**
+ * Shows or hides each `name` element whose value is one of `conditions`' keys; other values are left alone.
+ *
+ * @param name `show`, `order-show`, `address-show`…
+ */
+export function showIn(root: ParentNode, name: string, conditions: Readonly<Record<string, boolean>>): void {
+  qsa(root, sel(name)).forEach((el) => {
+    const key = get(el, name) ?? '';
+    if (Object.hasOwn(conditions, key)) show(el, conditions[key] === true);
+  });
+}
+
+/**
+ * @param row A copy of a repeater's template.
+ * @returns The `name` elements in `row`, and `row` itself when it carries `name`.
+ */
+export const bindsIn = (row: HTMLElement, name: string): HTMLElement[] =>
+  qsa(row, sel(name)).concat(row.matches(sel(name)) ? [row] : []);
+
+/** @returns A Shopify enum as text: `PARTIALLY_FULFILLED` → `partially fulfilled`. */
+export const enumText = (value: string | null | undefined): string =>
+  value ? value.toLowerCase().replace(/_/g, ' ') : '';
+
+/** @returns Shopify's formatted address on one line. */
+export const addressText = (address: { formatted?: string[] | null } | null | undefined): string =>
+  (address?.formatted ?? []).join(', ');
+
+/** A bind's value, looked up by the attribute's text: only the table's own keys, never `constructor` and the like. */
+export const ownValue = <T>(values: Readonly<Record<string, T>>, key: string): T | undefined =>
+  Object.hasOwn(values, key) ? values[key] : undefined;

package/src/account/operations.ts

@@ -0,0 +1,145 @@
+/**
+ * The account pages' operations: the Worker's fixed routes (shared/account-routes.ts), which check the input and run
+ * the documents with the customer's token. Each result is read into its typed shape (page-answers.ts), and a failure
+ * is a `TetherError`: `NOT_LOGGED_IN`, `INVALID` for input the Worker or Shopify refuses, `NETWORK`, and
+ * `HTTP_<status>` for a request that failed.
+ */
+import { TetherError } from '../client.ts';
+import { emit } from '../dom.ts';
+import { operationRequest } from '../../server/src/shared/account-routes.ts';
+import type {
+  AddressFields,
+  OperationInputs,
+  OperationName,
+  ReturnLine,
+  SubscriptionAction,
+} from '../../server/src/shared/account-routes.ts';
+
+export type { AddressFields, ReturnLine };
+import {
+  toAccountAddress,
+  toCustomerAddresses,
+  toDeletedId,
+  toOrderDetail,
+  toProfile,
+  toReturn,
+  toSubscriptionChange,
+  toSubscriptionContracts,
+} from './page-answers.ts';
+import type {
+  AccountAddress,
+  CustomerAddress,
+  OpenedReturn,
+  OrderDetail,
+  Profile,
+  SubscriptionChange,
+  SubscriptionContract,
+} from './page-answers.ts';
+import type { ServerAnswer, ServerRequest } from './server-client.ts';
+import type { AccountCustomer } from './answers.ts';
+
+/** The account part's session, shared so both parts act as one customer. */
+interface PagesContext {
+  serverFetch: (path: string, request?: ServerRequest) => Promise<ServerAnswer>;
+  customer: () => Promise<AccountCustomer | null>;
+  bindCustomer: (root: ParentNode) => Promise<void>;
+  /** Forgets the cached customer after a change of their data. */
+  reset: () => void;
+}
+
+/** `tether:account-updated`'s `what`. */
+type ChangedData = 'profile' | 'addresses' | 'subscriptions' | 'orders';
+
+let context: PagesContext | null = null;
+
+/** Called by the account part once, when it loads this part. */
+export function setup(shared: PagesContext): void {
+  context = shared;
+}
+
+/** @throws {Error} Before `setup`: this part is only ever loaded by the account part, which calls it first. */
+export function pagesContext(): PagesContext {
+  if (!context) throw new Error('account-pages: loaded without the account part');
+  return context;
+}
+
+/**
+ * @returns The operation's result fields, read by the caller.
+ * @throws {TetherError} With one of the codes in the file's comment.
+ */
+async function run<Name extends OperationName>(
+  name: Name,
+  input: OperationInputs[Name],
+): Promise<Record<string, unknown>> {
+  const { serverFetch } = pagesContext();
+  const { method, path } = operationRequest(name, input);
+  const answer = await serverFetch(path, method === 'POST' ? { method, body: input } : {});
+  if (answer.kind === 'logged-out') throw new TetherError('Not logged in', { code: 'NOT_LOGGED_IN', status: 401 });
+  return answer.data;
+}
+
+function changed(what: ChangedData): void {
+  pagesContext().reset();
+  emit('account-updated', { what });
+}
+
+/**
+ * One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns).
+ *
+ * @param id A gid or the numeric order id.
+ * @returns `null` when the customer has no such order.
+ */
+export async function order(id: string | number): Promise<OrderDetail | null> {
+  const result = await run('order', { id });
+  return toOrderDetail(result['order']);
+}
+
+export async function updateProfile({
+  firstName,
+  lastName,
+}: { firstName?: string; lastName?: string } = {}): Promise<Profile> {
+  const result = await run('profile', { firstName, lastName });
+  changed('profile');
+  return toProfile(result['customer']);
+}
+
+/** @returns The customer's addresses, the default one marked `isDefault`. */
+export async function addresses(): Promise<CustomerAddress[]> {
+  const result = await run('addresses', {});
+  return toCustomerAddresses(result['addresses']);
+}
+
+/** Creates an address, or updates the one with `id`; without fields, only makes it the default. */
+export async function saveAddress(
+  address: AddressFields | null,
+  { id, isDefault }: { id?: string | undefined; isDefault?: boolean } = {},
+): Promise<AccountAddress> {
+  const result = await run('saveAddress', { id, address, isDefault });
+  changed('addresses');
+  return toAccountAddress(result['address']);
+}
+
+/** @returns The deleted address's id. */
+export async function deleteAddress(id: string): Promise<string> {
+  const result = await run('deleteAddress', { id });
+  changed('addresses');
+  return toDeletedId(result['deleted']);
+}
+
+export async function subscriptions(): Promise<SubscriptionContract[]> {
+  const result = await run('subscriptions', {});
+  return toSubscriptionContracts(result['subscriptions']);
+}
+
+/** @returns The changed contract or billing cycle. */
+export async function subscriptionAction(id: string | number, action: SubscriptionAction): Promise<SubscriptionChange> {
+  const result = await run('subscription', { id, action });
+  changed('subscriptions');
+  return toSubscriptionChange(result);
+}
+
+export async function requestReturn(orderId: string | number, lines: ReturnLine[]): Promise<OpenedReturn> {
+  const result = await run('requestReturn', { orderId, lines });
+  changed('orders');
+  return toReturn(result['return']);
+}

package/src/account/{order-lines.js → order-lines.ts}

@@ -3,32 +3,23 @@
  * lines also carry price, total, sku and what can be returned; the order list's document has none of those, so they
  * render empty there, and its rows get no return controls.
  */
-import { formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.js';
-import { bindsIn, ownValue, showIn } from './markup.js';
-/** @import { Money } from '../shopify-values.js' */
+import { formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.ts';
+import { bindsIn, ownValue, showIn } from './markup.ts';
+import type { AccountOrderLine } from '../../server/src/shared/account-orders.ts';
+import type { OrderDetailLine } from './page-answers.ts';
 
-/**
- * @typedef {object} OrderLine A line of `ORDERS_QUERY` or of the order page's document (account-ops.js).
- * @property {string} [id] Only on the order page.
- * @property {string} [name]
- * @property {string} title
- * @property {string | null} [variantTitle]
- * @property {number} quantity
- * @property {string | null} [sku]
- * @property {{ url: string, altText: string | null } | null} [image]
- * @property {Money | null} [price]
- * @property {Money | null} [totalPrice]
- * @property {{ nodes: { id: string, name: string }[] }} [suggestedReturnReasonDefinitions]
- */
-/** @typedef {ReadonlyMap<string, number>} Returnable Line id → how many of it can still be returned. */
+/** A line of the order list, or of the order page, which has the fields after `image` too. */
+type OrderLine = AccountOrderLine &
+  Partial<Pick<OrderDetailLine, 'id' | 'name' | 'sku' | 'price' | 'totalPrice' | 'suggestedReturnReasonDefinitions'>>;
+/** Line id → how many of it can still be returned. */
+type Returnable = ReadonlyMap<string, number>;
 
 /**
- * @param {OrderLine} line
- * @param {number | null} returnable `null` in the order list, which knows nothing of returns.
- * @returns {Record<string, string | undefined>} The text of each `tether-order-line` value.
+ * @param returnable `null` in the order list, which knows nothing of returns.
+ * @returns The text of each `tether-order-line` value.
  */
-const lineTexts = (line, returnable) => ({
-  title: line.title || line.name,
+const lineTexts = (line: OrderLine, returnable: number | null): Record<string, string | undefined> => ({
+  title: line.title || line.name || '',
   'variant-title': line.variantTitle || '',
   quantity: String(line.quantity),
   price: formatMoney(line.price),
@@ -37,20 +28,10 @@ const lineTexts = (line, returnable) => ({
   returnable: returnable === null ? undefined : String(returnable),
 });
 
-/**
- * @param {HTMLElement} el
- * @returns {el is HTMLInputElement}
- */
-const isInput = (el) => el.tagName === 'INPUT';
+const isInput = (el: HTMLElement): el is HTMLInputElement => el.tagName === 'INPUT';
 
-/**
- * The return controls of one line: how many can be returned, and Shopify's suggested reasons.
- *
- * @param {HTMLElement} row
- * @param {OrderLine & { id: string }} line
- * @param {number} returnable
- */
-function fillReturnControls(row, line, returnable) {
+/** The return controls of one line: how many can be returned, and Shopify's suggested reasons. */
+function fillReturnControls(row: HTMLElement, line: OrderLine & { id: string }, returnable: number): void {
   showIn(row, 'order-line-show', { returnable: returnable > 0 });
   qsa(row, sel('return-quantity')).forEach((input) => {
     if (!isInput(input)) return;
@@ -64,7 +45,7 @@ function fillReturnControls(row, line, returnable) {
     if (select.dataset['tetherFilled'] === line.id) return;
     select.dataset['tetherFilled'] = line.id;
     (line.suggestedReturnReasonDefinitions?.nodes ?? []).forEach((reason) => {
-      select.appendChild(new Option(reason.name, reason.id));
+      select.appendChild(new Option(reason.name ?? '', reason.id));
     });
   });
 }
@@ -72,11 +53,9 @@ function fillReturnControls(row, line, returnable) {
 /**
  * Renders `lines` into a `tether-order-lines` repeater.
  *
- * @param {HTMLElement} box
- * @param {readonly OrderLine[]} lines
- * @param {Returnable | null} returns `null` for the order list.
+ * @param returns `null` for the order list.
  */
-export function fillLines(box, lines, returns) {
+export function fillLines(box: HTMLElement, lines: readonly OrderLine[], returns: Returnable | null): void {
   repeat(box, lines, (row, line) => {
     const id = line.id;
     const returnable = returns && id ? (returns.get(id) ?? 0) : null;
@@ -85,7 +64,7 @@ export function fillLines(box, lines, returns) {
     bindsIn(row, 'order-line').forEach((el) => {
       const key = get(el, 'order-line') ?? '';
       if (key === 'image') {
-        if (line.image) setImage(el, line.image.url, line.image.altText || line.title);
+        if (line.image) setImage(el, line.image.url, line.image.altText || line.title || '');
         return;
       }
       const text = ownValue(texts, key);

package/src/account/order-list.ts

@@ -0,0 +1,107 @@
+/**
+ * The customer's recent orders (`tether-orders`), with `tether-show="orders-loading"` while they load and
+ * `orders-empty` when there are none yet.
+ */
+import { cfg, reportError } from '../config.ts';
+import { isHttpsUrl } from '../shopify-values.ts';
+import { formatDate, formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.ts';
+import { ownValue, showIn } from './markup.ts';
+import { fillLines } from './order-lines.ts';
+import type { AccountOrder } from '../../server/src/shared/account-orders.ts';
+
+/** How many orders `orders()` answers, and a `tether-orders` list shows, without being told. */
+export const DEFAULT_ORDER_COUNT = 10;
+/** The most orders one request asks for: the Worker answers no more. */
+export const MAX_ORDER_COUNT = 50;
+
+/** @returns True for a number of orders one request can ask for: a whole number from 1 to `MAX_ORDER_COUNT`. */
+export const isOrderCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_ORDER_COUNT;
+
+/**
+ * @param limit The list's `tether-limit`.
+ * @returns How many orders the list shows: the limit, kept within what one request can ask for.
+ */
+function listLimit(limit: string | null): number {
+  const asked = Number.parseInt(limit || String(DEFAULT_ORDER_COUNT), 10) || DEFAULT_ORDER_COUNT;
+  return Math.min(Math.max(asked, 1), MAX_ORDER_COUNT);
+}
+
+/**
+ * @param gid `gid://shopify/Order/123`, possibly with a query.
+ * @returns The numeric id at its end.
+ */
+const numericId = (gid: string): string => gid.replace(/\?.*$/, '').replace(/^.*\//, '');
+
+/**
+ * The order's page: the site's own (`account.orderUrl`, e.g. `/account/order?id={id}`, every `{id}` the numeric
+ * order id), else Shopify's status page when it is https.
+ */
+function orderUrl(order: AccountOrder): string | null {
+  const template = cfg.account?.orderUrl;
+  if (template) return template.replaceAll('{id}', encodeURIComponent(numericId(order.id)));
+  const statusPage = order.statusPageUrl;
+  return statusPage !== null && isHttpsUrl(statusPage) ? statusPage : null;
+}
+
+/** @returns The text of each `tether-order-bind` value. */
+const orderTexts = (order: AccountOrder): Record<string, string | undefined> => ({
+  name: order.name ?? '',
+  date: formatDate(order.processedAt),
+  total: formatMoney(order.totalPrice),
+  status: order.financialStatus?.toLowerCase(),
+  fulfillment: order.fulfillmentStatus?.toLowerCase(),
+  items: order.lineItems.nodes.map((line) => `${String(line.quantity)}× ${line.title ?? ''}`).join(', '),
+});
+
+/** @param node A copy of the list's template. */
+function fillOrder(node: HTMLElement, order: AccountOrder): void {
+  const lines = order.lineItems.nodes;
+  const url = orderUrl(order);
+  const texts = orderTexts(order);
+  qsa(node, sel('order-bind')).forEach((el) => {
+    const key = get(el, 'order-bind') ?? '';
+    if (key === 'url') {
+      if (url) el.setAttribute('href', url);
+      return;
+    }
+    if (key === 'image') {
+      const image = lines.find((line) => line.image)?.image;
+      if (image) setImage(el, image.url, image.altText || lines[0]?.title || '');
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(el, text);
+  });
+  qsa(node, sel('order-lines')).forEach((box) => {
+    fillLines(box, lines, null);
+  });
+  if (get(node, 'order-bind') === 'url' && url) node.setAttribute('href', url);
+}
+
+/**
+ * Fills every `tether-orders` list in `root`. A failure is reported and leaves the lists empty, without claiming the
+ * customer has no orders.
+ */
+export async function renderOrderList(
+  root: ParentNode,
+  loadOrders: (first: number) => Promise<AccountOrder[]>,
+): Promise<void> {
+  const lists = qsa(root, sel('orders'));
+  const first = lists[0];
+  if (!first) return;
+  showIn(root, 'show', { 'orders-loading': true, 'orders-empty': false });
+  const limit = listLimit(get(first, 'limit'));
+  /** `null` after a failure. */
+  let orders: AccountOrder[] | null;
+  try {
+    orders = await loadOrders(limit);
+  } catch (error) {
+    reportError(error, 'orders');
+    orders = null;
+  }
+  showIn(root, 'show', { 'orders-loading': false, 'orders-empty': orders?.length === 0 });
+  lists.forEach((list) => {
+    repeat(list, orders ?? [], fillOrder);
+  });
+}