@jay-framework/wix-stores 0.15.0

package/README.md

@@ -0,0 +1,184 @@
+# @jay-framework/wix-stores
+
+Wix Stores integration for Jay Framework using the Catalog V3 API. Provides headless full-stack components for product pages, search/listing, and category navigation with server-side rendering.
+
+## Features
+
+- **Catalog V3 API** - Uses `productsV3` and `@wix/categories` for product and category data
+- **Three-phase rendering** - Slow (build/SSG), Fast (request/SSR), Interactive (client)
+- **Category-prefixed routes** - Optional URL prefixes per product line (e.g., `/products/polgat/shirt-name`)
+- **Unified search + category** - Single `product-search` component handles both search pages and category listings
+- **Shared cart** - Delegates cart operations to `@jay-framework/wix-cart`
+
+## Headless Components
+
+### Product Page (`product-page`)
+
+Complete product detail page with variant selection and add-to-cart.
+
+- **Slow phase**: Product details, media gallery, options, SEO data
+- **Fast phase**: Inventory status, pricing, variant availability
+- **Interactive**: Option/modifier selection, quantity, add to cart
+
+Route: `/products/[slug]` or `/products/[category]/[slug]` (when category prefixes are configured)
+
+### Product Search (`product-search`)
+
+Unified search and category listing component. Replaces the previous separate `category-page` component.
+
+- **Slow phase**: Available categories for filtering
+- **Fast phase**: Initial product results with price aggregations
+- **Interactive**: Search input, category/price/stock filters, sorting, load more
+
+When a `category` URL parameter is provided (e.g., from a route like `/products/polgat/`):
+
+- Scopes all searches to products within that category hierarchy
+- Shows only child categories of the root as filter options (root category is hidden)
+- Enables per-category template designs via separate jay-html files
+
+### Category List (`category-list`)
+
+Lists all store categories for navigation.
+
+## Configuration
+
+### Basic Setup
+
+The plugin requires `@jay-framework/wix-server-client` to be configured with Wix API credentials.
+
+Run setup to create the config template:
+
+```bash
+jay-stack setup wix-stores
+```
+
+### Category Prefixes (Optional)
+
+To enable category-prefixed product routes, create `config/.wix-stores.yaml`:
+
+```yaml
+categoryPrefixes:
+  - categoryId: '024a9fff-77de-4508-b82c-5fce24f74757'
+    prefix: 'polgat'
+    name: 'פולגת'
+  - categoryId: 'eac4db24-04cc-4f36-86cf-c9da6e873421'
+    prefix: 'kitan'
+    name: 'כיתן'
+```
+
+Each entry maps a root Wix category to a URL prefix. Products belonging to any child of the root category get URLs like `/products/{prefix}/{product-slug}`.
+
+To find category IDs, run setup to generate the category tree reference:
+
+```bash
+jay-stack setup wix-stores
+```
+
+This creates `agent-kit/references/wix-stores/categories.yaml` with all category IDs, names, product counts, and parent-child relationships as a tree.
+
+### Route Structure with Category Prefixes
+
+```
+src/pages/products/
+├── page.jay-html                         # /products (default search, optional)
+├── [slug]/page.jay-html                  # /products/:slug (default product page, optional)
+├── polgat/
+│   ├── page.jay-html                     # /products/polgat (polgat-design search)
+│   └── [slug]/page.jay-html              # /products/polgat/:slug (polgat product page)
+└── kitan/
+    ├── page.jay-html                     # /products/kitan (kitan-design search)
+    └── [slug]/page.jay-html              # /products/kitan/:slug (kitan product page)
+```
+
+Each prefix directory gets its own jay-html templates, enabling different visual designs per product line. Jay's routing precedence ensures static segments (`polgat`, `kitan`) take priority over the dynamic `[slug]` parameter.
+
+Products without a matching category prefix fall back to `/products/[slug]` if that route exists, or return 404 if it doesn't.
+
+## Server Actions
+
+### `searchProducts`
+
+Search products with filtering, sorting, and price aggregations.
+
+```typescript
+const results = await searchProducts({
+  query: 'shoes',
+  filters: { inStockOnly: true, categoryIds: ['cat-123'] },
+  sortBy: 'price_asc',
+  pageSize: 12,
+});
+```
+
+CLI:
+
+```bash
+jay-stack action wix-stores/searchProducts
+jay-stack action wix-stores/searchProducts --input '{"query": "shoes", "pageSize": 5}'
+```
+
+### `getProductBySlug`
+
+Fetch a single product by its URL slug.
+
+```typescript
+const product = await getProductBySlug({ slug: 'blue-sneakers' });
+```
+
+CLI:
+
+```bash
+jay-stack action wix-stores/getProductBySlug --input '{"slug": "blue-sneakers"}'
+```
+
+### `getCategories`
+
+Get all visible categories for filtering.
+
+```typescript
+const categories = await getCategories();
+```
+
+CLI:
+
+```bash
+jay-stack action wix-stores/getCategories
+```
+
+## Agent Kit References
+
+Running `jay-stack setup wix-stores` or `jay-stack agent-kit` generates a category tree reference at `agent-kit/references/wix-stores/categories.yaml`. This file contains:
+
+- All visible categories with IDs, names, slugs, and product counts
+- Full parent-child hierarchy as a nested tree
+- Configured category prefixes (if any) with their mapped category names
+
+## Architecture
+
+### Plugin Initialization
+
+```
+wix-server-client (init first)
+  └── Registers WIX_CLIENT_SERVICE (API key auth)
+
+wix-stores (init second)
+  ├── Loads config/.wix-stores.yaml (category prefixes)
+  ├── Registers WIX_STORES_SERVICE_MARKER (products, categories, inventory)
+  └── Client: Registers WIX_STORES_CONTEXT (delegates cart to wix-cart)
+```
+
+### Category Prefix Resolution
+
+When category prefixes are configured:
+
+1. **`loadProductParams`** fetches all products with `ALL_CATEGORIES_INFO` and resolves each product's prefix
+2. **`searchProducts`** includes `ALL_CATEGORIES_INFO` to generate correct prefixed URLs in results
+3. **`mapProductToCard`** generates URLs like `/products/polgat/shirt-name` based on the product's category ancestry
+4. **Product page** validates that the URL's category prefix matches the product's actual category
+
+## Design Log
+
+See [Design Log 10 - Category-Prefixed Product Routes](../../design-log/10%20-%20category-prefixed-product-routes.md) for the full design rationale.
+
+## License
+
+Apache-2.0

