@wix/agent-skills 1.15.0 → 1.15.1

package/skills/wix-vibe-headless/platforms/generic.md

@@ -0,0 +1,87 @@
+# Wix Managed Headless — build instructions
+
+You are building a **Wix Managed** headless site. The business to build, and your Wix client id
+and metasite id, are given in your initial prompt. Follow the steps below.
+
+## STEP 0 — Install the Wix skills locally
+
+Install three skills — they land under `.agents/skills/` as:
+- **`wix-vibe-headless`** — the client build guide: how to build the frontend against the Wix
+  APIs. This is your main source of truth (STEP 1).
+- **`wix-headless`** — a broad skill for building full Wix apps with the Wix SDK packages, **most
+  of which does not apply to how you build here**. Use it **only** as a seeding/admin recipe
+  reference — its `references/SEED.md` and `references/inline-recipes/`, for STEP 2. **Ignore
+  everything else in it** — in particular do **not** follow its authentication / `@wix/cli` /
+  "managed project" setup (e.g. anything under `references/managed/`, such as `AUTHENTICATION.md`).
+  That is **not** how auth works here — auth is handled per STEP 2 below.
+- **`wix-docs`** — a **fallback**: how to search and read the Wix API reference docs, for anything
+  the seeding recipes above don't cover.
+
+Install them so you can read them from files as you go (fetching skill docs over the web
+truncates or summarises large files).
+
+**Run the Skills CLI** — this is the install path to use:
+```bash
+CI=1 npx skills@latest add wix/skills/skills/wix-headless --yes
+CI=1 npx skills@latest add wix/skills/skills/wix-vibe-headless --yes
+CI=1 npx skills@latest add wix/skills/skills/wix-docs --yes
+```
+
+**Only if the CLI above actually errors** (not on a guess), fall back to curl + gzip — download
+each bundle and extract it into `.agents/skills/wix-<name>/`:
+```bash
+for s in headless vibe-headless docs; do
+  mkdir -p ".agents/skills/wix-$s"
+  curl -s "https://www.wix.com/skills/$s.tgz" | tar xz -C ".agents/skills/wix-$s" --strip-components=1
+done
+```
+
+## STEP 1 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/SKILL.md` and follow it **exactly** — it is the single
+source of truth for how the client app is built against the Wix APIs (over the public
+`WIX_CLIENT_ID`, which is a buyer/visitor-facing credential, safe in the frontend). To save time,
+prefer copying the ready-made files the `wix-vibe-headless` skill provides (e.g. the Wix client
+setup) and adapting them over re-generating them from scratch.
+
+## STEP 2 — Seed and manage the business
+
+Seed the site with real content by following the `wix-headless` skill's `references/SEED.md`
+(`.agents/skills/wix-headless/references/SEED.md`). Where its seed recipes don't cover what you
+need, fall back to the `wix-docs` skill to search and read the relevant Wix API docs.
+
+**Seeding is additive.** You may clean up the app install's **obvious default sample/mock data**
+right after a fresh install, but the site may already hold **real content** (a prior run, or
+owner-added) — if what's there isn't obviously install sample data, or you're unsure, **do not
+delete or overwrite it without the user's explicit ask or approval** (ask first).
+
+These management/admin calls need **elevated Wix credentials** — the public client id is not
+enough. If you don't already have a way to authenticate them, either **connect your platform's
+Wix connector** (if it has one) or **ask the user for a Wix API key / token** and store it in your
+platform's built-in **connector / secrets (env) manager** — never hardcode or commit it. **Once
+the connector is connected (or the API key is in place), you can make Wix REST admin calls
+directly** — authenticate each call with that credential (the `wix-docs` skill covers Wix API-key
+auth). Or, if the user prefers, tell them they can add this content themselves in the Wix
+dashboard instead.
+
+Authenticate admin calls with **only** that connector/API key. Do **not** install or run the Wix
+CLI (`@wix/cli`), do a device-login, or follow `wix-headless`'s `references/managed/AUTHENTICATION.md`
+— that managed-project auth flow does not apply here.
+
+Management/admin operations (seeding, `wix-headless`, `wix-docs`) are **separate from the
+client** — the client is built solely per the `wix-vibe-headless` skill.
+
+If possible, run STEP 1 and STEP 2 in parallel — building the client and seeding the business
+are independent. Within each, also parallelize independent work (API calls, seeding multiple
+entities) to finish faster.
+
+## Later admin requests
+
+For any later admin/management request, work the same way as STEP 2: check the `wix-headless`
+skill's inline recipes first (`.agents/skills/wix-headless/references/inline-recipes/`) and fall
+back to the `wix-docs` skill where the operation isn't documented there.
+
+## When done
+
+After the site is built and seeded, ask the user to open this URL to complete the setup in Wix
+(substitute the metasite id you were given): `https://manage.wix.com/dashboard/{metaSiteId}`

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

