@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/ordering-core.ts

@@ -1,15 +1,16 @@
 // Online-ordering rules and DTO mapping — transport-agnostic, imported by both ./ordering.ts (SDK)
 // and the REST twin in templates/restaurants/rest/ordering.ts (fetch). The restaurant cart rides
 // on the eCom current cart (Cart V2); what makes a line a RESTAURANT line is the catalogReference
-// built here: the Orders app id plus options { operationId, menuId, sectionId } and, exactly as
+// built here: the Orders app id plus options { operationId, menuId, menuSectionId } (sectionId is
+// sent too; Restaurants' checkout check reads menuSectionId) and, exactly as
 // Wix's own ordering code sends them, the visitor's choices: options.priceVariant { id,
 // formattedPrice }, options.modifierGroups [{ id, modifiers: [{ id, price, formattedPrice }] }],
 // options.specialRequests. Raw entities carry `_id` (SDK) or `id` (REST). Has its own formatMoney
 // (a copy of ../money.ts) so it stands alone when stripped. Imports are type-only except the zone
 // helpers from ./time-core (deployed beside this file).
-import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderLine, OrderSelection, OrderingStatus, SiteMoney, WeeklyWindow } from "./types";
+import type { DeliveryAddress, FulfillmentChoice, FulfillmentMethodInfo, FulfillmentTime, MenuItem, MenuOrderingInfo, OrderCart, OrderLine, OrderSelection, OrderingStatus, SiteMoney, WeeklyWindow } from "./types";
 import type { ImgSrc, Raw } from "./menu-core";
-import { zonedMinutes, zonedParts } from "./time-core";
+import { zonedDayKey, zonedMinutes, zonedParts } from "./time-core";
 
 /** The Restaurants Orders app id — every restaurant cart line's catalogReference.appId. */
 export const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
@@ -169,6 +170,98 @@ export function toFulfillmentMethods(raws: Raw[], fulfillmentIds: string[], mone
     }));
 }
 
