@jay-framework/wix-stores-v1 0.15.0

package/README.md

@@ -0,0 +1,150 @@
+# @jay-framework/wix-stores-v1
+
+Wix Stores **Catalog V1** API client and headless components for the Jay Framework.
+
+## Overview
+
+This package provides integration with the Wix Stores Catalog V1 API. If your Wix store uses the newer Catalog V3 API, use `@jay-framework/wix-stores` instead.
+
+### V1 vs V3
+
+| Feature      | V1 (this package) | V3 (@jay-framework/wix-stores) |
+| ------------ | ----------------- | ------------------------------ |
+| Products API | `products`        | `productsV3`                   |
+| Collections  | `collections`     | `@wix/categories`              |
+| Pagination   | Skip-based        | Cursor-based                   |
+| Price format | Numbers (289)     | Strings ("289")                |
+
+## Installation
+
+```bash
+npm install @jay-framework/wix-stores-v1
+```
+
+## Quick Start
+
+### 1. Configure Wix
+
+Set up your Wix configuration in `config/.wix.yaml`:
+
+```yaml
+apiKeyStrategy:
+  apiKey: 'your-api-key'
+  siteId: 'your-site-id'
+
+oauthStrategy:
+  clientId: 'your-oauth-client-id'
+```
+
+### 2. Use Server Actions
+
+```typescript
+import { searchProducts, getProductBySlug, getCollections } from '@jay-framework/wix-stores-v1';
+
+// Search products
+const results = await searchProducts({
+  query: 'whisky',
+  filters: { minPrice: 50, maxPrice: 200 },
+  sortBy: 'price_asc',
+  pageSize: 12,
+  page: 1,
+});
+// results.priceAggregation contains { minBound, maxBound, ranges }
+
+// Get a product by slug
+const product = await getProductBySlug({ slug: 'peat-s-beast-px-finish-54-1' });
+
+// Get collections (V1 equivalent of categories)
+const collections = await getCollections();
+```
+
+### 3. Use Client Context
+
+```typescript
+import { useContext } from '@jay-framework/runtime';
+import { WIX_STORES_V1_CONTEXT } from '@jay-framework/wix-stores-v1';
+
+function MyComponent(props, refs) {
+  const stores = useContext(WIX_STORES_V1_CONTEXT);
+
+  // Reactive cart indicator
+  const itemCount = stores.cartIndicator.itemCount();
+
+  // Add to cart
+  refs.addToCart.onclick(async () => {
+    await stores.addToCart('product-id', 1);
+  });
+}
+```
+
+## API
+
+### Server Actions
+
+| Action                    | Description                             |
+| ------------------------- | --------------------------------------- |
+| `searchProducts(input)`   | Search/filter products with pagination  |
+| `getProductBySlug(input)` | Get a single product by URL slug        |
+| `getCollections()`        | Get available collections for filtering |
+
+### Client Context Methods
+
+| Method                                  | Description                     |
+| --------------------------------------- | ------------------------------- |
+| `cartIndicator.itemCount()`             | Reactive cart item count        |
+| `cartIndicator.hasItems()`              | Reactive boolean for cart state |
+| `addToCart(productId, qty, variantId?)` | Add product to cart             |
+| `removeLineItems(ids)`                  | Remove items from cart          |
+| `updateLineItemQuantity(id, qty)`       | Update item quantity            |
+| `clearCart()`                           | Remove all items                |
+| `applyCoupon(code)`                     | Apply coupon code               |
+| `removeCoupon()`                        | Remove applied coupon           |
+| `getCollections()`                      | Get all collections             |
+
+## Differences from V3
+
+### Price Handling
+
+V1 prices are numbers, V3 are strings. This package handles the conversion:
+
+```typescript
+// V1 API response
+{ price: { price: 289, formatted: { price: "€289.00" } } }
+
+// Mapped to ViewState (same format as V3)
+{ actualPriceRange: { minValue: { amount: "289", formattedAmount: "€289.00" } } }
+```
+
+### Collections vs Categories
+
+V1 uses "collections" (`@wix/stores/collections`), V3 uses "categories" (`@wix/categories`):
+
+```typescript
+// V1 - this package
+const collections = await getCollections();
+
+// V3 - @jay-framework/wix-stores
+const categories = await getCategories();
+```
+
+### Pagination
+
+V1 uses skip-based pagination:
+
+```typescript
+// V1
+const results = await searchProducts({ page: 2, pageSize: 12 });
+
+// V3 uses cursor-based
+const results = await searchProducts({ cursor: 'abc123', pageSize: 12 });
+```
+
+## Reference
+
+- [Wix Stores Products V1 API](https://dev.wix.com/docs/sdk/backend-modules/stores/products/introduction)
+- [Wix Stores Collections API](https://dev.wix.com/docs/sdk/backend-modules/stores/collections/introduction)
+- Design Log: `wix/design-log/06 - wix-stores-v1 package.md`
+
+## License
+
+Apache-2.0

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

@@ -0,0 +1,12 @@
+name: getCollections
+description: Get available store collections for filtering products. V1 uses collections instead of categories. Returns collection details including name, slug, description, image, and product count.
+
+inputSchema: {}
+
+outputSchema:
+  - _id: string
+    name: string
+    slug: string
+    description: string
+    imageUrl: string
+    productCount: number

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

@@ -0,0 +1,10 @@
+name: getProductBySlug
+description: Get a single product by its URL slug using Catalog V1. 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,32 @@
+name: searchProducts
+description: Search products using Wix Stores Catalog V1 with page-based pagination. Supports text search, price and collection filtering, sorting, and returns price aggregation data.
+
+import:
+  productCard: product-card.jay-contract
+
+inputSchema:
+  query: string
+  filters?:
+    minPrice?: number
+    maxPrice?: number
+    collectionIds?: string[]
+  sortBy?: enum(relevance | price_asc | price_desc | name_asc | name_desc | newest)
+  page?: number
+  pageSize?: number
+
+outputSchema:
+  products:
+    - productCard
+  totalCount: number
+  currentPage: number
+  totalPages: number
+  hasMore: boolean
+  priceAggregation:
+    minBound: number
+    maxBound: number
+    ranges:
+      - rangeId: string
+        label: string
+        minValue?: number
+        maxValue?: number
+        isSelected: boolean

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

@@ -0,0 +1,55 @@
+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: hasImage
+        type: variant
+        dataType: boolean
+        description: Whether the category has an image
+        
+      - 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,41 @@
+import {HTMLElementCollectionProxy, JayContract} from "@jay-framework/runtime";
+
+
+export interface CategoryOfCategoryListViewState {
+  _id: string,
+  name: string,
+  slug: string,
+  description: string,
+  productCount: number,
+  imageUrl: string,
+  hasImage: boolean
+}
+
+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,199 @@
+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
+    
+  # Whether the collection has media
+  - tag: hasImage
+    type: variant
+    dataType: boolean
+    description: Whether the collection has a main image
+
+  # 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,125 @@
+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,
+  hasImage: boolean,
+  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' | 'hasImage'> & {
+    media: CategoryPageViewState['media'];
+    breadcrumbs: Array<CategoryPageViewState['breadcrumbs'][number]>;
+    products: Array<Pick<CategoryPageViewState['products'][number], '_id' | 'name' | 'slug' | 'productUrl' | '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