@occluze/tether 0.6.8 → 0.7.0

package/src/client.ts

@@ -0,0 +1,391 @@
+/**
+ * The one Storefront API client: a fetch wrapper that adds the market (`@inContext`), retries what Shopify asks to be
+ * retried, and turns every failure into a `TetherError`, an answer whose `data` lacks what its caller reads included
+ * (`DataCheck`). The browser (`gql`, and `query` for `Tether.query()`) and the server helpers (`request` with their own
+ * config) share it.
+ */
+import { cfg, log } from './config.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import { field, isRecord } from '../server/src/shared/json.ts';
+import { messageOf } from '../server/src/shared/error-message.ts';
+import type { TetherConfig } from './config.ts';
+import type { CountryCode, LanguageCode } from './market-codes.ts';
+
+export type TetherErrorCode =
+  | 'NOT_FOUND'
+  | 'NETWORK'
+  | 'NOT_CONFIGURED'
+  | 'NOT_LOGGED_IN'
+  | 'INVALID'
+  | 'INVALID_COUNTRY'
+  | 'INVALID_DISCOUNT'
+  | 'ERROR'
+  | `HTTP_${number}`;
+export interface GraphQLError {
+  message: string;
+  extensions?: { code?: string };
+}
+/** The response shape the GraphQL spec sets. */
+interface GraphQLResponse {
+  data?: unknown;
+  errors?: GraphQLError[];
+}
+export interface UserError {
+  message: string;
+  field?: string[] | null;
+  code?: string | null;
+}
+interface TetherErrorDetails {
+  /** Default `HTTP_<status>` with a status, else `ERROR`. */
+  code?: TetherErrorCode;
+  /** The HTTP status of the response that failed. */
+  status?: number;
+  /** The GraphQL errors of that response. */
+  errors?: GraphQLError[];
+  /** A mutation's user errors. */
+  userErrors?: readonly UserError[];
+}
+
+export class TetherError extends Error {
+  override name = 'TetherError' as const;
+  code: TetherErrorCode;
+  status: number | undefined;
+  errors: GraphQLError[] | undefined;
+  userErrors: readonly UserError[] | undefined;
+
+  constructor(message: string, { status, errors, userErrors, code }: TetherErrorDetails = {}) {
+    super(message);
+    this.code = code ?? (status ? `HTTP_${status}` : 'ERROR');
+    this.status = status;
+    this.errors = errors;
+    this.userErrors = userErrors;
+  }
+}
+
+/** What a request needs from a config: the browser's `cfg`, or a config the server helpers build. */
+export type StorefrontConfig = Pick<
+  TetherConfig,
+  'domain' | 'token' | 'apiVersion' | 'country' | 'language' | 'maxAge' | 'retries'
+> & { fetch?: typeof fetch };
+/** Checks a query's `data` before its caller reads it as a `T`. */
+export type DataCheck<T> = (data: unknown) => data is T;
+/**
+ * The structure of JSON a check accepts: a `typeof` name, `'object'` for a plain object, `[item]` for a list of
+ * items, an object's fields, or a check of its own. Fields it doesn't name aren't checked, so a shape names only what
+ * its reader walks without a fallback.
+ */
+export type Shape =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'object'
+  | ((value: unknown) => boolean)
+  | readonly [Shape]
+  | { readonly [key: string]: Shape };
+
+/** @returns True when `value` has the structure `shape` describes. */
+export function matches(value: unknown, shape: Shape): boolean {
+  if (typeof shape === 'function') return shape(value);
+  if (typeof shape === 'string') return shape === 'object' ? isRecord(value) : typeof value === shape;
+  if (isShapeList(shape)) return Array.isArray(value) && value.every((item) => matches(item, shape[0]));
+  return isRecord(value) && Object.entries(shape).every(([key, inner]) => matches(value[key], inner));
+}
+
+/** `Array.isArray` doesn't narrow a readonly tuple out of a union. */
+const isShapeList = (shape: Shape): shape is readonly [Shape] => Array.isArray(shape);
+
+/** @returns The shape of `null` or a value with the structure `shape` describes. */
+export const orNull =
+  (shape: Shape) =>
+  (value: unknown): boolean =>
+    value === null || matches(value, shape);
+
+/** @returns A check that `data` has the structure `shape` describes, which `T` states. */
+export const shaped =
+  <T>(shape: Shape): DataCheck<T> =>
+  (data): data is T =>
+    matches(data, shape);
+/** `context: false` sends the query without `@inContext`. */
+interface RequestOptions {
+  context?: boolean;
+}
+/** What the store's token may read beyond the defaults. */
+export interface StoreAccess {
+  inventory: boolean;
+}
+/**
+ * A query's text, or a function that writes it for what the token may read: Tether's own queries, built from
+ * `fragments.ts`, leave out inventory for a token that can't read it.
+ */
+export type QueryText = string | ((access: StoreAccess) => string);
+
+/** @returns The Storefront GraphQL endpoint of `conf`'s store. */
+export function endpoint(conf: Pick<TetherConfig, 'domain' | 'apiVersion'> = cfg): string {
+  return `https://${conf.domain}/api/${conf.apiVersion}/graphql.json`;
+}
+
+/** GraphQL strings and `#` comments: text in them is never part of an operation's header. */
+const STRINGS_AND_COMMENTS = /"(?:\\.|[^"\\\n])*"|#[^\n]*/g;
+/** An operation's keyword, name and variable definitions: named (query Name($x: T)) and anonymous (query { … }). */
+const OPERATION_START = /^\s*(?:query|mutation)(?:\s+\w+)?\s*(?:\([^)]*\))?/;
+
+/**
+ * Adds @inContext(country, language) to the first operation in the document, so prices, currency and translations
+ * follow the market. The header is found in a copy of the document whose strings and comments are blanked out, so a
+ * `)` in a default value or an `@inContext` in a comment or the selection set doesn't move or stop it; an operation
+ * that names its own `@inContext` keeps it. Tether's own documents start with their operation, and so do the ones
+ * `Tether.query()` is given in practice: a document that starts with a fragment is sent as written.
+ */
+function inContext(
+  query: string,
+  { country, language }: { country: CountryCode | undefined; language: LanguageCode | undefined },
+): string {
+  const args: string[] = [];
+  if (country) args.push(`country: ${country}`);
+  if (language) args.push(`language: ${language}`);
+  if (!args.length) return query;
+  const tag = `@inContext(${args.join(', ')})`;
+  const blanked = query.replace(STRINGS_AND_COMMENTS, (text) => ' '.repeat(text.length));
+  const selectionStart = blanked.indexOf('{');
+  if (blanked.slice(0, selectionStart).includes('@inContext')) return query;
+  // Shorthand: a document that starts with its selection set is a query without a keyword.
+  if (blanked.trimStart().startsWith('{')) return `query ${tag} ${query.slice(selectionStart)}`;
+  const header = OPERATION_START.exec(blanked);
+  if (!header) return query;
+  const end = header[0].length;
+  return `${query.slice(0, end).trimEnd()} ${tag} ${query.slice(end).trimStart()}`;
+}
+
+/**
+ * `inContext` for any country and language, as the public `Tether.withContext` takes them: one that isn't a valid
+ * code is left out, so page input never becomes query text.
+ */
+export function withContext(
+  query: string,
+  ctx: { country?: string | undefined; language?: string | undefined } = cfg,
+): string {
+  const country = toCountry(ctx.country) ?? undefined;
+  const language = toLanguage(ctx.language) ?? undefined;
+  return inContext(query, { country, language });
+}
+
+/** Backoff after a network error or a 429/5xx: this times 2^attempt. */
+const RETRY_BACKOFF_MS = 300;
+/** Backoff after Shopify's `THROTTLED` error, which asks for a longer wait: this times 2^attempt. */
+const THROTTLE_BACKOFF_MS = 500;
+/** Shopify's status for a request its bot protection rejected; retrying doesn't help. */
+const SECURITY_REJECTION = 430;
+const MS_PER_SECOND = 1000;
+
+/**
+ * `quantityAvailable` needs the token's `unauthenticated_read_product_inventory` scope; without it Shopify refuses the
+ * whole query with an error naming the field. That refusal is learned once per page and store: Tether's later queries
+ * to the store are written without the field (`StoreAccess`), so stock levels are unknown and everything else works,
+ * for one extra request.
+ */
+const INVENTORY_FIELD = 'quantityAvailable';
+
+/** The stores (domain, version and token) whose token can't read inventory. */
+const storesWithoutInventory = new Set<string>();
+
+const storeOf = (conf: StorefrontConfig) => `${conf.domain} ${conf.apiVersion} ${conf.token}`;
+
+/** @returns The text sent: with the market, and the cache's time bucket for a query. */
+function queryText(conf: StorefrontConfig, query: QueryText, access: StoreAccess, context: boolean): string {
+  const written = typeof query === 'string' ? query : query(access);
+  const text = context ? inContext(written, conf) : written;
+  if (conf.maxAge <= 0 || /^\s*mutation\b/.test(text)) return text;
+  return `${text} #${Math.floor(Date.now() / (conf.maxAge * MS_PER_SECOND))}`;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** What a status means, for errors Shopify sends without a message (401/403 have none). */
+function statusText(status: number, conf: StorefrontConfig): string {
+  if (status === 401 || status === 403) {
+    const adminHint = conf.token.startsWith('shpat_') ? ', not an Admin API token (shpat_…)' : '';
+    return `Shopify rejected the Storefront token for ${conf.domain} (${status}): use the public Storefront API token (Headless channel)${adminHint}`;
+  }
+  if (status === 404) {
+    return `Store or API version not found (404): check domain ${conf.domain} and apiVersion ${conf.apiVersion}`;
+  }
+  return `HTTP ${status} from ${conf.domain}`;
+}
+
+/**
+ * @param value One entry of a response's `errors`.
+ * @returns The error, with an empty message when it has none.
+ */
+function toGraphQLError(value: unknown): GraphQLError {
+  const message = field(value, 'message');
+  const code = field(field(value, 'extensions'), 'code');
+  const text = typeof message === 'string' ? message : '';
+  return typeof code === 'string' ? { message: text, extensions: { code } } : { message: text };
+}
+
+/**
+ * @param json A response body.
+ * @returns The body in the shape the GraphQL spec sets, `null` when it has another one.
+ */
+function toGraphQLResponse(json: unknown): GraphQLResponse | null {
+  if (!isRecord(json)) return null;
+  const { data, errors } = json;
+  if (errors === undefined || errors === null) return { data };
+  if (!Array.isArray(errors)) return null;
+  return { data, errors: errors.map(toGraphQLError) };
+}
+
+/** For a body that isn't JSON, isn't in the GraphQL shape or has `data` its caller's check refuses. */
+function invalidResponse(res: Response, conf: StorefrontConfig): TetherError {
+  const text = res.ok ? `Invalid response (${res.status})` : statusText(res.status, conf);
+  return new TetherError(text, { status: res.status });
+}
+
+function graphQLFailure(res: Response, errors: GraphQLError[], conf: StorefrontConfig): TetherError {
+  const message = errors
+    .map((error) => error.message)
+    .filter(Boolean)
+    .join(' | ');
+  let text = message || 'Storefront API error';
+  if (!res.ok) text = res.status === 401 || res.status === 403 || !message ? statusText(res.status, conf) : message;
+  return new TetherError(text, { status: res.status, errors });
+}
+
+type Attempt<T> =
+  { kind: 'data'; data: T } | { kind: 'retry'; backoffMs: number } | { kind: 'inventory-refused'; error: TetherError };
+
+/**
+ * One request. Failures that retrying can't fix throw.
+ *
+ * @param canRetry False on the last attempt: a retryable failure then throws too.
+ */
+async function attempt<T>(
+  conf: StorefrontConfig,
+  query: string,
+  variables: Record<string, unknown>,
+  isData: DataCheck<T>,
+  canRetry: boolean,
+): Promise<Attempt<T>> {
+  let res;
+  try {
+    res = await (conf.fetch ?? fetch)(endpoint(conf), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Shopify-Storefront-Access-Token': conf.token },
+      body: JSON.stringify({ query, variables }),
+    });
+  } catch (error) {
+    if (canRetry) return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
+    throw new TetherError(`Network error: ${messageOf(error)}`, {
+      code: 'NETWORK',
+    });
+  }
+  if (res.status === SECURITY_REJECTION) {
+    throw new TetherError('Shopify security rejection (430)', { status: SECURITY_REJECTION });
+  }
+  if (canRetry && (res.status === 429 || res.status >= 500)) {
+    return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
+  }
+
+  let json: unknown;
+  try {
+    json = await res.json();
+  } catch {
+    throw invalidResponse(res, conf);
+  }
+  const body = toGraphQLResponse(json);
+  if (!body) throw invalidResponse(res, conf);
+  const { data, errors = [] } = body;
+  if (errors.length) {
+    if (query.includes(INVENTORY_FIELD) && errors.some((error) => error.message.includes(INVENTORY_FIELD))) {
+      return { kind: 'inventory-refused', error: graphQLFailure(res, errors, conf) };
+    }
+    if (canRetry && errors.some((error) => error.extensions?.code === 'THROTTLED')) {
+      return { kind: 'retry', backoffMs: THROTTLE_BACKOFF_MS };
+    }
+    throw graphQLFailure(res, errors, conf);
+  }
+  if (!res.ok) throw new TetherError(statusText(res.status, conf), { status: res.status });
+  if (!isData(data)) throw invalidResponse(res, conf);
+  return { kind: 'data', data };
+}
+
+/**
+ * One Storefront API request, for any config: the browser's shared one (`gql`) or one the server helpers build.
+ * Queries carry a time bucket so Shopify's cache of an identical query text is at most `maxAge` seconds old. A query
+ * written for the store's access leaves out inventory once the token turns out not to read it (`INVENTORY_FIELD`);
+ * a fixed query text is the caller's own, and that refusal is its error.
+ *
+ * @param isData Checks that `data` has what the caller then reads, so a malformed answer fails here.
+ * @throws {TetherError} `NOT_CONFIGURED` without a domain or token, `NETWORK` when the store can't be reached,
+ *   `HTTP_<status>` for an HTTP or GraphQL failure, or for `data` that `isData` refuses.
+ */
+export async function request<T>(
+  conf: StorefrontConfig,
+  query: QueryText,
+  variables: Record<string, unknown>,
+  isData: DataCheck<T>,
+  { context = true }: RequestOptions = {},
+): Promise<T> {
+  if (!conf.domain || !conf.token) {
+    throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
+  }
+  const store = storeOf(conf);
+  let retries = 0;
+  for (;;) {
+    const sent = queryText(conf, query, { inventory: !storesWithoutInventory.has(store) }, context);
+    const outcome = await attempt(conf, sent, variables, isData, retries < conf.retries);
+    switch (outcome.kind) {
+      case 'data':
+        return outcome.data;
+      case 'inventory-refused':
+        if (typeof query === 'string') throw outcome.error;
+        log(`the token can't read inventory: ${INVENTORY_FIELD} is left out from now on`);
+        storesWithoutInventory.add(store);
+        break;
+      case 'retry':
+        retries += 1;
+        log('retry', retries);
+        await sleep(outcome.backoffMs * 2 ** retries);
+        break;
+    }
+  }
+}
+
+/** `request` with the browser's shared config. */
+export function gql<T>(
+  query: QueryText,
+  variables: Record<string, unknown>,
+  isData: DataCheck<T>,
+  options?: RequestOptions,
+): Promise<T> {
+  return request(cfg, query, variables, isData, options);
+}
+
+/** The check of `Tether.query()` and the server's `query()`, whose callers read `data` themselves. */
+export const hasData = (data: unknown): data is object => typeof data === 'object' && data !== null;
+
+/** `Tether.query()`: the caller's own query text decides the shape of `data`, and the caller's `T` states it. */
+export function query<T>(
+  text: QueryText,
+  variables: Record<string, unknown> = {},
+  options?: RequestOptions,
+): Promise<T> {
+  return gql(text, variables, hasData, options) as Promise<T>;
+}
+
+/**
+ * @param payload A mutation's payload.
+ * @param name The mutation, for the error message.
+ * @throws {TetherError} `ERROR` on an empty payload or on user errors (in `userErrors`).
+ */
+export function unwrap<Payload extends { userErrors?: readonly UserError[] | null }>(
+  payload: Payload | null | undefined,
+  name: string,
+): Payload {
+  if (!payload) throw new TetherError(`${name}: empty response`);
+  const userErrors = payload.userErrors ?? [];
+  if (userErrors.length) {
+    throw new TetherError(userErrors.map((error) => error.message).join(' | '), { userErrors });
+  }
+  return payload;
+}

