@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-manage/references/google-business-profile/manage-google-business-profile-locations.md

@@ -0,0 +1,182 @@
+---
+name: "Manage Google Business Profile Locations for a Wix Site"
+description: Import Google Business Profile locations into the authenticated Wix site, list and query them with or without live Google data, update Wix-side and Google-side details through the correct method for each, create a new Google listing, check whether a profile is actually live on Google, and remove a location from Wix or delete its Google listing. Checks the site's Google connection first and reports a missing one as a setup step, warns before destructive or Google-visible writes, and respects Google's shared rate budget.
+---
+
+# Manage Google Business Profile Locations for a Wix Site
+
+Use the public **Google Business Profile Locations API** to manage the
+authenticated Wix site's Business Profile locations — the entries that decide
+how the business appears on Google Search and Maps. The REST requests do not
+contain a site ID — the site comes from the caller's authorization context.
+Use the site the environment already supplies; if no site is selected, list
+the user's sites once and auto-select the only one, or ask the user to choose
+by site name when several are available. Never invent a site ID or ask the
+user to type one.
+
+> **Unconnected-site fast path — read first.** Read the connection once. Treat
+> `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or a single
+> `CONNECTION_NOT_FOUND`/not-found response from that connection check as the
+> same setup state. Query Wix-only GBP locations once to answer what the site
+> already has, report the result, explain the connect → account selection →
+> unimported-location selection → bulk-create flow, and stop — after that one
+> query the **next action is the final response**, with no other tool call. Do
+> not call a Google-backed location method, probe for Business Profile
+> accounts, guess an endpoint, or make further API probes or documentation
+> searches until the connection is `VALID`. A `403` or `PERMISSION_DENIED` is
+> terminal: the **next action is the final response** explaining it. Stop
+> without the Wix-only query, documentation search, or any other tool call.
+
+The API is a live view onto Google, not a copy: most calls make a real Google
+request, with Google's latency and rate limits. A location's ID is Google's
+opaque location ID and is what identifies it everywhere.
+
+## Direct calls for the unconnected-site path
+
+Use these request shapes directly; do not search the API reference before
+calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Query GBP Locations** | `POST https://www.wixapis.com/gbp/v1/locations/query` with body below |
+
+```json
+{ "query": { "paging": { "limit": 100 } } }
+```
+
+Make **Get Connection** first, then branch before making any other call:
+
+- `403` or `PERMISSION_DENIED` — stop. The next action is the final response;
+  explain that the current Wix identity cannot inspect the site's GBP state.
+  Do not query locations, inspect installed apps, search documentation, or try
+  another endpoint.
+- `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or `CONNECTION_NOT_FOUND` — make one
+  **Query GBP Locations** call, report the Wix-stored result, explain the future
+  import steps, and stop. The next action is the final response.
+- `VALID` — proceed with the requested Google-backed flow.
+
+Do not call **List GBP Accounts** or another Google-backed method until the
+connection is `VALID` — account discovery requires the connection, and its
+request shape is not the locations query. Never guess an endpoint that is not
+in the table above or in the loaded reference.
+
+## Check the connection first
+
+Google-backed methods require a Google connection, established through the
+**Google Business Profile Connection API** (see the connect recipe). Before
+Google-backed work, call **Get Connection**:
+
+- `VALID` — proceed.
+- `NEVER_CONNECTED` or `NEEDS_RECONNECT` — report a setup step, not an error,
+  and offer to run the connect flow. Do not retry location calls until the
+  connection is `VALID`.
+
+Wix-only reads and deletes still work without active Google credentials:
+**Get GBP Location**, **Query GBP Locations**, **Update Location**,
+**Delete Location**, and **Bulk Delete Locations**.
+
+## Import locations
+
+Importing registers listings that already exist at Google; it never creates
+one. Each step narrows the next:
+
+1. Call **List GBP Accounts**. One Google login can hold several Business
+   Profile accounts, so present the list and let the owner pick — never assume
+   the first one.
+2. Call **List Unimported Locations** with the chosen `accountId`. It returns
+   only what the site hasn't imported yet, so re-running never offers
+   duplicates.
+3. Let the owner select which locations to import, and confirm before writing.
+4. Call **Bulk Create Locations** with the selected locations, supplying `id`
+   and `accountId` on each.
+5. Inspect every `results[].itemMetadata.error`. The call reports per-item
+   failures instead of aborting, so a `200` does not mean every location
+   imported. Report failures explicitly.
+
+Repeat steps 2–5 per account if the owner wants locations from more than one.
+
+## List and query locations
+
+Choose by whether live Google data is needed:
+
+- **Just the site's locations:** call **Query GBP Locations**. Wix-stored rows
+  only — fast, no Google round-trip, no Google rate limit. Use it for counts,
+  ID lookups, and anything driven by `id`, `googleLocationId`, or `accountId`.
+- **Locations with live business details:** call **Query Google Locations**
+  (or **Get Google Location** for one). Each row is hydrated with a live
+  Google fetch. Check each row for `googleError` — one location failing at
+  Google does not fail the request or break paging, so render it as a
+  per-location problem, not an empty result.
+
+## Update the correct side
+
+Wix stores almost nothing; the method name tells you which side a write
+reaches. Check before calling anything destructive:
+
+| Method | Wix row | Google listing |
+|---|---|---|
+| **Create Location**, **Bulk Create Locations** | created | untouched (imports an existing listing) |
+| **Create Google Location** | created | **created** |
+| **Update Location** | updated | untouched (writes Wix-stored fields only) |
+| **Update Google Location** | untouched | **updated** |
+| **Delete Location**, **Bulk Delete Locations** | deleted | untouched |
+| **Delete Google Location** | deleted | **deleted** |
+
+- **Update Location** is not the way to edit a Business Profile — it writes
+  only Wix-stored fields. To change Google-owned data (title, address, hours,
+  categories), call **Update Google Location**, and confirm with the owner
+  first: the change is publicly visible on Google.
+- To create a brand-new Google listing, call **Create Google Location** after
+  explicit confirmation. Use the API's reference-data methods (address schema,
+  category and region suggestions) rather than inventing values.
+- Google allows roughly 10 profile edits per minute per Business Profile, and
+  the budget is shared across every write method. Pace the profile as a whole
+  and treat a `429` as worth retrying after a delay, not as a rejection.
+
+## Remove a location
+
+Decide first whether the owner is removing it from Wix or deleting the real
+Google listing — these are different operations and one is irreversible.
+Confirm which they mean before calling anything:
+
+- **Un-import from Wix, leave Google alone:** call **Delete Location**, or
+  **Bulk Delete Locations** for several. Inspect every
+  `results[].itemMetadata` entry — the bulk call can partially succeed.
+- **Delete the Google listing as well:** call **Delete Google Location** once
+  per location; there is no bulk Google delete. Require explicit confirmation
+  naming the location — the listing disappears from Google Search and Maps.
+- If **Delete Google Location** returns `LOCATION_DB_PERSIST_FAILED`, Google
+  deleted the listing but Wix didn't record it. The error payload carries the
+  location ID; call **Delete Location** with it to reconcile.
+
+## Check whether a profile is actually live
+
+A location existing in Wix does not mean it appears on Google — verification
+can be pending, the profile suspended, or ownership contested. Call
+**Get Voice of Merchant** for the location and act on what Google reports:
+wait, verify, comply, or resolve the conflict.
+
+## Recovery rules
+
+- **`FAILED_PRECONDITION` with `CONNECTION_NOT_FOUND`:** the site has no
+  usable Google connection. Report the setup step and offer the connect flow;
+  do not retry the same call.
+- **`GOOGLE_API_CALL_FAILED`:** read the carried Google code and description.
+  Some failures are permanent (profile suspended, field not editable) —
+  retrying will not help; explain instead.
+- **Per-row `googleError` on hydrating reads:** report it per location and
+  continue with the rest of the page.
+- **Rate limited (`429`):** wait, then retry; interleaved writes share one
+  budget per profile.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with other locations, request shapes, or sites, and do not
+  search for an alternate API or method. Deleting locations requires the
+  site's `GBP_ADMIN` role.
+
+The same API also covers reviews and replies, photos and bulk media uploads,
+attributes, verification, performance insights, and location admins — load the
+specific public method reference needed before constructing a request so field
+names, filters, permissions, and errors come from the live contract. Once a
+connection state or typed error selects a branch above, do not search or browse
+for an alternate API, method, or request shape.

package/skills/wix-manage/references/marketing/create-and-publish-social-post.md

@@ -359,6 +359,8 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
 - Otherwise, build it from the STEP 3 table row for your channel + `type`: the text field (`caption` for Instagram/Facebook/LinkedIn/X, `description` for YouTube/Pinterest/GBP/TikTok), the media (`mediaWrapper`, or `imageUrl`/`videoUrl` for a single item), and any channel-specific IDs from the STEP 4b account object, plus `title` where the channel uses one.
 - Instagram and story types require media.
 
+**Attribution (always set this).** Set `item.consumerInfo` to `{ "name": "wix-skills-social" }` on **every** create-draft call, for every channel. `consumerInfo.name` identifies what created the post — the Social Media Marketing dashboard sets `social-marketing`, and this recipe sets `wix-skills-social`. Set it on the draft: `name` is applied on creation only, and Update Item ignores it.
+
 **Idempotency (retry safety).** Set a stable, caller-defined `item.referenceId` on the draft. The Publisher enforces its uniqueness — a second item created/published with the same `referenceId` is rejected with `REFERENCE_ID_ALREADY_EXIST` instead of posting a duplicate. So if a create or publish call times out, retry with the **same** `referenceId` rather than risk double-posting.
 
 **Example — Instagram image post:**
@@ -368,6 +370,7 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
   "item": {
     "channel": { "name": "INSTAGRAM", "accountId": "17841405822304914" },
     "type": "POST",
+    "consumerInfo": { "name": "wix-skills-social" },
     "instagramPost": {
       "imageUrl": "https://static.wixstatic.com/media/cf2434_4b3a2d8eb7f54bc89c0d4524430a2af3~mv2.jpg",
       "caption": "Summer collection just dropped! Shop the look now. #summerstyle #newarrivals"

package/skills/wix-manage/references/seo/manage-seo-tags.md

@@ -0,0 +1,315 @@
+---
+name: "Manage a Wix Site's SEO Tags"
+description: Read and update the SEO tags of a Wix site at the right level — site-wide tags, page-type patterns, or one item's tags. Discover item IDs and pattern variables instead of inventing them, read before every full-replace write, and report resolved tags with the source each one came from.
+---
+
+# Manage a Wix Site's SEO Tags
+
+Use the public **SEO APIs** to read and write the titles, descriptions, social
+share tags, canonical links, structured data, and indexing directives of the
+authenticated Wix site. The API selects the site from the caller's
+authorization context; never ask for or send a site ID.
+
+Writing tags requires the **Manage SEO Settings** permission. Reading tags or
+listing pattern variables does not prove that the caller can write.
+
+## The one rule that must never be skipped
+
+**Every write replaces the target's tags in full, so a Get always immediately
+precedes a Set.** There is no partial update: sending only the tag the user
+asked about deletes every other tag that item, pattern, or site had. So before
+any Set, call the matching Get for that exact target, merge the requested change
+into the tags it returns, and send the complete set back.
+
+Never write from the user's request alone, and never skip the Get because the
+change looks small, because a list call already returned something, or because
+the target looks empty. The Set response returns the updated tags and
+`resolvedTags`, so report the outcome from that response instead of issuing
+another read.
+
+## Choose the level
+
+Wix combines tags from several sources, where a more specific source wins.
+Match the user's request to the level that owns the change:
+
+| User intent | Level | API |
+|---|---|---|
+| "Change my site's default social image", site verification tags, site-wide indexing | Site | **Site SEO Tags** |
+| "All my product/blog/event pages should be titled like X" — a convention for every item of a page type | Pattern | **SEO Patterns** |
+| "Change the title of this page/product/post" — one specific item | Item | **Item SEO Tags** |
+
+Work at the level that matches the change. Writing the same title onto many
+items is the same outcome as one pattern and much harder to undo. If the user's
+words fit more than one level, ask one short question before writing. An
+explicit request to change a specific tag at a clear level is already
+confirmation to make that write.
+
+All three APIs live under the **SEO** category of the Wix REST API reference.
+The request shapes are in the section below — construct requests from them. The
+reference article URLs follow this pattern (for edge cases not covered here):
+
+`https://dev.wix.com/docs/api-reference/business-management/seo/{api}/` + method slug
+
+| Level | API slug | Methods (slug) |
+|---|---|---|
+| Site | `site-seo-tags-v1` | Get Site SEO Tags (`get-site-seo-tags`), Set Site SEO Tags (`set-site-seo-tags`) |
+| Pattern | `seo-pattern-v1` | Get SEO Pattern (`get-seo-pattern`), List SEO Patterns (`list-seo-patterns`), List SEO Pattern Variables (`list-seo-pattern-variables`), Create SEO Pattern (`create-seo-pattern`), Set SEO Pattern (`set-seo-pattern`), Reset SEO Pattern To Default (`reset-seo-pattern-to-default`) |
+| Item | `item-seo-tags-v1` | Get Item SEO Tags (`get-item-seo-tags`), List Item SEO Tags (`list-item-seo-tags`), Set Item SEO Tags (`set-item-seo-tags`), Bulk Set Item SEO Tags (`bulk-set-item-seo-tags`), Reset Item SEO Tags To Default (`reset-item-seo-tags-to-default`) |
+
+## REST request and response shapes
+
+Use these shapes directly — do not go looking for them in the docs first.
+
+Build requests from the shapes below. Do not search the API schemas or read
+the reference article to construct them.
+
+### Set Item SEO Tags — `PATCH /item-seo-tags/{itemType}/{itemId}`
+
+```json
+{
+  "itemSeoTags": {
+    "tags": [
+      { "type": "title", "children": "Page title here" },
+      { "type": "meta", "props": { "name": "description", "content": "Description here" } }
+    ]
+  },
+  "fieldMask": "tags"
+}
+```
+
+### Get Item SEO Tags — `GET /item-seo-tags/{itemType}/{itemId}`
+
+No request body. Returns `itemSeoTags` with `tags`, `resolvedTags`,
+`hasOverride`, `publishStatus`, and `hostPageId`.
+
+### List Item SEO Tags — `GET /item-seo-tags/{itemType}?paging.limit=100`
+
+No request body. Returns `itemSeoTagsList[]` and `pagingMetadata` with cursors.
+
+### Set Site SEO Tags — `PATCH /site-seo-tags`
+
+```json
+{
+  "siteSeoTags": {
+    "tags": [
+      { "type": "meta", "props": { "name": "google-site-verification", "content": "token" } }
+    ]
+  },
+  "fieldMask": "tags"
+}
+```
+
+### Set SEO Pattern — `PATCH /seo-patterns/{pageType}`
+
+```json
+{
+  "seoPattern": {
+    "pattern": {
+      "tags": [
+        { "type": "title", "children": "{{item.name}} | {{site.name}}" }
+      ]
+    }
+  },
+  "fieldMask": "pattern"
+}
+```
+
+### Common rules across all shapes
+
+A tag is `{type, props, children}`: `title` and `script` carry their text in
+`children`; `meta` and `link` carry theirs in `props` (`name`/`content` for a
+meta tag, `rel`/`href` for a link).
+
+`fieldMask` over REST is a comma-separated **string** (`"fieldMask": "tags"`);
+the SDK takes an **array** (`fieldMask: ["tags"]`). Sending an array to REST
+returns `INVALID_FIELD_MASK`. `publish` is a boolean.
+
+`resolvedTags` in any Get or Set response is an array of
+`{tag, source, inheritedTag}`. `source` is one of `TAG_SOURCE_SITE`,
+`TAG_SOURCE_DEFAULT_PATTERN`, `TAG_SOURCE_USER_PATTERN`, `TAG_SOURCE_HOST_PAGE`,
+`TAG_SOURCE_ITEM`, or `TAG_SOURCE_UNSPECIFIED`. `inheritedTag` appears only when
+this source replaced a value a lower source had set.
+
+All paths are relative to `https://www.wixapis.com/promote/seo/v1`.
+
+## Discover, never invent
+
+- An item is addressed by an **item type and item ID together**, not by URL.
+  Common item types: `STATIC_PAGE`, `STORES_PRODUCT`, `STORES_CATEGORY`,
+  `BLOG_POST`, `BLOG_CATEGORY`, `BOOKINGS_SERVICE`, `EVENTS_PAGE`,
+  `PORTFOLIO_PROJECTS`, `PORTFOLIO_COLLECTIONS`, `RESTAURANTS_MENU_PAGE`.
+- To find an item's ID when the user refers to it by name (e.g. a product
+  name), use Search Products v3: `POST /stores/v3/products/search`
+  to get the product ID, then use that ID as the `itemId` with item type
+  `STORES_PRODUCT`. Do not call List Item SEO Tags and scan through all items
+  to match by name — use the vertical API.
+- Never fabricate an item ID. If you cannot find the item through its vertical
+  API or List Item SEO Tags, ask the user.
+- Item types exist on a site only when the business solution providing them is
+  installed. The authoritative list of supported item types is in the
+  `UNSUPPORTED_ITEM_TYPE` error message; do not hardcode one beyond the common
+  values listed above.
+- Before writing a pattern, call **List SEO Pattern Variables** for the page
+  type and build the pattern only from returned variables. Never invent a
+  variable name.
+- Dynamic Wix Data pages are addressed by `pageId`; addressing a pattern by
+  collection name is not supported.
+
+## The write sequence
+
+Exactly three calls, in this order, with no extra probing:
+
+1. **Get** the current tags or pattern for the target. Required — see the rule
+   above.
+2. **Set** the complete merged set, naming only the changed fields in the field
+   mask.
+3. Report from the **Set response**, which returns the updated tags and
+   `resolvedTags`. Do not issue a verification read: the write response is the
+   confirmation. Read again only to check a static page's published revision
+   after `publish: true`, or when the user asks about a target you have not read
+   in this session.
+
+To remove an item's own tags so it inherits again, call **Reset Item SEO Tags To
+Default** (or **Reset SEO Pattern To Default**) — never set an empty list to
+mean "reset".
+
+## Worked example: set a product's SEO title and description
+
+The user asks: *"Set the SEO title of my product 'Handmade Mug' to 'Handmade
+Ceramic Mug | Studio Shop' and its description to 'A stoneware mug.'"*
+
+**Step 1 — find the product ID.** Search Products v3 by name:
+
+```
+POST https://www.wixapis.com/stores/v3/products/search
+{ "search": { "search": { "expression": "Handmade Mug" } } }
+```
+
+```json
+{ "products": [{ "id": "a1b2c3d4-...", "name": "Handmade Mug", ... }] }
+```
+
+Take `products[0].id`. The item type is `STORES_PRODUCT`. Do not use Query
+Products with a `name` filter — `name` is not filterable and returns 400.
+
+**Step 2 — read the current tags.**
+
+```
+GET https://www.wixapis.com/promote/seo/v1/item-seo-tags/STORES_PRODUCT/{productId}
+```
+
+```json
+{
+  "itemSeoTags": {
+    "tags": [],
+    "hasOverride": false,
+    "resolvedTags": [
+      { "tag": { "type": "title", "children": "Handmade Mug | My Site" },
+        "source": "TAG_SOURCE_DEFAULT_PATTERN" }
+    ]
+  }
+}
+```
+
+`tags` is empty because the item has no overrides yet. `resolvedTags` shows
+what the page currently renders with and where each tag comes from.
+
+**Step 3 — merge and write.** Take the full `tags` array from step 2, replace
+or add the title and description, and send the complete set back:
+
+```json
+PATCH /item-seo-tags/STORES_PRODUCT/{productId}
+{
+  "itemSeoTags": {
+    "tags": [
+      { "type": "title", "children": "Handmade Ceramic Mug | Studio Shop" },
+      { "type": "meta", "props": { "name": "description", "content": "A stoneware mug." } }
+    ]
+  },
+  "fieldMask": "tags"
+}
+```
+
+**Step 4 — report from the response.** The Set response returns the updated
+`tags` and `resolvedTags`. Report each resolved tag with its source. Do not
+issue another Get — the write response is the confirmation.
+
+## Common agent mistakes — do not make these
+
+- **Searching the API schemas or reading the reference article before the first
+  call.** The request shapes are in this recipe. If you get a 400, compare your
+  request against the shapes in this recipe — do not go to the docs.
+- **Searching for the SEO endpoints through API spec tools.** The shapes are
+  above; searching wastes a turn.
+- **Sending `fieldMask` as an array over REST.** Over REST it is a
+  comma-separated string: `"fieldMask": "tags"`. The SDK's `["tags"]` array
+  returns `INVALID_FIELD_MASK`.
+- **Guessing the item type.** Use the values in the Discover section. A store
+  product is `STORES_PRODUCT`, not `StoresProduct`, `product`, or `Product`.
+
+- **Issuing a verification Get after a successful Set.** The Set response
+  already carries `resolvedTags`. A second read is redundant.
+- **Using Products v1 or filtering by `name` on Query Products.** Both return
+  400. Use Search Products v3: `POST /stores/v3/products/search` with
+  `{"search":{"search":{"expression":"..."}}}`.
+- **Calling List Item SEO Tags expecting product names.** List returns IDs
+  and tags, not names. Use Search Products to find the ID by name first.
+- **Retrying a 400 with a different request shape without checking why.** A 400
+  means the shape was wrong. Compare against the shapes in this recipe, fix the
+  mismatch, send once. Three retries with guessed shapes is three wasted calls.
+
+Tags can currently be written only for the site's primary language: leave
+`language` unset on every write. There is no revision checking — the last write
+wins and dashboard edits write to the same data, so read immediately before
+writing.
+
+**Static pages** keep a draft and a published revision: a write updates the
+draft unless `publish` is `true`, and `publish: true` updates only the
+published revision. Say clearly which revision the change reached. Item types
+that are always live, such as store products, need no publish step.
+
+## Bulk writes
+
+To set tags on many items, call **Bulk Set Item SEO Tags** once, not Set in a
+loop. Expected per-item failures (invalid tags, item not found) fail only that
+entry and are reported on that entry's `itemMetadata.error`; map results back
+to the request with `originalIndex` and retry only the failed entries. Report
+partial failures truthfully — never present a partially failed bulk write as a
+success.
+
+## Present results
+
+- When reporting what a page will render with, use the `resolvedTags` already
+  returned by the last Get or Set — not a fresh call — and name the source of
+  each tag (site, default pattern, user pattern, host page, or the item
+  itself). Naming the source of each reported tag is required, not optional.
+  `hasOverride: false` does not mean built-in defaults — the item may inherit
+  from a customized pattern or the site.
+- `resolvedTags` excludes tags added by site code or apps at render time, so
+  present it as what Wix manages, not a literal copy of the rendered page head.
+
+
+## Recovery rules
+
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`. Do
+  not retry with another item, level, request shape, or site. Explain that the
+  current Wix identity lacks **Manage SEO Settings** and must be reconnected or
+  authorized. Never imply that a successful read means the write ran.
+- **`UNSUPPORTED_ITEM_TYPE`:** the error message lists the item types the API
+  supports; use it to redirect the request rather than retrying blindly.
+- **`ITEM_NOT_FOUND`:** re-discover the item ID; do not guess a new one.
+- **Invalid tags:** tags are validated before anything is saved, so nothing
+  changed; fix the tag and resend the same complete set.
+- **`400` on a request you built from this recipe:** compare the request you
+  sent against the shapes in this recipe's "REST request and response shapes"
+  section. Fix the mismatch — a wrong nesting level, a missing wrapper key, or
+  `fieldMask` sent as an array instead of a string — and send again. Never
+  resend the same shape, and never walk through variations hoping one is
+  accepted.
+- **Setting tags for `EVENTS_PAGE` items:** not supported yet, although reading
+  them is; say so instead of retrying.
+
+This recipe is self-contained for the common flows: request shapes, field
+masks, tag structure, `resolvedTags` format, discovery, and error handling are
+all above. Do not read the method's reference article and do not search the
+API schemas — build every request from this recipe alone.