+// ---- fulfillment choice ----------------------------------------------------------------------------------
+// Restaurants reads the order's fulfillment from the cart's delivery method code, and the hosted
+// checkout offers no pickup/delivery choice until one is set: "<TYPE>|ASAP" or
+// "<TYPE>|<startEpochMs>|<endEpochMs>" for a scheduled slot.
+
+/** The cart delivery-method code for a choice (no time → ASAP). */
+export function fulfillmentCode(choice: Pick<FulfillmentChoice, "type" | "time">): string {
+  if (choice.time && choice.time.type !== choice.type) throw new Error("The chosen time is for a different fulfillment type.");
+  return choice.time?.code ?? `${choice.type}|ASAP`;
+}
+
+const epochMs = (iso: unknown): number => new Date(String(iso ?? "")).getTime();
+
+/**
+ * The operation's time slots → FulfillmentTime[] (ASAP first, then earliest first). `asapSlots` is
+ * the first-available response (one ASAP entry per type), `daySlots` a per-date response; both carry
+ * `timeslotsPerFulfillmentType` (the API spells the type field `fulfilmentType`). The calls return
+ * only orderable slots (blocked ones are left out), so there is nothing to filter.
+ */
+export function toFulfillmentTimes(asapSlots: Raw | null | undefined, daySlots: Raw | null | undefined): FulfillmentTime[] {
+  const out: FulfillmentTime[] = [];
+  const seen = new Set<string>();
+  for (const raw of [...((asapSlots?.timeslotsPerFulfillmentType ?? []) as Raw[]), ...((daySlots?.timeslotsPerFulfillmentType ?? []) as Raw[])]) {
+    const type = (raw.fulfilmentType ?? raw.fulfillmentType) === "DELIVERY" ? "DELIVERY" : "PICKUP";
+    const slot: Raw = raw.timeSlot ?? {};
+    const start = epochMs(slot.startTime), end = epochMs(slot.endTime ?? slot.startTime);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+    const asap = slot.orderSchedulingType === "ASAP";
+    const code = asap ? `${type}|ASAP` : `${type}|${start}|${end}`;
+    if (seen.has(code)) continue;
+    seen.add(code);
+    out.push({ type, code, asap, startIso: new Date(start).toISOString(), endIso: new Date(end).toISOString() });
+  }
+  return out.sort((a, b) => Number(b.asap) - Number(a.asap) || a.startIso.localeCompare(b.startIso));
+}
+
+/** The per-date slots query for a "YYYY-MM-DD" day at the restaurant (`date.day`, `date.month`, `date.year`). */
+export function slotsDateQuery(dayKey: string): Record<string, string> {
+  const [year, month, day] = dayKey.split("-").map(Number);
+  return { "date.day": String(day), "date.month": String(month), "date.year": String(year) };
+}
+
+/**
+ * The time-slot calls' `deliveryAddress.*` query for a delivery address, so the delivery slots are
+ * those of the methods that deliver there ({} when there's no street or city yet).
+ */
+export function slotsAddressQuery(address: DeliveryAddress | undefined, region: { country: string; subdivision: string }): Record<string, string> {
+  if (!address?.addressLine?.trim() || !address.city?.trim()) return {};
+  const a = fulfillmentAddress({ type: "DELIVERY", address }, region) as DeliveryAddress;
+  const q: Record<string, string> = {};
+  for (const [k, v] of Object.entries(a)) if (v) q[`deliveryAddress.${k}`] = String(v);
+  return q;
+}
+
+/** Today at the restaurant, "YYYY-MM-DD" (the operation's timezone; "" → the visitor's). */
+export const restaurantToday = (timeZone: string, now: Date = new Date()): string => zonedDayKey(now, timeZone);
+
+/**
+ * The restaurant's country and subdivision ("US-CA"), from its pickup address or its delivery
+ * area's center. The cart needs a country before ANY delivery method — pickup included — is
+ * accepted (DELIVERY_METHOD_MISSING_ADDRESS), and Wix pre-fills one only from the visitor's location.
+ */
+export function toRestaurantRegion(rawMethods: Raw[]): { country: string; subdivision: string } {
+  for (const m of rawMethods) {
+    const a: Raw = m.pickupOptions?.address ?? m.deliveryOptions?.deliveryArea?.radiusOptions?.centerPointAddress ?? {};
+    if (!a.country) continue;
+    const sub = String(a.subdivision ?? "");
+    return { country: a.country, subdivision: sub && !sub.includes("-") ? `${a.country}-${sub}` : sub };
+  }
+  return { country: "", subdivision: "" };
+}
+
+/**
+ * The address a choice puts on the cart: the delivery address with the restaurant's country and
+ * subdivision filled in, or for pickup just the restaurant's country. Refuses a delivery choice
+ * without the fields Restaurants requires (street, city, country).
+ */
+export function fulfillmentAddress(choice: FulfillmentChoice, region: { country: string; subdivision: string }): DeliveryAddress | { country: string; subdivision?: string } {
+  if (choice.type !== "DELIVERY") {
+    if (!region.country) throw new Error("Pickup isn't set up for online orders. Choose delivery.");
+    return { country: region.country, ...(region.subdivision ? { subdivision: region.subdivision } : {}) };
+  }
+  const a = choice.address;
+  const country = a?.country?.trim() || region.country;
+  const subdivision = a?.subdivision?.trim() || (country === region.country ? region.subdivision : "");
+  if (!a?.addressLine?.trim() || !a.city?.trim() || !country) throw new Error("Enter a delivery address: street and city.");
+  return { ...a, country, ...(subdivision ? { subdivision } : {}) };
+}
+
+/** The message for a delivery method the cart refused: the address is outside every delivery area. */
+export const NOT_DELIVERABLE = "We don't deliver to this address. Choose pickup or another address.";
+
 // ---- cart --------------------------------------------------------------------------------------------------------
 
 export function toOrderLine(raw: Raw, currency: string, imgSrc: ImgSrc): OrderLine {
@@ -192,10 +285,11 @@ export function toOrderLine(raw: Raw, currency: string, imgSrc: ImgSrc): OrderLi
 export function toOrderCart(raw: Raw | null, subtotal: string, imgSrc: ImgSrc): OrderCart {
   const currency = cartCurrency(raw);
   const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toOrderLine(l, currency, imgSrc));
-  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, currency };
+  const delivery: Raw = raw?.deliveryInfo ?? {};
+  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, currency, fulfillmentCode: delivery.method?.code ?? "" };
 }
 
-/** The after-discount subtotal from a cart estimate; "" when unknown. Fees, tax, delivery resolve at checkout. */
+/** The after-discount subtotal from a cart estimate; "" when unknown. Fees and tax resolve at checkout. */
 export function estimateSubtotal(estimate: Raw | null | undefined, raw: Raw): string {
   return formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
 }
