@wix/agent-skills 1.5.0 → 1.7.0

package/skills/wix-headless/scripts/seed-utilities.sh

@@ -1,21 +1,30 @@
 #!/usr/bin/env bash
-# Copy the skill's shared utilities into the project's src/utils/ and strip the
-# Astro starter cruft that ships with the blank template.
+# Frontend-track project prep: copy the skill's shared utilities into the
+# project's src/utils/ and strip the Astro starter cruft that ships with the
+# blank template. This is local-project (frontend) work, not backend seeding —
+# the orchestrator only runs it in scaffold mode (integrate mode has no
+# skill-written frontend to prep, so it is never invoked there).
 #
 # Usage (both modes work):
-#   bash <SKILL_ROOT>/scripts/seed-utilities.sh                # installed tgz
-#   bash <(curl -s https://dev.wix.com/skills/wix-headless/scripts/seed-utilities.sh)
+#   bash <SKILL_ROOT>/scripts/seed-utilities.sh --template astro
+#   bash <(curl -s https://dev.wix.com/skills/wix-headless/scripts/seed-utilities.sh) --template astro
 #
-# Run from the project directory (CWD = <project>/). The script auto-detects
+# --template (optional, default astro): astro
+#   Astro is the only frontend the skill scaffolds and preps, so the value is
+#   always "astro". Custom (non-astro) frontends route to the not-available stub
+#   (references/custom/INSTRUCTIONS.md) and never reach this script.
+#
+# Run from the project directory (CWD = <scaffold>/). The script auto-detects
 # whether shared-utilities is available on disk (tgz install) and falls back
 # to fetching from the well-known URL when streamed via process substitution
 # (BASH_SOURCE is /dev/fd/N, so the on-disk lookup naturally falls through).
 #
 # Behavior:
-#   - Copies the three shared utility files into src/utils/ — never overwrites
-#     an existing file (users can drop in their own version to override).
-#   - Removes Astro starter cruft (Welcome.astro + marketing SVGs) that ships
-#     with the blank template but is never imported by the build skill.
+#   - Copies the three shared utility files into src/utils/ for both templates —
+#     never overwrites an existing file (users can drop in their own version).
+#   - On --template=astro, removes Astro starter cruft (Welcome.astro + marketing
+#     SVGs) that ships with the blank template but is never imported by the build
+#     skill.
 #
 # Shared utilities copied:
 #   - wix-image.ts  — media URL resolver (used by stores, blog, cms)
@@ -27,6 +36,33 @@ set -euo pipefail
 SKILL_URL="https://dev.wix.com/skills/wix-headless"
 UTILS=(analytics.ts ricos.ts wix-image.ts)
 
+TEMPLATE="astro"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --template)
+      TEMPLATE="$2"
+      shift 2
+      ;;
+    --template=*)
+      TEMPLATE="${1#--template=}"
+      shift
+      ;;
+    *)
+      echo "seed-utilities.sh: unexpected arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+case "$TEMPLATE" in
+  astro) ;;
+  *)
+    echo "seed-utilities.sh: --template must be 'astro' (the only supported frontend); got $TEMPLATE" >&2
+    echo "(Custom non-astro frontends route to the stub and never reach this script.)" >&2
+    exit 2
+    ;;
+esac
+
 # Mode detection: prefer on-disk skill root if the sibling dir exists, else
 # fetch over HTTP. Covers both tgz install and `bash <(curl ...)` streaming.
 SHARED_UTILS_DIR=""
@@ -50,6 +86,8 @@ for f in "${UTILS[@]}"; do
   fi
 done
 
-# Astro starter cruft cleanup.
-rm -f src/components/Welcome.astro
-rm -f src/assets/astro.svg src/assets/wix.svg src/assets/background.svg
+# Astro starter cruft cleanup — astro template only.
+if [[ "$TEMPLATE" == "astro" ]]; then
+  rm -f src/components/Welcome.astro
+  rm -f src/assets/astro.svg src/assets/wix.svg src/assets/background.svg
+fi

