@jay-framework/wix-stores 0.16.3 → 0.16.5

package/dist/index.d.ts

@@ -420,6 +420,40 @@ declare function buildCategoryUrl(urls: UrlTemplates, tree: CategoryTree, catego
 /** Variant stock map: colorChoiceId -> textChoiceId -> inStock */
 type VariantStockMap = Record<string, Record<string, boolean>>;
 
+/**
+ * Data Extension Schema → Contract Tag Utilities
+ *
+ * Converts Wix Data Extension JSON Schema properties to jay-contract YAML tags.
+ * Used to materialize the product-page contract with site-specific custom fields.
+ *
+ * Design Log #16
+ */
+/** A single property from the JSON Schema returned by listDataExtensionSchemas */
+interface JsonSchemaProperty {
+    type: string;
+    items?: JsonSchemaProperty & {
+        properties?: Record<string, JsonSchemaProperty>;
+    };
+    properties?: Record<string, JsonSchemaProperty>;
+    maxLength?: number;
+    maxItems?: number;
+    /** Wix extension metadata — ignored for contract generation */
+    'x-wix-permissions'?: unknown;
+    'x-wix-created-date'?: string;
+    'x-wix-filterable'?: boolean;
+}
+/** Schema returned by listDataExtensionSchemas for a single namespace */
+interface DataExtensionSchema {
+    fqdn?: string | null;
+    namespace?: string | null;
+    jsonSchema?: {
+        properties?: Record<string, JsonSchemaProperty>;
+        additionalProperties?: boolean;
+    } | null;
+    _id?: string | null;
+    revision?: string | null;
+}
+
 interface WixStoresService {
     products: BuildDescriptors<typeof productsV3, {}>;
     categories: BuildDescriptors<typeof categories, {}>;
@@ -433,6 +467,8 @@ interface WixStoresService {
     getCategoryTree(): Promise<CategoryTree>;
     /** Get cached product customizations (options with choices). Lazily loaded. */
     getCustomizations(): Promise<Customization[]>;
+    /** Get cached data extension schemas for products. Lazily loaded. */
+    getDataExtensionSchemas(): Promise<DataExtensionSchema[]>;
 }
 /**
  * Server service marker for Wix Stores.
@@ -982,4 +1018,19 @@ declare function setupWixStores(ctx: PluginSetupContext): Promise<PluginSetupRes
  */
 declare function generateWixStoresReferences(ctx: PluginReferencesContext): Promise<PluginReferencesResult>;
 
-export { type CategoryListParams, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, productSearch, provideWixStoresService, searchProducts, setupWixStores };
+/**
+ * Product Page Contract Generator
+ *
+ * Materializes the product-page contract by extending the base static contract
+ * with site-specific data extension fields from the Wix Data Extension Schema API.
+ *
+ * Design Log #16
+ */
+/**
+ * Generator for the product-page contract.
+ * Takes the base contract YAML and appends an extendedFields sub-contract
+ * generated from the site's data extension schemas.
+ */
+declare const generator: _jay_framework_fullstack_component.DynamicContractGenerator<[WixStoresService]>;
+
+export { type CategoryListParams, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, provideWixStoresService, searchProducts, setupWixStores };

package/dist/index.js

@@ -1,8 +1,9 @@
 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 { createJayService, makeJayQuery, ActionError, makeJayStackComponent, RenderPipeline, makeJayInit, makeContractGenerator } from "@jay-framework/fullstack-component";
 import { customizationsV3, inventoryItemsV3, productsV3 } from "@wix/stores";
 import { categories } from "@wix/categories";
 import { registerService, getService } from "@jay-framework/stack-server-runtime";
+import { schemas } from "@wix/data-extension-schema";
 import { createJayContext } from "@jay-framework/runtime";
 import "@jay-framework/component";
 import { WIX_CLIENT_SERVICE } from "@jay-framework/wix-server-client";
@@ -57,6 +58,7 @@ const WIX_STORES_SERVICE_MARKER = createJayService("Wix Store Service");
 function provideWixStoresService(wixClient, options) {
   let cachedTree = null;
   let cachedCustomizations = null;
+  let cachedExtensionSchemas = null;
   const categoriesClient = getCategoriesClient(wixClient);
   const customizationsClient = getCustomizationsV3Client(wixClient);
   const service = {
@@ -110,6 +112,27 @@ function provideWixStoresService(wixClient, options) {
         cachedCustomizations = [];
       }
       return cachedCustomizations;
+    },
+    async getDataExtensionSchemas() {
+      if (cachedExtensionSchemas) return cachedExtensionSchemas;
+      try {
+        const client = wixClient.use(schemas);
+        const result = await client.listDataExtensionSchemas(
+          "wix.stores.catalog.v3.product"
+        );
+        cachedExtensionSchemas = result?.dataExtensionSchemas ?? [];
+        const fieldCount = cachedExtensionSchemas.reduce(
+          (n, s) => n + Object.keys(s.jsonSchema?.properties ?? {}).length,
+          0
+        );
+        console.log(
+          `[wix-stores] Loaded ${cachedExtensionSchemas.length} data extension schema(s), ${fieldCount} field(s)`
+        );
+      } catch (error) {
+        console.error("[wix-stores] Failed to load data extension schemas:", error);
+        cachedExtensionSchemas = [];
+      }
+      return cachedExtensionSchemas;
     }
   };
   registerService(WIX_STORES_SERVICE_MARKER, service);
@@ -1194,6 +1217,18 @@ var MediaType = /* @__PURE__ */ ((MediaType2) => {
   MediaType2[MediaType2["VIDEO"] = 1] = "VIDEO";
   return MediaType2;
 })(MediaType || {});
+function mapExtendedFields(product) {
+  const raw = product.extendedFields?.namespaces?.["_user_fields"] ?? {};
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (Array.isArray(value)) {
+      result[key] = value.map((item, i) => typeof item === "object" && item !== null ? { ...item, _index: i } : { value: item, _index: i });
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
 async function* loadProductParams([wixStores]) {
   const template = wixStores.urls.product;
   const needsPrefix = template.includes("{prefix}");
@@ -1402,7 +1437,8 @@ async function renderSlowlyChanging$1(props, wixStores) {
         productType: mapProductType(productType),
         options: mapOptionsToSlowVS(options),
         infoSections: mapInfoSections(infoSections),
-        modifiers: mapModifiersToSlowVS(modifiers)
+        modifiers: mapModifiersToSlowVS(modifiers),
+        extendedFields: mapExtendedFields(product)
       },
       headTags: mapSeoHeadTags(seoData),
       carryForward: {
@@ -1665,11 +1701,272 @@ async function generateWixStoresReferences(ctx) {
     ),
     "utf-8"
   );
+  let extensionFieldCount = 0;
+  try {
+    const extensionSchemas = await storesService.getDataExtensionSchemas();
+    const userFieldsSchema = extensionSchemas.find(
+      (s) => s.namespace === "_user_fields"
+    );
+    const properties = userFieldsSchema?.jsonSchema?.properties;
+    if (properties && Object.keys(properties).length > 0) {
+      extensionFieldCount = Object.keys(properties).length;
+      const extensionPath = path.join(ctx.referencesDir, "data-extension-fields.yaml");
+      fs.writeFileSync(
+        extensionPath,
+        yaml.dump(
+          {
+            _description: "Product data extension fields (custom fields defined in Wix dashboard).",
+            fqdn: "wix.stores.v3.product",
+            namespace: "_user_fields",
+            fieldCount: extensionFieldCount,
+            fields: Object.fromEntries(
+              Object.entries(properties).map(([key, prop]) => [
+                key,
+                { type: prop.type }
+              ])
+            )
+          },
+          { indent: 2, lineWidth: 120, noRefs: true }
+        ),
+        "utf-8"
+      );
+    }
+  } catch (error) {
+    console.error("[wix-stores] Failed to fetch data extension schemas:", error);
+  }
+  const referencesCreated = [`agent-kit/references/${ctx.pluginName}/categories.yaml`];
+  if (extensionFieldCount > 0) {
+    referencesCreated.push(`agent-kit/references/${ctx.pluginName}/data-extension-fields.yaml`);
+  }
   return {
-    referencesCreated: [`agent-kit/references/${ctx.pluginName}/categories.yaml`],
-    message: `${allCategories.length} categories (${roots.length} root)`
+    referencesCreated,
+    message: `${allCategories.length} categories (${roots.length} root), ${extensionFieldCount} extension fields`
   };
 }
+function jsonTypeToContractType(type) {
+  switch (type) {
+    case "boolean":
+      return "boolean";
+    case "number":
+    case "integer":
+      return "number";
+    default:
+      return "string";
+  }
+}
+function dataTag(key, type, indent) {
+  const prefix = " ".repeat(indent);
+  return `${prefix}- {tag: ${key}, type: data, dataType: ${type}}`;
+}
+function primitiveArraySubContract(key, itemType, indent) {
+  const prefix = " ".repeat(indent);
+  const innerIndent = indent + 2;
+  const indexTag = dataTag("_index", "number", innerIndent);
+  const valueTag = dataTag("value", jsonTypeToContractType(itemType), innerIndent);
+  return `${prefix}- tag: ${key}
+${prefix}  type: sub-contract
+${prefix}  repeated: true
+${prefix}  trackBy: _index
+${prefix}  description: ${key}
+${prefix}  tags:
+${indexTag}
+${valueTag}`;
+}
+function objectSubContract(key, properties, repeated, indent) {
+  const prefix = " ".repeat(indent);
+  const innerTags = jsonSchemaToContractTags(properties, indent + 2);
+  if (repeated) {
+    const indexTag = dataTag("_index", "number", indent + 2);
+    return `${prefix}- tag: ${key}
+${prefix}  type: sub-contract
+${prefix}  repeated: true
+${prefix}  trackBy: _index
+${prefix}  description: ${key}
+${prefix}  tags:
+${indexTag}
+${innerTags.join("\n")}`;
+  }
+  return `${prefix}- tag: ${key}
+${prefix}  type: sub-contract
+${prefix}  description: ${key}
+${prefix}  tags:
+${innerTags.join("\n")}`;
+}
+function jsonSchemaToContractTags(properties, indent = 4) {
+  const tags = [];
+  for (const [key, prop] of Object.entries(properties)) {
+    switch (prop.type) {
+      case "string":
+      case "boolean":
+      case "number":
+      case "integer":
+        tags.push(dataTag(key, jsonTypeToContractType(prop.type), indent));
+        break;
+      case "array": {
+        const items = prop.items;
+        if (!items) {
+          tags.push(dataTag(key, "string", indent));
+        } else if (items.type === "object" && items.properties) {
+          tags.push(objectSubContract(key, items.properties, true, indent));
+        } else {
+          tags.push(primitiveArraySubContract(key, items.type || "string", indent));
+        }
+        break;
+      }
+      case "object":
+        if (prop.properties) {
+          tags.push(objectSubContract(key, prop.properties, false, indent));
+        } else {
+          tags.push(dataTag(key, "string", indent));
+        }
+        break;
+      default:
+        tags.push(dataTag(key, "string", indent));
+        break;
+    }
+  }
+  return tags;
+}
+function buildExtendedFieldsSubContract(schemas2, indent = 2) {
+  const userFieldsSchema = schemas2.find((s) => s.namespace === "_user_fields");
+  const properties = userFieldsSchema?.jsonSchema?.properties;
+  if (!properties || Object.keys(properties).length === 0) {
+    return null;
+  }
+  const prefix = " ".repeat(indent);
+  const innerTags = jsonSchemaToContractTags(properties, indent + 2);
+  return `${prefix}- tag: extendedFields
+${prefix}  type: sub-contract
+${prefix}  description: Custom product fields from data extension schema
+${prefix}  tags:
+${innerTags.join("\n")}`;
+}
+const BASE_CONTRACT_YAML = `name: product-page
+description: Full product detail page with variants, options, media gallery, and add-to-cart. Use for individual product pages.
+params:
+  slug: string
+  prefix: string?
+  category: string?
+tags:
+  - {tag: _id, type: data, dataType: string, description: Product GUID}
+  - {tag: productName, type: data, dataType: string, required: true, description: Product name}
+
+  - tag: mediaGallery
+    type: sub-contract
+    phase: fast+interactive
+    link: "@jay-framework/wix-stores/media-gallery"
+
+  - {tag: description, type: data, dataType: string, description: Product description}
+  - {tag: brand, type: data, dataType: string, description: Brand name}
+  - {tag: ribbon, type: data, dataType: string, description: "Ribbon text (e.g., \\"New\\", \\"Sale\\")"}
+  - {tag: productType, type: variant, dataType: "enum (PHYSICAL | DIGITAL)", description: Product type }
+
+  - {tag: sku, type: data, dataType: string, phase: fast+interactive, description: Product SKU, or chosen variant SKU}
+  - {tag: price, type: data, dataType: string, phase: fast+interactive, description: The product or variant price}
+  - {tag: strikethroughPrice, type: data, dataType: string, phase: fast+interactive, description: A Strikethrough product price for sales}
+  - {tag: pricePerUnit, type: data, dataType: string, phase: fast+interactive, description: formatted price per unit, if used}
+  - {tag: stockStatus, type: variant, dataType: "enum (OUT_OF_STOCK | IN_STOCK)", phase: fast+interactive, description: indicator if the product or current variant are in stock }
+
+  - tag: quantity
+    type: sub-contract
+    description: Quantity selection controls
+    tags:
+      - {tag: decrementButton, type: interactive, elementType: HTMLButtonElement, description: Button to decrease quantity}
+      - {tag: incrementButton, type: interactive, elementType: HTMLButtonElement, description: Button to increase quantity}
+      - {tag: quantity, type: [data, interactive], dataType: number, elementType: HTMLInputElement, description: Selected Quantity and Direct quantity input field}
+
+  # Call to action
+  - {tag: addToCartButton, type: interactive, elementType: HTMLButtonElement, required: true, description: Add product to cart button}
+  - {tag: buyNowButton, type: interactive, elementType: HTMLButtonElement, required: true, description: Buy now button}
+  - {tag: actionsEnabled, type: variant, dataType: boolean, phase: fast+interactive, description: should the add to cart and buy now buttons be enabled}
+  - {tag: isAddingToCart, type: variant, dataType: boolean, phase: fast+interactive, description: Whether an add-to-cart request is currently in progress}
+
+  - tag: options
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Product customization options that generate variants
+    tags:
+      - {tag: _id, type: data, dataType: string, description: "Option GUID (customization ID)"}
+      - {tag: name, type: data, dataType: string, description: "Option name (e.g., \\"Color\\", \\"Size\\")"}
+      - {tag: optionRenderType, type: variant, dataType: "enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES)", description: How the option should be rendered}
+      - {tag: textChoice, type: interactive, elementType: HTMLSelectElement, description: dropdown for text choice}
+      - {tag: textChoiceSelection, type: data, dataType: string, phase: fast+interactive, description: the selected text option}
+
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        description: Available choices for this option
+        tags:
+          - {tag: choiceId, type: data, dataType: string, description: Choice GUID}
+          - {tag: choiceType, type: variant, dataType: "enum (CHOICE_TEXT | ONE_COLOR)", description: Type of choice}
+          - {tag: name, type: data, dataType: string, description: "Choice name (e.g., \\"Red\\", \\"Large\\")"}
+          - {tag: colorCode, type: data, dataType: string, description: Color code in HEX format (for color choices)}
+          - {tag: inStock, type: data, dataType: boolean, description: Whether at least one variant with this choice is in stock}
+          - {tag: isSelected, type: variant, dataType: boolean, phase: fast+interactive, description: Whether this choice is currently selected (UI state)}
+          - {tag: choiceButton, type: interactive, elementType: HTMLButtonElement, description: Button to select this choice}
+
+  # Additional info sections (from Wix Stores API)
+  - tag: infoSections
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Additional product information sections
+    tags:
+      - {tag: _id, type: data, dataType: string, description: Info section GUID}
+      - {tag: title, type: data, dataType: string, description: Info section title}
+      - {tag: plainDescription, type: data, dataType: string, description: Info section description in HTML}
+
+  - tag: modifiers
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Product customization options that do not generate variants
+    tags:
+      - {tag: _id, type: data, dataType: string, description: "modifier id"}
+      - {tag: name, type: data, dataType: string, description: "modifier name (e.g., \\"Color\\", \\"Size\\")"}
+      - {tag: modifierType, type: variant, dataType: "enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES | FREE_TEXT)", description: What type of modifier to use?}
+      - {tag: textModifier, type: interactive, elementType: HTMLSelectElement, description: dropdown for text modifier}
+      - {tag: textModifierSelection, type: data, dataType: string, phase: fast+interactive, description: the selected text modifier}
+      - {tag: textInput, type: interactive, elementType: HTMLInputElement | HTMLAreaElement, description: text input for free text}
+      - {tag: textInputLength, type: data, dataType: number, description: the limit on the length of free text}
+      - {tag: textInputRequired, type: data, dataType: boolean, description: Is the free text input required?}
+
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        description: Available choices for this Modifier
+        tags:
+          - {tag: choiceId, type: data, dataType: string, description: Choice GUID}
+          - {tag: choiceType, type: variant, dataType: "enum (CHOICE_TEXT | ONE_COLOR)", description: Type of choice}
+          - {tag: name, type: data, dataType: string, description: "Choice name (e.g., \\"Red\\", \\"Large\\")"}
+          - {tag: colorCode, type: data, dataType: string, description: Color code in HEX format (for color choices)}
+          - {tag: isSelected, type: variant, dataType: boolean, phase: fast+interactive, description: Whether this choice is currently selected (UI state)}
+          - {tag: choiceButton, type: interactive, elementType: HTMLButtonElement, description: Button to select this choice}
+
+  # SEO data is injected into <head> via headTags (Design Log #127), not part of the contract view state.`;
+const generator = makeContractGenerator().withServices(WIX_STORES_SERVICE_MARKER).generateWith(async (wixStoresService) => {
+  const schemas2 = await wixStoresService.getDataExtensionSchemas();
+  const extendedFieldsBlock = buildExtendedFieldsSubContract(schemas2);
+  let yaml2 = BASE_CONTRACT_YAML;
+  if (extendedFieldsBlock) {
+    yaml2 = yaml2 + "\n\n" + extendedFieldsBlock;
+  }
+  return [
+    {
+      yaml: yaml2,
+      description: "Product page with data extension fields",
+      metadata: {
+        extendedFieldCount: schemas2.reduce(
+          (count, s) => count + Object.keys(s.jsonSchema?.properties ?? {}).length,
+          0
+        )
+      }
+    }
+  ];
+});
 export {
   WIX_CART_CONTEXT,
   WIX_CART_SERVICE,
@@ -1689,6 +1986,7 @@ export {
   getVariantStock,
   init,
   productPage,
+  generator as productPageContractGenerator,
   productSearch,
   provideWixCartContext,
   provideWixCartService,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "type": "module",
   "description": "Wix Stores API client for Jay Framework",
   "license": "Apache-2.0",
@@ -14,6 +14,8 @@
     "./client": "./dist/index.client.js",
     "./plugin.yaml": "./plugin.yaml",
     "./product-page.jay-contract": "./dist/contracts/product-page.jay-contract",
+    "./media.jay-contract": "./dist/contracts/media.jay-contract",
+    "./media-gallery.jay-contract": "./dist/contracts/media-gallery.jay-contract",
     "./product-search.jay-contract": "./dist/contracts/product-search.jay-contract",
     "./category-list.jay-contract": "./dist/contracts/category-list.jay-contract",
     "./search-products.jay-action": "./dist/actions/search-products.jay-action",
@@ -35,17 +37,18 @@
     "test": ":"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.16.3",
-    "@jay-framework/fullstack-component": "^0.16.3",
-    "@jay-framework/reactive": "^0.16.3",
-    "@jay-framework/runtime": "^0.16.3",
-    "@jay-framework/secure": "^0.16.3",
-    "@jay-framework/stack-client-runtime": "^0.16.3",
-    "@jay-framework/stack-server-runtime": "^0.16.3",
-    "@jay-framework/wix-cart": "^0.16.3",
-    "@jay-framework/wix-server-client": "^0.16.3",
-    "@jay-framework/wix-utils": "^0.16.3",
+    "@jay-framework/component": "^0.16.5",
+    "@jay-framework/fullstack-component": "^0.16.5",
+    "@jay-framework/reactive": "^0.16.5",
+    "@jay-framework/runtime": "^0.16.5",
+    "@jay-framework/secure": "^0.16.5",
+    "@jay-framework/stack-client-runtime": "^0.16.5",
+    "@jay-framework/stack-server-runtime": "^0.16.5",
+    "@jay-framework/wix-cart": "^0.16.5",
+    "@jay-framework/wix-server-client": "^0.16.5",
+    "@jay-framework/wix-utils": "^0.16.5",
     "@wix/categories": "^1.0.185",
+    "@wix/data-extension-schema": "^1.0.221",
     "@wix/sdk": "^1.21.5",
     "@wix/sdk-runtime": "^1.0.11",
     "@wix/stores": "^1.0.742",
@@ -55,10 +58,10 @@
     "@babel/core": "^7.23.7",
     "@babel/preset-env": "^7.23.8",
     "@babel/preset-typescript": "^7.23.3",
-    "@jay-framework/compiler-jay-stack": "^0.16.3",
-    "@jay-framework/jay-cli": "^0.16.3",
-    "@jay-framework/jay-stack-cli": "^0.16.3",
-    "@jay-framework/vite-plugin": "^0.16.3",
+    "@jay-framework/compiler-jay-stack": "^0.16.5",
+    "@jay-framework/jay-cli": "^0.16.5",
+    "@jay-framework/jay-stack-cli": "^0.16.5",
+    "@jay-framework/vite-plugin": "^0.16.5",
     "nodemon": "^3.0.3",
     "rimraf": "^5.0.5",
     "tslib": "^2.6.2",

package/plugin.yaml

@@ -2,10 +2,6 @@ name: wix-stores
 # No module field for NPM packages - uses package main export by default
 
 contracts:
-  - name: product-page
-    contract: product-page.jay-contract # Export subpath (matches package.json exports)
-    component: productPage # Exported member name from index.ts
-    description: Complete headless product page with server-side rendering and client interactivity
   - name: product-search
     contract: product-search.jay-contract
     component: productSearch
@@ -16,6 +12,13 @@ contracts:
     component: categoryList
     description: Category list listing the categories
 
+# Dynamic contracts — materialized at setup time from site-specific data
+dynamic_contracts:
+  # Product page — base contract extended with data extension fields
+  - prefix: 'product-page'
+    component: productPage
+    generator: productPageContractGenerator
+
 # Server actions (named exports from main module)
 actions:
   - name: searchProducts