package/dist/actions/get-categories.jay-action

@@ -0,0 +1,8 @@
+name: getCategories
+description: Get available store categories for filtering products. Returns category IDs and names.
+
+inputSchema: {}
+
+outputSchema:
+  - categoryId: string
+    categoryName: string

package/dist/actions/get-product-by-slug.jay-action

@@ -0,0 +1,10 @@
+name: getProductBySlug
+description: Get a single product by its URL slug. Returns full ProductCardViewState or null if not found.
+
+import:
+  productCard: product-card.jay-contract
+
+inputSchema:
+  slug: string
+
+outputSchema: productCard?

package/dist/actions/search-products.jay-action

@@ -0,0 +1,33 @@
+name: searchProducts
+description: Search products in the Wix Store catalog using Catalog V3. Supports text search, price/stock/category filtering, sorting, and cursor-based pagination. Returns matching products with price aggregation data.
+
+import:
+  productCard: product-card.jay-contract
+
+inputSchema:
+  query: string
+  filters?:
+    inStockOnly?: boolean
+    minPrice?: number
+    maxPrice?: number
+    categoryIds?: string[]
+  sortBy?: enum(relevance | price_asc | price_desc | name_asc | name_desc | newest)
+  cursor?: string
+  pageSize?: number
+
+outputSchema:
+  products:
+    - productCard
+  totalCount: number
+  nextCursor?: string
+  hasMore: boolean
+  priceAggregation?:
+    minBound: number
+    maxBound: number
+    ranges:
+      - rangeId: string
+        label: string
+        minValue?: number
+        maxValue?: number
+        productCount: number
+        isSelected: boolean

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