package/skills/wix-manage/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, events, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
 # Management Recipes Index
 
+> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; every actual call ALSO needs `wix-site-id: <SITE_ID>` and `Content-Type: application/json`. **POST/PATCH against `wix-data/*`, `form-schema-service/*`, `stores/v3/*`, `blog/v3/*`, and other site-scoped REST families return 403 without `wix-site-id`** — observed seeder regression cost ~100 s rediscovering this on a 2026-05-24 run. Mint the token via `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 ## What Are Management Recipes?
 
 **Management recipes are for REST API operations** that configure, set up, and manage Wix business entities on your site. These recipes use REST API calls and are designed for:
@@ -155,6 +157,7 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 #### Config & API References
 - [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md)
+- [API: Shipping Delivery](references/ecommerce/api-shipping.md)
 - [Setup: Discount Rules](references/ecommerce/setup-discount-rules.md)
 - [Setup: Coupons](references/ecommerce/setup-coupons.md)
 - [Setup: Shipping Regions](references/ecommerce/setup-shipping-regions.md)
@@ -171,13 +174,6 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
-## Events
-
-### [List Events](references/events/list-events.md)
-**Technical:** Queries events from Wix Events using Events API. Covers field sets (DETAILS, URLS, REGISTRATION), filtering by status/date, and pagination.
-
----
-
 ## Forms
 
 ### [Create Form](references/forms/create-form.md)

package/skills/wix-manage/references/blog/how-to-create-blog-posts.md

@@ -5,6 +5,8 @@ description: Creates and publishes blog posts using Blog Posts API. Covers Ricos
 
 **Article: Create and Publish Blog Posts with Rich Content and Images**
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `blog/v3/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 ---
 
 ## Description
@@ -49,7 +51,13 @@ This article demonstrates how to create and immediately publish blog posts using
 
 ### Part 2: Create Blog Post with Rich Content
 
-1. Create blog post using [Create Draft Post](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/create-draft-post) for single posts, or [Bulk Create Draft Posts](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/bulk-create-draft-posts) for multiple posts.
+You have two endpoints:
+- **Single post:** [Create Draft Post](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/create-draft-post) — `POST https://www.wixapis.com/blog/v3/draft-posts`
+- **Multiple posts (preferred for any N ≥ 2):** [Bulk Create Draft Posts](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/bulk-create-draft-posts) — `POST https://www.wixapis.com/blog/v3/bulk/draft-posts/create`
+
+**Use the bulk endpoint when seeding multiple posts** — one call replaces N single-post calls and avoids the per-call latency of ~25–30 s each.
+
+#### Single-post endpoint
 
    ```bash
    curl -X POST "https://www.wixapis.com/blog/v3/draft-posts" \
@@ -86,6 +94,67 @@ This article demonstrates how to create and immediately publish blog posts using
      }'
    ```
 
