@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/cart-core.ts

@@ -0,0 +1,220 @@
+// Cart rules and DTO mapping — transport-agnostic, imported by both ./cart.ts (SDK) and the REST
+// twin in templates/storefront/rest/cart.ts (fetch). Raw Cart V2 entities may carry `_id` (SDK)
+// or `id` (REST). Has its own formatMoney (a copy of ../money.ts) so it stands alone when stripped.
+import type { Cart, CartAmount, CartLine } from "./types";
+import type { ImgSrc, Raw } from "./catalog-core";
+
+/** Public app id of the Wix Stores catalog — required inside every catalogReference. */
+export const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * Cart V2 money is ConvertedMoney { amount, convertedAmount } with NO formatted string, and the
+ * currency lives on the cart, not on the money. Format with the buyer's display currency when
+ * present, else the site's. Never hardcode "$" or assume USD.
+ */
+export function formatMoney(money: Raw | null | undefined, currencyCode: string | null | undefined): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}
+
+const amountOf = (money: Raw | null | undefined): number => {
+  const n = Number(money?.convertedAmount ?? money?.amount);
+  return Number.isFinite(n) ? n : 0;
+};
+
+export const cartCurrency = (raw: Raw | null | undefined): string =>
+  raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
+
+/** A TranslatableString / DescriptionLineName in the buyer's language, else the merchant's. */
+const translated = (t: Raw | string | null | undefined): string =>
+  typeof t === "string" ? t : t?.translated ?? t?.original ?? "";
+
+/**
+ * "Monthly plan · every 2 months · 6 payments" from the line's `attributes.subscriptionInfo`
+ * (where Cart V2 carries the plan); "" for a one-time purchase. Every word comes from the plan —
+ * a subscription line must read as one in the cart, never a generic "recurring".
+ */
+export function subscriptionTerms(info: Raw | undefined): string {
+  if (!info) return "";
+  const s: Raw = info.subscriptionSettings ?? {};
+  const unit: Record<string, string> = { DAY: "day", WEEK: "week", MONTH: "month", YEAR: "year" };
+  const parts: string[] = [];
+  const title = translated(info.title);
+  if (title) parts.push(title);
+  const u = unit[String(s.frequency ?? "")];
+  if (u) parts.push(`every ${s.interval && s.interval > 1 ? `${s.interval} ${u}s` : u}`);
+  if (!s.autoRenewal && s.billingCycles) parts.push(`${s.billingCycles} payments`);
+  return parts.join(" · ");
+}
+
+/**
+ * The catalog price to strike on a discounted line: the sale price when the buyer pays less than
+ * it, else the full price when the buyer pays less than that (an automatic discount or a coupon
+ * on a sale item), × quantity. null when the line isn't discounted.
+ */
+export function compareAtLinePrice(pricing: Raw | undefined, quantity: number, currency: string): string | null {
+  const unit = amountOf(pricing?.unitPrice);
+  const b: Raw = pricing?.breakdown ?? {};
+  const candidate = [b.salePrice, b.fullPrice].find((m) => m && amountOf(m) > unit);
+  if (!candidate || quantity < 1) return null;
+  return formatMoney({ amount: String(amountOf(candidate) * quantity) }, currency);
+}
+
+export function toLine(raw: Raw, currency: string, imgSrc: ImgSrc): CartLine {
+  const quantity: number = raw.quantityInfo?.confirmedQuantity ?? 0;
+  const url = raw.attributes?.url;
+  return {
+    lineItemId: rawId(raw), // the LINE id — what update/remove take, never the product id
+    productName: translated(raw.name),
+    quantity,
+    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
+    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
+    compareAtLinePrice: compareAtLinePrice(raw.pricing, quantity, currency),
+    availableQuantity: typeof raw.quantityInfo?.availableQuantity === "number" ? raw.quantityInfo.availableQuantity : null,
+    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
+    productUrl: typeof url === "string" ? url : url?.url ?? "",
+    descriptionLines: ((raw.attributes?.descriptionLines ?? []) as Raw[])
+      .map((d) => {
+        const label = translated(d.name), value = translated(d.plainText) || translated(d.colorInfo);
+        return label && value ? `${label}: ${value}` : value || label;
+      })
+      .filter(Boolean),
+    status: raw.status ?? "IN_STOCK", // not IN_STOCK → the line can't be checked out as-is
+    subscription: subscriptionTerms(raw.attributes?.subscriptionInfo),
+  };
+}
+
+/** The estimate's totals, formatted; every field "" / [] until an estimate ran. */
+export interface CartTotals {
+  subtotal: string;
+  discount: string;
+  discounts: (CartAmount & { scope: "cart" | "item" | "delivery" })[];
+  fees: CartAmount[];
+  taxes: CartAmount[];
+  pricesIncludeTax: boolean;
+  total: string;
+}
+
+export const EMPTY_TOTALS: CartTotals = { subtotal: "", discount: "", discounts: [], fees: [], taxes: [], pricesIncludeTax: false, total: "" };
+
+export function toCart(raw: Raw | null, totals: CartTotals, imgSrc: ImgSrc): Cart {
+  const currency = cartCurrency(raw);
+  const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toLine(l, currency, imgSrc));
+  const coupon: Raw | undefined = (raw?.coupons ?? [])[0];
+  return {
+    lines,
+    itemCount: lines.reduce((n, l) => n + l.quantity, 0),
+    subtotal: totals.subtotal,
+    discount: totals.discount,
+    // item-level discounts already live inside the line prices (the struck compareAtLinePrice)
+    discounts: totals.discounts.filter((d) => d.scope !== "item").map(({ name, amount }) => ({ name, amount })),
+    fees: totals.fees,
+    taxes: totals.taxes,
+    pricesIncludeTax: totals.pricesIncludeTax || raw?.taxInfo?.pricesIncludeTax === true,
+    total: totals.total,
+    coupon: coupon && rawId(coupon) ? { id: rawId(coupon), code: coupon.code ?? "" } : null,
+    note: raw?.note ?? "",
+    currency,
+  };
+}
+
+/**
+ * The totals from a cart estimate: the after-discount subtotal, the CART-level discount, every
+ * named discount / additional fee / tax, whether prices already include tax, and the total before
+ * delivery. Item-scope discounts are marked so the cart can skip them (already in the lines).
+ */
+export function summaryTotals(estimate: Raw | null | undefined, raw: Raw): CartTotals {
+  const s: Raw = estimate?.summary ?? {};
+  const currency = cartCurrency(raw) || cartCurrency(estimate?.cart);
+  const ps: Raw = s.priceSummary ?? {};
+  const named = (list: Raw[] | undefined, key: string): CartAmount[] =>
+    (list ?? [])
+      .filter((x) => x && amountOf(x[key]) > 0)
+      .map((x) => ({ name: translated(x.name) || translated(x.translatedName), amount: formatMoney(x[key], currency) }));
+  const scopeOf = (d: Raw): "cart" | "item" | "delivery" => (d.scope === "LINE_ITEM" ? "item" : d.scope === "DELIVERY" ? "delivery" : "cart");
+  return {
+    subtotal: formatMoney(ps.subtotal, currency),
+    discount: amountOf(ps.discount) > 0 ? formatMoney(ps.discount, currency) : "",
+    discounts: ((s.discounts ?? []) as Raw[]).filter((d) => d && amountOf(d.total) > 0).map((d) => ({ name: translated(d.name), amount: formatMoney(d.total, currency), scope: scopeOf(d) })),
+    fees: named(s.additionalFees, "price"),
+    taxes: named(s.taxSummary?.taxes, "amount"),
+    pricesIncludeTax: s.taxSummary?.pricesIncludeTax === true,
+    total: formatMoney(ps.total, currency),
+  };
+}
+
+/**
+ * The catalogReference.options object for an add — omits every key the buyer didn't use. Wix's
+ * own storefront sends the variant id AND every option's `key: choice.key` pair (plus the choice
+ * modifiers' pairs) under `options`; free text goes under `customTextFields` by the free-text key;
+ * `subscriptionOptionId` only for a recurring plan.
+ */
+export function addOptions({ variantId, optionChoices, modifierChoices, customTextFields, subscriptionOptionId, preorder }: {
+  variantId?: string | null; optionChoices?: Record<string, string>; modifierChoices?: Record<string, string>;
+  customTextFields?: Record<string, string>; subscriptionOptionId?: string; preorder?: boolean;
+}): Raw {
+  const o: Raw = {};
+  if (variantId) o.variantId = variantId; // REQUIRED for any product with options
+  const options = { ...(optionChoices ?? {}), ...(modifierChoices ?? {}) };
+  if (Object.keys(options).length) o.options = options;
+  if (customTextFields && Object.keys(customTextFields).length) o.customTextFields = customTextFields;
+  if (subscriptionOptionId) o.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) o.preOrderRequested = true;
+  return o;
+}
+
+/** The application error code of an SDK or REST failure (`details.applicationError.code`), if any. */
+export function errorCode(err: unknown): string | undefined {
+  const e = err as Raw | null | undefined;
+  const code = e?.details?.applicationError?.code ?? e?.code;
+  return typeof code === "string" ? code : undefined;
+}
+
+// Buyer copy for the codes Wix's own storefront maps; anything else keeps the API's message.
+const CART_ERRORS: Record<string, string> = {
+  ITEM_NOT_FOUND_IN_CATALOG: "This item is no longer available.",
+  INSUFFICIENT_INVENTORY: "This item is now out of stock.",
+  ERROR_COUPON_DOES_NOT_EXIST: "That code doesn't exist. Check it and try again.",
+  ERROR_COUPON_EXPIRED: "That code has expired.",
+  ERROR_COUPON_NOT_APPLICABLE: "That code doesn't apply to this cart.",
+};
+
+/** A buyer-facing message for a failed cart call. */
+export function cartErrorMessage(err: unknown, fallback = "Something went wrong with your cart. Please try again."): string {
+  const code = errorCode(err);
+  if (code && CART_ERRORS[code]) return CART_ERRORS[code];
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  return message || fallback;
+}
+
+/** Read the add result — a refused add still returns 200: a line whose status isn't IN_STOCK, or no line, is a refusal. */
+export function assertAdded(cart: Raw | null | undefined, productId: string, variantId?: string | null): void {
+  const line = ((cart?.lineItems ?? []) as Raw[]).find(
+    (l) => l.source?.catalogReference?.catalogItemId === productId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
+  );
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This item isn't available right now (${String(line.status).toLowerCase().replace(/_/g, " ")}).`);
+  }
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
+    throw new Error("The item couldn't be added. Make sure every required selection was made (options for a product with variants, and all mandatory customizations).");
+  }
+}
+
+/** Refuse checkout for an empty cart or any line not IN_STOCK — say which. */
+export function assertCheckoutable(raw: Raw | null): void {
+  const lines: Raw[] = raw?.lineItems ?? [];
+  if (!lines.length) throw new Error("Your cart is empty.");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
+  if (unavailable.length) {
+    throw new Error(`Some items are no longer available: ${unavailable.map((l) => translated(l.name)).filter(Boolean).join(", ")}.`);
+  }
+  if (!rawId(raw)) throw new Error("Checkout couldn't start: the cart has no id.");
+}

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/cart-store.ts