@@ -0,0 +1,50 @@
+name: category-list
+tags:
+  # List of visible categories
+  - tag: categories
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: List of visible store categories
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+        description: Category GUID
+        
+      - tag: name
+        type: data
+        dataType: string
+        required: true
+        description: Category name
+        
+      - tag: slug
+        type: data
+        dataType: string
+        description: Category slug for URL
+        
+      - tag: description
+        type: data
+        dataType: string
+        description: Category description
+        
+      - tag: productCount
+        type: data
+        dataType: number
+        description: Number of products in category
+        
+      - tag: imageUrl
+        type: data
+        dataType: string
+        description: Category image URL
+        
+      - tag: categoryLink
+        type: interactive
+        elementType: HTMLAnchorElement
+        description: Link to category page
+
+  # Empty state
+  - tag: hasCategories
+    type: variant
+    dataType: boolean
+    description: Whether there are any categories

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

@@ -0,0 +1,40 @@
+import {HTMLElementCollectionProxy, JayContract} from "@jay-framework/runtime";
+
+
+export interface CategoryOfCategoryListViewState {
+  _id: string,
+  name: string,
+  slug: string,
+  description: string,
+  productCount: number,
+  imageUrl: string
+}
+
+export interface CategoryListViewState {
+  categories: Array<CategoryOfCategoryListViewState>,
+  hasCategories: boolean
+}
+
+export type CategoryListSlowViewState = Pick<CategoryListViewState, 'hasCategories'> & {
+    categories: Array<CategoryListViewState['categories'][number]>;
+};
+
+export type CategoryListFastViewState = {};
+
+export type CategoryListInteractiveViewState = {};
+
+
+export interface CategoryListRefs {
+  categories: {
+    categoryLink: HTMLElementCollectionProxy<CategoryOfCategoryListViewState, HTMLAnchorElement>
+  }
+}
+
+
+export interface CategoryListRepeatedRefs {
+  categories: {
+    categoryLink: HTMLElementCollectionProxy<CategoryOfCategoryListViewState, HTMLAnchorElement>
+  }
+}
+
+export type CategoryListContract = JayContract<CategoryListViewState, CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState>

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

