@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-base44-connector/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-base44-connector
-description: "Build on Wix from the Base44 builder sandbox — this file is the complete guide (site context, doc discovery, API contracts, who calls Wix from where), and scripts/utils.js is its helper module, loaded from disk per exec. Triggers: build a Base44 app on a connected Wix site, look up a Wix API from the sandbox, decide frontend vs backend for a Wix call."
+description: "Build on and manage the connected Wix site from a Base44 app: discover and call any Wix API (endpoints, request/response shapes, fields), gather site context, route each call to the right identity, and follow curated recipes for admin tasks."
 ---
 
 # Building on Wix from Base44
@@ -10,6 +10,17 @@ find the APIs and learn their contracts from the docs, write the code. **Discove
 request and response fields all come from the calls below, never from memory or pattern. 404 or
 empty ⇒ discover, not permute. Examples teach mechanics and go stale — verify before relying.
 
+**Start every Wix task by getting the site context** (`wx.context`, below). It reports what the
+site actually has and how each part is configured, so every call targets what is really there
+instead of a guess from a name. It is the first step of a task, not a one-time setup: a later turn
+does not inherit an earlier turn's context, so re-read it before building on or calling a Wix API.
+
+**A management or admin task starts at the recipes**: call `wx.mgmtRecipes` (Learn Wix) and follow
+the one that fits. A recipe states outright what an API does not support, which fields a bulk call
+actually writes, and the order two calls have to go in — from the schemas alone those get re-derived
+several errors at a time. A REST search ranks the matching recipes too (`recipes` in its return), so
+they also surface from a search that began at the methods.
+
 ## What are you building?
 
 The app's audience picks the token, and the token picks the architecture: the **visitor token is
@@ -18,22 +29,24 @@ the connector's, server-side only.
 
 ```
 browser            ──(visitor token)─► wixapis.com   the visitor's own reads & actions
-base44/functions/* ──(admin token)───► wixapis.com   work that needs the owner's identity
+base44/functions/… ──(admin token)───► wixapis.com   work that needs the owner's identity
 exec_tool          ──(admin token)───► wixapis.com   you: ad hoc probing/managing while building
 ```
 
-**A site for visitors** — storefront, blog, booking. Headless means the Wix site has no pages of
-its own: your app IS its frontend. **The complete visitor experience —
+**A site for visitors** — store, blog, booking, ecom, CMS, CRM, and the rest of the business solutions.
+Your app is the site's frontend — whether the site is headless (no pages of its own) or your
+frontend extends an existing site. **The complete visitor experience —
 every page, every read, every action a visitor takes — is browser calls on the visitor token;
 none of it needs a backend function.** Public reads
-included (the visitor token queries the catalog directly), and `carts/current/*` + checkout act
-on the CALLER's cart, so only the visitor token reaches the visitor's cart. One file carries it
-all: `src/lib/wixClient.js` (Write the code, below). `base44/functions/*` appear only where work
+included (the visitor token queries public content directly), and per-visitor state is scoped to
+the CALLER — an API that acts on "the current visitor's" data resolves the visitor from the
+token, so only the visitor token reaches that visitor's own state. One shared visitor client
+carries it all (Write the code, below). `base44/functions/…` appear only where work
 needs the owner's identity — elevated-permission ops a visitor triggers, webhooks, scheduled
 jobs — and for the app's non-Wix backend.
 
-**An admin tool for the owner** — dashboard, back office. The pages act as the owner, whose token
-is a secret: `pages → base44/functions/* ──(admin token)──► wixapis.com`.
+**An admin tool for the owner** — dashboard, back office. Admin pages and agent act as the
+owner, using the secret admin token: `pages → base44/functions/… ──(admin token)──► wixapis.com`.
 
 ## The helpers
 
