@occluze/tether 0.6.8 → 0.7.0

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';

package/src/{account-pages.js → account-pages.ts}

@@ -1,16 +1,17 @@
 /**
  * Customer account pages, an optional part the account part loads on pages that use them: the order page with
- * returns, the profile form, addresses and subscriptions. The operations and their input checks are shared with the
- * Worker (server/src/shared/account-ops.js), so both modes do the same.
+ * returns, the profile form, addresses and subscriptions. Each operation is one of the Worker's fixed routes, which
+ * checks the input (account/operations.ts).
  */
-import { reportError } from './config.js';
-import { qsa, sel } from './dom.js';
-import { pagesContext } from './account/operations.js';
-import { renderOrder, showOrderState } from './account/order-page.js';
-import { renderAddresses } from './account/addresses-view.js';
-import { renderSubscriptions } from './account/subscriptions-view.js';
-import { listenToPages } from './account/page-events.js';
-import { showIn } from './account/markup.js';
+import { reportError } from './config.ts';
+import { qsa, sel } from './dom.ts';
+import { pagesContext } from './account/operations.ts';
+import { renderOrder, showOrderState } from './account/order-page.ts';
+import { renderAddresses } from './account/addresses-view.ts';
+import { renderSubscriptions } from './account/subscriptions-view.ts';
+import { listenToPages } from './account/page-events.ts';
+import { showIn } from './account/markup.ts';
+import type { AccountCustomer } from './account/answers.ts';
 
 export {
   setup,
@@ -22,26 +23,24 @@ export {
   subscriptions,
   subscriptionAction,
   requestReturn,
-} from './account/operations.js';
+} from './account/operations.ts';
 
 /** The profile fields a `tether-profile-form` is filled with. */
-const PROFILE_FIELDS = /** @type {const} */ (['firstName', 'lastName']);
+const PROFILE_FIELDS = ['firstName', 'lastName'] as const;
 