@@ -0,0 +1,134 @@
+// Client-side cart state — a module-scope store, deliberately NOT a React context.
+// A context can't span Astro islands (each island is its own React root); a module
+// singleton is shared by every island in the page bundle, and works identically in a
+// single-root SPA. Consume it through useCart() (hooks/), or subscribe directly.
+import type { Cart } from "./types";
+import {
+  addToCart as apiAdd,
+  applyCoupon as apiApplyCoupon,
+  fetchCart,
+  removeCoupon as apiRemoveCoupon,
+  removeLine as apiRemove,
+  setNote as apiSetNote,
+  updateQuantity as apiUpdate,
+  checkoutUrl,
+  type AddToCartExtras,
+} from "./cart";
+
+export interface CartState {
+  cart: Cart | null;
+  /**
+   * True while any cart operation is in flight — the DRAWER's flag (its steppers, remove, coupon
+   * and checkout controls), not a card's: a product card disables its own add control on
+   * `pendingProductId`, or every card in the grid dims for every add.
+   */
+  busy: boolean;
+  /** The product whose add is in flight, null otherwise — what a card's add control binds to. */
+  pendingProductId: string | null;
+  /** Last failed operation's message — render it; a new operation clears it. */
+  error: string | null;
+  /** Cart drawer visibility (CartButton opens it, CartDrawer renders by it). */
+  open: boolean;
+}
+
+const EMPTY: CartState = { cart: null, busy: false, pendingProductId: null, error: null, open: false };
+
+let state: CartState = EMPTY;
+const listeners = new Set<() => void>();
+let loaded = false;
+
+function setState(patch: Partial<CartState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+export function getCartState(): CartState {
+  return state;
+}
+
+export function subscribeCart(listener: () => void): () => void {
+  listeners.add(listener);
+  // First subscriber triggers the initial load (browser only — SSR renders the empty state).
+  if (!loaded && typeof window !== "undefined") {
+    loaded = true;
+    void refreshCart();
+  }
+  return () => listeners.delete(listener);
+}
+
+async function run(op: () => Promise<Cart>): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    setState({ cart: await op(), busy: false });
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export async function refreshCart(): Promise<void> {
+  try {
+    setState({ cart: await fetchCart() });
+  } catch {
+    /* no cart yet — leave the empty state */
+  }
+}
+
+/** Add to cart and open the drawer. Throws (and sets .error) on refusal. */
+export async function addLine(
+  productId: string,
+  variantId?: string | null,
+  quantity = 1,
+  extras?: AddToCartExtras,
+): Promise<void> {
+  setState({ pendingProductId: productId });
+  try {
+    await run(() => apiAdd(productId, variantId, quantity, extras));
+  } finally {
+    setState({ pendingProductId: null });
+    // Open either way. On success this shows the new line; on refusal it's the only thing that
+    // makes .error visible — the drawer renders it, and a drawer that stays shut on failure
+    // turns a refused add (out of stock, a digital product with no file) into silence.
+    setState({ open: true });
+  }
+}
+
+export async function updateLineQuantity(lineItemId: string, quantity: number): Promise<void> {
+  await run(() => apiUpdate(lineItemId, quantity));
+}
+
+export async function removeCartLine(lineItemId: string): Promise<void> {
+  await run(() => apiRemove(lineItemId));
+}
+
+/** Apply a coupon code; rejects (and sets .error with buyer copy) when the code is unknown, expired, or doesn't apply. */
+export async function applyCartCoupon(code: string): Promise<void> {
+  if (!code.trim()) return;
+  await run(() => apiApplyCoupon(code));
+}
+
+export async function removeCartCoupon(): Promise<void> {
+  await run(() => apiRemoveCoupon());
+}
+
+/** Save the buyer's note to the merchant (commit on blur, not on every keystroke). */
+export async function setCartNote(note: string): Promise<void> {
+  if ((state.cart?.note ?? "") === note.trim()) return;
+  await run(() => apiSetNote(note));
+}
+
+/** Navigate to the Wix-hosted checkout. Never hand-build a checkout URL. */
+export async function goToCheckout(): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    const url = await checkoutUrl();
+    window.location.href = url;
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export function setCartOpen(open: boolean): void {
+  setState({ open });
+}

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/cart.ts

@@ -0,0 +1,187 @@
+// Cart + checkout (Wix eCom Cart V2) over the SDK — the only file that touches raw cart entities
+// on this transport. Rules and mappers live in ./cart-core (shared with the REST twin in
+// templates/storefront/rest/); this file is the transport only. Copy as-is; extend by calling
+// these exports, never by editing them. The request shapes are exact (catalogItems wrapper,
+// options.variantId, the redirect-session body) and rewriting them is how carts break.
+//
+// Failures are loud: these throw on out-of-stock lines, an empty cart at checkout, a missing
+// required selection, a bad coupon — with buyer copy (cartErrorMessage) — surface the message to
+// the buyer, don't swallow it.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { currentCartV2 } from "@wix/ecom";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { productsV3 } from "@wix/stores";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { EMPTY_TOTALS, WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, cartErrorMessage, rawId, summaryTotals, toCart } from "./cart-core";
+import type { Raw } from "./catalog-core";
+import type { Cart } from "./types";
+
+const cartApi = wixModule(currentCartV2);
+const redirects = wixModule(redirectsModule);
+const productsApi = wixModule(productsV3);
+
+export interface AddToCartExtras {
+  /** The resolved variant's option selections: option key -> choice key (what Wix's own storefront sends beside variantId). */
+  optionChoices?: Record<string, string>;
+  /** TEXT_CHOICES modifier selections: modifier key -> choice key. */
+  modifierChoices?: Record<string, string>;
+  /** FREE_TEXT modifier inputs: the modifier's free-text key -> the buyer's text. */
+  customTextFields?: Record<string, string>;
+  /** The variant is out of stock but pre-orderable — sends preOrderRequested. */
+  preorder?: boolean;
+  /** A chosen recurring plan (SubscriptionPlan.id); omit for a one-time purchase. */
+  subscriptionOptionId?: string;
+}
+
+// Every cart call fails with buyer copy: Wix's error codes (ITEM_NOT_FOUND_IN_CATALOG, coupon
+// codes…) mapped, anything else with its own message.
+async function loud<T>(op: () => Promise<T>): Promise<T> {
+  try {
+    return await op();
+  } catch (e) {
+    throw new Error(cartErrorMessage(e));
+  }
+}
+
+// The V2 cart does NOT return line-item images (attributes.image is typed but comes back
+// absent — verified against a live cart), so images are joined from the catalog by the
+// line's catalogItemId and cached for the session.
+const lineImageCache = new Map<string, string>();
+async function fillLineImages(cart: Cart, raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>(); // productId -> line indexes
+  raws.forEach((raw, i) => {
+    if (cart.lines[i].imageUrl) return;
+    const pid = raw.source?.catalogReference?.catalogItemId;
+    if (!pid) return;
+    const cached = lineImageCache.get(pid);
+    if (cached !== undefined) {
+      cart.lines[i].imageUrl = cached;
+      return;
+    }
+    wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res = await productsApi.queryProducts().in("_id", [...wanted.keys()]).find();
+    for (const p of (res.items ?? []) as Raw[]) {
+      const url = imgSrc(p.media?.main, 300, 300);
+      lineImageCache.set(rawId(p), url);
+      for (const i of wanted.get(rawId(p)) ?? []) cart.lines[i].imageUrl = url;
+    }
+  } catch {
+    /* images are a nicety — the cart stays correct without them */
+  }
+}
+
+async function readCart(raw: Raw | null): Promise<Cart> {
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
+  if (!raw?.lineItems?.length) return toCart(raw, EMPTY_TOTALS, imgSrc);
+  // The authoritative totals come from the cart estimate, never from hand-summing lines: the
+  // after-discount subtotal, every named discount, additional fees and taxes (calculated when
+  // asked), and the total before delivery. Delivery resolves at checkout — never render it as
+  // "Free" here.
+  let totals = EMPTY_TOTALS;
+  try {
+    totals = summaryTotals(await cartApi.estimateCurrentCart({ calculateTax: true, calculateAdditionalFees: true }), raw);
+  } catch {
+    /* estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toCart(raw, totals, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
+  return cart;
+}
+
+/** Read the visitor's current cart. An empty Cart (not an error) when none exists yet. */
+export async function fetchCart(): Promise<Cart> {
+  try {
+    const { cart } = await cartApi.getCurrentCart();
+    return readCart(cart as Raw);
+  } catch {
+    return toCart(null, EMPTY_TOTALS, imgSrc);
+  }
+}
+
+/**
+ * Add a product to the current cart. For a product WITH options, `variantId` is mandatory —
+ * resolve it with `resolveVariant()` from ./catalog first. Mandatory modifiers must be included.
+ * A refused add still returns 200, so the returned line is checked.
+ */
+export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
+  return loud(async () => {
+    const options = addOptions({ variantId, ...extras });
+    const { cart } = await cartApi.addLineItemsToCurrentCart({
+      catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }],
+    });
+    assertAdded(cart as Raw, productId, variantId);
+    return readCart(cart as Raw);
+  });
+}
+
+/** Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id. */
+export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
+  return loud(async () => {
+    const { cart } = await cartApi.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] });
+    return readCart(cart as Raw);
+  });
+}
+
+/** Remove a line from the cart by CartLine.lineItemId. */
+export async function removeLine(lineItemId: string): Promise<Cart> {
+  return loud(async () => {
+    const { cart } = await cartApi.removeLineItemsFromCurrentCart([lineItemId]);
+    return readCart(cart as Raw);
+  });
+}
+
+/** Apply a coupon code (one per cart). Throws buyer copy for an unknown, expired, or inapplicable code. */
+export async function applyCoupon(code: string): Promise<Cart> {
+  return loud(async () => {
+    const { cart } = await cartApi.addCouponToCurrentCart({ code: code.trim() });
+    return readCart(cart as Raw);
+  });
+}
+
+/** Remove the applied coupon (a no-op when none is applied). */
+export async function removeCoupon(): Promise<Cart> {
+  return loud(async () => {
+    const current = (await cartApi.getCurrentCart()).cart as Raw;
+    const couponId = rawId((current?.coupons ?? [])[0]);
+    if (!couponId) return readCart(current);
+    const { cart } = await cartApi.removeCouponFromCurrentCart(couponId);
+    return readCart(cart as Raw);
+  });
+}
+
+/** Save the buyer's note to the merchant on the cart (it travels to checkout and the order). */
+export async function setNote(note: string): Promise<Cart> {
+  return loud(async () => {
+    const { cart } = await cartApi.updateCurrentCart({ note: note.trim() || null });
+    return readCart(cart as Raw);
+  });
+}
+
+/**
+ * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
+ * The cart's id IS the checkout id — no separate checkout-creation call (Wix's own storefront
+ * does the same; `createCheckoutFromCurrentCart` is the alternative when a checkout must exist
+ * before redirecting).
+ * Call from the browser: the return origin must be the site's real https origin
+ * (window.location.origin), never a server-derived request origin.
+ */
+export async function checkoutUrl(): Promise<string> {
+  const { cart } = await cartApi.getCurrentCart();
+  const raw = cart as Raw;
+  assertCheckoutable(raw);
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const session = await redirects.createRedirectSession({
+    ecomCheckout: { checkoutId: rawId(raw) },
+    callbacks: { postFlowUrl: origin ? `${origin}/` : undefined, thankYouPageUrl: origin ? `${origin}/` : undefined },
+  });
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}