@@ -0,0 +1,193 @@
+name: category-page
+tags:
+  # Category/Collection information (from Wix Stores Collection API)
+  - tag: _id
+    type: data
+    dataType: string
+    description: Collection GUID
+    
+  - tag: name
+    type: data
+    dataType: string
+    required: true
+    description: Collection name
+    
+  - tag: description
+    type: data
+    dataType: string
+    description: Collection description
+    
+  - tag: slug
+    type: data
+    dataType: string
+    description: Collection slug
+    
+  - tag: visible
+    type: data
+    dataType: boolean
+    description: Collection visibility (impacts dynamic pages only)
+    
+  - tag: numberOfProducts
+    type: data
+    dataType: number
+    description: Number of products in the collection
+    
+  # Media (from Wix Stores Collection API)
+  - tag: media
+    type: sub-contract
+    description: Media items associated with this collection
+    tags:
+      - tag: mainMedia
+        type: sub-contract
+        description: Primary media for the collection
+        tags:
+          - tag: _id
+            type: data
+            dataType: string
+            description: Media GUID
+            
+          - tag: url
+            type: data
+            dataType: string
+            description: Media URL
+            
+          - tag: altText
+            type: data
+            dataType: string
+            description: Media alt text
+            
+          - tag: mediaType
+            type: data
+            dataType: enum (IMAGE | VIDEO | AUDIO | DOCUMENT | ZIP)
+            description: Media item type
+            
+      - tag: items
+        type: sub-contract
+        repeated: true
+        trackBy: _id
+        description: All media items
+        tags:
+          - tag: _id
+            type: data
+            dataType: string
+            description: Media GUID
+            
+          - tag: url
+            type: data
+            dataType: string
+            description: Media URL
+            
+          - tag: altText
+            type: data
+            dataType: string
+            description: Media alt text
+            
+          - tag: title
+            type: data
+            dataType: string
+            description: Media item title
+            
+          - tag: mediaType
+            type: data
+            dataType: enum (IMAGE | VIDEO | AUDIO | DOCUMENT | ZIP)
+            description: Media item type
+            
+          - tag: thumbnail
+            type: sub-contract
+            description: Media thumbnail
+            tags:
+              - tag: url
+                type: data
+                dataType: string
+                description: Thumbnail URL
+                
+              - tag: width
+                type: data
+                dataType: number
+                description: Thumbnail width in pixels
+                
+              - tag: height
+                type: data
+                dataType: number
+                description: Thumbnail height in pixels
+                
+              - tag: format
+                type: data
+                dataType: string
+                description: Media format (mp4, png, etc.)
+    
+  # Breadcrumbs navigation
+  - tag: breadcrumbs
+    type: sub-contract
+    repeated: true
+    trackBy: categoryId
+    description: Breadcrumb navigation path
+    tags:
+      - tag: categoryId
+        type: data
+        dataType: string
+        description: Category GUID
+        
+      - tag: categoryName
+        type: data
+        dataType: string
+        description: Category name in breadcrumb
+        
+      - tag: categorySlug
+        type: data
+        dataType: string
+        description: Category slug for link
+        
+      - tag: categoryLink
+        type: interactive
+        elementType: HTMLAnchorElement
+        description: Link to category
+  
+  # Initial products (SSR - loaded in slow phase)
+  - tag: products
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Initial products in this category (rendered server-side)
+    link: ./product-card
+    
+  # Additional products (loaded on client via "load more")
+  - tag: loadedProducts
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    phase: fast+interactive
+    description: Additional products loaded on the client
+    link: ./product-card
+    
+  # Load more functionality
+  - tag: hasMore
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether there are more products to load
+    
+  - tag: loadMoreButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Button to load more products
+    
+  - tag: loadedCount
+    type: data
+    dataType: number
+    phase: fast+interactive
+    description: Number of products currently loaded
+  
+  # Loading state
+  - tag: isLoading
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether products are currently loading
+    
+  # Empty state
+  - tag: hasProducts
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether category has any products

package/dist/contracts/category-page.jay-contract.d.ts

