@wix/agent-skills 1.18.1 → 1.19.0

package/skills/wix-vibe-headless/references/storefront/seed/{seed-store.js → seed-store.cjs}

@@ -5,22 +5,44 @@
 //
 // Usage (build-time exec_tool):
 //   const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");  // Base44
-//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.js");
-//   const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs");
+//   const ctx = { token: accessToken }; // Installation reads the site ID from the deployed Wix config.
 //   await seed.installStoresApp(ctx);
 //   const products = await seed.bulkCreateProducts(ctx, [{ name, description, price, quantity, options? }]);
 //   const cats = await seed.createCategories(ctx, ["Legends", "Rising Stars"]);
 //   await seed.addProductsToCategories(ctx, { [cats[0].id]: products.map(p => p.id) });
 //   await seed.attachProductImages(ctx, products.map((p,i) => ({ id:p.id, url:imageUrls[i], altText:p.slug })));
 //
-// If any call fails with a shape the caller didn't expect, fall back to the wix-docs skill
+// If any call fails with a shape the caller didn't expect, fall back to the documentation skill available in your environment
 // (search + read the live Wix API reference) — never guess. Source recipe (authoritative):
 // wix-headless/references/inline-recipes/setup-online-store.md.
 
 const API = "https://www.wixapis.com";
 const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const WIX_CONFIG_PATH = "/app/src/rest/wix-config.js";
+let siteId;
 
-async function req(ctx, path, { method = "POST", body } = {}) {
+function getSiteId() {
+  if (siteId) return siteId;
+  let source;
+  try {
+    source = require("fs").readFileSync(WIX_CONFIG_PATH, "utf8");
+  } catch {
+    throw new Error(`Cannot read ${WIX_CONFIG_PATH}; deploy the Wix config before seeding.`);
+  }
+  // Base44/deploy writes a named export containing a JSON string literal. Do not execute config.
+  const match = source.match(/^export const WIX_METASITE_ID\s*=\s*("(?:[^"\\]|\\.)*")\s*;/m);
+  let value;
+  try { value = match && JSON.parse(match[1]); } catch { /* invalid config */ }
+  if (typeof value !== "string" || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new Error(`Missing or invalid WIX_METASITE_ID in ${WIX_CONFIG_PATH}; deploy the Wix config before seeding.`);
+  }
+  siteId = value;
+  return siteId;
+}
+
+
+async function req(ctx, path, { method = "POST", body, headers = {} } = {}) {
   // Retry while the catalog is still provisioning: right after a fresh Stores install the V3 WRITE
   // path becomes usable a bit later than the V3 read path, so even once waitForCatalogV3 (a read
   // probe) returns, the first bulk-create can still 428. Wait it out (~80s budget); every other
@@ -30,7 +52,7 @@ async function req(ctx, path, { method = "POST", body } = {}) {
       method,
       headers: {
         Authorization: `Bearer ${ctx.token}`,
-        "wix-site-id": ctx.siteId,
+        ...headers,
         "Content-Type": "application/json",
       },
       body: body ? JSON.stringify(body) : undefined,
@@ -69,7 +91,7 @@ async function waitForCatalogV3(ctx, { attempts = 40, delayMs = 2000 } = {}) {
   for (let i = 0; i < attempts; i++) {
     const res = await fetch(`${API}/stores/v3/products/query`, {
       method: "POST",
-      headers: { Authorization: `Bearer ${ctx.token}`, "wix-site-id": ctx.siteId, "Content-Type": "application/json" },
+      headers: { Authorization: `Bearer ${ctx.token}`, "Content-Type": "application/json" },
       body: JSON.stringify({ query: { paging: { limit: 1 } } }),
     });
     if (res.ok) return;
@@ -148,8 +170,57 @@ function buildOptions(options = []) {
   });
 }
 
+// Validate the whole batch before installation, uploads, or product creation.
+function validateProducts(products) {
+  const seen = new Map();
+  for (const product of products) {
+    if (product.inStock !== undefined && typeof product.inStock !== "boolean") {
+      throw new Error(`Product "${product.name}": inStock must be a boolean. No products were created by this call.`);
+    }
+    if (product.inStock !== undefined && product.quantity !== undefined) {
+      throw new Error(`Product "${product.name}": supply either inStock or quantity, not both. No products were created by this call.`);
+    }
+    if (!product.digitalFileUrl && product.quantity !== undefined &&
+        (!Number.isInteger(product.quantity) || product.quantity < 0 || product.quantity > 99999)) {
+      throw new Error(`Product "${product.name}": quantity must be an integer from 0 to 99999. ` +
+        `For unlimited stock, use inStock: true without quantity. No products were created by this call.`);
+    }
+    for (const option of product.options ?? []) {
+      const choiceNames = new Set();
+      for (const choice of option.choices ?? []) {
+        const name = typeof choice === "string" ? choice : choice.name;
+        const normalized = name.trim().toLowerCase();
+        if (choiceNames.has(normalized)) {
+          throw new Error(`Duplicate choice "${name}" in option "${option.name}" on product "${product.name}". ` +
+            `Each choice name must be unique within an option. No products were created by this call.`);
+        }
+        choiceNames.add(normalized);
+        if (option.type !== "color") continue;
+        const key = JSON.stringify([option.name.trim().toLowerCase(), choice.name.trim().toLowerCase()]);
+        const code = choice.colorCode?.trim().toLowerCase();
+        const previous = seen.get(key);
+        if (previous && previous.code !== code) {
+          throw new Error(`Conflicting color "${choice.name}" in option "${option.name}": ` +
+            `"${previous.product}" uses ${previous.code}, but "${product.name}" uses ${code}. ` +
+            `Use one color code for this name across the batch, or distinct names for different shades. No products were created by this call.`);
+        }
+        seen.set(key, { code, product: product.name });
+      }
+    }
+  }
+}
+
+// Choose one inventory tracking mode; downloads retain their default available stock.
+function inventoryFor(product) {
+  if (product.inStock !== undefined) return { inStock: product.inStock };
+  if (product.digitalFileUrl) return { inStock: true };
+  return { quantity: product.quantity ?? 0 };
+}
+
 // full Cartesian product of variants, each priced/stocked from the product; visible:true baked in
-function expandVariants(options = [], { price, compareAtPrice, quantity }, digitalFileId) {
+function expandVariants(options = [], product, digitalFileId) {
+  const { price, compareAtPrice } = product;
+  const inventoryItem = inventoryFor(product);
   const base = {
     price: {
       actualPrice: { amount: String(price) },
@@ -157,8 +228,9 @@ function expandVariants(options = [], { price, compareAtPrice, quantity }, digit
     },
     visible: true,
     ...(digitalFileId
-      ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem: { inStock: true } }
-      : { physicalProperties: {}, inventoryItem: { quantity: quantity ?? 0, preorderInfo: { enabled: false } } }),
+      ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem }
+      : { physicalProperties: {}, inventoryItem: { ...inventoryItem,
+          ...(inventoryItem.quantity !== undefined ? { preorderInfo: { enabled: false } } : {}) } }),
   };
   if (!options.length) return [base];
   let combos = [[]];
@@ -185,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()),
   });
