@tokenoftrust/cli 3.0.2 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/declared-config.d.mts

@@ -18,6 +18,13 @@ export const STRUCTURED_DATA_NODE_TOKENS: readonly string[];
 export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
 export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
 export function seoDeclarationProblems(seo: unknown): string[];
+export const DEFAULT_CURRENCY: "USD";
+export const CURRENCY_CODES: readonly string[];
+export function resolveStoreCurrency(declared: unknown): string;
+export function currencyDeclarationProblems(currency: unknown): string[];
+export const SHIPPING_KEYS: readonly string[];
+export const MAX_SHIPPING_AMOUNT: number;
+export function shippingDeclarationProblems(shipping: unknown): string[];
 export const COMPLIANCE_NOTICES: Record<string, string>;
 export const MANDATED_NOTICE_KEYS: string[];
 export function nearestKey(key: string, known: readonly string[]): string | null;

package/src/declared-config.mjs

@@ -19,7 +19,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo", "currency", "shipping",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -32,6 +32,44 @@ export const FEATURE_KEYS = [
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** The currency a store sells in when `.tot/config.json` declares none. */
+export const DEFAULT_CURRENCY = "USD";
+
+/** ISO 4217 codes a store may declare as its `currency`. */
+export const CURRENCY_CODES = Object.freeze(
+  ("AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP " +
+    "CRC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HTG HUF IDR ILS INR IQD IRR " +
+    "ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN " +
+    "MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLE SOS SRD " +
+    "SSP STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VES VND VUV WST XAF XCD XCG XOF XPF YER ZAR ZMW ZWG").split(" "),
+);
+
+/**
+ * The ONE place a store's currency is resolved. A declared ISO 4217 code wins; anything
+ * else (absent, wrong shape, lowercase, unknown code) is USD. Every surface that prices,
+ * signs or formats an amount takes the currency from here, never from a literal. Only the
+ * store owner's `.tot/config.json` can change it: a shopper's request never reaches this.
+ *
+ * @param {unknown} declared
+ * @returns {string}
+ */
+export function resolveStoreCurrency(declared) {
+  return typeof declared === "string" && CURRENCY_CODES.includes(declared) ? declared : DEFAULT_CURRENCY;
+}
+
+/**
+ * What is wrong with a declared `currency`, one sentence; `[]` when it is valid.
+ *
+ * @param {unknown} currency
+ * @returns {string[]}
+ */
+export function currencyDeclarationProblems(currency) {
+  return typeof currency === "string" && CURRENCY_CODES.includes(currency)
+    ? []
+    : [`\`currency\` is ${JSON.stringify(currency)} — must be an uppercase ISO 4217 code such as "USD" or "CAD"`];
+}
+
+
 /** Every `seo` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
 export const SEO_KEYS = Object.freeze(["trailingSlash", "verbatimSeoTitles", "structuredData"]);
 
@@ -158,6 +196,46 @@ export function seoDeclarationProblems(seo) {
   return problems;
 }
 
+/** Every `shipping` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+
+/** Largest shipping amount a declaration may state, in the cart's currency. */
+export const MAX_SHIPPING_AMOUNT = 100000;
+
+/** @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;
+
+/**
+ * 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.
+ *
+ * @param {unknown} shipping
+ * @returns {string[]}
+ */
+export function shippingDeclarationProblems(shipping) {
+  if (!isPlainObject(shipping)) return ["`shipping` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (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`);
+  }
+  return problems;
+}
+
+/** The owner-facing sentence for an invalid `shipping` declaration. */
+function shippingProblemMessage(problems) {
+  return `\`shipping\` is not a valid shipping policy (${problems.join("; ")}). ` +
+    "Checkout charges no shipping until it is fixed.";
+}
+
 
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
@@ -530,6 +608,8 @@ export function declarationFindings(current, previous) {
     if (warning.enabled && warning.problems.length > 0) {
       out.push(`CONFIG: ${nicotineWarningProblemMessage(warning.problems)}`);
     }
+    const shipping = current.shipping === undefined ? [] : shippingDeclarationProblems(current.shipping);
+    if (shipping.length > 0) out.push(`CONFIG: ${shippingProblemMessage(shipping)}`);
   }
   for (const { key, notice } of droppedMandatedNotices(previous, current)) {
     out.push(
@@ -608,11 +688,23 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
     out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
   }
+  if (config.currency !== undefined) {
+    for (const problem of currencyDeclarationProblems(config.currency)) {
+      out.push(mk(ERROR, "config-currency", file, `${problem} — the store sells in ${DEFAULT_CURRENCY} until it is fixed`));
+    }
+  }
   if (config.seo !== undefined) {
     for (const problem of seoDeclarationProblems(config.seo)) {
       out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
     }
   }
+  if (config.shipping !== undefined) {
+    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'));
+    }
+  }
   return out;
 }