@tokenoftrust/storefront-runner 3.7.2 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.7.2",
+  "version": "3.8.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/declared-config.mjs

@@ -197,20 +197,38 @@ export function seoDeclarationProblems(seo) {
 }
 
 /** Every `shipping` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
-export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+export const SHIPPING_KEYS = Object.freeze(["tiers"]);
+
+/** Every key of one `shipping.tiers` entry. */
+export const SHIPPING_TIER_KEYS = Object.freeze(["atOrAbove", "rate", "label"]);
 
 /** Largest shipping amount a declaration may state, in the cart's currency. */
 export const MAX_SHIPPING_AMOUNT = 100000;
 
+/** Most tiers one policy may declare. */
+export const MAX_SHIPPING_TIERS = 10;
+
+/** Longest shipping-line label, in characters. */
+export const MAX_SHIPPING_LABEL_LENGTH = 100;
+
 /** @param {unknown} value */
 const isShippingAmount = (value) =>
   typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
   && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
 
+/** @param {unknown} value */
+const isShippingLabel = (value) =>
+  typeof value === "string" && value.trim() === value && value.length > 0
+  && [...value].length <= MAX_SHIPPING_LABEL_LENGTH && !/[\u0000-\u001f\u007f]/.test(value);
+
 /**
  * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
  * valid. A policy with any problem is refused whole, so checkout never charges half of one.
  *
+ * Tiers are ordered by the item subtotal they start at. The first starts at 0 and states no
+ * `atOrAbove`; each later tier's `atOrAbove` is above the one before it and is inclusive, so an
+ * order whose subtotal equals it pays that tier's `rate`.
+ *
  * @param {unknown} shipping
  * @returns {string[]}
  */
