@occluze/tether 0.7.0 → 0.7.1

package/src/account/markup.ts

@@ -1,36 +0,0 @@
-/**
- * The account markup's shared vocabulary: `tether-*-show` conditions, binds on a template row (the row itself may
- * carry one), and how Shopify's enum values and formatted addresses read on the page.
- */
-import { get, qsa, sel, show } from '../dom.ts';
-
-/**
- * Shows or hides each `name` element whose value is one of `conditions`' keys; other values are left alone.
- *
- * @param name `show`, `order-show`, `address-show`…
- */
-export function showIn(root: ParentNode, name: string, conditions: Readonly<Record<string, boolean>>): void {
-  qsa(root, sel(name)).forEach((el) => {
-    const key = get(el, name) ?? '';
-    if (Object.hasOwn(conditions, key)) show(el, conditions[key] === true);
-  });
-}
-
-/**
- * @param row A copy of a repeater's template.
- * @returns The `name` elements in `row`, and `row` itself when it carries `name`.
- */
-export const bindsIn = (row: HTMLElement, name: string): HTMLElement[] =>
-  qsa(row, sel(name)).concat(row.matches(sel(name)) ? [row] : []);
-
-/** @returns A Shopify enum as text: `PARTIALLY_FULFILLED` → `partially fulfilled`. */
-export const enumText = (value: string | null | undefined): string =>
-  value ? value.toLowerCase().replace(/_/g, ' ') : '';
-
-/** @returns Shopify's formatted address on one line. */
-export const addressText = (address: { formatted?: string[] | null } | null | undefined): string =>
-  (address?.formatted ?? []).join(', ');
-
-/** A bind's value, looked up by the attribute's text: only the table's own keys, never `constructor` and the like. */
-export const ownValue = <T>(values: Readonly<Record<string, T>>, key: string): T | undefined =>
-  Object.hasOwn(values, key) ? values[key] : undefined;

package/src/account/operations.ts

