@jay-framework/wix-stores 0.15.1 → 0.15.5

package/dist/index.js

@@ -1,7 +1,6 @@
-import { getCurrentCartClient } from "@jay-framework/wix-cart";
 import { WIX_CART_CONTEXT, WIX_CART_SERVICE, cartIndicator, cartPage, provideWixCartContext, provideWixCartService } from "@jay-framework/wix-cart";
 import { createJayService, makeJayQuery, ActionError, makeJayStackComponent, RenderPipeline, makeJayInit } from "@jay-framework/fullstack-component";
-import { inventoryItemsV3, productsV3 } from "@wix/stores";
+import { customizationsV3, inventoryItemsV3, productsV3 } from "@wix/stores";
 import { categories } from "@wix/categories";
 import { registerService, getService } from "@jay-framework/stack-server-runtime";
 import { createJayContext } from "@jay-framework/runtime";
@@ -10,6 +9,11 @@ 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";
+var OptionRenderType$2 = /* @__PURE__ */ ((OptionRenderType2) => {
+  OptionRenderType2[OptionRenderType2["TEXT_CHOICES"] = 0] = "TEXT_CHOICES";
+  OptionRenderType2[OptionRenderType2["SWATCH_CHOICES"] = 1] = "SWATCH_CHOICES";
+  return OptionRenderType2;
+})(OptionRenderType$2 || {});
 var CurrentSort = /* @__PURE__ */ ((CurrentSort2) => {
   CurrentSort2[CurrentSort2["relevance"] = 0] = "relevance";
   CurrentSort2[CurrentSort2["priceAsc"] = 1] = "priceAsc";
@@ -22,7 +26,8 @@ var CurrentSort = /* @__PURE__ */ ((CurrentSort2) => {
 const instances = {
   productsV3ClientInstance: void 0,
   categoriesClientInstance: void 0,
-  inventoryV3ClientInstance: void 0
+  inventoryV3ClientInstance: void 0,
+  customizationsV3ClientInstance: void 0
 };
 function getProductsV3Client(wixClient) {
   if (!instances.productsV3ClientInstance) {
@@ -42,15 +47,70 @@ function getInventoryClient(wixClient) {
   }
   return instances.inventoryV3ClientInstance;
 }
+function getCustomizationsV3Client(wixClient) {
+  if (!instances.customizationsV3ClientInstance) {
+    instances.customizationsV3ClientInstance = wixClient.use(customizationsV3);
+  }
+  return instances.customizationsV3ClientInstance;
+}
 const WIX_STORES_SERVICE_MARKER = createJayService("Wix Store Service");
 function provideWixStoresService(wixClient, options) {
+  let cachedTree = null;
+  let cachedCustomizations = null;
+  const categoriesClient = getCategoriesClient(wixClient);
+  const customizationsClient = getCustomizationsV3Client(wixClient);
   const service = {
     products: getProductsV3Client(wixClient),
-    categories: getCategoriesClient(wixClient),
+    categories: categoriesClient,
     inventory: getInventoryClient(wixClient),
-    // Keep cart for backward compatibility, but prefer WIX_CART_SERVICE
-    cart: getCurrentCartClient(wixClient),
-    categoryPrefixes: options?.categoryPrefixes ?? []
+    customizations: customizationsClient,
+    urls: options?.urls ?? { product: "/products/{slug}", category: null },
+    defaultCategory: options?.defaultCategory ?? null,
+    async getCategoryTree() {
+      if (cachedTree) return cachedTree;
+      const slugMap = /* @__PURE__ */ new Map();
+      const parentMap = /* @__PURE__ */ new Map();
+      const rootIds = /* @__PURE__ */ new Set();
+      const imageMap = /* @__PURE__ */ new Map();
+      try {
+        const processItems = (items) => {
+          for (const cat of items) {
+            if (!cat._id || !cat.slug) continue;
+            slugMap.set(cat._id, cat.slug);
+            if (cat.parentCategory?._id) {
+              parentMap.set(cat._id, cat.parentCategory._id);
+            } else {
+              rootIds.add(cat._id);
+            }
+            const imageUrl = cat.media?.mainMedia?.image?.url || cat.media?.mainMedia?.url;
+            if (imageUrl) {
+              imageMap.set(cat._id, imageUrl);
+            }
+          }
+        };
+        let result = await categoriesClient.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("visible", true).limit(100).find();
+        processItems(result.items || []);
+        while (result.hasNext()) {
+          result = await result.next();
+          processItems(result.items || []);
+        }
+      } catch (error) {
+        console.error("[wix-stores] Failed to build category tree:", error);
+      }
+      cachedTree = { slugMap, parentMap, rootIds, imageMap };
+      return cachedTree;
+    },
+    async getCustomizations() {
+      if (cachedCustomizations) return cachedCustomizations;
+      try {
+        const result = await customizationsClient.queryCustomizations().eq("customizationType", "PRODUCT_OPTION").limit(100).find();
+        cachedCustomizations = result.items || [];
+      } catch (error) {
+        console.error("[wix-stores] Failed to load customizations:", error);
+        cachedCustomizations = [];
+      }
+      return cachedCustomizations;
+    }
   };
   registerService(WIX_STORES_SERVICE_MARKER, service);
   return service;
@@ -80,7 +140,8 @@ var ProductType$1 = /* @__PURE__ */ ((ProductType2) => {
 var QuickAddType = /* @__PURE__ */ ((QuickAddType2) => {
   QuickAddType2[QuickAddType2["SIMPLE"] = 0] = "SIMPLE";
   QuickAddType2[QuickAddType2["SINGLE_OPTION"] = 1] = "SINGLE_OPTION";
-  QuickAddType2[QuickAddType2["NEEDS_CONFIGURATION"] = 2] = "NEEDS_CONFIGURATION";
+  QuickAddType2[QuickAddType2["COLOR_AND_TEXT_OPTIONS"] = 2] = "COLOR_AND_TEXT_OPTIONS";
+  QuickAddType2[QuickAddType2["NEEDS_CONFIGURATION"] = 3] = "NEEDS_CONFIGURATION";
   return QuickAddType2;
 })(QuickAddType || {});
 var OptionRenderType$1 = /* @__PURE__ */ ((OptionRenderType2) => {
@@ -136,33 +197,54 @@ function formatWixMediaUrl(_id, url, resize) {
   }
   return "";
 }
-function resolveProductPrefix(product, prefixConfig) {
-  if (!prefixConfig?.length || !product.allCategoriesInfo?.categories) {
-    return null;
-  }
-  const productCategoryIds = new Set(
-    product.allCategoriesInfo.categories.map((c) => c._id).filter(Boolean)
-  );
-  for (const { categoryId, prefix } of prefixConfig) {
-    if (productCategoryIds.has(categoryId)) {
-      return prefix;
+function findRootCategoryId(categoryId, tree) {
+  let current = categoryId;
+  for (let depth = 0; depth < 20; depth++) {
+    if (tree.rootIds.has(current)) {
+      return current;
     }
+    const parentId = tree.parentMap.get(current);
+    if (!parentId) return current;
+    current = parentId;
   }
-  return null;
+  return current;
 }
-function resolveProductPrefixConfig(product, prefixConfig) {
-  if (!prefixConfig?.length || !product.allCategoriesInfo?.categories) {
-    return null;
+function findRootCategorySlug(categoryId, tree) {
+  const rootId = findRootCategoryId(categoryId, tree);
+  return tree.slugMap.get(rootId) ?? "";
+}
+function findCategoryImage(categoryId, tree) {
+  let current = categoryId;
+  for (let depth = 0; depth < 20 && current; depth++) {
+    const image = tree.imageMap.get(current);
+    if (image) return image;
+    current = tree.parentMap.get(current);
   }
-  const productCategoryIds = new Set(
-    product.allCategoriesInfo.categories.map((c) => c._id).filter(Boolean)
-  );
-  for (const config of prefixConfig) {
-    if (productCategoryIds.has(config.categoryId)) {
-      return config;
-    }
+  return "";
+}
+function buildProductUrl(urls, tree, slug, mainCategoryId) {
+  let url = urls.product;
+  url = url.replace("{slug}", slug);
+  if (url.includes("{category}")) {
+    const categorySlug = tree.slugMap.get(mainCategoryId);
+    url = url.replace("{category}", categorySlug);
   }
-  return null;
+  if (url.includes("{prefix}")) {
+    const prefixSlug = findRootCategorySlug(mainCategoryId, tree);
+    url = url.replace("{prefix}", prefixSlug);
+  }
+  return url;
+}
+function buildCategoryUrl(urls, tree, categorySlug, categoryId) {
+  if (!urls.category) return null;
+  let url = urls.category;
+  url = url.replace("{category}", categorySlug);
+  if (url.includes("{prefix}")) {
+    const prefixSlug = findRootCategorySlug(categoryId, tree);
+    if (!prefixSlug) return null;
+    url = url.replace("{prefix}", prefixSlug);
+  }
+  return url.includes("{") ? null : url;
 }
 function mapAvailabilityStatus(status) {
   switch (status) {
@@ -198,7 +280,15 @@ function isValidPrice(amount) {
 function getQuickAddType(product) {
   const optionCount = product.options?.length ?? 0;
   const hasModifiers = (product.modifiers?.length ?? 0) > 0;
-  if (hasModifiers || optionCount > 1) {
+  if (hasModifiers || optionCount > 2) {
+    return QuickAddType.NEEDS_CONFIGURATION;
+  }
+  if (optionCount === 2) {
+    const hasColor = product.options.some((o) => o.optionRenderType === "SWATCH_CHOICES");
+    const hasText = product.options.some((o) => o.optionRenderType === "TEXT_CHOICES");
+    if (hasColor && hasText) {
+      return QuickAddType.COLOR_AND_TEXT_OPTIONS;
+    }
     return QuickAddType.NEEDS_CONFIGURATION;
   }
   if (optionCount === 1) {
@@ -214,31 +304,85 @@ function mapChoiceType(choiceType) {
 }
 function mapQuickOption(option, variantsInfo) {
   if (!option) return null;
-  const optionId = option._id;
   const choices = option.choicesSettings?.choices || [];
   return {
-    _id: optionId,
+    _id: option._id || "",
     name: option.name || "",
     optionRenderType: mapOptionRenderType(option.optionRenderType),
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    choices: choices.map((choice) => {
-      return {
-        choiceId: choice.choiceId,
-        name: choice.name || "",
-        choiceType: mapChoiceType(choice.choiceType),
-        colorCode: choice.colorCode || "",
-        inStock: choice.inStock,
-        isSelected: false
-      };
-    })
+    choices: choices.map((choice) => ({
+      choiceId: choice.choiceId || "",
+      name: choice.name || "",
+      choiceType: mapChoiceType(choice.choiceType),
+      colorCode: choice.colorCode || "",
+      inStock: choice.inStock ?? true,
+      isSelected: false
+    }))
   };
 }
-const DEFAULT_PRODUCT_PAGE_PATH = "/products";
-function mapProductToCard(product, productPagePath = DEFAULT_PRODUCT_PAGE_PATH, prefixConfig) {
+function mapQuickAddOptions(product) {
+  const quickAddType = getQuickAddType(product);
+  if (quickAddType === QuickAddType.COLOR_AND_TEXT_OPTIONS) {
+    const colorOption = product.options.find((o) => o.optionRenderType === "SWATCH_CHOICES");
+    const textOption = product.options.find((o) => o.optionRenderType === "TEXT_CHOICES");
+    const quickOption = mapQuickOption(colorOption, product.variantsInfo);
+    const secondQuickOption = mapQuickOption(textOption, product.variantsInfo);
+    if (quickOption?.choices) {
+      const firstInStock = quickOption.choices.find((c) => c.inStock);
+      if (firstInStock) {
+        firstInStock.isSelected = true;
+      }
+    }
+    if (secondQuickOption?.choices) {
+      for (const choice of secondQuickOption.choices) {
+        choice.inStock = false;
+      }
+    }
+    return { quickAddType, quickOption, secondQuickOption };
+  }
+  if (quickAddType === QuickAddType.SINGLE_OPTION) {
+    return {
+      quickAddType,
+      quickOption: mapQuickOption(product.options?.[0], product.variantsInfo),
+      secondQuickOption: null
+    };
+  }
+  return { quickAddType, quickOption: null, secondQuickOption: null };
+}
+function buildVariantStockMap(product) {
+  const stockMap = {};
+  const options = product.options;
+  const variants = product.variantsInfo?.variants;
+  if (!options || options.length !== 2 || !variants) return stockMap;
+  const colorOption = options.find((o) => o.optionRenderType === "SWATCH_CHOICES");
+  const textOption = options.find((o) => o.optionRenderType === "TEXT_CHOICES");
+  if (!colorOption || !textOption) return stockMap;
+  const colorOptionId = colorOption._id || "";
+  const textOptionId = textOption._id || "";
+  const colorChoices = colorOption.choicesSettings?.choices || [];
+  const textChoices = textOption.choicesSettings?.choices || [];
+  for (const colorChoice of colorChoices) {
+    const cId = colorChoice.choiceId || "";
+    stockMap[cId] = {};
+    for (const textChoice of textChoices) {
+      const tId = textChoice.choiceId || "";
+      const variant = variants.find(
+        (v) => v.choices?.some(
+          (c) => c.optionChoiceIds?.optionId === colorOptionId && c.optionChoiceIds?.choiceId === cId
+        ) && v.choices?.some(
+          (c) => c.optionChoiceIds?.optionId === textOptionId && c.optionChoiceIds?.choiceId === tId
+        )
+      );
+      stockMap[cId][tId] = variant?.inventoryStatus?.inStock ?? false;
+    }
+  }
+  return stockMap;
+}
+function mapProductToCard(product, urls, tree) {
   const mainMedia = product.media?.main;
   const slug = product.slug || "";
-  const matchedPrefix = prefixConfig?.length ? resolveProductPrefixConfig(product, prefixConfig) : null;
-  const productUrl = slug ? matchedPrefix ? `${productPagePath}/${matchedPrefix.prefix}/${slug}` : `${productPagePath}/${slug}` : "";
+  const mainCategoryId = product.mainCategoryId || "";
+  const productUrl = buildProductUrl(urls, tree, slug, mainCategoryId);
+  const categoryName = tree.slugMap.get(mainCategoryId);
   const firstVariant = product.variantsInfo?.variants?.[0];
   const variantPrice = firstVariant?.price;
   const actualAmount = variantPrice?.actualPrice?.amount || product.actualPriceRange?.minValue?.amount || "0";
@@ -251,7 +395,7 @@ function mapProductToCard(product, productPagePath = DEFAULT_PRODUCT_PAGE_PATH,
     name: product.name || "",
     slug,
     productUrl,
-    categoryPrefix: matchedPrefix?.name ?? "",
+    categoryPrefix: categoryName,
     mainMedia: {
       url: mainMedia ? formatWixMediaUrl(mainMedia._id, mainMedia.url) : "",
       altText: mainMedia?.altText || product.name || "",
@@ -263,7 +407,6 @@ function mapProductToCard(product, productPagePath = DEFAULT_PRODUCT_PAGE_PATH,
       width: 300,
       height: 300
     },
-    // Simplified price fields
     price: actualFormattedAmount,
     strikethroughPrice: hasDiscount ? compareAtFormattedAmount : "",
     hasDiscount,
@@ -282,11 +425,13 @@ function mapProductToCard(product, productPagePath = DEFAULT_PRODUCT_PAGE_PATH,
     },
     productType: mapProductType$1(product.productType),
     isAddingToCart: false,
-    // Quick add behavior
-    quickAddType: getQuickAddType(product),
-    quickOption: getQuickAddType(product) === QuickAddType.SINGLE_OPTION ? mapQuickOption(product.options?.[0], product.variantsInfo) : null
+    ...mapQuickAddOptions(product)
   };
 }
+function needsCategoryInfo(wixStores) {
+  const template = wixStores.urls.product;
+  return template.includes("{category}") || template.includes("{prefix}");
+}
 const PRICE_BUCKET_BOUNDARIES = [
   0,
   20,
@@ -307,6 +452,31 @@ const PRICE_BUCKETS = PRICE_BUCKET_BOUNDARIES.slice(0, -1).map((from, i) => ({
   to: PRICE_BUCKET_BOUNDARIES[i + 1]
 }));
 PRICE_BUCKETS.push({ from: PRICE_BUCKET_BOUNDARIES[PRICE_BUCKET_BOUNDARIES.length - 1] });
+function getAvailableProductOptions(aggResults, customizations) {
+  const optionNamesAgg = aggResults.find((a) => a.name === "optionNames")?.values;
+  const choiceNamesAgg = aggResults.find((a) => a.name === "choiceNames")?.values;
+  if (!optionNamesAgg?.results?.length || !choiceNamesAgg?.results?.length) {
+    return [];
+  }
+  const optionNames = new Set(optionNamesAgg.results.map((e) => e.value));
+  const choiceCounts = new Map(
+    choiceNamesAgg.results.map((e) => [e.value.toLowerCase(), e.count ?? 0])
+  );
+  return customizations.filter(
+    (c) => c.customizationType === "PRODUCT_OPTION" && c.name && optionNames.has(c.name) && (c.customizationRenderType === "TEXT_CHOICES" || c.customizationRenderType === "SWATCH_CHOICES")
+  ).map((c) => ({
+    optionId: c._id || "",
+    optionName: c.name || "",
+    optionRenderType: c.customizationRenderType,
+    // Sort by product count descending (most used choices first)
+    choices: (c.choicesSettings?.choices || []).filter((ch) => ch.name && choiceCounts.has(ch.name.toLowerCase())).map((ch) => ({
+      choiceId: ch._id || "",
+      choiceName: ch.name || "",
+      colorCode: ch.colorCode || "",
+      productCount: choiceCounts.get(ch.name.toLowerCase()) ?? 0
+    })).sort((a, b) => b.productCount - a.productCount)
+  })).filter((o) => o.choices.length > 0);
+}
 const searchProducts = makeJayQuery("wixStores.searchProducts").withServices(WIX_STORES_SERVICE_MARKER).withHandler(
   async (input, wixStores) => {
     const { query, filters = {}, sortBy = "relevance", cursor, pageSize = 12 } = input;
@@ -339,6 +509,22 @@ const searchProducts = makeJayQuery("wixStores.searchProducts").withServices(WIX
           }
         });
       }
+      if (filters.optionFilters && filters.optionFilters.length > 0) {
+        for (const optFilter of filters.optionFilters) {
+          if (optFilter.choiceNames.length > 0) {
+            filterConditions.push({
+              $and: [
+                { "options.name": { $hasSome: [optFilter.optionName] } },
+                {
+                  "options.choicesSettings.choices.name": {
+                    $hasSome: optFilter.choiceNames
+                  }
+                }
+              ]
+            });
+          }
+        }
+      }
       const filter = filterConditions.length === 1 ? filterConditions[0] : { $and: filterConditions };
       const sort = [];
       switch (sortBy) {
@@ -392,23 +578,43 @@ const searchProducts = makeJayQuery("wixStores.searchProducts").withServices(WIX
           name: "max-price",
           type: "SCALAR",
           scalar: { type: "MAX" }
+        },
+        // Option names for option-based filtering
+        {
+          fieldPath: "options.name",
+          name: "optionNames",
+          type: "VALUE",
+          value: {
+            limit: 20,
+            sortType: "VALUE",
+            sortDirection: "DESC"
+          }
+        },
+        // Choice names for option-based filtering
+        {
+          fieldPath: "options.choicesSettings.choices.name",
+          name: "choiceNames",
+          type: "VALUE",
+          value: {
+            limit: 50,
+            sortType: "COUNT",
+            sortDirection: "DESC"
+          }
         }
       ];
       const searchResult = await wixStores.products.searchProducts(
         {
           filter,
-          // @ts-expect-error - Wix SDK types don't match actual API
           sort: sort.length > 0 ? sort : void 0,
           cursorPaging,
           search,
-          // @ts-expect-error - Wix SDK types don't include aggregations
           aggregations
         },
         {
           fields: [
             "CURRENCY",
             "VARIANT_OPTION_CHOICE_NAMES",
-            ...wixStores.categoryPrefixes.length > 0 ? ["ALL_CATEGORIES_INFO"] : []
+            ...needsCategoryInfo(wixStores) ? ["ALL_CATEGORIES_INFO"] : []
           ]
         }
       );
@@ -448,9 +654,11 @@ const searchProducts = makeJayQuery("wixStores.searchProducts").withServices(WIX
         };
       });
       priceRanges.push(...bucketRanges);
-      const prefixConfig = wixStores.categoryPrefixes;
+      const customizations = await wixStores.getCustomizations();
+      const optionFilters = getAvailableProductOptions(aggResults, customizations);
+      const tree = await wixStores.getCategoryTree();
       const mappedProducts = products.map(
-        (p) => mapProductToCard(p, "/products", prefixConfig)
+        (p) => mapProductToCard(p, wixStores.urls, tree)
       );
       return {
         products: mappedProducts,
@@ -461,7 +669,8 @@ const searchProducts = makeJayQuery("wixStores.searchProducts").withServices(WIX
           minBound,
           maxBound,
           ranges: priceRanges
-        }
+        },
+        optionFilters
       };
     } catch (error) {
       console.error("[wixStores.searchProducts] Search failed:", error);
@@ -476,11 +685,10 @@ const getProductBySlug = makeJayQuery("wixStores.getProductBySlug").withServices
       throw new ActionError("INVALID_INPUT", "Product slug is required");
     }
     try {
-      const prefixConfig = wixStores.categoryPrefixes;
       const fields = [
         "MEDIA_ITEMS_INFO",
         "VARIANT_OPTION_CHOICE_NAMES",
-        ...prefixConfig.length > 0 ? ["ALL_CATEGORIES_INFO"] : []
+        ...needsCategoryInfo(wixStores) ? ["ALL_CATEGORIES_INFO"] : []
       ];
       const result = await wixStores.products.getProductBySlug(slug, {
         fields: [...fields]
@@ -489,13 +697,27 @@ const getProductBySlug = makeJayQuery("wixStores.getProductBySlug").withServices
       if (!product) {
         return null;
       }
-      return mapProductToCard(product, "/products", prefixConfig);
+      const tree = await wixStores.getCategoryTree();
+      return mapProductToCard(product, wixStores.urls, tree);
     } catch (error) {
       console.error("[wixStores.getProductBySlug] Failed to get product:", error);
       return null;
     }
   }
 );
+const getVariantStock = makeJayQuery("wixStores.getVariantStock").withServices(WIX_STORES_SERVICE_MARKER).withHandler(
+  async (input, wixStores) => {
+    try {
+      const product = await wixStores.products.getProduct(input.productId, {
+        fields: ["VARIANT_OPTION_CHOICE_NAMES"]
+      });
+      return buildVariantStockMap(product);
+    } catch (error) {
+      console.error("[wixStores.getVariantStock] Failed:", error);
+      return {};
+    }
+  }
+);
 const getCategories = makeJayQuery("wixStores.getCategories").withServices(WIX_STORES_SERVICE_MARKER).withCaching({ maxAge: 3600 }).withHandler(
   async (_input, wixStores) => {
     try {
@@ -515,11 +737,193 @@ const getCategories = makeJayQuery("wixStores.getCategories").withServices(WIX_S
   }
 );
 const PAGE_SIZE = 12;
+function mapSortToAction(sort) {
+  switch (sort) {
+    case CurrentSort.priceAsc:
+      return "price_asc";
+    case CurrentSort.priceDesc:
+      return "price_desc";
+    case CurrentSort.newest:
+      return "newest";
+    case CurrentSort.nameAsc:
+      return "name_asc";
+    case CurrentSort.nameDesc:
+      return "name_desc";
+    default:
+      return "relevance";
+  }
+}
+function parseUrlFilters(url) {
+  try {
+    const params = new URL(url, "http://x").searchParams;
+    const optionSelections = /* @__PURE__ */ new Map();
+    const optParam = params.get("opt");
+    if (optParam) {
+      for (const segment of optParam.split(";")) {
+        const colonIdx = segment.indexOf(":");
+        if (colonIdx === -1)
+          continue;
+        const name = decodeURIComponent(segment.slice(0, colonIdx));
+        const choices = segment.slice(colonIdx + 1).split(",").map((c) => decodeURIComponent(c)).filter(Boolean);
+        if (choices.length > 0) {
+          optionSelections.set(name, new Set(choices));
+        }
+      }
+    }
+    return {
+      searchTerm: params.get("q") || "",
+      selectedCategorySlugs: params.get("cat")?.split(",").filter(Boolean) || [],
+      minPrice: params.has("min") ? Number(params.get("min")) : null,
+      maxPrice: params.has("max") ? Number(params.get("max")) : null,
+      inStockOnly: params.get("inStock") === "1",
+      sort: params.get("sort") || "relevance",
+      optionSelections
+    };
+  } catch {
+    return {
+      searchTerm: "",
+      selectedCategorySlugs: [],
+      minPrice: null,
+      maxPrice: null,
+      inStockOnly: false,
+      sort: "relevance",
+      optionSelections: /* @__PURE__ */ new Map()
+    };
+  }
+}
+function parseSortParam(sort) {
+  const sortMap = {
+    relevance: CurrentSort.relevance,
+    priceAsc: CurrentSort.priceAsc,
+    priceDesc: CurrentSort.priceDesc,
+    newest: CurrentSort.newest,
+    nameAsc: CurrentSort.nameAsc,
+    nameDesc: CurrentSort.nameDesc
+  };
+  return sortMap[sort] ?? CurrentSort.relevance;
+}
+function buildOptionFiltersViewState(baseOptionFilters, filteredResult, optionSelections) {
+  const filteredChoiceCounts = /* @__PURE__ */ new Map();
+  for (const opt of filteredResult.optionFilters || []) {
+    for (const ch of opt.choices) {
+      filteredChoiceCounts.set(ch.choiceName.toLowerCase(), ch.productCount);
+    }
+  }
+  return baseOptionFilters.map((opt) => ({
+    optionId: opt.optionId,
+    optionName: opt.optionName,
+    optionRenderType: opt.optionRenderType === "SWATCH_CHOICES" ? OptionRenderType$2.SWATCH_CHOICES : OptionRenderType$2.TEXT_CHOICES,
+    choices: opt.choices.map((ch) => {
+      const count = filteredChoiceCounts.get(ch.choiceName.toLowerCase()) ?? 0;
+      return {
+        choiceId: ch.choiceId,
+        choiceName: ch.choiceName,
+        colorCode: ch.colorCode,
+        productCount: count,
+        isSelected: optionSelections.get(opt.optionName)?.has(ch.choiceName) ?? false,
+        isDisabled: count === 0
+      };
+    })
+  }));
+}
+const EMPTY_CATEGORY_HEADER = {
+  name: "",
+  description: "",
+  imageUrl: "",
+  hasImage: false,
+  productCount: 0,
+  breadcrumbs: [],
+  seoData: { tags: [], settings: { preventAutoRedirect: false, keywords: [] } }
+};
+async function findCategoryBySlug(categoriesClient, slug) {
+  const result = await categoriesClient.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("slug", slug).eq("visible", true).limit(1).find();
+  return result.items?.[0] ?? null;
+}
+async function loadCategoryDetails(categoriesClient, categoryId) {
+  try {
+    return await categoriesClient.getCategory(categoryId, { appNamespace: "@wix/stores" }, { fields: ["DESCRIPTION", "BREADCRUMBS_INFO"] });
+  } catch {
+    return null;
+  }
+}
+async function buildCategoryHeader(wixStoreService, category, categoryUrlTemplate) {
+  const details = await loadCategoryDetails(wixStoreService.categories, category._id);
+  const cat = details || category;
+  const imageUrl = cat.image || "";
+  const description = cat.description || "";
+  const categoryTree = await wixStoreService.getCategoryTree();
+  const breadcrumbs = (cat.breadcrumbsInfo?.breadcrumbs || []).map((b) => ({
+    categoryId: b.categoryId,
+    name: b.categoryName,
+    slug: b.categorySlug,
+    url: categoryUrlTemplate ? buildCategoryUrl(wixStoreService.urls, categoryTree, b.categorySlug, b.categoryId) : ""
+  }));
+  const seoData = cat.seoData ? {
+    tags: (cat.seoData.tags || []).map((tag, index) => ({
+      position: index.toString().padStart(2, "0"),
+      type: tag.type || "",
+      props: Object.entries(tag.props || {}).map(([key, value]) => ({
+        key,
+        value
+      })),
+      meta: Object.entries(tag.meta || {}).map(([key, value]) => ({
+        key,
+        value
+      })),
+      children: tag.children || ""
+    })),
+    settings: {
+      preventAutoRedirect: cat.seoData.settings?.preventAutoRedirect || false,
+      keywords: (cat.seoData.settings?.keywords || []).map((k) => ({
+        term: k.term || "",
+        isMain: k.isMain || false,
+        origin: k.origin || ""
+      }))
+    }
+  } : EMPTY_CATEGORY_HEADER.seoData;
+  let header = {
+    name: cat.name || "",
+    description,
+    imageUrl,
+    hasImage: !!imageUrl,
+    productCount: cat.itemCounter || 0,
+    breadcrumbs,
+    seoData
+  };
+  if ((!description || !imageUrl) && cat.parentCategory?._id) {
+    const parent = await loadCategoryDetails(wixStoreService.categories, cat.parentCategory._id);
+    if (parent) {
+      if (!header.description && parent.description) {
+        header = { ...header, description: parent.description };
+      }
+      if (!header.imageUrl) {
+        const parentImage = parent.image || "";
+        if (parentImage) {
+          header = { ...header, imageUrl: parentImage, hasImage: true };
+        }
+      }
+    }
+  }
+  return header;
+}
 async function renderSlowlyChanging$2(props, wixStores) {
   const Pipeline = RenderPipeline.for();
-  const categoryPrefix = props.category;
-  const categoryConfig = categoryPrefix ? wixStores.categoryPrefixes.find((c) => c.prefix === categoryPrefix) : null;
-  const baseCategoryId = categoryConfig?.categoryId ?? null;
+  const subcategorySlug = props.subcategory ?? null;
+  const categorySlug = props.category ?? null;
+  const defaultCategorySlug = wixStores.defaultCategory;
+  let activeCategory = null;
+  let baseCategoryId = null;
+  if (subcategorySlug) {
+    activeCategory = await findCategoryBySlug(wixStores.categories, subcategorySlug);
+    baseCategoryId = activeCategory?._id ?? null;
+  } else if (categorySlug) {
+    activeCategory = await findCategoryBySlug(wixStores.categories, categorySlug);
+    baseCategoryId = activeCategory?._id ?? null;
+  } else if (defaultCategorySlug) {
+    activeCategory = await findCategoryBySlug(wixStores.categories, defaultCategorySlug);
+  }
+  const tree = await wixStores.getCategoryTree();
+  const categoryHeader = activeCategory ? await buildCategoryHeader(wixStores, activeCategory, wixStores.urls.category) : EMPTY_CATEGORY_HEADER;
   return Pipeline.try(async () => {
     let query = wixStores.categories.queryCategories({
       treeReference: { appNamespace: "@wix/stores" }
@@ -527,17 +931,35 @@ async function renderSlowlyChanging$2(props, wixStores) {
     if (baseCategoryId) {
       query = query.eq("parentCategory.id", baseCategoryId);
     }
-    const categoriesResult = await query.find();
-    return categoriesResult.items || [];
+    const baseCategoryIds = baseCategoryId ? [baseCategoryId] : [];
+    const [categoriesResult, productsResult] = await Promise.all([
+      query.find(),
+      searchProducts({
+        query: "",
+        filters: {
+          categoryIds: baseCategoryIds.length > 0 ? baseCategoryIds : void 0
+        },
+        pageSize: PAGE_SIZE
+      })
+    ]);
+    return {
+      categories: categoriesResult.items || [],
+      productsResult
+    };
   }).recover((error) => {
-    console.error("Failed to load categories:", error);
-    return Pipeline.ok([]);
-  }).toPhaseOutput((categories2) => {
+    console.error("Failed to load categories/products:", error);
+    return Pipeline.ok({
+      categories: [],
+      productsResult: null
+    });
+  }).toPhaseOutput(({ categories: categories2, productsResult }) => {
     const categoryInfos = categories2.map((cat) => ({
       categoryId: cat._id || "",
       categoryName: cat.name || "",
-      categorySlug: cat.slug || ""
+      categorySlug: cat.slug || "",
+      categoryUrl: buildCategoryUrl(wixStores.urls, tree, cat.slug || "", cat._id || "") ?? ""
     }));
+    const baseOptionFilters = productsResult?.optionFilters || [];
     return {
       viewState: {
         searchFields: "name,description,sku",
@@ -547,24 +969,45 @@ async function renderSlowlyChanging$2(props, wixStores) {
           categoryFilter: {
             categories: categoryInfos
           }
-        }
+        },
+        categoryHeader
       },
       carryForward: {
         searchFields: "name,description,sku",
         fuzzySearch: true,
         categories: categoryInfos,
-        baseCategoryId
+        baseCategoryId,
+        preloadedResult: productsResult,
+        baseOptionFilters
       }
     };
   });
 }
 async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
+  const urlFilters = parseUrlFilters(props.url);
+  const initialSort = parseSortParam(urlFilters.sort);
+  const initialCategoryIds = urlFilters.selectedCategorySlugs.map((slug) => slowCarryForward.categories.find((c) => c.categorySlug === slug)?.categoryId).filter(Boolean);
+  const initialOptionFilters = [];
+  for (const [optionName, choiceNames] of urlFilters.optionSelections) {
+    initialOptionFilters.push({ optionName, choiceNames: [...choiceNames] });
+  }
+  const hasActiveFilters = !!urlFilters.searchTerm || initialCategoryIds.length > 0 || urlFilters.minPrice !== null || urlFilters.maxPrice !== null || urlFilters.inStockOnly || initialSort !== CurrentSort.relevance || initialOptionFilters.length > 0;
   return Pipeline.try(async () => {
-    const baseCategoryIds = slowCarryForward.baseCategoryId ? [slowCarryForward.baseCategoryId] : [];
+    if (!hasActiveFilters && slowCarryForward.preloadedResult) {
+      return slowCarryForward.preloadedResult;
+    }
+    const baseCategoryIds = slowCarryForward.baseCategoryId ? [slowCarryForward.baseCategoryId, ...initialCategoryIds] : initialCategoryIds;
     const result = await searchProducts({
-      query: "",
-      filters: baseCategoryIds.length > 0 ? { categoryIds: baseCategoryIds } : void 0,
+      query: urlFilters.searchTerm || "",
+      filters: {
+        categoryIds: baseCategoryIds.length > 0 ? baseCategoryIds : void 0,
+        minPrice: urlFilters.minPrice ?? void 0,
+        maxPrice: urlFilters.maxPrice ?? void 0,
+        inStockOnly: urlFilters.inStockOnly || void 0,
+        optionFilters: initialOptionFilters.length > 0 ? initialOptionFilters : void 0
+      },
+      sortBy: initialSort !== CurrentSort.relevance ? mapSortToAction(initialSort) : void 0,
       pageSize: PAGE_SIZE
     });
     return result;
@@ -582,13 +1025,14 @@ async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
           {
             rangeId: "all",
             label: "Show all",
-            minValue: null,
-            maxValue: null,
+            minValue: 0,
+            maxValue: 1e3,
             productCount: 0,
             isSelected: true
           }
         ]
-      }
+      },
+      optionFilters: []
     });
   }).toPhaseOutput((result) => {
     const priceAgg = result.priceAggregation || {
@@ -598,8 +1042,8 @@ async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
         {
           rangeId: "all",
           label: "Show all",
-          minValue: null,
-          maxValue: null,
+          minValue: 0,
+          maxValue: 1e3,
           productCount: result.totalCount,
           isSelected: true
         }
@@ -607,33 +1051,37 @@ async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
     };
     return {
       viewState: {
-        searchExpression: "",
+        searchExpression: urlFilters.searchTerm,
         isSearching: false,
-        hasSearched: false,
+        hasSearched: !!urlFilters.searchTerm,
         searchResults: result.products,
         resultCount: result.products.length,
         hasResults: result.products.length > 0,
         hasSuggestions: false,
         suggestions: [],
         filters: {
-          inStockOnly: false,
+          inStockOnly: urlFilters.inStockOnly,
           priceRange: {
-            // Initialize sliders to full range (bounds)
-            minPrice: priceAgg.minBound,
-            maxPrice: priceAgg.maxBound,
+            minPrice: urlFilters.minPrice ?? priceAgg.minBound,
+            maxPrice: urlFilters.maxPrice ?? priceAgg.maxBound,
             minBound: priceAgg.minBound,
             maxBound: priceAgg.maxBound,
-            ranges: priceAgg.ranges
+            ranges: priceAgg.ranges.map((r) => ({
+              ...r,
+              minValue: r.minValue ?? 0,
+              maxValue: r.maxValue ?? 0
+            }))
           },
           categoryFilter: {
             categories: slowCarryForward.categories.map((cat) => ({
               categoryId: cat.categoryId,
-              isSelected: false
+              isSelected: initialCategoryIds.includes(cat.categoryId)
             }))
-          }
+          },
+          optionFilters: buildOptionFiltersViewState(slowCarryForward.baseOptionFilters, result, urlFilters.optionSelections)
         },
         sortBy: {
-          currentSort: CurrentSort.relevance
+          currentSort: initialSort
         },
         hasMore: result.hasMore,
         loadedCount: result.products.length,
@@ -643,12 +1091,35 @@ async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
         searchFields: slowCarryForward.searchFields,
         fuzzySearch: slowCarryForward.fuzzySearch,
         categories: slowCarryForward.categories,
-        baseCategoryId: slowCarryForward.baseCategoryId
+        baseCategoryId: slowCarryForward.baseCategoryId,
+        baseOptionFilters: slowCarryForward.baseOptionFilters
       }
     };
   });
 }
-const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+async function* loadSearchParams([wixStores]) {
+  try {
+    const result = await wixStores.categories.queryCategories({
+      treeReference: { appNamespace: "@wix/stores" }
+    }).eq("visible", true).limit(100).find();
+    const categories2 = result.items || [];
+    yield categories2.filter((cat) => cat.slug && (cat.itemCounter ?? 0) > 0).map((cat) => ({
+      category: cat.slug
+    }));
+    for (const cat of categories2) {
+      if (!cat.slug || !cat.parentCategory?._id || (cat.itemCounter ?? 0) === 0)
+        continue;
+      const parent = categories2.find((c) => c._id === cat.parentCategory?._id);
+      if (parent?.slug) {
+        yield [{ category: parent.slug, subcategory: cat.slug }];
+      }
+    }
+  } catch (error) {
+    console.error("Failed to load category params:", error);
+    yield [];
+  }
+}
+const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
 var ProductType = /* @__PURE__ */ ((ProductType2) => {
   ProductType2[ProductType2["PHYSICAL"] = 0] = "PHYSICAL";
   ProductType2[ProductType2["DIGITAL"] = 1] = "DIGITAL";
@@ -691,28 +1162,21 @@ var MediaType = /* @__PURE__ */ ((MediaType2) => {
   return MediaType2;
 })(MediaType || {});
 async function* loadProductParams([wixStores]) {
-  const prefixConfig = wixStores.categoryPrefixes;
-  const hasPrefixes = prefixConfig.length > 0;
-  const fields = hasPrefixes ? ["ALL_CATEGORIES_INFO"] : [];
+  const template = wixStores.urls.product;
+  const needsCategories = template.includes("{category}") || template.includes("{prefix}");
+  const fields = needsCategories ? ["ALL_CATEGORIES_INFO"] : [];
   try {
     let result = await wixStores.products.queryProducts({ fields: [...fields] }).find();
-    yield result.items.map((product) => mapProductToParams(product, prefixConfig));
+    yield result.items.map((product) => ({ slug: product.slug ?? "" })).filter((p) => p.slug);
     while (result.hasNext()) {
       result = await result.next();
-      yield result.items.map((product) => mapProductToParams(product, prefixConfig));
+      yield result.items.map((product) => ({ slug: product.slug ?? "" })).filter((p) => p.slug);
     }
   } catch (error) {
     console.error("Failed to load product slugs:", error);
     yield [];
   }
 }
-function mapProductToParams(product, prefixConfig) {
-  const prefix = resolveProductPrefix(product, prefixConfig);
-  return {
-    slug: product.slug ?? "",
-    ...prefix ? { category: prefix } : {}
-  };
-}
 function mapProductType(productType) {
   return productType === "DIGITAL" ? ProductType.DIGITAL : ProductType.PHYSICAL;
 }
@@ -848,8 +1312,8 @@ function mapVariants(variantsInfo) {
 }
 async function renderSlowlyChanging$1(props, wixStores) {
   const Pipeline = RenderPipeline.for();
-  const prefixConfig = wixStores.categoryPrefixes;
-  const hasPrefixes = prefixConfig.length > 0;
+  const template = wixStores.urls.product;
+  const needsCategories = template.includes("{category}") || template.includes("{prefix}");
   return Pipeline.try(async () => {
     const fields = [
       "INFO_SECTION",
@@ -857,17 +1321,11 @@ async function renderSlowlyChanging$1(props, wixStores) {
       "MEDIA_ITEMS_INFO",
       "PLAIN_DESCRIPTION",
       "CURRENCY",
-      ...hasPrefixes ? ["ALL_CATEGORIES_INFO"] : []
+      ...needsCategories ? ["ALL_CATEGORIES_INFO"] : []
     ];
     const response = await wixStores.products.getProductBySlug(props.slug, {
       fields: [...fields]
     });
-    if (props.category && hasPrefixes) {
-      const actualPrefix = resolveProductPrefix(response.product, prefixConfig);
-      if (actualPrefix !== props.category) {
-        throw new Error("Category prefix mismatch");
-      }
-    }
     return response;
   }).recover((error) => {
     console.log("product page error", error);
@@ -960,37 +1418,38 @@ const categoryList = makeJayStackComponent().withProps().withServices(WIX_STORES
 const WIX_STORES_CONTEXT = createJayContext();
 function loadWixStoresConfig() {
   const configPath = path.join(process.cwd(), "config", ".wix-stores.yaml");
+  const defaults = {
+    urls: { product: "/products/{slug}", category: null },
+    defaultCategory: null
+  };
   if (!fs.existsSync(configPath)) {
-    return { categoryPrefixes: [] };
+    return defaults;
   }
   const fileContents = fs.readFileSync(configPath, "utf8");
   const raw = yaml.load(fileContents);
   if (!raw) {
-    return { categoryPrefixes: [] };
+    return defaults;
   }
-  const prefixes = [];
-  if (Array.isArray(raw.categoryPrefixes)) {
-    for (const entry of raw.categoryPrefixes) {
-      if (typeof entry.categoryId === "string" && typeof entry.prefix === "string") {
-        prefixes.push({
-          categoryId: entry.categoryId.trim(),
-          prefix: entry.prefix.trim(),
-          name: typeof entry.name === "string" ? entry.name.trim() : entry.prefix.trim()
-        });
-      }
-    }
-  }
-  return { categoryPrefixes: prefixes };
+  const urls = raw.urls;
+  return {
+    urls: {
+      product: typeof urls?.product === "string" ? urls.product : defaults.urls.product,
+      category: typeof urls?.category === "string" ? urls.category : null
+    },
+    defaultCategory: typeof raw.defaultCategory === "string" ? raw.defaultCategory : null
+  };
 }
 const init = makeJayInit().withServer(async () => {
   console.log("[wix-stores] Initializing Wix Stores service...");
   const wixClient = getService(WIX_CLIENT_SERVICE);
   const storesConfig = loadWixStoresConfig();
   provideWixStoresService(wixClient, {
-    categoryPrefixes: storesConfig.categoryPrefixes
+    urls: storesConfig.urls,
+    defaultCategory: storesConfig.defaultCategory
   });
-  if (storesConfig.categoryPrefixes.length > 0) {
-    console.log(`[wix-stores] Category prefixes configured: ${storesConfig.categoryPrefixes.map((p) => p.prefix).join(", ")}`);
+  console.log(`[wix-stores] URL templates: product="${storesConfig.urls.product}", category="${storesConfig.urls.category ?? "none"}"`);
+  if (storesConfig.defaultCategory) {
+    console.log(`[wix-stores] Default category: ${storesConfig.defaultCategory}`);
   }
   console.log("[wix-stores] Server initialization complete");
   return {
@@ -1001,20 +1460,22 @@ const init = makeJayInit().withServer(async () => {
 const CONFIG_FILE_NAME = ".wix-stores.yaml";
 const CONFIG_TEMPLATE = `# Wix Stores Configuration
 #
-# Category Prefixes (optional):
-# Maps root Wix categories to URL prefix slugs.
-# Products under a root category get URLs like /products/{prefix}/{product-slug}
-# Each prefix gets its own search/listing page and product page templates.
+# URL templates for link generation.
+# Placeholders: {slug} (product), {category} (sub-category), {prefix} (root category)
 #
-# To find category IDs, use: jay-stack action wix-stores/getCategories
+# urls:
+#   product: "/products/{slug}"                              # simple (default)
+#   product: "/products/{category}/{slug}"                   # with categories
+#   product: "/products/{prefix}/{category}/{slug}"          # with prefixes + categories
+#   category: "/products/{prefix}/{category}"                # category deep-link pages
 #
-# categoryPrefixes:
-#   - categoryId: "<root-category-id>"
-#     prefix: "<url-prefix>"
-#     name: "<display-name>"
-#   - categoryId: "<another-root-category-id>"
-#     prefix: "<another-url-prefix>"
-#     name: "<another-display-name>"
+# Fallback category for pages without category context:
+# defaultCategory: "all-products"
+#
+# To see available categories: jay-stack setup wix-stores (generates category tree reference)
+
+urls:
+  product: "/products/{slug}"
 `;
 async function setupWixStores(ctx) {
   if (ctx.initError) {
@@ -1041,8 +1502,7 @@ async function setupWixStores(ctx) {
     configCreated.push(`config/${CONFIG_FILE_NAME}`);
   }
   const service = getService(WIX_STORES_SERVICE_MARKER);
-  const prefixCount = service.categoryPrefixes.length;
-  const message = prefixCount > 0 ? `Wix Stores configured with ${prefixCount} category prefix(es): ${service.categoryPrefixes.map((p) => p.prefix).join(", ")}` : "Wix Stores service verified";
+  const message = `Wix Stores configured (product URL: ${service.urls.product})`;
   return {
     status: "configured",
     message,
@@ -1091,22 +1551,13 @@ async function generateWixStoresReferences(ctx) {
       roots.push(node);
     }
   }
-  const prefixConfig = storesService.categoryPrefixes;
-  const configuredPrefixes = prefixConfig.map((p) => ({
-    categoryId: p.categoryId,
-    prefix: p.prefix,
-    name: p.name,
-    categoryName: nodeMap.get(p.categoryId)?.name ?? "unknown"
-  }));
   const categoriesPath = path.join(ctx.referencesDir, "categories.yaml");
   fs.writeFileSync(
     categoriesPath,
     yaml.dump(
       {
-        _generated: (/* @__PURE__ */ new Date()).toISOString(),
-        _description: "Wix Stores category tree for agent discovery. Shows category hierarchy, IDs, product counts, and configured URL prefixes.",
+        _description: "Wix Stores category tree for agent discovery. Shows category hierarchy, IDs, slugs, product counts, and parent-child relationships.",
         totalCategories: allCategories.length,
-        configuredPrefixes: configuredPrefixes.length > 0 ? configuredPrefixes : void 0,
         categoryTree: roots
       },
       { indent: 2, lineWidth: 120, noRefs: true }
@@ -1123,12 +1574,18 @@ export {
   WIX_CART_SERVICE,
   WIX_STORES_CONTEXT,
   WIX_STORES_SERVICE_MARKER,
+  buildCategoryUrl,
+  buildProductUrl,
   cartIndicator,
   cartPage,
   categoryList,
+  findCategoryImage,
+  findRootCategoryId,
+  findRootCategorySlug,
   generateWixStoresReferences,
   getCategories,
   getProductBySlug,
+  getVariantStock,
   init,
   productPage,
   productSearch,