@tokenoftrust/storefront-runner 2.5.6 → 3.0.0

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

@@ -345,6 +345,12 @@ export interface CommerceProviderCartSnapshot {
   totals: MinorTotals;
   destinationDigest: string;
   destination: { country: string; region: string };
+  /**
+   * The shopper's verification correlation handle, from the signed `verification` cart option.
+   * Present only when the cart carries one; outside the cart digest. A handle, not a claim: the
+   * final-cart authority re-reads its status from the verification provider.
+   */
+  verificationRef?: string;
 }
 
 /** Safe source references explaining each server-owned authority decision. */
@@ -357,13 +363,6 @@ export interface CommerceAuthoritySource {
 }
 export type CommerceEvidenceProvenance = Record<keyof CommerceEvidence, CommerceAuthoritySource>;
 
-export interface SyntheticCommerceAuthorityPolicy {
-  purpose: "synthetic-nonbillable";
-  revision: string;
-  expiresAt: string;
-  requirements: Record<"verification" | "tax" | "risk", "required" | "not-required">;
-}
-
 export interface CommerceAdmissionSnapshot extends CommerceProviderCartSnapshot {
   authorizationId: string;
   cartDigest: string;

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

@@ -24,8 +24,9 @@ import type {
   ProductPurchaseOption,
   SubscriptionPurchaseOption,
 } from "./product.js";
+import { resolveStoreCurrency } from "./declared-tenant-config.mjs";
 import { DEFAULT_ONE_TIME_PURCHASE_OPTION } from "./product.js";
-import type { TenantConfig } from "./tenant.js";
+import type { ShippingPolicy, TenantConfig } from "./tenant.js";
 
 /** Stable commerce scope shared by signed carts, provider callers and operator authorization. */
 export function commerceTenantId(tenant: Pick<TenantConfig, "appDomain">): string {
@@ -159,6 +160,11 @@ export interface BuildVariantCartPayloadOptions {
    * Signed into the cart when present. Never taken from the submitted form.
    */
   tenantId?: string;
+  /**
+   * The store's currency (`TenantConfig.currency`), signed into the cart. Resolved through
+   * `resolveStoreCurrency`, so absent or invalid is USD. Never taken from the submitted form.
+   */
+  currency?: string;
 }
 
 /** Declared public serving substrate (ADR 0013 `serving.provider`). */
@@ -180,6 +186,7 @@ export type CartDenialCode =
   | "price"
   | "quantity"
   | "tenant"
+  | "shipping"
   | "signing-unavailable";
 
 export class CartSigningUnavailableError extends Error {
@@ -190,6 +197,120 @@ export class CartSigningUnavailableError extends Error {
   }
 }
 
+/**
+ * Signed cart fields the checkout consumes but a shopper must never see. The
+ * cart renders every non-native field as a line option, so each checkout store's
+ * hidden product options must list exactly these names. `tenant` stays a signed
+ * item option: `enforceCartSubmission` and the commerce pre-payment callback
+ * both bind the cart to it. `verification` carries the shopper's verification
+ * ref when the gate produced one (`withVerificationRef`). `shipping_policy` carries the
+ * store's declared shipping charge (`withShippingPolicy`).
+ */
+export const INTERNAL_CART_FIELDS = ["currency", "tenant", "verification", "shipping_policy"] as const;
+
+/** The signed cart option the checkout store reads the shipping charge from. */
+export const SHIPPING_POLICY_CART_FIELD = "shipping_policy";
+
+/** Shopper copy when a cart cannot carry the store's shipping charge. */
+export const SHIPPING_UNAVAILABLE_CART_MESSAGE =
+  "Checkout is unavailable because shipping for this order could not be calculated.";
+
+/** A declared shipping policy cannot be charged exactly in the cart's currency. */
+export class ShippingPolicyUnavailableError extends Error {
+  readonly code = "shipping" as const;
+  constructor() {
+    super("The store's shipping policy cannot be charged in this cart's currency.");
+    this.name = "ShippingPolicyUnavailableError";
+  }
+}
+
+/** A shipping policy in the minor units of one currency. */
+export interface ShippingPolicyMinor {
+  currency: string;
+  digits: number;
+  flatMinor: number;
+  freeAtOrAboveMinor: number | null;
+}
+
+function minorUnits(amount: number, digits: number): number {
+  const scaled = amount * 10 ** digits;
+  const rounded = Math.round(scaled);
+  if (!Number.isFinite(amount) || amount < 0 || Math.abs(scaled - rounded) > 0.000001) {
+    throw new ShippingPolicyUnavailableError();
+  }
+  return rounded;
+}
+
+/**
+ * The policy in `currency`'s minor units. Throws `ShippingPolicyUnavailableError` for an
+ * unknown currency or an amount that currency cannot state exactly, so no caller rounds a
+ * declared charge into a different one.
+ */
+export function shippingPolicyMinor(policy: ShippingPolicy, currency: string): ShippingPolicyMinor {
+  if (!/^[A-Z]{3}$/.test(currency)) throw new ShippingPolicyUnavailableError();
+  let digits: number | undefined;
+  try {
+    digits = new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions().maximumFractionDigits;
+  } catch {
+    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 };
+}
+
+/** Shipping owed on an order whose item subtotal is `subtotalMinor`: the flat rate, or 0 at or above the free threshold. */
+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;
+}
+
+/**
+ * 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.
+ */
+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(";");
+}
+
+/** A verification correlation handle as a cart may carry it (the commerce adapter's shape). */
+export const CART_VERIFICATION_REF = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/;
+
+/** Native checkout item parameters. The cart consumes them; none renders as an option. */
+export const NATIVE_CART_FIELDS = [
+  "name",
+  "price",
+  "code",
+  "quantity",
+  "image",
+  "sub_frequency",
+  "sub_startdate",
+  "sub_enddate",
+] as const;
+
+/** Non-variant fields deliberately shown on the shopper's cart line. */
+export const VISIBLE_CART_FIELDS = ["Purchase option"] as const;
+
+export type CartFieldVisibility = "native" | "internal" | "visible" | "variant-option" | "undeclared";
+
+/**
+ * How a field emitted by `cartFieldsForVariant` reaches the shopper. A field
+ * that is none of native, internal, declared-visible, or one of the variant's
+ * own options is `undeclared`: it would render on the cart line unreviewed.
+ */
+export function cartFieldVisibility(name: string, variant: Pick<CatalogVariant, "option_values">): CartFieldVisibility {
+  if ((NATIVE_CART_FIELDS as readonly string[]).includes(name)) return "native";
+  if ((INTERNAL_CART_FIELDS as readonly string[]).includes(name)) return "internal";
+  if ((VISIBLE_CART_FIELDS as readonly string[]).includes(name)) return "visible";
+  if (Object.prototype.hasOwnProperty.call(variant.option_values, name)) return "variant-option";
+  return "undeclared";
+}
+
 const DEFAULT_CHECKOUT_HOST_SUFFIX = ".foxycart.com";
 const SUBSCRIPTION_FREQUENCY_RE = /^(?:\d+(?:\.\d+)?|\.\d+)[dwmy]$/;
 const PREVIEW_PIN_RE = /\/preview\/(?:staged|candidate)(?:\/|$)/;
