@occluze/tether 0.6.8 → 0.7.1

package/src/account.js

@@ -1,342 +0,0 @@
-/**
- * Customer accounts (Shopify Customer Account API), as an optional part: loaded only when `account` is configured
- * and the page uses it, or a login is in progress, or the visitor may be logged in.
- *
- *   window.TETHER_CONFIG = { …, account: { server: '/_tether/account' } }  // or { clientId: '…' } for browser mode
- *
- *   <button tether-account-login>Log in</button>
- *   <button tether-account-logout tether-show="logged-in">Log out</button>
- *   <span tether-account-bind="first-name"></span>             first-name, last-name, name, email, address
- *   <div tether-orders>                                       the customer's orders (first child = template)
- *     <a tether-order-bind="url"><span tether-order-bind="name"></span> · <span tether-order-bind="date"></span></a>
- *   </div>
- *   <p tether-show="logged-out">…</p>
- *
- * Two modes, one interface: server mode (`account/server-client.js`), where the site's Worker holds the tokens, and
- * browser mode (`account/browser-session.js`), where this browser does the OAuth login itself. Shopify needs HTTPS
- * (no localhost: use a tunnel) and the site's origin, callback and logout URLs registered in the Headless channel's
- * Customer Account API settings. The order page, profile, addresses, subscriptions and returns are the
- * `account-pages` part, loaded only on pages that use them.
- */
-import { cfg, log, reportError } from './config.js';
-import { TetherError } from './client.js';
-import { sel, get, qsa, setText, show, emit } from './dom.js';
-import { Cart } from './cart.js';
-import { loadPart } from './lazy.js';
-import { ORDERS_QUERY } from '../server/src/shared/account-documents.js';
-import {
-  browserCustomer,
-  browserLoginRedirect,
-  browserLogout,
-  forgetBrowserCustomer,
-  getToken,
-  handleCallback,
-  hasBrowserLogin,
-  query as browserQuery,
-} from './account/browser-session.js';
-import {
-  forgetServerLogin,
-  isServerLoggedIn,
-  serverBase,
-  serverCheckoutUrl,
-  serverFetch,
-  serverLogin,
-  serverLoginRedirect,
-  serverLogout,
-} from './account/server-client.js';
-import { renderOrderList } from './account/order-list.js';
-import { ownValue } from './account/markup.js';
-/** @import { AccountCustomer } from './account/browser-session.js' */
-/** @import { AccountOrder } from './account/order-list.js' */
-/** @import { Parts } from './lazy.js' */
-/** @import { AddressFields, ReturnLine } from './account/operations.js' */
-/** @import { SubscriptionAction } from '../server/src/shared/account-ops.js' */
-
-export { getToken, handleCallback };
-
-/**
- * @typedef {{ kind: 'logged-in' } | { kind: 'logged-out' } | { kind: 'unknown', error: unknown }} LoginState
- *   `unknown` when the Worker or Shopify can't say: the page shows its logged-out content, and the account pages their
- *   error state.
- */
-
-/** The attributes of the account pages, which are their own part. */
-const PAGE_ATTRIBUTES = ['order', 'addresses', 'subscriptions', 'profile-form', 'address-form'];
-
-/** @returns {boolean} True while a customer is logged in, as far as this page knows without asking. */
-export function isLoggedIn() {
-  return serverBase() ? isServerLoggedIn() : hasBrowserLogin();
-}
-
-/**
- * To Shopify's login page; the visitor comes back to `account.callbackUrl` (default: this page).
- *
- * @param {{ returnTo?: string, locale?: string }} [options]
- * @returns {Promise<void>}
- * @throws {TetherError} `NOT_CONFIGURED` in browser mode without `account.clientId`.
- */
-export async function login({ returnTo = window.location.href, locale } = {}) {
-  if (serverBase()) serverLoginRedirect({ returnTo, locale });
-  else await browserLoginRedirect({ returnTo, locale });
-}
-
-/**
- * Any Customer Account API query, in browser mode.
- *
- * @template T The shape of the query's `data`.
- * @param {string} document
- * @param {Record<string, unknown>} [variables]
- * @returns {Promise<T>}
- * @throws {TetherError} `NOT_ALLOWED` in server mode, which answers only its fixed operations; `NOT_LOGGED_IN`.
- */
-export async function query(document, variables = {}) {
-  if (serverBase()) {
-    throw new TetherError('Customer accounts in server mode only answer customer() and orders()', {
-      code: 'NOT_ALLOWED',
-    });
-  }
-  return browserQuery(document, variables);
-}
-
-/** @returns {Promise<AccountCustomer | null>} The logged-in customer, `null` when nobody is. */
-export async function customer() {
-  if (!serverBase()) return browserCustomer();
-  const me = await serverLogin();
-  if (!me.loggedIn) return null;
-  return {
-    ...me.customer,
-    emailAddress: { emailAddress: me.customer.email },
-    defaultAddress: { formatted: me.customer.address },
-  };
-}
-
-/**
- * @param {{ first?: number }} [options]
- * @returns {Promise<AccountOrder[]>} The customer's most recent orders, newest first; none when nobody is logged in
- *   (server mode).
- */
-export async function orders({ first = 10 } = {}) {
-  if (serverBase()) {
-    const answer = await serverFetch(`/orders?first=${first}`);
-    if (answer.kind === 'logged-out') return [];
-    const list = answer.data['orders'];
-    // The Worker sends the nodes of the same `ORDERS_QUERY`.
-    return Array.isArray(list) ? /** @type {AccountOrder[]} */ (list) : [];
-  }
-  /** @type {{ customer: { orders: { nodes: AccountOrder[] } } | null }} */
-  const data = await browserQuery(ORDERS_QUERY, { first });
-  return data.customer?.orders.nodes ?? [];
-}
-
-/**
- * Logs out here and at Shopify, and unlinks the cart. Sends `tether:account-logout`.
- *
- * @param {{ returnTo?: string }} [options] Where Shopify sends the visitor afterwards.
- * @returns {Promise<void>}
- */
-export async function logout({ returnTo = cfg.account?.logoutUrl || `${window.location.origin}/` } = {}) {
-  const outcome = serverBase() ? await serverLogout(returnTo) : await browserLogout(returnTo);
-  if (outcome === 'stayed') await render(document);
-}
-
-/** @returns {Promise<LoginState>} */
-async function loginState() {
-  try {
-    if (serverBase()) return (await serverLogin()).loggedIn ? { kind: 'logged-in' } : { kind: 'logged-out' };
-    if (hasBrowserLogin() || (await getToken())) return { kind: 'logged-in' };
-    return { kind: 'logged-out' };
-  } catch (error) {
-    return { kind: 'unknown', error };
-  }
-}
-
-/** @param {ParentNode} root */
-const usesPages = (root) => PAGE_ATTRIBUTES.some((name) => qsa(root, sel(name)).length > 0);
-
-/**
- * `tether-account-link`: Shopify's own pages, for what has to stay there: `subscriptions` and `payment`
- * (`account.subscriptionsUrl` / `paymentUrl`), or the account itself.
- *
- * @param {ParentNode} root
- */
-function linkShopifyPages(root) {
-  const account = cfg.account;
-  qsa(root, sel('account-link')).forEach((link) => {
-    const page = get(link, 'account-link');
-    const subscriptions = account?.subscriptionsUrl;
-    const url =
-      (page === 'payment' && (account?.paymentUrl || subscriptions)) || (page === 'subscriptions' && subscriptions);
-    link.setAttribute('href', url || `https://${cfg.domain}/account`);
-  });
-}
-
-/**
- * Fills the account markup in `root`: what shows when logged in or out, the customer, their orders, and the account
- * pages.
- *
- * @param {ParentNode} [root]
- * @returns {Promise<void>}
- */
-export async function render(root = document) {
-  const state = await loginState();
-  if (state.kind === 'unknown') reportError(state.error, 'account');
-  const loggedIn = state.kind === 'logged-in';
-  qsa(root, sel('show')).forEach((el) => {
-    const condition = get(el, 'show');
-    if (condition === 'logged-in') show(el, loggedIn);
-    if (condition === 'logged-out') show(el, !loggedIn);
-  });
-  linkShopifyPages(root);
-  if (state.kind === 'unknown' && usesPages(root)) {
-    (await pages()).showUnavailable(root);
-    return;
-  }
-  if (!loggedIn) return;
-  await bindCustomer(root);
-  await Promise.all([
-    renderOrderList(root, (first) => orders({ first })),
-    usesPages(root) ? pages().then((part) => part.renderPages(root)) : null,
-  ]);
-}
-
-/**
- * `tether-account-bind`: the customer's name, email, default address. A failure is reported and leaves the binds as
- * they are.
- *
- * @param {ParentNode} root
- */
-async function bindCustomer(root) {
-  const binds = qsa(root, sel('account-bind'));
-  if (!binds.length) return;
-  const profile = await customer().catch((/** @type {unknown} */ error) => {
-    reportError(error, 'account');
-    return null;
-  });
-  /** @type {Record<string, string | null | undefined>} */
-  const texts = {
-    'first-name': profile?.firstName,
-    'last-name': profile?.lastName,
-    name: profile?.displayName,
-    email: profile?.emailAddress?.emailAddress,
-    address: profile?.defaultAddress?.formatted?.join(', '),
-  };
-  binds.forEach((el) => {
-    const text = ownValue(texts, get(el, 'account-bind') ?? '');
-    if (text != null) setText(el, text);
-  });
-}
-
-/** @type {Promise<Parts['account-pages']> | null} */
-let pagesPart = null;
-
-/** @returns {Promise<Parts['account-pages']>} The account pages part, sharing this part's session. */
-function pages() {
-  pagesPart ??= loadPart('account-pages').then((part) => {
-    part.setup({
-      serverBase,
-      serverFetch,
-      query,
-      customer,
-      bindCustomer,
-      reset: () => {
-        forgetBrowserCustomer();
-        forgetServerLogin();
-      },
-    });
-    return part;
-  });
-  return pagesPart;
-}
-
-/**
- * One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns).
- *
- * @param {string | number} id
- */
-export const order = (id) => pages().then((part) => part.order(id));
-/** @param {{ firstName?: string, lastName?: string }} [fields] */
-export const updateProfile = (fields) => pages().then((part) => part.updateProfile(fields));
-export const addresses = () => pages().then((part) => part.addresses());
-/**
- * Creates an address, or updates the one with `id`.
- *
- * @param {AddressFields | null} address
- * @param {{ id?: string, isDefault?: boolean }} [options]
- */
-export const saveAddress = (address, options) => pages().then((part) => part.saveAddress(address, options));
-/** @param {string} id */
-export const deleteAddress = (id) => pages().then((part) => part.deleteAddress(id));
-export const subscriptions = () => pages().then((part) => part.subscriptions());
-/**
- * @param {string | number} id
- * @param {SubscriptionAction} action
- */
-export const subscriptionAction = (id, action) => pages().then((part) => part.subscriptionAction(id, action));
-/**
- * @param {string | number} orderId
- * @param {ReturnLine[]} lines
- */
-export const requestReturn = (orderId, lines) => pages().then((part) => part.requestReturn(orderId, lines));
-
-/** @param {MouseEvent} event */
-function onClick(event) {
-  const target = event.target;
-  if (!(target instanceof window.Element)) return;
-  if (target.closest(sel('account-login'))) {
-    event.preventDefault();
-    login().catch((/** @type {unknown} */ error) => {
-      reportError(error, 'login');
-    });
-  } else if (target.closest(sel('account-logout'))) {
-    event.preventDefault();
-    logout().catch((/** @type {unknown} */ error) => {
-      reportError(error, 'logout');
-    });
-  }
-}
-
-/** Back from the Worker's login (`?account=in`): drops the mark, and lets the Worker link the cart at checkout. */
-function startServerMode() {
-  const url = new URL(window.location.href);
-  if (url.searchParams.get('account')) {
-    url.searchParams.delete('account');
-    window.history.replaceState(window.history.state, '', url);
-    emit('account-login', {});
-  }
-  Cart.setCustomer({ beforeCheckout: serverCheckoutUrl });
-}
-
-/** Finishes a login that's coming back from Shopify, and links the cart of a customer who is logged in. */
-async function startBrowserMode() {
-  try {
-    await handleCallback();
-  } catch (error) {
-    reportError(error, 'login');
-  }
-  if (Cart.customerAccessToken) return;
-  try {
-    const accessToken = await getToken();
-    if (accessToken) Cart.setCustomer({ accessToken });
-  } catch (error) {
-    reportError(error, 'account');
-  }
-}
-
-let started = false;
-
-/**
- * Called by the core on mount: on the first one, finishes a login that's coming back; then fills the page.
- *
- * @param {ParentNode} [root]
- * @returns {Promise<void>}
- */
-export async function mountAccount(root = document) {
-  if (!started) {
-    started = true;
-    document.addEventListener('click', onClick);
-    if (serverBase()) startServerMode();
-    else await startBrowserMode();
-    log('account', isLoggedIn() ? 'logged in' : 'logged out');
-  }
-  await render(root);
-}

