@occluze/tether 0.6.8 → 0.7.0

package/src/account/order-page.js

@@ -1,192 +0,0 @@
-/**
- * The order page (`tether-order`): one order in full, with its lines, totals, addresses, shipments and what can be
- * returned. `tether-order-state` and `tether-order-show` follow the load: `loading`, then `ready`, `not-found` or
- * `error`.
- */
-import { reportError } from '../config.js';
-import { isHttpsUrl, localDate } from '../account-links.js';
-import { attr, formatMoney, get, qsa, repeat, sel, setText, show } from '../dom.js';
-import { addressText, bindsIn, enumText, ownValue, showIn } from './markup.js';
-import { fillLines } from './order-lines.js';
-import { order } from './operations.js';
-/** @import { Money } from '../shopify-values.js' */
-/** @import { OrderLine } from './order-lines.js' */
-
-/**
- * @typedef {object} Fulfillment
- * @property {string} status
- * @property {string} createdAt
- * @property {string | null} estimatedDeliveryAt
- * @property {string | null} latestShipmentStatus
- * @property {{ company: string | null, number: string | null, url: string | null }[]} trackingInformation
- */
-/**
- * @typedef {object} OrderDetail The order page's document in account-ops.js.
- * @property {string} id
- * @property {string} name
- * @property {string} processedAt
- * @property {string | null} cancelledAt
- * @property {string | null} financialStatus
- * @property {string | null} fulfillmentStatus
- * @property {string | null} statusPageUrl
- * @property {Money} totalPrice
- * @property {Money | null} subtotal
- * @property {Money | null} totalShipping
- * @property {Money | null} totalTax
- * @property {{ formatted: string[] } | null} shippingAddress
- * @property {{ formatted: string[] } | null} billingAddress
- * @property {{ nodes: (OrderLine & { id: string })[] }} lineItems
- * @property {{ nodes: Fulfillment[] }} fulfillments
- * @property {{ returnableLineItems: { nodes: { quantity: number, lineItem: { id: string } | null }[] } } | null}
- *   returnInformation
- * @property {{ nodes: { id: string, status: string }[] }} returns
- */
-/** @typedef {'loading' | 'ready' | 'not-found' | 'error'} OrderState */
-
-/**
- * @param {HTMLElement} el
- * @returns {string | null} The order `tether-order` names: an id, or `url:<param>` for one in the page's URL.
- */
-function orderKey(el) {
-  const raw = get(el, 'order') || '';
-  if (!raw.startsWith('url:')) return raw;
-  return new URL(window.location.href).searchParams.get(raw.slice('url:'.length) || 'id');
-}
-
-/**
- * Every state but `ready`, which shows with the order.
- *
- * @param {HTMLElement} el
- * @param {Exclude<OrderState, 'ready'>} state
- */
-export function showOrderState(el, state) {
-  el.setAttribute(attr('order-state'), state);
-  showIn(el, 'order-show', {
-    loading: state === 'loading',
-    ready: false,
-    'not-found': state === 'not-found',
-    error: state === 'error',
-  });
-}
-
-/**
- * @param {OrderDetail} detail
- * @returns {Record<string, string>} The text of each `tether-order-bind` value.
- */
-const orderTexts = (detail) => ({
-  name: detail.name,
-  date: localDate(detail.processedAt),
-  total: formatMoney(detail.totalPrice),
-  subtotal: formatMoney(detail.subtotal),
-  shipping: formatMoney(detail.totalShipping),
-  tax: formatMoney(detail.totalTax),
-  status: enumText(detail.financialStatus),
-  fulfillment: enumText(detail.fulfillmentStatus),
-  'shipping-address': addressText(detail.shippingAddress),
-  'billing-address': addressText(detail.billingAddress),
-  items: detail.lineItems.nodes.map((line) => `${line.quantity}× ${line.title || line.name}`).join(', '),
-  cancelled: detail.cancelledAt ? localDate(detail.cancelledAt) : '',
-});
-
-/**
- * One shipment row: its status and dates, and its tracking link, hidden without an https one.
- *
- * @param {HTMLElement} row
- * @param {Fulfillment} fulfillment
- */
-function fillFulfillment(row, fulfillment) {
-  const tracking = fulfillment.trackingInformation[0];
-  /** @type {Record<string, string>} */
-  const texts = {
-    status: enumText(fulfillment.latestShipmentStatus || fulfillment.status),
-    date: localDate(fulfillment.createdAt),
-    eta: fulfillment.estimatedDeliveryAt ? localDate(fulfillment.estimatedDeliveryAt) : '',
-    company: tracking?.company || '',
-    number: tracking?.number || '',
-  };
-  bindsIn(row, 'fulfillment-bind').forEach((el) => {
-    const key = get(el, 'fulfillment-bind') ?? '';
-    if (key === 'url') {
-      const url = tracking?.url;
-      const linked = isHttpsUrl(url);
-      if (linked && url) el.setAttribute('href', url);
-      show(el, linked);
-      return;
-    }
-    const text = ownValue(texts, key);
-    if (text !== undefined) setText(el, text);
-  });
-}
-
-/**
- * @param {HTMLElement} el
- * @param {OrderDetail} detail
- */
-function fillOrder(el, detail) {
-  const returnable = new Map(
-    (detail.returnInformation?.returnableLineItems.nodes ?? []).map((entry) => [
-      entry.lineItem?.id ?? '',
-      entry.quantity,
-    ]),
-  );
-  const shipments = detail.fulfillments.nodes;
-  const texts = orderTexts(detail);
-  qsa(el, sel('order-bind')).forEach((bind) => {
-    const key = get(bind, 'order-bind') ?? '';
-    if (key === 'url') {
-      if (detail.statusPageUrl && isHttpsUrl(detail.statusPageUrl)) bind.setAttribute('href', detail.statusPageUrl);
-      return;
-    }
-    const text = ownValue(texts, key);
-    if (text !== undefined) setText(bind, text);
-  });
-  qsa(el, sel('order-lines')).forEach((box) => {
-    fillLines(box, detail.lineItems.nodes, returnable);
-  });
-  qsa(el, sel('order-fulfillments')).forEach((box) => {
-    repeat(box, shipments, fillFulfillment);
-  });
-  const returnRequested = el.dataset['tetherReturned'] === '1';
-  showIn(el, 'order-show', {
-    loading: false,
-    ready: true,
-    error: false,
-    'not-found': false,
-    cancelled: Boolean(detail.cancelledAt),
-    shipped: shipments.length > 0,
-    returnable: [...returnable.values()].some((quantity) => quantity > 0),
-    'has-returns': !returnRequested && detail.returns.nodes.length > 0,
-    'return-requested': returnRequested,
-  });
-  el.setAttribute(attr('order-state'), 'ready');
-}
-
-/**
- * Loads and renders the order `el` names. A failure is reported and shows the error state.
- *
- * @param {HTMLElement} el
- */
-export async function renderOrder(el) {
-  const key = orderKey(el);
-  if (!key) {
-    el.setAttribute(attr('order-state'), 'not-found');
-    showIn(el, 'order-show', { 'not-found': true });
-    return;
-  }
-  showOrderState(el, 'loading');
-  /** @type {OrderDetail | null} */
-  let detail;
-  try {
-    detail = await order(key);
-  } catch (error) {
-    reportError(error, 'order');
-    showOrderState(el, 'error');
-    return;
-  }
-  if (!detail) {
-    showOrderState(el, 'not-found');
-    return;
-  }
-  el.dataset['tetherOrderId'] = detail.id;
-  fillOrder(el, detail);
-}

