@occluze/tether 0.6.7 → 0.7.0

package/src/account/page-events.ts

@@ -0,0 +1,253 @@
+/**
+ * What the visitor does on the account pages: the profile and address forms, the address buttons, subscription
+ * actions and return requests. Each change marks its form or row busy (`aria-busy`, `is-busy`), then sets
+ * `tether-form-state` to `saved` or `error` with Shopify's message in `tether-form-error`.
+ */
+import { attr, get, qsa, sel, setText } from '../dom.ts';
+import {
+  saveAddress,
+  deleteAddress,
+  subscriptionAction,
+  requestReturn,
+  updateProfile,
+  pagesContext,
+} from './operations.ts';
+import type { ReturnLine } from './operations.ts';
+import { renderAddresses, shownAddress } from './addresses-view.ts';
+import { renderSubscriptions } from './subscriptions-view.ts';
+import { renderOrder } from './order-page.ts';
+import { TetherError } from '../client.ts';
+import type { SubscriptionAction } from '../../server/src/shared/account-routes.ts';
+
+const SUBSCRIPTION_ACTIONS: readonly SubscriptionAction[] = ['pause', 'resume', 'skip', 'unskip', 'cancel'];
+
+const isSubscriptionAction = (value: string | null): value is SubscriptionAction =>
+  SUBSCRIPTION_ACTIONS.some((action) => action === value);
+
+const isField = (el: Element): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
+  el instanceof window.HTMLInputElement ||
+  el instanceof window.HTMLSelectElement ||
+  el instanceof window.HTMLTextAreaElement;
+
+const isForm = (el: Element): el is HTMLFormElement => el instanceof window.HTMLFormElement;
+
+/** @returns The form's text fields by name. */
+function fieldsOf(form: HTMLFormElement): Record<string, string> {
+  const fields: Record<string, string> = {};
+  for (const field of form.elements) {
+    if (!isField(field)) continue;
+    if (!field.name || field.type === 'submit' || field.type === 'button' || field.type === 'checkbox') continue;
+    fields[field.name] = field.value;
+  }
+  return fields;
+}
+
+/** @returns What to tell the customer: Shopify's own messages when it refused the input. */
+function customerMessage(error: unknown): string {
+  const userErrors = error instanceof TetherError ? (error.userErrors ?? []) : [];
+  const message = userErrors.map((userError) => userError.message).join(' ');
+  if (message) return message;
+  const text = error instanceof Error && error.message ? error.message : 'Something went wrong';
+  return text.replace(/^Customer accounts: /, '');
+}
+
+/**
+ * Runs one change for `el`; a second one while it is on its way (Enter, a double click) is ignored. The failure is
+ * shown in `el` (`tether-form-error`), the place the customer looks.
+ */
+async function act(el: HTMLElement, change: () => Promise<void>): Promise<'saved' | 'error' | 'busy'> {
+  if (el.getAttribute('aria-busy') === 'true') return 'busy';
+  el.classList.add('is-busy');
+  el.setAttribute('aria-busy', 'true');
+  el.setAttribute(attr('form-state'), 'pending');
+  const errorBoxes = qsa(el, sel('form-error'));
+  errorBoxes.forEach((box) => {
+    setText(box, '');
+  });
+  try {
+    await change();
+    el.setAttribute(attr('form-state'), 'saved');
+    return 'saved';
+  } catch (error) {
+    el.setAttribute(attr('form-state'), 'error');
+    errorBoxes.forEach((box) => {
+      setText(box, customerMessage(error));
+    });
+    return 'error';
+  } finally {
+    el.classList.remove('is-busy');
+    el.removeAttribute('aria-busy');
+  }
+}
+
+/** @returns True when the button asks no `tether-confirm` question, or the visitor agreed. */
+const confirmed = (button: Element): boolean => {
+  const question = get(button, 'confirm');
+  return !question || window.confirm(question);
+};
+
+const addressFormReset = (form: HTMLFormElement): void => {
+  form.reset();
+  delete form.dataset['tetherAddressId'];
+};
+
+function onSubmit(event: SubmitEvent): void {
+  const form = event.target;
+  if (!(form instanceof window.HTMLFormElement)) return;
+  if (form.matches(sel('profile-form'))) {
+    event.preventDefault();
+    void act(form, async () => {
+      await updateProfile(fieldsOf(form));
+      await pagesContext().bindCustomer(document);
+    });
+  } else if (form.matches(sel('address-form'))) {
+    event.preventDefault();
+    const id = form.dataset['tetherAddressId'];
+    const box = form.elements.namedItem('isDefault');
+    const isDefault = box instanceof window.HTMLInputElement && box.checked;
+    void act(form, async () => {
+      await saveAddress(fieldsOf(form), { id, isDefault });
+      addressFormReset(form);
+      await renderAddresses(document);
+    });
+  }
+}
+
+/** Fills the address form with a shown address, to edit it. */
+function editAddress(id: string): void {
+  const address = shownAddress(id);
+  const form = document.querySelector(sel('address-form'));
+  if (!address || !form || !isForm(form)) return;
+  form.dataset['tetherAddressId'] = address.id;
+  const valuesByName: Readonly<Record<string, unknown>> = { ...address };
+  for (const field of form.elements) {
+    if (!isField(field)) continue;
+    if (field.name === 'isDefault') {
+      if (field instanceof window.HTMLInputElement) field.checked = address.isDefault;
+    } else if (field.name && Object.hasOwn(valuesByName, field.name)) {
+      const value = valuesByName[field.name];
+      field.value = typeof value === 'string' ? value : '';
+    }
+  }
+  form.scrollIntoView({ block: 'nearest' });
+}
+
+/** @returns True when the click was on an address button. */
+function onAddressClick(event: MouseEvent, target: Element): boolean {
+  const row = target.closest('[data-tether-address]');
+  const id = row instanceof window.HTMLElement ? row.dataset['tetherAddress'] : undefined;
+  if (target.closest(sel('address-new'))) {
+    const form = document.querySelector(sel('address-form'));
+    if (form && isForm(form)) addressFormReset(form);
+    return true;
+  }
+  if (!(row instanceof window.HTMLElement) || !id) return false;
+  const deleteButton = target.closest(sel('address-delete'));
+  if (deleteButton) {
+    event.preventDefault();
+    if (!confirmed(deleteButton)) return true;
+    void act(row, async () => {
+      await deleteAddress(id);
+      await renderAddresses(document);
+    });
+  } else if (target.closest(sel('address-default'))) {
+    event.preventDefault();
+    void act(row, async () => {
+      await saveAddress(null, { id, isDefault: true });
+      await renderAddresses(document);
+    });
+  } else if (target.closest(sel('address-edit'))) {
+    event.preventDefault();
+    editAddress(id);
+  } else {
+    return false;
+  }
+  return true;
+}
+
+/** @param button A `tether-subscription-action` button. */
+function onSubscriptionAction(button: HTMLElement): void {
+  const row = button.closest('[data-tether-subscription]');
+  const action = get(button, 'subscription-action');
+  const disabled = ('disabled' in button && button.disabled === true) || button.classList.contains('is-disabled');
+  if (!(row instanceof window.HTMLElement) || !isSubscriptionAction(action) || disabled || !confirmed(button)) return;
+  const id = row.dataset['tetherSubscription'] ?? '';
+  row.setAttribute(attr('subscription-state'), 'pending');
+  void act(row, async () => {
+    await subscriptionAction(id, action);
+    await renderSubscriptions(document);
+  }).then((outcome) => {
+    const state = outcome === 'error' ? 'error' : 'done';
+    // The re-render may have replaced the row: mark the one that shows this subscription now.
+    qsa(document, '[data-tether-subscription]')
+      .filter((candidate) => candidate === row || candidate.dataset['tetherSubscription'] === id)
+      .forEach((candidate) => {
+        candidate.setAttribute(attr('subscription-state'), state);
+      });
+  });
+}
+
+/** @param row A line row of the order page. */
+function returnLineOf(row: HTMLElement): ReturnLine {
+  const quantity = row.querySelector(sel('return-quantity'));
+  const reason = row.querySelector(sel('return-reason'));
+  const note = row.querySelector(sel('return-note'));
+  const valueOf = (field: Element | null) =>
+    field && 'value' in field && typeof field.value === 'string' ? field.value : '';
+  const line: ReturnLine = {
+    lineItemId: row.dataset['tetherLine'] ?? '',
+    quantity: Number.parseInt(valueOf(quantity) || '0', 10),
+  };
+  const reasonId = valueOf(reason);
+  if (reasonId) line.reasonId = reasonId;
+  const noteText = valueOf(note);
+  if (noteText) line.note = noteText;
+  return line;
+}
+
+/** @param button A `tether-order-return` button. */
+function onReturnRequest(button: HTMLElement): void {
+  const scope = button.closest(sel('order'));
+  if (!(scope instanceof window.HTMLElement)) return;
+  const orderId = scope.dataset['tetherOrderId'];
+  if (!orderId) return;
+  const lines = qsa(scope, '[data-tether-line]')
+    .map(returnLineOf)
+    .filter((line) => line.quantity > 0);
+  if (!lines.length || !confirmed(button)) return;
+  void act(scope, async () => {
+    await requestReturn(orderId, lines);
+    scope.dataset['tetherReturned'] = '1';
+    await renderOrder(scope);
+  });
+}
+
+function onClick(event: MouseEvent): void {
+  const target = event.target;
+  if (!(target instanceof window.Element)) return;
+  if (onAddressClick(event, target)) return;
+  const subscriptionButton = target.closest(sel('subscription-action'));
+  if (subscriptionButton instanceof window.HTMLElement) {
+    event.preventDefault();
+    onSubscriptionAction(subscriptionButton);
+    return;
+  }
+  const returnButton = target.closest(sel('order-return'));
+  if (returnButton instanceof window.HTMLElement) {
+    event.preventDefault();
+    onReturnRequest(returnButton);
+  }
+}
+
+/** Listens on the document once, for every account page rendered into it. */
+export function listenToPages(): void {
+  // Capture: before a router (Astro's ClientRouter) turns the submit into a navigation with the fields in the URL.
+  document.addEventListener('submit', onSubmit, true);
+  document.addEventListener('input', (event) => {
+    const target = event.target;
+    if (target instanceof window.HTMLElement && target.closest(sel('profile-form'))) {
+      target.dataset['tetherTouched'] = '1';
+    }
+  });
+  document.addEventListener('click', onClick);
+}