@@ -201,9 +274,10 @@ const digitalFileName = (p) =>
 // ---- exported operations ----
 
 async function installStoresApp(ctx) {
+  const siteId = getSiteId(); // Fail before the install-error catch if config is missing.
   try {
-    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
-      tenant: { tenantType: "SITE", id: ctx.siteId },
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { headers: { "wix-site-id": siteId }, body: {
+      tenant: { tenantType: "SITE", id: siteId },
       appInstance: { appDefId: STORES_APP_ID, enabled: true },
     } });
   } catch {
@@ -220,7 +294,7 @@ async function listProducts(ctx) {
 
 /**
  * Bulk-create products.
- * @param products [{ name, description, price, compareAtPrice?, quantity,
+ * @param products [{ name, description, price, compareAtPrice?, quantity?, inStock?,
  *   options?: [{ name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}] }],
  *   digitalFileUrl?, digitalFileName? }]
  *   digitalFileUrl: makes the product a DIGITAL download — the file is uploaded and the variant
@@ -229,10 +303,12 @@ async function listProducts(ctx) {
  *   Wix rich text here, so the storefront renders paragraphs and bold rather than tag text.
  *   options = ONLY things the buyer selects-and-buys (Size, Color) -> become variants.
  *   Display-only attributes go in name/category/description, NOT options. Default: no options.
- *   visible/physicalProperties/variant-expansion handled here. `quantity` is the stock created.
+ *   visible/physicalProperties/variant-expansion handled here. `quantity` tracks 0–99999 units (default 0); `inStock` selects availability without a count.
+ *   Supply only one. Each variant inherits that stock mode. Downloads default to inStock:true.
  * @returns [{ id, slug, revision }]
  */
 async function bulkCreateProducts(ctx, products) {
+  validateProducts(products);
   const fileIds = await Promise.all(products.map((p) =>
     p.digitalFileUrl ? uploadDigitalFile(ctx, p.digitalFileUrl, digitalFileName(p)) : null));
   const body = {
@@ -251,13 +327,39 @@ async function bulkCreateProducts(ctx, products) {
   };
   const r = await req(ctx, "/stores/v3/bulk/products-with-inventory/create", { body });
   // NB: results nest under productResults.results[].item — NOT a top-level `results`.
-  const created = (r.productResults?.results ?? []).map((x, i) => ({
-    id: x.item?.id, slug: x.item?.slug, revision: x.item?.revision,
-    variantId: x.item?.variantsInfo?.variants?.[0]?.id,
-    hasOptions: (products[i]?.options?.length ?? 0) > 0,
-    isDigital: !!fileIds[i],
-    quantity: products[i]?.quantity ?? 0,
-  }));
+  const results = r.productResults?.results ?? [];
+  const created = [];
+  const failures = [];
+  const seen = new Set();
+  for (const [position, result] of results.entries()) {
+    const index = result.itemMetadata?.originalIndex ?? position;
+    seen.add(index);
+    if (result.itemMetadata?.success === false || !result.item?.id) {
+      failures.push({ index, name: products[index]?.name, ...result.itemMetadata?.error,
+        message: result.itemMetadata?.error?.description ?? "Create result has no product ID" });
+      continue;
+    }
+    created.push({
+      id: result.item.id, slug: result.item.slug, revision: result.item.revision,
+      variantId: result.item.variantsInfo?.variants?.[0]?.id,
+      hasOptions: (products[index]?.options?.length ?? 0) > 0,
+      isDigital: !!fileIds[index], inventory: inventoryFor(products[index]),
+      index, name: products[index]?.name,
+    });
+  }
+  products.forEach((product, index) => {
+    if (!seen.has(index)) failures.push({ index, name: product.name, message: "Missing bulk-create result; creation status unknown" });
+  });
+  if (failures.length) {
+    const successes = created.map(({ id, name, index }) => ({ id, name, index }));
+    const error = new Error(`Product creation did not fully succeed. ` +
+      `Created: ${JSON.stringify(successes)}. Failures: ${JSON.stringify(failures)}. ` +
+      `Stopped before stock, categories, or images. Do not rerun the full seed: existing products would be duplicated.`);
+    error.createdProducts = successes;
+    error.failures = failures;
+    throw error;
+  }
+  created.sort((a, b) => a.index - b.index);
   await stockOptionlessProducts(ctx, created);
   return created.map((p) => ({ id: p.id, slug: p.slug, revision: p.revision }));
 }
@@ -278,7 +380,7 @@ async function stockOptionlessProducts(ctx, created) {
   }
   const inventoryItems = need
     .filter((p) => p.variantId)
-    .map((p) => ({ productId: p.id, variantId: p.variantId, quantity: p.quantity }));
+    .map((p) => ({ productId: p.id, variantId: p.variantId, ...p.inventory }));
   if (inventoryItems.length) {
     await req(ctx, "/stores/v3/bulk/inventory-items/create", { body: { inventoryItems } });
   }
@@ -315,8 +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]));
@@ -329,21 +440,58 @@ async function attachProductImages(ctx, items) {
   });
 }
 
