@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-menu.js

@@ -0,0 +1,224 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Menu — top of the hierarchy. One per published menu (e.g. Dinner, Drinks).
+ *   id {string}, name {string}, description {string}, visible {boolean},
+ *   sectionIds {string[]} — ordered Section GUIDs,
+ *   urlQueryParam {string} — URL slug fragment, businessLocationId {string}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/menu-object.md
+ *
+ * Section — a group of items within a menu (e.g. Appetizers, Mains).
+ *   id {string}, name {string}, description {string},
+ *   image {object} — { id, url, width, height, altText },
+ *   itemIds {string[]} — ordered Item GUIDs, visible {boolean}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/section-object.md
+ *
+ * Item — a single dish/drink. Has EITHER priceInfo (single price) OR priceVariants (one-of).
+ *   id {string}, name {string}, description {string},
+ *   image {object} — { id, url, width, height, altText },
+ *   priceInfo.price {string} — decimal string e.g. "12.50" (NO currency symbol),
+ *   priceVariants.variants {object[]} — [{ variantId, priceInfo: { price } }],
+ *   labels {object[]} — [{ id }] resolve via listLabels,
+ *   visible {boolean}, featured {boolean},
+ *   orderSettings.inStock {boolean}, orderSettings.acceptSpecialRequests {boolean},
+ *   modifierGroups {object[]} — [{ id }] resolve via listModifierGroups
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/item-object.md
+ *
+ * PriceVariant (from listVariants): { id, name } — name for the variantId in item.priceVariants.
+ * ModifierGroup: { id, name, rule: { required, minSelections, maxSelections },
+ *   modifiers: [{ id, preSelected, additionalChargeInfo: { additionalCharge } }] }
+ * Modifier (from listModifiers): { id, name, inStock }
+ * Label (from listLabels): { id, name, icon: { url } } — e.g. "Vegan", "Spicy"
+ *
+ * NOTE: Restaurant prices are plain decimal strings with NO currency symbol.
+ * getFullMenu() assembles the full tree and is the recommended entry point.
+ */
+
+/**
+ * Internal: fetch a list endpoint by a set of GUIDs, chunked to avoid long query strings.
+ */
+async function fetchAllByIds(path, idParamName, responseKey, ids, extraQuery = {}) {
+  const unique = [...new Set((ids ?? []).filter(Boolean))];
+  if (!unique.length) return [];
+  const out = [];
+  for (let i = 0; i < unique.length; i += 100) {
+    const chunk = unique.slice(i, i + 100);
+    const res = await wixApiRequest(path, {
+      method: "GET",
+      query: { [idParamName]: chunk, ...extraQuery },
+    });
+    out.push(...(res?.[responseKey] ?? []));
+  }
+  return out;
+}
+
+/**
+ * List menus (one page). Pass `onlyVisible: true` for visitor-facing menus.
+ * GET https://www.wixapis.com/restaurants/menus/v1/menus
+ * @param {{ onlyVisible?: boolean, limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ menus: object[], nextCursor: string|null }>}
+ */
+export async function listMenus({ onlyVisible = true, limit = 500, cursor } = {}) {
+  const res = await wixApiRequest("/restaurants/menus/v1/menus", {
+    method: "GET",
+    query: {
+      onlyVisible: onlyVisible ? "true" : undefined,
+      "paging.limit": String(limit),
+      "paging.cursor": cursor,
+    },
+  });
+  return { menus: res?.menus ?? [], nextCursor: res?.pagingMetadata?.cursors?.next ?? null };
+}
+
+/**
+ * List sections by their GUIDs.
+ * @param {string[]} sectionIds
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function listSections(sectionIds, { onlyVisible = true } = {}) {
+  return fetchAllByIds("/restaurants/menus/v1/sections", "sectionIds", "sections", sectionIds, {
+    onlyVisible: onlyVisible ? "true" : undefined,
+  });
+}
+
+/**
+ * List items by their GUIDs.
+ * @param {string[]} itemIds
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function listItems(itemIds, { onlyVisible = true } = {}) {
+  return fetchAllByIds("/restaurants/menus/v1/items", "itemIds", "items", itemIds, {
+    onlyVisible: onlyVisible ? "true" : undefined,
+  });
+}
+
+/**
+ * List price variants by their GUIDs (resolves variantId → name).
+ * @param {string[]} variantIds
+ * @returns {Promise<object[]>}
+ */
+export async function listVariants(variantIds) {
+  return fetchAllByIds("/restaurants/menus/v1/variants", "variantIds", "variants", variantIds);
+}
+
+/**
+ * List modifier groups by their GUIDs.
+ * @param {string[]} modifierGroupIds
+ * @returns {Promise<object[]>}
+ */
+export async function listModifierGroups(modifierGroupIds) {
+  return fetchAllByIds(
+    "/restaurants/menus/v1/modifier-groups",
+    "modifierGroupIds",
+    "modifierGroups",
+    modifierGroupIds,
+  );
+}
+
+/**
+ * List modifiers by their GUIDs (resolves modifierId → name + inStock).
+ * @param {string[]} modifierIds
+ * @returns {Promise<object[]>}
+ */
+export async function listModifiers(modifierIds) {
+  return fetchAllByIds("/restaurants/item-modifiers/v1/modifiers", "modifierIds", "modifiers", modifierIds);
+}
+
+/**
+ * List every item label on the site.
+ * @returns {Promise<object[]>}
+ */
+export async function listLabels() {
+  const res = await wixApiRequest("/restaurants/menus/v1/labels", { method: "GET" });
+  return res?.labels ?? [];
+}
+
+/**
+ * Retrieve the complete assembled menu tree in one call. Walks menus → sections → items,
+ * then enriches each item with resolved price variants, modifier groups + modifiers, and labels.
+ * This is the recommended entry point for the menu screen.
+ *
+ * Returns:
+ *   { menus: [ { ...menu, sections: [ { ...section, items: [ assembledItem ] } ] } ] }
+ * where assembledItem adds:
+ *   price          {string|null}  Single price (null when variant-priced)
+ *   variants       {object[]}     [{ variantId, name, price }]
+ *   modifierGroups {object[]}     [{ id, name, rule, modifiers: [{ id, name, preSelected, additionalCharge, inStock }] }]
+ *   labels         {object[]}     [{ id, name, icon }]
+ *
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/retrieve-a-complete-menu-structure.md
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<{ menus: object[] }>}
+ */
+export async function getFullMenu({ onlyVisible = true } = {}) {
+  const { menus } = await listMenus({ onlyVisible });
+  if (!menus.length) return { menus: [] };
+
+  const sectionIds = menus.flatMap((m) => m.sectionIds ?? []);
+  const sections = await listSections(sectionIds, { onlyVisible });
+
+  const itemIds = sections.flatMap((s) => s.itemIds ?? []);
+  const items = await listItems(itemIds, { onlyVisible });
+
+  const variantIds = items.flatMap((i) => (i.priceVariants?.variants ?? []).map((v) => v.variantId));
+  const modifierGroupIds = items.flatMap((i) => (i.modifierGroups ?? []).map((g) => g.id));
+
+  const [variants, modifierGroups, labels] = await Promise.all([
+    listVariants(variantIds),
+    listModifierGroups(modifierGroupIds),
+    listLabels(),
+  ]);
+
+  const modifierIds = modifierGroups.flatMap((g) => (g.modifiers ?? []).map((m) => m.id));
+  const modifiers = await listModifiers(modifierIds);
+
+  const variantMap = new Map(variants.map((v) => [v.id, v]));
+  const groupMap = new Map(modifierGroups.map((g) => [g.id, g]));
+  const modifierMap = new Map(modifiers.map((m) => [m.id, m]));
+  const labelMap = new Map(labels.map((l) => [l.id, l]));
+
+  const assembleItem = (item) => ({
+    ...item,
+    price: item.priceInfo?.price ?? null,
+    variants: (item.priceVariants?.variants ?? []).map((v) => ({
+      variantId: v.variantId,
+      name: variantMap.get(v.variantId)?.name ?? null,
+      price: v.priceInfo?.price ?? null,
+    })),
+    modifierGroups: (item.modifierGroups ?? [])
+      .map((ref) => groupMap.get(ref.id))
+      .filter(Boolean)
+      .map((group) => ({
+        id: group.id,
+        name: group.name,
+        rule: group.rule ?? null,
+        modifiers: (group.modifiers ?? []).map((m) => ({
+          id: m.id,
+          name: modifierMap.get(m.id)?.name ?? null,
+          preSelected: m.preSelected ?? false,
+          additionalCharge: m.additionalChargeInfo?.additionalCharge ?? "0",
+          inStock: modifierMap.get(m.id)?.inStock ?? true,
+        })),
+      })),
+    labels: (item.labels ?? []).map((ref) => labelMap.get(ref.id)).filter(Boolean),
+  });
+
+  const itemMap = new Map(items.map((i) => [i.id, assembleItem(i)]));
+  const sectionMap = new Map(
+    sections.map((s) => [
+      s.id,
+      { ...s, items: (s.itemIds ?? []).map((id) => itemMap.get(id)).filter(Boolean) },
+    ]),
+  );
+
+  return {
+    menus: menus.map((m) => ({
+      ...m,
+      sections: (m.sectionIds ?? []).map((id) => sectionMap.get(id)).filter(Boolean),
+    })),
+  };
+}

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js

