@jay-framework/wix-stores 0.18.3 → 0.19.1

package/README.md

@@ -50,7 +50,12 @@ The plugin requires `@jay-framework/wix-server-client` to be configured with Wix
 jay-stack setup wix-stores
 ```
 
-This creates `config/.wix-stores.yaml` and generates `agent-kit/references/wix-stores/categories.yaml` with the full category tree.
+This creates `config/.wix-stores.yaml` and writes static AIditor Add Menu component items to `agent-kit/aiditor/add-menu/wix-stores.yaml`.
+
+Run `jay-stack agent-kit` (or `yarn agent-kit`) to index the live category tree and refresh:
+
+- `agent-kit/references/wix-stores/categories.yaml` — full hierarchy for agent discovery
+- `agent-kit/aiditor/add-menu/wix-stores.generated.yaml` — one Add Menu item per category (Store → Categories)
 
 ### Config File (`config/.wix-stores.yaml`)
 

package/dist/agent-kit/aiditor/add-menu.template.yaml

@@ -0,0 +1,53 @@
+items:
+  - id: wix-stores:product-search
+    title: Product search
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/product-search.png
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract product-search.
+      Read agent-kit/materialized-contracts/wix-stores/product-search.jay-contract.
+      Script key: search
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
+
+  - id: wix-stores:product-page
+    title: Product page
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/product-page.png
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract product-page.
+      Read agent-kit/materialized-contracts/wix-stores/product-page.jay-contract.
+      Script key: p
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
+
+  - id: wix-stores:related-products
+    title: Related products
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/related-products.png
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract related-products.
+      Read agent-kit/materialized-contracts/wix-stores/related-products.jay-contract.
+      Script key: r
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
+      Use alongside product-page; pass productId and categorySlug as instance props.
+
+  - id: wix-stores:category-list
+    title: Category list
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/category-list.png
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract category-list.
+      Read agent-kit/materialized-contracts/wix-stores/category-list.jay-contract.
+      Script key: categories
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.

package/dist/contracts/category-list.jay-contract

@@ -42,6 +42,7 @@ tags:
         type: data
         dataType: string
         description: Category image URL
+        meta: {mediaType: wix-image}
         
       - tag: categoryLink
         type: interactive

package/dist/contracts/media.jay-contract

@@ -1,6 +1,5 @@
 name: media
 description: Single media item with URL, type, and thumbnail. Used as a sub-contract in media galleries.
 tags:
-  - {tag: url, type: data, dataType: string, description: Media Url}
+  - {tag: url, type: data, dataType: string, description: Media Url, meta: {mediaType: wix-image}}
   - {tag: mediaType, type: variant, dataType: "enum (IMAGE | VIDEO)", description: Media type}
-  - {tag: thumbnail_50x50, type: data, dataType: string, description: Media Thumbnail Url }

package/dist/contracts/media.jay-contract.d.ts

@@ -8,11 +8,10 @@ export enum MediaType {
 
 export interface MediaViewState {
   url: string,
-  mediaType: MediaType,
-  thumbnail_50x50: string
+  mediaType: MediaType
 }
 
-export type MediaSlowViewState = Pick<MediaViewState, 'url' | 'mediaType' | 'thumbnail_50x50'>;
+export type MediaSlowViewState = Pick<MediaViewState, 'url' | 'mediaType'>;
 
 export type MediaFastViewState = {};
 

package/dist/contracts/product-card.jay-contract

@@ -42,17 +42,18 @@ tags:
         type: data
         dataType: string
         description: Media URL
-        
+        meta: {mediaType: wix-image}
+
       - tag: altText
         type: data
         dataType: string
         description: Media alt text
-        
+
       - tag: mediaType
         type: data
         dataType: enum (IMAGE | VIDEO)
         description: Media type
-        
+
   - tag: thumbnail
     type: sub-contract
     description: Thumbnail image optimized for listings
@@ -61,17 +62,18 @@ tags:
         type: data
         dataType: string
         description: Thumbnail URL
-        
+        meta: {mediaType: wix-image}
+
       - tag: altText
         type: data
         dataType: string
         description: Thumbnail alt text
-        
+
       - tag: width
         type: data
         dataType: number
         description: Thumbnail width in pixels
-        
+
       - tag: height
         type: data
         dataType: number

package/dist/index.d.ts

@@ -631,8 +631,7 @@ declare enum MediaType {
 
 interface MediaViewState {
   url: string,
-  mediaType: MediaType,
-  thumbnail_50x50: string
+  mediaType: MediaType
 }
 
 interface MediaRefs {}

package/dist/index.js

@@ -10,6 +10,7 @@ import { WIX_CLIENT_SERVICE } from "@jay-framework/wix-server-client";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
+import { fileURLToPath } from "url";
 var OptionRenderType$2 = /* @__PURE__ */ ((OptionRenderType2) => {
   OptionRenderType2[OptionRenderType2["TEXT_CHOICES"] = 0] = "TEXT_CHOICES";
   OptionRenderType2[OptionRenderType2["SWATCH_CHOICES"] = 1] = "SWATCH_CHOICES";
@@ -205,7 +206,7 @@ function parseWixMediaUrl(url) {
   return result;
 }
 function formatWixMediaUrl(_id, url, resize) {
-  const resizeFragment = resize ? `/v1/fit/w_${resize.w},h_${resize.h},q_90/file.jpg` : "";
+  const resizeFragment = "";
   if (url == null ? void 0 : url.startsWith("wix:")) {
     const parsed = parseWixMediaUrl(url);
     if (parsed) {
@@ -429,7 +430,7 @@ function mapProductToCard(product, urls, tree) {
       mediaType: mapMediaType$1(mainMedia?.mediaType)
     },
     thumbnail: {
-      url: mainMedia ? formatWixMediaUrl(mainMedia._id, mainMedia.url, { w: 300, h: 300 }) : "",
+      url: mainMedia ? formatWixMediaUrl(mainMedia._id, mainMedia.url) : "",
       altText: mainMedia?.altText || product.name || "",
       width: 300,
       height: 300
@@ -1343,7 +1344,7 @@ function mapMedia(media) {
   const main = media?.main;
   if (!main) {
     return {
-      selectedMedia: { url: "", mediaType: MediaType.IMAGE, thumbnail_50x50: "" },
+      selectedMedia: { url: "", mediaType: MediaType.IMAGE },
       availableMedia: []
     };
   }
@@ -1351,15 +1352,13 @@ function mapMedia(media) {
   return {
     selectedMedia: {
       url: formatWixMediaUrl(main._id, main.url),
-      mediaType: mainMediaType,
-      thumbnail_50x50: formatWixMediaUrl(main._id, main.url, { w: 50, h: 50 })
+      mediaType: mainMediaType
     },
     availableMedia: media.itemsInfo?.items?.map((item) => ({
       mediaId: item._id,
       media: {
         url: formatWixMediaUrl(item._id, item.url),
-        mediaType: item.mediaType === "IMAGE" ? MediaType.IMAGE : MediaType.VIDEO,
-        thumbnail_50x50: formatWixMediaUrl(item._id, item.url, { w: 50, h: 50 })
+        mediaType: item.mediaType === "IMAGE" ? MediaType.IMAGE : MediaType.VIDEO
       },
       selected: item._id === main._id ? Selected.selected : Selected.notSelected
     })) ?? []
@@ -1650,8 +1649,9 @@ async function renderSlowlyChanging(props, wixStores) {
 }
 const categoryList = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging);
 const WIX_STORES_CONTEXT = createJayContext("wix:stores");
-function loadWixStoresConfig() {
-  const configPath = path.join(process.cwd(), "config", ".wix-stores.yaml");
+function loadWixStoresConfig(projectRoot) {
+  const root = projectRoot ?? process.cwd();
+  const configPath = path.join(root, "config", ".wix-stores.yaml");
   const defaults = {
     urls: { product: "/products/{slug}", category: null },
     defaultCategory: null
@@ -1691,7 +1691,171 @@ const init = makeJayInit().withServer(async () => {
     enableClientSearch: true
   };
 });
+function flattenCategoryTree(roots, parentNames = [], parentSlugs = [], rootSlug = null) {
+  const entries = [];
+  for (const node of roots) {
+    const entryRootSlug = rootSlug ?? node.slug;
+    entries.push({
+      node,
+      breadcrumbNames: parentNames,
+      breadcrumbSlugs: parentSlugs,
+      rootSlug: entryRootSlug,
+      parentSlug: parentSlugs.length > 0 ? parentSlugs[parentSlugs.length - 1] : null
+    });
+    if (node.children.length > 0) {
+      entries.push(
+        ...flattenCategoryTree(
+          node.children,
+          [...parentNames, node.name],
+          [...parentSlugs, node.slug],
+          entryRootSlug
+        )
+      );
+    }
+  }
+  return entries;
+}
+function sanitizeIdSegment(slug, categoryId) {
+  const sanitized = slug.trim().replace(/[^\w-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (sanitized.length > 0) {
+    return sanitized.slice(0, 64);
+  }
+  return categoryId.slice(0, 8);
+}
+function uniqueCategoryItemId(slug, categoryId, usedIds) {
+  const base = sanitizeIdSegment(slug, categoryId);
+  let id = `wix-stores:category:${base}`;
+  let suffix = 2;
+  while (usedIds.has(id)) {
+    id = `wix-stores:category:${base}-${suffix++}`;
+  }
+  usedIds.add(id);
+  return id;
+}
+function formatCategoryTitle(entry) {
+  const { node, breadcrumbNames, rootSlug } = entry;
+  if (breadcrumbNames.length === 0) {
+    return `Category — ${node.name}`;
+  }
+  const rootLabel = rootSlug !== node.slug ? ` (${rootSlug})` : "";
+  const path2 = [...breadcrumbNames, node.name].join(" › ");
+  return `Category — ${path2}${rootLabel}`;
+}
+function resolveExampleCategoryUrl(config, entry) {
+  const template = config.urls.category;
+  if (!template) {
+    return null;
+  }
+  let url = template;
+  if (url.includes("{prefix}")) {
+    url = url.replace("{prefix}", entry.rootSlug);
+  }
+  if (url.includes("{category}")) {
+    url = url.replace("{category}", entry.node.slug);
+  }
+  return url;
+}
+function buildCategoryPrompt(config, entry) {
+  const { node, breadcrumbNames, breadcrumbSlugs, rootSlug, parentSlug } = entry;
+  const hierarchyPath = breadcrumbNames.length > 0 ? [...breadcrumbNames, node.name].join(" > ") : node.name;
+  const lines = [
+    `Scope this request to Wix Stores category "${node.name}".`,
+    "",
+    "Category facts (from agent-kit/references/wix-stores/categories.yaml):",
+    `  Category ID: ${node._id}`,
+    `  Category slug: ${node.slug}`,
+    `  Product count: ${node.productCount}`,
+    `  Hierarchy: ${hierarchyPath}`
+  ];
+  if (parentSlug) {
+    lines.push(`  Parent category slug: ${parentSlug}`);
+  }
+  if (rootSlug && rootSlug !== node.slug) {
+    lines.push(`  Root / prefix category slug: ${rootSlug}`);
+  }
+  const exampleUrl = resolveExampleCategoryUrl(config, entry);
+  if (exampleUrl) {
+    lines.push(`  Example category URL (config/.wix-stores.yaml): ${exampleUrl}`);
+  }
+  lines.push(
+    "",
+    "Full indexed category tree: agent-kit/references/wix-stores/categories.yaml",
+    "",
+    "Common headless bindings for this category:",
+    `  product-search — filter by category slug via jay-params, e.g. category="${node.slug}"${rootSlug !== node.slug ? `; prefix="${rootSlug}" when URL template uses {prefix}` : ""}`
+  );
+  if (parentSlug) {
+    lines.push(
+      `  category-list — show direct children with parentCategory="${parentSlug}"; this category's children use parentCategory="${node.slug}"`
+    );
+  } else {
+    lines.push(
+      `  category-list — show top-level categories (no parentCategory), or children with parentCategory="${node.slug}"`
+    );
+  }
+  lines.push(
+    `  related-products — pass categorySlug="${node.slug}" alongside a productId when showing related items in this category`,
+    "",
+    "Contracts:",
+    "  agent-kit/materialized-contracts/wix-stores/product-search.jay-contract",
+    "  agent-kit/materialized-contracts/wix-stores/category-list.jay-contract",
+    "  agent-kit/materialized-contracts/wix-stores/related-products.jay-contract",
+    "",
+    "Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md."
+  );
+  if (config.defaultCategory) {
+    lines.push(
+      "",
+      `Project defaultCategory (fallback when no category context): ${config.defaultCategory}`
+    );
+  }
+  return lines.join("\n");
+}
+function buildCategoryAddMenuItems(roots, config) {
+  const usedIds = /* @__PURE__ */ new Set();
+  const entries = flattenCategoryTree(roots);
+  return entries.map((entry) => ({
+    id: uniqueCategoryItemId(entry.node.slug, entry.node._id, usedIds),
+    title: formatCategoryTitle(entry),
+    category: "Store",
+    subCategory: "Categories",
+    pluginName: "wix-stores",
+    packageName: "@jay-framework/wix-stores",
+    prompt: buildCategoryPrompt(config, entry)
+  }));
+}
 const CONFIG_FILE_NAME = ".wix-stores.yaml";
