@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -0,0 +1,111 @@
+
+# Wix Portfolio Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/portfolio/wix-portfolio.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+
+Builds a real, client-only Wix portfolio showcase. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Portfolio is **read-only**: never mock projects, never invent media,
+and always render live Wix data (or an honest empty state). The content tree is
+**Collection → Project → Project Item (image/video)**.
+
+## When to use
+- User wants a Wix portfolio / showcase site or asks to "connect Wix Portfolio".
+- Replacing placeholder/mock galleries with live Wix Portfolio data.
+- Adding a collections gallery, project grids, or a project detail page (media gallery +
+  details/links) over an existing Wix Portfolio.
+
+## Prerequisites
+1. A Wix site with **Wix Portfolio installed and content already added** — at least one
+   collection with projects, and projects with items (this skill does NOT provision; it is
+   read-only over the content).
+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 visitor-facing
+   credential (it only mints anonymous visitor tokens), **not** a secret, so
+   hardcoding/committing it is fine.
+3. If the read calls return `403`/`428` before content is published, the Portfolio app or its
+   content may not be live yet. That is a **Wix dashboard setup step the owner completes** —
+   out of this skill's scope. Flag it and continue; don't fall back to mock data.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the portfolio'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
+  persisted to localStorage; do not re-mint anonymously per load.
+- `src/rest/wix-portfolio.js` — exports:
+  - **Collections:** `queryCollections`, `getCollectionBySlug`, `countCollections`
+  - **Projects:** `queryProjects`, `queryProjectsByCollection`, `getProjectBySlug`, `getProject`
+  - **Project items (media):** `listProjectItems`
+
+The Collection, Project, and Project Item shapes are documented as JSDoc comments at the top of
+`wix-portfolio.js`. Read them before building the UI — they describe the key fields (cover
+image/video, media resolutions, details rows) and link to the full API reference.
+
+## How to wire it (UI is the project's choice)
+- **Collections gallery (home)** — `queryCollections()` for the listing (visible collections
+  only, in dashboard order); pass `nextCursor` back as `cursor` to load the next page. Render
+  `collection.title`, `collection.description`, and `collection.coverImage.imageInfo.url`. Link
+  each card to a collection page keyed on `collection.slug`.
+- **Collection page** — `getCollectionBySlug(slug)` for the header (returns null on miss — show
+  a not-found state, never invent one). Then `queryProjectsByCollection(collection.id, { limit?, cursor? })`
+  for its project grid; paginate exactly like `queryCollections`.
+- **All-work gallery (optional)** — `queryProjects()` to list every visible project across
+  collections (newest-first); paginate the same way.
+- **Project grid card** — render `project.title` and the cover: use `project.coverImage.imageInfo.url`
+  when present, else the `project.coverVideo.videoInfo.posters[0]` / first
+  `coverVideo.videoInfo.resolutions[]` entry. Link each card to a project page keyed on `project.slug`.
+- **Project detail page** — `getProjectBySlug(slug)` for the header (title, description, and the
+  `details[]` rows: each has a `label` plus either `text` or `link: { text, url, target }`).
+  Then `listProjectItems(project.id)` for the media gallery — render IMAGE items from
+  `image.imageInfo.url` and VIDEO items from the first `video.videoInfo.resolutions[]` entry
+  (with `video.videoInfo.posters[0]` as the poster). Honor each item's optional `link`.
+  - If you already hold a project id (not a slug), use `getProject(projectId)` instead.
+- **Empty state** — if `countCollections()` is 0, show an empty state telling the user to add
+  collections and projects in their Wix dashboard. Never invent projects or media.
+
+## Hard rules (do not violate)
+- ✅ Render only live Wix Portfolio data — collections, projects, and items as returned.
+- ❌ Never mock projects, collections, or media — render live data or the empty state.
+- ❌ Never hand-build Wix Media URLs or page permalinks — use the `url`/`imageInfo.url`/
+  `videoInfo.resolutions[].url` fields Wix returns.
+- ❌ Never invent project details, captions, dates, or testimonials. Show only what the API returns.
+- ❌ Never show `hidden: true` collections or projects to visitors (the helpers already filter
+  `hidden` out — don't add them back).
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Route on `slug` (`getCollectionBySlug` / `getProjectBySlug`); fall back to `getProject(id)`
+  only when you hold a GUID.
+- The helpers fail soft on read: single fetches return `null` on a miss so you render a
+  not-found/empty state rather than a crash — surface that state, don't paper over it with fake data.
+
+## Beyond the snippets
+The snippets cover the common portfolio paths. If you hit a use case they don't cover (e.g.
+collection SEO tags, project watermark settings, portfolio-wide settings, or filtering by a
+field not shown), 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:
+- Wix Portfolio API reference: https://dev.wix.com/docs/api-reference/business-solutions/portfolio.md
+- Portfolio Settings (logo, layout, options): https://dev.wix.com/docs/api-reference/business-solutions/portfolio/portfolio-settings/get-portfolio-settings.md
+- API query language (filters, sort, paging): https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md
+
+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 portfolio content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For portfolio data those pages are:
+- **Portfolio** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-portfolio/projects` (`Dashboard → Portfolio`). Projects and Collections are tabs on this one page: the **Projects** tab adds projects and their media galleries; the **Collections** tab groups projects into collections.
+
+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 (no re-mint storm; reads stay fast)
+- [ ] Collections gallery renders live collections with cover images, in dashboard order
+- [ ] Clicking a collection lists its projects via `queryProjectsByCollection`
+- [ ] Project page renders the project's media gallery from `listProjectItems` (images AND videos)
+- [ ] Project `details[]` rows render (text rows and link rows both)
+- [ ] Slug routing works; an unknown slug shows a not-found state (no invented project)
+- [ ] Hidden collections/projects never appear
+- [ ] Empty state shown when `countCollections()` is 0
+- [ ] No mock projects, collections, or media anywhere
+- [ ] Told the user at least once that they can continue setting up their portfolio in the dashboard and provided deep links.

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

@@ -0,0 +1,194 @@
+import { wixApiRequest } from "./wix-client.js";
+
+/**
+ * Wix Portfolio — read-only showcase. 3-level tree:
+ *   Collection → Project → Project Item (image or video)
+ * Hidden entities (hidden: true) are editor-only — every helper here filters them out.
+ *
+ * Collection: { id, title, description, slug, hidden, sortOrder,
+ *   coverImage.imageInfo: { id, url, height, width, altText },
+ *   url: { relativePath, url } (only when includePageUrl=true) }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/collection-object.md
+ *
+ * Project: { id, title, description, slug, hidden, collectionIds {string[]},
+ *   details {array} — [{ label, text? OR link: { text, url, target } }],
+ *   coverImage.imageInfo: { id, url, height, width, altText } (ONE-OF with coverVideo),
+ *   coverVideo.videoInfo: { id, url, posters, resolutions },
+ *   url: { relativePath, url } (only when includePageUrl=true) }
+ * Full media gallery is in Project Items — fetch with listProjectItems(project.id).
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/project-object.md
+ *
+ * Project Item: { id, projectId, sortOrder, title, description,
+ *   type "IMAGE"|"VIDEO"|"UNDEFINED",
+ *   image.imageInfo: { id, url, height, width, altText } (when IMAGE),
+ *   video.videoInfo: { id, url, posters, resolutions } (when VIDEO; render first resolution),
+ *   link: { text, url, target } }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/project-item-object.md
+ */
+
+const COLLECTIONS_QUERY_URL = "/portfolio/v1/collections/query";
+const PROJECTS_QUERY_URL = "/portfolio/v1/projects/query";
+
+/**
+ * Query visible portfolio collections (one page), sorted by their dashboard order.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/query-collections.md
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @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,
+  };
+}
+
+/**
+ * Get a single visible collection by its URL slug. Returns null if not found / hidden.
+ * Portfolio has no get-by-slug endpoint, so this queries with a slug filter.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/query-collections.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getCollectionBySlug(slug) {
+  const res = await wixApiRequest(COLLECTIONS_QUERY_URL, {
+    method: "POST",
+    body: {
+      includePageUrl: true,
+      query: { filter: { slug, hidden: false }, cursorPaging: { limit: 1 } },
+    },
+  });
+  return res?.collections?.[0] ?? null;
+}
+
+/**
+ * Total number of visible collections. Used for empty-state logic
+ * (0 → prompt the user to add collections in their Wix dashboard).
+ * @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);
+}
+
+/**
+ * Query visible projects (one page), sorted newest-first. Use for an "all work" gallery.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects.md
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @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,
+  };
+}
+
+/**
+ * Query the visible projects that belong to a collection (one page), in dashboard order.
+ * Filters on `collectionIds` with `$hasSome`.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects.md
+ * @param {string} collectionId  `collection.id` from queryCollections / getCollectionBySlug.
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @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,
+  };
+}
+
+/**
+ * Get a single visible project by its URL slug. Returns null if not found / hidden.
+ * Portfolio has no get-by-slug endpoint, so this queries with a slug filter.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getProjectBySlug(slug) {
+  const res = await wixApiRequest(PROJECTS_QUERY_URL, {
+    method: "POST",
+    body: {
+      includePageUrl: true,
+      query: { filter: { slug, hidden: false }, cursorPaging: { limit: 1 } },
+    },
+  });
+  return res?.projects?.[0] ?? null;
+}
+
+/**
+ * Get a single project by its GUID. Returns null if not found.
+ * Use when you already hold a project id (e.g. from a list) rather than a slug.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/get-project.md
+ * @param {string} projectId
+ * @returns {Promise<object|null>}
+ */
+export async function getProject(projectId) {
+  try {
+    const res = await wixApiRequest(`/portfolio/v1/projects/${encodeURIComponent(projectId)}`, {
+      method: "GET",
+      query: { includePageUrl: "true" },
+    });
+    return res?.project ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all media items (images/videos) of a project, in dashboard order.
+ * This is the project's gallery — call it on the project detail screen.
+ * https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items.md
+ * @param {string} projectId  `project.id`.
+ * @param {{ limit?: number, offset?: number }} [options]  Project items use offset paging, not cursors.
+ * @returns {Promise<{ items: object[], total: number }>}
+ */
+export async function listProjectItems(projectId, { limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest(`/portfolio/v1/projectItems/${encodeURIComponent(projectId)}/items`, {
+    method: "GET",
+    query: { "paging.limit": String(limit), "paging.offset": String(offset) },
+  });
+  const items = (res?.items ?? []).slice().sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0));
+  return { items, total: res?.metadata?.total ?? items.length };
+}

package/skills/wix-vibe-headless/references/pricing-plans/INSTRUCTIONS.md

@@ -0,0 +1,127 @@
+
+# Wix Pricing Plans Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/pricing-plans/wix-pricing-plans.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+
+Builds a real, client-only Wix pricing-plans / membership front end. The browser talks to Wix
+directly over a public `WIX_CLIENT_ID`. Never mock plans; never hand-build a `/checkout` or
+purchase URL — purchasing always goes through the Wix-hosted **redirect-session** (which also
+handles member login and payment).
+
+## When to use
+- User wants a "Plans & Pricing", membership, or subscription page on a Wix site.
+- User asks to "connect Wix pricing plans" or sell memberships / subscriptions / paid plans.
+- Replacing placeholder/mock plans with live Wix data.
+- Adding a plan detail page, a buy/subscribe button, or a "my plans" area over existing plans.
+
+## Prerequisites
+1. A Wix site with **Pricing Plans installed and at least one plan created** (this skill does
+   NOT provision — it's read-only over the plans the merchant added in the dashboard).
+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. **Purchasing a plan is members-only and uses Wix-hosted checkout.** The hosted flow handles
+   member login/signup + the order form + payment, then returns to your site. The deployed app
+   domain must be allow-listed on the OAuth client for that return to work — this is a **separate
+   Wix setup flow the user completes later**, out of this skill's scope. If the return fails
+   before that setup is done, that's expected; flag it and continue.
+4. To actually charge for paid plans, the site needs a payment method connected and (where
+   applicable) tax/business-address configured in the Wix dashboard. Free plans work without this.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the page'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
+  persisted to localStorage; after a hosted checkout the same identity returns as a logged-in
+  member. Do not re-mint anonymously per load.
+- `src/rest/wix-pricing-plans.js` — exports:
+  - **Plans:** `queryPlans`, `getPlanById`, `getPlanBySlug`
+  - **Purchase:** `checkout`
+  - **Member:** `getMyPlanOrders`
+
+The Plan and Order shapes are documented as JSDoc comments at the top of `wix-pricing-plans.js`.
+Read them before building the UI — pricing has several models (recurring subscription,
+single-payment-for-duration, single-payment-unlimited, free, plus free trials) and the JSDoc
+shows exactly how to read price, cycle, and trial for display.
+
+## How to wire it (UI is the project's choice)
+- **Plans grid** — `queryPlans()` for the listing (PUBLIC plans only); pass `nextCursor` back as
+  `cursor` to load the next page. For each plan render `name`, `description`, `perks[].description`
+  as feature bullets, and the price from `pricingVariants[0]` (see the JSDoc "Reading the price"
+  notes: `pricingStrategies[0].flatRate.amount` + plan `currency`, plus `billingCycle` for
+  recurring and `freeTrialDays` for trials). Show a "Subscribe"/"Buy" button only when
+  `plan.buyable` is true.
+- **Plan detail** — `getPlanBySlug(slug)` keyed off the URL slug (or `getPlanById(id)`); returns
+  null on miss — show a not-found state, never invent a plan. Render perks, the full price/billing
+  summary, free-trial note, and `termsAndConditions` if present.
+- **Purchase** — `window.location.href = await checkout(planId, { thankYouPageUrl })`. This
+  redirects to Wix-hosted checkout, which logs the member in (or signs them up), collects the
+  order form, and takes payment. On success Wix returns to `thankYouPageUrl` with a
+  `?planOrderId=<GUID>` query param (and `wixMemberLoggedIn`); on abandon/interrupt it returns to
+  `postFlowUrl` (defaults to the current page). Never create the order or build the URL yourself.
+- **My plans / confirmation** — `getMyPlanOrders()` for the logged-in member's purchases; filter
+  with `{ orderStatuses: ["ACTIVE"] }` for current memberships. After returning from checkout,
+  re-fetch (e.g. on mount + `visibilitychange`, or when `planOrderId` is in the URL) to show the
+  new order. Returns `[]` for anonymous visitors — show a "log in to see your plans" state, and wire
+  that log-in via the **members** vertical (`references/members/`) so they can sign in on your own UI.
+- **Empty state** — if `queryPlans()` returns no plans, show an empty state telling the user to
+  create plans in their Wix dashboard. Never invent plans.
+
+## Hard rules (do not violate)
+- ✅ Purchase ONLY via `checkout()` (`/headless/v1/redirect-session` with `paidPlansCheckout`),
+  then redirect to `redirectSession.fullUrl`.
+- ❌ Never hand-build a checkout, purchase, or `/plans-checkout` URL; never call create-order
+  directly from the client to "skip" the hosted flow.
+- ❌ Never mock plans — render live Wix data or the empty state.
+- ❌ Never invent perks, prices, trials, testimonials, or member counts. Render only what the
+  plan object returns; empty perks → no feature list.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Treat plan objects as display-only — never compute the final charge; Wix settles price, tax,
+  proration, and schedule during hosted checkout.
+- ✅ Show the buy button only when `plan.buyable` is true; otherwise the plan is merchant-assigned.
+- The engine fails loudly on purpose: `checkout()` throws if it can't create the redirect session.
+  A green path means it really reached Wix-hosted checkout — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common plans paths. If you hit a use case they don't cover, 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:
+- Pricing Plans API reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans.md
+- Orders (cancel / pause / resume a member's order, price preview): https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders.md
+- Headless redirect session (login, logout, other checkouts): https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+
+Common genuine gaps and where to look:
+- **Cancel / pause / resume** a member's subscription → Orders API (`request-cancellation`,
+  `pause-order`, `resume-order`). Gate on `plan.buyerCanCancel`.
+- **Member login / logout** outside of a purchase → use the **members** vertical
+  (`references/members/INSTRUCTIONS.md`) for *custom* login (email+password / Google / Facebook / SSO)
+  on your own UI — so a member can log in *before* subscribing and see "my plans" without going through
+  a purchase. Pair it with this vertical whenever plans need a real account surface.
+- **Coupons / custom start date** at purchase → covered by the hosted checkout; for a fully
+  custom flow see Create Online Order in the Orders reference.
+
+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 pricing plans content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For pricing plans data those pages are:
+- **Pricing Plans** — `https://manage.wix.com/dashboard/{metaSiteId}/pricing-plans` (`Dashboard → Pricing Plans`) → **+ Create Plan** (set the name, pricing model, perks, and connect the plan to the content/services it unlocks)
+
+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)
+- [ ] Plans list renders live data; price, billing cycle, and free trial read correctly across
+      pricing models (recurring, single-payment, free)
+- [ ] Plan detail loads by slug and shows a not-found state on a bad slug
+- [ ] Buy button shown only for `buyable` plans
+- [ ] Purchase redirects via redirect-session `fullUrl` (no hand-built URL) and reaches
+      Wix-hosted login + payment
+- [ ] On return, the new order appears via `getMyPlanOrders()` (and a "log in" state shows for
+      anonymous visitors)
+- [ ] Empty state shown when `queryPlans()` returns no plans
+- [ ] No mock plans, perks, or prices anywhere
+- [ ] Told the user at least once that they can continue setting up their plans in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/pricing-plans/wix-pricing-plans.js