package/src/account/server-client.js

@@ -1,172 +0,0 @@
-/**
- * Server mode (`account.server`): the site's Worker holds the Shopify tokens, and this browser only a session cookie
- * its scripts can't read. This module is the browser's side of the Worker's account routes.
- */
-import { cfg } from '../config.js';
-import { TetherError } from '../client.js';
-import { Cart } from '../cart.js';
-import { emit } from '../dom.js';
-import {
-  isRecord,
-  loginCountry,
-  loginLanguage,
-  navigate,
-  readJsonObjectOrEmpty,
-  setLoginHint,
-  textOrNull,
-} from './shared.js';
-/** @import { UserError } from '../client.js' */
-
-/**
- * @typedef {{ kind: 'answer', data: Record<string, unknown> } | { kind: 'logged-out' }} ServerAnswer The Worker's
- *   answer, or a 401: the session cookie is missing, has expired, or Shopify ended the login.
- */
-/**
- * @typedef {object} ServerCustomer The profile the Worker's `/me` sends.
- * @property {string | null} firstName
- * @property {string | null} lastName
- * @property {string | null} displayName
- * @property {string | null} email
- * @property {string[] | null} address The default address, one line per entry.
- */
-/** @typedef {{ loggedIn: true, customer: ServerCustomer } | { loggedIn: false }} ServerLogin */
-/** @typedef {{ method?: 'GET' | 'POST', body?: Record<string, unknown> }} ServerRequest */
-
-/** @type {ServerLogin | null} The Worker's `/me` answer, until a change of the customer's data. */
-let known = null;
-
-/**
- * @returns {string} The Worker's account routes, without a trailing slash; `''` in browser mode. `account.server` is a
- *   full URL or a path on this site.
- */
-export function serverBase() {
-  const server = cfg.account?.server;
-  if (!server) return '';
-  return new URL(server, window.location.href).href.replace(/\/$/, '');
-}
-
-/**
- * One request to the Worker, with the session cookie. A POST carries the header the Worker requires against
- * cross-site forms.
- *
- * @param {string} path
- * @param {ServerRequest} [request]
- * @returns {Promise<ServerAnswer>}
- * @throws {TetherError} `HTTP_<status>` for any failure but a 401, with the Worker's `userErrors`.
- */
-export async function serverFetch(path, { method = 'GET', body } = {}) {
-  /** @type {RequestInit} */
-  const init = { 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 fetch(`${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);
-    /** @type {TetherError['userErrors']} */
-    const userErrors = Array.isArray(data['userErrors'])
-      ? // The Worker sends Shopify's own `userErrors` list unchanged.
-        /** @type {UserError[]} */ (data['userErrors'])
-      : undefined;
-    throw new TetherError(`Customer accounts: ${reason}`, {
-      status: response.status,
-      ...(userErrors && { userErrors }),
-    });
-  }
-  return { kind: 'answer', data };
-}
-
-/**
- * @param {unknown} value
- * @returns {ServerCustomer}
- */
-function toServerCustomer(value) {
-  const customer = isRecord(value) ? value : {};
-  const address = customer['address'];
-  return {
-    firstName: textOrNull(customer['firstName']),
-    lastName: textOrNull(customer['lastName']),
-    displayName: textOrNull(customer['displayName']),
-    email: textOrNull(customer['email']),
-    address: Array.isArray(address) ? address.filter((line) => typeof line === 'string') : null,
-  };
-}
-
-/**
- * Who is logged in, asked once and then kept; the "may be logged in" hint follows the answer.
- *
- * @returns {Promise<ServerLogin>}
- * @throws {TetherError} When the Worker can't be reached or fails: that says nothing about the login.
- */
-export async function serverLogin() {
-  if (!known) {
-    const answer = await serverFetch('/me');
-    known =
-      answer.kind === 'answer' && answer.data['loggedIn'] === true
-        ? { loggedIn: true, customer: toServerCustomer(answer.data['customer']) }
-        : { loggedIn: false };
-  }
-  setLoginHint(known.loggedIn);
-  return known;
-}
-
-/** @returns {boolean} True when the Worker last said a customer is logged in. */
-export const isServerLoggedIn = () => known?.loggedIn === true;
-
-/** Asks the Worker again on the next `serverLogin()`, after a change of the customer's data. */
-export function forgetServerLogin() {
-  known = null;
-}
-
-/**
- * To the Worker's login, which comes back to `returnTo`. The cart is linked later, at checkout, through the Worker's
- * protected `POST /cart`.
- *
- * @param {{ returnTo: string, locale?: string | undefined }} options
- */
-export function serverLoginRedirect({ returnTo, locale }) {
-  const url = new URL(`${serverBase()}/login`);
-  url.searchParams.set('returnTo', returnTo);
-  const language = loginLanguage(locale);
-  if (language) url.searchParams.set('locale', language);
-  const country = loginCountry();
-  if (country) url.searchParams.set('country', country);
-  navigate(url.toString());
-}
-
-/**
- * The logged-in customer's checkout, for `Cart.beforeCheckout`: the Worker links the cart to the customer and answers
- * with its checkout URL.
- *
- * @returns {Promise<string | null>} `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() {
-  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;
-  const url = textOrNull(answer.data['checkoutUrl']);
-  if (!url) return null;
-  return `${url}${url.includes('?') ? '&' : '?'}logged_in=true`;
-}
-
-/**
- * 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`.
- *
- * @param {string} returnTo
- * @returns {Promise<'redirected' | 'stayed'>}
- */
-export async function serverLogout(returnTo) {
-  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/shared.js

@@ -1,111 +0,0 @@
-/**
- * What both account modes share: the storage keys, the redirect to Shopify's pages, the login language, and reading
- * the JSON that Shopify and the Worker answer with. Storage throws in private mode and where the visitor blocks site
- * data; a login then lasts as long as the page.
- */
-import { cfg } from '../config.js';
-
-/** @typedef {'session' | 'local'} StorageArea */
-
-/** @returns {string} The browser-mode session's key. */
-export const sessionKey = () => `${cfg.prefix}:account:${cfg.domain}`;
-
-/** @returns {string} The key of the login in progress (browser mode), between leaving for Shopify and coming back. */
-export const pendingLoginKey = () => `${cfg.prefix}:account-login:${cfg.domain}`;
-
-/**
- * Server mode's "may be logged in" mark: it makes the core load this part on the next page, and holds no secret.
- *
- * @returns {string}
- */
-const hintKey = () => `${cfg.prefix}:account-hint:${cfg.domain}`;
-
-/** @returns {StorageArea} Where the browser-mode session lives: `localStorage` with `account.remember`. */
-export const sessionArea = () => (cfg.account?.remember ? 'local' : 'session');
-
-/** @param {StorageArea} area */
-const storageOf = (area) => (area === 'local' ? window.localStorage : window.sessionStorage);
-
-/**
- * @param {StorageArea} area
- * @param {string} key
- * @returns {unknown} The stored JSON value; `null` without one, for text that isn't JSON, or with storage blocked.
- */
-export function readJsonIfAllowed(area, key) {
-  try {
-    return JSON.parse(storageOf(area).getItem(key) ?? 'null');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Keeps `value` as JSON; without storage nothing is kept (see the file's comment).
- *
- * @param {StorageArea} area
- * @param {string} key
- * @param {unknown} value `null` removes the key.
- */
-export function writeJsonIfAllowed(area, key, value) {
-  try {
-    if (value === null) storageOf(area).removeItem(key);
-    else storageOf(area).setItem(key, JSON.stringify(value));
-  } catch {
-    // Private mode or blocked storage: see the file's comment.
-  }
-}
-
-/** @param {boolean} loggedIn */
-export function setLoginHint(loggedIn) {
-  writeJsonIfAllowed('local', hintKey(), loggedIn ? 1 : null);
-}
-
-/**
- * @param {unknown} value
- * @returns {value is Record<string, unknown>}
- */
-export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-
-/**
- * @param {unknown} value
- * @returns {string | null}
- */
-export const textOrNull = (value) => (typeof value === 'string' ? value : null);
-
-/**
- * An error page that isn't JSON reads as an empty answer: the response's status then says what went wrong.
- *
- * @param {Response} response
- * @returns {Promise<Record<string, unknown>>}
- */
-export async function readJsonObjectOrEmpty(response) {
-  /** @type {unknown} */
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    return {};
-  }
-  return isRecord(json) ? json : {};
-}
-
-/**
- * Goes to one of Shopify's (or the Worker's) pages, through `account.navigate` when the site replaces the redirect.
- *
- * @param {string} url
- */
-export function navigate(url) {
-  const replacement = cfg.account?.navigate;
-  if (replacement) replacement(url);
-  else window.location.assign(url);
-}
-
-/**
- * @param {string | undefined} locale The caller's choice.
- * @returns {string} The language of Shopify's login page: the caller's, `account.locale`, else the site's; `''` for
- *   Shopify's default.
- */
-export const loginLanguage = (locale) => locale || cfg.account?.locale || (cfg.locale || '').split('-')[0] || '';
-
-/** @returns {string} The market's country for Shopify's login page, `''` without one. */
-export const loginCountry = () => (cfg.country ? cfg.country.toUpperCase() : '');

package/src/account/shopify-auth.js

@@ -1,150 +0,0 @@
-/**
- * Shopify's side of the browser-mode login: the OAuth and Customer Account API endpoints, found through the shop's
- * `.well-known` documents (a shop with its own accounts domain has other ones), the token endpoint, and the check of
- * the id token it answers with.
- */
-import { cfg } from '../config.js';
-import { TetherError } from '../client.js';
-import { fromBase64Url } from '../../server/src/shared/base64url.js';
-import { isRecord, readJsonObjectOrEmpty, textOrNull } from './shared.js';
-
-/**
- * @typedef {object} Endpoints
- * @property {string} issuer The id token's `iss`.
- * @property {string} authorizationEndpoint
- * @property {string} tokenEndpoint
- * @property {string} endSessionEndpoint
- * @property {string} graphql The Customer Account API.
- */
-/**
- * @typedef {object} TokenAnswer
- * @property {string} access
- * @property {string | null} refresh Left out of some refresh answers.
- * @property {string | null} idToken Left out of refresh answers.
- * @property {number} expiresInSeconds
- */
-
-/** Shopify's access tokens last an hour; an answer without `expires_in` is taken to say so. */
-const DEFAULT_TOKEN_SECONDS = 3600;
-
-/** @type {Endpoints | null} */
-let endpoints = null;
-
-/**
- * @param {string} document `openid-configuration` or `customer-account-api`.
- * @returns {Promise<Record<string, unknown>>}
- */
-async function wellKnown(document) {
-  const shop = cfg.account?.shopDomain || cfg.domain;
-  const response = await fetch(`https://${shop}/.well-known/${document}`);
-  if (!response.ok) {
-    throw new TetherError(`Customer accounts: ${document} answered ${response.status}`, { status: response.status });
-  }
-  const json = /** @type {unknown} */ (await response.json());
-  return isRecord(json) ? json : {};
-}
-
-/**
- * @param {Record<string, unknown>} json
- * @param {string} name
- * @returns {string}
- * @throws {TetherError} When Shopify's document lacks the endpoint.
- */
-function endpointIn(json, name) {
-  const url = textOrNull(json[name]);
-  if (!url) throw new TetherError(`Customer accounts: Shopify named no ${name}`);
-  return url;
-}
-
-/**
- * @returns {Promise<Endpoints>} The shop's endpoints, asked once per page.
- * @throws {TetherError} When Shopify's documents can't be read.
- */
-export async function discover() {
-  if (endpoints) return endpoints;
-  const [openid, api] = await Promise.all([wellKnown('openid-configuration'), wellKnown('customer-account-api')]);
-  endpoints = {
-    issuer: endpointIn(openid, 'issuer'),
-    authorizationEndpoint: endpointIn(openid, 'authorization_endpoint'),
-    tokenEndpoint: endpointIn(openid, 'token_endpoint'),
-    endSessionEndpoint: endpointIn(openid, 'end_session_endpoint'),
-    graphql: endpointIn(api, 'graphql_api'),
-  };
-  return endpoints;
-}
-
-/**
- * A token request, as a "simple" request (a form body, no custom header) so the browser sends it without a CORS
- * preflight. `account.tokenUrl` replaces Shopify's endpoint for a browser that can't reach it; it must be the shop's
- * own first-party endpoint passing the form on to Shopify, because the id token in the answer is trusted unsigned
- * (`idTokenClaims`).
- *
- * @param {Record<string, string>} params
- * @returns {Promise<TokenAnswer>}
- * @throws {TetherError} `SESSION_ENDED` when Shopify refuses the code or refresh token (400, 401), else `TOKEN_FAILED`.
- */
-export async function requestToken(params) {
-  const { tokenEndpoint } = await discover();
-  const response = await fetch(cfg.account?.tokenUrl || tokenEndpoint, {
-    method: 'POST',
-    body: new URLSearchParams(params),
-  });
-  const data = await readJsonObjectOrEmpty(response);
-  const access = textOrNull(data['access_token']);
-  if (!response.ok || !access) {
-    const ended = response.status === 400 || response.status === 401;
-    throw new TetherError(`Customer accounts: token ${response.status} ${textOrNull(data['error']) ?? ''}`.trim(), {
-      status: response.status,
-      code: ended ? 'SESSION_ENDED' : 'TOKEN_FAILED',
-    });
-  }
-  return {
-    access,
-    refresh: textOrNull(data['refresh_token']) || null,
-    idToken: textOrNull(data['id_token']) || null,
-    expiresInSeconds: Number(data['expires_in']) || DEFAULT_TOKEN_SECONDS,
-  };
-}
-
-/**
- * The id token's claims. Its signature isn't checked: the token comes straight from Shopify's token endpoint over
- * TLS, in answer to this browser's own code and verifier, so nobody else could have written it. That holds only while
- * `account.tokenUrl` (when set) is the shop's own first-party endpoint passing the request on to Shopify (see
- * `requestToken`).
- *
- * @param {string} idToken
- * @returns {Record<string, unknown> | null}
- */
-function idTokenClaims(idToken) {
-  const payload = idToken.split('.')[1];
-  if (!payload) return null;
-  /** @type {unknown} */
-  let claims;
-  try {
-    claims = JSON.parse(new TextDecoder().decode(fromBase64Url(payload)));
-  } catch {
-    // Not base64url JSON: not an id token, which the caller refuses.
-    return null;
-  }
-  return isRecord(claims) ? claims : null;
-}
-
-/**
- * @param {string | null} idToken
- * @param {{ nonce: string, issuer: string, client: string }} expected The login's nonce, Shopify's issuer, our client.
- * @returns {boolean} True when the id token answers this login: the expected claims, and not expired.
- */
-export function answersLogin(idToken, { nonce, issuer, client }) {
-  const claims = idToken ? idTokenClaims(idToken) : null;
-  if (!claims) return false;
-  const audience = claims['aud'];
-  const audiences = Array.isArray(audience) ? audience : [audience];
-  const expiresAt = claims['exp'];
-  return (
-    claims['nonce'] === nonce &&
-    claims['iss'] === issuer &&
-    audiences.includes(client) &&
-    typeof expiresAt === 'number' &&
-    expiresAt * 1000 >= Date.now()
-  );
-}