@occluze/tether 0.6.8 → 0.7.1

package/src/account/operations.js

@@ -1,180 +0,0 @@
-/**
- * The account pages' operations, the same fixed ones in both modes: the Worker's routes in server mode, the Customer
- * Account API directly in browser mode, with the documents and input checks of account-ops.js either way. Each
- * result has the shape of its document there, which the typedefs of the views that render it state.
- */
-import { TetherError } from '../client.js';
-import { emit } from '../dom.js';
-import { ops, InputError } from '../../server/src/shared/account-ops.js';
-/** @import { ServerAnswer, ServerRequest } from './server-client.js' */
-/** @import { AccountCustomer } from './browser-session.js' */
-/** @import { OrderDetail } from './order-page.js' */
-/** @import { CustomerAddress } from './addresses-view.js' */
-/** @import { SubscriptionContract } from './subscriptions-view.js' */
-/** @import { SubscriptionAction } from '../../server/src/shared/account-ops.js' */
-
-/**
- * @typedef {object} PagesContext The account part's session, shared so both parts act as one customer.
- * @property {() => string} serverBase `''` in browser mode.
- * @property {(path: string, request?: ServerRequest) => Promise<ServerAnswer>} serverFetch
- * @property {(document: string, variables?: Record<string, unknown>) => Promise<unknown>} query
- * @property {() => Promise<AccountCustomer | null>} customer
- * @property {(root: ParentNode) => Promise<void>} bindCustomer
- * @property {() => void} reset Forgets the cached customer after a change of their data.
- */
-/** @typedef {Record<string, unknown>} AddressFields `CustomerAddressInput` fields; account-ops.js keeps only those. */
-/**
- * @typedef {object} ReturnLine
- * @property {string} lineItemId
- * @property {number} quantity
- * @property {string} [reasonId]
- * @property {string} [note]
- */
-/** @typedef {'order' | 'addresses' | 'subscriptions' | 'profile' | 'saveAddress' | 'deleteAddress' | 'subscription' | 'requestReturn'} OperationName */
-/** @typedef {'profile' | 'addresses' | 'subscriptions' | 'orders'} ChangedData `tether:account-updated`'s `what`. */
-
-/** @type {PagesContext | null} */
-let context = null;
-
-/**
- * Called by the account part once, when it loads this part.
- *
- * @param {PagesContext} shared
- */
-export function setup(shared) {
-  context = shared;
-}
-
-/**
- * @returns {PagesContext}
- * @throws {Error} Before `setup`: this part is only ever loaded by the account part, which calls it first.
- */
-export function pagesContext() {
-  if (!context) throw new Error('account-pages: loaded without the account part');
-  return context;
-}
-
-/** @type {Record<OperationName, (input: Record<string, unknown>) => ['GET' | 'POST', string]>} */
-const ROUTE = {
-  order: (input) => ['GET', `/order?id=${encodeURIComponent(String(input['id']))}`],
-  addresses: () => ['GET', '/addresses'],
-  subscriptions: () => ['GET', '/subscriptions'],
-  profile: () => ['POST', '/profile'],
-  saveAddress: () => ['POST', '/address'],
-  deleteAddress: () => ['POST', '/address/delete'],
-  subscription: () => ['POST', '/subscription'],
-  requestReturn: () => ['POST', '/return'],
-};
-
-/**
- * @param {OperationName} name
- * @param {Record<string, unknown>} [input]
- * @returns {Promise<Record<string, unknown>>} The operation's result fields.
- * @throws {TetherError} `NOT_LOGGED_IN` (status 401), `INVALID` for input account-ops.js refuses (with Shopify's
- *   `userErrors`), or the request's failure.
- */
-async function run(name, input = {}) {
-  const { serverBase, serverFetch, query } = pagesContext();
-  if (serverBase()) {
-    const [method, path] = ROUTE[name](input);
-    const answer = await serverFetch(path, method === 'POST' ? { method, body: input } : {});
-    if (answer.kind === 'logged-out') throw new TetherError('Not logged in', { code: 'NOT_LOGGED_IN', status: 401 });
-    return answer.data;
-  }
-  const operation = ops[name];
-  if (!operation) throw new TetherError(`Customer accounts: no operation ${name}`);
-  try {
-    // account-ops.js's `Ask` reads every answer field by field, so the answer's shape needn't be stated here.
-    return await operation(
-      async (document, variables) => /** @type {Record<string, unknown> | null} */ (await query(document, variables)),
-      input,
-    );
-  } catch (error) {
-    if (!(error instanceof InputError)) throw error;
-    throw new TetherError(error.message, { code: 'INVALID', userErrors: error.userErrors });
-  }
-}
-
-/** @param {ChangedData} what */
-function changed(what) {
-  pagesContext().reset();
-  emit('account-updated', { what });
-}
-
-/**
- * One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns).
- *
- * @param {string | number} id A gid or the numeric order id.
- * @returns {Promise<OrderDetail | null>} `null` when the customer has no such order.
- */
-export async function order(id) {
-  const result = await run('order', { id });
-  return /** @type {OrderDetail | null} */ (result['order'] ?? null);
-}
-
-/**
- * @param {{ firstName?: string, lastName?: string }} [fields]
- * @returns {Promise<{ firstName: string | null, lastName: string | null }>}
- */
-export async function updateProfile({ firstName, lastName } = {}) {
-  const result = await run('profile', { firstName, lastName });
-  changed('profile');
-  return /** @type {{ firstName: string | null, lastName: string | null }} */ (result['customer']);
-}
-
-/** @returns {Promise<CustomerAddress[]>} The customer's addresses, the default one marked `isDefault`. */
-export async function addresses() {
-  const result = await run('addresses');
-  return /** @type {CustomerAddress[]} */ (result['addresses']);
-}
-
-/**
- * Creates an address, or updates the one with `id`; without fields, only makes it the default.
- *
- * @param {AddressFields | null} address
- * @param {{ id?: string | undefined, isDefault?: boolean }} [options]
- * @returns {Promise<CustomerAddress>}
- */
-export async function saveAddress(address, { id, isDefault } = {}) {
-  const result = await run('saveAddress', { id, address, isDefault });
-  changed('addresses');
-  return /** @type {CustomerAddress} */ (result['address']);
-}
-
-/**
- * @param {string} id
- * @returns {Promise<string>} The deleted address's id.
- */
-export async function deleteAddress(id) {
-  const result = await run('deleteAddress', { id });
-  changed('addresses');
-  return /** @type {string} */ (result['deleted']);
-}
-
-/** @returns {Promise<SubscriptionContract[]>} */
-export async function subscriptions() {
-  const result = await run('subscriptions');
-  return /** @type {SubscriptionContract[]} */ (result['subscriptions']);
-}
-
-/**
- * @param {string | number} id
- * @param {SubscriptionAction} action
- * @returns {Promise<Record<string, unknown>>} The changed contract or billing cycle.
- */
-export async function subscriptionAction(id, action) {
-  const result = await run('subscription', { id, action });
-  changed('subscriptions');
-  return result;
-}
-
-/**
- * @param {string | number} orderId
- * @param {ReturnLine[]} lines
- * @returns {Promise<{ id: string, status: string }>} The return Shopify opened.
- */
-export async function requestReturn(orderId, lines) {
-  const result = await run('requestReturn', { orderId, lines });
-  changed('orders');
-  return /** @type {{ id: string, status: string }} */ (result['return']);
-}