@@ -243,6 +337,7 @@ export function orderCatalogItem(
       options: {
         operationId: ctx.operationId,
         menuId: ctx.menuId,
+        menuSectionId: ctx.sectionId, // what Restaurants' checkout validates the dish against
         sectionId: ctx.sectionId,
         ...(variant ? { priceVariant: { id: variant.variantId, formattedPrice: variant.price } } : {}),
         ...(modifierGroups.length ? { modifierGroups } : {}),

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/ordering.ts

@@ -4,11 +4,13 @@
 // the transport only. Copy as-is; extend by calling these exports, never by editing them. The
 // request shapes are exact and rewriting them is how carts break:
 //   - the catalogReference appId is the ORDERS app (9a5d83fd-…), never the Stores id;
-//   - options MUST carry operationId + menuId + sectionId (all three);
+//   - options MUST carry operationId + menuId + menuSectionId (sectionId rides along);
 //   - the visitor's choices ride in options.priceVariant / options.modifierGroups /
-//     options.specialRequests, the keys Wix's own ordering code sends (built in ordering-core).
+//     options.specialRequests, the keys Wix's own ordering code sends (built in ordering-core);
+//   - the fulfillment (pickup/delivery + time) is the cart's delivery method code, set BEFORE the
+//     checkout redirect: the hosted checkout has no picker for it and refuses the order without it.
 // Failures are loud: throws on a missing or paused ordering operation, an invalid selection,
-// unavailable lines, and an empty order at checkout — surface the message, don't swallow it.
+// unavailable lines, an undeliverable address, and an empty order at checkout — surface the message.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/menu-ordering-settings/query-menu-ordering-settings.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.md
@@ -17,6 +19,10 @@
 // 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
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/set-delivery-method-for-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/calculate-available-time-slots-for-date.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/calculate-first-available-time-slot-per-fulfillment-type.md
 import {
   operations as operationsModule,
   fulfillmentMethods as fulfillmentModule,
@@ -25,25 +31,33 @@ import {
 } from "@wix/restaurants";
 import { currentCartV2 } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
-import { wixModule } from "../sdk";
+import { wixFetch, wixModule } from "../sdk";
 import { imgSrc } from "../media";
 import { fetchSiteMoney } from "./menu";
 import { initialSelection, nextCursor, validateSelection, type Raw } from "./menu-core";
 import {
+  NOT_DELIVERABLE,
   RESTAURANTS_ORDERS_APP_ID,
   assertOrderAdded,
   assertOrderCheckoutable,
   assertOrderContext,
   assertOrderable,
   estimateSubtotal,
+  fulfillmentAddress,
+  fulfillmentCode,
   orderCatalogItem,
   rawId,
   resolveOperation,
+  restaurantToday,
+  slotsAddressQuery,
+  slotsDateQuery,
   toFulfillmentMethods,
+  toFulfillmentTimes,
   toMenuOrderingMap,
   toOrderCart,
+  toRestaurantRegion,
 } from "./ordering-core";
-import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "./types";
+import type { DeliveryAddress, FulfillmentChoice, FulfillmentMethodInfo, FulfillmentTime, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "./types";
 
 export { RESTAURANTS_ORDERS_APP_ID };
 
@@ -98,12 +112,24 @@ export async function fetchMenuOrdering(): Promise<Record<string, MenuOrderingIn
 
 /**
  * The operation's enabled pickup/delivery methods (operation.fulfillmentIds only), fees and
- * minimums formatted in the site currency — for display; the buyer picks one on the hosted checkout.
+ * minimums formatted in the site currency — what the fulfillment picker offers.
  */
 export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
   try {
-    const [status, money] = await Promise.all([resolveOrdering(), fetchSiteMoney()]);
+    const [status, money, raws] = await Promise.all([resolveOrdering(), fetchSiteMoney(), listFulfillmentRaws()]);
+    return toFulfillmentMethods(raws, status.fulfillmentIds, money);
+  } catch {
+    return []; // ordering still works without the list (pickup ASAP)
+  }
+}
+
+// The operation's raw fulfillment methods (operation.fulfillmentIds only), read once per session.
+let fulfillmentRawsPromise: Promise<Raw[]> | null = null;
+function listFulfillmentRaws(): Promise<Raw[]> {
+  fulfillmentRawsPromise ??= (async () => {
+    const status = await resolveOrdering();
     if (!status.fulfillmentIds.length) return [];
+    const wanted = new Set(status.fulfillmentIds);
     const raws: Raw[] = [];
     let cursor: string | null = null;
     do {
@@ -111,10 +137,12 @@ export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]
       raws.push(...((res.fulfillmentMethods ?? []) as Raw[]));
       cursor = nextCursor(res);
     } while (cursor);
-    return toFulfillmentMethods(raws, status.fulfillmentIds, money);
-  } catch {
-    return []; // display nicety — ordering still works without the list
-  }
+    return raws.filter((m) => wanted.has(rawId(m)));
+  })().catch((e) => {
+    fulfillmentRawsPromise = null; // transient failure — allow a retry on the next call
+    throw e;
+  });
+  return fulfillmentRawsPromise;
 }
 
 // A line's attributes.image may come back absent — join the menu items' images by the line's
@@ -212,17 +240,75 @@ export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
   return readCartWithSubtotal(cart as Raw);
 }
 