package/src/account/server-client.ts

@@ -0,0 +1,183 @@
+/**
+ * The browser's side of the Worker's account routes (`account.server`). The Worker holds the Shopify tokens, and
+ * this browser only a session cookie its scripts can't read; what it keeps itself is the "may be logged in" hint,
+ * which holds no secret. Storage throws in private mode and where the visitor blocks site data: the hint is then
+ * not kept, and only pages with account markup load the part.
+ */
+import { cfg } from '../config.ts';
+import { TetherError } from '../client.ts';
+import { Cart } from '../cart.ts';
+import { emit } from '../dom.ts';
+import { isRecord, textOrNull } from '../../server/src/shared/json.ts';
+import { messageOf } from '../../server/src/shared/error-message.ts';
+import { hintKey } from '../account-marks.ts';
+import { removeStored, setStored } from '../storage.ts';
+import { toAccountCustomer, toUserErrors } from './answers.ts';
+import type { AccountCustomer } from './answers.ts';
+
+/** The Worker's answer, or a 401: the session cookie is missing, has expired, or Shopify ended the login. */
+export type ServerAnswer = { kind: 'answer'; data: Record<string, unknown> } | { kind: 'logged-out' };
+type ServerLogin = { loggedIn: true; customer: AccountCustomer } | { loggedIn: false };
+export interface ServerRequest {
+  method?: 'GET' | 'POST';
+  body?: Record<string, unknown>;
+}
+
+/** The Worker's `/me` answer, until a change of the customer's data. */
+let known: ServerLogin | null = null;
+
+/**
+ * @returns The Worker's account routes, without a trailing slash. `account.server` is a full URL or a path on this
+ *   site.
+ * @throws {TetherError} `NOT_CONFIGURED` without `account.server`.
+ */
+function serverBase(): string {
+  const server = cfg.account?.server;
+  if (!server) {
+    throw new TetherError('Customer accounts need the Worker: set account.server', { code: 'NOT_CONFIGURED' });
+  }
+  return new URL(server, window.location.href).href.replace(/\/$/, '');
+}
+
+/**
+ * Keeps the hint that makes the core load the part on the next page; without storage it is not kept (see the file's
+ * comment).
+ */
+function setLoginHint(loggedIn: boolean): void {
+  if (loggedIn) setStored(hintKey(), '1');
+  else removeStored(hintKey());
+}
+
+/** @throws {TetherError} `NETWORK` when the request fails before an answer. */
+async function fetchFromWorker(url: string, init: RequestInit): Promise<Response> {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    throw new TetherError(`Network error: ${messageOf(error)}`, {
+      code: 'NETWORK',
+    });
+  }
+}
+
+/** An error page that isn't JSON reads as an empty answer: the response's status then says what went wrong. */
+async function readJsonObjectOrEmpty(response: Response): Promise<Record<string, unknown>> {
+  let json: unknown;
+  try {
+    json = await response.json();
+  } catch {
+    return {};
+  }
+  return isRecord(json) ? json : {};
+}
+
+/**
+ * One request to the Worker, with the session cookie. A POST carries the header the Worker requires against
+ * cross-site forms.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without `account.server`, `INVALID` for refused input, `HTTP_<status>` for
+ *   any other failure but a 401, with the Worker's `userErrors`; `NETWORK` when the Worker can't be reached.
+ */
+export async function serverFetch(path: string, { method = 'GET', body }: ServerRequest = {}): Promise<ServerAnswer> {
+  const init: RequestInit = { method, credentials: 'include' };
+  if (method === 'POST') init.headers = { 'Content-Type': 'application/json', 'X-Tether-Account': '1' };
+  if (body) init.body = JSON.stringify(body);
+  const response = await fetchFromWorker(`${serverBase()}${path}`, init);
+  if (response.status === 401) return { kind: 'logged-out' };
+  const data = await readJsonObjectOrEmpty(response);
+  if (!response.ok) {
+    const reason = textOrNull(data['error']) ?? String(response.status);
+    const userErrors = toUserErrors(data['userErrors']);
+    throw new TetherError(`Customer accounts: ${reason}`, {
+      status: response.status,
+      ...(userErrors.length > 0 && { userErrors }),
+      // The Worker marks refused input (a 400, or a 404 for a contract that isn't the customer's) with `code`.
+      ...(data['code'] === 'INVALID' && { code: 'INVALID' }),
+    });
+  }
+  return { kind: 'answer', data };
+}
+
+/**
+ * Who is logged in, asked once and then kept; the "may be logged in" hint follows the answer.
+ *
+ * @throws {TetherError} When the Worker can't be reached or fails: that says nothing about the login.
+ */
+export async function serverLogin(): Promise<ServerLogin> {
+  if (!known) {
+    const answer = await serverFetch('/me');
+    known =
+      answer.kind === 'answer' && answer.data['loggedIn'] === true
+        ? { loggedIn: true, customer: toAccountCustomer(answer.data['customer']) }
+        : { loggedIn: false };
+  }
+  setLoginHint(known.loggedIn);
+  return known;
+}
+
+/** @returns True when the Worker last said a customer is logged in. */
+export const isServerLoggedIn = (): boolean => known?.loggedIn === true;
+
+/** Asks the Worker again on the next `serverLogin()`, after a change of the customer's data. */
+export function forgetServerLogin(): void {
+  known = null;
+}
+
+/** Goes to the Worker's (or Shopify's) pages, through `account.navigate` when the site replaces the redirect. */
+function navigate(url: string): void {
+  const replacement = cfg.account?.navigate;
+  if (replacement) replacement(url);
+  else window.location.assign(url);
+}
+
+/**
+ * @param locale The caller's choice.
+ * @returns The language of Shopify's login page: the caller's, `account.locale`, else the site's; `''` for Shopify's
+ *   default.
+ */
+const loginLanguage = (locale: string | undefined): string =>
+  locale || cfg.account?.locale || (cfg.locale || '').split('-')[0] || '';
+
+/**
+ * To the Worker's login, which comes back to `returnTo` with `?account=<outcome>`. The cart is linked later, at
+ * checkout, through the Worker's protected `POST /cart`.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without `account.server`.
+ */
+export function serverLoginRedirect({ returnTo, locale }: { returnTo: string; locale?: string | undefined }): void {
+  const url = new URL(`${serverBase()}/login`);
+  url.searchParams.set('returnTo', returnTo);
+  const language = loginLanguage(locale);
+  if (language) url.searchParams.set('locale', language);
+  if (cfg.country) url.searchParams.set('country', cfg.country.toUpperCase());
+  navigate(url.toString());
+}
+
+/**
+ * The logged-in customer's checkout, for `Cart.setCheckoutResolver`: the Worker links the cart to the customer and
+ * answers with its checkout URL.
+ *
+ * @returns `null` when nobody is logged in or the Worker linked no cart, so the cart's own checkout URL is used.
+ * @throws {TetherError} When the Worker fails; the cart reports it and checks out without the login.
+ */
+export async function serverCheckoutUrl(): Promise<string | null> {
+  const cartId = Cart.id();
+  if (!(await serverLogin()).loggedIn || !cartId) return null;
+  const answer = await serverFetch('/cart', { method: 'POST', body: { cartId } });
+  if (answer.kind === 'logged-out') return null;
+  return textOrNull(answer.data['checkoutUrl']);
+}
+
+/**
+ * Ends the session at the Worker, which also unlinks the cart, then goes on to Shopify's logout when the Worker says
+ * where. Sends `tether:account-logout`.
+ */
+export async function serverLogout(returnTo: string): Promise<'redirected' | 'stayed'> {
+  const answer = await serverFetch('/logout', { method: 'POST', body: { returnTo, cartId: Cart.id() } });
+  known = null;
+  setLoginHint(false);
+  emit('account-logout', {});
+  const logoutUrl = answer.kind === 'answer' ? textOrNull(answer.data['logoutUrl']) : null;
+  if (!logoutUrl) return 'stayed';
+  navigate(logoutUrl);
+  return 'redirected';
+}