package/src/amounts.js

@@ -1,36 +0,0 @@
-/**
- * Shopify sends money amounts as decimal strings (`'27.50'`). Comparing them as floats can misjudge two amounts that
- * differ only past float precision, so they are compared digit by digit, as integers of the smallest unit present.
- */
-
-const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?$/;
-
-/**
- * @param {string} amount
- * @param {number} fractionDigits Digits after the point to scale to.
- * @returns {bigint | null} The amount in units of 10^-fractionDigits, `null` when it isn't a decimal number.
- */
-function toScaledInteger(amount, fractionDigits) {
-  const match = DECIMAL.exec(amount.trim());
-  if (!match) return null;
-  const [, sign = '', whole = '0', fraction = ''] = match;
-  const digits = BigInt(`${whole}${fraction.padEnd(fractionDigits, '0')}`);
-  return sign === '-' ? -digits : digits;
-}
-
-/** @param {string} amount */
-const fractionLength = (amount) => amount.split('.')[1]?.length ?? 0;
-
-/**
- * @param {string | null | undefined} amount
- * @param {string | null | undefined} other
- * @returns {boolean} True when both are decimal numbers and `amount` is the larger one.
- */
-export function isGreaterAmount(amount, other) {
-  if (amount == null || other == null) return false;
-  const fractionDigits = Math.max(fractionLength(amount.trim()), fractionLength(other.trim()));
-  const scaled = toScaledInteger(amount, fractionDigits);
-  const scaledOther = toScaledInteger(other, fractionDigits);
-  if (scaled === null || scaledOther === null) return false;
-  return scaled > scaledOther;
-}