+// A raw Cart V2 / operations call under the SDK's auth, for the few calls this transport makes
+// by path. Throws an Error carrying the API's code (`.code`).
+async function wixJson(path: string, init?: RequestInit): Promise<Raw> {
+  const res = await wixFetch(path, { ...init, headers: { "Content-Type": "application/json", ...(init?.headers ?? {}) } });
+  const body: Raw = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const err = new Error(body?.message || `Request failed (${res.status})`) as Error & { code?: string };
+    err.code = body?.details?.applicationError?.code;
+    throw err;
+  }
+  return body;
+}
+
+/**
+ * The times the order can be fulfilled at: ASAP for each type, then the scheduled slots of `dayKey`
+ * ("YYYY-MM-DD" at the restaurant; default today), ASAP first. Pass the delivery `address` once the
+ * visitor has entered it: the delivery times are then those of the methods that deliver there (none
+ * when no method does). [] when there is no operation. Pass the chosen entry to setOrderFulfillment as `time`.
+ */
+export async function fetchFulfillmentTimes(dayKey?: string, address?: DeliveryAddress): Promise<FulfillmentTime[]> {
+  const { operationId, timeZone } = await resolveOrdering();
+  if (!operationId) return [];
+  const base = `/restaurants-operations/v1/operations/${operationId}`;
+  const where = slotsAddressQuery(address, address ? toRestaurantRegion(await listFulfillmentRaws()) : { country: "", subdivision: "" });
+  const day = new URLSearchParams({ ...slotsDateQuery(dayKey ?? restaurantToday(timeZone)), ...where });
+  const first = new URLSearchParams(where).toString();
+  const [asap, slots] = await Promise.all([
+    wixJson(`${base}/first-available-time-slot-per-fulfillment-type${first ? `?${first}` : ""}`, { method: "GET" }),
+    wixJson(`${base}/available-time-slots-per-date?${day}`, { method: "GET" }),
+  ]);
+  return toFulfillmentTimes(asap, slots);
+}
+
+/**
+ * Set how and when the order is fulfilled: pickup or delivery, a time from fetchFulfillmentTimes
+ * (omitted → ASAP), and for delivery the address (street, city; country and subdivision default to
+ * the restaurant's). Pickup puts the restaurant's country on the cart, which Wix requires before
+ * any delivery method. Throws NOT_DELIVERABLE when the address is outside every delivery area.
+ */
+export async function setOrderFulfillment(choice: FulfillmentChoice): Promise<OrderCart> {
+  const address = fulfillmentAddress(choice, toRestaurantRegion(await listFulfillmentRaws()));
+  await wixJson("/ecom/v2/carts/current", { method: "PATCH", body: JSON.stringify({ cart: { deliveryInfo: { address } } }) });
+  try {
+    const res = await wixJson("/ecom/v2/carts/current/set-delivery-method", { method: "POST", body: JSON.stringify({ deliveryMethod: { code: fulfillmentCode(choice) } }) });
+    return readCartWithSubtotal(res.cart ?? null);
+  } catch (e) {
+    if ((e as { code?: string }).code === "DELIVERY_METHOD_NOT_FOUND") {
+      throw new Error(choice.type === "DELIVERY" ? NOT_DELIVERABLE : "This pickup time isn't available. Choose another time.");
+    }
+    throw e;
+  }
+}
+
 /**
  * Start the Wix-hosted checkout for the current order and return the URL to navigate to.
- * The cart's id IS the checkout id — no separate checkout-creation call. Fulfillment
- * (pickup/delivery + time) and payment are collected on the hosted page. Call from the
- * browser: the return origin must be window.location.origin (https), never a server-derived
- * request origin (http behind the proxy → the return redirect 403s).
+ * The cart's id IS the checkout id — no separate checkout-creation call. The fulfillment must be
+ * on the cart first (setOrderFulfillment); a cart with none gets pickup ASAP. Payment is collected
+ * on the hosted page. Call from the browser: the return origin must be window.location.origin
+ * (https), never a server-derived request origin (http behind the proxy → the return redirect 403s).
  */
 export async function orderCheckoutUrl(): Promise<string> {
   const { cart } = await cartApi.getCurrentCart();
   const raw = cart as Raw;
   assertOrderCheckoutable(raw);
+  if (!raw.deliveryInfo?.method?.code) {
+    await setOrderFulfillment({ type: "PICKUP" }).catch(() => {
+      throw new Error("Choose pickup or delivery before checkout.");
+    });
+  }
   const origin = typeof window !== "undefined" ? window.location.origin : "";
   const session = await redirects.createRedirectSession({
     ecomCheckout: { checkoutId: rawId(raw) },

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/types.ts

@@ -190,7 +190,7 @@ export interface MenuOrderingInfo {
   };
 }
 
-/** A pickup/delivery method the operation offers (the buyer picks one on the hosted checkout). */
+/** A pickup/delivery method the operation offers (display: name, fee, minimum). */
 export interface FulfillmentMethodInfo {
   id: string;
   type: "PICKUP" | "DELIVERY";
@@ -203,6 +203,38 @@ export interface FulfillmentMethodInfo {
   minOrderPriceAmount: string;
 }
 
+/**
+ * A time the order can be fulfilled at, from the operation's time slots. `code` is what the cart's
+ * delivery method takes ("PICKUP|ASAP", or "PICKUP|<startMs>|<endMs>" for a scheduled slot).
+ */
+export interface FulfillmentTime {
+  type: "PICKUP" | "DELIVERY";
+  code: string;
+  asap: boolean;
+  /** ISO start/end (equal for a point in time); render in OrderingStatus.timeZone. */
+  startIso: string;
+  endIso: string;
+}
+
+/**
+ * A delivery address. country (ISO-3166 alpha-2) and subdivision ("US-CA") default to the
+ * restaurant's when omitted — delivery is local.
+ */
+export interface DeliveryAddress {
+  addressLine: string;
+  city: string;
+  postalCode?: string;
+  country?: string;
+  subdivision?: string;
+}
+
+/** The visitor's fulfillment: pickup or delivery, a time (omitted → ASAP), and the address for delivery. */
+export interface FulfillmentChoice {
+  type: "PICKUP" | "DELIVERY";
+  time?: FulfillmentTime;
+  address?: DeliveryAddress;
+}
+
 export interface OrderLine {
   /** The cart line id — what update/remove take (NOT the menu item id). */
   lineItemId: string;
@@ -227,6 +259,8 @@ export interface OrderCart {
   /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
   subtotal: string;
   currency: string;
+  /** The fulfillment code set on the cart ("PICKUP|ASAP", …); "" when none is set yet. */
+  fulfillmentCode: string;
 }
 
 /** A custom question the owner added to the reservation form. */

package/skills/wix-headless-templates/restaurants/rest/ordering.ts

@@ -2,35 +2,49 @@
 // app/wix/restaurants/ordering.ts. Same exports, same OrderCart/OrderLine DTOs; rules and mappers
 // from ordering-core (the SAME file the SDK transport uses, deployed flat next to this one). The
 // request shapes are exact and rewriting them is how carts break: the Orders app id, options
-// { operationId, menuId, sectionId } — all three — and the visitor's choices in
+// { operationId, menuId, menuSectionId } (sectionId rides along) and the visitor's choices in
 // options.priceVariant / options.modifierGroups / options.specialRequests, the keys Wix's own
-// ordering sends. Failures are loud: a missing or paused operation, an invalid selection, an
-// unavailable line, an empty order at checkout all throw — surface the message.
+// ordering sends; and the fulfillment (pickup/delivery + time) as the cart's delivery method code,
+// set BEFORE the checkout redirect — the hosted checkout has no picker for it and refuses the order
+// without it. Failures are loud: a missing or paused operation, an invalid selection, an
+// unavailable line, an undeliverable address, an empty order at checkout all throw — surface the message.
 // All calls run with the visitor token: the cart is the token's (see ./client).
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/menu-ordering-settings/query-menu-ordering-settings.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.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-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/set-delivery-method-for-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/calculate-available-time-slots-for-date.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/calculate-first-available-time-slot-per-fulfillment-type.md
 import { WixApiError, wixRequest } from "../../shared/rest/client.js";
 import { imgSrc } from "../../shared/rest/media.js";
 import { fetchSiteMoney } from "./menu.js";
 import { initialSelection, nextCursor, validateSelection, type Raw } from "../app/wix/restaurants/menu-core.js";
 import {
+  NOT_DELIVERABLE,
   RESTAURANTS_ORDERS_APP_ID,
   assertOrderAdded,
   assertOrderCheckoutable,
   assertOrderContext,
   assertOrderable,
   estimateSubtotal,
+  fulfillmentAddress,
+  fulfillmentCode,
   orderCatalogItem,
   rawId,
   resolveOperation,
+  restaurantToday,
+  slotsAddressQuery,
+  slotsDateQuery,
   toFulfillmentMethods,
+  toFulfillmentTimes,
   toMenuOrderingMap,
   toOrderCart,
+  toRestaurantRegion,
 } from "../app/wix/restaurants/ordering-core.js";
-import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "../app/wix/restaurants/types.js";
+import type { DeliveryAddress, FulfillmentChoice, FulfillmentMethodInfo, FulfillmentTime, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "../app/wix/restaurants/types.js";
 
 export { RESTAURANTS_ORDERS_APP_ID };
 
@@ -86,8 +100,20 @@ export async function fetchMenuOrdering(): Promise<Record<string, MenuOrderingIn
  */
 export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
   try {
-    const [status, money] = await Promise.all([resolveOrdering(), fetchSiteMoney()]);
+    const [status, money, raws] = await Promise.all([resolveOrdering(), fetchSiteMoney(), listFulfillmentRaws()]);
+    return toFulfillmentMethods(raws, status.fulfillmentIds, money);
+  } catch {
+    return []; // ordering still works without the list (pickup ASAP)
+  }
+}
+
+// The operation's raw fulfillment methods (operation.fulfillmentIds only), read once per session.
+let fulfillmentRawsPromise: Promise<Raw[]> | null = null;
+function listFulfillmentRaws(): Promise<Raw[]> {
+  fulfillmentRawsPromise ??= (async () => {
+    const status = await resolveOrdering();
     if (!status.fulfillmentIds.length) return [];
+    const wanted = new Set(status.fulfillmentIds);
     const raws: Raw[] = [];
     let cursor: string | null = null;
     do {
@@ -95,10 +121,12 @@ export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]
       raws.push(...((res?.fulfillmentMethods ?? []) as Raw[]));
       cursor = nextCursor(res);
     } while (cursor);
-    return toFulfillmentMethods(raws, status.fulfillmentIds, money);
-  } catch {
-    return []; // display nicety — ordering still works without the list
-  }
+    return raws.filter((m) => wanted.has(rawId(m)));
+  })().catch((e) => {
+    fulfillmentRawsPromise = null; // transient failure — allow a retry on the next call
+    throw e;
+  });
+  return fulfillmentRawsPromise;
 }
 
 // A line's attributes.image may come back absent — join the menu items' images by the line's
@@ -165,7 +193,7 @@ export async function fetchOrderCart(): Promise<OrderCart> {
  * the dish can't be ordered, a modifier rule fails, or the line is refused (a refused add still returns 200).
  * POST /ecom/v2/carts/current/add-line-items
  *   { catalogItems: [{ quantity, catalogReference: { catalogItemId, appId: <Orders app>, options: {
- *       operationId, menuId, sectionId, priceVariant?: { id, formattedPrice },
+ *       operationId, menuId, menuSectionId, sectionId, priceVariant?: { id, formattedPrice },
  *       modifierGroups?: [{ id, modifiers: [{ id, price, formattedPrice? }] }], specialRequests? } } }] }
  */
 export async function addToOrder(
@@ -202,17 +230,66 @@ export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
   return readCartWithSubtotal(res?.cart ?? null);
 }
 
+/**
+ * The times the order can be fulfilled at: ASAP for each type, then the scheduled slots of `dayKey`
+ * ("YYYY-MM-DD" at the restaurant; default today), ASAP first. Pass the delivery `address` once the
+ * visitor has entered it: the delivery times are then those of the methods that deliver there (none
+ * when no method does). [] when there is no operation. Pass the chosen entry to setOrderFulfillment as `time`.
+ * GET /restaurants-operations/v1/operations/{id}/first-available-time-slot-per-fulfillment-type[?deliveryAddress.*]
+ * GET /restaurants-operations/v1/operations/{id}/available-time-slots-per-date?date.day=&date.month=&date.year=[&deliveryAddress.*]
+ *   deliveryAddress.addressLine / .city / .postalCode / .country / .subdivision
+ */
+export async function fetchFulfillmentTimes(dayKey?: string, address?: DeliveryAddress): Promise<FulfillmentTime[]> {
+  const { operationId, timeZone } = await resolveOrdering();
+  if (!operationId) return [];
+  const base = `/restaurants-operations/v1/operations/${operationId}`;
+  const where = slotsAddressQuery(address, address ? toRestaurantRegion(await listFulfillmentRaws()) : { country: "", subdivision: "" });
+  const [asap, slots] = await Promise.all([
+    wixRequest<Raw>(`${base}/first-available-time-slot-per-fulfillment-type`, { method: "GET", query: where }),
+    wixRequest<Raw>(`${base}/available-time-slots-per-date`, { method: "GET", query: { ...slotsDateQuery(dayKey ?? restaurantToday(timeZone)), ...where } }),
+  ]);
+  return toFulfillmentTimes(asap, slots);
+}
+
+/**
+ * Set how and when the order is fulfilled: pickup or delivery, a time from fetchFulfillmentTimes
+ * (omitted → ASAP), and for delivery the address (street, city; country and subdivision default to
+ * the restaurant's). Pickup puts the restaurant's country on the cart, which Wix requires before
+ * any delivery method. Throws NOT_DELIVERABLE when the address is outside every delivery area.
+ * PATCH /ecom/v2/carts/current  { cart: { deliveryInfo: { address: { addressLine, city, postalCode, country, subdivision } } } }
+ *   (the street field is addressLine; addressLine1 is dropped)
+ * POST  /ecom/v2/carts/current/set-delivery-method  { deliveryMethod: { code: "PICKUP|ASAP" | "<TYPE>|<startMs>|<endMs>" } }
+ */
+export async function setOrderFulfillment(choice: FulfillmentChoice): Promise<OrderCart> {
+  const address = fulfillmentAddress(choice, toRestaurantRegion(await listFulfillmentRaws()));
+  await wixRequest<Raw>(CART, { method: "PATCH", body: { cart: { deliveryInfo: { address } } } });
+  try {
+    const res = await wixRequest<Raw>(`${CART}/set-delivery-method`, { body: { deliveryMethod: { code: fulfillmentCode(choice) } } });
+    return readCartWithSubtotal(res?.cart ?? null);
+  } catch (e) {
+    if (e instanceof WixApiError && e.code === "DELIVERY_METHOD_NOT_FOUND") {
+      throw new Error(choice.type === "DELIVERY" ? NOT_DELIVERABLE : "This pickup time isn't available. Choose another time.");
+    }
+    throw e;
+  }
+}
+
 /**
  * Start the Wix-hosted checkout for the current order and return the URL to navigate the FULL
- * document to. The cart's id IS the checkout id; fulfillment (pickup/delivery + time) and payment
- * are collected on the hosted page. `origin` must be the site's real https origin as registered on
- * the OAuth app's allowed domains (browser: window.location.origin) — an unlisted or http origin
- * 403s on return.
+ * document to. The cart's id IS the checkout id. The fulfillment must be on the cart first
+ * (setOrderFulfillment); a cart with none gets pickup ASAP. Payment is collected on the hosted
+ * page. `origin` must be the site's real https origin as registered on the OAuth app's allowed
+ * domains (browser: window.location.origin) — an unlisted or http origin 403s on return.
  * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
  */
 export async function orderCheckoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
   const raw = await getCurrentCartRaw();
   assertOrderCheckoutable(raw);
+  if (!raw?.deliveryInfo?.method?.code) {
+    await setOrderFulfillment({ type: "PICKUP" }).catch(() => {
+      throw new Error("Choose pickup or delivery before checkout.");
+    });
+  }
   const res = await wixRequest<Raw>("/headless/v1/redirect-session", {
     body: { ecomCheckout: { checkoutId: rawId(raw) }, callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {} },
   });