@@ -0,0 +1,156 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Operation — online-ordering context (fulfillment + scheduling). Every cart line item must
+ * reference an operationId. Pick the default / first enabled one for a simple flow.
+ *   id {string}, name {string}, default {boolean},
+ *   onlineOrderingStatus {string} — "ENABLED"|"DISABLED"|"PAUSED_UNTIL"|UNDEFINED,
+ *   defaultFulfillmentType {string} — "PICKUP"|"DELIVERY",
+ *   fulfillmentIds {string[]}, businessLocationId {string}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/operation-object.md
+ *
+ * Cart (Wix eCom) — restaurant orders use the same visitor cart as the storefront.
+ *   id {string}, currency {string},
+ *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
+ *   lineItems[].quantity {number},
+ *   lineItems[].catalogReference.catalogItemId {string} — the ordered item's GUID,
+ *   lineItems[].productName.original {string},
+ *   lineItems[].price.formattedAmount {string},
+ *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/cart/cart-object.md
+ */
+
+// Wix Restaurants Orders app id — required in catalogReference when adding menu items to the eCom cart.
+const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+
+/**
+ * List the restaurant's online-ordering operations.
+ * GET https://www.wixapis.com/restaurants-operations/v1/operations
+ * @returns {Promise<object[]>}
+ */
+export async function listOperations() {
+  const res = await wixApiRequest("/restaurants-operations/v1/operations", { method: "GET" });
+  return res?.operations ?? [];
+}
+
+/**
+ * Pick the operation to order through — the default, else the first ENABLED, else the first.
+ * Returns null when no operation is configured (show an "ordering unavailable" state).
+ * @returns {Promise<object|null>}
+ */
+export async function getDefaultOperation() {
+  const operations = await listOperations();
+  return (
+    operations.find((o) => o.default) ??
+    operations.find((o) => o.onlineOrderingStatus === "ENABLED") ??
+    operations[0] ??
+    null
+  );
+}
+
+/**
+ * Add a restaurant menu item to the visitor's current eCom cart.
+ *
+ * Requires operationId (from listOperations/getDefaultOperation), menuId, and sectionId.
+ * Throws if any is missing, or if the added line is not AVAILABLE.
+ *
+ * Variant selection and modifier up-charges on the cart line are not covered here — the
+ * restaurants catalogReference.options shape for those is not documented for client add-to-cart.
+ * Confirm the shape before extending:
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/sample-flows.md
+ *
+ * POST https://www.wixapis.com/ecom/v1/carts/current/add-to-cart
+ * @param {string} itemId  Menu item GUID (item.id).
+ * @param {{ operationId: string, menuId: string, sectionId: string, onlineOrderingPageUrl?: string, quantity?: number }} opts
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function addItemToCart(itemId, { operationId, menuId, sectionId, onlineOrderingPageUrl, quantity = 1 } = {}) {
+  if (!itemId) throw new Error("addItemToCart: itemId is required.");
+  if (!operationId || !menuId || !sectionId) {
+    throw new Error("addItemToCart: operationId, menuId and sectionId are all required for a restaurant line item.");
+  }
+  const options = { operationId, menuId, sectionId };
+  if (onlineOrderingPageUrl) options.onlineOrderingPageUrl = onlineOrderingPageUrl;
+
+  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+    method: "POST",
+    body: {
+      lineItems: [{ catalogReference: { appId: RESTAURANTS_ORDERS_APP_ID, catalogItemId: itemId, options }, quantity }],
+    },
+  });
+  const line = (res?.cart?.lineItems ?? []).find((l) => l.catalogReference?.catalogItemId === itemId);
+  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
+    throw new Error(`Item not available to order (status: ${line.availability.status}).`);
+  }
+  return res?.cart;
+}
+
+/** Read the visitor's current cart. Returns null if no cart exists yet. */
+export async function getCurrentCart() {
+  try {
+    const res = await wixApiRequest("/ecom/v1/carts/current", { method: "GET" });
+    return res?.cart ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not the item id.
+ * POST https://www.wixapis.com/ecom/v1/carts/current/update-line-items-quantity
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function updateCartItemQuantity(lineItemId, quantity) {
+  const res = await wixApiRequest("/ecom/v1/carts/current/update-line-items-quantity", {
+    method: "POST",
+    body: { lineItems: [{ id: lineItemId, quantity }] },
+  });
+  return res?.cart;
+}
+
+/**
+ * Remove a line from the current cart by its cart.lineItems[].id.
+ * POST https://www.wixapis.com/ecom/v1/carts/current/remove-line-items
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function removeFromCart(lineItemId) {
+  const res = await wixApiRequest("/ecom/v1/carts/current/remove-line-items", {
+    method: "POST",
+    body: { lineItemIds: [lineItemId] },
+  });
+  return res?.cart;
+}
+
+/**
+ * Create a checkout from the current cart and return the Wix-hosted checkout URL.
+ * Throws on empty cart, unavailable lines, or a missing redirect URL.
+ * Redirect with: window.location.href = await checkout()
+ * @returns {Promise<string>}
+ */
+export async function checkout() {
+  const cart = await getCurrentCart();
+  const lines = cart?.lineItems ?? [];
+  if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
+  const unavailable = lines.filter((l) => l.availability?.status && l.availability.status !== "AVAILABLE");
+  if (unavailable.length) {
+    const names = unavailable.map((l) => l.productName?.original ?? l.catalogReference?.catalogItemId).join(", ");
+    throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
+  }
+
+  const checkoutRes = await wixApiRequest("/ecom/v1/carts/current/create-checkout", {
+    method: "POST",
+    body: { channelType: "WEB" },
+  });
+  const checkoutId = checkoutRes?.checkoutId;
+  if (!checkoutId) throw new Error("Failed to create checkout from the current cart.");
+
+  const redirect = await wixApiRequest("/headless/v1/redirect-session", {
+    method: "POST",
+    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+  });
+  const url = redirect?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Failed to create the checkout redirect session.");
+  return url;
+}

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-reservations.js

@@ -0,0 +1,107 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * ReservationLocation — a restaurant location that accepts table reservations.
+ *   id {string}, default {boolean}, archived {boolean},
+ *   location {object} — physical location details,
+ *   configuration {object}:
+ *     onlineReservations.approval.mode — "AUTOMATIC"|"MANUAL"|"MANUAL_FOR_LARGE_PARTIES"
+ *     partySize.min / partySize.max — guest count limits
+ *     timeSlotInterval — minutes between slots
+ *     reservationForm: { lastNameRequired, emailRequired, customFieldDefinitions }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/reservation-location-object.md
+ *
+ * TimeSlot (from getTimeSlots):
+ *   { startDate, duration, status, manualApproval }
+ *   status: "AVAILABLE" | "UNAVAILABLE" | "NON_WORKING_HOURS" — offer only AVAILABLE slots.
+ *
+ * Reservation (from createHeldReservation / reserveReservation):
+ *   { id, revision, status, details: { reservationLocationId, startDate, endDate, partySize }, reservee, paymentStatus }
+ *   status: "HELD" → "RESERVED" (auto-approved) or "REQUESTED" (manual approval required) after reserve.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reservation-object.md
+ */
+
+/**
+ * List the site's reservation locations (up to 100).
+ * GET https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations
+ * @returns {Promise<object[]>}
+ */
+export async function listReservationLocations() {
+  const res = await wixApiRequest(
+    "/table-reservations/reservation-locations/v1/reservation-locations",
+    { method: "GET" },
+  );
+  return res?.reservationLocations ?? [];
+}
+
+/**
+ * Get reservation time slots for a location on a date, filtered to AVAILABLE only.
+ * Use slotsBefore / slotsAfter to fan out around the chosen date.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/time-slots
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/time-slots/get-time-slots.md
+ * @param {string} reservationLocationId
+ * @param {string} date       ISO-8601 datetime e.g. "2026-07-01T19:00:00.000Z"
+ * @param {number} partySize
+ * @param {{ slotsBefore?: number, slotsAfter?: number, duration?: number }} [options]
+ * @returns {Promise<{ timeSlots: object[], availableTimeSlots: object[] }>}
+ */
+export async function getTimeSlots(reservationLocationId, date, partySize, { slotsBefore = 4, slotsAfter = 4, duration } = {}) {
+  if (!reservationLocationId || !date || !partySize) {
+    throw new Error("getTimeSlots: reservationLocationId, date and partySize are required.");
+  }
+  const res = await wixApiRequest("/table-reservations/reservations/v1/time-slots", {
+    method: "POST",
+    body: { reservationLocationId, date, partySize, slotsBefore, slotsAfter, ...(duration ? { duration } : {}) },
+  });
+  const timeSlots = res?.timeSlots ?? [];
+  return { timeSlots, availableTimeSlots: timeSlots.filter((s) => s.status === "AVAILABLE") };
+}
+
+/**
+ * Hold a reservation for 10 minutes while the visitor fills in their details.
+ * Returns a reservation with status "HELD" — keep its id and revision for reserveReservation.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/reservations/hold
+ * @param {string} reservationLocationId
+ * @param {string} startDate  ISO-8601 datetime of the chosen time slot.
+ * @param {number} partySize
+ * @returns {Promise<object>} The held reservation ({ id, revision, status: "HELD", ... }).
+ */
+export async function createHeldReservation(reservationLocationId, startDate, partySize) {
+  if (!reservationLocationId || !startDate || !partySize) {
+    throw new Error("createHeldReservation: reservationLocationId, startDate and partySize are required.");
+  }
+  const res = await wixApiRequest("/table-reservations/reservations/v1/reservations/hold", {
+    method: "POST",
+    body: { reservationDetails: { reservationLocationId, startDate, partySize } },
+  });
+  const reservation = res?.reservation;
+  if (!reservation?.id) throw new Error("Failed to hold the reservation (the slot may no longer be available).");
+  return reservation;
+}
+
+/**
+ * Confirm a held reservation with the visitor's details. Moves status from "HELD" to
+ * "RESERVED" (auto-approval) or "REQUESTED" (manual approval required).
+ * reservee.firstName and reservee.phone (E.164, e.g. "+15551234567") are REQUIRED.
+ * Pass the revision returned by createHeldReservation. Holds expire after 10 minutes.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/reservations/{id}/reserve
+ * @param {string} reservationId
+ * @param {string} revision
+ * @param {{ firstName: string, phone: string, lastName?: string, email?: string, marketingConsent?: boolean }} reservee
+ * @returns {Promise<object>} The updated reservation.
+ */
+export async function reserveReservation(reservationId, revision, reservee) {
+  if (!reservationId || !revision) throw new Error("reserveReservation: reservationId and revision are required.");
+  if (!reservee?.firstName || !reservee?.phone) {
+    throw new Error("reserveReservation: reservee.firstName and reservee.phone are required.");
+  }
+  const res = await wixApiRequest(
+    `/table-reservations/reservations/v1/reservations/${encodeURIComponent(reservationId)}/reserve`,
+    { method: "POST", body: { revision, reservee } },
+  );
+  const reservation = res?.reservation;
+  if (!reservation?.id) throw new Error("Failed to confirm the reservation (the hold may have expired — start over).");
+  return reservation;
+}

package/skills/wix-vibe-headless/references/shared/wix-client.js

@@ -0,0 +1,186 @@
+/**
+ * REST version of the Wix headless integration — the direct analog of
+ * `storefrontApiRequest` in src/lib/shopify.ts. Plain fetch, JSON in / JSON out.
+ * No SDK, no query builder, no Velo.
+ *
+ * WIX_CLIENT_ID is the one thing to set. The client exchanges it for a visitor
+ * access token via the OAuth2 token endpoint, then sends that token on every API call.
+ */
+
+/**
+ * The public headless OAuth client id. It is a buyer-facing credential (it only mints
+ * anonymous visitor tokens), NOT a secret — so it is safe to hardcode here. Paste the
+ * value from the Wix Business Manager prompt in place of the placeholder.
+ */
+export const WIX_CLIENT_ID = "<YOUR-CLIENT-ID>";
+
+export const WIX_API_BASE = "https://www.wixapis.com";
+const OAUTH_TOKEN_URL = `${WIX_API_BASE}/oauth2/token`;
+
+// Scope the storage key by client id so two headless sites served from the same
+// origin (e.g. localhost:4321 across projects) don't share one visitor token —
+// which would load site A's token for site B and mix up carts/identity.
+const TOKEN_STORAGE_KEY = `wix-visitor-token-${WIX_CLIENT_ID}`;
+let tokenCache = null;
+
+function loadToken() {
+  if (tokenCache) return tokenCache;
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(TOKEN_STORAGE_KEY);
+    if (raw) tokenCache = JSON.parse(raw);
+  } catch {
+    /* ignore disabled/full storage */
+  }
+  return tokenCache;
+}
+
+function saveToken(t) {
+  tokenCache = t;
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(TOKEN_STORAGE_KEY, JSON.stringify(t));
+  } catch {
+    /* ignore */
+  }
+}
+
+async function mintToken(body) {
+  const res = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`Wix OAuth failed: ${res.status}`);
+  const data = await res.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresAt: Date.now() + data.expires_in * 1000,
+  };
+}
+
+/**
+ * Log a member in on THIS client by swapping the persisted token set for the
+ * member's tokens (see references/members/). Member tokens are the SAME shape as
+ * visitor tokens and refresh via the same `refresh_token` grant — logging in just
+ * replaces the set the client already carries, so EVERY subsequent `wixApiRequest`
+ * (cart, orders, bookings, "my …" reads) now runs as the member. Called by the
+ * members helper after a successful credential / social / SSO login.
+ *
+ * @param {{ accessToken: string, refreshToken: string, expiresIn: number }} tokens
+ */
+export function setSessionTokens({ accessToken, refreshToken, expiresIn }) {
+  saveToken({
+    accessToken,
+    refreshToken,
+    expiresAt: Date.now() + expiresIn * 1000,
+    role: "member",
+  });
+}
+
+/**
+ * Drop the persisted session so the next call mints a FRESH anonymous visitor.
+ * Call on logout — otherwise the dead member token lingers and reads fail.
+ */
+export function clearSession() {
+  tokenCache = null;
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(TOKEN_STORAGE_KEY);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * True once a member is logged in on this client (vs. an anonymous visitor).
+ * Gate account UI on this, or on the members helper's `isLoggedIn()`.
+ * @returns {boolean}
+ */
+export function isMember() {
+  return loadToken()?.role === "member";
+}
+
+/**
+ * Get a visitor access token from the client id.
+ *
+ * The visitor token IS the identity of the Wix "current cart", so we persist the
+ * refresh token to localStorage and REFRESH it on expiry — re-minting a fresh
+ * `anonymous` token would create a NEW visitor and silently empty the cart on
+ * every reload / after the 4h token lifetime. Anonymous mint happens only once
+ * (or when no refresh token is stored).
+ */
+async function getAccessToken() {
+  const cached = loadToken();
+  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.accessToken;
+
+  if (cached?.refreshToken) {
+    try {
+      const refreshed = await mintToken({ clientId: WIX_CLIENT_ID, grantType: "refresh_token", refreshToken: cached.refreshToken });
+      // Refreshing preserves identity: a member refresh token yields member tokens.
+      refreshed.role = cached.role || "visitor";
+      saveToken(refreshed);
+      return refreshed.accessToken;
+    } catch {
+      /* refresh failed — fall through to a fresh anonymous visitor */
+    }
+  }
+  const fresh = await mintToken({ clientId: WIX_CLIENT_ID, grantType: "anonymous" });
+  fresh.role = "visitor";
+  saveToken(fresh);
+  return fresh.accessToken;
+}
+
+/**
+ * Core transport — mirrors storefrontApiRequest. Adds the Authorization header,
+ * resolves the path against the Wix API base, parses JSON, surfaces errors.
+ *
+ * @param {string} path
+ * @param {{ method?: "GET"|"POST"|"PUT"|"DELETE", body?: unknown, query?: Record<string, string | undefined> }} [options]
+ */
+export async function wixApiRequest(path, options = {}) {
+  const { method = "POST", body, query } = options;
+  const token = await getAccessToken();
+
+  const url = new URL(path.startsWith("http") ? path : `${WIX_API_BASE}${path}`);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined) continue;
+      if (Array.isArray(v)) {
+        for (const item of v) url.searchParams.append(k, item);
+      } else {
+        url.searchParams.set(k, v);
+      }
+    }
+  }
+
+  const res = await fetch(url.toString(), {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: token, // Wix expects the raw access token (no "Bearer " prefix)
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  if (res.status === 402) {
+    // This API requires an active plan / premium feature on the site.
+    console.warn("Wix: Payment required (402) — this API needs an active plan/premium feature.");
+    return;
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    let parsed;
+    try { parsed = JSON.parse(text); } catch { parsed = text; }
+    // Attach status + parsed body so callers (e.g. the members helper) can map a
+    // meaningful auth outcome (404 = bad credentials, 409 = email exists) to a
+    // friendly message instead of parsing the message string.
+    const err = new Error(`Wix API error ${res.status}: ${text}`);
+    err.status = res.status;
+    err.body = parsed;
+    throw err;
+  }
+  if (res.status === 204) return undefined;
+  return await res.json();
+}