@occluze/tether 0.6.7 → 0.7.0

package/src/account/order-list.ts

@@ -0,0 +1,107 @@
+/**
+ * The customer's recent orders (`tether-orders`), with `tether-show="orders-loading"` while they load and
+ * `orders-empty` when there are none yet.
+ */
+import { cfg, reportError } from '../config.ts';
+import { isHttpsUrl } from '../shopify-values.ts';
+import { formatDate, formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.ts';
+import { ownValue, showIn } from './markup.ts';
+import { fillLines } from './order-lines.ts';
+import type { AccountOrder } from '../../server/src/shared/account-orders.ts';
+
+/** How many orders `orders()` answers, and a `tether-orders` list shows, without being told. */
+export const DEFAULT_ORDER_COUNT = 10;
+/** The most orders one request asks for: the Worker answers no more. */
+export const MAX_ORDER_COUNT = 50;
+
+/** @returns True for a number of orders one request can ask for: a whole number from 1 to `MAX_ORDER_COUNT`. */
+export const isOrderCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_ORDER_COUNT;
+
+/**
+ * @param limit The list's `tether-limit`.
+ * @returns How many orders the list shows: the limit, kept within what one request can ask for.
+ */
+function listLimit(limit: string | null): number {
+  const asked = Number.parseInt(limit || String(DEFAULT_ORDER_COUNT), 10) || DEFAULT_ORDER_COUNT;
+  return Math.min(Math.max(asked, 1), MAX_ORDER_COUNT);
+}
+
+/**
+ * @param gid `gid://shopify/Order/123`, possibly with a query.
+ * @returns The numeric id at its end.
+ */
+const numericId = (gid: string): string => gid.replace(/\?.*$/, '').replace(/^.*\//, '');
+
+/**
+ * The order's page: the site's own (`account.orderUrl`, e.g. `/account/order?id={id}`, every `{id}` the numeric
+ * order id), else Shopify's status page when it is https.
+ */
+function orderUrl(order: AccountOrder): string | null {
+  const template = cfg.account?.orderUrl;
+  if (template) return template.replaceAll('{id}', encodeURIComponent(numericId(order.id)));
+  const statusPage = order.statusPageUrl;
+  return statusPage !== null && isHttpsUrl(statusPage) ? statusPage : null;
+}
+
+/** @returns The text of each `tether-order-bind` value. */
+const orderTexts = (order: AccountOrder): Record<string, string | undefined> => ({
+  name: order.name ?? '',
+  date: formatDate(order.processedAt),
+  total: formatMoney(order.totalPrice),
+  status: order.financialStatus?.toLowerCase(),
+  fulfillment: order.fulfillmentStatus?.toLowerCase(),
+  items: order.lineItems.nodes.map((line) => `${String(line.quantity)}× ${line.title ?? ''}`).join(', '),
+});
+
+/** @param node A copy of the list's template. */
+function fillOrder(node: HTMLElement, order: AccountOrder): void {
+  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.
+ */
+export async function renderOrderList(
+  root: ParentNode,
+  loadOrders: (first: number) => Promise<AccountOrder[]>,
+): Promise<void> {
+  const lists = qsa(root, sel('orders'));
+  const first = lists[0];
+  if (!first) return;
+  showIn(root, 'show', { 'orders-loading': true, 'orders-empty': false });
+  const limit = listLimit(get(first, 'limit'));
+  /** `null` after a failure. */
+  let orders: AccountOrder[] | null;
+  try {
+    orders = await loadOrders(limit);
+  } catch (error) {
+    reportError(error, 'orders');
+    orders = null;
+  }
+  showIn(root, 'show', { 'orders-loading': false, 'orders-empty': orders?.length === 0 });
+  lists.forEach((list) => {
+    repeat(list, orders ?? [], fillOrder);
+  });
+}

package/src/account/order-page.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.ts';
+import { isHttpsUrl } from '../shopify-values.ts';
+import { attr, formatDate, formatMoney, get, qsa, repeat, sel, setText, show } from '../dom.ts';
+import { addressText, bindsIn, enumText, ownValue, showIn } from './markup.ts';
+import { fillLines } from './order-lines.ts';
+import { order } from './operations.ts';
+import type { Fulfillment, OrderDetail } from './page-answers.ts';
+
+type OrderState = 'loading' | 'ready' | 'not-found' | 'error';
+
+/** @returns The order `tether-order` names: an id, or `url:<param>` for one in the page's URL. */
+function orderKey(el: HTMLElement): string | null {
+  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. */
+export function showOrderState(el: HTMLElement, state: Exclude<OrderState, 'ready'>): void {
+  el.setAttribute(attr('order-state'), state);
+  showIn(el, 'order-show', {
+    loading: state === 'loading',
+    ready: false,
+    'not-found': state === 'not-found',
+    error: state === 'error',
+  });
+}
+
+/** @returns The text of each `tether-order-bind` value. */
+const orderTexts = (detail: OrderDetail): Record<string, string> => ({
+  name: detail.name ?? '',
+  date: formatDate(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) => `${String(line.quantity)}× ${line.title || line.name || ''}`).join(', '),
+  cancelled: formatDate(detail.cancelledAt),
+});
+
+/** One shipment row: its status and dates, and its tracking link, hidden without an https one. */
+function fillFulfillment(row: HTMLElement, fulfillment: Fulfillment): void {
+  const tracking = fulfillment.trackingInformation[0];
+  const texts: Record<string, string> = {
+    status: enumText(fulfillment.latestShipmentStatus || fulfillment.status),
+    date: formatDate(fulfillment.createdAt),
+    eta: formatDate(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 ?? null;
+      const linked = url !== null && isHttpsUrl(url);
+      if (linked) el.setAttribute('href', url);
+      show(el, linked);
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(el, text);
+  });
+}
+
+function fillOrder(el: HTMLElement, detail: OrderDetail): void {
+  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') {
+      const statusPage = detail.statusPageUrl;
+      if (statusPage !== null && isHttpsUrl(statusPage)) bind.setAttribute('href', statusPage);
+      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. */
+export async function renderOrder(el: HTMLElement): Promise<void> {
+  const key = orderKey(el);
+  if (!key) {
+    el.setAttribute(attr('order-state'), 'not-found');
+    showIn(el, 'order-show', { 'not-found': true });
+    return;
+  }
+  showOrderState(el, 'loading');
+  let detail: OrderDetail | null;
+  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/page-answers.ts

@@ -0,0 +1,317 @@
+/**
+ * The account pages' answers as typed values: addresses, the order page, subscriptions and what a change returns. The
+ * rules are answers.ts's: every selected field is kept, a missing one reads as `null`, and the ids the pages act on
+ * are required.
+ */
+import {
+  countOrZero,
+  field,
+  isRecord,
+  listOf,
+  nodesOf,
+  numberOrNull,
+  textList,
+  textOrNull,
+} from '../../server/src/shared/json.ts';
+import { imageOrNull, moneyOrNull, toOrderLine } from '../../server/src/shared/account-orders.ts';
+import type { AccountImage, AccountOrderLine } from '../../server/src/shared/account-orders.ts';
+import type { Money } from '../shopify-values.ts';
+import { requiredId, unexpected } from './answers.ts';
+
+/** An address as the documents select it. */
+export interface MailingAddress {
+  id: string | null;
+  firstName: string | null;
+  lastName: string | null;
+  company: string | null;
+  address1: string | null;
+  address2: string | null;
+  city: string | null;
+  province: string | null;
+  zoneCode: string | null;
+  zip: string | null;
+  country: string | null;
+  countryCode: string | null;
+  phoneNumber: string | null;
+  /** One line per entry. */
+  formatted: string[];
+}
+/** One of the customer's saved addresses. */
+export type AccountAddress = MailingAddress & { id: string };
+export type CustomerAddress = AccountAddress & { isDefault: boolean };
+interface ReturnReason {
+  id: string;
+  name: string | null;
+  handle: string | null;
+}
+/** A line of the order page's document. */
+export type OrderDetailLine = AccountOrderLine & {
+  id: string;
+  name: string | null;
+  sku: string | null;
+  price: Money | null;
+  totalPrice: Money | null;
+  suggestedReturnReasonDefinitions: { nodes: ReturnReason[] };
+};
+interface Tracking {
+  company: string | null;
+  number: string | null;
+  url: string | null;
+}
+export interface Fulfillment {
+  id: string | null;
+  status: string | null;
+  createdAt: string | null;
+  estimatedDeliveryAt: string | null;
+  latestShipmentStatus: string | null;
+  trackingInformation: Tracking[];
+}
+interface ReturnableLine {
+  quantity: number;
+  lineItem: { id: string } | null;
+}
+/** A return Shopify opened. */
+export interface OpenedReturn {
+  id: string;
+  status: string | null;
+}
+/** The order page's document. */
+export interface OrderDetail {
+  id: string;
+  name: string | null;
+  number: number | null;
+  processedAt: string | null;
+  cancelledAt: string | null;
+  financialStatus: string | null;
+  fulfillmentStatus: string | null;
+  statusPageUrl: string | null;
+  requiresShipping: boolean | null;
+  totalPrice: Money | null;
+  subtotal: Money | null;
+  totalShipping: Money | null;
+  totalTax: Money | null;
+  shippingAddress: MailingAddress | null;
+  billingAddress: MailingAddress | null;
+  lineItems: { nodes: OrderDetailLine[] };
+  fulfillments: { nodes: Fulfillment[] };
+  returnInformation: { returnableLineItems: { nodes: ReturnableLine[] } } | null;
+  returns: { nodes: OpenedReturn[] };
+}
+export interface SubscriptionLine {
+  id: string | null;
+  name: string | null;
+  title: string | null;
+  variantTitle: string | null;
+  quantity: number;
+  sku: string | null;
+  currentPrice: Money | null;
+  lineDiscountedPrice: Money | null;
+  image: AccountImage | null;
+}
+interface BillingCycle {
+  cycleIndex: number | null;
+  skipped: boolean;
+  billingAttemptExpectedDate: string | null;
+}
+/** The subscriptions document. */
+export interface SubscriptionContract {
+  id: string;
+  /** `ACTIVE`, `PAUSED`, `CANCELLED`, `EXPIRED` or `FAILED`. */
+  status: string | null;
+  nextBillingDate: string | null;
+  currencyCode: string | null;
+  deliveryPrice: Money | null;
+  deliveryPolicy: { interval: string | null; intervalCount: { count: number } | null } | null;
+  lines: { nodes: SubscriptionLine[] };
+  upcomingBillingCycles: { nodes: BillingCycle[] };
+}
+export interface Profile {
+  firstName: string | null;
+  lastName: string | null;
+}
+/** What a subscription action changed: the contract (pause, resume, cancel) or its next billing cycle (skip, unskip). */
+export type SubscriptionChange =
+  | { contract: { id: string | null; status: string | null } }
+  | { billingCycle: { cycleIndex: number | null; skipped: boolean } };
+
+function toMailingAddress(value: unknown): MailingAddress {
+  const text = (name: string) => textOrNull(field(value, name));
+  return {
+    id: text('id'),
+    firstName: text('firstName'),
+    lastName: text('lastName'),
+    company: text('company'),
+    address1: text('address1'),
+    address2: text('address2'),
+    city: text('city'),
+    province: text('province'),
+    zoneCode: text('zoneCode'),
+    zip: text('zip'),
+    country: text('country'),
+    countryCode: text('countryCode'),
+    phoneNumber: text('phoneNumber'),
+    formatted: textList(field(value, 'formatted')),
+  };
+}
+
+const mailingAddressOrNull = (value: unknown): MailingAddress | null =>
+  isRecord(value) ? toMailingAddress(value) : null;
+
+/** @throws {TetherError} Without an id. */
+export const toAccountAddress = (value: unknown): AccountAddress => ({
+  ...toMailingAddress(value),
+  id: requiredId(field(value, 'id'), 'address id'),
+});
+
+/**
+ * @param value The addresses operation's list, each address with the `isDefault` it adds.
+ * @throws {TetherError} For an address without an id.
+ */
+export const toCustomerAddresses = (value: unknown): CustomerAddress[] =>
+  listOf(value, (address) => ({ ...toAccountAddress(address), isDefault: field(address, 'isDefault') === true }));
+
+const toOrderDetailLine = (value: unknown): OrderDetailLine => ({
+  ...toOrderLine(value),
+  id: requiredId(field(value, 'id'), 'line item id'),
+  name: textOrNull(field(value, 'name')),
+  sku: textOrNull(field(value, 'sku')),
+  price: moneyOrNull(field(value, 'price')),
+  totalPrice: moneyOrNull(field(value, 'totalPrice')),
+  suggestedReturnReasonDefinitions: nodesOf(field(value, 'suggestedReturnReasonDefinitions'), (reason) => ({
+    id: requiredId(field(reason, 'id'), 'return reason id'),
+    name: textOrNull(field(reason, 'name')),
+    handle: textOrNull(field(reason, 'handle')),
+  })),
+});
+
+const toFulfillment = (value: unknown): Fulfillment => ({
+  id: textOrNull(field(value, 'id')),
+  status: textOrNull(field(value, 'status')),
+  createdAt: textOrNull(field(value, 'createdAt')),
+  estimatedDeliveryAt: textOrNull(field(value, 'estimatedDeliveryAt')),
+  latestShipmentStatus: textOrNull(field(value, 'latestShipmentStatus')),
+  trackingInformation: listOf(field(value, 'trackingInformation'), (tracking) => ({
+    company: textOrNull(field(tracking, 'company')),
+    number: textOrNull(field(tracking, 'number')),
+    url: textOrNull(field(tracking, 'url')),
+  })),
+});
+
+function toReturnableLine(value: unknown): ReturnableLine {
+  const lineId = textOrNull(field(field(value, 'lineItem'), 'id'));
+  return { quantity: countOrZero(field(value, 'quantity')), lineItem: lineId === null ? null : { id: lineId } };
+}
+
+function toReturnInformation(value: unknown): OrderDetail['returnInformation'] {
+  if (!isRecord(value)) return null;
+  return { returnableLineItems: nodesOf(value['returnableLineItems'], toReturnableLine) };
+}
+
+/**
+ * @param value The order operation's `order`.
+ * @returns `null` when the customer has no such order.
+ * @throws {TetherError} For an order, line, reason or return without an id.
+ */
+export function toOrderDetail(value: unknown): OrderDetail | null {
+  if (!isRecord(value)) return null;
+  const text = (name: string) => textOrNull(value[name]);
+  const money = (name: string) => moneyOrNull(value[name]);
+  const requiresShipping = value['requiresShipping'];
+  return {
+    id: requiredId(value['id'], 'order id'),
+    name: text('name'),
+    number: numberOrNull(value['number']),
+    processedAt: text('processedAt'),
+    cancelledAt: text('cancelledAt'),
+    financialStatus: text('financialStatus'),
+    fulfillmentStatus: text('fulfillmentStatus'),
+    statusPageUrl: text('statusPageUrl'),
+    requiresShipping: typeof requiresShipping === 'boolean' ? requiresShipping : null,
+    totalPrice: money('totalPrice'),
+    subtotal: money('subtotal'),
+    totalShipping: money('totalShipping'),
+    totalTax: money('totalTax'),
+    shippingAddress: mailingAddressOrNull(value['shippingAddress']),
+    billingAddress: mailingAddressOrNull(value['billingAddress']),
+    lineItems: nodesOf(value['lineItems'], toOrderDetailLine),
+    fulfillments: nodesOf(value['fulfillments'], toFulfillment),
+    returnInformation: toReturnInformation(value['returnInformation']),
+    returns: nodesOf(value['returns'], toReturn),
+  };
+}
+
+const toSubscriptionLine = (value: unknown): SubscriptionLine => ({
+  id: textOrNull(field(value, 'id')),
+  name: textOrNull(field(value, 'name')),
+  title: textOrNull(field(value, 'title')),
+  variantTitle: textOrNull(field(value, 'variantTitle')),
+  quantity: countOrZero(field(value, 'quantity')),
+  sku: textOrNull(field(value, 'sku')),
+  currentPrice: moneyOrNull(field(value, 'currentPrice')),
+  lineDiscountedPrice: moneyOrNull(field(value, 'lineDiscountedPrice')),
+  image: imageOrNull(field(value, 'image')),
+});
+
+const toBillingCycle = (value: unknown): BillingCycle => ({
+  cycleIndex: numberOrNull(field(value, 'cycleIndex')),
+  skipped: field(value, 'skipped') === true,
+  billingAttemptExpectedDate: textOrNull(field(value, 'billingAttemptExpectedDate')),
+});
+
+function toDeliveryPolicy(value: unknown): SubscriptionContract['deliveryPolicy'] {
+  if (!isRecord(value)) return null;
+  const intervalCount = value['intervalCount'];
+  return {
+    interval: textOrNull(value['interval']),
+    intervalCount: isRecord(intervalCount) ? { count: countOrZero(intervalCount['count']) } : null,
+  };
+}
+
+/** @throws {TetherError} Without an id. */
+const toSubscriptionContract = (value: unknown): SubscriptionContract => ({
+  id: requiredId(field(value, 'id'), 'subscription id'),
+  status: textOrNull(field(value, 'status')),
+  nextBillingDate: textOrNull(field(value, 'nextBillingDate')),
+  currencyCode: textOrNull(field(value, 'currencyCode')),
+  deliveryPrice: moneyOrNull(field(value, 'deliveryPrice')),
+  deliveryPolicy: toDeliveryPolicy(field(value, 'deliveryPolicy')),
+  lines: nodesOf(field(value, 'lines'), toSubscriptionLine),
+  upcomingBillingCycles: nodesOf(field(value, 'upcomingBillingCycles'), toBillingCycle),
+});
+
+/**
+ * @param value The subscriptions operation's list.
+ * @throws {TetherError} For a contract without an id.
+ */
+export const toSubscriptionContracts = (value: unknown): SubscriptionContract[] =>
+  listOf(value, toSubscriptionContract);
+
+/**
+ * @param result The subscription operation's result.
+ * @throws {TetherError} With neither a contract nor a billing cycle.
+ */
+export function toSubscriptionChange(result: Record<string, unknown>): SubscriptionChange {
+  const { contract, billingCycle } = result;
+  if (isRecord(contract)) {
+    return { contract: { id: textOrNull(contract['id']), status: textOrNull(contract['status']) } };
+  }
+  if (isRecord(billingCycle)) {
+    const { cycleIndex, skipped } = toBillingCycle(billingCycle);
+    return { billingCycle: { cycleIndex, skipped } };
+  }
+  throw unexpected('changed subscription');
+}
+
+/** @throws {TetherError} Without an id. */
+export function toReturn(value: unknown): OpenedReturn {
+  return { id: requiredId(field(value, 'id'), 'return id'), status: textOrNull(field(value, 'status')) };
+}
+
+/** @throws {TetherError} Without an id. */
+export const toDeletedId = (value: unknown): string => requiredId(value, 'deleted address id');
+
+/** @param value The profile operation's `customer`. */
+export const toProfile = (value: unknown): Profile => ({
+  firstName: textOrNull(field(value, 'firstName')),
+  lastName: textOrNull(field(value, 'lastName')),
+});