package/src/account/subscriptions-view.ts

@@ -0,0 +1,115 @@
+/**
+ * The customer's subscriptions (`tether-subscriptions`), with `tether-show="subscriptions-loading"`,
+ * `subscriptions-empty` and `subscriptions-error`. Each row's `tether-subscription-show` conditions and action buttons
+ * follow the contract's status and its next billing cycle.
+ */
+import { reportError } from '../config.ts';
+import { attr, formatDate, formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.ts';
+import { bindsIn, enumText, ownValue, showIn } from './markup.ts';
+import { subscriptions } from './operations.ts';
+import type { SubscriptionContract, SubscriptionLine } from './page-answers.ts';
+
+/** @returns The row's `tether-subscription-show` conditions, `can-<action>` among them. */
+function conditionsOf(contract: SubscriptionContract): Record<string, boolean> {
+  const next = contract.upcomingBillingCycles.nodes[0];
+  const status = contract.status;
+  const active = status === 'ACTIVE';
+  return {
+    active,
+    paused: status === 'PAUSED',
+    cancelled: status === 'CANCELLED',
+    expired: status === 'EXPIRED',
+    failed: status === 'FAILED',
+    skipped: Boolean(next?.skipped),
+    'can-pause': active,
+    'can-resume': status === 'PAUSED' || status === 'FAILED',
+    'can-skip': active && next !== undefined && !next.skipped,
+    'can-unskip': active && Boolean(next?.skipped),
+    'can-cancel': active || status === 'PAUSED' || status === 'FAILED',
+  };
+}
+
+/** @returns `month`, `3 months`; `''` without a delivery policy. */
+function intervalText(contract: SubscriptionContract): string {
+  const unit = enumText(contract.deliveryPolicy?.interval);
+  if (!unit) return '';
+  const count = contract.deliveryPolicy?.intervalCount?.count ?? 1;
+  return count <= 1 ? unit : `${String(count)} ${unit}s`;
+}
+
+/** @returns The text of each `tether-subscription-bind` value. */
+function contractTexts(contract: SubscriptionContract): Record<string, string> {
+  const lines = contract.lines.nodes;
+  const total = lines.reduce((sum, line) => sum + Number.parseFloat(line.lineDiscountedPrice?.amount ?? '0'), 0);
+  return {
+    status: enumText(contract.status),
+    next: formatDate(contract.nextBillingDate),
+    interval: intervalText(contract),
+    products: lines.map((line) => `${String(line.quantity)}× ${line.title ?? ''}`).join(', '),
+    total: formatMoney(
+      lines.length && contract.currencyCode ? { amount: String(total), currencyCode: contract.currencyCode } : null,
+    ),
+    delivery: formatMoney(contract.deliveryPrice),
+  };
+}
+
+function fillLine(row: HTMLElement, line: SubscriptionLine): void {
+  const texts: Record<string, string> = {
+    title: line.title ?? '',
+    'variant-title': line.variantTitle || '',
+    quantity: String(line.quantity),
+    price: formatMoney(line.currentPrice),
+  };
+  bindsIn(row, 'subscription-line').forEach((el) => {
+    const key = get(el, 'subscription-line') ?? '';
+    if (key === 'image') {
+      if (line.image) setImage(el, line.image.url, line.image.altText || line.title || '');
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(el, text);
+  });
+}
+
+function fillContract(row: HTMLElement, contract: SubscriptionContract): void {
+  row.dataset['tetherSubscription'] = contract.id;
+  row.setAttribute(attr('subscription-status'), enumText(contract.status));
+  const texts = contractTexts(contract);
+  qsa(row, sel('subscription-bind')).forEach((el) => {
+    const text = ownValue(texts, get(el, 'subscription-bind') ?? '');
+    if (text !== undefined) setText(el, text);
+  });
+  qsa(row, sel('subscription-lines')).forEach((box) => {
+    repeat(box, contract.lines.nodes, fillLine);
+  });
+  const conditions = conditionsOf(contract);
+  showIn(row, 'subscription-show', conditions);
+  qsa(row, sel('subscription-action')).forEach((button) => {
+    const allowed = ownValue(conditions, `can-${get(button, 'subscription-action') ?? ''}`) === true;
+    if ('disabled' in button) button.disabled = !allowed;
+    button.classList.toggle('is-disabled', !allowed);
+  });
+}
+
+/** Loads and renders the subscriptions. A failure is reported and shows `subscriptions-error`. */
+export async function renderSubscriptions(root: ParentNode): Promise<void> {
+  const boxes = qsa(root, sel('subscriptions'));
+  if (!boxes.length) return;
+  showIn(root, 'show', { 'subscriptions-loading': true, 'subscriptions-empty': false });
+  let list: SubscriptionContract[];
+  try {
+    list = await subscriptions();
+  } catch (error) {
+    reportError(error, 'subscriptions');
+    showIn(root, 'show', { 'subscriptions-loading': false, 'subscriptions-error': true });
+    return;
+  }
+  showIn(root, 'show', {
+    'subscriptions-loading': false,
+    'subscriptions-empty': list.length === 0,
+    'subscriptions-error': false,
+  });
+  boxes.forEach((box) => {
+    repeat(box, list, fillContract);
+  });
+}

package/src/account-api.ts

@@ -0,0 +1,98 @@
+/**
+ * The core's side of customer accounts, which are an optional part: whether a page needs the part, and
+ * `Tether.account`, whose functions load it on first call. Every function returns a promise, the part's own sync ones
+ * (`isLoggedIn`) too, because the part may still have to load.
+ */
+import { cfg, reportError } from './config.ts';
+import { attr } from './dom.ts';
+import { loadPart } from './lazy.ts';
+import { within } from './mounting.ts';
+import { hintKey, isLoginOutcome } from './account-marks.ts';
+import { getStored } from './storage.ts';
+import type { Parts } from './lazy.ts';
+
+type AccountPart = Parts['account'];
+type AccountResult<Name extends keyof AccountPart> = Awaited<ReturnType<AccountPart[Name]>>;
+type AccountFunction<Name extends keyof AccountPart> = (
+  ...args: Parameters<AccountPart[Name]>
+) => Promise<AccountResult<Name>>;
+type AccountApi = { [Name in keyof AccountPart]: AccountFunction<Name> };
+
+/** The attributes of the account markup: a page with one of them loads the part. */
+const ACCOUNT_ATTRIBUTES = [
+  'account-login',
+  'account-bind',
+  'account-link',
+  'orders',
+  'order',
+  'addresses',
+  'subscriptions',
+  'profile-form',
+  'address-form',
+];
+
+/** @returns A selector for every element the account part fills in or shows. */
+const accountSelector = (): string =>
+  [...ACCOUNT_ATTRIBUTES.map((name) => `[${attr(name)}]`), `[${attr('show')}^="logged-"]`].join(',');
+
+/**
+ * Whether this browser keeps the "may be logged in" hint, so checkout on a page without account markup still knows
+ * the customer.
+ *
+ * @returns False where the browser blocks storage, which then holds no hint.
+ */
+function hasLoginHint(): boolean {
+  return Boolean(getStored(hintKey()));
+}
+
+/**
+ * Loads the account part and mounts it on `root`, when accounts are configured and the page needs them: account
+ * markup in `root`, a login coming back from the Worker (`?account=`), or the "may be logged in" hint.
+ */
+export function mountAccountIfUsed(root: ParentNode): void {
+  if (!cfg.account) return;
+  const needed =
+    within(root, accountSelector()).length > 0 ||
+    isLoginOutcome(new URLSearchParams(window.location.search).get('account')) ||
+    hasLoginHint();
+  if (!needed) return;
+  loadPart('account')
+    .then((part) => part.mountAccount(root))
+    .catch((error: unknown) => {
+      reportError(error, 'account');
+    });
+}
+
+/** @returns `name` of the account part, called once the part has loaded. */
+function fromPart<Name extends keyof AccountPart>(name: Name): AccountFunction<Name> {
+  return (...args) =>
+    loadPart('account').then((part) => {
+      // `Name` picks one function of the part, and `args` are that function's parameters.
+      const call = part[name] as (
+        ...callArgs: Parameters<AccountPart[Name]>
+      ) => AccountResult<Name> | PromiseLike<AccountResult<Name>>;
+      return call(...args);
+    });
+}
+
+/**
+ * `Tether.account`: the account part's functions, each loading the part on first call. A plain object, so `await
+ * Tether.account` and `Object.keys(Tether.account)` behave as for any object.
+ */
+export const accountApi: AccountApi = {
+  login: fromPart('login'),
+  logout: fromPart('logout'),
+  isLoggedIn: fromPart('isLoggedIn'),
+  customer: fromPart('customer'),
+  orders: fromPart('orders'),
+  order: fromPart('order'),
+  updateProfile: fromPart('updateProfile'),
+  addresses: fromPart('addresses'),
+  saveAddress: fromPart('saveAddress'),
+  deleteAddress: fromPart('deleteAddress'),
+  subscriptions: fromPart('subscriptions'),
+  subscriptionAction: fromPart('subscriptionAction'),
+  requestReturn: fromPart('requestReturn'),
+  render: fromPart('render'),
+  mountAccount: fromPart('mountAccount'),
+};

package/src/account-marks.ts

@@ -0,0 +1,35 @@
+/**
+ * What tells a page that customer accounts are in use in this browser: the "may be logged in" hint the account part
+ * keeps in `localStorage`, and the Worker's `?account=` mark after a login. The core reads them to decide whether a
+ * page loads the part, and the part writes the hint, so both take them from here.
+ */
+import { cfg } from './config.ts';
+import { removeStored } from './storage.ts';
+
+/**
+ * What the Worker's login redirect says in `?account=`: `in` after a login, `expired` when the login took too long,
+ * `error` when it failed.
+ */
+type LoginOutcome = 'in' | 'expired' | 'error';
+
+/** The "may be logged in" hint's key: it makes the core load the part on the next page, and holds no secret. */
+export const hintKey = (): string => `${cfg.prefix}:account-hint:${cfg.domain}`;
+
+/** Removes a key from both storage areas, each on its own: a blocked one doesn't keep the key in the other. */
+function removeFromBothAreas(key: string): void {
+  removeStored(key, 'sessionStorage');
+  removeStored(key, 'localStorage');
+}
+
+/**
+ * Removes the customer tokens and pending login that Tether 0.6's browser-mode accounts kept in this browser. The
+ * session held a refresh token with the customer's full scope, so it must not stay behind once accounts run through
+ * the Worker. TODO: remove in 0.8.0, when no visitor's browser still holds a 0.6 session.
+ */
+export function forgetBrowserModeTokens(): void {
+  removeFromBothAreas(`${cfg.prefix}:account:${cfg.domain}`);
+  removeFromBothAreas(`${cfg.prefix}:account-login:${cfg.domain}`);
+}
+
+export const isLoginOutcome = (value: string | null): value is LoginOutcome =>
+  value === 'in' || value === 'expired' || value === 'error';