package/src/{collection.js → collection.ts}

@@ -3,8 +3,8 @@
  * first child of [tether-list] is the card template; every card becomes a product scope, so all product attributes
  * work inside cards (including quick-add with a subscription toggle).
  */
-import { reportError } from './config.js';
-import { TetherError } from './client.js';
+import { reportError } from './config.ts';
+import { TetherError } from './client.ts';
 import {
   attr,
   sel,
@@ -19,47 +19,42 @@ import {
   notifyLayoutChanged,
   busy,
   show,
-} from './dom.js';
-import { getProducts, getRecommendations } from './loader.js';
-import { setScopeStatus, isNotFound, resolveProductKey } from './status.js';
-/** @import { Product } from './fragments.js' */
-/** @import { Collection, PageInfo, ProductQuery } from './loader.js' */
+} from './dom.ts';
+import { getProducts, getRecommendations } from './loader.ts';
+import { setScopeStatus, isNotFound, resolveProductKey } from './status.ts';
+import type { Product } from './fragments.ts';
+import type { Collection, PageInfo, ProductQuery } from './loader.ts';
 
 /** `tether-products="url:q"`: the search in the page's `?q=`, for a results page on a static site. */
 const URL_QUERY_SOURCE = 'url:';
 
 export const listSelector = () => `${sel('collection')},${sel('products')},${sel('recommendations')}`;
 
