@occluze/tether 0.6.8 → 0.7.0

package/src/{api-version.js → api-version.ts}

@@ -1,8 +1,11 @@
 /**
  * Shopify API versions are quarterly (YYYY-01, -04, -07, -10) and supported for 12 months. Tether pins a dated version
- * and never targets `unstable` (it changes without notice). Used by the diagnose part and the release scripts.
+ * and never targets `unstable` (it changes without notice). Used by the config, the diagnose part and the release
+ * scripts.
  */
 
+import type { ApiVersion } from '../server/src/shared/api-versions.ts';
+
 const QUARTERLY_VERSION = /^(\d{4})-(01|04|07|10)$/;
 const MONTHS_PER_QUARTER = 3;
 const QUARTERS_PER_YEAR = 4;
@@ -11,54 +14,45 @@ const MONTHS_SUPPORTED = 12;
 const UPGRADE_WARNING_MONTHS = 3;
 const AVERAGE_MONTH_MS = 30.44 * 24 * 3600 * 1000;
 
-/**
- * @typedef {object} ApiVersionStatus
- * @property {string} version
- * @property {boolean} ok Released and still supported.
- * @property {string} note What to do about it, for people.
- * @property {number} [monthsLeft] Months of support left, rounded; negative once support ended.
- * @property {string} [next] The version after this one.
- */
+export interface ApiVersionStatus {
+  version: string;
+  /** Released and still supported. */
+  ok: boolean;
+  /** What to do about it, for people. */
+  note: string;
+  /** Months of support left, rounded; negative once support ended. */
+  monthsLeft?: number;
+  /** The version after this one. */
+  next?: string;
+}
 