@@ -1,145 +0,0 @@
-/**
- * The account pages' operations: the Worker's fixed routes (shared/account-routes.ts), which check the input and run
- * the documents with the customer's token. Each result is read into its typed shape (page-answers.ts), and a failure
- * is a `TetherError`: `NOT_LOGGED_IN`, `INVALID` for input the Worker or Shopify refuses, `NETWORK`, and
- * `HTTP_<status>` for a request that failed.
- */
-import { TetherError } from '../client.ts';
-import { emit } from '../dom.ts';
-import { operationRequest } from '../../server/src/shared/account-routes.ts';
-import type {
-  AddressFields,
-  OperationInputs,
-  OperationName,
-  ReturnLine,
-  SubscriptionAction,
-} from '../../server/src/shared/account-routes.ts';
-
-export type { AddressFields, ReturnLine };
-import {
-  toAccountAddress,
-  toCustomerAddresses,
-  toDeletedId,
-  toOrderDetail,
-  toProfile,
-  toReturn,
-  toSubscriptionChange,
-  toSubscriptionContracts,
-} from './page-answers.ts';
-import type {
-  AccountAddress,
-  CustomerAddress,
-  OpenedReturn,
-  OrderDetail,
-  Profile,
-  SubscriptionChange,
-  SubscriptionContract,
-} from './page-answers.ts';
-import type { ServerAnswer, ServerRequest } from './server-client.ts';
-import type { AccountCustomer } from './answers.ts';
-
-/** The account part's session, shared so both parts act as one customer. */
-interface PagesContext {
-  serverFetch: (path: string, request?: ServerRequest) => Promise<ServerAnswer>;
-  customer: () => Promise<AccountCustomer | null>;
-  bindCustomer: (root: ParentNode) => Promise<void>;
-  /** Forgets the cached customer after a change of their data. */
-  reset: () => void;
-}
-
-/** `tether:account-updated`'s `what`. */
-type ChangedData = 'profile' | 'addresses' | 'subscriptions' | 'orders';
-
-let context: PagesContext | null = null;
-
-/** Called by the account part once, when it loads this part. */
-export function setup(shared: PagesContext): void {
-  context = shared;
-}
-
-/** @throws {Error} Before `setup`: this part is only ever loaded by the account part, which calls it first. */
-export function pagesContext(): PagesContext {
-  if (!context) throw new Error('account-pages: loaded without the account part');
-  return context;
-}
-
-/**
- * @returns The operation's result fields, read by the caller.
- * @throws {TetherError} With one of the codes in the file's comment.
- */
-async function run<Name extends OperationName>(
-  name: Name,
-  input: OperationInputs[Name],
-): Promise<Record<string, unknown>> {
-  const { serverFetch } = pagesContext();
-  const { method, path } = operationRequest(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;
-}
-
-function changed(what: ChangedData): void {
-  pagesContext().reset();
-  emit('account-updated', { what });
-}
-
-/**
- * One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns).
- *
- * @param id A gid or the numeric order id.
- * @returns `null` when the customer has no such order.
- */
-export async function order(id: string | number): Promise<OrderDetail | null> {
-  const result = await run('order', { id });
-  return toOrderDetail(result['order']);
-}
-
-export async function updateProfile({
-  firstName,
-  lastName,
-}: { firstName?: string; lastName?: string } = {}): Promise<Profile> {
-  const result = await run('profile', { firstName, lastName });
-  changed('profile');
-  return toProfile(result['customer']);
-}
-
-/** @returns The customer's addresses, the default one marked `isDefault`. */
-export async function addresses(): Promise<CustomerAddress[]> {
-  const result = await run('addresses', {});
-  return toCustomerAddresses(result['addresses']);
-}
-
-/** Creates an address, or updates the one with `id`; without fields, only makes it the default. */
-export async function saveAddress(
-  address: AddressFields | null,
-  { id, isDefault }: { id?: string | undefined; isDefault?: boolean } = {},
-): Promise<AccountAddress> {
-  const result = await run('saveAddress', { id, address, isDefault });
-  changed('addresses');
-  return toAccountAddress(result['address']);
-}
-
-/** @returns The deleted address's id. */
-export async function deleteAddress(id: string): Promise<string> {
-  const result = await run('deleteAddress', { id });
-  changed('addresses');
-  return toDeletedId(result['deleted']);
-}
-
-export async function subscriptions(): Promise<SubscriptionContract[]> {
-  const result = await run('subscriptions', {});
-  return toSubscriptionContracts(result['subscriptions']);
-}
-
-/** @returns The changed contract or billing cycle. */
-export async function subscriptionAction(id: string | number, action: SubscriptionAction): Promise<SubscriptionChange> {
-  const result = await run('subscription', { id, action });
-  changed('subscriptions');
-  return toSubscriptionChange(result);
-}
-
-export async function requestReturn(orderId: string | number, lines: ReturnLine[]): Promise<OpenedReturn> {
-  const result = await run('requestReturn', { orderId, lines });
-  changed('orders');
-  return toReturn(result['return']);
-}

package/src/account/order-lines.ts

@@ -1,75 +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.ts';
-import { bindsIn, ownValue, showIn } from './markup.ts';
-import type { AccountOrderLine } from '../../server/src/shared/account-orders.ts';
-import type { OrderDetailLine } from './page-answers.ts';
-
-/** A line of the order list, or of the order page, which has the fields after `image` too. */
-type OrderLine = AccountOrderLine &
-  Partial<Pick<OrderDetailLine, 'id' | 'name' | 'sku' | 'price' | 'totalPrice' | 'suggestedReturnReasonDefinitions'>>;
-/** Line id → how many of it can still be returned. */
-type Returnable = ReadonlyMap<string, number>;
-
-/**
- * @param returnable `null` in the order list, which knows nothing of returns.
- * @returns The text of each `tether-order-line` value.
- */
-const lineTexts = (line: OrderLine, returnable: number | null): Record<string, string | undefined> => ({
-  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),
-});
-
-const isInput = (el: HTMLElement): el is HTMLInputElement => el.tagName === 'INPUT';
-
-/** The return controls of one line: how many can be returned, and Shopify's suggested reasons. */
-function fillReturnControls(row: HTMLElement, line: OrderLine & { id: string }, returnable: number): void {
-  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 returns `null` for the order list.
- */
-export function fillLines(box: HTMLElement, lines: readonly OrderLine[], returns: Returnable | null): void {
-  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.ts

@@ -1,107 +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 { 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

@@ -1,137 +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.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);
-}