@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -0,0 +1,164 @@
+
+# Wix Storefront Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and both storefront helpers from `references/storefront/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`). Copy **both** for a full storefront:
+>
+> | File | What it covers |
+> |---|---|
+> | `wix-store-catalog.js` | Products, categories, product detail, search |
+> | `wix-store-cart.js` | Add to cart, cart management, checkout |
+
+Builds a real, client-only Wix storefront. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock products; never hand-build `/checkout` URLs — always
+go through the eCom cart + redirect-session.
+
+## When to use
+- User wants a Wix eCommerce store or asks to "connect Wix".
+- Replacing placeholder/mock products with live Wix data.
+- Adding cart, checkout, categories, or product detail pages over an existing Wix Stores catalog.
+
+## Prerequisites
+1. A Wix site with **Wix Stores installed and products already added** (this skill does
+   NOT provision — it's read-only over the catalog).
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the
+   Wix Business Manager surfaces a copyable prompt with the id filled in — see
+   the router `SKILL.md`). Paste it into `src/rest/wix-client.js` in place of the placeholder. It is a
+   buyer-facing credential (it only mints anonymous visitor tokens), **not** a secret, so
+   hardcoding/committing it is fine.
+3. The deployed app domain must be allow-listed on the OAuth client for Wix-hosted
+   checkout to return. This is a **separate Wix setup flow the user completes later** —
+   out of this skill's scope. If checkout return fails before that setup is done, that's
+   expected; flag it and continue.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the storefront's UI
+however the project wants; wire it to these two snippets. Copy them into the app (e.g.
+`src/api/`) and only adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to
+  the id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh
+  token IS the cart identity; it is persisted to localStorage. Do not re-mint anonymously
+  per load or the cart silently empties.
+- `src/rest/wix-store-catalog.js` — **Catalog:**
+  `queryProducts`, `queryProductsByCategory`, `getProductBySlug`, `countProducts`,
+  `queryCategories`, `getCategoryBySlug`
+- `src/rest/wix-store-cart.js` — **Cart & checkout:**
+  `addToCart`, `getCurrentCart`, `updateCartItemQuantity`, `removeFromCart`, `checkout`
+
+The Product and Cart shapes are documented as JSDoc comments at the top of each helper file.
+Read them before building the UI — they describe the key fields and link to the full API
+reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Product grid** — `queryProducts()` for the listing (visible products only); pass
+  `nextCursor` back as `cursor` to load the next page. Render most fields directly from the Wix
+  product object (see the `Product` typedef in `wix-store-catalog.js` for key fields) — the one
+  exception is `plainDescription`, which is HTML (see PDP below). For price, use
+  `actualPriceRange.minValue.formattedAmount` (already includes the currency symbol) — no
+  manual formatting needed.
+- **PDP** — `getProductBySlug(slug)` keyed off the URL slug; returns null on miss — show
+  a not-found state, never invent a product. **Drive the whole PDP from the returned product
+  object at runtime — build it generically, not around the one product you happened to inspect.**
+  A catalog is heterogeneous: some products have `options`, some have `modifiers` (mandatory or
+  optional), some track inventory, some none of these. Render a selector for **every** entry the
+  product actually carries: one control per `product.options` (variant choices) **and** one per
+  `product.modifiers` (TEXT_CHOICES → choice buttons/select; FREE_TEXT → a text input); render
+  neither when the arrays are empty. Skipping modifiers is a common miss — a product with a
+  **mandatory** modifier (e.g. "gift wrap?") whose control isn't rendered can never be added: the
+  buyer can't satisfy the requirement, so `add-to-cart` returns 200 with an **empty** `lineItems`
+  and the add silently no-ops.
+  Render `product.plainDescription` as **HTML** — despite the name it contains markup (`<p>`,
+  `<br>`, `<strong>`), so `dangerouslySetInnerHTML={{ __html: product.plainDescription }}` (React)
+  or `el.innerHTML = product.plainDescription`, never as a plain text node (that shows raw `<p>`
+  tags). Strip tags only for plain-text contexts (SEO/meta description, a truncated card teaser).
+- **Gate the Add-to-cart button** — disable it only until the requirements the product *actually
+  has* are met, computed from the product object (never assume every product has options or
+  modifiers): if `product.options` is non-empty, a variant must resolve from the selections; every
+  `modifier.mandatory === true` must have a value. A product with no options and no mandatory
+  modifiers is immediately addable — don't leave the button stuck. Optional modifiers never block.
+  Then pass the selections to `addToCart` (see Cart below); never call it with a required selection missing.
+- **Reflect stock in the UI** — the product object already carries availability at three levels; surface
+  it rather than letting the buyer discover it only on click. Read it from the data at runtime (never
+  hardcode):
+  - **Grid / card:** `product.inventory.availabilityStatus` (`IN_STOCK` / `OUT_OF_STOCK` /
+    `PARTIALLY_OUT_OF_STOCK`) — badge an out-of-stock product as sold out.
+  - **Option choice:** `product.options[].choicesSettings.choices[].inStock` — disable/strike a choice
+    (e.g. size L) that has no in-stock variant, before a full variant is even resolved.
+  - **Variant:** `variantsInfo.variants[].inventoryStatus.inStock` — once selections resolve to a
+    variant, disable Add-to-cart (label "Out of stock") when that variant is `inStock: false`.
+  A product/variant with inventory tracking **off** reports `availabilityStatus: IN_STOCK` /
+  `inStock: true` and stays freely addable — tracking-off is not "no data", it's "always available".
+  `addToCart` still throws on a sold-out line as a backstop, but the UI should prevent reaching it.
+- **Categories** — `queryCategories()` for a category menu; `getCategoryBySlug(slug)` for
+  a category landing page. Pass `category.id` to `queryProductsByCategory(categoryId, { limit?, cursor? })`
+  to list only the products in that category; paginate exactly like `queryProducts`.
+  `queryCategories()` includes Wix's auto-created **"All Products" system category** (`slug:
+  "all-products"`) — it mirrors the full catalog, so drop it from the category menu
+  (`categories.filter(c => c.slug !== "all-products")`). Filter by that slug, not by name (renames/
+  localizes) or `visible` (it's `visible: true` like any other).
+- **Cart** — `addToCart(catalogItemId, variantId?, qty?, { modifierChoices?, customTextFields? }?)`,
+  `updateCartItemQuantity(lineItemId, qty)`, `removeFromCart(lineItemId)`.
+  - `variantId` (`variantsInfo.variants[].id` from `getProductBySlug`) — required for products with
+    options; resolve it by matching the buyer's selections to `variant.choices[].optionChoiceIds`.
+  - `modifierChoices` — `{ [modifier.key]: choiceKey }` for `TEXT_CHOICES` modifiers.
+  - `customTextFields` — `{ [modifier.freeTextSettings.key]: userInput }` for `FREE_TEXT` modifiers.
+    Mandatory modifiers must be included. See the eCommerce integration guide:
+    https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
+  - Use `cart.lineItems[].id` as `lineItemId` (not `catalogItemId`) for mutations.
+  - Read the cart back with `getCurrentCart()` rather than mirroring it locally.
+- **Checkout** — `window.location.href = await checkout()`. After the buyer returns from
+  hosted checkout the order is placed and the cart is empty — re-fetch with
+  `getCurrentCart()` on return (e.g. on mount + `visibilitychange`) to clear the UI.
+- **Empty state** — if `countProducts()` is 0, show an empty state telling the user to
+  add products in their Wix dashboard. Never invent products.
+
+## Hard rules (do not violate)
+- ✅ Checkout ONLY via `checkout()` (`create-checkout` → `/headless/v1/redirect-session`
+  `fullUrl`), then redirect.
+- ❌ Never hand-build `/checkout`, cart-add, or product permalinks for purchase.
+- ❌ Never mock products — render live Wix data or the empty state.
+- ❌ Never generate fake reviews, ratings, or testimonials. Empty review UI only.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ `lineItemId` for cart mutations is `cart.lineItems[].id`, not `catalogItemId`.
+- ✅ On the PDP, render a control for **every** `product.options` entry **and** every `product.modifiers`
+  entry — never only variants. Keep Add-to-cart disabled until a variant resolves and every
+  `modifier.mandatory === true` has a value; a mandatory modifier with no rendered control makes the
+  product unbuyable (add-to-cart returns 200 with empty `lineItems`).
+- ✅ Pass `addToCart`'s `variantId` (`variantsInfo.variants[].id`) for products with variants; omit for products without.
+- ✅ Pass `modifierChoices` (`{ [modifier.key]: choiceKey }`) for TEXT_CHOICES modifiers; pass `customTextFields`
+  (`{ [modifier.freeTextSettings.key]: userInput }`) for FREE_TEXT modifiers. Include mandatory modifiers.
+- The engine fails loudly on purpose: `addToCart`/`checkout` throw on out-of-stock or
+  empty carts. A green path means it is really buyable — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common storefront paths. If you hit a use case they don't cover
+(e.g. coupons, members/auth, a product field not shown in the typedef), make the call
+yourself with `wixApiRequest` — but look up the exact endpoint, HTTP method, and request
+body in the **official Wix API reference** first; never guess:
+- Official Wix API reference: https://dev.wix.com/docs/api-reference.md
+- eCommerce integration guide (modifiers, custom text, variants): https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
+- Member login + a "my orders" account view → the **members** vertical (`references/members/INSTRUCTIONS.md`): custom login on your own UI so buyers can sign in and see their account.
+
+Keep the snippets as the default for everything they already do; reach for the API
+reference only for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the store content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For store data those pages are:
+- **Products** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-stores/products` (`Dashboard → Store → Products`; add/edit products, variants, inventory)
+- **Categories** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-stores/categories/list` (`Dashboard → Store → Categories`; organize products into the category menu)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (cart survives reload, same visitor)
+- [ ] Every product choice renders on the PDP — variant options **and** modifiers (mandatory ones included)
+- [ ] Add-to-cart button stays disabled until all required choices are made (variant + mandatory modifiers)
+- [ ] A product with a mandatory modifier adds successfully (its selection is sent, cart line appears)
+- [ ] Stock reflected in the UI — sold-out product badged (grid), out-of-stock option choices and variants disabled/labelled (PDP)
+- [ ] Add to cart works; out-of-stock items throw rather than add a dead line
+- [ ] Quantity update / remove reflect in `getCurrentCart()`
+- [ ] Checkout redirects via redirect-session `fullUrl` (no hand-built URL)
+- [ ] Cart re-fetched on return from checkout (clears once the order is placed)
+- [ ] Empty state shown when `countProducts()` is 0
+- [ ] No mock products anywhere
+- [ ] Told the user at least once that they can continue setting up their store in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/storefront/wix-store-cart.js

@@ -0,0 +1,147 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+// Product shape (for addToCart): see wix-store-catalog.js
+
+// Stores app id — required inside catalogReference for store products.
+const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+/**
+ * Wix eCom Cart — key fields for building a cart UI.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-cart.md
+ *
+ *   id {string}, currency {string},
+ *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),
+ *   lineItems[].quantity {number},
+ *   lineItems[].catalogReference.catalogItemId {string},
+ *   lineItems[].productName.original {string},
+ *   lineItems[].price.formattedAmount {string} — after discounts with currency symbol,
+ *   lineItems[].fullPrice.formattedAmount {string} — before discount (strikethrough),
+ *   lineItems[].descriptionLines {array} — human-readable option/modifier labels:
+ *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
+ *   lineItems[].image.url {string},
+ *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
+ */
+
+/**
+ * Add a product to the visitor's current cart.
+ *
+ * For products with options (variants), pass the chosen variantId — resolve it from
+ * product.variantsInfo.variants (from getProductBySlug) by matching the buyer's selected
+ * option choices to variant.choices[].optionChoiceIds.
+ *
+ * For products with modifiers:
+ *   - TEXT_CHOICES: pass modifierChoices: { [modifier.key]: choiceKey }
+ *   - FREE_TEXT: pass customTextFields: { [modifier.freeTextSettings.key]: userInput }
+ *   Mandatory modifiers (modifier.mandatory === true) MUST be included.
+ *
+ * Throws on out-of-stock so the buyer can't reach checkout with an unbuyable line.
+ * Full catalogReference reference: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
+ *
+ * @param {string} catalogItemId    Product GUID (product.id).
+ * @param {string} [variantId]      variantsInfo.variants[].id — required for products with variants.
+ * @param {number} [quantity]
+ * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string> }} [extras]
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields } = {}) {
+  const catalogReferenceOptions = {};
+  if (variantId) catalogReferenceOptions.variantId = variantId;
+  if (modifierChoices && Object.keys(modifierChoices).length) catalogReferenceOptions.options = modifierChoices;
+  if (customTextFields && Object.keys(customTextFields).length) catalogReferenceOptions.customTextFields = customTextFields;
+
+  const catalogReference = { appId: STORES_APP_ID, catalogItemId };
+  if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
+  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+    method: "POST",
+    body: { lineItems: [{ catalogReference, quantity }] },
+  });
+  const line = (res?.cart?.lineItems ?? []).find(
+    (l) => l.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.catalogReference?.options?.variantId === variantId),
+  );
+  // Wix returns 200 even when the line is silently rejected — guard both signals:
+  // 1. availability.status set to something other than AVAILABLE
+  // 2. no matching line at all (quantity 0 / line absent)
+  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
+    throw new Error(`Item not available for sale (status: ${line.availability.status}). Is it in stock?`);
+  }
+  if (!line || line.quantity === 0) {
+    // A missing line usually means a required selection wasn't sent — a mandatory modifier
+    // (pass modifierChoices/customTextFields) or the variantId for a product with options —
+    // not necessarily out of stock. Verify every required choice is included in this call.
+    throw new Error(
+      "Item could not be added to the cart. Check that every required selection was sent: " +
+        "the variantId for a product with options, and all mandatory modifiers " +
+        "(modifierChoices for TEXT_CHOICES, customTextFields for FREE_TEXT). It may also be out of stock.",
+    );
+  }
+  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;
+  }
+}
+
+/**
+ * Create a checkout from the current cart and return the hosted checkout URL.
+ * Throws on empty cart, unavailable lines, or a missing redirect URL.
+ * Usage: 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;
+}
+
+/**
+ * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not catalogItemId.
+ * Wix caps the result at remaining stock — returned quantity may be lower than requested.
+ * @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.
+ * @param {string} lineItemId
+ * @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;
+}

package/skills/wix-vibe-headless/references/storefront/wix-store-catalog.js

@@ -0,0 +1,146 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Wix Stores V3 Product — key fields for the storefront catalog.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
+ *
+ *   id {string}, name {string}, slug {string}, visible {boolean}, productType "PHYSICAL"|"DIGITAL",
+ *   mainCategoryId {string},
+ *   media.main.image {object} — { id, url, height, width, altText },
+ *   media.itemsInfo.items {array} — gallery: [{ id, altText, image: { id, url, height, width, altText }, mediaType }],
+ *   actualPriceRange.minValue.formattedAmount {string} — lowest price with currency symbol,
+ *   actualPriceRange.maxValue.formattedAmount {string} — highest price with currency symbol,
+ *   compareAtPriceRange.minValue.formattedAmount {string} — strikethrough price (present when on sale),
+ *   inventory.availabilityStatus {string} — "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK",
+ *   options {array} — product options e.g. Size, Color:
+ *     [{ id, name, optionRenderType "TEXT_CHOICES"|"COLOR_CHOICES"|"SWATCH_CHOICES",
+ *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, linkedMedia }] }],
+ *   modifiers {array} — non-variant customizations (engraving, gift wrap):
+ *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
+ *        key, choicesSettings.choices, freeTextSettings.key }],
+ *   plainDescription {string} — product description as an HTML string (contains <p>, <br>,
+ *     <strong>…) despite the "plain" name — NOT plain text. Render with innerHTML /
+ *     dangerouslySetInnerHTML; strip tags only for plain-text contexts (meta description, teaser),
+ *   variantsInfo.variants {array} — returned only by getProductBySlug:
+ *     [{ id, visible, choices [{ optionChoiceIds: { optionId, choiceId } }],
+ *        price: { actualPrice, compareAtPrice }, media, inventoryStatus: { inStock } }]
+ *     To resolve a buyer's option selections to a variantId: find the variant whose choices
+ *     match all selected { optionId, choiceId } pairs, then pass variant.id to addToCart.
+ *
+ * Category: { id, name, slug, visible, description, image, itemCounter, parentCategory.id }
+ *   NB: queryCategories includes the auto-created system category { slug: "all-products" } —
+ *   filter it out of a category menu (see INSTRUCTIONS.md). `visible` does not flag it.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
+ */
+
+/**
+ * Query visible products (one page). Pass nextCursor back as cursor to load the next page.
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ products: object[], nextCursor: string|null }>}
+ */
+export async function queryProducts({ limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/stores/v3/products/query", {
+    method: "POST",
+    body: {
+      fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"],
+      query: {
+        ...(cursor ? {} : { filter: { visible: true } }),
+        cursorPaging: cursor ? { limit, cursor } : { limit },
+      },
+    },
+  });
+  return {
+    products: res?.products ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Fetch a product by its URL slug. Returns null if not found.
+ * Returns the full product including variantsInfo.variants (with per-variant media and choices).
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getProductBySlug(slug) {
+  const res = await wixApiRequest(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, {
+    method: "GET",
+    query: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"] },
+  });
+  return res?.product ?? null;
+}
+
+/**
+ * Query visible products belonging to a category (one page).
+ * @param {string} categoryId  Category GUID from queryCategories / getCategoryBySlug.
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ products: object[], nextCursor: string|null }>}
+ */
+export async function queryProductsByCategory(categoryId, { limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/stores/v3/products/search", {
+    method: "POST",
+    body: {
+      fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"],
+      search: {
+        ...(cursor
+          ? { cursorPaging: { limit, cursor } }
+          : {
+              cursorPaging: { limit },
+              filter: {
+                visible: true,
+                "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] },
+              },
+            }),
+      },
+    },
+  });
+  return {
+    products: res?.products ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Total number of visible products. Used for empty-state logic (0 → prompt user to add products).
+ * @returns {Promise<number>}
+ */
+export async function countProducts() {
+  const res = await wixApiRequest("/stores/v3/products/count", {
+    method: "POST",
+    body: { filter: { visible: true } },
+  });
+  return res?.count ?? 0;
+}
+
+/**
+ * Query Wix Stores categories (one page).
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ categories: object[], nextCursor: string|null }>}
+ */
+export async function queryCategories({ limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/categories/v1/categories/query", {
+    method: "POST",
+    body: {
+      treeReference: { appNamespace: "@wix/stores", treeKey: null },
+      query: { cursorPaging: cursor ? { limit, cursor } : { limit } },
+    },
+  });
+  return {
+    categories: res?.categories ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Get a single category by its URL slug. Returns null if not found.
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getCategoryBySlug(slug) {
+  const res = await wixApiRequest(`/categories/v1/categories/slug/${encodeURIComponent(slug)}`, {
+    method: "GET",
+    query: { "treeReference.appNamespace": "@wix/stores" },
+  });
+  return res?.category ?? null;
+}