@@ -0,0 +1,157 @@
+import { wixApiRequest } from "./wix-client.js";
+
+/**
+ * Wix Pricing Plans V3 Plan — key fields for a Plans & Pricing page.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/plan-object.md
+ *
+ *   id {string}, name {string}, description {string}, slug {string},
+ *   image {object} — { id, width, height, altText } (id is a WixMedia id),
+ *   currency {string} — ISO-4217 e.g. "USD", termsAndConditions {string},
+ *   visibility "PUBLIC"|"PRIVATE" — queryPlans returns PUBLIC only,
+ *   buyable {boolean} — hide buy button when false, buyerCanCancel {boolean},
+ *   perks {array} — [{ id, description }] feature bullets,
+ *   pricingVariants {array} — 1 variant per plan:
+ *     [{ id, name, freeTrialDays, pricingStrategies[0].flatRate.amount (decimal string, "0" = free),
+ *        billingTerms: { billingCycle: { period "DAY"|"WEEK"|"MONTH"|"YEAR", count },
+ *        startType "ON_PURCHASE"|"CUSTOM", endType "UNTIL_CANCELLED"|"CYCLES_COMPLETED" } }]
+ * Display price: amount = v.pricingStrategies[0].flatRate.amount + plan.currency.
+ * Never compute a final charge — Wix settles price, tax, and schedule at hosted checkout.
+ *
+ * Order (member's purchase) — key fields for "My plans" screen.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/order-object.md
+ *   id {string}, planId {string}, planName {string},
+ *   status "DRAFT"|"PENDING"|"ACTIVE"|"PAUSED"|"ENDED"|"CANCELED",
+ *   lastPaymentStatus "PAID"|"REFUNDED"|"FAILED"|"UNPAID"|"NOT_APPLICABLE",
+ *   startDate {string}, endDate {string}, freeTrialDays {number},
+ *   currentCycle { index, startedDate, endedDate }, autoRenewCanceled {boolean}
+ */
+
+const REDIRECT_SESSION_URL = "/headless/v1/redirect-session";
+
+/**
+ * Query public, listable pricing plans (one page).
+ * Returns only PUBLIC plans (the ones meant for the Plans & Pricing page). Some plans may have
+ * `buyable: false` (merchant-assigned only) — keep them for display but hide the buy button.
+ *
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
+ *
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ plans: object[], nextCursor: string|null }>}
+ */
+export async function queryPlans({ limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/pricing-plans/v3/plans/query", {
+    method: "POST",
+    body: {
+      query: {
+        ...(cursor ? {} : { filter: { visibility: "PUBLIC" } }),
+        cursorPaging: cursor ? { limit, cursor } : { limit },
+      },
+    },
+  });
+  return {
+    plans: res?.plans ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Fetch a single plan by its GUID. Returns null if not found.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/get-plan.md
+ *
+ * @param {string} planId  Plan GUID (`plan.id`).
+ * @returns {Promise<object|null>}
+ */
+export async function getPlanById(planId) {
+  try {
+    const res = await wixApiRequest(`/pricing-plans/v3/plans/${encodeURIComponent(planId)}`, {
+      method: "GET",
+    });
+    return res?.plan ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch a single PUBLIC plan by its URL slug. Returns null if not found.
+ * There is no get-by-slug endpoint, so this queries with a slug filter and returns the first match.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
+ *
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getPlanBySlug(slug) {
+  const res = await wixApiRequest("/pricing-plans/v3/plans/query", {
+    method: "POST",
+    body: {
+      query: {
+        filter: { visibility: "PUBLIC", slug },
+        cursorPaging: { limit: 1 },
+      },
+    },
+  });
+  return res?.plans?.[0] ?? null;
+}
+
+/**
+ * Start a purchase for a plan and return the Wix-hosted checkout URL.
+ *
+ * Pricing Plans purchases are MEMBERS-ONLY: the hosted flow handles member login (or signup),
+ * the order form, and payment, then returns the visitor to your site. Redirect the browser to the
+ * returned URL — do NOT create the order yourself; Wix settles price, tax, and the subscription.
+ *
+ * On return:
+ *   - postFlowUrl is hit when the flow completes, is abandoned, or is interrupted.
+ *   - thankYouPageUrl (if given) is hit only on success, with a `?planOrderId=<GUID>` query param.
+ *   - Both callbacks also carry `wixMemberLoggedIn` (true if a member logged in during the flow).
+ * After a successful purchase the visitor is a logged-in member — call getMyPlanOrders() to confirm.
+ *
+ * Reference: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+ *
+ * @param {string} planId  Plan GUID (`plan.id`). Must be a buyable plan.
+ * @param {{ thankYouPageUrl?: string, postFlowUrl?: string }} [options]
+ * @returns {Promise<string>} The hosted checkout URL to redirect to.
+ */
+export async function checkout(planId, { thankYouPageUrl, postFlowUrl } = {}) {
+  if (!planId) throw new Error("Cannot check out: a planId is required.");
+  const callbacks = { postFlowUrl: postFlowUrl ?? window.location.href };
+  if (thankYouPageUrl) callbacks.thankYouPageUrl = thankYouPageUrl;
+
+  const redirect = await wixApiRequest(REDIRECT_SESSION_URL, {
+    method: "POST",
+    body: { paidPlansCheckout: { planId }, callbacks },
+  });
+  const url = redirect?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Failed to create the pricing-plan checkout redirect session.");
+  return url;
+}
+
+/**
+ * List the currently logged-in member's own plan orders (their purchases / subscriptions).
+ * Use for a "My plans" screen and to confirm a purchase after returning from checkout.
+ *
+ * Requires a MEMBER identity. For an anonymous visitor (not logged in) Wix returns no member
+ * context — this resolves to `[]` rather than throwing, so the UI can show a "log in to see your
+ * plans" state. Up to 50 orders are returned per call.
+ *
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-orders-service-list-orders.md
+ *
+ * @param {{ orderStatuses?: string[], limit?: number, offset?: number }} [options]
+ *        orderStatuses: filter, e.g. ["ACTIVE"] | ["ACTIVE","PENDING","PAUSED"].
+ * @returns {Promise<object[]>} The member's orders (empty array if none / not a member).
+ */
+export async function getMyPlanOrders({ orderStatuses, limit, offset } = {}) {
+  try {
+    const res = await wixApiRequest("/pricing-plans/v2/member/orders", {
+      method: "GET",
+      query: {
+        orderStatuses,
+        limit: limit !== undefined ? String(limit) : undefined,
+        offset: offset !== undefined ? String(offset) : undefined,
+      },
+    });
+    return res?.orders ?? [];
+  } catch {
+    return [];
+  }
+}