+#### Bulk-create endpoint (preferred for multiple posts)
+
+> **⚠️ Body shape — read this carefully. Each item in `draftPosts` is a FLAT post object: `{title, memberId, richContent, media?, ...}`. Do NOT wrap each item in a `draftPost` field.** Unlike the single-post endpoint (which uses `{draftPost: {...}}` because the request is one post), the bulk endpoint puts each post DIRECTLY inside the `draftPosts` array.
+
+✅ **CORRECT body shape (verified against the live API — returns 200 with `results[].itemMetadata.success: true`):**
+
+   ```json
+   {
+     "draftPosts": [
+       { "title": "First Post",  "memberId": "...", "richContent": { /* … */ } },
+       { "title": "Second Post", "memberId": "...", "richContent": { /* … */ } }
+     ],
+     "publish": true
+   }
+   ```
+
+❌ **WRONG body shape (returns `400 Bad Request` with `draftPosts[i].title must not be empty` because the API is looking for `draftPosts[i].title` directly and finds it nested under a `draftPost` field):**
+
+   ```json
+   {
+     "draftPosts": [
+       { "draftPost": { "title": "First Post",  "memberId": "...", "richContent": { /* … */ } } },
+       { "draftPost": { "title": "Second Post", "memberId": "...", "richContent": { /* … */ } } }
+     ],
+     "publish": true
+   }
+   ```
+
+The natural intuition is "the bulk endpoint reuses the single-post `{draftPost: {...}}` envelope, just inside an array" — that's wrong. The bulk endpoint flattens the envelope away because the array IS the envelope. **Use the FLAT shape: `draftPosts[i]` IS the post.**
+
+#### Full bulk-create curl example
+
+   ```bash
+   curl -X POST "https://www.wixapis.com/blog/v3/bulk/draft-posts/create" \
+     -H "Authorization: <AUTH>" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "draftPosts": [
+         {
+           "title": "First Post",
+           "memberId": "author-member-id",
+           "richContent": { /* Ricos JSON — see below */ },
+           "media": { "wixMedia": { "image": { "id": "mediaId" } }, "displayed": true, "custom": true }
+         },
+         {
+           "title": "Second Post",
+           "memberId": "author-member-id",
+           "richContent": { /* Ricos JSON */ }
+         }
+       ],
+       "publish": true
+     }'
+   ```
+
+   The response body is `{results: [{itemMetadata: {id, originalIndex, success}}, ...]}`. Each result's `itemMetadata` carries the created post id and a `success: boolean` flag — the bulk call returns 200 even if some posts fail; check each `results[i].itemMetadata.success` individually.
+
+   **Common URL-shape mistakes (do not use these — both return 404):**
+   - `/blog/v3/draft-posts/bulk` ✗
+   - `/blog/v3/draft-posts/bulk-create` ✗
+   - The correct path is `/blog/v3/bulk/draft-posts/create` (note: `bulk` is a path segment between `v3` and `draft-posts`, not a suffix on `draft-posts`).
+
 2. Structure rich content using Ricos JSON format. Reference [Ricos documentation](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/introduction) for complete node structure. Common node types:
    - `PARAGRAPH` for text content
    - `HEADING` for section headers

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -4,6 +4,8 @@ description: "Add, query, update, and delete items in CMS collections. Use this
 ---
 # CMS Data Items CRUD
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
 
 ## Prerequisites
@@ -365,6 +367,8 @@ curl -X DELETE \
 | `IMAGE` | Image reference (HTTP url or wix:image://v1/{mediaId}/{friendlyName}) | `"wix:image://v1/3f72369f2219e2ee853e9e3df0217ce1.jpg/Colorful%20Business%20Cards.jpg"` |
 | `VIDEO` | Video reference (HTTP url or wix:video://v1/{mediaId}/{friendlyName}) | `"wix:video://v1/11062b_484182533ede4b9a81329daf20238867/Sketching%20Design%20Concepts#posterUri=11062b_484182533ede4b9a81329daf20238867f000.jpg&posterWidth=1920&posterHeight=1080"` |
 | `DOCUMENT` | Document reference  (HTTP url or wix:document://v1/{mediaId}) | `"wix:document://v1/..."` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
 | `EMAIL` | Email | `"example@wix.com"` |

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -4,6 +4,8 @@ description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use ins
 ---
 # CMS References & Relationships
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 This recipe covers linking CMS collections together using reference fields.
 
 ## Prerequisites

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -4,6 +4,8 @@ description: Create and modify CMS collection structures. Covers listing collect
 ---
 # CMS Schema Management
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 This recipe covers managing the structure (schema) of Wix CMS collections using the REST API.
 
 ## Prerequisites
@@ -120,6 +122,8 @@ curl -X GET \
 | `DATE` | Date only | `"2024-01-15"` |
 | `DATETIME` | Date and time | `{ "$date": "2024-01-15T10:00:00.000Z" }` |
 | `IMAGE` | Image reference | `"wix:image://v1/..."` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
 | `ARRAY_STRING` | Array of strings | `["tag1", "tag2"]` |