@@ -58,7 +58,11 @@ the full API reference for anything not shown.
 ## How to wire it (UI is the project's choice)
 - **Service list** — `queryServices()` for the listing (visitor-visible services only). Render
   `name`, `tagLine`, the image via `mediaUrl(service.media?.items?.[0]?.image)`, and the price
-  from `payment.fixed.price.formattedValue` (already includes the currency). Pass the returned
+  from `payment.fixed.price`. `value` + `currency` are always present; `formattedValue` is
+  **optional** (it may be missing), so don't depend on it — build the price from `value`+`currency`
+  and use `formattedValue` only when present. e.g. `new Intl.NumberFormat(undefined, { style:
+  'currency', currency }).format(Number(value))`. (Rendering `formattedValue` alone leaves the price
+  blank — or your "Varies" fallback — whenever it's absent.) Pass the returned
   `nextOffset` back as `offset` to load the next page. Books **APPOINTMENT and CLASS** services
   (see the slot picker below); COURSE is whole-course enrollment and out of scope.
 - **Service detail** — `getService(serviceId)` keyed off the URL/route; returns null on miss —

package/skills/wix-vibe-headless/references/bookings/wix-bookings-services.js

@@ -12,7 +12,9 @@ import { wixApiRequest } from "./wix-client.js";
  *   media.items {array} — [{ image: { id, url, width, height, altText } }]
  *     (url may be a bare Wix media handle — pass through mediaUrl() before rendering),
  *   payment.rateType "FIXED"|"CUSTOM"|"VARIED"|"NO_FEE"|"SUBSCRIPTION",
- *   payment.fixed.price { value, currency, formattedValue },
+ *   payment.fixed.price { value, currency, formattedValue } — value + currency are always
+ *     present; formattedValue is optional (may be missing), so format the price from
+ *     value+currency and use formattedValue only when present,
  *   payment.options { online, inPerson, deposit, pricingPlan },
  *   schedule.id {string}, onlineBooking.enabled {boolean},
  *   category { id, name }, staffMemberIds {string[]}, locations {array},

package/skills/wix-vibe-headless/references/events/wix-events-browse.js

@@ -24,7 +24,8 @@ import { wixApiRequest } from "./wix-client.js";
  *     type {string} — "RSVP"|"TICKETING"|"EXTERNAL"|"NONE",
  *     status {string} — only OPEN_* statuses accept new registrations,
  *     rsvp.responseType — "YES_AND_NO" allows a "NO" reply,
- *     tickets.currency, tickets.lowestPrice, tickets.soldOut,
+ *     tickets.lowestPrice {object} — money { value, currency, formattedValue }; render
+ *       formattedValue, not the object (see "Money/price fields" in SKILL.md). tickets.soldOut {boolean},
  *     external.url — link out when type === "EXTERNAL",
  *   eventPageUrl {object} — { base, path } (URLS fieldset) — needed for getTicketCheckoutUrl,
  *   form {object} — registration form controls (FORM fieldset),

package/skills/wix-vibe-headless/references/portfolio/wix-portfolio.js

@@ -36,23 +36,31 @@ const PROJECTS_QUERY_URL = "/portfolio/v1/projects/query";
  * @returns {Promise<{ collections: object[], nextCursor: string|null }>}
  */
 export async function queryCollections({ limit = 100, cursor } = {}) {
-  const res = await wixApiRequest(COLLECTIONS_QUERY_URL, {
-    method: "POST",
-    body: {
-      includePageUrl: true,
-      query: cursor
-        ? { cursorPaging: { limit, cursor } }
-        : {
-            filter: { hidden: false },
-            sort: [{ fieldName: "sortOrder", order: "ASC" }],
-            cursorPaging: { limit },
-          },
-    },
-  });
-  return {
-    collections: res?.collections ?? [],
-    nextCursor: res?.metadata?.cursors?.next ?? null,
-  };
+  try {
+    const res = await wixApiRequest(COLLECTIONS_QUERY_URL, {
+      method: "POST",
+      body: {
+        includePageUrl: true,
+        query: cursor
+          ? { cursorPaging: { limit, cursor } }
+          : {
+              filter: { hidden: false },
+              sort: [{ fieldName: "sortOrder", order: "ASC" }],
+              cursorPaging: { limit },
+            },
+      },
+    });
+    return {
+      collections: res?.collections ?? [],
+      nextCursor: res?.metadata?.cursors?.next ?? null,
+    };
+  } catch (err) {
+    // Degrade to an empty page instead of rethrowing: an uncaught read would leave a
+    // component's `loading` flag stuck true and hang the gallery on a spinner. Empty
+    // renders the same empty state as a genuinely empty backend.
+    console.error("queryCollections failed:", err);
+    return { collections: [], nextCursor: null };
+  }
 }
 
 /**
@@ -79,11 +87,18 @@ export async function getCollectionBySlug(slug) {
  * @returns {Promise<number>}
  */
 export async function countCollections() {
-  const res = await wixApiRequest(COLLECTIONS_QUERY_URL, {
-    method: "POST",
-    body: { query: { filter: { hidden: false }, cursorPaging: { limit: 100 } } },
-  });
-  return res?.metadata?.total ?? (res?.collections?.length ?? 0);
+  try {
+    const res = await wixApiRequest(COLLECTIONS_QUERY_URL, {
+      method: "POST",
+      body: { query: { filter: { hidden: false }, cursorPaging: { limit: 100 } } },
+    });
+    return res?.metadata?.total ?? (res?.collections?.length ?? 0);
+  } catch (err) {
+    // On failure treat as empty (0) rather than rethrowing — a thrown count would hang
+    // the empty-state check; 0 falls through to the "add collections" prompt.
+    console.error("countCollections failed:", err);
+    return 0;
+  }
 }
 
 /**
@@ -93,23 +108,30 @@ export async function countCollections() {
  * @returns {Promise<{ projects: object[], nextCursor: string|null }>}
  */
 export async function queryProjects({ limit = 100, cursor } = {}) {
-  const res = await wixApiRequest(PROJECTS_QUERY_URL, {
-    method: "POST",
-    body: {
-      includePageUrl: true,
-      query: cursor
-        ? { cursorPaging: { limit, cursor } }
-        : {
-            filter: { hidden: false },
-            sort: [{ fieldName: "createdDate", order: "DESC" }],
-            cursorPaging: { limit },
-          },
-    },
-  });
-  return {
-    projects: res?.projects ?? [],
-    nextCursor: res?.metadata?.cursors?.next ?? null,
-  };
+  try {
+    const res = await wixApiRequest(PROJECTS_QUERY_URL, {
+      method: "POST",
+      body: {
+        includePageUrl: true,
+        query: cursor
+          ? { cursorPaging: { limit, cursor } }
+          : {
+              filter: { hidden: false },
+              sort: [{ fieldName: "createdDate", order: "DESC" }],
+              cursorPaging: { limit },
+            },
+      },
+    });
+    return {
+      projects: res?.projects ?? [],
+      nextCursor: res?.metadata?.cursors?.next ?? null,
+    };
+  } catch (err) {
+    // Degrade to an empty page instead of rethrowing (see queryCollections) — an uncaught
+    // read hangs the gallery on an infinite spinner; empty renders the empty state instead.
+    console.error("queryProjects failed:", err);
+    return { projects: [], nextCursor: null };
+  }
 }
 
 /**
@@ -121,22 +143,29 @@ export async function queryProjects({ limit = 100, cursor } = {}) {
  * @returns {Promise<{ projects: object[], nextCursor: string|null }>}
  */
 export async function queryProjectsByCollection(collectionId, { limit = 100, cursor } = {}) {
-  const res = await wixApiRequest(PROJECTS_QUERY_URL, {
-    method: "POST",
-    body: {
-      includePageUrl: true,
-      query: cursor
-        ? { cursorPaging: { limit, cursor } }
-        : {
-            filter: { hidden: false, collectionIds: { $hasSome: [collectionId] } },
-            cursorPaging: { limit },
-          },
-    },
-  });
-  return {
-    projects: res?.projects ?? [],
-    nextCursor: res?.metadata?.cursors?.next ?? null,
-  };
+  try {
+    const res = await wixApiRequest(PROJECTS_QUERY_URL, {
+      method: "POST",
+      body: {
+        includePageUrl: true,
+        query: cursor
+          ? { cursorPaging: { limit, cursor } }
+          : {
+              filter: { hidden: false, collectionIds: { $hasSome: [collectionId] } },
+              cursorPaging: { limit },
+            },
+      },
+    });
+    return {
+      projects: res?.projects ?? [],
+      nextCursor: res?.metadata?.cursors?.next ?? null,
+    };
+  } catch (err) {
+    // Degrade to an empty page instead of rethrowing (see queryCollections) — an uncaught
+    // read hangs the collection page on an infinite spinner; empty renders the empty state.
+    console.error("queryProjectsByCollection failed:", err);
+    return { projects: [], nextCursor: null };
+  }
 }
 
 /**

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

@@ -50,8 +50,9 @@ 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 fields directly from the Wix
-  product object (see the `Product` typedef in `wix-store.js` for key fields). For price, use
+  `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
@@ -65,6 +66,10 @@ reference for anything not shown.
   **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
@@ -86,6 +91,10 @@ reference for anything not shown.
 - **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

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

@@ -20,7 +20,9 @@ import { wixApiRequest } from "./wix-client.js";
  *   modifiers {array} — non-variant customizations (engraving, gift wrap):
  *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
  *        key, choicesSettings.choices, freeTextSettings.key }],
- *   plainDescription {string} — HTML product description,
+ *   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 } }]
@@ -28,6 +30,8 @@ import { wixApiRequest } from "./wix-client.js";
  *     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
  */