@occluze/tether 0.7.0 → 0.7.1

package/src/account.ts

@@ -1,284 +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 coming back, or the visitor may be logged in.
- *
- *   window.TETHER_CONFIG = { …, account: { server: '/_tether/account' } }
- *
- *   <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>
- *
- * The site's Worker logs the customer in and holds the tokens (`account/server-client.ts` is this browser's side of
- * it), so no token is ever in the browser. 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.ts';
-import { TetherError } from './client.ts';
-import { sel, get, qsa, setText, show, emit } from './dom.ts';
-import { Cart } from './cart.ts';
-import { loadPart } from './lazy.ts';
-import type { Parts } from './lazy.ts';
-import {
-  forgetServerLogin,
-  isServerLoggedIn,
-  serverCheckoutUrl,
-  serverFetch,
-  serverLogin,
-  serverLoginRedirect,
-  serverLogout,
-} from './account/server-client.ts';
-import { DEFAULT_ORDER_COUNT, MAX_ORDER_COUNT, isOrderCount, renderOrderList } from './account/order-list.ts';
-import { ownValue } from './account/markup.ts';
-import { toAccountOrders } from './account/answers.ts';
-import type { AccountCustomer } from './account/answers.ts';
-import { isLoginOutcome } from './account-marks.ts';
-import type { AccountOrder } from '../server/src/shared/account-orders.ts';
-import type { AddressFields, ReturnLine } from './account/operations.ts';
-import type {
-  AccountAddress,
-  CustomerAddress,
-  OpenedReturn,
-  OrderDetail,
-  Profile,
-  SubscriptionChange,
-  SubscriptionContract,
-} from './account/page-answers.ts';
-import type { SubscriptionAction } from '../server/src/shared/account-routes.ts';
-
-/**
- * `unknown` when the Worker or Shopify can't say: the page shows its logged-out content, and the account pages their
- * error state.
- */
-type LoginState = { kind: 'logged-in' } | { kind: 'logged-out' } | { kind: 'unknown'; error: unknown };
-
-/** The attributes of the account pages, which are their own part. */
-const PAGE_ATTRIBUTES = ['order', 'addresses', 'subscriptions', 'profile-form', 'address-form'];
-
-/** @returns True when the Worker last said a customer is logged in; false before it has been asked. */
-export const isLoggedIn = isServerLoggedIn;
-
-/**
- * Through the Worker to Shopify's login page; the visitor comes back to `returnTo`.
- *
- * @throws {TetherError} `NOT_CONFIGURED` without `account.server`.
- */
-export function login({
-  returnTo = window.location.href,
-  locale,
-}: { returnTo?: string; locale?: string } = {}): Promise<void> {
-  // In a promise, so a missing `account.server` rejects as it does for every other account function.
-  return new Promise((resolve) => {
-    serverLoginRedirect({ returnTo, locale });
-    resolve();
-  });
-}
-
-/**
- * @returns The logged-in customer, `null` when nobody is.
- * @throws {TetherError} When the Worker can't be reached or fails.
- */
-export async function customer(): Promise<AccountCustomer | null> {
-  const me = await serverLogin();
-  return me.loggedIn ? me.customer : null;
-}
-
-/**
- * @param options `first`: a whole number from 1 to `MAX_ORDER_COUNT`.
- * @returns The customer's most recent orders, newest first; none when nobody is logged in.
- * @throws {TetherError} `INVALID` for another `first`, which is refused before any request; else when the Worker or
- *   Shopify can't answer.
- */
-export async function orders({ first = DEFAULT_ORDER_COUNT }: { first?: number } = {}): Promise<AccountOrder[]> {
-  if (!isOrderCount(first)) {
-    throw new TetherError(`Customer accounts: orders() takes first from 1 to ${String(MAX_ORDER_COUNT)}`, {
-      code: 'INVALID',
-    });
-  }
-  const answer = await serverFetch(`/orders?${new URLSearchParams({ first: String(first) }).toString()}`);
-  return answer.kind === 'logged-out' ? [] : toAccountOrders(answer.data['orders']);
-}
-
-/**
- * Logs out here and at Shopify, and unlinks the cart. Sends `tether:account-logout`.
- *
- * @param options `returnTo`: where Shopify sends the visitor afterwards.
- */
-export async function logout({
-  returnTo = cfg.account?.logoutUrl || `${window.location.origin}/`,
-}: { returnTo?: string } = {}): Promise<void> {
-  if ((await serverLogout(returnTo)) === 'stayed') await render(document);
-}
-
-async function loginState(): Promise<LoginState> {
-  try {
-    return (await serverLogin()).loggedIn ? { kind: 'logged-in' } : { kind: 'logged-out' };
-  } catch (error) {
-    return { kind: 'unknown', error };
-  }
-}
-
-const usesPages = (root: ParentNode): boolean => 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.
- */
-function linkShopifyPages(root: ParentNode): void {
-  qsa(root, sel('account-link')).forEach((link) => {
-    link.setAttribute('href', shopifyPageUrl(get(link, 'account-link')));
-  });
-}
-
-/**
- * @param page The `tether-account-link` value.
- * @returns The configured page for it, else the shop's account.
- */
-function shopifyPageUrl(page: string | null): string {
-  const account = cfg.account;
-  const fallback = `https://${cfg.domain}/account`;
-  if (page === 'payment') return account?.paymentUrl || account?.subscriptionsUrl || fallback;
-  if (page === 'subscriptions') return account?.subscriptionsUrl || fallback;
-  return fallback;
-}
-
-/**
- * Fills the account markup in `root`: what shows when logged in or out, the customer, their orders, and the account
- * pages.
- */
-export async function render(root: ParentNode = document): Promise<void> {
-  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.
- */
-async function bindCustomer(root: ParentNode): Promise<void> {
-  const binds = qsa(root, sel('account-bind'));
-  if (!binds.length) return;
-  let profile: AccountCustomer | null;
-  try {
-    profile = await customer();
-  } catch (error) {
-    reportError(error, 'account');
-    return;
-  }
-  if (!profile) return;
-  const texts: Record<string, string | null | undefined> = {
-    '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);
-  });
-}
-
-let pagesPart: Promise<Parts['account-pages']> | null = null;
-
-/** @returns The account pages part, sharing this part's session. */
-function pages(): Promise<Parts['account-pages']> {
-  pagesPart ??= loadPart('account-pages').then((part) => {
-    part.setup({ serverFetch, customer, bindCustomer, reset: forgetServerLogin });
-    return part;
-  });
-  return pagesPart;
-}
-
-/** One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns). */
-export const order = (id: string | number): Promise<OrderDetail | null> => pages().then((part) => part.order(id));
-export const updateProfile = (fields?: { firstName?: string; lastName?: string }): Promise<Profile> =>
-  pages().then((part) => part.updateProfile(fields));
-export const addresses = (): Promise<CustomerAddress[]> => pages().then((part) => part.addresses());
-/** Creates an address, or updates the one with `id`. */
-export const saveAddress = (
-  address: AddressFields | null,
-  options?: { id?: string; isDefault?: boolean },
-): Promise<AccountAddress> => pages().then((part) => part.saveAddress(address, options));
-export const deleteAddress = (id: string): Promise<string> => pages().then((part) => part.deleteAddress(id));
-export const subscriptions = (): Promise<SubscriptionContract[]> => pages().then((part) => part.subscriptions());
-export const subscriptionAction = (id: string | number, action: SubscriptionAction): Promise<SubscriptionChange> =>
-  pages().then((part) => part.subscriptionAction(id, action));
-export const requestReturn = (orderId: string | number, lines: ReturnLine[]): Promise<OpenedReturn> =>
-  pages().then((part) => part.requestReturn(orderId, lines));
-
-function onClick(event: MouseEvent): void {
-  const target = event.target;
-  if (!(target instanceof window.Element)) return;
-  if (target.closest(sel('account-login'))) {
-    event.preventDefault();
-    login().catch((error: unknown) => {
-      reportError(error, 'login');
-    });
-  } else if (target.closest(sel('account-logout'))) {
-    event.preventDefault();
-    logout().catch((error: unknown) => {
-      reportError(error, 'logout');
-    });
-  }
-}
-
-/**
- * Back from the Worker's login (`?account=`): drops the mark and sends `tether:account-login`, or
- * `tether:account-error` with the outcome as its `error` when the login didn't finish.
- */
-function finishServerLogin(): void {
-  const url = new URL(window.location.href);
-  const outcome = url.searchParams.get('account');
-  if (!isLoginOutcome(outcome)) return;
-  url.searchParams.delete('account');
-  window.history.replaceState(window.history.state, '', url);
-  switch (outcome) {
-    case 'in':
-      emit('account-login', {});
-      break;
-    case 'expired':
-    case 'error':
-      emit('account-error', { error: outcome });
-      break;
-  }
-}
-
-let started = false;
-
-/**
- * Called by the core on mount: on the first one, finishes a login that's coming back and lets the Worker link the
- * cart at checkout; then fills the page.
- */
-export async function mountAccount(root: ParentNode = document): Promise<void> {
-  if (started) {
-    await render(root);
-    return;
-  }
-  started = true;
-  document.addEventListener('click', onClick);
-  finishServerLogin();
-  Cart.setCheckoutResolver(serverCheckoutUrl);
-  await render(root);
-  log('account', isLoggedIn() ? 'logged in' : 'logged out');
-}

