@wix/agent-skills 1.20.1 → 1.21.0

package/skills/wix-headless-fast/references/storefront/seed/seed-store.mjs

@@ -384,19 +384,47 @@ export async function addProductsToCategories(ctx, mapping) {
 // current revision is read right before the update, so attach any number of times, any pass.
 // Wix re-hosts each url server-side; the media can take a little while to appear on read-back
 // (propagation) — normal, not a failure.
+// The bulk update returns 200 on PARTIAL failure, like the bulk create: each item's outcome is
+// in results[].itemMetadata (success, error, originalIndex). Seen live (runs 85 and 86,
+// 2026-09-26): one product of three came back with no media while the call succeeded — most
+// likely its revision moved between the read and the update (variant stocking runs just
+// before). So: pair results to inputs, retry the misses once with fresh revisions, and report
+// what actually persisted. Returns { attached: [id], failures: [{ id, error }] }.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md
 export async function attachProductImages(ctx, items) {
-  if (!items?.length) return;
-  const ids = items.map((it) => it.id);
-  const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
-  const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
-  return req(ctx, "/stores/v3/bulk/products/update", {
-    body: {
-      products: items.map((it) => ({
-        product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
-      })),
-    },
-  });
+  if (!items?.length) return { attached: [], failures: [] };
+  const send = async (batch) => {
+    const ids = batch.map((it) => it.id);
+    const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
+    const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
+    const r = await req(ctx, "/stores/v3/bulk/products/update", {
+      body: {
+        products: batch.map((it) => ({
+          product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
+        })),
+      },
+    });
+    const ok = new Set();
+    const failed = [];
+    for (const x of r.results ?? []) {
+      const src = batch[x.itemMetadata?.originalIndex];
+      if (!src) continue;
+      if (x.itemMetadata?.success) ok.add(src.id);
+      else failed.push({ id: src.id, error: x.itemMetadata?.error?.description ?? x.itemMetadata?.error?.code ?? "unknown" });
+    }
+    // an input with no result at all did not persist either
+    for (const it of batch) if (!ok.has(it.id) && !failed.some((f) => f.id === it.id)) failed.push({ id: it.id, error: "no result for item" });
+    return { ok, failed };
+  };
+  const first = await send(items);
+  const attached = new Set(first.ok);
+  let failures = first.failed;
+  if (failures.length) {
+    const retry = await send(items.filter((it) => failures.some((f) => f.id === it.id)));
+    for (const id of retry.ok) attached.add(id);
+    failures = retry.failed;
+  }
+  return { attached: [...attached], failures };
 }
 
 // Reject plans the API would reject halfway through, while nothing has been created yet —
@@ -491,18 +519,26 @@ export async function setupStore(ctx, { products = [], categories = {}, currency
   const imageItems = withNames
     .map((p, i) => (files[i] && p.id ? { id: p.id, url: files[i].url, altText: products[i]?.altText ?? p.slug } : null))
     .filter(Boolean);
+  // imagesAttached counts the attaches the API CONFIRMED (per-item results), not the ones sent;
+  // imageFailures names the products left text-only and why. Neither blocks the seed: a re-run of
+  // the same plan reuses the products and attaches again.
   let imagesAttached = 0;
+  const imageFailures = [];
+  const nameOf = (id) => withNames.find((p) => p.id === id)?.name;
   try {
-    if (imageItems.length) await attachProductImages(ctx, imageItems);
-    imagesAttached = imageItems.length;
-  } catch {
-    /* never block on image failure — the products stay text-only */
+    if (imageItems.length) {
+      const r = await attachProductImages(ctx, imageItems);
+      imagesAttached = r.attached.length;
+      for (const f of r.failures) imageFailures.push({ name: nameOf(f.id), error: f.error });
+    }
+  } catch (e) {
+    for (const it of imageItems) imageFailures.push({ name: nameOf(it.id), error: e?.message ?? String(e) });
   }
 
   // failures is part of the result, not an exception: a partial seed still leaves a usable
   // store, and the agent needs the names to report rather than silently shipping a short
   // catalog. Re-run the seed to retry them — existing names are skipped, not duplicated.
-  return { products: withNames, categories: cats, imagesAttached, failures };
+  return { products: withNames, categories: cats, imagesAttached, imageFailures, failures };
 }
 
 // ---- CLI entry ----------------------------------------------------------------------------------

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md

@@ -47,10 +47,7 @@ Before creating a coupon, check for code conflicts and existing promotions on th
         "code": "SUMMER20",
         "percentOffRate": 20,
         "scope": {
-          "namespace": "stores",
-          "group": {
-            "name": "product"
-          }
+          "namespace": "stores"
         },
         "startTime": 1717200000000,
         "expirationTime": 1719792000000,
@@ -91,10 +88,7 @@ Check for: duplicate codes, overlapping scopes with active coupons, and cross-me
     "code": "SPRING15",
     "percentOffRate": 15,
     "scope": {
-      "namespace": "stores",
-      "group": {
-        "name": "product"
-      }
+      "namespace": "stores"
     },
     "startTime": 1714521600000,
     "usageLimit": 200,
@@ -167,10 +161,7 @@ Check for: duplicate codes, overlapping scopes with active coupons, and cross-me
     "code": "SAVE10",
     "moneyOffAmount": 10,
     "scope": {
-      "namespace": "stores",
-      "group": {
-        "name": "product"
-      }
+      "namespace": "stores"
     },
     "startTime": 1714521600000,
     "active": true
@@ -230,11 +221,11 @@ Instead of targeting a scope, you can require a minimum cart subtotal. This is a
 
 ## Scope values for Wix Stores
 
-| Scope target | `namespace` | `group.name` | `group.entityId` |
-|---|---|---|---|
-| All store products | `"stores"` | `"product"` | Omit (applies to all) |
-| Specific product | `"stores"` | `"product"` | Product UUID |
-| Specific collection | `"stores"` | `"collection"` | Collection UUID |
+| Scope target | `namespace` | `group` |
+|---|---|---|
+| All store products | `"stores"` | Omit the `group` field entirely — a present-but-empty `group: {}` is rejected the same as a populated one missing `entityId` |
+| Specific product | `"stores"` | `{ "name": "product", "entityId": "<product UUID>" }` |
+| Specific collection | `"stores"` | `{ "name": "collection", "entityId": "<collection UUID>" }` |
 
 ---
 
@@ -246,7 +237,7 @@ When the recommendation output has `mechanism: "COUPON"`, use this mapping to co
 
 | Recommendation `scope` | Coupon `scope` |
 |---|---|
-| `SITE` | `{ "namespace": "stores", "group": { "name": "product" } }` (all products, no entityId) |
+| `SITE` | `{ "namespace": "stores" }` (all products — omit `group` entirely) |
 | `CATEGORY` | `{ "namespace": "stores", "group": { "name": "collection", "entityId": "<first categoryId>" } }` |
 | `ITEMS` | `{ "namespace": "stores", "group": { "name": "product", "entityId": "<first productId>" } }` |
 
@@ -340,7 +331,7 @@ When the recommendation output has `mechanism: "COUPON"`, use this mapping to co
 
 | Error | Cause | Fix |
 |---|---|---|
-| `"When scope or minimumSubtotal is not used - only FreeShipping coupon is allowed"` | Coupon sent without `scope` or `minimumSubtotal` | Add `scope: { "namespace": "stores", "group": { "name": "product" } }` for site-wide, or set `minimumSubtotal` |
+| `"When scope or minimumSubtotal is not used - only FreeShipping coupon is allowed"` | Coupon sent without `scope` or `minimumSubtotal` | Add `scope: { "namespace": "stores" }` for site-wide (omit `group` — do not send `group: {}`, which is rejected identically), or set `minimumSubtotal` |
 | Duplicate code | Another coupon uses the same code | Generate a different code |
 | Invalid startTime | Value too low (must be epoch ms, not seconds) | Multiply by 1000 if in seconds |
 | Both scope and minimumSubtotal set | These are oneOf — cannot use both | Choose scope OR minimumSubtotal |

package/skills/wix-manage/references/events/create-wix-event.md

@@ -200,7 +200,11 @@ The response is the definition under `ticketDefinition`:
 Keep `revision` — `PATCH /events/v3/ticket-definitions/{id}` requires the current value, and it
 increments on every update.
 
-- **`feeType` is required** — `FEE_ADDED_AT_CHECKOUT` or `FEE_INCLUDED`.
+- **`feeType` is required.** A free ticket (`fixedPrice` of `"0"`) takes `NO_FEE`. A paid ticket
+  takes `FEE_ADDED_AT_CHECKOUT` (the guest pays the service fee) unless the user asked to absorb it,
+  then `FEE_INCLUDED`. `NO_FEE` on a paid ticket is accepted only on sites that do not collect ticket
+  fees. If a paid ticket fails with `400 INVALID_FEE_TYPE`, the site is one that does not collect
+  ticket fees: retry that ticket once with `NO_FEE`.
 - **`value` is a string.** `"value": 10` fails `400 Unexpected value for field value`.
 - **No writable `free` flag** — `pricingMethod.free` is read-only; a free ticket is a `fixedPrice`
   of `"0"`.

package/skills/wix-headless-fast/install/fast-path.mjs

@@ -1,181 +0,0 @@
-// Fast path for a managed CREATE run — one deterministic call from "plan exists" to
-// "brand layer can start". Composes the pieces that also remain individually runnable
-// (deploy.mjs, the vertical's seed module); use those directly to recover a failed step,
-// or for connect/iterate runs (which must NOT scaffold and don't use this script).
-//
-//   node <SKILL_ROOT>/install/fast-path.mjs --business-name "<Brand>" --plan plan.json \
-//        --vertical <storefront|bookings|…> [--stack astro] [--subfolder [--folder-name <npm-safe-name>]]
-//
-// The project is created in the CURRENT DIRECTORY — the folder the entry had the agent work from,
-// which already holds the installed skills (`.agents/skills/`), so the project is self-contained
-// and a later session opened in it finds them. `--subfolder` (opt-in) leaves it in a new folder
-// named after the business instead, for a current folder that must stay as it is.
-//
-// It emits ONE JSON event per line and exits in ~35s with BOTH long steps — the dependency
-// install AND the seed — running detached in the background (logs + completion markers
-// reported in the final event), so the caller can build the brand layer while they finish.
-// Steps: scaffold (Wix CLI; requires a logged-in session) → deploy shipped code + deps +
-// lockfile → start `npm ci || npm install` detached → start the seed detached.
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-
-const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
-const fail = (step, detail) => {
-  emit("error", { step, detail: String(detail).slice(0, 600) });
-  process.exit(1);
-};
-
-// ---- args ---------------------------------------------------------------------------------------
-const argv = process.argv.slice(2);
-const flag = (name) => {
-  const i = argv.indexOf(`--${name}`);
-  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
-};
-const businessName = flag("business-name");
-const planPath = flag("plan");
-const vertical = flag("vertical");
-const stack = flag("stack") ?? "astro";
-// Opt-in: keep the project in a subfolder instead of the current directory.
-const subfolder = argv.includes("--subfolder");
-// --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong
-// seed against the plan — fail loudly with the discovered choices instead.
-const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
-  .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
-  .map((d) => d.name);
-if (!businessName || !planPath || !vertical) {
-  fail("args", `usage: fast-path.mjs --business-name "<Brand>" --plan plan.json --vertical <${knownVerticals.join("|")}> [--stack astro]`);
-}
-if (!knownVerticals.includes(vertical)) {
-  fail("args", `unknown vertical "${vertical}" — shipped verticals: ${knownVerticals.join(", ")}`);
-}
-if (!existsSync(planPath)) fail("args", `plan file not found: ${planPath}`);
-const plan = JSON.parse(readFileSync(planPath, "utf8"));
-
-const folderName =
-  flag("folder-name") ??
-  businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
-// `let`: the Wix CLI can only scaffold into a subfolder; by default we then move the scaffold up
-// into the current directory and repoint projectDir there, so the detached install/seed and every
-// reported path use the final location.
-let projectDir = resolve(process.cwd(), folderName);
-
-// ---- 1 · scaffold -------------------------------------------------------------------------------
-if (existsSync(join(process.cwd(), "wix.config.json"))) {
-  fail("scaffold", "the current directory is already a Wix project — this script is for CREATE runs only; use deploy.mjs + the seed module directly");
-}
-if (existsSync(join(projectDir, "wix.config.json"))) {
-  emit("scaffold_skipped", { reason: "project already exists", folder: folderName });
-} else {
-  emit("scaffolding", { folder: folderName });
-  const scaffold = spawnSync(
-    "npm",
-    // --skip-git: this wrapper composes its own steps and leaves version control to
-    // the caller / the enclosing repo; the scaffold's own `git init` + "Initial
-    // commit" is noise here, and becomes a nested-repo (submodule gitlink) hazard
-    // if the project is later placed inside an existing repo. --skip-install for the
-    // same reason: deps install in a detached step below.
-    ["create", "@wix/new@latest", "--", "headless",
-     "--folder-name", folderName, "--business-name", businessName,
-     "--site-template", "--skip-install", "--skip-git", "--no-publish"],
-    { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
-  );
-  if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
-    fail("scaffold", (scaffold.stderr || scaffold.stdout || "scaffold produced no wix.config.json — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-600));
-  }
-}
-const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
-const siteId = wixConfig.siteId ?? wixConfig.projectId;
-emit("scaffolded", { folder: folderName, siteId });
-
-// ---- 2 · deploy shipped code + deps + lockfile ---------------------------------------------------
-const deploy = spawnSync(
-  "node",
-  [
-    join(SKILL_ROOT, "install", "deploy.mjs"),
-    vertical,
-    "--stack",
-    stack,
-    "--plan",
-    resolve(planPath),
-  ],
-  { cwd: projectDir, encoding: "utf8", timeout: 60_000 },
-);
-if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
-let deployResult = {};
-try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going with raw output below */ }
-if (deployResult.error) fail("deploy", deployResult.error);
-emit("deployed", deployResult);
-
-// ---- 2c · place the project in the current directory --------------------------------------------
-// The default. The Wix CLI scaffolds into a subfolder, so the scaffold is moved up into the current
-// directory — the folder that already holds the installed skills — and the subfolder removed. Done
-// HERE, before the detached install below, on purpose: no node_modules exists yet, so the move is
-// instant and cannot collide with a running install. A pure move: the scaffold was created with
-// --skip-git, so there is no nested repo to reconcile — git is whatever the folder already is.
-// Refuses rather than overwrite: an entry that already exists in the current directory stops the
-// move before anything is touched. `--subfolder` skips this step.
-const targetDir = process.cwd();
-if (!subfolder && projectDir !== targetDir) {
-  const entries = readdirSync(projectDir);
-  const clashes = entries.filter((e) => existsSync(join(targetDir, e)));
-  if (clashes.length) {
-    fail("place", `the current directory already has: ${clashes.join(", ")} — run with --subfolder to keep the project in ${folderName}/, or start in an empty folder`);
-  }
-  try {
-    for (const entry of entries) renameSync(join(projectDir, entry), join(targetDir, entry));
-    rmSync(projectDir, { recursive: true, force: true });
-    projectDir = targetDir;
-    emit("project_placed", { into: targetDir });
-  } catch (e) {
-    fail("place", e?.stack || e);
-  }
-}
-
-// ---- 3 · start the dependency install, detached --------------------------------------------------
-const installLog = join(projectDir, "npm-install.log");
-const logFd = openSync(installLog, "a");
-const install = spawn("sh", ["-c", "npm ci --ignore-scripts || npm install --ignore-scripts"], {
-  cwd: projectDir,
-  detached: true,
-  stdio: ["ignore", logFd, logFd],
-});
-install.unref();
-emit("install_started", { log: installLog, doneMarker: "node_modules/.package-lock.json" });
-
-// ---- 4 · start the seed, detached ----------------------------------------------------------------
-// The seed includes a Wix-side provisioning wait of unpredictable length (10-80s); running it
-// in the caller's foreground would idle the agent for exactly that long. Detach it like the
-// install: result JSON + exit-code marker land as files the caller syncs on before release.
-const seedDir = join(SKILL_ROOT, "references", vertical, "seed");
-const seedName = existsSync(seedDir)
-  ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
-  : undefined;
-const seedFile = seedName ? join(seedDir, seedName) : null;
-if (!seedFile) fail("seed", `no seed module found under ${seedDir}`);
-const seedResultFile = join(projectDir, "seed-result.json");
-const seedLog = join(projectDir, "seed.log");
-const seedDoneMarker = join(projectDir, ".seed-exit");
-const planAbs = resolve(planPath);
-const seedChild = spawn(
-  "sh",
-  ["-c", `node "${seedFile}" "${planAbs}" > seed-result.json 2> seed.log; echo $? > .seed-exit`],
-  { cwd: projectDir, detached: true, stdio: "ignore" },
-);
-seedChild.unref();
-emit("seeding_started", { vertical, resultFile: seedResultFile, log: seedLog, doneMarker: seedDoneMarker });
-
-// ---- done ----------------------------------------------------------------------------------------
-emit("ready_for_brand_layer", {
-  projectDir,
-  siteId,
-  dashboardUrl: deployResult.dashboardUrl,
-  productsUrl: deployResult.productsUrl,
-  categoriesUrl: deployResult.categoriesUrl,
-  install: { log: installLog, doneMarker: "node_modules/.package-lock.json" },
-  seed: { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" },
-  next: "theme SiteLayout + write the home page; then wait for BOTH done markers, verify .seed-exit is 0 (else read seed.log and re-run the seed module), build, release",
-});