-/**
- * @param {EventTarget | null} target
- * @returns {target is Element}
- */
-const isElement = (target) => target instanceof window.Element;
+const isElement = (target: EventTarget | null): target is Element => target instanceof window.Element;
 
 /**
- * @param {string | null} raw A `tether-limit`.
- * @returns {number | undefined} The limit; `undefined` for none, zero or not a number.
+ * @param raw A `tether-limit`.
+ * @returns The limit; `undefined` for none, zero or not a number.
  */
-const toLimit = (raw) => parseInt(raw ?? '', 10) || undefined;
+const toLimit = (raw: string | null): number | undefined => parseInt(raw ?? '', 10) || undefined;
 
 /**
- * @param {string | null} raw A `tether-intent`.
- * @returns {'RELATED' | 'COMPLEMENTARY'} Shopify's recommendation intent, `RELATED` unless `COMPLEMENTARY` is written.
+ * @param raw A `tether-intent`.
+ * @returns Shopify's recommendation intent, `RELATED` unless `COMPLEMENTARY` is written.
  */
-const toIntent = (raw) => (raw === 'COMPLEMENTARY' ? 'COMPLEMENTARY' : 'RELATED');
+const toIntent = (raw: string | null): 'RELATED' | 'COMPLEMENTARY' =>
+  raw === 'COMPLEMENTARY' ? 'COMPLEMENTARY' : 'RELATED';
 
 export class ListScope {
-  /** @param {HTMLElement} root */
-  constructor(root) {
+  readonly root: HTMLElement;
+  products: Product[] = [];
+  pageInfo: PageInfo | null = null;
+  collection: Collection | null = null;
+  /** Counts loads, so only the latest one renders. */
+  loadToken = 0;
+
+  constructor(root: HTMLElement) {
     this.root = root;
-    /** @type {Product[]} */
-    this.products = [];
-    /** @type {PageInfo | null} */
-    this.pageInfo = null;
-    /** @type {Collection | null} */
-    this.collection = null;
-    /** Counts loads, so only the latest one renders. */
-    this.loadToken = 0;
     setScopeStatus(root, 'loading');
     root.addEventListener('click', (event) => {
       if (!isElement(event.target)) return;
@@ -70,16 +65,14 @@ export class ListScope {
     });
   }
 
-  /** @param {string} selector */
-  $(selector) {
+  $(selector: string) {
     return scoped(this.root, selector, listSelector());
   }
 
-  /** @returns {ProductQuery} The collection or search query of the list's attributes. */
-  options() {
+  /** The collection or search query of the list's attributes. */
+  options(): ProductQuery {
     const { root } = this;
-    /** @type {ProductQuery} */
-    const query = { reverse: get(root, 'reverse') === 'true' };
+    const query: ProductQuery = { reverse: get(root, 'reverse') === 'true' };
     const first = toLimit(get(root, 'limit'));
     if (first) query.first = first;
     const sortKey = get(root, 'sort');
@@ -99,10 +92,9 @@ export class ListScope {
    * The product of a recommendations list: a handle, `url:…` (one dynamic product page), or empty inside a product
    * scope for that product.
    *
-   * @returns {Promise<Product[]>}
    * @throws {TetherError} `NOT_FOUND` when there is no product to recommend for.
    */
-  async loadRecommendations() {
+  async loadRecommendations(): Promise<Product[]> {
     let { key } = resolveProductKey(this.root, window.location, 'recommendations');
     const scope = this.root.closest(sel('product'));
     if (!key && scope) ({ key } = resolveProductKey(scope));
@@ -110,8 +102,8 @@ export class ListScope {
     return getRecommendations(key, toIntent(get(this.root, 'intent')));
   }
 
-  /** @param {boolean} [more] Appends the next page instead of replacing the products. */
-  async load(more = false) {
+  /** @param more Appends the next page instead of replacing the products. */
+  async load(more = false): Promise<void> {
     this.loadToken += 1;
     const token = this.loadToken;
     const stale = () => token !== this.loadToken;