package/src/account/order-lines.js

@@ -1,96 +0,0 @@
-/**
- * The products of an order (`tether-order-lines`), for the order list and the order page alike. The order page's
- * lines also carry price, total, sku and what can be returned; the order list's document has none of those, so they
- * render empty there, and its rows get no return controls.
- */
-import { formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.js';
-import { bindsIn, ownValue, showIn } from './markup.js';
-/** @import { Money } from '../shopify-values.js' */
-
-/**
- * @typedef {object} OrderLine A line of `ORDERS_QUERY` or of the order page's document (account-ops.js).
- * @property {string} [id] Only on the order page.
- * @property {string} [name]
- * @property {string} title
- * @property {string | null} [variantTitle]
- * @property {number} quantity
- * @property {string | null} [sku]
- * @property {{ url: string, altText: string | null } | null} [image]
- * @property {Money | null} [price]
- * @property {Money | null} [totalPrice]
- * @property {{ nodes: { id: string, name: string }[] }} [suggestedReturnReasonDefinitions]
- */
-/** @typedef {ReadonlyMap<string, number>} Returnable Line id → how many of it can still be returned. */
-
-/**
- * @param {OrderLine} line
- * @param {number | null} returnable `null` in the order list, which knows nothing of returns.
- * @returns {Record<string, string | undefined>} The text of each `tether-order-line` value.
- */
-const lineTexts = (line, returnable) => ({
-  title: line.title || line.name,
-  'variant-title': line.variantTitle || '',
-  quantity: String(line.quantity),
-  price: formatMoney(line.price),
-  total: formatMoney(line.totalPrice),
-  sku: line.sku || '',
-  returnable: returnable === null ? undefined : String(returnable),
-});
-
-/**
- * @param {HTMLElement} el
- * @returns {el is HTMLInputElement}
- */
-const isInput = (el) => el.tagName === 'INPUT';
-
-/**
- * The return controls of one line: how many can be returned, and Shopify's suggested reasons.
- *
- * @param {HTMLElement} row
- * @param {OrderLine & { id: string }} line
- * @param {number} returnable
- */
-function fillReturnControls(row, line, returnable) {
-  showIn(row, 'order-line-show', { returnable: returnable > 0 });
-  qsa(row, sel('return-quantity')).forEach((input) => {
-    if (!isInput(input)) return;
-    input.max = String(returnable);
-    input.min = '0';
-    if (!input.value) input.value = '0';
-    input.disabled = returnable < 1;
-  });
-  qsa(row, `select${sel('return-reason')}`).forEach((select) => {
-    // A select keeps its options across renders of the same line: they are added once.
-    if (select.dataset['tetherFilled'] === line.id) return;
-    select.dataset['tetherFilled'] = line.id;
-    (line.suggestedReturnReasonDefinitions?.nodes ?? []).forEach((reason) => {
-      select.appendChild(new Option(reason.name, reason.id));
-    });
-  });
-}
-
-/**
- * Renders `lines` into a `tether-order-lines` repeater.
- *
- * @param {HTMLElement} box
- * @param {readonly OrderLine[]} lines
- * @param {Returnable | null} returns `null` for the order list.
- */
-export function fillLines(box, lines, returns) {
-  repeat(box, lines, (row, line) => {
-    const id = line.id;
-    const returnable = returns && id ? (returns.get(id) ?? 0) : null;
-    if (id) row.dataset['tetherLine'] = id;
-    const texts = lineTexts(line, returnable);
-    bindsIn(row, 'order-line').forEach((el) => {
-      const key = get(el, 'order-line') ?? '';
-      if (key === 'image') {
-        if (line.image) setImage(el, line.image.url, line.image.altText || line.title);
-        return;
-      }
-      const text = ownValue(texts, key);
-      if (text !== undefined) setText(el, text);
-    });
-    if (id && returnable !== null) fillReturnControls(row, { ...line, id }, returnable);
-  });
-}

package/src/account/order-list.js

@@ -1,91 +0,0 @@
-/**
- * The customer's recent orders (`tether-orders`), with `tether-show="orders-loading"` while they load and
- * `orders-empty` when there are none yet.
- */
-import { reportError } from '../config.js';
-import { orderUrl, localDate } from '../account-links.js';
-import { formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.js';
-import { ownValue, showIn } from './markup.js';
-import { fillLines } from './order-lines.js';
-/** @import { Money } from '../shopify-values.js' */
-/** @import { OrderLine } from './order-lines.js' */
-
-/**
- * @typedef {object} AccountOrder A node of `ORDERS_QUERY` (account-ops.js).
- * @property {string} id
- * @property {string} name
- * @property {string} processedAt
- * @property {string | null} financialStatus
- * @property {string | null} fulfillmentStatus
- * @property {string | null} statusPageUrl
- * @property {Money} totalPrice
- * @property {{ nodes: OrderLine[] }} lineItems
- */
-
-/** How many orders a `tether-orders` list shows without `tether-limit`. */
-const DEFAULT_ORDER_COUNT = 10;
-
-/**
- * @param {AccountOrder} order
- * @returns {Record<string, string | undefined>} The text of each `tether-order-bind` value.
- */
-const orderTexts = (order) => ({
-  name: order.name,
-  date: localDate(order.processedAt),
-  total: formatMoney(order.totalPrice),
-  status: order.financialStatus?.toLowerCase(),
-  fulfillment: order.fulfillmentStatus?.toLowerCase(),
-  items: order.lineItems.nodes.map((line) => `${line.quantity}× ${line.title}`).join(', '),
-});
-
-/**
- * @param {HTMLElement} node A copy of the list's template.
- * @param {AccountOrder} order
- */
-function fillOrder(node, order) {
-  const lines = order.lineItems.nodes;
-  const url = orderUrl(order);
-  const texts = orderTexts(order);
-  qsa(node, sel('order-bind')).forEach((el) => {
-    const key = get(el, 'order-bind') ?? '';
-    if (key === 'url') {
-      if (url) el.setAttribute('href', url);
-      return;
-    }
-    if (key === 'image') {
-      const image = lines.find((line) => line.image)?.image;
-      if (image) setImage(el, image.url, image.altText || lines[0]?.title || '');
-      return;
-    }
-    const text = ownValue(texts, key);
-    if (text !== undefined) setText(el, text);
-  });
-  qsa(node, sel('order-lines')).forEach((box) => {
-    fillLines(box, lines, null);
-  });
-  if (get(node, 'order-bind') === 'url' && url) node.setAttribute('href', url);
-}
-
-/**
- * Fills every `tether-orders` list in `root`. A failure is reported and leaves the lists empty, without claiming the
- * customer has no orders.
- *
- * @param {ParentNode} root
- * @param {(first: number) => Promise<AccountOrder[]>} loadOrders
- */
-export async function renderOrderList(root, loadOrders) {
-  const lists = qsa(root, sel('orders'));
-  const first = lists[0];
-  if (!first) return;
-  showIn(root, 'show', { 'orders-loading': true, 'orders-empty': false });
-  const limit = Number.parseInt(get(first, 'limit') || String(DEFAULT_ORDER_COUNT), 10) || DEFAULT_ORDER_COUNT;
-  /** @type {AccountOrder[] | null} `null` after a failure. */
-  const orders = await loadOrders(limit).catch((/** @type {unknown} */ error) => {
-    reportError(error, 'orders');
-    return null;
-  });
-  showIn(root, 'show', { 'orders-loading': false, 'orders-empty': orders?.length === 0 });
-  lists.forEach((list) => {
-    repeat(list, orders ?? [], fillOrder);
-  });
-}

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);
-}