package/src/amounts.ts

@@ -1,64 +0,0 @@
-/**
- * Arithmetic on Shopify's money amounts, which are decimal strings (`'27.50'`). Comparisons go digit by digit, as
- * integers of the smallest unit present, so two amounts that differ only past float precision aren't misjudged. Sums
- * and differences are taken in the currency's own smallest unit, so JPY stays whole and KWD keeps its three digits.
- */
-import type { Money } from './shopify-values.ts';
-
-const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?$/;
-
-/**
- * @param fractionDigits Digits after the point to scale to.
- * @returns The amount in units of 10^-fractionDigits, `null` when it isn't a decimal number.
- */
-function toScaledInteger(amount: string, fractionDigits: number): bigint | null {
-  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;
-}
-
-const fractionLength = (amount: string) => amount.split('.')[1]?.length ?? 0;
-
-/** @returns True when both are decimal numbers and `amount` is the larger one. */
-export function isGreaterAmount(amount: string | null | undefined, other: string | null | undefined): boolean {
-  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;
-}
-
-/** For a currency code Intl doesn't know: most currencies have two digits, and `formatMoney` then shows two too. */
-const DEFAULT_FRACTION_DIGITS = 2;
-
-/** Currency code → its fraction digits, which never change on a page. */
-const fractionDigitsByCurrency = new Map<string, number>();
-
-/** @returns The digits after the point the currency has: 0 for JPY, 2 for EUR, 3 for KWD. */
-function currencyFractionDigits(currencyCode: string): number {
-  const known = fractionDigitsByCurrency.get(currencyCode);
-  if (known !== undefined) return known;
-  let digits = DEFAULT_FRACTION_DIGITS;
-  try {
-    const format = new Intl.NumberFormat('en', { style: 'currency', currency: currencyCode });
-    digits = format.resolvedOptions().maximumFractionDigits ?? DEFAULT_FRACTION_DIGITS;
-  } catch {
-    // A code Intl doesn't know (RangeError): see DEFAULT_FRACTION_DIGITS.
-  }
-  fractionDigitsByCurrency.set(currencyCode, digits);
-  return digits;
-}
-
-/** @returns The amount in the currency's smallest unit (cents, yen, fils), rounded to a whole one. */
-export function toMinorUnits(money: Money): number {
-  return Math.round(parseFloat(money.amount) * 10 ** currencyFractionDigits(money.currencyCode));
-}
-
-/** @returns The amount written with the currency's own number of digits. */
-export function fromMinorUnits(minorUnits: number, currencyCode: string): Money {
-  const digits = currencyFractionDigits(currencyCode);
-  return { amount: (minorUnits / 10 ** digits).toFixed(digits), currencyCode };
-}