-/**
- * @param {unknown} version
- * @returns {{ year: number, month: number } | null}
- */
-function parseVersion(version) {
+function parseVersion(version: unknown): { year: number; month: number } | null {
   const match = QUARTERLY_VERSION.exec(typeof version === 'string' ? version : '');
   if (!match) return null;
   return { year: Number(match[1]), month: Number(match[2]) };
 }
 
-/**
- * @param {number} year
- * @param {number} month 1 to 12.
- */
-const formatVersion = (year, month) => `${year}-${String(month).padStart(2, '0')}`;
+/** @returns True for a dated version such as `2026-07`. */
+export const isQuarterlyVersion = (version: unknown): version is ApiVersion => parseVersion(version) !== null;
+
+/** @param month 1 to 12. */
+const formatVersion = (year: number, month: number) => `${year}-${String(month).padStart(2, '0')}`;
 
 /**
  * `'2026-07'` → `'2026-10'`, `'2026-10'` → `'2027-01'`.
  *
- * @param {string} version
- * @param {number} [steps] Quarters ahead.
- * @returns {string}
+ * @param steps Quarters ahead.
  * @throws {Error} When `version` isn't a quarterly version.
  */
-export function nextApiVersion(version, steps = 1) {
+export function nextApiVersion(version: string, steps = 1): string {
   const parsed = parseVersion(version);
   if (!parsed) throw new Error(`not a quarterly Shopify API version: ${version}`);
   const quarter = parsed.year * QUARTERS_PER_YEAR + (parsed.month - 1) / MONTHS_PER_QUARTER + steps;
   return formatVersion(Math.floor(quarter / QUARTERS_PER_YEAR), (quarter % QUARTERS_PER_YEAR) * MONTHS_PER_QUARTER + 1);
 }
 
-/**
- * The support window of `version`, relative to `now`.
- *
- * @param {string} version
- * @param {Date} [now]
- * @returns {ApiVersionStatus}
- */
-export function apiVersionStatus(version, now = new Date()) {
+/** The support window of `version`, relative to `now`. */
+export function apiVersionStatus(version: string, now = new Date()): ApiVersionStatus {
   if (version === 'unstable') {
     return { version, ok: false, note: '"unstable" changes without notice: pin a dated version such as 2026-07' };
   }

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

@@ -10,36 +10,66 @@
  *   PUBLIC_SHOPIFY_DOMAIN=your-store.myshopify.com
  *   PUBLIC_SHOPIFY_STOREFRONT_TOKEN=your-public-storefront-token
  *
- * Options are Tether's config (domain and token override .env). Functions (onError, formatMoney, hooks) can't be
+ * Options are Tether's config (domain and token override .env), and may be the object createStorefront() is given too:
+ * its own options (siteUrl, pageSize) are left out of the page. Functions (onError, formatMoney, hooks) can't be
  * passed here: set them in window.TETHER_CONFIG in your layout, it is merged in. View Transitions (<ClientRouter />)
  * work without extra code. In dev, changes to src/shop.config.js restart the dev server (other files:
  * tether({ ..., watch: ['my/config.js'] })). Runs in Node, inside Astro's config step.
  */
-import { isSecretShopifyToken, STORE_ENV_NAMES } from './shopify-values.js';
+import { DEFAULTS } from './config.ts';
+import type { TetherOptions } from './config.ts';
+import type { StorefrontOptions } from './server.ts';
+import { isSecretShopifyToken, STORE_ENV_NAMES } from './shopify-values.ts';
+import { messageOf } from '../server/src/shared/error-message.ts';
 
-/**
- * Astro isn't a dependency, so the parts of its integration API this file uses are described here.
- *
- * @typedef {{ warn: (message: string) => void }} AstroLogger
- * @typedef {(options: { context: 'client', access: 'public', optional: boolean }) => unknown} EnvStringField
- * @typedef {object} AstroConfigSetup The argument of Astro's `astro:config:setup` hook.
- * @property {(stage: 'head-inline' | 'page', content: string) => void} injectScript
- * @property {string} command `dev`, `build`, `preview` or `sync`.
- * @property {{ root?: URL }} config
- * @property {AstroLogger} logger
- * @property {(path: string) => void} [addWatchFile]
- * @property {(config: { env: { schema: Record<string, unknown> } }) => void} [updateConfig]
- */
+// Astro isn't a dependency, so the parts of its integration API this file uses are described here.
+interface AstroLogger {
+  warn: (message: string) => void;
+}
+type EnvStringField = (options: { context: 'client'; access: 'public'; optional: boolean }) => unknown;
+/** The argument of Astro's `astro:config:setup` hook. */
+interface AstroConfigSetup {
+  injectScript: (stage: 'head-inline' | 'page', content: string) => void;
+  /** `dev`, `build`, `preview` or `sync`. */
+  command: string;
+  config: { root?: URL };
+  logger: AstroLogger;
+  addWatchFile?: (path: string) => void;
+  /** Takes a partial Astro config. A method, so that Astro's own `DeepPartial<AstroConfig>` parameter fits. */
+  updateConfig?(config: { env?: { schema?: Record<string, unknown> } }): unknown;
+}
 
-/**
- * @typedef {object} TetherAstroOptions Tether's serializable config, plus the integration's own options.
- * @property {boolean} [inject] Add the Tether script to every page (default true).
- * @property {string[] | null} [watch] Files that restart the dev server when they change.
- */
-/** @typedef {{ domain?: unknown, token?: unknown, [option: string]: unknown }} PageConfig */
-/** @typedef {Record<string, string | undefined>} Env */
+/** The config options a page can be handed as JSON: all but the functions. */
+type SerializableOptions = {
+  [
+    Key in keyof TetherOptions as Exclude<TetherOptions[Key], null | undefined> extends (...args: never[]) => unknown
+      ? never
+      : Key
+  ]?: TetherOptions[Key];
+};
+
+/** `createStorefront()`'s own options that a config shared with it may hold, which the page leaves out. */
+type ServerOnlyOptions = Pick<StorefrontOptions, 'siteUrl' | 'pageSize'>;
+
+/** Tether's serializable config and the storefront's own options, plus the integration's own options. */
+interface TetherAstroOptions extends SerializableOptions, ServerOnlyOptions {
+  /** Add the Tether script to every page (default true). */
+  inject?: boolean;
+  /** Files that restart the dev server when they change. */
+  watch?: string[] | null;
+}
+interface PageConfig {
+  domain?: unknown;
+  token?: unknown;
+  [option: string]: unknown;
+}
+type Env = Record<string, string | undefined>;
+
+export type { TetherAstroOptions, AstroConfigSetup };
 
 const DEFAULT_WATCH = ['src/shop.config.js', 'src/shop.config.mjs', 'src/shop.config.ts'];
+/** The keys of `ServerOnlyOptions`: the browser has no use for them. */
+const SERVER_OPTIONS = new Set(['siteUrl', 'pageSize']);
 /**
  * Astro is an optional peer dependency. A variable specifier keeps both tsc and the bundler from resolving it.
  */
@@ -48,12 +78,8 @@ const ENV_LINE = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*?)\s*$/;
 /** A quoted value; a `#` comment may follow the closing quote. */
 const QUOTED_VALUE = /^(["'])(.*?)\1/;
 
-/**
- * @param {string} command
- * @param {readonly string[]} [argv]
- * @returns {string} The mode Astro runs in: `--mode`, else development for dev and production for everything else.
- */
-function modeOf(command, argv = process.argv) {
+/** @returns The mode Astro runs in: `--mode`, else development for dev and production for everything else. */
+function modeOf(command: string, argv: readonly string[] = process.argv): string {
   const defaultMode = command === 'dev' ? 'development' : 'production';
   const index = argv.findIndex((arg) => arg === '--mode' || arg.startsWith('--mode='));
   if (index < 0) return defaultMode;
@@ -62,17 +88,11 @@ function modeOf(command, argv = process.argv) {
   return mode ?? defaultMode;
 }
 
-/**
- * @param {unknown} error
- * @returns {boolean} True for Node's "no such file" error.
- */
-const isMissingFile = (error) => error instanceof Error && Reflect.get(error, 'code') === 'ENOENT';
+/** @returns True for Node's "no such file" error. */
+const isMissingFile = (error: unknown): boolean => error instanceof Error && 'code' in error && error.code === 'ENOENT';
 
-/**
- * @param {string} path
- * @returns {Promise<string | null>} The file's text, `null` when it doesn't exist: every .env file is optional.
- */
-async function readOptionalFile(path) {
+/** @returns The file's text, `null` when it doesn't exist: every .env file is optional. */
+async function readOptionalFile(path: string): Promise<string | null> {
   const { readFile } = await import('node:fs/promises');
   try {
     return await readFile(path, 'utf8');
@@ -83,10 +103,10 @@ async function readOptionalFile(path) {
 }
 
 /**
- * @param {string} text A .env file.
- * @param {Env} into Receives each variable; a later line wins.
+ * @param text A .env file.
+ * @param into Receives each variable; a later line wins.
  */
-function parseEnvFile(text, into) {
+function parseEnvFile(text: string, into: Env) {
   for (const line of text.split(/\r?\n/)) {
     const match = ENV_LINE.exec(line);
     if (!match || line.trim().startsWith('#')) continue;
@@ -97,15 +117,13 @@ function parseEnvFile(text, into) {
 }
 
 /**
- * @param {string} command
- * @param {string} root The project folder.
- * @returns {Promise<Env>} The .env files the way Vite reads them (later files win), with `process.env` on top.
+ * @param root The project folder.
+ * @returns The .env files the way Vite reads them (later files win), with `process.env` on top.
  */
-async function readEnv(command, root) {
+async function readEnv(command: string, root: string): Promise<Env> {
   const path = await import('node:path');
   const mode = modeOf(command);
-  /** @type {Env} */
-  const env = {};
+  const env: Env = {};
   for (const name of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
     const text = await readOptionalFile(path.join(root, name));
     if (text !== null) parseEnvFile(text, env);
@@ -117,13 +135,11 @@ async function readEnv(command, root) {
  * Fills the store's domain and token from .env when the options don't set them, and refuses a secret token: whatever
  * is read here is written into every page.
  *
- * @param {PageConfig} config Changed in place.
- * @param {Env} env
- * @param {AstroLogger} logger
+ * @param config Changed in place.
  * @throws {Error} When the token is a secret Shopify token.
  */
-function applyStoreEnv(config, env, logger) {
-  for (const key of /** @type {const} */ (['domain', 'token'])) {
+function applyStoreEnv(config: PageConfig, env: Env, logger: AstroLogger) {
+  for (const key of ['domain', 'token'] as const) {
     if (config[key]) continue;
     const name = STORE_ENV_NAMES[key].find((candidate) => env[candidate]);
     if (!name) continue;
@@ -143,12 +159,8 @@ function applyStoreEnv(config, env, logger) {
 /**
  * The options usually come from a file the Astro config imports (src/shop.config.js): the dev server restarts when it
  * changes, so the browser gets the new config too.
- *
- * @param {string} root
- * @param {readonly string[]} files
- * @param {(path: string) => void} addWatchFile
  */
-async function watchConfigFiles(root, files, addWatchFile) {
+async function watchConfigFiles(root: string, files: readonly string[], addWatchFile: (path: string) => void) {
   const { existsSync } = await import('node:fs');
   const path = await import('node:path');
   for (const file of files) {
@@ -157,50 +169,46 @@ async function watchConfigFiles(root, files, addWatchFile) {
   }
 }
 
-/**
- * @param {string} specifier
- * @returns {Promise<unknown>} The module, `null` when the package isn't installed.
- */
-async function importIfInstalled(specifier) {
+/** @returns The module, `null` when the package isn't installed. */
+async function importIfInstalled(specifier: string): Promise<unknown> {
   try {
-    /** @type {unknown} */
-    const module = await import(specifier);
+    const module: unknown = await import(specifier);
     return module;
   } catch (error) {
-    if (error instanceof Error && Reflect.get(error, 'code') === 'ERR_MODULE_NOT_FOUND') return null;
+    if (error instanceof Error && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') return null;
     throw error;
   }
 }
 
+/**
+ * @param envField `astro/config`'s `envField`, which Astro 4 doesn't have.
+ * @returns True when it has the `string` field Astro 5 documents.
+ */
+const hasStringField = (envField: unknown): envField is { string: EnvStringField } =>
+  typeof envField === 'object' && envField !== null && 'string' in envField && typeof envField.string === 'function';
+
 /**
  * Declares the store variables in `astro:env` (Astro 5+), so Astro checks them. Astro 4 has no `envField`.
- *
- * @param {NonNullable<AstroConfigSetup['updateConfig']>} updateConfig
- * @param {AstroLogger} logger
  */
-async function declareEnvSchema(updateConfig, logger) {
+async function declareEnvSchema(setup: AstroConfigSetup) {
+  if (!setup.updateConfig) return;
   const astroConfig = await importIfInstalled(ASTRO_CONFIG_MODULE);
-  /** @type {unknown} */
   const envField =
-    typeof astroConfig === 'object' && astroConfig !== null ? Reflect.get(astroConfig, 'envField') : null;
-  if (typeof envField !== 'object' || envField === null || typeof Reflect.get(envField, 'string') !== 'function')
-    return;
-  // Checked above: Astro's `envField.string`.
-  const fields = /** @type {{ string: EnvStringField }} */ (envField);
-  const field = () => fields.string({ context: 'client', access: 'public', optional: true });
+    typeof astroConfig === 'object' && astroConfig !== null && 'envField' in astroConfig ? astroConfig.envField : null;
+  if (!hasStringField(envField)) return;
+  const field = () => envField.string({ context: 'client', access: 'public', optional: true });
   try {
-    updateConfig({ env: { schema: { PUBLIC_SHOPIFY_DOMAIN: field(), PUBLIC_SHOPIFY_STOREFRONT_TOKEN: field() } } });
+    setup.updateConfig({
+      env: { schema: { PUBLIC_SHOPIFY_DOMAIN: field(), PUBLIC_SHOPIFY_STOREFRONT_TOKEN: field() } },
+    });
   } catch (error) {
     // Astro versions with `envField` but without a stable `env` option refuse it; the variables still work unchecked.
-    logger.warn(`.env variables not declared in astro:env: ${error instanceof Error ? error.message : String(error)}`);
+    setup.logger.warn(`.env variables not declared in astro:env: ${messageOf(error)}`);
   }
 }
 
-/**
- * @param {PageConfig} config Changed in place: functions can't be written into a page.
- * @param {AstroLogger} logger
- */
-function dropFunctions(config, logger) {
+/** @param config Changed in place: functions can't be written into a page. */
+function dropFunctions(config: PageConfig, logger: AstroLogger) {
   const functions = Object.keys(config).filter((key) => typeof config[key] === 'function');
   for (const key of functions) Reflect.deleteProperty(config, key);
   if (functions.length) {
@@ -210,11 +218,16 @@ function dropFunctions(config, logger) {
   }
 }
 
-/**
- * @param {AstroConfigSetup['injectScript']} injectScript
- * @param {PageConfig} config
- */
-function injectTether(injectScript, config) {
+/** @param config Changed in place: only browser options are written into the page. */
+function keepBrowserOptions(config: PageConfig, logger: AstroLogger) {
+  for (const key of Object.keys(config)) {
+    if (key in DEFAULTS) continue;
+    Reflect.deleteProperty(config, key);
+    if (!SERVER_OPTIONS.has(key)) logger.warn(`${key} is not a Tether option: left out of the page.`);
+  }
+}
+
+function injectTether(injectScript: AstroConfigSetup['injectScript'], config: PageConfig) {
   // Before any module runs: window.TETHER_CONFIG in the layout doesn't auto-start a second init.
   injectScript('head-inline', 'window.TETHER_INTEGRATION="astro";');
   injectScript(
@@ -229,31 +242,24 @@ function injectTether(injectScript, config) {
   );
 }
 
-/**
- * @param {TetherAstroOptions & PageConfig} [options]
- * @returns {{ name: string, hooks: { 'astro:config:setup': (setup: AstroConfigSetup) => Promise<void> } }}
- */
-export default function tether(options = {}) {
+export default function tether(options: TetherAstroOptions = {}): {
+  name: string;
+  hooks: { 'astro:config:setup': (setup: AstroConfigSetup) => Promise<void> };
+} {
   const { inject = true, watch = DEFAULT_WATCH, ...pageOptions } = options;
   return {
     name: '@occluze/tether',
     hooks: {
-      'astro:config:setup': async ({
-        injectScript,
-        command,
-        config: astroConfig,
-        logger,
-        addWatchFile,
-        updateConfig,
-      }) => {
+      'astro:config:setup': async (setup) => {
+        const { injectScript, command, config: astroConfig, logger, addWatchFile } = setup;
         const { fileURLToPath } = await import('node:url');
         const root = astroConfig.root ? fileURLToPath(astroConfig.root) : process.cwd();
         if (command === 'dev' && addWatchFile) await watchConfigFiles(root, watch ?? [], addWatchFile);
-        if (updateConfig) await declareEnvSchema(updateConfig, logger);
-        /** @type {PageConfig} */
-        const config = { ...pageOptions };
+        await declareEnvSchema(setup);
+        const config: PageConfig = { ...pageOptions };
         applyStoreEnv(config, await readEnv(command, root), logger);
         dropFunctions(config, logger);
+        keepBrowserOptions(config, logger);
         if (!config.domain || !config.token) {
           logger.warn(
             'No Shopify store configured: set PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN in .env (the public Storefront API token).',

package/src/cart/cart-shape.ts

@@ -0,0 +1,25 @@
+/**
+ * The structure of Tether's cart fragment, checked on a Storefront answer before it is used as a `ShopifyCart`. The
+ * cart's render, its totals and the cart API walk its lines and prices without checking each step. Text fields are
+ * written as text, so they need no check.
+ */
+import { MONEY } from '../product-shape.ts';
+import type { Shape } from '../client.ts';
+
+const LINE = {
+  id: 'string',
+  quantity: 'number',
+  attributes: ['object'],
+  cost: { totalAmount: MONEY, subtotalAmount: MONEY, amountPerQuantity: MONEY },
+  merchandise: { id: 'string', selectedOptions: ['object'], product: 'object' },
+} as const satisfies Shape;
+
+export const CART = {
+  id: 'string',
+  checkoutUrl: 'string',
+  totalQuantity: 'number',
+  attributes: ['object'],
+  discountCodes: ['object'],
+  cost: { totalAmount: MONEY, subtotalAmount: MONEY },
+  lines: { nodes: [LINE] },
+} as const satisfies Shape;

package/src/cart/checkout.ts

@@ -0,0 +1,101 @@
+/**
+ * Sending the visitor to Shopify's checkout. The URL comes from Shopify at click time, because the cart's checkout URL
+ * changes with its market and customer; the account part resolves a logged-in customer's own (`setCheckoutResolver`).
+ */
+import { cfg, reportError } from '../config.ts';
+import { TetherError } from '../client.ts';
+import { isHttpsUrl } from '../shopify-values.ts';
+import { emit } from '../dom.ts';
+import { fetchCheckoutUrl } from './mutations.ts';
+import { currentCart, savedCartId } from './store.ts';
+import type { CheckoutTarget } from '../config.ts';
+
+type CheckoutUrlAnswer = { kind: 'url'; url: string | null } | { kind: 'failed'; error: unknown };
+
+/**
+ * The logged-in customer's checkout URL for the cart; `null` when nobody is logged in, so the cart's own checkout URL
+ * is used.
+ */
+type CheckoutResolver = () => Promise<string | null>;
+
+let resolveAccountCheckout: CheckoutResolver | null = null;
+
+/** Sets the account part's checkout URL, or clears it with `null`. A URL it answers opens checkout logged in. */
+export function setCheckoutResolver(resolver: CheckoutResolver | null): void {
+  resolveAccountCheckout = resolver;
+}
+
+/**
+ * @returns Shopify's answer as a value, so the request can run alongside the account's and its failure is read only
+ *   when its URL is the one used.
+ */
+const askCheckoutUrl = (cartId: string): Promise<CheckoutUrlAnswer> =>
+  fetchCheckoutUrl(cartId).then(
+    (url) => ({ kind: 'url', url }),
+    (error: unknown) => ({ kind: 'failed', error }),
+  );
+
+/**
+ * @returns The logged-in customer's checkout URL. When the account can't give one, the failure is reported and the
+ *   cart's own checkout URL is used, which still checks out (without the login).
+ */
+async function accountCheckoutUrl(): Promise<string | null> {
+  if (!resolveAccountCheckout) return null;
+  try {
+    const url = await resolveAccountCheckout();
+    // Shopify's checkout shows the customer as logged in only with this parameter.
+    return url && `${url}${url.includes('?') ? '&' : '?'}logged_in=true`;
+  } catch (error) {
+    reportError(error, 'account checkout');
+    return null;
+  }
+}
+
+/** @throws {TetherError} `ERROR` without a checkout URL (the cart is empty or Shopify no longer has it). */
+async function checkoutUrl(cartId: string): Promise<string> {
+  const cartAnswer = askCheckoutUrl(cartId);
+  const accountUrl = await accountCheckoutUrl();
+  if (accountUrl) return accountUrl;
+  const answer = await cartAnswer;
+  if (answer.kind === 'failed') throw answer.error;
+  if (!answer.url) throw new TetherError('No checkoutUrl (cart empty or expired)');
+  return answer.url;
+}
+
+/**
+ * A new tab's `opener` gives the checkout page a handle on this one; a browser that doesn't let a script clear it
+ * leaves the tab as it opened.
+ */
+function detachOpenerIfAllowed(tab: Window) {
+  try {
+    tab.opener = null;
+  } catch {
+    // The browser keeps `opener` read-only: see the function's comment.
+  }
+}
+
+/**
+ * Goes to Shopify's checkout. With `_blank` the tab opens inside the click (Safari blocks `window.open` after an
+ * await) and gets its URL once there is one.
+ *
+ * @returns The checkout URL, `null` with nothing to check out or after a reported failure.
+ */
+export async function checkout(target: CheckoutTarget = cfg.checkoutTarget): Promise<string | null> {
+  const cartId = savedCartId();
+  const cart = currentCart();
+  if (!cartId || (cart && !cart.totalQuantity)) return null;
+  const tab = target === '_blank' ? window.open('', '_blank') : null;
+  if (tab) detachOpenerIfAllowed(tab);
+  try {
+    const url = await checkoutUrl(cartId);
+    if (!isHttpsUrl(url)) throw new TetherError('The checkout URL is not https: not opened');
+    emit('checkout', { url, cart: currentCart() });
+    if (tab && !tab.closed) tab.location.href = url;
+    else window.location.href = url;
+    return url;
+  } catch (error) {
+    tab?.close();
+    reportError(error, 'checkout failed');
+    return null;
+  }
+}

package/src/cart/{drawer.js → drawer.ts}

@@ -3,8 +3,8 @@
  * into the open cart, Tab stays inside it and focus returns on close (`cartFocus`). A page without a drawer (a cart
  * built in React, Svelte or Vue) still has an open state, for `Tether.cart.subscribe`.
  */
-import { cfg } from '../config.js';
-import { sel, get, qsa, emit } from '../dom.js';
+import { cfg } from '../config.ts';
+import { sel, get, qsa, emit } from '../dom.ts';
 
 const FOCUSABLE =
   'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
@@ -15,30 +15,22 @@ const FOCUS_AFTER_OPEN_MS = 60;
 /** The open state of a page without a drawer element. */
 let openWithoutDrawer = false;
 
-/** @type {HTMLElement | null} Where focus was before the cart opened. */
-let returnFocus = null;
+/** Where focus was before the cart opened. */
+let returnFocus: HTMLElement | null = null;
 
-/**
- * @param {Element | null} el
- * @returns {el is HTMLElement}
- */
-const isFocusable = (el) => el !== null && 'focus' in el;
+const isFocusable = (el: Element | null): el is HTMLElement => el !== null && 'focus' in el;
 
-/**
- * @param {ParentNode} drawer
- * @returns {HTMLElement[]} The visible focusable elements inside `drawer`, in document order.
- */
-const focusables = (drawer) =>
+/** @returns The visible focusable elements inside `drawer`, in document order. */
+const focusables = (drawer: ParentNode): HTMLElement[] =>
   qsa(drawer, FOCUSABLE).filter((el) => el.offsetParent !== null || el === document.activeElement);
 
-/** @returns {HTMLElement[]} Every cart drawer on the page. */
-export const drawers = () => qsa(document, sel('cart-drawer'));
+/** Every cart drawer on the page. */
+export const drawers = (): HTMLElement[] => qsa(document, sel('cart-drawer'));
 
-/** @param {HTMLElement} drawer */
-const isOpenDrawer = (drawer) => drawer.classList.contains(cfg.cartDrawerOpenClass);
+const isOpenDrawer = (drawer: HTMLElement) => drawer.classList.contains(cfg.cartDrawerOpenClass);
 
-/** @returns {boolean} True while a drawer, or the drawer-less cart, is open. */
-export function isOpen() {
+/** True while a drawer, or the drawer-less cart, is open. */
+export function isOpen(): boolean {
   const all = drawers();
   return all.length ? all.some(isOpenDrawer) : openWithoutDrawer;
 }
@@ -46,10 +38,8 @@ export function isOpen() {
 /**
  * `aria-expanded` on the open buttons, and dialog semantics on the drawers unless their markup has its own. A closed
  * drawer is hidden from screen readers and, with `cartFocus`, out of the Tab order (inert), like a closed dialog.
- *
- * @param {boolean} open
  */
-export function syncDrawerAria(open) {
+export function syncDrawerAria(open: boolean): void {
   qsa(document, sel('cart-open')).forEach((button) => {
     button.setAttribute('aria-expanded', String(open));
   });
@@ -65,15 +55,14 @@ export function syncDrawerAria(open) {
   });
 }
 
-/** @param {HTMLElement} drawer */
-function focusInto(drawer) {
+function focusInto(drawer: HTMLElement) {
   const target = focusables(drawer)[0] ?? drawer;
   if (target === drawer && !drawer.hasAttribute('tabindex')) drawer.tabIndex = -1;
   target.focus({ preventScroll: true });
 }
 
 /** Opens every drawer except `tether-cart-drawer="manual"` ones, which the site opens itself. */
-export function openCart() {
+export function openCart(): void {
   if (isOpen()) return;
   openWithoutDrawer = true;
   const opened = drawers().filter((drawer) => get(drawer, 'cart-drawer') !== 'manual');
@@ -94,7 +83,7 @@ export function openCart() {
   emit('cart-toggled', { open: true });
 }
 
-export function closeCart() {
+export function closeCart(): void {
   if (!isOpen()) return;
   openWithoutDrawer = false;
   const all = drawers();
@@ -111,7 +100,7 @@ export function closeCart() {
   emit('cart-toggled', { open: false });
 }
 
-export function toggleCart() {
+export function toggleCart(): void {
   if (isOpen()) closeCart();
   else openCart();
 }
@@ -119,10 +108,8 @@ export function toggleCart() {
 /**
  * Keeps Tab inside the open drawer (`cartFocus`): from the last focusable element it wraps to the first, with Shift
  * from the first to the last, and from outside the drawer it goes in. For a document `keydown` listener.
- *
- * @param {KeyboardEvent} event
  */
-export function trapFocus(event) {
+export function trapFocus(event: KeyboardEvent): void {
   if (event.key !== 'Tab' || !cfg.cartFocus || !isOpen()) return;
   const drawer = drawers().find(isOpenDrawer);
   if (!drawer) return;