@wix/himalaya-cli 0.1493.0 → 0.1495.0

package/templates/retail-store/himalaya.content.json

@@ -53,7 +53,7 @@
       "displayName": "Orders"
     },
     "himi_product": {
-      "displayName": "Product"
+      "displayName": "Product Details"
     },
     "himi_saved": {
       "displayName": "Saved"

package/templates/retail-store/tier5-src/_shared/himi-store-collection.ts

@@ -7,9 +7,12 @@ export const storeCollectionSaving: CollectionSaving = {
     const products = new Map(readSavedProducts().map(row => [row.id, row]));
     for (const row of rows) {
       if (typeof row.id !== 'string' || typeof row.name !== 'string') continue;
-      products.set(row.id, { id: row.id, name: row.name,
-        price: typeof row.commercePrice === 'string' ? row.commercePrice : typeof row.subtitle === 'string' ? row.subtitle : '',
-        image: typeof row.image === 'string' ? row.image : '' });
+      const previous = products.get(row.id);
+      const freshPrice = typeof row.commercePrice === 'string' ? row.commercePrice : typeof row.subtitle === 'string' ? row.subtitle : '';
+      const wasPrice = typeof row.wasPrice === 'string' ? row.wasPrice || undefined : previous?.price === freshPrice ? previous?.wasPrice : undefined;
+      products.set(row.id, { ...previous, wasPrice, id: row.id, name: row.name,
+        price: freshPrice || previous?.price || '',
+        image: typeof row.image === 'string' && row.image ? row.image : previous?.image ?? '' });
     }
     const selected = ids.map(id => products.get(id));
     if (selected.some(row => !row)) throw new Error('Saved product metadata is unavailable');

package/templates/retail-store/tier5-src/_shared/himi-store-saved.ts

@@ -5,6 +5,8 @@ export interface SavedProduct {
   name: string;
   price: string;
   image: string;
+  wasPrice?: string;
+  swatches?: string[];
 }
 type StorageLike = { getItem(key: string): string | null; setItem(key: string, value: string): void };
 const KEY = "himi-store:saved-products:v1";
@@ -24,7 +26,11 @@ export function readSavedProducts(): SavedProduct[] {
     if (!value || typeof value !== "object") continue;
     const row = value as Record<string, unknown>;
     if (typeof row.id !== "string" || !row.id.trim() || typeof row.name !== "string") continue;
-    rows.set(row.id, { id: row.id, name: row.name, price: typeof row.price === "string" ? row.price : "", image: typeof row.image === "string" ? row.image : "" });
+    const swatches = Array.isArray(row.swatches)
+      ? row.swatches.filter((color): color is string => typeof color === "string" && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(color)).slice(0, 5)
+      : [];
+    rows.set(row.id, { id: row.id, name: row.name, price: typeof row.price === "string" ? row.price : "", image: typeof row.image === "string" ? row.image : "",
+      ...(typeof row.wasPrice === "string" && row.wasPrice ? { wasPrice: row.wasPrice } : {}), ...(swatches.length ? { swatches } : {}) });
   }
   return [...rows.values()];
 }

package/templates/retail-store/tier5-src/_shared/wix-service-price.ts

@@ -99,6 +99,24 @@ export function serviceIsChargeable(service: unknown): boolean {
   return amount != null && amount > 0;
 }
 
+/**
+ * Format one Bookings v2 Money value (`{ value, currency }`, `value` a decimal string) — a
+ * price, a deposit, a VARIED minimum, a cancellation fee. A whole amount drops its cents
+ * ("₪90", not "₪90.00"), as the service screen shows it. "" when it carries no usable
+ * amount. The currency comes from the Money itself, then from `fallbackCurrency`.
+ */
+export function formatServiceMoney(money: unknown, fallbackCurrency = "USD"): string {
+  const m = (money ?? {}) as { value?: unknown; amount?: unknown; currency?: unknown };
+  const amount = numberOf(m.value ?? m.amount);
+  if (amount == null) return "";
+  const currency = stringOf(m.currency) || fallbackCurrency;
+  try {
+    return formatCurrency(amount, currency, "en", Number.isInteger(amount) ? 0 : undefined);
+  } catch {
+    return `${amount}`;
+  }
+}
+
 /**
  * Format a Wix Bookings service's price for display, e.g. "₪111" / "$20".
  *

package/templates/retail-store/tier5-src/himi-branded-lite-cart/index.ts

@@ -2,11 +2,12 @@ import { getStoreProduct } from "../_shared/himi-store.js";
 import { iapPriceCopy } from "../_shared/iap-worker.js";
 import { withIapPresentation } from "../_shared/iap-presentation.js";
 import { type IapCommerce, classifyCart } from "@himalaya/iap-checkout";
-import { createCheckoutFromCurrentCart, createOrder, getCurrentCart, removeLineItemsFromCurrentCart, updateLineItemsQuantity, type WixCartLineItemDetail } from "@himalaya/wix-ecom";
+import { addCouponToCurrentCart, calculateCurrentCart, createCheckoutFromCurrentCart, createOrder, getCurrentCart, removeCouponFromCurrentCart, removeLineItemsFromCurrentCart, updateLineItemsQuantity, type WixCartDetail, type WixCartLineItemDetail } from "@himalaya/wix-ecom";
 import { createRedirectSession } from "@himalaya/wix-redirects";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { payCashierOrder } from "@himalaya/checkout";
 import { hostedCheckoutOpener, isHostedWorker } from "../_shared/hosted-checkout.js";
+import { formatCurrency } from "../_shared/engine-intl.js";
 
 /** Wix Stores appDefId — the vertical that owns a cart/ecom order, and therefore the
  *  `appId` its cashier order is paid under. (Same constant Wix's own tooling uses.) */
@@ -26,6 +27,7 @@ async function resolveMsid(): Promise<string> {
 import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
 import { getAll, upsert, remove as dbRemove, type DbEntity } from "@himalaya/local-db";
 import { isOfflineFailure, writeMayHaveLanded } from "../_shared/owner-load-error.js";
+import { isProductSaved, readSavedProducts, toggleSavedProduct } from "../_shared/himi-store-saved.js";
 
 // Offline-first (data-offline): the cart is READ-THROUGH — paint the last-synced line
 // items from the on-device `cart` entity first (instant, works offline), then
@@ -36,8 +38,37 @@ import { isOfflineFailure, writeMayHaveLanded } from "../_shared/owner-load-erro
 // The checkout redirect path is unchanged. Every local-db call is wrapped so a build
 // without the `local_database` grant behaves exactly as before (online-only).
 const ENTITY = "cart";
+function cachedUnitPrice(total: string, quantity: number): string {
+  if (quantity <= 1) return total;
+  const match = /\d(?:[\d.,]|[ \u00a0\u202f](?=\d))*/u.exec(total);
+  if (!match) return total;
+  const raw = match[0];
+  const compact = raw.replace(/[ \u00a0\u202f]/g, "");
+  const last = Math.max(compact.lastIndexOf("."), compact.lastIndexOf(","));
+  const digits = last >= 0 && compact.length - last - 1 <= 2 ? compact.length - last - 1 : 0;
+  const decimal = digits ? compact[last] : ".";
+  const numeric = digits ? `${compact.slice(0, last).replace(/[,.]/g, "")}.${compact.slice(last + 1)}` : compact.replace(/[,.]/g, "");
+  const amount = Number(numeric);
+  if (!Number.isFinite(amount)) return total;
+  const [whole, fraction] = (amount / quantity).toFixed(digits).split(".");
+  const spaceGrouping = raw.match(/[ \u00a0\u202f](?=\d)/u)?.[0];
+  const grouped = spaceGrouping ? whole.replace(/\B(?=(\d{3})+(?!\d))/g, spaceGrouping) : whole;
+  return total.replace(raw, `${grouped}${digits ? decimal + fraction : ""}`);
+}
 async function readCachedItems(): Promise<Row[]> {
-  try { return (await getAll(ENTITY)) as unknown as Row[]; } catch { return []; }
+  try {
+    return ((await getAll(ENTITY)) as unknown as Row[]).map(item => {
+      const quantity = Math.max(1, Math.floor(Number(item.quantity) || 1));
+      let saved = false;
+      try { saved = isProductSaved(item.catalogReference?.catalogItemId ?? item.productId ?? ""); } catch { /* keep the cached line usable */ }
+      const unitPrice = item.unitPrice || cachedUnitPrice(item.total || item.commerceTotal || "", quantity);
+      return { ...item, catalogItemId: item.catalogReference?.catalogItemId ?? item.productId ?? "", quantity, quantityLabel: String(quantity), atMinQuantity: quantity <= 1, unitPrice,
+        wasPrice: item.wasPrice ?? "", swatches: item.swatches ?? [], option1: item.option1 ?? "", option2: item.option2 ?? "", option3: item.option3 ?? "",
+        noOption1: !item.option1, noOption2: !item.option2, noOption3: !item.option3,
+        stockMessage: item.stockMessage ?? "", noStockMessage: !item.stockMessage,
+        inStockMessage: item.inStockMessage ?? "", noInStockMessage: !item.inStockMessage, saved, notSaved: !saved };
+    });
+  } catch { return []; }
 }
 /** Mirror the cart Wix returned: upsert its lines and drop any cached line it no longer has
  *  (one removed elsewhere, or a removal whose answer was lost), so the offline paint never
@@ -54,6 +85,8 @@ async function cacheDrop(id: string): Promise<void> { try { await dbRemove(ENTIT
 
 interface Row {
   catalogReference?: { appId: string; catalogItemId: string; options?: Record<string, unknown> };
+  productId?: string;
+  catalogItemId?: string;
   id: string;
   name: string;
   title: string;
@@ -64,19 +97,45 @@ interface Row {
   /** The "−" control at qty 1 removes the line, so it never dead-ends. */
   atMinQuantity: boolean;
   total: string;
+  unitPrice: string;
+  wasPrice?: string;
+  swatches?: string[];
   commerceTotal: string;
   image: string;
   initial: string;
   hasImage: boolean;
   noImage: boolean;
+  option1: string; option2: string; option3: string;
+  noOption1: boolean; noOption2: boolean; noOption3: boolean;
+  stockMessage: string; noStockMessage: boolean;
+  inStockMessage: string; noInStockMessage: boolean;
+  saved: boolean;
+  notSaved: boolean;
 }
 interface State {
   status: "loading" | "ready" | "error";
+  errorKind: "offline" | "server" | "";
   items: Row[];
   subtotal: string;
   commerceSubtotal?: string;
   emptyText: string;
   checkoutHint: string;
+  itemCount: number;
+  promoCode: string;
+  appliedCode: string;
+  appliedLabel: string;
+  couponId: string;
+  promoError: string;
+  promoBusy: boolean;
+  noPromoError: boolean;
+  hasCoupon: boolean;
+  discount: string;
+  noDiscount: boolean;
+  noCheckoutHint: boolean;
+  showPaidToast: boolean;
+  noPaidToast: boolean;
+  noCoupon: boolean;
+  subtotalLabel: string;
   isLoading: boolean;
   notLoading: boolean;
   /** Standard error quad (the himi-store retryBlock contract): the descriptor
@@ -84,6 +143,8 @@ interface State {
    *  failed load shows the retry card instead of a blank list + blank subtotal. */
   isErrored: boolean;
   notErrored: boolean;
+  noOfflineError: boolean;
+  noServerError: boolean;
   hideContent: boolean;
   noEmpty: boolean;
   noItems: boolean;
@@ -91,7 +152,14 @@ interface State {
 
 function itemId(arg: unknown): string {
   if (typeof arg === "string") return arg;
-  return (arg as { id?: string } | undefined)?.id ?? "";
+  if (!arg || typeof arg !== "object") return "";
+  const payload = arg as {
+    id?: string;
+    item?: { id?: string };
+    args?: { id?: string };
+    params?: { id?: string };
+  };
+  return payload.id ?? payload.item?.id ?? payload.args?.id ?? payload.params?.id ?? "";
 }
 
 function mediaUrl(value: unknown): string {
@@ -130,11 +198,37 @@ function mediaUrl(value: unknown): string {
 }
 
 function row(item: WixCartLineItemDetail, index: number): Row {
+  const raw = item as WixCartLineItemDetail & Record<string, unknown>;
   const quantity = item.quantity ?? 1;
   const name = item.productName?.original || copyParam("cart.itemFallbackName", "Cart item");
   const image = mediaUrl(item);
+  const lines = Array.isArray(raw.descriptionLines) ? raw.descriptionLines as Array<{ name?: { original?: string }; plainText?: { original?: string }; colorInfo?: { original?: string; code?: string } }> : [];
+  const opts = lines.slice(0, 3).map(line => {
+    const label = line.name?.original?.trim() ?? "";
+    const name = label && label === label.toUpperCase() ? label.charAt(0) + label.slice(1).toLowerCase() : label;
+    const value = line.plainText?.original || line.colorInfo?.original || "";
+    return [name, value].filter(Boolean).join(": ");
+  });
+  const inventory = raw.inventory as { quantity?: number } | undefined;
+  const availabilityData = raw.availability as { status?: string; quantityAvailable?: number } | undefined;
+  const stockCount = Number(availabilityData?.quantityAvailable ?? raw.inventoryQuantity ?? inventory?.quantity);
+  const availability = String(availabilityData?.status ?? raw.availabilityStatus ?? "").toUpperCase();
+  const stockMessage = availability === "NOT_AVAILABLE" || availability === "NOT_FOUND" || availability.includes("OUT")
+    ? copyParam("cart.outOfStock", "Out of stock")
+    : availability === "PARTIALLY_AVAILABLE" && Number.isFinite(stockCount) && stockCount > 0
+      ? copyTemplate("cart.onlyLeft", "Only {count} left", { count: stockCount }) : "";
+  const inStock = !stockMessage && (availability === "AVAILABLE" || availability === "IN_STOCK" || availability === "PARTIALLY_AVAILABLE");
+  const total = (raw.lineItemPrice as { formattedAmount?: string } | undefined)?.formattedAmount
+    ?? (raw.totalPriceAfterTax as { formattedAmount?: string } | undefined)?.formattedAmount
+    ?? (raw.totalPriceBeforeTax as { formattedAmount?: string } | undefined)?.formattedAmount
+    ?? item.price?.formattedAmount ?? "";
+  const unitPrice = item.price?.formattedAmount ?? "";
+  const fullPrice = (raw.fullPrice as { formattedAmount?: string } | undefined)?.formattedAmount ?? "";
+  const swatches = lines.map(line => line.colorInfo?.code ?? "").filter(code => /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(code)).slice(0, 5);
+  const saved = (() => { try { return isProductSaved(String((item as WixCartLineItemDetail & { catalogReference?: { catalogItemId?: string } }).catalogReference?.catalogItemId ?? "")); } catch { return false; } })();
   return {
     catalogReference: (item as WixCartLineItemDetail & { catalogReference?: Row["catalogReference"] }).catalogReference,
+    catalogItemId: (item as WixCartLineItemDetail & { catalogReference?: Row["catalogReference"] }).catalogReference?.catalogItemId ?? "",
     id: item.id || `line-${index}`,
     name,
     title: name,
@@ -142,33 +236,66 @@ function row(item: WixCartLineItemDetail, index: number): Row {
     quantity,
     quantityLabel: `${quantity}`,
     atMinQuantity: quantity <= 1,
-    total: item.price?.formattedAmount ?? "",
-    commerceTotal: item.price?.formattedAmount ?? "",
+    total,
+    unitPrice,
+    wasPrice: fullPrice && fullPrice !== unitPrice ? fullPrice : "",
+    swatches,
+    commerceTotal: total,
     image,
     initial: (name.trim()[0] || "C").toUpperCase(),
     hasImage: Boolean(image),
     noImage: !image,
+    option1: opts[0] ?? "", option2: opts[1] ?? "", option3: opts[2] ?? "",
+    noOption1: !opts[0], noOption2: !opts[1], noOption3: !opts[2],
+    stockMessage, noStockMessage: !stockMessage,
+    inStockMessage: inStock ? copyParam("cart.inStock", "In Stock") : "",
+    noInStockMessage: !inStock,
+    saved,
+    notSaved: !saved,
   };
 }
 
 /** POST /ecom/v1/carts/{cartId}/update-line-items-quantity via @himalaya/wix-ecom. */
-function updateLineItemQuantity(cartId: string, lineItemId: string, quantity: number): Promise<unknown> {
+function updateLineItemQuantity(cartId: string, lineItemId: string, quantity: number): Promise<{ cart?: WixCartDetail }> {
   return updateLineItemsQuantity(cartId, [{ id: lineItemId, quantity: Math.max(1, quantity) }]);
 }
 
 function derive(state: State): State {
+  let savedIds: Set<string> | null = null;
+  try { savedIds = new Set(readSavedProducts().map(row => row.id)); }
+  catch { /* saved storage unavailable: retain the saved flags already shown on each row */ }
+  const items = savedIds ? state.items.map(item => {
+    const productId = item.catalogReference?.catalogItemId ?? item.productId;
+    if (!productId) return item;
+    const saved = savedIds.has(productId);
+    return { ...item, saved, notSaved: !saved };
+  }) : state.items;
+  const itemCount = items.reduce((n, item) => n + item.quantity, 0);
   return {
     ...state,
+    items,
+    promoBusy: promoInFlight && state.promoBusy,
     isLoading: state.status === "loading",
     notLoading: state.status !== "loading",
     isErrored: state.status === "error",
     notErrored: state.status !== "error",
+    noOfflineError: state.status !== "error" || state.errorKind !== "offline",
+    noServerError: state.status !== "error" || state.errorKind !== "server",
     // Exactly one of {content, error card, empty card} renders: content only on
     // "ready" (an errored cart must not paint a blank subtotal), the error card
     // on "error", the empty card on ready + no items.
     hideContent: state.status !== "ready",
-    noEmpty: state.status !== "ready" || state.items.length > 0,
-    noItems: state.items.length === 0,
+    noEmpty: state.status !== "ready" || items.length > 0,
+    noItems: items.length === 0,
+    itemCount,
+    hasCoupon: Boolean(state.appliedCode),
+    appliedLabel: state.appliedCode ? copyTemplate("cart.promoApplied", "Promo code {code}", { code: state.appliedCode }) : "",
+    noPromoError: !state.promoError,
+    noDiscount: !state.discount,
+    noCheckoutHint: !state.checkoutHint || state.showPaidToast,
+    noPaidToast: !state.showPaidToast,
+    noCoupon: !state.appliedCode,
+    subtotalLabel: copyTemplate("cart.subtotalCount", "Subtotal ({count})", { count: itemCount }),
   };
 }
 
@@ -205,21 +332,61 @@ async function removeLine(state: State, id: string): Promise<State> {
   }
 }
 
-async function refresh(state: State, checkoutHint = ""): Promise<State> {
-  const cart = await getCurrentCart();
+async function refresh(state: State, checkoutHint = "", updatedCart?: WixCartDetail, calculatedCart?: unknown): Promise<State> {
+  const cart = updatedCart ?? await getCurrentCart();
   const items = (cart.lineItems ?? []).map(row);
   await writeCachedItems(items);
+  const rawCart = cart as unknown as Record<string, unknown>;
+  const summary = (rawCart.priceSummary ?? rawCart.totals ?? {}) as Record<string, unknown>;
+  const discountRaw = (summary.discount ?? summary.discountAmount) as { formattedAmount?: string } | string | undefined;
+  const applied = couponDetails(cart);
+  let discount = formattedDiscount(typeof discountRaw === "string" ? discountRaw : discountRaw?.formattedAmount ?? "");
+  if (applied.code && !discount) {
+    const calculated = calculatedCart ?? await calculateCurrentCart().catch(() => null);
+    discount = calculatedDiscount(calculated, String(rawCart.currency ?? rawCart.paymentCurrency ?? "")) || (state.appliedCode === applied.code ? state.discount : "");
+  }
   return derive({
     ...state,
     status: "ready",
     items,
     subtotal: cart.subtotal?.formattedAmount ?? "",
     commerceSubtotal: cart.subtotal?.formattedAmount ?? "",
+    discount,
+    appliedCode: applied.code,
+    couponId: applied.id,
     emptyText: items.length ? "" : copyParam("cart.emptyText", "Your cart is empty."),
+    ...(items.length ? {} : { promoCode: "", appliedCode: "", couponId: "", discount: "", promoError: "" }),
     checkoutHint,
+    showPaidToast: false,
   });
 }
 
+function formattedDiscount(value: string): string {
+  if (!value || !/[1-9]/.test(value)) return "";
+  return /^[−-]/.test(value.trim()) ? value : `−${value}`;
+}
+
+function calculatedDiscount(result: unknown, currency: string): string {
+  const discount = (result as { summary?: { priceSummary?: { discount?: { amount?: string; convertedAmount?: string } } } } | null)?.summary?.priceSummary?.discount;
+  const amount = Number(discount?.amount);
+  if (!Number.isFinite(amount) || amount === 0 || !currency) return "";
+  return formattedDiscount(formatCurrency(Math.abs(amount), currency, "en"));
+}
+
+function invalidCouponFailure(error: unknown): boolean {
+  const status = Number((error as { status?: unknown; statusCode?: unknown } | null)?.status ?? (error as { statusCode?: unknown } | null)?.statusCode);
+  const message = String((error as Error | null)?.message ?? error ?? "");
+  return status === 400 || status === 422 || /\bHTTP (?:400|422)\b|INVALID_COUPON|COUPON_(?:NOT_FOUND|EXPIRED)/i.test(message);
+}
+
+function couponDetails(result: unknown): { id: string; code: string } {
+  const envelope = result as { cart?: Record<string, unknown> } | null;
+  const cart = envelope?.cart ?? result as Record<string, unknown> | null;
+  const discounts = cart?.appliedDiscounts as Array<{ coupon?: { id?: string; code?: string }; id?: string; code?: string }> | { discounts?: Array<{ coupon?: { id?: string; code?: string }; id?: string; code?: string }> } | undefined;
+  const coupon = (Array.isArray(discounts) ? discounts : discounts?.discounts)?.find(entry => entry.coupon?.code || entry.code);
+  return { id: coupon?.coupon?.id ?? coupon?.id ?? "", code: coupon?.coupon?.code ?? coupon?.code ?? "" };
+}
+
 /** The state slice a SETTLED order leaves behind: the order consumed the cart, so the
  *  lines AND the subtotal go with it (`refresh` and the error path both clear the pair —
  *  leaving a stale subtotal in state is the class of defect #864 fixed on the render side).
@@ -233,33 +400,41 @@ async function refresh(state: State, checkoutHint = ""): Promise<State> {
  *  the subtotal and emptyText resets were missing. It survived because nothing typechecks
  *  Tier-5 workers: esbuild erases types, and no tsconfig includes tier5-bundles-src.
  */
-function cartConsumedByOrder(): Pick<State, "items" | "subtotal" | "emptyText" | "checkoutHint"> {
+function cartConsumedByOrder(): Pick<State, "items" | "subtotal" | "emptyText" | "checkoutHint" | "showPaidToast" | "promoCode" | "appliedCode" | "couponId" | "discount"> {
   return {
     items: [],
     subtotal: "",
     emptyText: "",
     checkoutHint: copyParam("cart.checkoutPaidMessage", "Order placed. Thanks!"),
+    showPaidToast: true,
+    promoCode: "", appliedCode: "", couponId: "", discount: "",
   };
 }
 
 let cartPricing: IapCommerce;
 const defineService = withIapPresentation<State>({
   onCreate: commerce => { cartPricing = commerce; },
-  prefix: "cart", transientKeys: ["items", "subtotal"], contentActions: ["load", "remove", "increment", "decrement"],
+  prefix: "cart", transientKeys: ["items", "subtotal", "promoBusy"], contentActions: ["load", "remove", "increment", "decrement"],
   items: state => state.items.flatMap(row => row.catalogReference?.catalogItemId ? [{ reference: { kind: "storesProduct", id: row.catalogReference.catalogItemId }, commerceDisplayPrice: row.commerceTotal ?? row.total }] : []),
   present: (state, price, allowed) => ({ ...state,
     items: state.items.map(row => ({ ...row, total: row.catalogReference?.catalogItemId ? price(row.catalogReference.catalogItemId, row.commerceTotal ?? row.total) : row.total })),
     subtotal: state.items.length > 0 && state.items.every(row => row.catalogReference?.catalogItemId && allowed(row.catalogReference.catalogItemId)) ? state.commerceSubtotal ?? state.subtotal : "" }),
 });
 
+let promoInFlight = false;
 const svc = defineService<State, {
   load: (state: State, arg?: unknown) => Promise<State>;
+  setPromo: (state: State, arg?: unknown) => State;
+  beginPromo: (state: State) => State;
+  applyPromo: (state: State) => Promise<State>;
+  removePromo: (state: State) => Promise<State>;
   remove: (state: State, arg?: unknown) => Promise<State>;
+  save: (state: State, arg?: unknown) => State;
   increment: (state: State, arg?: unknown) => Promise<State>;
   decrement: (state: State, arg?: unknown) => Promise<State>;
   checkout: (state: State) => Promise<State>;
 }>("himiStoreCart", {
-  state: derive({ status: "loading", items: [], subtotal: "", emptyText: "", checkoutHint: "", isLoading: true, notLoading: false, isErrored: false, notErrored: true, hideContent: true, noEmpty: true, noItems: true }),
+  state: derive({ status: "loading", errorKind: "", items: [], subtotal: "", subtotalLabel: "", emptyText: "", checkoutHint: "", showPaidToast: false, noPaidToast: true, itemCount: 0, promoCode: "", appliedCode: "", appliedLabel: "", couponId: "", promoError: "", promoBusy: false, noPromoError: true, hasCoupon: false, discount: "", noDiscount: true, noCheckoutHint: true, noCoupon: true, isLoading: true, notLoading: false, isErrored: false, notErrored: true, noOfflineError: true, noServerError: true, hideContent: true, noEmpty: true, noItems: true }),
   actions: {
     load: async (state, arg) => {
       stashCopy(arg);
@@ -271,11 +446,61 @@ const svc = defineService<State, {
       // 2) Revalidate from Wix and refresh the cache.
       try {
         return await refresh(state);
-      } catch {
+      } catch (error) {
         // Offline / fetch failure: keep the cached items instead of a blank error state.
         return cached.length
           ? base
-          : derive({ ...state, status: "error", items: [], subtotal: "", emptyText: copyParam("cart.loadErrorText", "Cart could not load."), checkoutHint: "" });
+          : derive({ ...state, status: "error", errorKind: isOfflineFailure(error) ? "offline" : "server", items: [], subtotal: "", emptyText: copyParam("cart.loadErrorText", "Cart could not load."), checkoutHint: "" });
+      }
+    },
+    setPromo: (state, arg) => derive({ ...state, promoCode: (typeof arg === "string" ? arg : String((arg as { value?: unknown } | undefined)?.value ?? "")).slice(0, 100), promoError: "" }),
+    beginPromo: state => derive({ ...state, promoBusy: true, promoError: "" }),
+    applyPromo: async (state): Promise<State> => {
+      const code = state.promoCode.trim();
+      if (promoInFlight) return svc.getState() as State;
+      if (!code) return derive({ ...state, promoError: copyParam("cart.promoEmpty", "Enter a promo code.") });
+      promoInFlight = true;
+      let added = false;
+      try {
+        await svc.beginPromo();
+        state = svc.getState() as State;
+        await addCouponToCurrentCart(code);
+        added = true;
+        const calculated = await calculateCurrentCart().catch(() => null);
+        const refreshed = await refresh(state, "", undefined, calculated);
+        return refreshed.appliedCode
+          ? derive({ ...refreshed, promoBusy: false, promoCode: "", promoError: "" })
+          : derive({ ...refreshed, promoBusy: false, promoCode: state.promoCode, promoError: copyParam("cart.promoInvalid", "This promo code is not valid.") });
+      } catch (error) {
+        const mayHaveLanded = added || writeMayHaveLanded(error);
+        const refreshed = mayHaveLanded ? await refresh(state).catch(() => null) : null;
+        if (refreshed?.appliedCode === code) return derive({ ...refreshed, promoBusy: false, promoCode: "", promoError: "" });
+        return derive({ ...state, promoBusy: false, promoError: mayHaveLanded
+          ? copyParam("cart.promoUnconfirmed", "Could not confirm the promo code. Refresh your cart.")
+          : isOfflineFailure(error)
+            ? copyParam("cart.promoOffline", "Connect to the internet to use a promo code.")
+            : invalidCouponFailure(error)
+              ? copyParam("cart.promoInvalid", "This promo code is not valid.")
+              : copyParam("cart.promoUnavailable", "Could not apply the promo code. Try again.") });
+      } finally {
+        promoInFlight = false;
+      }
+    },
+    removePromo: async state => {
+      if (!state.couponId) return derive({ ...state, appliedCode: "", discount: "" });
+      let removed = false;
+      try {
+        await removeCouponFromCurrentCart(state.couponId);
+        removed = true;
+        await calculateCurrentCart().catch(() => null);
+        return derive({ ...(await refresh(state)), appliedCode: "", couponId: "", promoError: "" });
+      } catch (error) {
+        const mayHaveLanded = removed || writeMayHaveLanded(error);
+        const refreshed = mayHaveLanded ? await refresh(state).catch(() => null) : null;
+        if (refreshed && !refreshed.appliedCode) return derive({ ...refreshed, promoError: "" });
+        return derive({ ...state, promoError: mayHaveLanded
+          ? copyParam("cart.promoRemoveUnconfirmed", "Could not confirm promo removal. Refresh your cart.")
+          : copyParam("cart.promoRemoveFailed", "Could not remove the promo code.") });
       }
     },
     remove: async (state, arg) => {
@@ -283,14 +508,24 @@ const svc = defineService<State, {
       if (!id) return state;
       return removeLine(state, id);
     },
+    save: (state, arg) => {
+      const id = itemId(arg);
+      const item = state.items.find(candidate => candidate.id === id);
+      const productId = item?.catalogReference?.catalogItemId ?? item?.productId;
+      if (!item || !productId) return state;
+      try {
+        const saved = toggleSavedProduct({ id: productId, name: item.name, price: item.unitPrice, wasPrice: item.wasPrice, image: item.image, swatches: item.swatches });
+        return derive({ ...state, items: state.items.map(candidate => (candidate.catalogReference?.catalogItemId ?? candidate.productId) === productId ? { ...candidate, saved, notSaved: !saved } : candidate) });
+      } catch { return derive({ ...state, checkoutHint: copyParam("cart.saveError", "Could not save this item.") }); }
+    },
     increment: async (state, arg) => {
       const id = itemId(arg);
       const line = state.items.find((candidate) => candidate.id === id);
       if (!line) return state;
       try {
         const cartId = (await getCurrentCart()).id || "";
-        await updateLineItemQuantity(cartId, id, line.quantity + 1);
-        return await refresh(state);
+        const updated = await updateLineItemQuantity(cartId, id, line.quantity + 1);
+        return await refresh(state, "", updated.cart);
       } catch {
         return derive({ ...state, checkoutHint: copyParam("cart.quantityFailedMessage", "Could not update the quantity.") });
       }
@@ -303,8 +538,8 @@ const svc = defineService<State, {
       if (line.quantity <= 1) return removeLine(state, id);
       try {
         const cartId = (await getCurrentCart()).id || "";
-        await updateLineItemQuantity(cartId, id, line.quantity - 1);
-        return await refresh(state);
+        const updated = await updateLineItemQuantity(cartId, id, line.quantity - 1);
+        return await refresh(state, "", updated.cart);
       } catch {
         return derive({ ...state, checkoutHint: copyParam("cart.quantityFailedMessage", "Could not update the quantity.") });
       }
@@ -349,6 +584,7 @@ const svc = defineService<State, {
         const order = hosted ? { paymentGatewayOrderId: "" } : await createOrder(checkoutId);
         const snapshotId = order.paymentGatewayOrderId ?? "";
         if (!snapshotId && !hosted) {
+          await writeCachedItems([]);
           return derive({ ...state, ...cartConsumedByOrder() });
         }
 
@@ -377,6 +613,7 @@ const svc = defineService<State, {
         });
         if (pay.kind === "paid") {
           // Settled in place — the cart is consumed by the order.
+          await writeCachedItems([]);
           return derive({ ...state, ...cartConsumedByOrder() });
         }
         if (pay.kind === "handoff") {