package/src/analytics-shopify.ts

@@ -1,246 +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.ts';
-import { gql, shaped } from './client.ts';
-import type { AnalyticsConfig } from './config.ts';
-
-export type EventPayload = Record<string, unknown>;
-
-interface TrackingValues {
-  uniqueToken: string;
-  visitToken: string;
-}
-
-interface DestinationContext {
-  getTrackingValues: () => TrackingValues;
-}
-
-type Subscriber = (payload: EventPayload, context: DestinationContext) => void;
-type Subscribe = (event: string, subscriber: Subscriber) => () => void;
-
-interface BusConfig {
-  shop: { shopId: string; channel: 'headless' };
-  consent: { mode: string };
-}
-
-/** What shopify.js registers. */
-interface DestinationSpec {
-  name: string;
-  setup?: (api: { subscribe: Subscribe; getConfig: () => BusConfig }) => unknown;
-}
-
-/** Hydrogen's `window.Shopify.analytics`. */
-export interface AnalyticsBus {
-  getConfig: () => BusConfig;
-  publish: (event: string, payload?: EventPayload) => void;
-  addDestination: (destination: DestinationSpec) => () => void;
-}
-
-type TokenReader = (options: { generateFallback: boolean; tag: string }) => string;
-
-/** The parts of Shopify's Customer Privacy API (`window.Shopify.customerPrivacy`) that decide tracking. */
-interface CustomerPrivacy {
-  consentStatus?: string;
-  currentVisitorConsent?: () => { analytics?: string } | undefined;
-  analyticsProcessingAllowed?: () => boolean;
-  __internal?: { uniqueToken?: TokenReader; visitToken?: TokenReader };
-  config?: object;
-}
-
-/** `window.Shopify`, which Shopify's scripts read and extend. */
-interface ShopifyGlobal {
-  analytics?: AnalyticsBus;
-  customerPrivacy?: CustomerPrivacy;
-  country?: string;
-  locale?: string;
-  shop?: string;
-  routes?: object;
-}
-
-interface BufferedEvent {
-  event: string;
-  payload: EventPayload;
-}
-
-interface Destination {
-  name: string;
-  /** The index of the next buffered event it gets. */
-  next: number;
-  subscribers: Map<string, Set<Subscriber>>;
-  context: DestinationContext;
-}
-
-/** 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';
-
-/** The page, where Shopify's scripts keep `window.Shopify` in the shape they define. */
-const page = (): Window & { Shopify?: ShopifyGlobal } => window;
-
-const shopifyGlobal = (): ShopifyGlobal | undefined => page().Shopify;
-
-/** The `analytics.shopify` options; `true` sets none. */
-function shopifyOptions(): Exclude<NonNullable<AnalyticsConfig['shopify']>, boolean> {
-  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.
- */
-function trackingAllowed(): boolean {
-  try {
-    const privacy = shopifyGlobal()?.customerPrivacy;
-    return (
-      privacy?.consentStatus === 'loaded' &&
-      privacy.currentVisitorConsent?.()?.analytics !== 'no' &&
-      Boolean(privacy.analyticsProcessingAllowed?.())
-    );
-  } catch {
-    return false;
-  }
-}
-
-/** @param name The destination's name, Hydrogen tags its tokens with it. */
-function destinationContext(name: string): DestinationContext {
-  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 }) ?? '',
-      };
-    },
-  };
-}
-
-const subscriberOf =
-  (destination: Destination): Subscribe =>
-  (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);
-  };
-
-/** A bus that buffers events and delivers them to each destination once consent allows. */
-function createBus(shopId: string): AnalyticsBus {
-  const destinations: Destination[] = [];
-  const buffer: BufferedEvent[] = [];
-  const config: BusConfig = {
-    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);
-      }
-    }
-  };
-  const bus: AnalyticsBus = {
-    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) {
-      const destination: 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((error: unknown) => {
-          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;
-}
-
-function deliverTo(destination: Destination, { event, payload }: BufferedEvent): void {
-  destination.subscribers.get(event)?.forEach((subscriber) => {
-    try {
-      subscriber(payload, destination.context);
-    } catch (error) {
-      reportError(error, `analytics ${destination.name}`);
-    }
-  });
-}
-
-function loadScript(src: string): void {
-  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 isProductPage Asked by Shopify's script for the page template.
- * @returns The bus, the page's own when a theme already set one up.
- */
-export async function startShopifyAnalytics(isProductPage: () => boolean): Promise<AnalyticsBus> {
-  const existing = shopifyGlobal();
-  if (existing?.analytics) return existing.analytics;
-  const data = await gql(
-    'query TetherShopId { shop { id } }',
-    {},
-    shaped<{ shop: { id: string } }>({ shop: { id: 'string' } }),
-    { context: false },
-  );
-  const shopify = shopifyGlobal() ?? {};
-  page().Shopify = shopify;
-  shopify.country = cfg.country ?? 'US';
-  // Shopify's script requires a language, not a full locale.
-  const [language = 'en'] = (cfg.locale || 'en').split('-');
-  shopify.locale = language.toLowerCase();
-  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;
-}