@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,223 @@
+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 } = {}) {
+  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 };
+  }
+}
+
+/**
+ * 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() {
+  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;
+  }
+}
+
+/**
+ * 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 } = {}) {
+  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 };
+  }
+}
+
+/**
+ * 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 } = {}) {
+  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 };
+  }
+}
+
+/**
+ * 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 [];
+  }
+}

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

@@ -0,0 +1,138 @@
+
+# Wix Restaurants Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and the helper file(s) you need from `references/restaurants/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`).
+>
+> | Need | Copy |
+> |---|---|
+> | Menu display (always) | `wix-restaurants-menu.js` |
+> | Online ordering (cart + checkout) | `wix-restaurants-ordering.js` |
+> | Table reservations | `wix-restaurants-reservations.js` |
+
+Builds a real, client-only Wix restaurant experience. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock the menu; never hand-build `/checkout` or reservation URLs —
+always go through the official cart + redirect-session and the reservations hold/reserve flow.
+
+## When to use
+- User wants a Wix restaurant site, an online food-ordering page, or a table-reservation page.
+- User asks to "connect Wix Restaurants" or replace placeholder menu/ordering/booking UI with live data.
+- Adding a menu, cart + checkout, or reservations over an existing Wix Restaurants setup.
+
+## Prerequisites
+1. A Wix site with the **Wix Restaurants Menus** app installed and **menu content already added**
+   (this skill is read-only over the menu — it does NOT create menus/items).
+2. For **online ordering**: at least one online-ordering **Operation** configured (Wix Restaurants
+   Orders). For **reservations**: the **Table Reservations** app installed with at least one location
+   and online reservations enabled. If a flow's backing app/config isn't set up, that flow returns
+   empty — flag it and continue; don't fabricate data.
+3. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (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 — hardcoding/committing
+   it is fine.
+4. 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 restaurant 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-restaurants-menu.js` — **Menu (read-only):**
+  `getFullMenu` (the assembled tree — start here), `listMenus`, `listSections`, `listItems`,
+  `listVariants`, `listModifierGroups`, `listModifiers`, `listLabels`
+- `src/rest/wix-restaurants-ordering.js` — **Online ordering:**
+  `listOperations`, `getDefaultOperation`, `addItemToCart`, `getCurrentCart`,
+  `updateCartItemQuantity`, `removeFromCart`, `checkout`
+- `src/rest/wix-restaurants-reservations.js` — **Reservations:**
+  `listReservationLocations`, `getTimeSlots`, `createHeldReservation`, `reserveReservation`
+
+The Menu, Item, ModifierGroup, Operation, Cart, ReservationLocation, TimeSlot, and Reservation
+shapes are documented as JSDoc at the top of each helper file. Read the relevant file(s) before
+building the UI — they describe the key fields and link to the full reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Menu page** — call `getFullMenu()` once. It returns `{ menus: [{ ...menu, sections: [{ ...section,
+  items: [assembledItem] }] }] }`, already ordered by `sectionIds` / `itemIds`. Render each item's
+  `name`, `description`, `image`, `labels` (`name` + `icon`), and `featured` flag. For price, show
+  `item.price` (single) or the `item.variants[]` (each `{ name, price }`). **Restaurants prices are
+  plain decimal strings with NO currency symbol** — format with the site's currency in the UI.
+- **Item detail** — render `item.modifierGroups[]`: each group's `name`, its `rule`
+  (`required`, `minSelections`, `maxSelections`), and `modifiers[]` (`name`, `additionalCharge`,
+  `preSelected`, `inStock`). If `orderSettings.acceptSpecialRequests`, offer a free-text field.
+- **Online ordering** — resolve an operation with `getDefaultOperation()` (or let the user pick from
+  `listOperations()`); if it's `null`, show an "ordering unavailable" state. Add a dish with
+  `addItemToCart(item.id, { operationId, menuId, sectionId, quantity })` — `menuId`/`sectionId` are
+  the menu and section the item was shown under. Read the cart back with `getCurrentCart()`; mutate
+  with `updateCartItemQuantity(lineItemId, qty)` / `removeFromCart(lineItemId)` using
+  `cart.lineItems[].id` (not the item id).
+- **Checkout** — `window.location.href = await checkout()`. After the visitor returns, the order is
+  placed and the cart is empty — re-fetch with `getCurrentCart()` on return (e.g. on mount +
+  `visibilitychange`) to clear the UI.
+- **Reservations** — `listReservationLocations()` for the picker (use `location` details for the
+  label; if a location's `configuration.onlineReservations.onlineReservationsEnabled` is false, hide
+  it). Then `getTimeSlots(locationId, dateISO, partySize)` — render `availableTimeSlots` (already
+  filtered to `AVAILABLE`). On slot pick, `createHeldReservation(locationId, slot.startDate,
+  partySize)` → keep the returned `id` + `revision`. Collect the visitor's details, then
+  `reserveReservation(id, revision, { firstName, phone, lastName?, email? })`. A `RESERVED` status is
+  confirmed; `REQUESTED` means the location requires manual approval — tell the user it's pending.
+- **Empty state** — if `getFullMenu()` returns no menus, show an empty state telling the user to add
+  a menu in their Wix dashboard. Never invent menu items.
+
+## Hard rules (do not violate)
+- ✅ Order ONLY through the cart: `addItemToCart()` → `checkout()` (`create-checkout` →
+  `/headless/v1/redirect-session` `fullUrl`), then redirect.
+- ❌ Never hand-build `/checkout`, ordering, or reservation URLs.
+- ❌ Never mock menus, items, prices, operations, locations, or time slots — 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).
+- ✅ `addItemToCart` requires `operationId`, `menuId`, and `sectionId` — it throws if any is missing.
+- ✅ `lineItemId` for cart mutations is `cart.lineItems[].id`, not the item id.
+- ✅ Reservations: offer only `AVAILABLE` slots; a HELD reservation expires in 10 minutes — pass the
+  `revision` from the hold into `reserveReservation`, and restart the flow if it expired.
+- ✅ Reservee `firstName` + `phone` (E.164, e.g. `+15551234567`) are mandatory to confirm.
+- The engine fails loudly on purpose: `addItemToCart`/`checkout` throw on out-of-stock or empty
+  carts; reservation helpers throw on unavailable slots or expired holds. A green path means it is
+  really orderable/bookable — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common menu / ordering / reservation paths. For the "20%" 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:
+- Restaurants API reference: https://dev.wix.com/docs/api-reference/business-solutions/restaurants.md
+- Selecting a specific **price variant** or applying **modifier up-charges** on the cart line: the
+  restaurants `catalogReference.options` shape for these is not documented for client add-to-cart.
+  The menu UI still displays them; confirm the shape before wiring them into `addItemToCart`:
+  https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/sample-flows.md
+- Fulfillment methods, delivery-address validation, scheduled (preorder) time slots, service fees:
+  see the Online Orders section of the reference.
+- **Member login + a "my orders" account view** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`): ordering/reserving works anonymously, but signing a member
+  in (custom login on your own UI) lets them see their own order/reservation history.
+
+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 restaurant content for their site — across up to three apps. To facilitate this, provide the user with deep links directly to the relevant dashboard pages; only mention the apps the project actually uses. Those pages are:
+- **Menu** (always) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-menus-new` (`Dashboard → Restaurant Menus`; click **Manage Items** to add dishes; only visible menus appear in the app)
+- **Online ordering** (if wired) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-orders-new/settings` (`Dashboard → Restaurant Orders → Settings`). Enable at least one fulfillment method before the site accepts orders — each has its own page: pickup `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-orders-new/settings/pickup`, delivery `.../wix-restaurants-orders-new/settings/delivery`, dine-in `.../wix-restaurants-orders-new/settings/dine-in`.
+- **Table reservations** (if wired) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-table-reservations/table-reservations` (`Dashboard → Table Reservations` → **Settings**; configure tables, availability, and enable online reservations)
+
+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)
+- [ ] `getFullMenu()` renders real sections/items with prices, variants, modifiers, and labels
+- [ ] Empty state shown when there are no menus (never invented items)
+- [ ] Add to cart works with a real `operationId`/`menuId`/`sectionId`; out-of-stock items throw
+- [ ] Quantity update / remove reflect in `getCurrentCart()`
+- [ ] Checkout redirects via redirect-session `fullUrl` (no hand-built URL); cart re-fetched on return
+- [ ] Reservations: only `AVAILABLE` slots offered; hold → reserve produces `RESERVED`/`REQUESTED`
+- [ ] No mock data anywhere
+- [ ] Told the user at least once that they can continue setting up their restaurant (menu / ordering / reservations) in the dashboard and provided deep links.