@wix/agent-skills 1.18.2 → 1.19.0

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -24,7 +24,8 @@ No installation, deployment, or AGENTS.md update is needed.
 The deployed implementation and configuration files do not need to be read; use the build and seed
 guides below for their contracts and usage. Continue with STEP 1.
 
-Follow STEPs 1–3 below exactly (run STEP 2 in parallel with STEP 1).
+Follow STEPs 1–3 below exactly. Fire product image generations first, then build the client
+(STEP 1), and seed (STEP 2) **after** the client is built — generation finishes while you build.
 
 ## STEP 1 — Build the client
 
@@ -74,13 +75,13 @@ Inline via exec_tool, `base44` is already declared — use it directly; do **not
 `@base44/sdk`, re-declare it, or call `createClient()` (that's for standalone `.js` files only;
 inline it throws *"Identifier 'base44' has already been declared."*).
 
-**Product images.** Generate with **Base44's built-in image generation**, then attach via the
-storefront seed module's image-attach step.
-
-**Seed images with the FINAL url, in one call.** Use the real `https://media.base44.com/...` url
-from the **completed** `generate_image` result and pass it straight into your single `setupStore`
-call (images included). `generate_image` runs in the background while you build the client, so the
-urls are ready by the time you seed.
+**Product images.** Fire every `generate_image` **before you build the client**, and seed **after**
+it — generation finishes while you build, so by the time you write the seed call your images are
+ready: each finished result now reads `status: "completed"` with its final
+`https://media.base44.com/...` url. Read every `imageUrl` from the results **as they read at that
+moment** — not from what they said when you called the tool — and pass them in the single
+`setupStore` call. A result without a final url by then (still running, or failed) → seed that
+product **without** `imageUrl` and attach it afterwards with `attachProductImages`.
 
 ## STEP 3 — Wrap up
 

package/skills/wix-vibe-headless/platforms/base44.md

@@ -11,7 +11,8 @@ only), safe in the frontend; use it directly for the Wix client setup.
 **Banner enabled for this entry flow:** mount `<WixManageBanner/>` once in the Layout, above
 the header in the fixed top region, per the vertical instructions. It is preview-only.
 
-Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3 — **except `forms`**, see STEP 3).
+Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3 — **except `forms`**, see
+STEP 3, and **except a seed that attaches entity images**, which runs after the build; see STEP 4).
 
 ## STEP 1 — Install the Wix skills locally
 
@@ -98,8 +99,15 @@ rejects the write. Wire routes/imports in with `find_replace`, leave the rest as
 
 Seed by calling your vertical's ready-made seed module — read
 `.agents/skills/wix-vibe-headless/references/<vertical>/seed/SEED.md` and follow it (the loader
-snippet, admin connector token, entity images with the final `media.base44.com` url, and every field
-shape are there). Gaps or an unexpected shape → the documentation skill available in your environment.
+snippet, admin connector token, and every field shape are there). Gaps or an unexpected shape → the
+documentation skill available in your environment.
+
+**Entity images:** fire every image generation **before you build the client**, and run an
+image-carrying seed **after** the build — generation finishes while you build, and each finished
+result then reads `status: "completed"` with its final `https://media.base44.com/...` url. Read
+every image url from the results **as they read at that moment**, not from what they said when you
+called the tool. No final url by then (still running, or failed) → seed without that image and
+attach it afterwards per the vertical's `SEED.md`.
 Seeding is **admin-only** — not part of the client, which is built solely per the `wix-vibe-headless` skill.
 
 - **Additive only:** never delete or overwrite the user's content, even apparent sample data; ask first if a cleanup truly seems needed.

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -336,6 +336,10 @@ wire these exactly as shown below.
 When adding storefront routes and providers to `src/App.jsx`, preserve the existing platform
 authentication setup, including `AuthProvider`, `useAuth`, and their `@/lib/AuthContext` imports.
 Do not remove or replace that authentication logic.
+The shipped commerce flow needs no login: shoppers browse, cart, and check out on the Wix visitor
+session, which is separate from platform user auth. Whether the storefront is public or members-only
+is the brief's call — default to public, and gate routes behind platform auth only when the brief
+asks for it. Neither choice affects the commerce flow.
 - Wrap the routed tree in `<CartProvider>` (from `@/context/CartContext`).
 - Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
   route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page

package/skills/wix-vibe-headless/references/storefront/seed/SEED.md

@@ -19,9 +19,7 @@ const ctx = { token: accessToken };
 // ONE call: install (+ wait for V3) → create products → categories → attach images, ids kept
 // in memory (no hand-threading). Categories map name -> product NAMES. Pass an imageUrl per product
 // to attach its image; omit it to skip images.
