@occluze/tether 0.6.7 → 0.6.8

package/src/account/server-client.js

@@ -0,0 +1,172 @@
+/**
+ * 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

@@ -0,0 +1,111 @@
+/**
+ * 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

@@ -0,0 +1,150 @@
+/**
+ * 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()
+  );
+}

package/src/account/subscriptions-view.js

@@ -0,0 +1,158 @@
+/**
+ * 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.js';
+import { attr, formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.js';
+import { bindsIn, enumText, ownValue, showIn } from './markup.js';
+import { subscriptions } from './operations.js';
+import { localDate } from '../account-links.js';
+/** @import { Money } from '../shopify-values.js' */
+
+/**
+ * @typedef {object} SubscriptionLine
+ * @property {string} title
+ * @property {string | null} variantTitle
+ * @property {number} quantity
+ * @property {Money} currentPrice
+ * @property {Money | null} lineDiscountedPrice
+ * @property {{ url: string, altText: string | null } | null} image
+ */
+/**
+ * @typedef {object} SubscriptionContract The subscriptions document in account-ops.js.
+ * @property {string} id
+ * @property {'ACTIVE' | 'PAUSED' | 'CANCELLED' | 'EXPIRED' | 'FAILED'} status
+ * @property {string | null} nextBillingDate
+ * @property {string} currencyCode
+ * @property {Money | null} deliveryPrice
+ * @property {{ interval: string | null, intervalCount: { count: number } | null } | null} deliveryPolicy
+ * @property {{ nodes: SubscriptionLine[] }} lines
+ * @property {{ nodes: { cycleIndex: number, skipped: boolean }[] }} upcomingBillingCycles
+ */
+
+/**
+ * @param {SubscriptionContract} contract
+ * @returns {Record<string, boolean>} The row's `tether-subscription-show` conditions, `can-<action>` among them.
+ */
+function conditionsOf(contract) {
+  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',
+  };
+}
+
+/**
+ * @param {SubscriptionContract} contract
+ * @returns {string} `month`, `3 months`; `''` without a delivery policy.
+ */
+function intervalText(contract) {
+  const unit = enumText(contract.deliveryPolicy?.interval);
+  if (!unit) return '';
+  const count = contract.deliveryPolicy?.intervalCount?.count ?? 1;
+  return count <= 1 ? unit : `${count} ${unit}s`;
+}
+
+/**
+ * @param {SubscriptionContract} contract
+ * @returns {Record<string, string>} The text of each `tether-subscription-bind` value.
+ */
+function contractTexts(contract) {
+  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: contract.nextBillingDate ? localDate(contract.nextBillingDate) : '',
+    interval: intervalText(contract),
+    products: lines.map((line) => `${line.quantity}× ${line.title}`).join(', '),
+    total: lines.length ? formatMoney({ amount: String(total), currencyCode: contract.currencyCode }) : '',
+    delivery: formatMoney(contract.deliveryPrice),
+  };
+}
+
+/**
+ * @param {HTMLElement} row
+ * @param {SubscriptionLine} line
+ */
+function fillLine(row, line) {
+  /** @type {Record<string, string>} */
+  const texts = {
+    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);
+  });
+}
+
+/**
+ * @param {HTMLElement} row
+ * @param {SubscriptionContract} contract
+ */
+function fillContract(row, contract) {
+  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`.
+ *
+ * @param {ParentNode} root
+ */
+export async function renderSubscriptions(root) {
+  const boxes = qsa(root, sel('subscriptions'));
+  if (!boxes.length) return;
+  showIn(root, 'show', { 'subscriptions-loading': true, 'subscriptions-empty': false });
+  /** @type {SubscriptionContract[]} */
+  let list;
+  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);
+  });
+}