-/**
- * Fills the profile form with the customer's name, leaving a field the visitor has typed in alone.
- *
- * @param {HTMLElement} form
- */
-async function renderProfile(form) {
-  const customer = await pagesContext()
-    .customer()
-    .catch((/** @type {unknown} */ error) => {
-      // The form stays empty and still saves: only the prefill is missing.
-      reportError(error, 'account');
-      return null;
-    });
-  if (!customer || form.tagName !== 'FORM') return;
-  const fields = /** @type {HTMLFormElement} */ (form).elements;
+/** Fills the profile form with the customer's name, leaving a field the visitor has typed in alone. */
+async function renderProfile(form: HTMLElement): Promise<void> {
+  if (!(form instanceof window.HTMLFormElement)) return;
+  let customer: AccountCustomer | null;
+  try {
+    customer = await pagesContext().customer();
+  } catch (error) {
+    // The form stays empty and still saves: only the prefill is missing.
+    reportError(error, 'account');
+    return;
+  }
+  if (!customer) return;
+  const fields = form.elements;
   PROFILE_FIELDS.forEach((name) => {
     const input = fields.namedItem(name);
     const isTextField = input instanceof window.HTMLInputElement || input instanceof window.HTMLTextAreaElement;
@@ -51,13 +50,8 @@ async function renderProfile(form) {
 
 let listening = false;
 
-/**
- * Renders the order page, profile form, addresses and subscriptions in `root`: only what it has.
- *
- * @param {ParentNode} [root]
- * @returns {Promise<void>}
- */
-export async function renderPages(root = document) {
+/** Renders the order page, profile form, addresses and subscriptions in `root`: only what it has. */
+export async function renderPages(root: ParentNode = document): Promise<void> {
   if (!listening) {
     listening = true;
     listenToPages();
@@ -73,10 +67,8 @@ export async function renderPages(root = document) {
 /**
  * The error state of every account page in `root`, for when nobody can say whether a customer is logged in (the
  * Worker or Shopify can't be reached).
- *
- * @param {ParentNode} root
  */
-export function showUnavailable(root) {
+export function showUnavailable(root: ParentNode): void {
   qsa(root, sel('order')).forEach((el) => {
     showOrderState(el, 'error');
   });

package/src/account.ts

@@ -0,0 +1,284 @@
+/**
+ * Customer accounts (Shopify Customer Account API), as an optional part: loaded only when `account` is configured
+ * and the page uses it, or a login is coming back, or the visitor may be logged in.
+ *
+ *   window.TETHER_CONFIG = { …, account: { server: '/_tether/account' } }
+ *
+ *   <button tether-account-login>Log in</button>
+ *   <button tether-account-logout tether-show="logged-in">Log out</button>
+ *   <span tether-account-bind="first-name"></span>             first-name, last-name, name, email, address
+ *   <div tether-orders>                                       the customer's orders (first child = template)
+ *     <a tether-order-bind="url"><span tether-order-bind="name"></span> · <span tether-order-bind="date"></span></a>
+ *   </div>
+ *   <p tether-show="logged-out">…</p>
+ *
+ * The site's Worker logs the customer in and holds the tokens (`account/server-client.ts` is this browser's side of
+ * it), so no token is ever in the browser. The order page, profile, addresses, subscriptions and returns are the
+ * `account-pages` part, loaded only on pages that use them.
+ */
+import { cfg, log, reportError } from './config.ts';
+import { TetherError } from './client.ts';
+import { sel, get, qsa, setText, show, emit } from './dom.ts';
+import { Cart } from './cart.ts';
+import { loadPart } from './lazy.ts';
+import type { Parts } from './lazy.ts';
+import {
+  forgetServerLogin,
+  isServerLoggedIn,
+  serverCheckoutUrl,
+  serverFetch,
+  serverLogin,
+  serverLoginRedirect,
+  serverLogout,
+} from './account/server-client.ts';
+import { DEFAULT_ORDER_COUNT, MAX_ORDER_COUNT, isOrderCount, renderOrderList } from './account/order-list.ts';
+import { ownValue } from './account/markup.ts';
+import { toAccountOrders } from './account/answers.ts';
+import type { AccountCustomer } from './account/answers.ts';
+import { isLoginOutcome } from './account-marks.ts';
+import type { AccountOrder } from '../server/src/shared/account-orders.ts';
+import type { AddressFields, ReturnLine } from './account/operations.ts';
+import type {
+  AccountAddress,
+  CustomerAddress,
+  OpenedReturn,
+  OrderDetail,
+  Profile,
+  SubscriptionChange,
+  SubscriptionContract,
+} from './account/page-answers.ts';
+import type { SubscriptionAction } from '../server/src/shared/account-routes.ts';
+
+/**
+ * `unknown` when the Worker or Shopify can't say: the page shows its logged-out content, and the account pages their
+ * error state.
+ */
+type LoginState = { kind: 'logged-in' } | { kind: 'logged-out' } | { kind: 'unknown'; error: unknown };
+
+/** The attributes of the account pages, which are their own part. */
+const PAGE_ATTRIBUTES = ['order', 'addresses', 'subscriptions', 'profile-form', 'address-form'];
+
+/** @returns True when the Worker last said a customer is logged in; false before it has been asked. */
+export const isLoggedIn = isServerLoggedIn;
+
+/**
+ * Through the Worker to Shopify's login page; the visitor comes back to `returnTo`.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without `account.server`.
+ */
+export function login({
+  returnTo = window.location.href,
+  locale,
+}: { returnTo?: string; locale?: string } = {}): Promise<void> {
+  // In a promise, so a missing `account.server` rejects as it does for every other account function.
+  return new Promise((resolve) => {
+    serverLoginRedirect({ returnTo, locale });
+    resolve();
+  });
+}
+
+/**
+ * @returns The logged-in customer, `null` when nobody is.
+ * @throws {TetherError} When the Worker can't be reached or fails.
+ */
+export async function customer(): Promise<AccountCustomer | null> {
+  const me = await serverLogin();
+  return me.loggedIn ? me.customer : null;
+}
+
+/**
+ * @param options `first`: a whole number from 1 to `MAX_ORDER_COUNT`.
+ * @returns The customer's most recent orders, newest first; none when nobody is logged in.
+ * @throws {TetherError} `INVALID` for another `first`, which is refused before any request; else when the Worker or
+ *   Shopify can't answer.
+ */
+export async function orders({ first = DEFAULT_ORDER_COUNT }: { first?: number } = {}): Promise<AccountOrder[]> {
+  if (!isOrderCount(first)) {
+    throw new TetherError(`Customer accounts: orders() takes first from 1 to ${String(MAX_ORDER_COUNT)}`, {
+      code: 'INVALID',
+    });
+  }
+  const answer = await serverFetch(`/orders?${new URLSearchParams({ first: String(first) }).toString()}`);
+  return answer.kind === 'logged-out' ? [] : toAccountOrders(answer.data['orders']);
+}
+
+/**
+ * Logs out here and at Shopify, and unlinks the cart. Sends `tether:account-logout`.
+ *
+ * @param options `returnTo`: where Shopify sends the visitor afterwards.
+ */
+export async function logout({
+  returnTo = cfg.account?.logoutUrl || `${window.location.origin}/`,
+}: { returnTo?: string } = {}): Promise<void> {
+  if ((await serverLogout(returnTo)) === 'stayed') await render(document);
+}
+
+async function loginState(): Promise<LoginState> {
+  try {
+    return (await serverLogin()).loggedIn ? { kind: 'logged-in' } : { kind: 'logged-out' };
+  } catch (error) {
+    return { kind: 'unknown', error };
+  }
+}
+
+const usesPages = (root: ParentNode): boolean => PAGE_ATTRIBUTES.some((name) => qsa(root, sel(name)).length > 0);
+
+/**
+ * `tether-account-link`: Shopify's own pages, for what has to stay there: `subscriptions` and `payment`
+ * (`account.subscriptionsUrl` / `paymentUrl`), or the account itself.
+ */
+function linkShopifyPages(root: ParentNode): void {
+  qsa(root, sel('account-link')).forEach((link) => {
+    link.setAttribute('href', shopifyPageUrl(get(link, 'account-link')));
+  });
+}
+
+/**
+ * @param page The `tether-account-link` value.
+ * @returns The configured page for it, else the shop's account.
+ */
+function shopifyPageUrl(page: string | null): string {
+  const account = cfg.account;
+  const fallback = `https://${cfg.domain}/account`;
+  if (page === 'payment') return account?.paymentUrl || account?.subscriptionsUrl || fallback;
+  if (page === 'subscriptions') return account?.subscriptionsUrl || fallback;
+  return fallback;
+}
+
+/**
+ * Fills the account markup in `root`: what shows when logged in or out, the customer, their orders, and the account
+ * pages.
+ */
+export async function render(root: ParentNode = document): Promise<void> {
+  const state = await loginState();
+  if (state.kind === 'unknown') reportError(state.error, 'account');
+  const loggedIn = state.kind === 'logged-in';
+  qsa(root, sel('show')).forEach((el) => {
+    const condition = get(el, 'show');
+    if (condition === 'logged-in') show(el, loggedIn);
+    if (condition === 'logged-out') show(el, !loggedIn);
+  });
+  linkShopifyPages(root);
+  if (state.kind === 'unknown' && usesPages(root)) {
+    (await pages()).showUnavailable(root);
+    return;
+  }
+  if (!loggedIn) return;
+  await bindCustomer(root);
+  await Promise.all([
+    renderOrderList(root, (first) => orders({ first })),
+    usesPages(root) ? pages().then((part) => part.renderPages(root)) : null,
+  ]);
+}
+
+/**
+ * `tether-account-bind`: the customer's name, email, default address. A failure is reported and leaves the binds as
+ * they are.
+ */
+async function bindCustomer(root: ParentNode): Promise<void> {
+  const binds = qsa(root, sel('account-bind'));
+  if (!binds.length) return;
+  let profile: AccountCustomer | null;
+  try {
+    profile = await customer();
+  } catch (error) {
+    reportError(error, 'account');
+    return;
+  }
+  if (!profile) return;
+  const texts: Record<string, string | null | undefined> = {
+    'first-name': profile.firstName,
+    'last-name': profile.lastName,
+    name: profile.displayName,
+    email: profile.emailAddress?.emailAddress,
+    address: profile.defaultAddress?.formatted.join(', '),
+  };
+  binds.forEach((el) => {
+    const text = ownValue(texts, get(el, 'account-bind') ?? '');
+    if (text != null) setText(el, text);
+  });
+}
+
+let pagesPart: Promise<Parts['account-pages']> | null = null;
+
+/** @returns The account pages part, sharing this part's session. */
+function pages(): Promise<Parts['account-pages']> {
+  pagesPart ??= loadPart('account-pages').then((part) => {
+    part.setup({ serverFetch, customer, bindCustomer, reset: forgetServerLogin });
+    return part;
+  });
+  return pagesPart;
+}
+
+/** One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns). */
+export const order = (id: string | number): Promise<OrderDetail | null> => pages().then((part) => part.order(id));
+export const updateProfile = (fields?: { firstName?: string; lastName?: string }): Promise<Profile> =>
+  pages().then((part) => part.updateProfile(fields));
+export const addresses = (): Promise<CustomerAddress[]> => pages().then((part) => part.addresses());
+/** Creates an address, or updates the one with `id`. */
+export const saveAddress = (
+  address: AddressFields | null,
+  options?: { id?: string; isDefault?: boolean },
+): Promise<AccountAddress> => pages().then((part) => part.saveAddress(address, options));
+export const deleteAddress = (id: string): Promise<string> => pages().then((part) => part.deleteAddress(id));
+export const subscriptions = (): Promise<SubscriptionContract[]> => pages().then((part) => part.subscriptions());
+export const subscriptionAction = (id: string | number, action: SubscriptionAction): Promise<SubscriptionChange> =>
+  pages().then((part) => part.subscriptionAction(id, action));
+export const requestReturn = (orderId: string | number, lines: ReturnLine[]): Promise<OpenedReturn> =>
+  pages().then((part) => part.requestReturn(orderId, lines));
+
+function onClick(event: MouseEvent): void {
+  const target = event.target;
+  if (!(target instanceof window.Element)) return;
+  if (target.closest(sel('account-login'))) {
+    event.preventDefault();
+    login().catch((error: unknown) => {
+      reportError(error, 'login');
+    });
+  } else if (target.closest(sel('account-logout'))) {
+    event.preventDefault();
+    logout().catch((error: unknown) => {
+      reportError(error, 'logout');
+    });
+  }
+}
+
+/**
+ * Back from the Worker's login (`?account=`): drops the mark and sends `tether:account-login`, or
+ * `tether:account-error` with the outcome as its `error` when the login didn't finish.
+ */
+function finishServerLogin(): void {
+  const url = new URL(window.location.href);
+  const outcome = url.searchParams.get('account');
+  if (!isLoginOutcome(outcome)) return;
+  url.searchParams.delete('account');
+  window.history.replaceState(window.history.state, '', url);
+  switch (outcome) {
+    case 'in':
+      emit('account-login', {});
+      break;
+    case 'expired':
+    case 'error':
+      emit('account-error', { error: outcome });
+      break;
+  }
+}
+
+let started = false;
+
+/**
+ * Called by the core on mount: on the first one, finishes a login that's coming back and lets the Worker link the
+ * cart at checkout; then fills the page.
+ */
+export async function mountAccount(root: ParentNode = document): Promise<void> {
+  if (started) {
+    await render(root);
+    return;
+  }
+  started = true;
+  document.addEventListener('click', onClick);
+  finishServerLogin();
+  Cart.setCheckoutResolver(serverCheckoutUrl);
+  await render(root);
+  log('account', isLoggedIn() ? 'logged in' : 'logged out');
+}

package/src/amounts.ts

@@ -0,0 +1,64 @@
+/**
+ * Arithmetic on Shopify's money amounts, which are decimal strings (`'27.50'`). Comparisons go digit by digit, as
+ * integers of the smallest unit present, so two amounts that differ only past float precision aren't misjudged. Sums
+ * and differences are taken in the currency's own smallest unit, so JPY stays whole and KWD keeps its three digits.
+ */
+import type { Money } from './shopify-values.ts';
+
+const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?$/;
+
+/**
+ * @param fractionDigits Digits after the point to scale to.
+ * @returns The amount in units of 10^-fractionDigits, `null` when it isn't a decimal number.
+ */
+function toScaledInteger(amount: string, fractionDigits: number): bigint | null {
+  const match = DECIMAL.exec(amount.trim());
+  if (!match) return null;
+  const [, sign = '', whole = '0', fraction = ''] = match;
+  const digits = BigInt(`${whole}${fraction.padEnd(fractionDigits, '0')}`);
+  return sign === '-' ? -digits : digits;
+}
+
+const fractionLength = (amount: string) => amount.split('.')[1]?.length ?? 0;
+
+/** @returns True when both are decimal numbers and `amount` is the larger one. */
+export function isGreaterAmount(amount: string | null | undefined, other: string | null | undefined): boolean {
+  if (amount == null || other == null) return false;
+  const fractionDigits = Math.max(fractionLength(amount.trim()), fractionLength(other.trim()));
+  const scaled = toScaledInteger(amount, fractionDigits);
+  const scaledOther = toScaledInteger(other, fractionDigits);
+  if (scaled === null || scaledOther === null) return false;
+  return scaled > scaledOther;
+}
+
+/** For a currency code Intl doesn't know: most currencies have two digits, and `formatMoney` then shows two too. */
+const DEFAULT_FRACTION_DIGITS = 2;
+
+/** Currency code → its fraction digits, which never change on a page. */
+const fractionDigitsByCurrency = new Map<string, number>();
+
+/** @returns The digits after the point the currency has: 0 for JPY, 2 for EUR, 3 for KWD. */
+function currencyFractionDigits(currencyCode: string): number {
+  const known = fractionDigitsByCurrency.get(currencyCode);
+  if (known !== undefined) return known;
+  let digits = DEFAULT_FRACTION_DIGITS;
+  try {
+    const format = new Intl.NumberFormat('en', { style: 'currency', currency: currencyCode });
+    digits = format.resolvedOptions().maximumFractionDigits ?? DEFAULT_FRACTION_DIGITS;
+  } catch {
+    // A code Intl doesn't know (RangeError): see DEFAULT_FRACTION_DIGITS.
+  }
+  fractionDigitsByCurrency.set(currencyCode, digits);
+  return digits;
+}
+
+/** @returns The amount in the currency's smallest unit (cents, yen, fils), rounded to a whole one. */
+export function toMinorUnits(money: Money): number {
+  return Math.round(parseFloat(money.amount) * 10 ** currencyFractionDigits(money.currencyCode));
+}
+
+/** @returns The amount written with the currency's own number of digits. */
+export function fromMinorUnits(minorUnits: number, currencyCode: string): Money {
+  const digits = currencyFractionDigits(currencyCode);
+  return { amount: (minorUnits / 10 ** digits).toFixed(digits), currencyCode };
+}