@wix/agent-skills 1.15.1 → 1.16.1

package/skills/wix-manage/references/contacts/create-a-contact.md

@@ -0,0 +1,82 @@
+---
+name: "Create a Contact"
+description: Creates a contact with the Contacts API. Covers the minimum identifying fields, the single-object shape of `email` and `phone`, and adding a physical address with the ISO 3166-2 subdivision format required for state, region, and province codes.
+---
+# Create a Contact
+
+## Description
+Creates a contact, optionally with a physical address in the same call.
+
+## API Endpoint
+`POST https://www.wixapis.com/contacts/v5/contacts`
+
+## Steps
+
+### 1. Create the contact
+
+At least one of `name.first`, `name.last`, `email.email`, or `phone.phone` must be present. Copy this body and change the values:
+
+```json
+{
+  "contact": {
+    "name": { "first": "Maria", "last": "Gomez" },
+    "email": { "email": "maria.gomez@example.com" },
+    "phone": { "phone": "+1 212 555 0134" }
+  }
+}
+```
+
+`email` is a single object, exactly as above. Send a list instead — `emails: [{ tag: 'MAIN', email: '…' }]` — and the request still returns `200`, but the field is discarded: the contact is created with no email at all. Nothing in the response reports this, so it surfaces only when something later reads the contact back and the email is missing. The same holds for `phone`. Read `contact.email.email` off the create response to confirm it was stored.
+
+### 2. Add an address (optional)
+
+Include `addresses` in the same create call when the user gave a street address:
+
+```json
+{
+  "contact": {
+    "name": { "first": "Maria", "last": "Gomez" },
+    "email": { "email": "maria.gomez@example.com" },
+    "addresses": [
+      {
+        "tag": "HOME",
+        "address": {
+          "addressLine": "350 Fifth Avenue",
+          "city": "New York",
+          "subdivision": "US-NY",
+          "postalCode": "10118",
+          "country": "US"
+        }
+      }
+    ]
+  }
+}
+```
+
+`addresses[].address` takes either `addressLine` as free text, or a structured `streetAddress` object — not both.
+
+`tag` is one of `OTHER`, `HOME`, `WORK`, `BILLING`, `SHIPPING`, and that list is closed — there is no "untagged" or "none" member. When the user did not say what kind of address it is, leave `tag` out and it defaults to `OTHER`; inventing a value for that case is rejected with `400`.
+
+### 3. Write `subdivision` in ISO 3166-2 form
+
+`subdivision` is the 2-letter country code, a hyphen, then 1-3 characters for the state, region, prefecture or province: `US-NY`, `GB-ENG`, `FR-976`. A bare state code is rejected:
+
+```
+HTTP 400 {"message":"contact is invalid:
+`-- addresses [at index 0] is invalid:
+    `-- address is invalid:
+       `-- subdivision is not a valid subdivision code",
+ "details":{"validationError":{"fieldViolations":[{
+   "field":"contact.addresses[0].address.subdivision",
+   "description":"is not a valid subdivision code","violatedRule":"FORMAT",
+   "data":{"type":"SUBDIVISION"}}]}}}
+```
+
+The Create Contact reference describes this field as a "short code (2 or 3 letters)" and gives `NY` as the example, which the server does not accept. Use the hyphenated form.
+
+`country` is the plain [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code — `US`, no hyphen. Only `subdivision` carries the country prefix.
+
+## Related
+
+- [Create Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/create-contact)
+- [Update Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/update-contact)

package/skills/wix-manage/references/contacts/update-a-contact.md

@@ -0,0 +1,119 @@
+---
+name: "Update a Contact"
+description: Updates an existing contact's email, phone, name, or address with the Contacts API. Covers locating the contact when the user identifies it by name, passing its current revision, and the ISO 3166-2 subdivision format required for state, region and province codes.
+---
+# Update a Contact
+
+## Description
+Changes fields on a contact that already exists — its email, phone, name, or address.
+
+## API Endpoints
+- `POST https://www.wixapis.com/contacts/v5/contacts/search` — locate the contact
+- `PATCH https://www.wixapis.com/contacts/v5/contacts/{contactId}` — change its fields
+- `POST https://www.wixapis.com/contacts/v5/contacts/{contactId}/addresses` — add one address
+
+Contacts has two live versions. Use the v5 endpoints above for updates; the v4 update takes a
+different, more deeply nested body, and mixing the two shapes is rejected with
+`400 {"message":"Expected an object"}`.
+
+## Steps
+
+### 1. Locate the contact with Search Contacts, not Query Contacts
+
+When the user identifies a contact by name — "my contact Jordan Lee" — the lookup is Search
+Contacts. Query Contacts filters on a small closed set of fields that does not include the
+contact's name, so a query filtered by name is rejected:
+
+```
+HTTP 400 {"message":"value Field 'name.first' is not declared as filterable",
+ "details":{"validationError":{"fieldViolations":[{"field":"value",
+   "description":"Field 'name.first' is not declared as filterable"}]}}}
+```
+
+Search Contacts takes a free-text expression, and matches on names. Note the doubled `search` —
+the outer one is the search request, the inner one is the free-text clause:
+
+```json
+{ "search": { "search": { "expression": "Jordan Lee" } } }
+```
+
+Read both `id` and `revision` off the contact it returns. Step 2 needs both. Query Contacts is
+still the right call when you already have an email address, a phone number or an id to filter on.
+
+### 2. Send the update with the contact's current revision
+
+Copy this body and change the values. Only the fields you send are being set; `id` and `revision`
+identify which contact and which version you are updating:
+
+```json
+{
+  "contact": {
+    "id": "<contact id from step 1>",
+    "revision": "<revision from step 1>",
+    "email": { "email": "jordan.lee@newmail.com" }
+  }
+}
+```
+
+Swap `email` for `phone` (`{ "phone": { "phone": "+1-212-555-0100" } }`) or `name` to change those
+instead. `revision` changes on every write, so re-read it if an update conflicts.
+
+### 3. Add an address with Add Contact Address
+
+To attach one more address, post it to the contact's `addresses` sub-resource rather than sending
+the whole contact — the address is appended, so existing addresses survive:
+
+```json
+{
+  "revision": "<revision from step 1>",
+  "address": {
+    "address": {
+      "addressLine": "350 Fifth Avenue",
+      "city": "New York",
+      "subdivision": "US-NY",
+      "postalCode": "10118",
+      "country": "US"
+    }
+  }
+}
+```
+
+Note the doubled `address` here too: the outer object is the contact's address entry, which can
+carry a `tag`, and the inner one is the postal address itself.
+
+`tag` is one of `OTHER`, `HOME`, `WORK`, `BILLING`, `SHIPPING`, and that list is closed — there is
+no "untagged" or "none" member. When the user did not say what kind of address it is, leave `tag`
+out, exactly as above; inventing a value for that case is rejected:
+
+```
+HTTP 400 {"message":"address is invalid:
+`-- tag enum must be in [UNKNOWN_ADDRESS_TAG(0), OTHER(1), HOME(2), WORK(3), BILLING(4), SHIPPING(5)]"}
+```
+
+### 4. Write `subdivision` in ISO 3166-2 form
+
+`subdivision` is the 2-letter country code, a hyphen, then 1-3 characters for the state, region,
+prefecture or province: `US-NY`, `GB-ENG`, `FR-976`. A bare state code is rejected, on updates as
+well as on creates:
+
+```
+HTTP 400 {"message":"address is invalid:
+`-- address is invalid:
+    `-- subdivision is not a valid subdivision code",
+ "details":{"validationError":{"fieldViolations":[{
+   "field":"address.address.subdivision",
+   "description":"is not a valid subdivision code","violatedRule":"FORMAT",
+   "data":{"type":"SUBDIVISION"}}]}}}
+```
+
+The Contacts reference describes this field as a "short code (2 or 3 letters)" and gives `NY` as
+the example, which the server does not accept. Use the hyphenated form.
+
+`country` is the plain [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code
+— `US`, no hyphen. Only `subdivision` carries the country prefix.
+
+## Related
+
+- [Update Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/update-contact)
+- [Search Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/search-contacts)
+- [Add Contact Address](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/add-contact-address)

package/skills/wix-manage/references/dashboard-navigation/dashboard-navigation.md

@@ -0,0 +1,82 @@
+---
+name: "Dashboard Navigation"
+description: "Entry point for building direct links into a site's Wix dashboard (manage.wix.com). Documents the shared URL structure for all dashboard pages (site and account level, app-ID fallback, entity deep links, machine-readable routes.json) and routes to a per-business-solution recipe for every covered solution — bookings, stores/ecommerce, blog, pricing plans, restaurants, CMS, contacts, forms, marketing, get paid, analytics, google ads, app management, site settings, sites, and domains. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Dashboard Navigation
+
+Build direct links into a site's Wix dashboard (manage.wix.com). This is the shared contract; per-business-solution recipes list the actual page routes.
+
+## URL Structure
+
+Every dashboard page lives under:
+
+```
+https://manage.wix.com/dashboard/{metaSiteId}/{route}
+```
+
+- `{metaSiteId}` — the site's meta site ID: the `id` returned by the Query Sites API, and the `siteId` in a CLI project's `wix.config.json`.
+- `{route}` — `{appSlug}/{pagePath}`. Each Wix app owns a URL namespace (its slug) and registers pages under it, e.g. `bookings/services`, `wix-stores/products`.
+
+Useful properties of these URLs:
+
+- **App-ID fallback.** `https://manage.wix.com/dashboard/{metaSiteId}/app/{appDefinitionId}/{pagePath}` always works and redirects to the slug form. With no `pagePath` it lands on the app's main dashboard page, so knowing just the app ID is enough for a working link:
+
+  ```
+  https://manage.wix.com/dashboard/{metaSiteId}/app/13d21c63-b5ec-5912-8397-c3a5ddb27a97
+  → redirects to .../bookings (the Wix Bookings main page)
+  ```
+
+  To get an app's `appDefinitionId`, use [List Installed Apps](../app-installation/list-installed-apps.md) (`GET /apps-installer-service/v1/app-instances` returns each installed app's ID and name), or take it from the per-solution recipe — each leaf states its apps' IDs.
+- **Graceful degradation.** Unknown deeper paths fall back to the longest matching route (`.../bookings/services/unknown` lands on the services list), so links don't 404.
+- **Legacy redirects.** Older route formats (e.g. `store/orders`, `bookings/scheduler/owner/...`) redirect to the current pages; links in existing content keep working.
+- **Entity deep links.** Pages that show a single entity accept the entity ID as an extra path segment (e.g. `bookings/services/form/{serviceId}`). Query params can follow.
+- **Permissions.** The dashboard enforces its own login and per-page permissions; links just navigate.
+- **Site vs account pages.** Most pages are site-scoped (the `/dashboard/{metaSiteId}/...` form above). Some solutions also have **account-level** pages that apply to the whole Wix account and take no metaSiteId: `https://manage.wix.com/account/{route}` — e.g. `account/websites` (My Sites), `account/domains` (My Domains). The per-solution recipes say which is which.
+
+## Per-Business-Solution Recipes
+
+| Business solution | Recipe | Covers |
+|---|---|---|
+| Wix Bookings | [Bookings Dashboard Navigation](../bookings/bookings-dashboard-navigation.md) | Services, calendar, booking list, staff, availability, resources, settings |
+| Wix Stores / eCommerce | [Stores Dashboard Navigation](../stores/stores-dashboard-navigation.md) | Products, categories, inventory, orders, abandoned checkouts, gift cards, shipping, tax |
+| Wix Blog | [Blog Dashboard Navigation](../blog/blog-dashboard-navigation.md) | Posts (published + drafts), categories, tags, writers, comments, analytics, monetization, settings |
+| Wix Pricing Plans | [Pricing Plans Dashboard Navigation](../pricing-plans/pricing-plans-dashboard-navigation.md) | Plans list, create/edit plan, manual orders, settings |
+| Wix Restaurants | [Restaurants Dashboard Navigation](../restaurants/restaurants-dashboard-navigation.md) | Menus, items, online orders board, ordering settings, reservations, floor plans, reservation experiences |
+| Wix CMS | [CMS Dashboard Navigation](../cms/cms-dashboard-navigation.md) | Collections list, collection items view |
+| Wix Contacts (CRM) | [Contacts Dashboard Navigation](../contacts/contacts-dashboard-navigation.md) | Contacts list, contact view, import, segments |
+| Wix Forms | [Forms Dashboard Navigation](../forms/forms-dashboard-navigation.md) | Forms list, submissions, form builder, standalone forms, templates, settings |
+| Get Paid | [Get Paid Dashboard Navigation](../get-paid/get-paid-dashboard-navigation.md) | Payment links, invoices, recurring invoices, accept-payments settings |
+| Wix Marketing | [Marketing Dashboard Navigation](../marketing/marketing-dashboard-navigation.md) | Social posts hub, design templates, email campaigns, campaign analytics |
+| Wix Analytics | [Analytics Dashboard Navigation](../analytics/analytics-dashboard-navigation.md) | Highlights, reports, traffic/behavior/sales/marketing overviews, benchmarks |
+| Google Ads | [Google Ads Dashboard Navigation](../google-ads/google-ads-dashboard-navigation.md) | The Google Ads campaign page |
+| App management | [App Management Dashboard Navigation](../app-installation/app-installation-dashboard-navigation.md) | App Market, installed-apps management |
+| Site settings | [Site Settings Dashboard Navigation](../site-properties/site-properties-dashboard-navigation.md) | Settings hub, website settings, language & region |
+| Sites (account) | [Sites Dashboard Navigation](../sites/sites-dashboard-navigation.md) | My Sites list, per-site dashboard home |
+| Domains | [Domains Dashboard Navigation](../domains/domains-dashboard-navigation.md) | Site domain settings, account-level My Domains |
+
+For a business solution not listed yet, use the app-ID fallback URL with the solution's app definition ID, or link the dashboard home: `https://manage.wix.com/dashboard/{metaSiteId}/home`.
+
+## Machine-Readable Route Data
+
+[routes.json](https://www.wix.com/skills/manage/references/dashboard-navigation/routes.json) holds the full page inventory behind these recipes — every covered app with its `appDefinitionId`, `slug`, and per page: `path` (append to `https://manage.wix.com/dashboard/{metaSiteId}/`), `title`, `inSidebar`, redirecting `legacyAliases`, and — where the page shows a single entity — `deepLink` with the ID placeholder (`bookings/services/form/{serviceId}`). Prefer the per-solution recipes for guidance (curation, entity deep links, read-API pairing); use the JSON to look up or enumerate routes programmatically:
+
+```bash
+curl -s https://www.wix.com/skills/manage/references/dashboard-navigation/routes.json
+```
+
+```bash
+# All user-facing pages of an app
+jq -r '.apps[] | select(.app == "Wix Bookings") | .pages[] | select(.inSidebar) | .path' routes.json
+
+# Find the page for a concept ("invoice") across all apps
+jq -r '.apps[].pages[] | select(.title | test("invoice"; "i")) | .path' routes.json
+
+# Entity deep link: fetch the pattern, substitute the ID, prepend the base
+jq -r '.apps[].pages[] | select(.deepLink) | .deepLink' routes.json | grep productId
+# → wix-stores/products/product/{productId}
+# → https://manage.wix.com/dashboard/{metaSiteId}/wix-stores/products/product/8a12...
+
+# Where does an old link land now?
+jq -r '.apps[].pages[] | select(.legacyAliases | index("store/orders")) | .path' routes.json
+```