+// Site-wide payment currency; product amounts are not converted when this changes.
+// https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md
+async function configureCurrency(ctx, requested) {
+  const result = { requested: requested ?? null, actual: null, status: "unchanged", warnings: [] };
+  if (requested !== undefined) {
+    try {
+      if (typeof requested !== "string" || !/^[A-Z]{3}$/.test(requested))
+        throw new Error("currency must be a three-letter uppercase ISO currency code");
+      await req(ctx, "/site-properties/v4/properties", {
+        method: "PATCH",
+        body: { properties: { paymentCurrency: requested }, fields: { paths: ["paymentCurrency"] } },
+      });
+      result.status = "updated";
+    } catch (error) {
+      result.status = "failed";
+      result.warnings.push(`Currency update failed; seeding continued: ${error.message}`);
+    }
+  }
+  try {
+    const snapshot = await req(ctx, "/site-properties/v4/properties", { method: "GET" });
+    result.actual = snapshot.properties?.paymentCurrency ?? null;
+    if (!result.actual) throw new Error("Site Properties returned no paymentCurrency");
+    if (requested !== undefined && result.actual !== requested) {
+      result.status = "failed";
+      result.warnings.push(`Requested currency ${requested}; site currency is ${result.actual}.`);
+    }
+  } catch (error) {
+    result.status = "failed";
+    result.warnings.push(`Currency verification failed; seeding continued: ${error.message}`);
+  }
+  return result;
+}
+
 /**
  * ONE-CALL seed: install → create products → categories → attach images, in the correct order,
  * keeping the created ids in memory (no hand-threading of product ids across exec calls). This is
  * the DEFAULT path — call it once instead of the individual functions.
  *
  * @param plan {{
- *   products: [{ name, description, price, compareAtPrice?, quantity, options?, imageUrl?, altText?,
+ *   currency?: string, // requested site payment currency; omitted preserves the current setting
+ *   products: [{ name, description, price, compareAtPrice?, quantity?, inStock?, options?, imageUrl?, altText?,
  *                digitalFileUrl?, digitalFileName? }],
  *   categories?: { [categoryName]: string[] },   // map of category name -> product NAMES in it
  * }}
- * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number }
+ * @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 = {} } = {}) {
+async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
+  validateProducts(products);
   await installStoresApp(ctx); // installs if needed AND waits for the V3 catalog to be ready
 
+  const currencyResult = await configureCurrency(ctx, currency);
   const created = await bulkCreateProducts(ctx, products);
   const withNames = created.map((p, i) => ({ ...p, name: products[i]?.name }));
   const idByName = new Map(withNames.map((p) => [p.name, p.id]));
@@ -360,11 +508,29 @@ async function setupStore(ctx, { products = [], categories = {} } = {}) {
   }
 
   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 };
+  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 = {

package/skills/wix-vibe-headless/references/storefront/app/pages/Shop.jsx

@@ -1,75 +0,0 @@
-// Shop / catalog page — thin view over useShop (all logic lives in the hook). Category menu, sort,
-// cursor paging, plus the loading / empty / failed states a seeded-separately catalog needs.
-// Styled with base44 design tokens (shadcn Tailwind classes).
-import { useShop, SORTS } from "@/hooks/useShop";
-import ProductGrid from "@/components/ProductGrid";
-
-export default function Shop() {
-  const s = useShop();
-  const showCategories = s.categories.length > 0;
-
-  return (
-    <main className="max-w-[1200px] mx-auto p-4">
-      <div className="flex flex-wrap items-end justify-between gap-3 mb-4">
-        <h1 className="font-display m-0">{s.activeCategory?.name || "Shop"}</h1>
-        {s.products?.length > 0 && (
-          <label className="flex items-center gap-2 text-sm text-muted-foreground">
-            Sort
-            <select value={s.sort} onChange={(e) => s.setSort(e.target.value)}
-              className="py-1.5 px-2 border border-input rounded-sm bg-background text-foreground text-sm">
-              {Object.entries(SORTS).map(([key, { label }]) => <option key={key} value={key}>{label}</option>)}
-            </select>
-          </label>
-        )}
-      </div>
-
-      {showCategories && (
-        <nav aria-label="Categories" className="flex flex-wrap gap-2 mb-6">
-          <CategoryChip active={!s.activeCategory} onClick={() => s.setActiveCategory(null)}>All</CategoryChip>
-          {s.categories.map((c) => (
-            <CategoryChip key={c.id} active={s.activeCategory?.id === c.id} onClick={() => s.setActiveCategory(c)}>
-              {c.name}
-            </CategoryChip>
-          ))}
-        </nav>
-      )}
-
-      {s.error ? (
-        <div role="alert" className="flex flex-col items-center gap-3 py-16 text-center">
-          <p className="m-0 text-muted-foreground">{s.error}</p>
-          <button onClick={s.retry}
-            className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Try again</button>
-        </div>
-      ) : (
-        <>
-          <ProductGrid
-            products={s.products}
-            loading={s.loading}
-            empty={s.activeCategory ? `Nothing in ${s.activeCategory.name} yet.` : "No products yet."}
-            emptyHint={s.activeCategory
-              ? "Pick another category, or add products to this one from your Wix dashboard."
-              : "Add products in your Wix dashboard and they'll appear here — no redeploy needed."}
-          />
-
-          {s.hasMore && (
-            <div className="flex justify-center mt-8">
-              <button onClick={s.loadMore} disabled={s.loadingMore}
-                className="border border-border bg-card text-foreground rounded-sm py-2.5 px-6 cursor-pointer text-sm font-semibold disabled:opacity-60 disabled:cursor-wait">
-                {s.loadingMore ? "Loading…" : "Load more"}
-              </button>
-            </div>
-          )}
-        </>
-      )}
-    </main>
-  );
-}
-
-function CategoryChip({ active, onClick, children }) {
-  return (
-    <button onClick={onClick} aria-pressed={active}
-      className={`py-1.5 px-3 cursor-pointer text-sm rounded-sm border ${
-        active ? "border-primary bg-primary text-primary-foreground" : "border-border bg-card text-foreground"
-      }`}>{children}</button>
-  );
-}