@@ -0,0 +1,124 @@
+import {HTMLElementCollectionProxy, HTMLElementProxy, JayContract} from "@jay-framework/runtime";
+import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
+
+export enum MediaType {
+  IMAGE,
+  VIDEO,
+  AUDIO,
+  DOCUMENT,
+  ZIP
+}
+
+export interface MainMediaOfMediaOfCategoryPageViewState {
+  _id: string,
+  url: string,
+  altText: string,
+  mediaType: MediaType
+}
+
+export enum MediaType {
+  IMAGE,
+  VIDEO,
+  AUDIO,
+  DOCUMENT,
+  ZIP
+}
+
+export interface ThumbnailOfItemOfMediaOfCategoryPageViewState {
+  url: string,
+  width: number,
+  height: number,
+  format: string
+}
+
+export interface ItemOfMediaOfCategoryPageViewState {
+  _id: string,
+  url: string,
+  altText: string,
+  title: string,
+  mediaType: MediaType,
+  thumbnail: ThumbnailOfItemOfMediaOfCategoryPageViewState
+}
+
+export interface MediaOfCategoryPageViewState {
+  mainMedia: MainMediaOfMediaOfCategoryPageViewState,
+  items: Array<ItemOfMediaOfCategoryPageViewState>
+}
+
+export interface BreadcrumbOfCategoryPageViewState {
+  categoryId: string,
+  categoryName: string,
+  categorySlug: string
+}
+
+export interface CategoryPageViewState {
+  _id: string,
+  name: string,
+  description: string,
+  slug: string,
+  visible: boolean,
+  numberOfProducts: number,
+  media: MediaOfCategoryPageViewState,
+  breadcrumbs: Array<BreadcrumbOfCategoryPageViewState>,
+  products: Array<ProductCardViewState>,
+  loadedProducts: Array<ProductCardViewState>,
+  hasMore: boolean,
+  loadedCount: number,
+  isLoading: boolean,
+  hasProducts: boolean
+}
+
+export type CategoryPageSlowViewState = Pick<CategoryPageViewState, '_id' | 'name' | 'description' | 'slug' | 'visible' | 'numberOfProducts'> & {
+    media: CategoryPageViewState['media'];
+    breadcrumbs: Array<CategoryPageViewState['breadcrumbs'][number]>;
+    products: Array<Pick<CategoryPageViewState['products'][number], '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: CategoryPageViewState['products'][number]['mainMedia'];
+    thumbnail: CategoryPageViewState['products'][number]['thumbnail'];
+    inventory: CategoryPageViewState['products'][number]['inventory'];
+    ribbon: CategoryPageViewState['products'][number]['ribbon'];
+    brand: CategoryPageViewState['products'][number]['brand'];
+    quickOption: Pick<CategoryPageViewState['products'][number]['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<CategoryPageViewState['products'][number]['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode' | 'variantId'>>;
+};
+}>;
+};
+
+export type CategoryPageFastViewState = Pick<CategoryPageViewState, 'hasMore' | 'loadedCount' | 'isLoading' | 'hasProducts'> & {
+    products: Array<Pick<CategoryPageViewState['products'][number], '_id' | 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<CategoryPageViewState['products'][number]['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+}>;
+    loadedProducts: Array<CategoryPageViewState['loadedProducts'][number]>;
+};
+
+export type CategoryPageInteractiveViewState = Pick<CategoryPageViewState, 'hasMore' | 'loadedCount' | 'isLoading' | 'hasProducts'> & {
+    products: Array<Pick<CategoryPageViewState['products'][number], '_id' | 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<CategoryPageViewState['products'][number]['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+}>;
+    loadedProducts: Array<CategoryPageViewState['loadedProducts'][number]>;
+};
+
+
+export interface CategoryPageRefs {
+  loadMoreButton: HTMLElementProxy<CategoryPageViewState, HTMLButtonElement>,
+  breadcrumbs: {
+    categoryLink: HTMLElementCollectionProxy<BreadcrumbOfCategoryPageViewState, HTMLAnchorElement>
+  },
+  products: ProductCardRepeatedRefs,
+  loadedProducts: ProductCardRepeatedRefs
+}
+
+
+export interface CategoryPageRepeatedRefs {
+  loadMoreButton: HTMLElementCollectionProxy<CategoryPageViewState, HTMLButtonElement>,
+  breadcrumbs: {
+    categoryLink: HTMLElementCollectionProxy<BreadcrumbOfCategoryPageViewState, HTMLAnchorElement>
+  },
+  products: ProductCardRepeatedRefs,
+  loadedProducts: ProductCardRepeatedRefs
+}
+
+export type CategoryPageContract = JayContract<CategoryPageViewState, CategoryPageRefs, CategoryPageSlowViewState, CategoryPageFastViewState, CategoryPageInteractiveViewState>

package/dist/contracts/media-gallery.jay-contract

@@ -0,0 +1,22 @@
+name: mediaGallery
+tags:
+  - tag: selectedMedia
+    type: sub-contract
+    description: Selected Media (image, video) to display with selection based galleries
+    link: ./media
+
+  - tag: availableMedia
+    type: sub-contract
+    repeated: true
+    trackBy: mediaId
+    description: Available media for display or use as thumbnails
+    tags:
+      - tag: mediaId
+        type: data
+      - tag: media
+        type: sub-contract
+        link: ./media
+      - tag: selected
+        type: [variant, interactive]
+        dataType: enum(selected | notSelected)
+        elementType: HTMLImageElement | HTMLDivElement