+const ADD_MENU_OUTPUT_REL = "agent-kit/aiditor/add-menu/wix-stores.yaml";
+const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/wix-stores.generated.yaml";
+function resolveAddMenuTemplatePath() {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const fromDist = path.join(thisDir, "agent-kit/aiditor/add-menu.template.yaml");
+  if (fs.existsSync(fromDist)) {
+    return fromDist;
+  }
+  return path.join(thisDir, "..", "agent-kit/aiditor/add-menu.template.yaml");
+}
+function writeAddMenuCatalog(ctx) {
+  const outputPath = path.join(ctx.projectRoot, ADD_MENU_OUTPUT_REL);
+  if (fs.existsSync(outputPath) && !ctx.force) {
+    return null;
+  }
+  const templatePath = resolveAddMenuTemplatePath();
+  const templateContent = fs.readFileSync(templatePath, "utf-8");
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, templateContent, "utf-8");
+  return ADD_MENU_OUTPUT_REL;
+}
+function writeGeneratedAddMenuCatalog(projectRoot, categoryRoots) {
+  const outputPath = path.join(projectRoot, ADD_MENU_GENERATED_REL);
+  const config = loadWixStoresConfig(projectRoot);
+  const items = buildCategoryAddMenuItems(categoryRoots, config);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const header = "# DO NOT EDIT BY HAND — regenerated by jay-stack agent-kit (wix-stores references)\n\n";
+  const body = yaml.dump({ items }, { indent: 2, lineWidth: 120, noRefs: true });
+  fs.writeFileSync(outputPath, header + body, "utf-8");
+  return ADD_MENU_GENERATED_REL;
+}
 const CONFIG_TEMPLATE = `# Wix Stores Configuration
 #
 # URL templates for link generation.
@@ -1736,6 +1900,20 @@ async function setupWixStores(ctx) {
     configCreated.push(`config/${CONFIG_FILE_NAME}`);
   }
   const service = getService(WIX_STORES_SERVICE_MARKER);
+  try {
+    await service.products.searchProducts({});
+  } catch (e) {
+    const msg = e.message || "";
+    const hint = msg.includes("404") || msg.includes("not found") ? "Wix Stores may not be installed on this site" : msg.includes("403") || msg.includes("permission") ? "API key may lack Wix Stores permissions" : "This package requires the Stores Catalog V3 API — if using Catalog V1, use @jay-framework/wix-stores-v1 instead";
+    return {
+      status: "error",
+      message: `Wix Stores V3 API check failed: ${hint}. (${msg})`
+    };
+  }
+  const addMenuCreated = writeAddMenuCatalog(ctx);
+  if (addMenuCreated) {
+    configCreated.push(addMenuCreated);
+  }
   const message = `Wix Stores configured (product URL: ${service.urls.product})`;
   return {
     status: "configured",
@@ -1798,6 +1976,7 @@ async function generateWixStoresReferences(ctx) {
     ),
     "utf-8"
   );
+  const addMenuGenerated = writeGeneratedAddMenuCatalog(ctx.projectRoot, roots);
   let extensionFieldCount = 0;
   try {
     const extensionSchemas = await storesService.getDataExtensionSchemas();
@@ -1831,7 +2010,10 @@ async function generateWixStoresReferences(ctx) {
   } catch (error) {
     console.error("[wix-stores] Failed to fetch data extension schemas:", error);
   }
-  const referencesCreated = [`agent-kit/references/${ctx.pluginName}/categories.yaml`];
+  const referencesCreated = [
+    `agent-kit/references/${ctx.pluginName}/categories.yaml`,
+    addMenuGenerated
+  ];
   if (extensionFieldCount > 0) {
     referencesCreated.push(`agent-kit/references/${ctx.pluginName}/data-extension-fields.yaml`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.18.3",
+  "version": "0.19.1",
   "type": "module",
   "description": "Wix Stores API client for Jay Framework",
   "license": "Apache-2.0",
@@ -30,24 +30,24 @@
     "validate": "jay-stack-cli validate-plugin",
     "build:client": "vite build",
     "build:server": "vite build --ssr",
-    "build:copy-contract": "mkdir -p dist/contracts && cp lib/contracts/*.jay-contract* dist/contracts/ && mkdir -p dist/actions && cp lib/actions/*.jay-action dist/actions/",
+    "build:copy-contract": "mkdir -p dist/contracts && cp lib/contracts/*.jay-contract* dist/contracts/ && mkdir -p dist/actions && cp lib/actions/*.jay-action dist/actions/ && mkdir -p dist/agent-kit/aiditor && cp agent-kit/aiditor/add-menu.template.yaml dist/agent-kit/aiditor/",
     "build:types": "tsup lib/index.ts --dts-only --format esm",
     "build:check-types": "tsc",
     "clean": "rimraf dist",
     "confirm": "npm run clean && npm run build && npm run test",
-    "test": ":"
+    "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.18.3",
-    "@jay-framework/fullstack-component": "^0.18.3",
-    "@jay-framework/reactive": "^0.18.3",
-    "@jay-framework/runtime": "^0.18.3",
-    "@jay-framework/secure": "^0.18.3",
-    "@jay-framework/stack-client-runtime": "^0.18.3",
-    "@jay-framework/stack-server-runtime": "^0.18.3",
-    "@jay-framework/wix-cart": "^0.18.3",
-    "@jay-framework/wix-server-client": "^0.18.3",
-    "@jay-framework/wix-utils": "^0.18.3",
+    "@jay-framework/component": "^0.19.1",
+    "@jay-framework/fullstack-component": "^0.19.1",
+    "@jay-framework/reactive": "^0.19.1",
+    "@jay-framework/runtime": "^0.19.1",
+    "@jay-framework/secure": "^0.19.1",
+    "@jay-framework/stack-client-runtime": "^0.19.1",
+    "@jay-framework/stack-server-runtime": "^0.19.1",
+    "@jay-framework/wix-cart": "^0.19.1",
+    "@jay-framework/wix-server-client": "^0.19.1",
+    "@jay-framework/wix-utils": "^0.19.1",
     "@wix/categories": "^1.0.185",
     "@wix/data-extension-schema": "^1.0.221",
     "@wix/sdk": "^1.21.5",
@@ -59,16 +59,17 @@
     "@babel/core": "^7.23.7",
     "@babel/preset-env": "^7.23.8",
     "@babel/preset-typescript": "^7.23.3",
-    "@jay-framework/compiler-jay-stack": "^0.18.3",
-    "@jay-framework/jay-cli": "^0.18.3",
-    "@jay-framework/jay-stack-cli": "^0.18.3",
-    "@jay-framework/vite-plugin": "^0.18.3",
+    "@jay-framework/compiler-jay-stack": "^0.19.1",
+    "@jay-framework/jay-cli": "^0.19.1",
+    "@jay-framework/jay-stack-cli": "^0.19.1",
+    "@jay-framework/vite-plugin": "^0.19.1",
     "nodemon": "^3.0.3",
     "rimraf": "^5.0.5",
     "tslib": "^2.6.2",
     "tsup": "^8.5.1",
     "typescript": "^5.3.3",
     "vite": "^5.0.11",
-    "vite-plugin-inspect": "^0.8.1"
+    "vite-plugin-inspect": "^0.8.1",
+    "vitest": "^1.2.0"
   }
 }