@@ -292,7 +413,7 @@ export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
   purchaseOption?: ProductPurchaseOption,
-  opts?: { signedPrice?: number; tenantId?: string },
+  opts?: { signedPrice?: number; tenantId?: string; currency?: string },
 ): { code: string; fields: CartField[] } {
   const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
@@ -304,13 +425,16 @@ export function cartFieldsForVariant(
     opts?.signedPrice !== undefined
       ? assertEffectivePrice(opts.signedPrice, variant.price)
       : purchaseOptionPrice(variant.price, purchaseOption);
-  if (!variant.currency) {
-    throw new Error("cartFieldsForVariant: variant currency is required");
+  const currency = resolveStoreCurrency(opts?.currency);
+  if (variant.currency && variant.currency !== currency) {
+    throw new Error(
+      `cartFieldsForVariant: variant is priced in ${variant.currency}; this store sells in ${currency}`,
+    );
   }
   const fields: CartField[] = [
     { name: "name", value: cartLineName(product, variant) },
     { name: "price", value: price.toFixed(2) },
-    { name: "currency", value: variant.currency },
+    { name: "currency", value: currency },
     { name: "code", value: code },
     { name: "quantity", value: "1", open: true },
   ];
@@ -509,7 +633,7 @@ export async function buildVariantCartPayload(
     product,
     variant,
     opts.purchaseOption,
-    { signedPrice: opts.signedPrice, tenantId: opts.tenantId },
+    { signedPrice: opts.signedPrice, tenantId: opts.tenantId, currency: opts.currency },
   );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {
@@ -532,6 +656,7 @@ const CART_DENIAL_MESSAGE: Record<CartDenialCode, string> = {
   price: "Checkout was refused because the price does not match the signed price.",
   quantity: "Checkout was refused because the quantity is not an allowed amount.",
   tenant: "Checkout was refused because the cart tenant does not match this store.",
+  shipping: SHIPPING_UNAVAILABLE_CART_MESSAGE,
   "signing-unavailable": CART_SIGNING_OPERATOR_ERROR,
 };
 
@@ -673,6 +798,65 @@ export async function enforceCartSubmission(input: {
   };
 }
 
+/**
+ * Split the shopper's verification ref out of a submitted cart form. The browser posts it as
+ * one plain `verification` field; every `verification` field is removed from the entries, so
+ * none reaches the signature check or the cart unsigned. More than one, or a value that is not
+ * a well-formed handle, yields no ref.
+ */
+export function takeVerificationRef(
+  entries: Iterable<[string, string]>,
+): { entries: Array<[string, string]>; ref: string | null } {
+  const kept: Array<[string, string]> = [];
+  const refs: string[] = [];
+  for (const [name, value] of entries) {
+    if (name.split("||")[0] !== "verification") kept.push([name, value]);
+    else if (name === "verification") refs.push(value);
+  }
+  const ref = refs.length === 1 && CART_VERIFICATION_REF.test(refs[0]!) ? refs[0]! : null;
+  return { entries: kept, ref };
+}
+
+/**
+ * Add the verification ref to an enforced cart as the internal `verification` option, signed
+ * against the cart's product code like every other field. The ref is a correlation handle,
+ * not a claim: the final-cart authority re-reads its status from the provider.
+ */
+export async function withVerificationRef(
+  fields: readonly CartSubmissionField[],
+  opts: { mode: ManagedCheckoutConfig["mode"]; secret?: string; ref: string | null },
+): Promise<CartSubmissionField[]> {
+  if (!opts.ref || !CART_VERIFICATION_REF.test(opts.ref)) return [...fields];
+  const code = fields.find((field) => field.name.split("||")[0] === "code")?.value;
+  if (!code) return [...fields];
+  const field: CartField = { name: "verification", value: opts.ref };
+  if (opts.mode !== "signed") return [...fields, field];
+  if (!opts.secret) throw new CartSigningUnavailableError();
+  return [...fields, await signField(opts.secret, code, field)];
+}
+
+/**
+ * Bind the store's shipping policy into an enforced cart as the internal `shipping_policy`
+ * option, signed against the cart's product code. Any `shipping_policy` the shopper submitted is
+ * dropped first, so only the trusted tenant's declaration reaches the cart. No policy leaves the
+ * cart without one. The amounts are stated in the cart's own `currency` field. Throws
+ * `ShippingPolicyUnavailableError` when the cart names no currency the policy can be charged in.
+ */
+export async function withShippingPolicy(
+  fields: readonly CartSubmissionField[],
+  opts: { mode: ManagedCheckoutConfig["mode"]; secret?: string; policy: ShippingPolicy | undefined },
+): Promise<CartSubmissionField[]> {
+  const kept = fields.filter((field) => field.name.split("||")[0] !== SHIPPING_POLICY_CART_FIELD);
+  if (!opts.policy) return kept;
+  const code = kept.find((field) => field.name.split("||")[0] === "code")?.value;
+  const currency = kept.find((field) => field.name.split("||")[0] === "currency")?.value;
+  if (!code || !currency) throw new ShippingPolicyUnavailableError();
+  const field: CartField = { name: SHIPPING_POLICY_CART_FIELD, value: shippingPolicyOptionValue(opts.policy, currency) };
+  if (opts.mode !== "signed") return [...kept, field];
+  if (!opts.secret) throw new CartSigningUnavailableError();
+  return [...kept, await signField(opts.secret, code, field)];
+}
+
 /** Cart URL the browser may navigate to after enforcement. Not a payment. */
 export function foxyCartRedirectUrl(
   cartUrl: string,

package/packages/public-runtime/src/compliance/evaluate.ts

@@ -70,6 +70,8 @@ export interface ComplianceBlock {
   message: string;
   region?: string;
   sku?: string;
+  /** `flavored_prohibited` only: the characterizing flavor labels that triggered it. */
+  flavors?: string[];
   /** True when this block is a fail-closed safety default, not a real violation. */
   failedClosed?: boolean;
 }
@@ -214,13 +216,15 @@ export function evaluateCartCompliance(
           continue;
         }
         if (stateRule?.banFlavored && line.profile.isFlavored) {
+          const flavors = line.profile.characterizingFlavors;
           blocks.push({
             code: "flavored_prohibited",
             region,
             sku: line.sku,
-            message: `Flavored ${line.title ?? line.sku} cannot be shipped to ${region}${
-              stateRule?.note ? ` (${stateRule.note})` : ""
-            }.`,
+            flavors,
+            message: `${line.title ?? line.sku} cannot be shipped to ${region}: flavored (${
+              flavors.length > 0 ? flavors.join(", ") : "unnamed flavor"
+            })${stateRule?.note ? ` (${stateRule.note})` : ""}.`,
           });
         }
       }

package/packages/public-runtime/src/compliance/profile.ts

@@ -32,8 +32,17 @@ export interface ProductComplianceProfile {
    * ban for ENDS. `false` for tobacco/menthol/unflavored.
    */
   isFlavored: boolean;
-  /** Flavor labels found (lowercased), e.g. ["mango", "ice"]. */
+  /**
+   * Flavor labels found (lowercased), e.g. ["mango", "ice"]. Nicotine-format
+   * labels filed under `F:` ("nicotine salt", "freebase") are not flavors and
+   * are excluded.
+   */
   flavorLabels: string[];
+  /**
+   * The subset of `flavorLabels` that is characterizing — the labels that make
+   * `isFlavored` true, so a flavored-ENDS block can name its trigger.
+   */
+  characterizingFlavors: string[];
   /** Derived regulated category. */
   category: RegulatedCategory;
   /**
@@ -44,10 +53,11 @@ export interface ProductComplianceProfile {
   restrictedRegions: string[];
 }
 
-/** Flavors that do NOT count as "characterizing" for a flavored-ENDS ban. */
+/**
+ * Exact labels that do NOT count as "characterizing" for a flavored-ENDS ban.
+ * Tobacco labels are classified by `isTobaccoFlavorLabel`.
+ */
 const UNFLAVORED = new Set([
-  "tobacco",
-  "classic tobacco",
   "menthol",
   "unflavored",
   "none",
@@ -55,6 +65,69 @@ const UNFLAVORED = new Set([
   "plain",
 ]);
 
+/**
+ * Nicotine format/strength labels that catalogs file under `F:` tags. They
+ * describe the nicotine, not the taste, so they are dropped before
+ * classification.
+ */
+const NICOTINE_FORMAT_LABELS = new Set([
+  "nicotine salt",
+  "nicotine salts",
+  "salt nicotine",
+  "salt nic",
+  "nic salt",
+  "nic salts",
+  "salt",
+  "salts",
+  "freebase",
+  "free base",
+  "freebase nicotine",
+  "free base nicotine",
+  "synthetic",
+  "synthetic nicotine",
+  "tfn",
+  "tobacco free nicotine",
+  "tobacco-free nicotine",
+]);
+
+/**
+ * Closed allowlist of tobacco type, origin and style words. A label is a plain
+ * tobacco flavor only when every word besides "tobacco" is in this list:
+ * "Virginia Tobacco" is tobacco, while "Caramel Tobacco" and "Golden Tobacco"
+ * are characterizing flavors. An unlisted word means flavored (fail closed),
+ * so extend this list only with words that name a tobacco, never a taste.
+ */
+const TOBACCO_QUALIFIERS = new Set([
+  "american",
+  "virginia",
+  "pipe",
+  "cuban",
+  "turkish",
+  "burley",
+  "kentucky",
+  "classic",
+  "traditional",
+  "original",
+  "regular",
+  "rich",
+  "bold",
+  "mild",
+  "blend",
+]);
+
+/** True when a label names tobacco, optionally qualified by `TOBACCO_QUALIFIERS` only. */
+function isTobaccoFlavorLabel(label: string): boolean {
+  const words = label.split(/[^a-z0-9]+/).filter((w) => w.length > 0);
+  return (
+    words.includes("tobacco") &&
+    words.every((w) => w === "tobacco" || TOBACCO_QUALIFIERS.has(w))
+  );
+}
+
+function isCharacterizingFlavor(label: string): boolean {
+  return !UNFLAVORED.has(label) && !isTobaccoFlavorLabel(label);
+}
+
 const NICOTINE_HINTS = [
   "nicotine",
   "vape",
@@ -104,20 +177,24 @@ function parseRestrictedRegions(raw: string | undefined): string[] {
   }
 }
 
-/** Collect flavor labels from the `F: <flavor>` tag convention + a chosen variant. */
+/**
+ * Collect flavor labels from the `F: <flavor>` tag convention + a chosen
+ * variant, dropping nicotine-format labels.
+ */
 function collectFlavors(
   product: Pick<CatalogProduct, "tags">,
   variant?: Pick<CatalogVariant, "option_values"> | null,
 ): string[] {
   const labels = new Set<string>();
+  const add = (raw: string) => {
+    const v = raw.trim().toLowerCase();
+    if (v && !NICOTINE_FORMAT_LABELS.has(v)) labels.add(v);
+  };
   for (const tag of product.tags ?? []) {
-    if (tag.startsWith("F: ")) {
-      const v = tag.slice(3).trim().toLowerCase();
-      if (v) labels.add(v);
-    }
+    if (tag.startsWith("F: ")) add(tag.slice(3));
   }
   const optFlavor = variant?.option_values?.["Flavor"];
-  if (optFlavor) labels.add(optFlavor.trim().toLowerCase());
+  if (optFlavor) add(optFlavor);
   return [...labels];
 }
 
@@ -166,10 +243,8 @@ export function deriveProductProfile(
       (!nicOptionSaysZero && containsAny(haystack, NICOTINE_HINTS)));
 
   const flavorLabels = collectFlavors(product, variant);
-  const isFlavored =
-    containsNicotine &&
-    flavorLabels.some((f) => !UNFLAVORED.has(f)) &&
-    flavorLabels.length > 0;
+  const characterizingFlavors = flavorLabels.filter(isCharacterizingFlavor);
+  const isFlavored = containsNicotine && characterizingFlavors.length > 0;
 
   let cat: RegulatedCategory = "none";
   if (isAccessory) cat = "accessory";
@@ -183,6 +258,7 @@ export function deriveProductProfile(
     containsNicotine,
     isFlavored,
     flavorLabels,
+    characterizingFlavors,
     category: cat,
     restrictedRegions,
   };

package/packages/public-runtime/src/compliance-coherence.d.mts

@@ -9,9 +9,18 @@ export interface CoherenceFailure {
   hint: string;
 }
 
+/** A resolved obligation, as `resolveObligations` returns it (only these fields are read). */
+export interface AppliedObligation {
+  id: string;
+  surface: string;
+}
+
 export const COHERENCE_CHECK_IDS: readonly CoherenceCheckId[];
-export function isRegulatedCompliance(compliance: object | null | undefined): boolean;
+export const OBLIGATION_EVIDENCE_CHECK: Readonly<Record<string, CoherenceCheckId | null>>;
+export function isRegulatedObligationSet(obligations: readonly AppliedObligation[]): boolean;
+export function coherenceChecksFor(obligations: readonly AppliedObligation[]): CoherenceCheckId[];
 export function declaresJurisdictionNotice(compliance: object | null | undefined): boolean;
 export function complianceCoherenceFailures(
   compliance: object | null | undefined,
+  obligations: readonly AppliedObligation[],
 ): Partial<Record<CoherenceCheckId, CoherenceFailure>>;