@occluze/tether 0.4.0 → 0.6.0

package/src/client.js

@@ -15,8 +15,8 @@ export class TetherError extends Error {
   }
 }
 
-export function endpoint() {
-  return `https://${cfg.domain}/api/${cfg.apiVersion}/graphql.json`;
+export function endpoint(conf = cfg) {
+  return `https://${conf.domain}/api/${conf.apiVersion}/graphql.json`;
 }
 
 /**
@@ -31,42 +31,51 @@ export function withContext(query, ctx = cfg) {
   if (ctx.language) args.push(`language: ${String(ctx.language).toUpperCase().replace('-', '_')}`);
   if (!args.length || /@inContext/.test(query)) return query;
 
-  return query.replace(
-    /^(\s*(?:query|mutation)\s+\w+\s*(?:\([^)]*\))?)/,
-    `$1 @inContext(${args.join(', ')})`,
-  );
+  const tag = `@inContext(${args.join(', ')})`;
+  // Named (query Name($x: T)), anonymous (query { … }) and shorthand ({ … }) queries.
+  if (/^\s*\{/.test(query)) return `query ${tag} ${query.trimStart()}`;
+  return query.replace(/^(\s*(?:query|mutation)(?:\s+\w+)?\s*(?:\([^)]*\))?)/, `$1 ${tag}`);
 }
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-export async function gql(query, variables = {}, { context = true } = {}) {
-  if (!cfg.domain || !cfg.token) {
+/**
+ * One Storefront API request with retries, for any config object (the browser's shared config,
+ * or the server module's own). gql() below is the browser version.
+ */
+export async function request(conf, query, variables = {}, { context = true } = {}) {
+  if (!conf.domain || !conf.token) {
     throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
   }
 
-  const body = JSON.stringify({ query: context ? withContext(query) : query, variables });
+  // Shopify caches the response of an identical query text (prices included, for hours after a
+  // change). A time bucket in a comment keeps answers at most maxAge seconds old (default 60).
+  let text = context ? withContext(query, conf) : query;
+  const age = conf.maxAge ?? 60;
+  if (age > 0 && !/^\s*mutation\b/.test(text)) text += ` #${Math.floor(Date.now() / (age * 1000))}`;
+  const body = JSON.stringify({ query: text, variables });
   let attempt = 0;
 
   for (;;) {
     let res;
     try {
-      res = await fetch(endpoint(), {
+      res = await (conf.fetch || fetch)(endpoint(conf), {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          'X-Shopify-Storefront-Access-Token': cfg.token,
+          'X-Shopify-Storefront-Access-Token': conf.token,
         },
         body,
       });
     } catch (err) {
-      if (attempt++ < cfg.retries) { await sleep(300 * 2 ** attempt); continue; }
+      if (attempt++ < conf.retries) { await sleep(300 * 2 ** attempt); continue; }
       throw new TetherError(`Network error: ${err.message}`, { code: 'NETWORK' });
     }
 
     if (res.status === 430) throw new TetherError('Shopify security rejection (430)', { status: 430 });
 
     const retryable = res.status === 429 || res.status >= 500;
-    if (retryable && attempt++ < cfg.retries) {
+    if (retryable && attempt++ < conf.retries) {
       log('retry', res.status, attempt);
       await sleep(300 * 2 ** attempt);
       continue;
@@ -82,10 +91,14 @@ export async function gql(query, variables = {}, { context = true } = {}) {
       const inventoryDenied = json.errors.some((e) => /quantityAvailable/.test(e.message || ''));
       if (inventoryDenied && /\bquantityAvailable\b/.test(body)) {
         log('no inventory permission, retrying without quantityAvailable');
-        return gql(query.replace(/\bquantityAvailable\b/g, ''), variables, { context });
+        return request(conf, query.replace(/\bquantityAvailable\b/g, ''), variables, { context });
+      }
+      // An older apiVersion without cart warnings (before 2024-07): retry without them.
+      if (json.errors.some((e) => /'warnings'/.test(e.message || '')) && /warnings \{ code message target \}/.test(query)) {
+        return request(conf, query.replace(/ warnings \{ code message target \}/g, ''), variables, { context });
       }
       const throttled = json.errors.some((e) => e.extensions?.code === 'THROTTLED');
-      if (throttled && attempt++ < cfg.retries) { await sleep(500 * 2 ** attempt); continue; }
+      if (throttled && attempt++ < conf.retries) { await sleep(500 * 2 ** attempt); continue; }
       throw new TetherError(json.errors.map((e) => e.message).join(' | '), {
         status: res.status, errors: json.errors,
       });
@@ -96,6 +109,8 @@ export async function gql(query, variables = {}, { context = true } = {}) {
   }
 }
 
+export const gql = (query, variables, opts) => request(cfg, query, variables, opts);
+
 /** Throws on mutation userErrors, returns the payload otherwise. */
 export function unwrap(payload, name) {
   if (!payload) throw new TetherError(`${name}: empty response`);

package/src/collection.js

@@ -5,9 +5,10 @@
  * quick-add with a subscription toggle).
  */
 import { reportError } from './config.js';
-import { attr, sel, get, has, scoped, emit, setText, setImage, repeat, notifyLayoutChanged, busy } from './dom.js';
-import { getProducts, getRecommendations, getProduct } from './loader.js';
-import { setScopeStatus, isNotFound } from './status.js';
+import { TetherError } from './client.js';
+import { attr, sel, get, has, scoped, emit, setText, setImage, repeat, notifyLayoutChanged, busy, show } from './dom.js';
+import { getProducts, getRecommendations } from './loader.js';
+import { setScopeStatus, isNotFound, resolveProductKey } from './status.js';
 
 export const listSelector = () => `${sel('collection')},${sel('products')},${sel('recommendations')}`;
 
@@ -46,9 +47,12 @@ export class ListScope {
     const stale = () => token !== this.loadToken;
     try {
       if (has(this.root, 'recommendations')) {
-        const key = get(this.root, 'recommendations');
-        const base = await getProduct(key);
-        const recs = await getRecommendations(base.id, get(this.root, 'intent') || 'RELATED');
+        // A handle, url:handle (one dynamic product page), or empty inside a product: that product.
+        let { key } = resolveProductKey(this.root, window.location, 'recommendations');
+        const scope = this.root.closest(sel('product'));
+        if (!key && scope) ({ key } = resolveProductKey(scope));
+        if (!key) throw new TetherError('No product for recommendations', { code: 'NOT_FOUND' });
+        const recs = await getRecommendations(key, get(this.root, 'intent') || 'RELATED');
         if (stale()) return;
         const limit = parseInt(get(this.root, 'limit') || '', 10);
         this.products = limit ? recs.slice(0, limit) : recs;
@@ -66,7 +70,8 @@ export class ListScope {
       if (stale()) return;
       // Keep what's already rendered on a failed "load more"; otherwise show the error state.
       if (!more) setScopeStatus(this.root, isNotFound(err) ? 'not-found' : 'error', err);
-      reportError(err, 'list load failed');
+      // A missing product for recommendations is a page detail, not an error to report.
+      if (!(isNotFound(err) && has(this.root, 'recommendations'))) reportError(err, 'list load failed');
       emit('error', { error: err, context: 'list' }, this.root);
     }
   }
@@ -95,10 +100,10 @@ export class ListScope {
     const empty = this.products.length === 0;
     this.$(sel('show')).forEach((el) => {
       const k = get(el, 'show');
-      if (k === 'list-empty') el.style.display = empty ? '' : 'none';
-      if (k === 'list-filled') el.style.display = empty ? 'none' : '';
+      if (k === 'list-empty') show(el, empty);
+      if (k === 'list-filled') show(el, !empty);
     });
-    this.$(sel('load-more')).forEach((el) => { el.style.display = this.pageInfo?.hasNextPage ? '' : 'none'; });
+    this.$(sel('load-more')).forEach((el) => show(el, Boolean(this.pageInfo?.hasNextPage)));
     notifyLayoutChanged('list');
   }
 }

package/src/config.js

@@ -25,6 +25,7 @@ export const DEFAULTS = {
   sellingPlansFirst: 25,
   collectionFirst: 24,
   retries: 2,
+  revalidate: true,           // products from the server (tether/server hydrate()): refresh once in the background
 
   // Cart
   storageKey: null,           // defaults to `tether:cart:<domain>`
@@ -35,10 +36,14 @@ export const DEFAULTS = {
 
   // Subscriptions
   defaultPurchase: 'one-time', // 'one-time' | 'subscription'
+  variantUrl: false, // true: ?variant= follows the visitor's choice on the main product (shareable links)
+  maxAge: 60, // seconds a Shopify answer may be cached (0 = Shopify's own caching, can be hours)
+  lowStock: 5, // tether-show="low-stock" at this many or fewer (needs inventory access)
 
   // Mounting
   autoMount: true,            // mount document on DOMContentLoaded
   observe: false,             // auto-mount nodes added later (CMS load-more, filters)
+  astro: true,                // mount on Astro View Transitions (astro:page-load); false if you do it yourself
   partsUrl: null,             // folder of tether.markets/diagnose(.min).js for the <script> build (default: next to it)
 
   // Formatting

package/src/diagnose.js

@@ -63,10 +63,10 @@ export function checkMarkup(root = document) {
   });
 
   const known = new Set([
-    'in-stock', 'out-of-stock', 'backorder', 'low-stock', 'on-sale', 'not-on-sale', 'has-variants', 'single-variant',
+    'in-stock', 'out-of-stock', 'backorder', 'low-stock', 'plenty-in-stock', 'on-sale', 'not-on-sale', 'has-variants', 'single-variant',
     'subscription-available', 'subscription-unavailable', 'subscription-only', 'one-time-available',
     'subscription-selected', 'one-time-selected', 'has-savings', 'loading', 'ready', 'error', 'not-found',
-    'cart-empty', 'cart-filled', 'cart-has-subscription', 'cart-no-subscription', 'cart-has-discount', 'cart-error',
+    'cart-empty', 'cart-filled', 'cart-has-subscription', 'cart-no-subscription', 'cart-has-discount', 'cart-error', 'cart-warning',
     'list-empty', 'list-filled',
   ]);
   qsa(root, sel('show')).forEach((el) => {
@@ -107,7 +107,8 @@ export async function diagnose({ root = document, silent = false, version, now =
       autoMount: cfg.autoMount, observe: cfg.observe, onError: typeof cfg.onError === 'function',
     },
     apiVersion: apiVersionStatus(cfg.apiVersion, now),
-    market: cfg.markets?.detect ? detectMarket(cfg.markets) : null,
+    // The market in use (a visitor's choice included), plus what detection would pick.
+    market: { country: cfg.country || null, language: cfg.language || null, locale: cfg.locale || null, detected: cfg.markets?.detect ? detectMarket(cfg.markets) : null },
     reachable: false,
     shop: null,
     latencyMs: null,
@@ -141,6 +142,14 @@ export async function diagnose({ root = document, silent = false, version, now =
           const plans = allPlans(p);
           report.products.push({ key: keys[i], handle: p.handle, title: p.title, plans: plans.length, requiresSellingPlan: p.requiresSellingPlan });
           plans.forEach((pl) => report.sellingPlans.push({ product: p.handle, group: pl.group?.name, plan: pl.name, id: pl.id }));
+          // Options a visitor can't choose on this page (they get the first available variant's value).
+          qsa(root, sel('product')).filter((el) => resolveProductKey(el).key === keys[i] && el.querySelector(sel('add-to-cart'))).forEach((el) => {
+            const shown = new Set(qsa(el, `${sel('option-list')},select${sel('option')}`).map((x) => get(x, 'option-list') || get(x, 'option')));
+            if (!shown.size && qsa(el, `select${sel('variant-select')}`).length) return;
+            (p.options || []).filter((o) => o.optionValues.length > 1 && !shown.has(o.name)).forEach((o) => {
+              report.problems.push({ level: 'warn', message: `Product "${p.handle}": option "${o.name}" (${o.optionValues.length} values) has no tether-option-list, so visitors can't choose it.` });
+            });
+          });
         } else {
           report.products.push({ key: keys[i], error: r.reason?.message });
           report.problems.push({ level: 'error', message: `Product "${keys[i]}": ${r.reason?.message}. Is it published to the Headless channel?` });

package/src/dom.js

@@ -33,6 +33,12 @@ export function emit(name, detail, target = document) {
   target.dispatchEvent(new CustomEvent(`${cfg.prefix}:${name}`, { detail, bubbles: true }));
 }
 
+/** 30 -> "30%" (en, nl) or "30 %" (de, fr), in the configured locale. */
+export function formatPercent(n, locale = cfg.locale) {
+  if (!n) return '';
+  try { return new Intl.NumberFormat(locale || undefined, { style: 'percent', maximumFractionDigits: 0 }).format(n / 100); } catch { return `${n}%`; }
+}
+
 export function formatMoney(money) {
   if (!money) return '';
   if (typeof cfg.formatMoney === 'function') return cfg.formatMoney(money, cfg.locale);
@@ -53,24 +59,37 @@ export function formatDate(iso) {
 }
 
 /** Shopify CDN resize via max-width / max-height / crop attributes on the element. */
-export function cdnUrl(url, el) {
-  if (!url || !el) return url;
-  const w = el.getAttribute('max-width');
-  const h = el.getAttribute('max-height');
-  const crop = el.getAttribute('crop');
-  if (!w && !h) return url;
+/**
+ * Shopify CDN image at a size: imageUrl(url, { width: 800 }). Use the same width as the element's
+ * max-width attribute, so the browser script keeps the image instead of loading it again.
+ */
+export function imageUrl(url, { width, height, crop } = {}) {
+  if (!url) return url;
   try {
     const u = new URL(url);
-    if (w) u.searchParams.set('width', w);
-    if (h) u.searchParams.set('height', h);
+    if (width) u.searchParams.set('width', String(width));
+    if (height) u.searchParams.set('height', String(height));
     if (crop) u.searchParams.set('crop', crop);
     return u.toString();
   } catch { return url; }
 }
 
+export function cdnUrl(url, el) {
+  if (!url || !el) return url;
+  const g = (k) => el.getAttribute(k);
+  return imageUrl(url, { width: g('max-width'), height: g('max-height'), crop: g('max-width') || g('max-height') ? g('crop') : null });
+}
+
+/** Same image, whatever size parameters: the server-rendered one is kept (no second download). */
+export const sameImage = (a, b) => Boolean(a && b) && a.split('?')[0] === b.split('?')[0];
+
 export function setImage(el, url, alt) {
   if (!url) return;
   const src = cdnUrl(url, el);
+  if (el.tagName === 'IMG' && sameImage(el.getAttribute('src'), src)) {
+    if (alt != null && !el.getAttribute('alt')) el.setAttribute('alt', alt);
+    return;
+  }
   if (el.tagName === 'IMG') {
     el.removeAttribute('srcset');
     el.removeAttribute('sizes');
@@ -104,14 +123,24 @@ export function setTextTracked(el, v) {
 export function show(el, visible) {
   const k = 'tetherPrevDisplay';
   if (visible) {
+    if (el.dataset.tetherShown !== undefined) return; // already visible, nothing to check
+    el.dataset.tetherShown = '';
+    el.removeAttribute('hidden');
     if (el.dataset[k] !== undefined) {
       el.style.display = el.dataset[k];
       delete el.dataset[k];
     } else if (el.style.display === 'none') {
       el.style.display = '';
     }
+    // Hidden before the script ran (a class, an inline display:none, a hidden attribute): show it
+    // as block or the value of tether-display.
+    if (typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
+      el.style.display = el.getAttribute(`${cfg.prefix}-display`) || 'block';
+    }
   } else {
-    if (el.dataset[k] === undefined) el.dataset[k] = el.style.display || '';
+    delete el.dataset.tetherShown;
+    // Remember a real display value to restore, never 'none'.
+    if (el.dataset[k] === undefined && el.style.display !== 'none') el.dataset[k] = el.style.display || '';
     el.style.display = 'none';
   }
 }
@@ -145,7 +174,7 @@ function template(container) {
 /** Rebuilds the list on every render. Fine for images, tags, options. */
 export function repeat(container, items, render) {
   const tpl = template(container);
-  if (!tpl) { warn('repeater without a template child', container); return; }
+  if (!tpl) { if (items.length) warn('repeater without a template child', container); return; }
   container.innerHTML = '';
   items.forEach((item, i) => {
     const node = tpl.cloneNode(true);

package/src/extras.js

@@ -0,0 +1,63 @@
+/**
+ * Optional part with features that load when first needed: bundles (on the first "add set"
+ * click), tab sync (on the first change in another tab) and shareable variant links (on the
+ * first variant change, with variantUrl or tether-variant-url).
+ */
+import { cfg, warn, reportError } from './config.js';
+import { sel, get, has, qsa, emit, parseJSONAttr, toAttributes } from './dom.js';
+import { scopes } from './product.js';
+import { Cart } from './cart.js';
+
+/**
+ * [tether-group] + [tether-group-add]: adds every product scope inside the group in one request.
+ * Bundles, build-a-box, "complete the set". Lines get attribute _group (and tether-line-attributes).
+ */
+export async function addGroup(btn) {
+  const group = btn.closest(sel('group'));
+  if (!group) return null;
+  const name = get(group, 'group');
+  const extra = toAttributes(parseJSONAttr(group, 'line-attributes'));
+  const groupAttrs = name ? [{ key: '_group', value: name }, ...extra] : extra;
+  const lines = qsa(group, sel('product'))
+    .map((el) => scopes.get(el))
+    .filter((s) => s && s.variant?.availableForSale && s.quantity > 0)
+    .map((s) => {
+      const l = s.getLine();
+      l.attributes = [...(l.attributes || []), ...groupAttrs];
+      return l;
+    });
+  if (!lines.length) { warn('group-add: nothing selected'); return null; }
+  try {
+    const cart = await Cart.add(lines);
+    emit('group-added', { group: name, lines }, group);
+    return cart;
+  } catch (err) { reportError(err, 'group add'); return null; }
+}
+
+/** Another tab changed the cart (reload it here) or the visitor's market (follow it). */
+export function onStorage(e) {
+  if (e.key === cfg.storageKey || e.key === `${cfg.storageKey}:seen`) Cart.init();
+  else if (e.key === `${cfg.prefix}:market:${cfg.domain}` && e.newValue) {
+    try {
+      const m = JSON.parse(e.newValue);
+      if (m?.country) window.Tether?.setCountry(m.country, { language: m.language ?? null, locale: m.locale, remember: false }).catch(() => {});
+    } catch { /* ignore */ }
+  }
+}
+
+const urlKeys = new WeakMap(); // scope root -> last variant|plan, so the first render doesn't write
+
+/** ?variant= (and selling_plan=) follow the visitor's choice. */
+export function writeVariantUrl(root, { variant, sellingPlanId }) {
+  const key = `${variant.id}|${sellingPlanId || ''}`;
+  const before = urlKeys.get(root);
+  urlKeys.set(root, key);
+  if (!before || before === key) return;
+  if (!has(root, 'variant-url') && !(cfg.variantUrl && document.querySelector(sel('product')) === root)) return;
+  try {
+    const u = new URL(window.location.href);
+    u.searchParams.set('variant', variant.id.split('/').pop());
+    if (sellingPlanId) u.searchParams.set('selling_plan', sellingPlanId.split('/').pop()); else u.searchParams.delete('selling_plan');
+    window.history.replaceState(window.history.state, '', u);
+  } catch { /* ignore */ }
+}

package/src/fragments.js

@@ -7,8 +7,8 @@ import { cfg } from './config.js';
 const MONEY = 'amount currencyCode';
 const IMAGE = 'url altText width height';
 
-export function metafieldIdentifiers() {
-  return (cfg.metafields || []).map((m) => {
+export function metafieldIdentifiers(o = cfg) {
+  return (o.metafields || []).map((m) => {
     if (typeof m === 'string') {
       const i = m.indexOf('.');
       return { namespace: m.slice(0, i), key: m.slice(i + 1) };
@@ -17,8 +17,8 @@ export function metafieldIdentifiers() {
   }).filter((m) => m.namespace && m.key);
 }
 
-function metafieldsField() {
-  const ids = metafieldIdentifiers();
+function metafieldsField(o = cfg) {
+  const ids = metafieldIdentifiers(o);
   if (!ids.length) return '';
   const list = ids
     .map((m) => `{namespace: ${JSON.stringify(m.namespace)}, key: ${JSON.stringify(m.key)}}`)
@@ -53,26 +53,27 @@ export const ALLOCATION_FIELDS = `
     unitPrice { ${MONEY} }
   }`;
 
-export function productFragment() {
+/** The product fields Tether renders. `o` = config (counts, metafields); the server module passes its own. */
+export function productFragment(o = cfg) {
   return `
 fragment TetherProduct on Product {
   id handle title description descriptionHtml productType vendor tags
   availableForSale publishedAt onlineStoreUrl requiresSellingPlan
   seo { title description }
   featuredImage { ${IMAGE} }
-  images(first: ${cfg.imagesFirst}) { nodes { ${IMAGE} } }
+  images(first: ${o.imagesFirst}) { nodes { ${IMAGE} } }
   options { name optionValues { name swatch { color image { previewImage { ${IMAGE} } } } } }
   priceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
   compareAtPriceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
-  ${metafieldsField()}
-  sellingPlanGroups(first: ${cfg.sellingPlanGroupsFirst}) {
+  ${metafieldsField(o)}
+  sellingPlanGroups(first: ${o.sellingPlanGroupsFirst}) {
     nodes {
       name appName
       options { name values }
-      sellingPlans(first: ${cfg.sellingPlansFirst}) { nodes { ${SELLING_PLAN_FIELDS} } }
+      sellingPlans(first: ${o.sellingPlansFirst}) { nodes { ${SELLING_PLAN_FIELDS} } }
     }
   }
-  variants(first: ${cfg.variantsFirst}) {
+  variants(first: ${o.variantsFirst}) {
     nodes {
       id title availableForSale currentlyNotInStock quantityAvailable sku barcode
       selectedOptions { name value }
@@ -80,7 +81,7 @@ fragment TetherProduct on Product {
       price { ${MONEY} }
       compareAtPrice { ${MONEY} }
       unitPrice { ${MONEY} }
-      sellingPlanAllocations(first: ${cfg.sellingPlansFirst}) { nodes { ${ALLOCATION_FIELDS} } }
+      sellingPlanAllocations(first: ${o.sellingPlansFirst}) { nodes { ${ALLOCATION_FIELDS} } }
     }
   }
 }`;
@@ -116,7 +117,7 @@ fragment TetherCart on Cart {
       }
       merchandise {
         ... on ProductVariant {
-          id title sku availableForSale requiresShipping
+          id title sku availableForSale requiresShipping quantityAvailable
           image { ${IMAGE} }
           price { ${MONEY} }
           compareAtPrice { ${MONEY} }