@@ -221,12 +239,38 @@ export function shippingDeclarationProblems(shipping) {
   for (const key of Object.keys(source)) {
     if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
   }
-  if (!isShippingAmount(source.flatRate)) {
-    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
-  }
-  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
-    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  const tiers = source.tiers;
+  if (!Array.isArray(tiers) || tiers.length === 0 || tiers.length > MAX_SHIPPING_TIERS) {
+    problems.push(`\`shipping.tiers\` must be a list of 1 to ${MAX_SHIPPING_TIERS} tiers`);
+    return problems;
   }
+  let previous = 0;
+  tiers.forEach((tier, index) => {
+    const at = `shipping.tiers[${index}]`;
+    if (!isPlainObject(tier)) {
+      problems.push(`\`${at}\` must be an object`);
+      return;
+    }
+    const entry = /** @type {Record<string, unknown>} */ (tier);
+    for (const key of Object.keys(entry)) {
+      if (!SHIPPING_TIER_KEYS.includes(key)) problems.push(`\`${at}.${key}\` is not a tier key (${SHIPPING_TIER_KEYS.join(", ")})`);
+    }
+    if (!isShippingAmount(entry.rate)) {
+      problems.push(`\`${at}.rate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+    }
+    if (entry.label !== undefined && !isShippingLabel(entry.label)) {
+      problems.push(`\`${at}.label\` must be text of 1 to ${MAX_SHIPPING_LABEL_LENGTH} characters with no surrounding spaces or line breaks`);
+    }
+    if (index === 0) {
+      if (entry.atOrAbove !== undefined) problems.push(`\`${at}\` starts at 0, so it states no \`atOrAbove\``);
+      return;
+    }
+    if (!(isShippingAmount(entry.atOrAbove) && /** @type {number} */ (entry.atOrAbove) > previous)) {
+      problems.push(`\`${at}.atOrAbove\` must be an amount above ${previous}, where the tier before it starts, and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+      return;
+    }
+    previous = /** @type {number} */ (entry.atOrAbove);
+  });
   return problems;
 }
 
@@ -702,7 +746,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     const problems = shippingDeclarationProblems(config.shipping);
     if (problems.length > 0) {
       out.push(mk(ERROR, "config-shipping", `${file} shipping`, shippingProblemMessage(problems),
-        'declare e.g. `"shipping": { "flatRate": 5.99, "freeAtOrAbove": 100 }`, or remove `shipping` to charge none'));
+        'declare e.g. `"shipping": { "tiers": [ { "rate": 5.99 }, { "atOrAbove": 100, "rate": 0, "label": "Free shipping" } ] }`, or remove `shipping` to charge none'));
     }
   }
   return out;

package/packages/public-runtime/src/checkout.ts

@@ -224,12 +224,19 @@ export class ShippingPolicyUnavailableError extends Error {
   }
 }
 
-/** A shipping policy in the minor units of one currency. */
+/** One shipping tier in the minor units of one currency. */
+export interface ShippingTierMinor {
+  /** Item subtotal the tier starts at, inclusive; 0 for the first tier. */
+  fromMinor: number;
+  rateMinor: number;
+  label: string | null;
+}
+
+/** A shipping policy in the minor units of one currency, tiers ascending by `fromMinor`. */
 export interface ShippingPolicyMinor {
   currency: string;
   digits: number;
-  flatMinor: number;
-  freeAtOrAboveMinor: number | null;
+  tiers: ShippingTierMinor[];
 }
 
 function minorUnits(amount: number, digits: number): number {
@@ -255,27 +262,51 @@ export function shippingPolicyMinor(policy: ShippingPolicy, currency: string): S
     throw new ShippingPolicyUnavailableError();
   }
   if (digits === undefined) throw new ShippingPolicyUnavailableError();
-  const freeAtOrAboveMinor = policy.freeAtOrAbove === undefined ? null : minorUnits(policy.freeAtOrAbove, digits);
-  if (freeAtOrAboveMinor === 0) throw new ShippingPolicyUnavailableError();
-  return { currency, digits, flatMinor: minorUnits(policy.flatRate, digits), freeAtOrAboveMinor };
+  const declared = Array.isArray(policy?.tiers) ? policy.tiers : [];
+  if (declared.length === 0) throw new ShippingPolicyUnavailableError();
+  const tiers = declared.map((tier, index): ShippingTierMinor => {
+    if ((index === 0) !== (tier.atOrAbove === undefined)) throw new ShippingPolicyUnavailableError();
+    return {
+      fromMinor: index === 0 ? 0 : minorUnits(tier.atOrAbove!, digits),
+      rateMinor: minorUnits(tier.rate, digits),
+      label: tier.label ?? null,
+    };
+  });
+  // Tiers that collapse onto one minor-unit start (or run backwards) cannot say which applies.
+  if (tiers.some((tier, index) => index > 0 && tier.fromMinor <= tiers[index - 1]!.fromMinor)) {
+    throw new ShippingPolicyUnavailableError();
+  }
+  return { currency, digits, tiers };
 }
 
-/** Shipping owed on an order whose item subtotal is `subtotalMinor`: the flat rate, or 0 at or above the free threshold. */
+/**
+ * The tier an order whose item subtotal is `subtotalMinor` pays: the last one whose start it
+ * reaches. A subtotal exactly at a tier's `atOrAbove` pays that tier.
+ */
+export function shippingTierFor(policy: ShippingPolicy, currency: string, subtotalMinor: number): ShippingTierMinor {
+  const { tiers } = shippingPolicyMinor(policy, currency);
+  return tiers.reduce((paid, tier) => (subtotalMinor >= tier.fromMinor ? tier : paid), tiers[0]!);
+}
+
+/** Shipping owed, in minor units, on an order whose item subtotal is `subtotalMinor`. */
 export function shippingMinorFor(policy: ShippingPolicy, currency: string, subtotalMinor: number): number {
-  const minor = shippingPolicyMinor(policy, currency);
-  return minor.freeAtOrAboveMinor !== null && subtotalMinor >= minor.freeAtOrAboveMinor ? 0 : minor.flatMinor;
+  return shippingTierFor(policy, currency, subtotalMinor).rateMinor;
 }
 
 /**
- * The `shipping_policy` option value, e.g. `currency=USD;flat=5.99;free_at=100.00` (`free_at`
- * only when declared). Amounts carry exactly the currency's minor-unit digits; the checkout
- * store's shipping code parses this shape and refuses any other.
+ * The `shipping_policy` option value: `currency=<code>` then one `tier=<from>,<rate>[,<label>]`
+ * per tier, ascending, e.g.
+ * `currency=USD;tier=0.00,14.99,Flat%20rate%20shipping;tier=100.00,7.00,FREE%20shipping`.
+ * Amounts carry exactly the currency's minor-unit digits; a label is `encodeURIComponent`-encoded
+ * so it cannot contain `,` or `;`. The checkout store's shipping code parses this shape and
+ * refuses any other.
  */
 export function shippingPolicyOptionValue(policy: ShippingPolicy, currency: string): string {
   const minor = shippingPolicyMinor(policy, currency);
   const amount = (value: number) => (value / 10 ** minor.digits).toFixed(minor.digits);
-  return [`currency=${currency}`, `flat=${amount(minor.flatMinor)}`,
-    ...(minor.freeAtOrAboveMinor === null ? [] : [`free_at=${amount(minor.freeAtOrAboveMinor)}`])].join(";");
+  return [`currency=${currency}`, ...minor.tiers.map((tier) =>
+    `tier=${[amount(tier.fromMinor), amount(tier.rateMinor), ...(tier.label === null ? [] : [encodeURIComponent(tier.label)])].join(",")}`)]
+    .join(";");
 }
 
 /** A verification correlation handle as a cart may carry it (the commerce adapter's shape). */

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -21,7 +21,10 @@ export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
 export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
 export function seoDeclarationProblems(seo: unknown): string[];
 export const SHIPPING_KEYS: readonly string[];
+export const SHIPPING_TIER_KEYS: readonly string[];
 export const MAX_SHIPPING_AMOUNT: number;
+export const MAX_SHIPPING_TIERS: number;
+export const MAX_SHIPPING_LABEL_LENGTH: number;
 export function shippingDeclarationProblems(shipping: unknown): string[];
 export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
 export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -243,20 +243,38 @@ export function seoDeclarationProblems(seo) {
 }
 
 /** Every `shipping` key (ShippingPolicy, tenant.ts). */
-export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+export const SHIPPING_KEYS = Object.freeze(["tiers"]);
+
+/** Every key of one `shipping.tiers` entry (ShippingTier, tenant.ts). */
+export const SHIPPING_TIER_KEYS = Object.freeze(["atOrAbove", "rate", "label"]);
 
 /** Largest shipping amount a declaration may state, in the cart's currency. */
 export const MAX_SHIPPING_AMOUNT = 100000;
 
+/** Most tiers one policy may declare. */
+export const MAX_SHIPPING_TIERS = 10;
+
+/** Longest shipping-line label, in characters. */
+export const MAX_SHIPPING_LABEL_LENGTH = 100;
+
 /** @param {unknown} value */
 const isShippingAmount = (value) =>
   typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
   && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
 
+/** @param {unknown} value */
+const isShippingLabel = (value) =>
+  typeof value === "string" && value.trim() === value && value.length > 0
+  && [...value].length <= MAX_SHIPPING_LABEL_LENGTH && !/[\u0000-\u001f\u007f]/.test(value);
+
 /**
  * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
  * valid. A policy with any problem is refused whole, so checkout never charges half of one.
  *
+ * Tiers are ordered by the item subtotal they start at. The first starts at 0 and states no
+ * `atOrAbove`; each later tier's `atOrAbove` is above the one before it and is inclusive, so an
+ * order whose subtotal equals it pays that tier's `rate`.
+ *
  * @param {unknown} shipping
  * @returns {string[]}
  */
@@ -267,15 +285,54 @@ export function shippingDeclarationProblems(shipping) {
   for (const key of Object.keys(source)) {
     if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
   }
-  if (!isShippingAmount(source.flatRate)) {
-    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
-  }
-  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
-    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  const tiers = source.tiers;
+  if (!Array.isArray(tiers) || tiers.length === 0 || tiers.length > MAX_SHIPPING_TIERS) {
+    problems.push(`\`shipping.tiers\` must be a list of 1 to ${MAX_SHIPPING_TIERS} tiers`);
+    return problems;
   }
+  let previous = 0;
+  tiers.forEach((tier, index) => {
+    const at = `shipping.tiers[${index}]`;
+    if (!isPlainObject(tier)) {
+      problems.push(`\`${at}\` must be an object`);
+      return;
+    }
+    const entry = /** @type {Record<string, unknown>} */ (tier);
+    for (const key of Object.keys(entry)) {
+      if (!SHIPPING_TIER_KEYS.includes(key)) problems.push(`\`${at}.${key}\` is not a tier key (${SHIPPING_TIER_KEYS.join(", ")})`);
+    }
+    if (!isShippingAmount(entry.rate)) {
+      problems.push(`\`${at}.rate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+    }
+    if (entry.label !== undefined && !isShippingLabel(entry.label)) {
+      problems.push(`\`${at}.label\` must be text of 1 to ${MAX_SHIPPING_LABEL_LENGTH} characters with no surrounding spaces or line breaks`);
+    }
+    if (index === 0) {
+      if (entry.atOrAbove !== undefined) problems.push(`\`${at}\` starts at 0, so it states no \`atOrAbove\``);
+      return;
+    }
+    if (!(isShippingAmount(entry.atOrAbove) && /** @type {number} */ (entry.atOrAbove) > previous)) {
+      problems.push(`\`${at}.atOrAbove\` must be an amount above ${previous}, where the tier before it starts, and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+      return;
+    }
+    previous = /** @type {number} */ (entry.atOrAbove);
+  });
   return problems;
 }
 
+/**
+ * A valid declaration copied to exactly its declared keys.
+ *
+ * @param {{ tiers: Array<Record<string, unknown>> }} policy
+ */
+const shippingPolicyOf = (policy) => ({
+  tiers: policy.tiers.map((tier) => ({
+    ...(tier.atOrAbove === undefined ? {} : { atOrAbove: tier.atOrAbove }),
+    rate: tier.rate,
+    ...(tier.label === undefined ? {} : { label: tier.label }),
+  })),
+});
+
 /**
  * The declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
  * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
@@ -302,8 +359,7 @@ export function declaredTenantConfig(config) {
   // The shipping charge: refused whole when any part is malformed (`tot validate` and the
   // reconcile report it), so checkout keeps charging no shipping rather than a guess.
   if (shipping !== undefined && shippingDeclarationProblems(shipping).length === 0) {
-    const policy = /** @type {Record<string, number>} */ (shipping);
-    out.shipping = { flatRate: policy.flatRate, ...(policy.freeAtOrAbove === undefined ? {} : { freeAtOrAbove: policy.freeAtOrAbove }) };
+    out.shipping = shippingPolicyOf(/** @type {{ tiers: Array<Record<string, unknown>> }} */ (shipping));
   }
   return out;
 }

package/packages/public-runtime/src/tenant.ts

@@ -773,16 +773,27 @@ export interface TenantConfig {
 }
 
 /**
- * A store's shipping charge: one flat rate per order, waived when the order's item subtotal
- * is at or above `freeAtOrAbove`. The cart carries it as the signed `shipping_policy` option;
- * the checkout store charges it and the final-cart authority re-derives it from this
- * declaration (checkout.ts `shippingMinorFor`).
+ * A store's shipping charge: one rate per order, chosen by the order's item subtotal from
+ * `tiers`. The cart carries it as the signed `shipping_policy` option; the checkout store
+ * charges it under the tier's label, and the final-cart authority re-derives the amount from
+ * this declaration (checkout.ts `shippingMinorFor`).
  */
 export interface ShippingPolicy {
-  /** Charged once per order, in the cart's currency. `0` ships every order free. */
-  flatRate: number;
-  /** Item subtotal at or above which shipping is free, in the cart's currency. */
-  freeAtOrAbove?: number;
+  /**
+   * Ascending by `atOrAbove`. The first tier starts at 0 and states no `atOrAbove`; an order
+   * pays the last tier whose start its item subtotal reaches.
+   */
+  tiers: ShippingTier[];
+}
+
+/** One band of item subtotals and what an order in it pays for shipping. */
+export interface ShippingTier {
+  /** Item subtotal this tier starts at, inclusive, in the cart's currency. Absent on the first tier. */
+  atOrAbove?: number;
+  /** Charged once per order, in the cart's currency. `0` ships free. */
+  rate: number;
+  /** The shipping line the shopper reads at checkout. Absent ⇒ "Free shipping" or "Shipping". */
+  label?: string;
 }
 
 /** Page types a structured-data profile declares a graph for (STRUCTURED_DATA_PAGE_TYPES). */