-// imageUrl must be the FINAL https://media.base44.com/... url from the COMPLETED generate_image
-// result — not a still-generating /__generating__/<id>.png placeholder (Wix can't fetch that).
-// generate_image runs in the background while you build, so the urls are ready by seed time.
+// imageUrl: a public, fetchable https:// url — Wix copies the image bytes at attach time.
 const result = await seed.setupStore(ctx, {
   currency: "EUR", // Pass only if the user asked for a currency or it's obvious for the store; else omit this line.
   products: [
@@ -38,6 +36,8 @@ const result = await seed.setupStore(ctx, {
   categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
 });
 // result: { products:[{id,slug,revision,name}], categories:[{id,name}], imagesAttached,
+//   imagesSkipped (product names whose imageUrl was not an absolute https:// url — attach those afterwards),
+//   productsWithoutImages (product names seeded with no imageUrl — attach afterwards once urls exist),
 //   currency: { requested, actual, status, warnings } }
 ```
 
@@ -112,6 +112,8 @@ enrolls in — is **Pricing Plans**, not a Stores product, so it isn't seeded he
 download — uploaded and created with both the file and stock, which is what the cart requires
 (`quantity` is ignored). It's also the only way in: a file-less digital product is created
 successfully, reads back healthy, and is then rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`.
+No real, fetchable file in hand → seed the product as **physical** with `inStock: true` and tell the
+user; swap it to a digital download once a real file exists.
 
 Two things this module does **not** seed, so don't try:
 
@@ -138,7 +140,6 @@ const products = await seed.bulkCreateProducts(ctx, [                 // → [{i
 ]);
 const cats = await seed.createCategories(ctx, ["Legends"]);           // sequential → [{id,name}]
 await seed.addProductsToCategories(ctx, { [cats[0].id]: [products[0].id] });
-// images: use the FINAL https://media.base44.com/... url only (never a /__generating__/ placeholder)
 await seed.attachProductImages(ctx, products.map((p, i) => ({ id: p.id, url: imageUrls[i], altText: p.slug })));
 ```
 

package/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs

@@ -257,7 +257,8 @@ async function uploadDigitalFile(ctx, url, fileName) {
   if (!mimeType) throw new Error(`digitalFileName needs one of these extensions (${Object.keys(FILE_MIME).join(", ")}): ${fileName}`);
   const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
   const src = await fetch(url);
-  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}`);
+  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}. A digital product needs a real, ` +
+    `fetchable file — with none at hand, seed this product as physical with inStock: true and tell the user.`);
   const res = await fetch(uploadUrl, {
     method: "PUT", headers: { "Content-Type": mimeType }, body: Buffer.from(await src.arrayBuffer()),
   });
@@ -416,9 +417,17 @@ async function addProductsToCategories(ctx, mapping) {
 // caller never manages a revision token — attach any number of times, in any pass. Wix re-hosts the
 // image from the url server-side; the re-hosted media can take a little while to appear on read-back
 // (propagation) — that's normal, not a failure, so we don't block on it.
+// Wix imports the image bytes server-side, so an attach needs an absolute, publicly fetchable url.
+const isFetchableImageUrl = (url) => typeof url === "string" && /^https:\/\//.test(url);
+
 async function attachProductImages(ctx, items) {
   if (!items?.length) return;
   if (items.some((it) => !it.id)) throw new Error("Image attachment requires a product ID for every item; no image request was sent.");
+  const unfetchable = items.filter((it) => !isFetchableImageUrl(it.url));
+  if (unfetchable.length) throw new Error(
+    `Image url(s) for [${unfetchable.map((it) => it.altText || it.id).join(", ")}] are not absolute ` +
+    `https:// urls, and Wix copies the image bytes at attach time. Re-call attachProductImages once each ` +
+    `image has its final url. No image request was sent; products are unaffected.`);
   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]));
@@ -475,7 +484,8 @@ async function configureCurrency(ctx, requested) {
  *                digitalFileUrl?, digitalFileName? }],
  *   categories?: { [categoryName]: string[] },   // map of category name -> product NAMES in it
  * }}
- * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number, currency: {requested,actual,status,warnings} }
+ * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number,
+ *             imagesSkipped?: string[], note?: string, currency: {requested,actual,status,warnings} }
  */
 async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
   validateProducts(products);
@@ -498,11 +508,29 @@ async function setupStore(ctx, { products = [], categories = {}, currency } = {}
   }
 
   const imageItems = withNames
-    .map((p, i) => ({ id: p.id, url: products[i]?.imageUrl, altText: products[i]?.altText ?? p.slug }))
+    .map((p, i) => ({ id: p.id, url: products[i]?.imageUrl, altText: products[i]?.altText ?? p.slug, name: p.name }))
     .filter((it) => it.url);
-  if (imageItems.length) await attachProductImages(ctx, imageItems);
+  // A url Wix cannot fetch would fail the attach: seed the product imageless and report it,
+  // so the caller attaches once the final url exists.
+  const readyItems = imageItems.filter((it) => isFetchableImageUrl(it.url));
+  const skipped = imageItems.filter((it) => !isFetchableImageUrl(it.url)).map((it) => it.name);
+  if (readyItems.length) await attachProductImages(ctx, readyItems);
 
-  return { products: withNames, categories: cats, imagesAttached: imageItems.length, currency: currencyResult };
+  const withoutImages = withNames.filter((p, i) => !products[i]?.imageUrl).map((p) => p.name);
+  return {
+    products: withNames, categories: cats, imagesAttached: readyItems.length,
+    ...(skipped.length && {
+      imagesSkipped: skipped,
+      note: "these products' image urls were not absolute https:// urls — attach them with " +
+        "attachProductImages once each image has its final url",
+    }),
+    ...(withoutImages.length && !skipped.length && {
+      productsWithoutImages: withoutImages,
+      note: "these products were seeded without an image — once their images have final urls, " +
+        "attach them with attachProductImages",
+    }),
+    currency: currencyResult,
+  };
 }
 
 module.exports = {