package/src/analytics-shopify.js

@@ -1,241 +0,0 @@
-/**
- * Shopify's own analytics for the analytics part. Tether sets up the same event bus Hydrogen uses
- * (`window.Shopify.analytics`) and loads Shopify's consent script and shopify.js, which build and send the events.
- * Nothing is delivered before the Customer Privacy API allows analytics.
- */
-import { cfg, log, reportError } from './config.js';
-import { gql } from './client.js';
-
-/** @typedef {Record<string, unknown>} EventPayload */
-/** @typedef {{ uniqueToken: string, visitToken: string }} TrackingValues */
-/** @typedef {{ getTrackingValues: () => TrackingValues }} DestinationContext */
-/** @typedef {(payload: EventPayload, context: DestinationContext) => void} Subscriber */
-/** @typedef {(event: string, subscriber: Subscriber) => () => void} Subscribe */
-/** @typedef {{ shop: { shopId: string, channel: 'headless' }, consent: { mode: string } }} BusConfig */
-/**
- * @typedef {object} DestinationSpec What shopify.js registers.
- * @property {string} name
- * @property {(api: { subscribe: Subscribe, getConfig: () => BusConfig }) => unknown} [setup]
- */
-/**
- * @typedef {object} AnalyticsBus Hydrogen's `window.Shopify.analytics`.
- * @property {() => BusConfig} getConfig
- * @property {(event: string, payload?: EventPayload) => void} publish
- * @property {(destination: DestinationSpec) => () => void} addDestination
- */
-
-/**
- * The parts of Shopify's Customer Privacy API (`window.Shopify.customerPrivacy`) that decide tracking.
- *
- * @typedef {object} CustomerPrivacy
- * @property {string} [consentStatus]
- * @property {() => { analytics?: string } | undefined} [currentVisitorConsent]
- * @property {() => boolean} [analyticsProcessingAllowed]
- * @property {{ uniqueToken?: TokenReader, visitToken?: TokenReader }} [__internal]
- * @property {object} [config]
- */
-/** @typedef {(options: { generateFallback: boolean, tag: string }) => string} TokenReader */
-/**
- * `window.Shopify`, which Shopify's scripts read and extend.
- *
- * @typedef {object} ShopifyGlobal
- * @property {AnalyticsBus} [analytics]
- * @property {CustomerPrivacy} [customerPrivacy]
- * @property {string} [country]
- * @property {string} [locale]
- * @property {string} [shop]
- * @property {object} [routes]
- */
-
-/** @typedef {{ event: string, payload: EventPayload }} BufferedEvent */
-/**
- * @typedef {object} Destination
- * @property {string} name
- * @property {number} next The index of the next buffered event it gets.
- * @property {Map<string, Set<Subscriber>>} subscribers
- * @property {DestinationContext} context
- */
-
-/** Events kept for destinations that register late (shopify.js loads after the first page view). */
-const BUFFER_SIZE = 500;
-const CONSENT_SCRIPTS = {
-  'default-banner': 'https://cdn.shopify.com/shopifycloud/privacy-banner/storefront-banner.js',
-  other: 'https://cdn.shopify.com/shopifycloud/consent-tracking-api/v0.2/consent-tracking-api.js',
-};
-const ANALYTICS_SCRIPT = 'https://cdn.shopify.com/storefront/analytics/shopify.js';
-
-/** @returns {ShopifyGlobal | undefined} `window.Shopify`, whose shape Shopify's scripts define. */
-function shopifyGlobal() {
-  /** @type {unknown} */
-  const shopify = Reflect.get(window, 'Shopify');
-  return /** @type {ShopifyGlobal | undefined} */ (shopify);
-}
-
-/** @returns {{ consent?: string, proxy?: string }} The `analytics.shopify` options; `true` sets none. */
-function shopifyOptions() {
-  const shopify = cfg.analytics?.shopify;
-  return typeof shopify === 'object' ? shopify : {};
-}
-
-/**
- * Shopify's privacy API can throw while its script is still setting up. An answer it can't give counts as "not
- * allowed", so nothing is sent without consent; the next consent event asks again.
- *
- * @returns {boolean}
- */
-function trackingAllowed() {
-  try {
-    const privacy = shopifyGlobal()?.customerPrivacy;
-    return (
-      privacy?.consentStatus === 'loaded' &&
-      privacy.currentVisitorConsent?.()?.analytics !== 'no' &&
-      Boolean(privacy.analyticsProcessingAllowed?.())
-    );
-  } catch {
-    return false;
-  }
-}
-
-/**
- * @param {string} name The destination's name, Hydrogen tags its tokens with it.
- * @returns {DestinationContext}
- */
-function destinationContext(name) {
-  const tag = `hydrogen:${name}`;
-  return {
-    getTrackingValues: () => {
-      const internal = trackingAllowed() ? shopifyGlobal()?.customerPrivacy?.__internal : undefined;
-      return {
-        uniqueToken: internal?.uniqueToken?.({ generateFallback: true, tag }) ?? '',
-        visitToken: internal?.visitToken?.({ generateFallback: true, tag }) ?? '',
-      };
-    },
-  };
-}
-
-/**
- * @param {Destination} destination
- * @returns {Subscribe}
- */
-const subscriberOf = (destination) => (event, subscriber) => {
-  const subscribers = destination.subscribers.get(event) ?? new Set();
-  destination.subscribers.set(event, subscribers);
-  subscribers.add(subscriber);
-  return () => destination.subscribers.get(event)?.delete(subscriber);
-};
-
-/**
- * @param {string} shopId
- * @returns {AnalyticsBus} A bus that buffers events and delivers them to each destination once consent allows.
- */
-function createBus(shopId) {
-  /** @type {Destination[]} */
-  const destinations = [];
-  /** @type {BufferedEvent[]} */
-  const buffer = [];
-  /** @type {BusConfig} */
-  const config = {
-    shop: { shopId, channel: 'headless' },
-    consent: { mode: shopifyOptions().consent || 'no-banner' },
-  };
-  const deliver = () => {
-    if (!trackingAllowed()) return;
-    for (const destination of destinations) {
-      for (; destination.next < buffer.length; destination.next += 1) {
-        const buffered = buffer[destination.next];
-        if (buffered) deliverTo(destination, buffered);
-      }
-    }
-  };
-  /** @type {AnalyticsBus} */
-  const bus = {
-    getConfig: () => config,
-    publish(event, payload = {}) {
-      buffer.push({ event, payload: { shop: config.shop, url: window.location.href, ...payload } });
-      if (buffer.length > BUFFER_SIZE) {
-        buffer.shift();
-        for (const destination of destinations) destination.next = Math.max(0, destination.next - 1);
-      }
-      deliver();
-    },
-    addDestination(spec) {
-      /** @type {Destination} */
-      const destination = { name: spec.name, next: 0, subscribers: new Map(), context: destinationContext(spec.name) };
-      Promise.resolve(spec.setup?.({ subscribe: subscriberOf(destination), getConfig: bus.getConfig }))
-        .then(() => {
-          destinations.push(destination);
-          deliver();
-        })
-        .catch((/** @type {unknown} */ error) => {
-          reportError(error, `analytics ${spec.name}`);
-        });
-      return () => {
-        const index = destinations.indexOf(destination);
-        if (index >= 0) destinations.splice(index, 1);
-      };
-    },
-  };
-  document.addEventListener('consentTrackingApiLoaded', deliver);
-  document.addEventListener('visitorConsentCollected', deliver);
-  return bus;
-}
-
-/**
- * @param {Destination} destination
- * @param {BufferedEvent} buffered
- */
-function deliverTo(destination, { event, payload }) {
-  destination.subscribers.get(event)?.forEach((subscriber) => {
-    try {
-      subscriber(payload, destination.context);
-    } catch (error) {
-      reportError(error, `analytics ${destination.name}`);
-    }
-  });
-}
-
-/** @param {string} src */
-function loadScript(src) {
-  const script = document.createElement('script');
-  script.src = src;
-  script.async = true;
-  document.head.appendChild(script);
-}
-
-/**
- * Sets up `window.Shopify` for Shopify's scripts and loads them.
- *
- * @param {() => boolean} isProductPage Asked by Shopify's script for the page template.
- * @returns {Promise<AnalyticsBus>} The bus, the page's own when a theme already set one up.
- */
-export async function startShopifyAnalytics(isProductPage) {
-  const existing = shopifyGlobal();
-  if (existing?.analytics) return existing.analytics;
-  /** @type {{ shop: { id: string } }} */
-  const data = await gql('query TetherShopId { shop { id } }', {}, { context: false });
-  const shopify = shopifyGlobal() ?? {};
-  Reflect.set(window, 'Shopify', shopify);
-  shopify.country = (cfg.country || 'US').toUpperCase();
-  // Shopify's script requires a language, not a full locale.
-  shopify.locale = (cfg.locale || 'en').split('-')[0]?.toLowerCase() ?? 'en';
-  shopify.shop = cfg.domain;
-  shopify.routes = {
-    root: '/',
-    match: () => ({ pageTemplateName: isProductPage() ? 'product' : 'page' }),
-    ...shopify.routes,
-  };
-  // A same-origin Storefront API path gives Shopify exact visitor counts.
-  const { proxy, consent } = shopifyOptions();
-  shopify.customerPrivacy = {
-    ...shopify.customerPrivacy,
-    config: proxy
-      ? { isHeadless: true, asyncConsent: true, asyncVisitorState: true, consentDomain: window.location.host }
-      : { isHeadless: true, storefrontAccessToken: cfg.token, checkoutRootDomain: cfg.domain },
-  };
-  const bus = createBus(data.shop.id);
-  shopify.analytics = bus;
-  loadScript(consent === 'default-banner' ? CONSENT_SCRIPTS['default-banner'] : CONSENT_SCRIPTS.other);
-  loadScript(ANALYTICS_SCRIPT);
-  log('shopify analytics ready', data.shop.id);
-  return bus;
-}