npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.2 → 1.3.4-rc.2 - Mend

@tokenoftrust/storefront-runner 1.3.2 → 1.3.4-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/apps/storefront/src/pages/dashboard/[appDomain]/team.astro CHANGED Viewed

@@ -14,10 +14,22 @@ export const prerender = false;
 import { readViewerSession } from "@/lib/auth/route";
 import { membershipFor } from "@/lib/dashboard/tenantSelection";
+import { readEnv } from "@/lib/env";
 const cspNonce = Astro.locals.cspNonce;
 const appDomain = decodeURIComponent(Astro.params.appDomain ?? "");
+// qa-tier warn: derived from the SAME MCP origin the invite preflight uses
+// (MCP_APP_BINDING_URL). We don't want people onboarding developers via qa now that
+// prod+qa share data — so warn (non-blocking; qa is legitimate for testing).
+let isQaTier = false;
+try {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  isQaTier = !!bindingUrl && new URL(bindingUrl).hostname.startsWith("mcp.qa.");
+} catch {
+  isQaTier = false;
+}
 const session = await readViewerSession(Astro);
 if (!session) {
   return Astro.redirect(
@@ -89,6 +101,9 @@ const backHref = `/dashboard/${encodeURIComponent(appDomain)}`;
         .msg.ok { background: #16311f; border-color: #2f6b41; color: #a7e0ba; }
         .msg.err { background: #3a1f22; border-color: #6b2f34; color: #f6b9b9; }
       }
+      .warn { margin: 0 0 1rem; font-size: .88rem; border-radius: 9px; padding: .6rem .8rem;
+        background: #fff7e6; border: 1px solid #f0d999; color: #7a5b12; }
+      @media (prefers-color-scheme: dark) { .warn { background: #332a12; border-color: #6b5a2f; color: #e8d39a; } }
       .muted { color: #9a9a9a; font-size: .85rem; }
       .who { margin-top: 2rem; font-size: .82rem; color: #8a8a8a; }
       .who a, a.back { color: inherit; }
@@ -105,6 +120,10 @@ const backHref = `/dashboard/${encodeURIComponent(appDomain)}`;
         : " Viewing as Token of Trust staff — invite by email to grant a developer access."}</p>
       <h2>Invite a developer</h2>
+      {isQaTier && (
+        <p class="warn">⚠ This invite connects the developer to the <strong>QA</strong> environment
+          — likely not what you want.</p>
+      )}
       <div class="card">
         <label for="email">Developer email</label>
         <input id="email" type="email" placeholder="dev@agency.com" autocomplete="off" />

package/apps/storefront/src/pages/index.astro CHANGED Viewed

@@ -14,7 +14,7 @@ import CollectionCard from "@/components/CollectionCard.astro";
 import Img from "@/components/Img.astro";
 import MarketingBlocks from "@/components/marketing/MarketingBlocks.astro";
 import { withBase } from "@/lib/basePath";
-import { rawHtmlResponse } from "@/lib/rawMarketingHtml";
+import { rawHtmlPolicy, rawHtmlResponse } from "@/lib/rawMarketingHtml";
 import type { CatalogCollection, CatalogProduct } from "@tot/public-runtime";
 import {
   isMarketingBlock,
@@ -23,7 +23,12 @@ import {
   type NewsletterBlock,
   type PromoTilesBlock,
   type MarketingBlock,
+  type FeaturedProductsBlock,
 } from "@/lib/storyblok/content-model";
+import {
+  normalizeProductSectionSource,
+} from "@tot/public-runtime";
+import { resolveSectionSource } from "@/lib/sections";
 const { tenant, tot, content, basePath, features } = Astro.locals;
 const marketing = !features.catalog;
@@ -37,22 +42,17 @@ const marketing = !features.catalog;
 // OpenGraph/JSON-LD come from the document's own <head>. The homepage `/` is in
 // the marketing sitemap (sitemap.xml.ts).
 //
-// Served regardless of siteType: a tenant that ships home.html gets its raw
-// marketing home whether or not commerce is on. This is the HYBRID tenant —
-// pixel-perfect marketing chrome at `/` surrounding a live commerce core at
-// /collections + /products/* (see playbook/site-migration/commerce-handoff.md §1
-// and product-boundaries.md). Commerce tenants with no home.html fall through to
-// the block-composed home below, unchanged. Mirrors the raw-subpage path in
-// [...slug].astro (getPageHtml is already siteType-agnostic).
-{
-  const rawHtml = await content.getHomeHtml();
-  if (rawHtml) {
-    // Shared chrome: if the tenant ships a chrome.html wrapper AND this home is a
-    // body-only fragment, rawHtmlResponse splices it in; a full document serves
-    // verbatim (backward-compatible).
-    const chromeWrapper = await content.getChromeHtml();
-    return rawHtmlResponse(rawHtml, { nonce: Astro.locals.cspNonce, basePath, chromeWrapper });
-  }
+// Allowed only when rawHtmlPolicy says the tenant can safely bypass Layout.
+// Regulated tenants fall through to the block-composed home so platform
+// age/identity, warning, tax, and checkout guardrails remain non-removable.
+// Mirrors the raw-subpage path in [...slug].astro.
+const rawHtml = await content.getHomeHtml();
+if (rawHtml && rawHtmlPolicy(tenant).allowed) {
+  // Shared chrome: if the tenant ships a chrome.html wrapper AND this home is a
+  // body-only fragment, rawHtmlResponse splices it in; a full document serves
+  // verbatim (backward-compatible).
+  const chromeWrapper = await content.getChromeHtml();
+  return rawHtmlResponse(rawHtml, { nonce: Astro.locals.cspNonce, basePath, chromeWrapper });
 }
 const home = await content.getHome();
@@ -75,21 +75,15 @@ type Resolved =
   | { kind: "newsletter"; block: NewsletterBlock };
 async function resolveProducts(
-  source: "featured" | "newest",
+  source: FeaturedProductsBlock["source"],
   handles: string[] | undefined,
   limit: number,
 ): Promise<CatalogProduct[]> {
-  if (handles?.length) {
-    const all = await Promise.all(handles.map((h) => tot.getProductByHandle(h)));
-    return all
-      .filter((p): p is CatalogProduct => !!p && p.status === "active")
-      .slice(0, limit);
-  }
-  if (source === "newest") {
-    const { products } = await tot.listProducts({ sort: "newest", pageSize: limit });
-    return products;
-  }
-  return tot.getFeatured(limit);
+  return resolveSectionSource(
+    normalizeProductSectionSource(source, handles),
+    tot,
+    limit,
+  );
 }
 const resolved: Resolved[] = [];

package/apps/storefront/src/pages/products/[handle].astro CHANGED Viewed

@@ -17,9 +17,15 @@ import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
 import ReviewSummary from "@/components/commerce/ReviewSummary.astro";
 import ReviewList from "@/components/commerce/ReviewList.astro";
 import { isOnSale, isNew, isAvailable, fromPrice } from "@/lib/tot/query";
-import { buildVariantCartPayload } from "@tot/public-runtime";
-import type { VariantCartPayload } from "@tot/public-runtime";
-import { readCartSecret } from "@/lib/foxyCommerce";
+import {
+  buildVariantCartPayload,
+  normalizePurchaseOptions,
+} from "@tot/public-runtime";
+import type {
+  ProductPurchaseOption,
+  VariantCartPayload,
+} from "@tot/public-runtime";
+import { readCartSecret } from "@/lib/checkoutCommerce";
 import { truncate } from "@/lib/format";
 import { productLd, breadcrumbLd, reviewLd } from "@/lib/jsonld";
 import { isUsableImageUrl } from "@/lib/placeholder";
@@ -138,29 +144,53 @@ const reviews = await tot.getReviews(product.handle);
 const onSale = isOnSale(product);
 const available = isAvailable(product);
-// FoxyCart add-to-cart (Track A). Pre-build each variant's cart payload server-
+// Managed add-to-cart (Track A). Pre-build each variant's cart payload server-
 // side so the island can render a signed, tamper-proof form. In `signed` mode a
 // missing secret means we render NO cart (never a tamperable form); the
 // `unsigned-demo` mode needs no secret. Drafts still get a cart (preview links).
-let foxyCart:
-  | { action: string; byVariantId: Record<string, VariantCartPayload> }
+let checkoutCart:
+  | {
+      action: string;
+      purchaseOptions: ProductPurchaseOption[];
+      byVariantId: Record<string, Record<string, VariantCartPayload>>;
+    }
   | undefined;
 if (commerce) {
   const secret = await readCartSecret(commerce);
   if (commerce.mode !== "signed" || secret) {
-    const entries = await Promise.all(
-      product.variants.map(
-        async (v) =>
-          [
-            v.id,
-            await buildVariantCartPayload(product, v, {
-              mode: commerce.mode,
-              secret,
-            }),
-          ] as const,
-      ),
-    );
-    foxyCart = { action: commerce.cartUrl, byVariantId: Object.fromEntries(entries) };
+    try {
+      const purchaseOptions = normalizePurchaseOptions(product);
+      const entries = await Promise.all(
+        product.variants.map(
+          async (v) => {
+            const payloads = await Promise.all(
+              purchaseOptions.map(
+                async (purchaseOption) =>
+                  [
+                    purchaseOption.id,
+                    await buildVariantCartPayload(product, v, {
+                      mode: commerce.mode,
+                      secret,
+                      purchaseOption,
+                    }),
+                  ] as const,
+              ),
+            );
+            return [v.id, Object.fromEntries(payloads)] as const;
+          },
+        ),
+      );
+      checkoutCart = {
+        action: commerce.cartUrl,
+        purchaseOptions,
+        byVariantId: Object.fromEntries(entries),
+      };
+    } catch (err) {
+      console.warn(
+        `[storefront] Invalid checkout purchase options for ${product.handle}; cart disabled for this product.`,
+        err,
+      );
+    }
   }
 }
@@ -268,7 +298,7 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
           options={product.options}
           currency={product.price_range.currency}
           locale={tenant.locale}
-          foxyCart={foxyCart}
+          checkoutCart={checkoutCart}
         />
         <button
           type="button"

package/package.json CHANGED Viewed

@@ -1,12 +1,16 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "1.3.2",
+  "version": "1.3.4-rc.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.12.0"
   },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "scripts": {
     "dev": "pnpm --filter @tot/storefront-runner dev",
     "build": "pnpm --filter @tot/storefront-runner build",

package/packages/public-runtime/src/capabilities.ts CHANGED Viewed

@@ -1,10 +1,16 @@
 /**
  * Tenant capability switches — config that travels with the PR (Track A/B).
  *
- * Three independently-toggleable capabilities:
- *   - cartCheckout      — FoxyCart cart/checkout ("Powered by FoxyCart", Track A)
+ * Three capability states:
+ *   - cartCheckout      — managed cart/checkout (Track A)
  *   - ageVerification   — Token of Trust age/identity gate (21+ regulated)
- *   - exciseTax         — excise tax collection at checkout (Track B, tot-foxycart)
+ *   - exciseTax         — excise tax collection at checkout (Track B, commerce service)
+ *
+ * Important: these are configurable surfaces, not compliance obligations. A
+ * tenant repo may request that a surface turn off, but `resolveCapabilities`
+ * reapplies the compliance floor after every override. Developers can disable
+ * optional commerce affordances; they cannot disable required age/identity or
+ * excise-tax enforcement for regulated tenants.
  *
  * The source of truth is the tenant repo's `.tot/config.json` `capabilities`
  * block — so a change is a code change that travels with a PR. Resolution is
@@ -23,16 +29,28 @@ export interface CapabilityState {
 }
 export interface CapabilityConfig {
-  /** FoxyCart cart/checkout: loader + signed add-to-cart. */
+  /** Managed cart/checkout: loader + signed add-to-cart. */
   cartCheckout: CapabilityState;
   /** Token of Trust age/identity verification (soft 21+ gate now; full ToT later). */
   ageVerification: CapabilityState;
-  /** Excise tax collection at checkout (materialized in the FoxyCart cart). */
+  /** Excise tax collection at checkout (materialized in the managed cart). */
   exciseTax: CapabilityState;
 }
 export type CapabilityKey = keyof CapabilityConfig;
+export interface CapabilityObligation {
+  required: boolean;
+  reason?: string;
+}
+export type CapabilityObligations = Record<CapabilityKey, CapabilityObligation>;
+export interface CapabilityFloorViolation {
+  capability: CapabilityKey;
+  reason: string;
+}
 /** Stable capability order + labels for any surface that lists them. */
 export const CAPABILITY_KEYS: CapabilityKey[] = [
   "cartCheckout",
@@ -49,6 +67,58 @@ export function capabilitiesArtifactPath(tenantId: string): string {
   return `tenants/${tenantId}/capabilities.json`;
 }
+/**
+ * Resolve the non-negotiable compliance floor for a tenant. This is intentionally
+ * narrower than feature defaults: it says only what MUST remain on for the site
+ * to be publishable.
+ */
+export function resolveComplianceObligations(
+  tenant: Pick<TenantConfig, "compliance" | "siteType">,
+): CapabilityObligations {
+  return {
+    cartCheckout: { required: false },
+    ageVerification: tenant.compliance?.minAge
+      ? {
+          required: true,
+          reason: `Tenant requires age/identity verification for ${tenant.compliance.minAge}+ access.`,
+        }
+      : { required: false },
+    exciseTax: tenant.compliance?.nicotineWarning
+      ? {
+          required: true,
+          reason:
+            "Tenant sells nicotine/vape products and must keep excise-tax collection enabled at checkout.",
+        }
+      : { required: false },
+  };
+}
+/**
+ * Find attempted overrides that weaken the compliance floor. This is used by
+ * validators to fail a publish early; `resolveCapabilities` also enforces the
+ * same floor at runtime as defense in depth.
+ */
+export function capabilityFloorViolations(
+  tenant: Pick<TenantConfig, "compliance" | "siteType">,
+  requested?: Partial<CapabilityConfig> | null,
+): CapabilityFloorViolation[] {
+  if (!requested) return [];
+  const obligations = resolveComplianceObligations(tenant);
+  const out: CapabilityFloorViolation[] = [];
+  for (const key of CAPABILITY_KEYS) {
+    if (
+      obligations[key].required &&
+      requested[key]?.enabled === false
+    ) {
+      out.push({
+        capability: key,
+        reason: obligations[key].reason ?? `${key} is required for this tenant.`,
+      });
+    }
+  }
+  return out;
+}
 /**
  * Resolve a tenant's effective capabilities: build-time `TenantConfig.capabilities`
  * default (itself defaulted from siteType/compliance), then any per-environment
@@ -74,16 +144,34 @@ export function resolveCapabilities(
       enabled: c?.exciseTax?.enabled ?? !!tenant.compliance?.nicotineWarning,
     },
   };
-  if (!override) return base;
+  const requested = override
+    ? {
+        cartCheckout: {
+          enabled: override.cartCheckout?.enabled ?? base.cartCheckout.enabled,
+        },
+        ageVerification: {
+          enabled:
+            override.ageVerification?.enabled ?? base.ageVerification.enabled,
+        },
+        exciseTax: {
+          enabled: override.exciseTax?.enabled ?? base.exciseTax.enabled,
+        },
+      }
+    : base;
+  const obligations = resolveComplianceObligations(tenant);
   return {
     cartCheckout: {
-      enabled: override.cartCheckout?.enabled ?? base.cartCheckout.enabled,
+      enabled:
+        obligations.cartCheckout.required || requested.cartCheckout.enabled,
     },
     ageVerification: {
-      enabled: override.ageVerification?.enabled ?? base.ageVerification.enabled,
+      enabled:
+        obligations.ageVerification.required ||
+        requested.ageVerification.enabled,
     },
     exciseTax: {
-      enabled: override.exciseTax?.enabled ?? base.exciseTax.enabled,
+      enabled: obligations.exciseTax.required || requested.exciseTax.enabled,
     },
   };
 }

package/packages/public-runtime/src/{foxy-orders.ts → checkout-orders.ts} RENAMED Viewed

@@ -1,11 +1,12 @@
 /**
  * Order READ DTO — the FROZEN v1 contract shape the storefront consumes from
- * tot-foxycart's `GET /commerce/orders[/:orderId]` (card 8585 / U1). Kept in
+ * the checkout order API's `GET /commerce/orders[/:orderId]` (card 8585 / U1). Kept in
  * `@tot/public-runtime` (types only, no secrets, edge-safe) so the server-side
  * order client (U2), the Orders admin route (U2), and the view-model mapping (U3)
  * all code against one source of truth.
  *
- * Authoritative spec: `docs/storefront-foxycart-contract.md` §9 (tot-foxycart).
+ * Authoritative API shape lives with the checkout order service; this file
+ * freezes the storefront-facing v1 DTO.
  *
  * READ-ONLY (scope-locks): no write/mutation shapes here. Two fields are
  * ENRICHED-later by U4 (the tot20 identity/age join) and are `null`/`[]` until
@@ -15,52 +16,52 @@
  */
 /** Payment state of an order. */
-export type FoxyOrderPayment = "authorized" | "captured" | "refunded";
+export type CheckoutOrderPayment = "authorized" | "captured" | "refunded";
 /** Fulfillment / queue state of an order. */
-export type FoxyOrderFulfillment =
+export type CheckoutOrderFulfillment =
   | "unfulfilled"
   | "ready_to_ship"
   | "hold_review_required"
   | "completed";
-export interface FoxyOrderCustomer {
+export interface CheckoutOrderCustomer {
   /** ToT-core customer id, or null for a guest / unlinked order. */
   id: string | null;
   name: string;
 }
 /** A row in the orders list. All fields populated by U1 EXCEPT `verification`. */
-export interface FoxyOrderSummary {
+export interface CheckoutOrderSummary {
   /** Order / transaction id (string). */
   id: string;
   /** ISO 8601 placed-at timestamp. */
   placedAt: string;
   currency: string;
-  customer: FoxyOrderCustomer;
+  customer: CheckoutOrderCustomer;
   /** Human one-liner, e.g. "Vape Pen Starter Kit +1 more". */
   itemsSummary: string;
   itemCount: number;
   /** Order total in MAJOR currency units (e.g. dollars). */
   total: number;
-  payment: FoxyOrderPayment;
-  fulfillment: FoxyOrderFulfillment;
+  payment: CheckoutOrderPayment;
+  fulfillment: CheckoutOrderFulfillment;
   /** Why the order is held, or null. */
   blocker: string | null;
   /**
    * Identity/age verification summary — ENRICHED by U4 (tot20 join). `null` from
    * U1; consumers render risk as "pending" until it is filled.
    */
-  verification: FoxyOrderVerification | null;
+  verification: CheckoutOrderVerification | null;
 }
 /** U4-filled verification summary (shape reserved; opaque to U1/U2/U3). */
-export interface FoxyOrderVerification {
+export interface CheckoutOrderVerification {
   riskLevel?: string;
   [k: string]: unknown;
 }
-export interface FoxyOrderLineItem {
+export interface CheckoutOrderLineItem {
   sku: string;
   name: string;
   quantity: number;
@@ -68,7 +69,7 @@ export interface FoxyOrderLineItem {
   unitPrice: number;
 }
-export interface FoxyOrderTotals {
+export interface CheckoutOrderTotals {
   subtotal: number;
   shipping: number;
   estimatedTax: number;
@@ -76,7 +77,7 @@ export interface FoxyOrderTotals {
   total: number;
 }
-export interface FoxyOrderShippingAddress {
+export interface CheckoutOrderShippingAddress {
   line1: string;
   line2: string;
   city: string;
@@ -87,21 +88,21 @@ export interface FoxyOrderShippingAddress {
 }
 /** U4-filled per-order verification detail; `readinessChecks`/`evidenceTimeline` empty from U1. */
-export interface FoxyOrderVerificationDetail {
+export interface CheckoutOrderVerificationDetail {
   readinessChecks: unknown[];
   evidenceTimeline: unknown[];
 }
 /** A single order's full detail (summary + line items, totals, address, verification detail). */
-export interface FoxyOrderDetail extends FoxyOrderSummary {
+export interface CheckoutOrderDetail extends CheckoutOrderSummary {
   /** The excise line (TOT_EXCISE_TAX) is NOT here — it surfaces in totals.taxesAndFees. */
-  lineItems: FoxyOrderLineItem[];
-  totals: FoxyOrderTotals;
-  shippingAddress: FoxyOrderShippingAddress | null;
-  verificationDetail: FoxyOrderVerificationDetail;
+  lineItems: CheckoutOrderLineItem[];
+  totals: CheckoutOrderTotals;
+  shippingAddress: CheckoutOrderShippingAddress | null;
+  verificationDetail: CheckoutOrderVerificationDetail;
 }
-export interface FoxyOrderPage {
+export interface CheckoutOrderPage {
   limit: number;
   cursor: string | null;
   /** Opaque cursor for the next page, or null on the last page. */
@@ -111,18 +112,18 @@ export interface FoxyOrderPage {
 }
 /** `GET /commerce/orders` response envelope. */
-export interface FoxyOrderListResponse {
-  orders: FoxyOrderSummary[];
-  page: FoxyOrderPage;
+export interface CheckoutOrderListResponse {
+  orders: CheckoutOrderSummary[];
+  page: CheckoutOrderPage;
 }
 /** `GET /commerce/orders/:orderId` response envelope. */
-export interface FoxyOrderDetailResponse {
-  order: FoxyOrderDetail;
+export interface CheckoutOrderDetailResponse {
+  order: CheckoutOrderDetail;
 }
 /** Optional list filters (all server-side; see contract §9). */
-export interface FoxyOrderListFilters {
+export interface CheckoutOrderListFilters {
   queue?: string;
   status?: string;
   /** ISO datetime lower bound. */

package/packages/public-runtime/src/checkout-style-publish.ts CHANGED Viewed

@@ -1,16 +1,16 @@
 /**
- * Signed storefront → FoxyCart theme-publish client (U11b, the PUSH half of U11).
+ * Signed storefront → checkout theme-publish client (U11b, the PUSH half of U11).
  *
- * Points a store's Foxy checkout template at the storefront-hosted stylesheet
- * (`GET /api/checkout-style.css`, U11) by driving tot-foxycart's `/theme/foxy`
+ * Points a store's hosted checkout template at the storefront-hosted stylesheet
+ * (`GET /api/checkout-style.css`, U11) by driving the commerce service's theme
  * endpoint: PUT the `content_url`, then POST `/refresh` (PUT alone only sets the
- * pointer — Foxy caches the template, so nothing goes live until refresh).
+ * pointer — checkout caches the template, so nothing goes live until refresh).
  *
  * AUTH: each request carries an `x-tot-signature` header = lowercase-hex
  * HMAC-SHA256 of `JSON.stringify(body)` keyed by the STORE'S ToT SECRET KEY —
- * byte-identical to tot-foxycart's `foxyStore.verifyWebhookSignature`. That
+ * byte-identical to the commerce service's webhook-signature verifier. That
  * secret is the storefront's `TOT_SECRET_KEY`; this is independent of the
- * FoxyCart hAPI credentials (see decision `u11b-not-blocked-by-u7`).
+ * provider API credentials (see decision `u11b-not-blocked-by-u7`).
  *
  * Edge-safe + node-free (WebCrypto HMAC); the network call is injected so the
  * flow is fully unit-testable offline. The caller (the checkout-styling promote
@@ -19,10 +19,10 @@
  */
 import type { CustomizationEnv } from "./customization-preview.js";
-/** Header tot-foxycart reads the HMAC from (matches foxyThemeEndpoint SIGNATURE_HEADER). */
+/** Header the commerce service reads the HMAC from. */
 export const TOT_SIGNATURE_HEADER = "x-tot-signature";
-/** Foxy caps content_url at 300 chars; '' detaches the template (revert to default). */
+/** The provider caps content_url at 300 chars; '' detaches the template. */
 export const MAX_CONTENT_URL = 300;
 /** Fetch shape we depend on — the platform `fetch`, injectable for tests. */
@@ -36,15 +36,15 @@ export type FetchLike = (
 ) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
 export interface ThemePublishTarget {
-  /** tot-foxycart proxy base, e.g. `https://foxycart-test.tokenoftrust.com`. */
-  foxyBaseUrl: string;
-  /** The store's app domain / subdomain (tot-foxycart resolves the store from it). */
+  /** Commerce service base URL for the checkout proxy. */
+  checkoutServiceBaseUrl: string;
+  /** The store's app domain / subdomain (the service resolves the store from it). */
   appDomain: string;
-  /** The hosted stylesheet URL Foxy will fetch (U11's `/api/checkout-style.css`). */
+  /** The hosted stylesheet URL checkout will fetch (U11's `/api/checkout-style.css`). */
   contentUrl: string;
   /** The store's ToT secret key (storefront `TOT_SECRET_KEY`) — signs the request. */
   secret: string;
-  /** Foxy template to target; checkout styling uses `checkout` (the default). */
+  /** Checkout template to target; checkout styling uses `checkout` (the default). */
   templateType?: string;
 }
@@ -58,7 +58,7 @@ export interface ThemePublishResult {
   error?: string;
 }
-/** Lowercase-hex HMAC-SHA256(message) under `secret` (WebCrypto). Matches foxy.ts. */
+/** Lowercase-hex HMAC-SHA256(message) under `secret` (WebCrypto). */
 async function hmacHex(secret: string, message: string): Promise<string> {
   const enc = new TextEncoder();
   const key = await crypto.subtle.importKey(
@@ -75,8 +75,8 @@ async function hmacHex(secret: string, message: string): Promise<string> {
 }
 /**
- * The exact signature tot-foxycart verifies: hex HMAC-SHA256 of the JSON body
- * string under the store secret. Exported so the promote hook and tests can
+ * The exact commerce-service signature: hex HMAC-SHA256 of the JSON body string
+ * under the store secret. Exported so the promote hook and tests can
  * compute/assert it identically.
  */
 export function signThemeRequestBody(
@@ -88,9 +88,9 @@ export function signThemeRequestBody(
 /**
  * The canonical, stable content_url a store's checkout template points at — the
- * U11 route on the store's own host, so Foxy's server-side fetch self-identifies
- * the tenant + env. Returns null if it would exceed Foxy's 300-char cap (so the
- * caller surfaces a config error rather than pushing a URL Foxy will reject).
+ * U11 route on the store's own host, so the server-side fetch self-identifies
+ * the tenant + env. Returns null if it would exceed the provider's 300-char cap
+ * so the caller surfaces a config error before pushing a URL checkout will reject.
  */
 export function checkoutStyleContentUrl(
   host: string,
@@ -114,7 +114,7 @@ async function readErr(
 }
 /**
- * Publish a store's checkout styling to Foxy: signed PUT `/theme/foxy` then
+ * Publish a store's checkout styling: signed PUT `/theme/foxy` then
  * signed POST `/theme/foxy/refresh`. Returns a discriminated result — we do NOT
  * fail open: if the PUT fails we skip the refresh and report the error, so the
  * caller never reports "published" for something that didn't take.
@@ -127,7 +127,7 @@ export async function publishCheckoutTheme(
 ): Promise<ThemePublishResult> {
   const doFetch = fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
   const templateType = target.templateType ?? "checkout";
-  const base = target.foxyBaseUrl.replace(/\/+$/, "");
+  const base = target.checkoutServiceBaseUrl.replace(/\/+$/, "");
   if (
     target.contentUrl !== "" &&
@@ -188,11 +188,11 @@ export async function publishCheckoutTheme(
 }
 /**
- * Convenience: the env → Foxy-proxy base URL for this workstream's targets.
- * qa runs NODE_ENV=test (proxy `foxycart-test`); sandbox → `foxycart-sandbox`;
- * live → the prod proxy. Kept here so the promote hook (U13) resolves one place.
+ * Convenience: the env → checkout service base URL for this workstream's targets.
+ * qa/test use the non-prod proxy; live uses the prod proxy. Kept here so the
+ * promote hook (U13) resolves one place.
  */
-export function foxyProxyBaseUrl(env: CustomizationEnv): string {
+export function checkoutServiceBaseUrl(env: CustomizationEnv): string {
   // "test" is the qa target's env; "live" is prod.
   return env === "live"
     ? "https://foxycart.tokenoftrust.com"