@@ -49,15 +62,25 @@ const wx = (() => { const m = { exports: {} };
   new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
 ```
 
-Results ≤ 4,000 chars come back inline (exec results clip at ~5,000); anything bigger is saved
-under `.agents/skills/wix-base44-connector/tmp/` and returns `{ path, bytes, lines, outline }` —
-the outline is the map. Read a saved file the way you already know how:
-`wx.bash("grep -n 'term' <path> | head -40")` to find (GNU grep/sed, awk is mawk, no rg;
-across everything saved: `grep -rn 'term' .agents/skills/wix-base44-connector/tmp/`), and
-`read_file` to quote — a window via `offset`/`limit` at the lines grep named, or the whole
-file when it fits read_file's 45K cap. **API responses are site data and never land in
-never saved** — project them to facts. Fetch every URL inside exec with `fetch()` — website/browser
-tools clip at 10,000 chars silently. One exec per round; timeout 10s, up to 120 via `{timeout}`.
+`wx` exports these helpers:
+
+- `wx.post/get/patch/put/del(url, [body], token?)` — JSON transports, one per verb (`get`/`del` take no body): Bearer from `token`, non-2xx **throws** the API's own error
+- `wx.clip(value)` — cap a return value: oversized → `{ truncated, total, head }`; renders `undefined` as `null` so absence stays visible
+- `wx.context(token, section?)` — the site's dynamic context report; no section → its outline
+- `wx.browse(menuUrl, { include, filter, depth })` — walk a docs-portal menu deterministically
+- `wx.search(term, { type, max, lines })` — ranked docs search; hits carry endpoint (`VERB url`) + docsUrl + gist, and the worked requests the docs publish for them. A REST search also ranks the **management recipes**, returned as their own `recipes` list ahead of the methods — each with its steps, the endpoints it calls, and `file` when the wix-manage skill is on disk
+- `wx.page(docsUrl)` — read a doc page; its worked examples come back as titles + line numbers
+- `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
+- `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
+- `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
+- `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
+
+Every helper answers inline when the result fits (≤ 4,000 chars — exec results clip at ~5,000).
+A bigger result is saved under `.agents/skills/wix-base44-connector/tmp/` and comes back as
+`{ path, bytes, lines, outline }` — the outline is your map into the file. Work a saved file in
+two moves: find with `wx.bash("grep -n 'term' <path> | head -40")` (or across every save:
+`grep -rn 'term' .agents/skills/wix-base44-connector/tmp/`), then quote with `read_file` — an
+`offset`/`limit` window at the lines grep named, or the whole file when it fits the 45K cap.
 
 ## Gather context — the dynamic context report
 
@@ -72,8 +95,27 @@ An empty report = bad token, never an empty site.
 
 ## Learn Wix — find the APIs, learn their contracts
 
+### Management recipes — first stop for an admin task
+
+Curated admin flows, by category — ecommerce, bookings, stores, cms, google-ads, sites, contacts,
+get-paid, marketing, pricing-plans, events, blog, forms, restaurants, domains, media, …:
+
+```js
+await wx.mgmtRecipes();           // categories with counts
+await wx.mgmtRecipes("stores");   // a category's list — or any task word: wx.mgmtRecipes("coupon")
+// each row points at its recipe: `file` when the wix-manage skill is installed — read_file it
+// straight off disk — else `url`: wx.page(url), whole when small, saved + outline when big
+```
+
+A recipe carries prerequisites, order, and gotchas that no method page has. A REST search ranks
+these same recipes as its own `recipes` list, so they surface either way.
+
+### Find a method — search and browse
+
 ```js
-// know the product? browse is deterministic — menuUrl alone orients (children + counts);
+// name the method? search finds it in one call:
+await wx.search("stores v3 update product");   // → [{ method, endpoint: "VERB url", docsUrl, gist }]; call wx.<verb>(url, body, token); spec(docsUrl) for the full schema
+// exploring an unfamiliar product? browse is deterministic — menuUrl alone orients (children + counts);
 // filter before listing methods. browse works for both portals this skill uses — REST
 // (api-reference) and WIX_HEADLESS (go-headless) — just pass that portal's menu URL.
 await wx.browse("https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings",
@@ -91,6 +133,22 @@ await wx.search("pause a pricing plan subscription and resume it");
 await wx.search("mint a visitor token and read the current cart", { type: "WIX_HEADLESS" });
 ```
 
+Products and their capabilities — the common ones, partial lists:
+
+- **Stores** — products · categories · product options and variants · inventory · promotions · *+7 more*
+- **Bookings** — services · appointments · classes · staff members · time slots · waitlists · *+7 more*
+- **eCommerce** — cart · checkout · orders · order fulfillment · discount rules · *+7 more*
+- **Events** — events · ticket definitions · RSVP · check-in · *+6 more*
+- **Restaurants** — menus · items · item modifiers · online orders · reservations · *+9 more*
+- **Blog** — posts · draft posts · categories · tags · *+3 more*
+- **CMS** — data items · data collections · collection permissions · external databases · *+4 more*
+- **Pricing Plans** — plans · orders · recurring subscriptions · free trial periods · *+4 more*
+- **Members & Contacts** — contacts · labels · extended fields · members · badges · *+7 more*
+- **Forms** — form schemas · form submissions · interactive form sessions · *+3 more*
+- **Loyalty** — loyalty points · earning rules · tiers · rewards · *+5 more*
+
+Full list — all 36 products, their capabilities and docs paths: `references/CAPABILITY_MAP.md`.
+
 Go deeper for fields, enums, or absence — only the spec index proves absence.
 
 ### Read a doc page
@@ -100,8 +158,9 @@ map and window in the SAME exec; coordinates are for your code, not for a second
 
 ```js
 const pg = await wx.page(docsUrl);   // whole text when small; else { path, bytes, lines, outline }
-// your half, windowed to your term and its Examples (a complete working request — URL, headers,
-// body — usually all you need), one round:
+// pg.examples lists the page's worked requests as { title, line } — a complete request (URL,
+// headers, body) is usually all you need: read_file(pg.path, offset: <its line>)
+// anything else, windowed to your term in the same round:
 return wx.bash(`sed -n '/^## REST API/,/^## JavaScript SDK/p' ${pg.path} | grep -B5 -A40 -i 'examples\\|<term>' | head -c 3800`);
 // a giant fenced example → its field vocabulary instead of paging it:
 // wx.bash(`sed -n '<a>,<b>p' ${pg.path} | grep -oE '"[a-zA-Z]+":' | sort -u | head -60`)
@@ -112,7 +171,17 @@ lines weren't enough.
 
 ### The spec index — a located method's exact schema
 
-Read the schema of a method you already have a `docsUrl` for (from search/browse):
+Pass a method's `docsUrl` (a search/browse hit carries it) — spec loads that method's schema (request
+body, responses, filterable-fields map, examples) in one call, a direct lookup. Read the field
+**descriptions**, not just the names — they carry the rules (which field is canonical, when one is empty):
+
+```js
+const sp = await wx.spec(hit.docsUrl);
+// sp.examples — the method's worked requests as { title, line }, all saved at sp.examplesPath.
+// The one that matches the task is rarely the first: read_file(sp.examplesPath, offset: <its line>)
+```
+
+Want to shape the result yourself? Pass raw code against the index (`lightIndex` + `getResourceSchemaByUrl`):
 
 ```js
 await wx.spec(`
@@ -134,40 +203,52 @@ await wx.spec(`
 `filterable` maps each field to its allowed operators + sort — filter server-side only on what it
 lists, else filter in code.
 
-### Management recipes — check before composing admin flows
-
-~100 curated multi-step management (admin) flows across 23 categories — the largest are
-ecommerce (24), bookings (13), stores (9), cms (7), google-ads (7), sites (7), contacts (5),
-then get-paid, marketing, pricing-plans, events, blog, forms, restaurants, domains, media, …:
-
-```js
-await wx.mgmtRecipes();           // categories with counts
-await wx.mgmtRecipes("stores");   // a category's list — or any task word: wx.mgmtRecipes("coupon")
-await wx.page(url);           // read the chosen recipe — whole when small, saved + outline when
-                              // big; then grep / read_file windows by the outline's line numbers
-```
+## Write the code
 
-A matching recipe beats composing the flow from single endpoints: it carries ordering and
-cross-step gotchas no method page mentions.
+**REST, not the JS SDK** — everywhere: the admin ops you run while building, backend functions,
+frontend pages. Doc pages carry twin REST and SDK halves; read the REST one.
 
-## Write the code
+**Send what the page documents, nothing more** — required fields, nesting, and enum values exactly
+as spelled; a header only when the operation's REST section lists it. Never `wix-site-id`: every
+token here is already bound to a site, and in the browser the header fails CORS preflight outright.
 
-**Response shapes obey the discover rule in every lane**: code against fields you saw in a live
-response or the schema — remembered names are often from older versions. Probe one real row first.
+**Shapes are discovery too**: read a method's request/response schema from `spec()` — its field
+descriptions state which field is canonical and when one reads back empty. Don't infer shape from a
+single live probe: it reflects only the params you sent, so probe with the same request your code makes.
 
-### Admin calls — exec ad hoc, backend functions deployed
+### Admin ops while building — you, in exec_tool
 
 ```js
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const data = await wx.post("https://www.wixapis.com/contacts/v5/contacts/query",   // spec-index publicUrl
   { query: { cursorPaging: { limit: 10 } } }, accessToken);
 // let it throw — the thrown message is your result; .catch hides the answer
-return wx.clip({ error: null, count: data.contacts?.length, first: data.contacts?.[0] });
-//  ↑ one real row, whole — the shapes you code against live here, not in key names
+return wx.clip({ error: null, count: data.contacts?.length, first: data.contacts[0] });
+// `first` is one complete record — read the real field shapes off it; don't code from remembered key names
+```
+
+### Backend functions — the app, as the owner
+
+The same API call, deployed. **No helpers run here** — `wx.*` is a build tool loaded into exec,
+absent from `base44/functions/…`; write plain `fetch`. Nor `clip`, which caps what an exec returns
+to you: a function returns its data to the app.
+
+```js
+// inside base44/functions/… — plain fetch, no wx
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const res = await fetch("https://www.wixapis.com/contacts/v5/contacts/query", {
+  method: "POST",
+  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ query: { cursorPaging: { limit: 10 } } }),
+});
+if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);   // the API's own error, not a generic one
+return (await res.json()).contacts;
 ```
 
-The same call deploys as `base44/functions/*` (work the app does as the owner) — shipped code
-carries its own four-line fetch; the helpers are a build tool, not a runtime dependency.
+- That `Authorization: Bearer …` is the whole auth for this lane, unless the operation's page says
+  otherwise.
+- One file per business area, not per call — each file is its own deploy, and deploys cost time.
+- Call every function you deploy and fix what breaks. Deploying is not testing.
 
 ### A visitor client — src/lib/wixClient.js
 
@@ -200,3 +281,11 @@ return await wx.post("<a public read from Learn Wix>", { query: {} }, access_tok
 // a lean default response isn't the whole shape — contracts often define a fields param
 // that opts INTO heavier parts (formatted prices, media); read the contract for it
 ```
+
+No OAuth app in the context report to take the `clientId` from? Create one (admin, one-time) —
+the returned `id` IS the `clientId`:
+
+```js
+const { oAuthApp } = await wx.post("https://www.wixapis.com/oauth-app/v1/oauth-apps",
+  { oAuthApp: { name: "My App" } }, accessToken);   // oAuthApp.id is the visitor clientId
+```

package/skills/wix-base44-connector/references/CAPABILITY_MAP.md

@@ -0,0 +1,78 @@
+# Capability map — which Wix product owns what
+
+Every Wix product, its capabilities, and its docs path. Paths are relative to
+`https://dev.wix.com/docs/api-reference/`; read a product's `<path>/introduction.md` for detail.
+Capabilities come from those introduction pages — re-derive from them when a product looks wrong or
+missing.
+
+## Business solutions
+
+| Product | Path | Features |
+|---|---|---|
+| Stores | `business-solutions/stores` | Products · Categories · Product options and variants · Inventory · Brands · Ribbons · Product info sections · Product customizations · Promotions · Store locations · Site currency · Currency conversion |
+| Bookings | `business-solutions/bookings` | Services · Appointments · Classes · Courses · Staff members · Resources · Pricing · Policies · Time slots · Bookings · Waitlists · External calendar · Checkout and orders |
+| eCommerce | `business-solutions/e-commerce` | Cart · Checkout · Abandoned checkout · Orders · Order transactions · Order fulfillment · Discount rules · Recommendations · Shipping rates · Additional fees · Payments · Catalog |
+| Restaurants | `business-solutions/restaurants` | Menus · Sections · Items · Item variants · Item modifiers · Item labels · Online orders · Operations · Fulfillment methods · Availability exceptions · Service fees · Reservations · Time slots · Experiences |
+| Events | `business-solutions/events` | Events · Ticket definitions · Tickets · RSVP · Orders and checkout · Check-in · Event guests · Guest list · Event schedule · Policies |
+| Blog | `business-solutions/blog` | Posts · Draft posts · Categories · Tags · Post stats · Blog roles · Paid post subscriptions |
+| CMS | `business-solutions/cms` | Data items · Data collections · Collection permissions · Aggregations · Indexes · External databases · Backups · Background tasks |
+| Pricing Plans | `business-solutions/pricing-plans` | Plans · Orders · Recurring subscriptions · Single payment plans · Free plans · Free trial periods · Order cancellation · Credits |
+| Portfolio | `business-solutions/portfolio` | Projects · Project items · Collections · Portfolio settings · Gallery layouts · Cover media |
+| Gift Cards | `business-solutions/gift-cards` | Gift cards · Gift card products · Redemption codes · Balance tracking · Denominations · Expiration policies · Transactions |
+| Coupons | `business-solutions/coupons` | Coupons · Percentage discounts · Fixed amount discounts · Free shipping · Buy X Get Y · Coupon scopes · Usage limits · Expiration dates |
+| Donations | `business-solutions/donations` | Donation campaigns · Fundraising goals · One-time and recurring donations · Predefined and custom amounts · Cover fees · Campaign progress |
+| Benefit Programs | `business-solutions/benefit-programs` | Benefit programs · Program templates · Membership tiers · Credits · Benefit redemption · Visitor enrollment · Balances · Eligibility checks |
+| Meetings | `business-solutions/meetings` | Scheduling links · Shareable booking page · Meeting duration and location · Video, phone, in-person · Hosts · Calendar sync · Intake forms · Paid meetings · Rescheduling |
+| Rentals | `business-solutions/rentals` | Rental services · Hourly and daily durations · Customer-selected length · Bookable resources · Resource attributes · Per-hour and per-day pricing · Availability · Consecutive multi-day bookings |
+| Suppliers Hub | `business-solutions/suppliers-hub` | Marketplace products · Suppliers · Dropshipping · Wholesale price tiers · Categories and tags · Product search · Bulk catalog operations · Mockup generation |
+| Forum | `business-solutions/forum` | **Deprecated** — discontinued March 2026; migrate to Community → Groups |
+
+## Site-wide products (CRM and business management)
+
+| Product | Path | Features |
+|---|---|---|
+| Members & Contacts | `crm/members-contacts` | Contacts · Labels · Extended fields · Notes · Attachments · Activity log · Members · Member profiles · Member authentication · Privacy settings · Badges · Followers |
+| Forms | `crm/forms` | Form schemas · Form submissions · Form schema templates · Intake forms · Interactive form sessions · Chat settings |
+| Loyalty Program | `crm/loyalty-program` | Loyalty program · Loyalty points · Earning rules · Tiers · Loyalty accounts · Transactions · Rewards · Loyalty coupons · Checkout discount |
+| Community | `crm/community` | Groups · Group rules · Group membership · Join requests · Comments · Reviews · Review requests · Reports · Moderation rules |
+| Communication | `crm/communication` | Inbox · Conversations · Messages · Email subscriptions · Communication channels |
+| CRM | `crm/crm` | Tasks · Pipelines · Cards |
+| Automations | `business-management/automations` | Automations · Triggers · Actions · Conditions · Delays · Pre-installed automations · Trigger catalog · Action catalog |
+| Marketing | `business-management/marketing` | Email campaigns · Transactional emails · Sender details · Sending domains · Marketing consent · Referral program · Referral rewards · Marketing tags · Social media posts · Google Ads · Ads.txt |
+| Payments | `business-management/payments` | Checkout sessions · Payment methods · Transactions · Refunds · Disputes · Payouts · Balances · Tax documents · Payment service provider integration |
+| Get Paid | `business-management/get-paid` | Invoices · Invoice presets · Billable items · Payment links · Receipts · Receipt presets · Bulk downloads |
+| SEO | `business-management/seo` | Site SEO tags · SEO patterns · Item SEO tags · Resolved tags · Verification tags · Redirects |
+| Multilingual | `business-management/multilingual` | Locales · Locale settings · Translation schemas · Translation content · Published translated content · Machine translation · Word credits |
+| Notifications | `business-management/notifications` | Notifications · Notification templates · Dashboard site feed · Owner app notification center · Mobile push |
+| Locations | `business-management/locations` | Locations · Default location · Business schedule · Special hours · Location types · Location archiving |
+| Branches | `business-management/branches` | Branches · Default branch · Branch tags · Branch types |
+| Online Programs | `business-management/online-programs` | Programs · Sections · Steps · Join applications · Instructors · Enrollment · Payment flows |
+| Calendar | `business-management/calendar` | Schedules · Events · Recurring events · Schedule time frames · Event views · Participation — **infrastructure** under Bookings, not a product a site owner picks |
+| Analytics | `business-management/analytics` | Analytics data · Semantic models · Sessions |
+| Site Search | `business-management/site-search` | Search · Search schemas |
+
+Also under `business-management/`, thinner or platform-facing: `site-properties`, `site-urls`,
+`tags`, `dashboard`, `secrets`, `functions`, `app-installation`, `async-job`, `captcha`,
+`cookie-consent-policy`, `custom-embeds`, `data-extension-schema`, `google-business-profile`,
+`headless`, `ai-site-chat`, `faq-app`.
+
+## Not in the docs
+
+- No roles API and no segments API in `crm/` or `business-management/` — contact **labels** serve
+  segmentation.
+- For a single method, `spec(docsUrl)` is what proves absence.
+
+## Where things actually live
+
+- **SEO spans two products** — the tag model is `business-management/seo`; Ads.txt and keyword
+  suggestions are `business-management/marketing/seo`.
+- **Badges and Followers** live under `crm/members-contacts/members/activity/`, not member
+  management. Profiles are `members/member-management/members-about-v2`, privacy is
+  `member-management/privacy`, custom fields are `member-management/custom-fields`.
+- **Meetings and Rentals ship no APIs of their own** — both are Wix Bookings with restricted field
+  values, so their contracts are the Bookings ones.
+- **Loyalty coupons** (`crm/loyalty-program/rewards/coupons`) are a different resource from
+  eCommerce **Coupons** (`business-solutions/coupons`).
+- **Stores categories** are called *Collections* in Catalog V1 and *Categories* in Catalog V3.
+- **Stores, Coupons and Suppliers Hub have no usable introduction page** — start from the menu page
+  and the sub-section introductions.