@jay-framework/wix-stores 0.15.0 → 0.15.4

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { getCurrentCartClient, CartState } from '@jay-framework/wix-cart';
+import { CartState } from '@jay-framework/wix-cart';
 export { AddToCartOptions, CartIndicatorState, CartLineItem, CartState, CartSummary, WIX_CART_CONTEXT, WIX_CART_SERVICE, WixCartContext, WixCartService, cartIndicator, cartPage, provideWixCartContext, provideWixCartService } from '@jay-framework/wix-cart';
 import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
 import { UrlParams, Signals, PageProps } from '@jay-framework/fullstack-component';
@@ -6,9 +6,10 @@ import * as _jay_framework_component from '@jay-framework/component';
 import * as _jay_framework_runtime from '@jay-framework/runtime';
 import { HTMLElementCollectionProxy, HTMLElementProxy } from '@jay-framework/runtime';
 import { WixClient } from '@wix/sdk';
+import { BuildDescriptors } from '@wix/sdk-types';
 import { productsV3, inventoryItemsV3 } from '@wix/stores';
 import { categories } from '@wix/categories';
-import { BuildDescriptors } from '@wix/sdk-types';
+import { currentCart } from '@wix/ecom';
 import { Getter } from '@jay-framework/reactive';
 import { OptionChoice } from '@wix/auto_sdk_stores_products-v-3';
 import { PluginSetupContext, PluginSetupResult, PluginReferencesContext, PluginReferencesResult } from '@jay-framework/stack-server-runtime';
@@ -29,7 +30,6 @@ interface ChoiceOfProductOptionsViewState {
   choiceType: ChoiceType$1,
   colorCode: string,
   inStock: boolean,
-  variantId: string,
   isSelected: boolean
 }
 
@@ -100,6 +100,7 @@ declare enum ProductType$1 {
 declare enum QuickAddType {
   SIMPLE,
   SINGLE_OPTION,
+  COLOR_AND_TEXT_OPTIONS,
   NEEDS_CONFIGURATION
 }
 
@@ -121,7 +122,8 @@ interface ProductCardViewState {
   productType: ProductType$1,
   isAddingToCart: boolean,
   quickAddType: QuickAddType,
-  quickOption: ProductOptionsViewState
+  quickOption: ProductOptionsViewState,
+  secondQuickOption: ProductOptionsViewState
 }
 
 
@@ -129,7 +131,8 @@ interface ProductCardRepeatedRefs {
   productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
   viewOptionsButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
-  quickOption: ProductOptionsRepeatedRefs
+  quickOption: ProductOptionsRepeatedRefs,
+  secondQuickOption: ProductOptionsRepeatedRefs
 }
 
 interface RangeOfPriceRangeOfFilterOfProductSearchViewState {
@@ -153,7 +156,8 @@ interface CategoryOfCategoryFilterOfFilterOfProductSearchViewState {
   categoryId: string,
   categoryName: string,
   categorySlug: string,
-  isSelected: boolean
+  isSelected: boolean,
+  categoryUrl: string
 }
 
 interface CategoryFilterOfFilterOfProductSearchViewState {
@@ -184,6 +188,57 @@ interface SuggestionOfProductSearchViewState {
   suggestionText: string
 }
 
+interface BreadcrumbOfCategoryHeaderOfProductSearchViewState {
+  categoryId: string,
+  name: string,
+  slug: string,
+  url: string
+}
+
+interface PropOfTagOfSeoDatumOfCategoryHeaderOfProductSearchViewState {
+  key: string,
+  value: string
+}
+
+interface MetaOfTagOfSeoDatumOfCategoryHeaderOfProductSearchViewState {
+  key: string,
+  value: string
+}
+
+interface TagOfSeoDatumOfCategoryHeaderOfProductSearchViewState {
+  position: string,
+  type: string,
+  props: Array<PropOfTagOfSeoDatumOfCategoryHeaderOfProductSearchViewState>,
+  meta: Array<MetaOfTagOfSeoDatumOfCategoryHeaderOfProductSearchViewState>,
+  children: string
+}
+
+interface KeywordOfSettingOfSeoDatumOfCategoryHeaderOfProductSearchViewState {
+  term: string,
+  isMain: boolean,
+  origin: string
+}
+
+interface SettingOfSeoDatumOfCategoryHeaderOfProductSearchViewState {
+  preventAutoRedirect: boolean,
+  keywords: Array<KeywordOfSettingOfSeoDatumOfCategoryHeaderOfProductSearchViewState>
+}
+
+interface SeoDatumOfCategoryHeaderOfProductSearchViewState {
+  tags: Array<TagOfSeoDatumOfCategoryHeaderOfProductSearchViewState>,
+  settings: SettingOfSeoDatumOfCategoryHeaderOfProductSearchViewState
+}
+
+interface CategoryHeaderOfProductSearchViewState {
+  name: string,
+  description: string,
+  imageUrl: string,
+  hasImage: boolean,
+  productCount: number,
+  breadcrumbs: Array<BreadcrumbOfCategoryHeaderOfProductSearchViewState>,
+  seoData: SeoDatumOfCategoryHeaderOfProductSearchViewState
+}
+
 interface ProductSearchViewState {
   searchExpression: string,
   searchFields: string,
@@ -200,15 +255,17 @@ interface ProductSearchViewState {
   loadedCount: number,
   totalCount: number,
   hasSuggestions: boolean,
-  suggestions: Array<SuggestionOfProductSearchViewState>
+  suggestions: Array<SuggestionOfProductSearchViewState>,
+  categoryHeader: CategoryHeaderOfProductSearchViewState
 }
 
 type ProductSearchSlowViewState = Pick<ProductSearchViewState, 'searchFields' | 'fuzzySearch' | 'emptyStateMessage'> & {
     filters: {
     categoryFilter: {
-    categories: Array<Pick<ProductSearchViewState['filters']['categoryFilter']['categories'][number], 'categoryId' | 'categoryName' | 'categorySlug'>>;
+    categories: Array<Pick<ProductSearchViewState['filters']['categoryFilter']['categories'][number], 'categoryId' | 'categoryName' | 'categorySlug' | 'categoryUrl'>>;
 };
 };
+    categoryHeader: ProductSearchViewState['categoryHeader'];
 };
 
 type ProductSearchFastViewState = Pick<ProductSearchViewState, 'searchExpression' | 'isSearching' | 'hasSearched' | 'resultCount' | 'hasResults' | 'hasMore' | 'loadedCount' | 'totalCount' | 'hasSuggestions'> & {
@@ -267,79 +324,94 @@ interface ProductSearchRefs {
 }
 
 /**
- * Wix Store API Client Factories
- *
- * These functions create singleton instances of Wix API clients.
- * Used by both the server service and client context.
+ * Configuration loader for wix-stores plugin.
  *
- * Note: Cart client is provided by @jay-framework/wix-cart package.
+ * Reads optional config from config/.wix-stores.yaml.
+ * When the file doesn't exist, returns defaults.
  */
+/**
+ * URL templates for building canonical product and category links.
+ * Placeholders: {slug}, {category}, {prefix}
+ */
+interface UrlTemplates {
+    /** URL template for product pages. Default: "/products/{slug}" */
+    product: string;
+    /** URL template for category pages. Not set = no category deep-linking */
+    category: string | null;
+}
 
 /**
- * Get a configured Wix Stores Products V3 client (singleton)
+ * Shared Product Mapping Utilities
  *
- * The Products V3 API is part of the new Catalog V3 system that provides
- * advanced product management capabilities for sophisticated e-commerce applications.
- *
- * @returns Products V3 client instance from @wix/stores
- * @see https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-v3/introduction
+ * Maps Wix Stores Catalog V3 product responses to view state contracts.
  */
-declare function getProductsV3Client(wixClient: WixClient): BuildDescriptors<typeof productsV3, {}>;
+
 /**
- * Get a configured Wix Stores Categories client (singleton)
- *
- * The Categories API allows you to manage product Categories in your Wix store.
- *
- * @returns Categories client instance from @wix/stores
- * @see https://dev.wix.com/docs/sdk/backend-modules/categories/categories/introduction
+ * Cached category hierarchy data, used for resolving category slugs and parent chains.
+ * Built lazily from the Wix Categories API and cached on the service.
  */
-declare function getCategoriesClient(wixClient: WixClient): BuildDescriptors<typeof categories, {}>;
+interface CategoryTree {
+    /** Map of categoryId → slug */
+    slugMap: Map<string, string>;
+    /** Map of categoryId → parent categoryId */
+    parentMap: Map<string, string>;
+    /** Set of root category IDs (categories with no parent) */
+    rootIds: Set<string>;
+    /** Map of categoryId → image URL (only for categories that have an image) */
+    imageMap: Map<string, string>;
+}
 /**
- * Get a configured Wix Stores Inventory V3 client (singleton)
- *
- * The Inventory API allows you to manage product inventory in your Wix store.
- *
- * @returns Inventory client instance from @wix/stores
- * @see https://dev.wix.com/docs/sdk/backend-modules/stores/inventory/introduction
+ * Find the root category ID for a given category by walking up the parent chain.
  */
-declare function getInventoryClient(wixClient: WixClient): BuildDescriptors<typeof inventoryItemsV3, {}>;
-
+declare function findRootCategoryId(categoryId: string, tree: CategoryTree): string;
 /**
- * Maps a Wix root category to a URL prefix slug.
- * Products belonging to any child of this category get URLs like /products/{prefix}/{slug}.
+ * Get the slug of the root category for a given category.
  */
-interface CategoryPrefixConfig {
-    /** Root category ID in Wix */
-    categoryId: string;
-    /** URL prefix slug (e.g., 'polgat', 'kitan') */
-    prefix: string;
-    /** Display name for the category (e.g., 'פולגת', 'כיתן') */
-    name: string;
-}
+declare function findRootCategorySlug(categoryId: string, tree: CategoryTree): string;
+/**
+ * Find the image URL for a category, walking up the parent chain if the category has no image.
+ * Returns the first image found in the ancestry, or empty string.
+ */
+declare function findCategoryImage(categoryId: string, tree: CategoryTree): string;
+/**
+ * Build a product URL from the template, resolving {slug}, {category}, {prefix}.
+ * Defaults to placeholders if values are not provided
+ */
+declare function buildProductUrl(urls: UrlTemplates, tree: CategoryTree, slug: string, mainCategoryId: string): string | null;
+/**
+ * Build a category URL from the template, resolving {category} and {prefix}.
+ * Returns null if template is null or a required placeholder can't be resolved.
+ */
+declare function buildCategoryUrl(urls: UrlTemplates, tree: CategoryTree, categorySlug: string, categoryId: string): string | null;
+/** Variant stock map: colorChoiceId -> textChoiceId -> inStock */
+type VariantStockMap = Record<string, Record<string, boolean>>;
+
 interface WixStoresService {
-    products: ReturnType<typeof getProductsV3Client>;
-    categories: ReturnType<typeof getCategoriesClient>;
-    inventory: ReturnType<typeof getInventoryClient>;
+    products: BuildDescriptors<typeof productsV3, {}>;
+    categories: BuildDescriptors<typeof categories, {}>;
+    inventory: BuildDescriptors<typeof inventoryItemsV3, {}>;
     /** @deprecated Use WIX_CART_SERVICE from @jay-framework/wix-cart instead */
-    cart: ReturnType<typeof getCurrentCartClient>;
-    /** Category-to-URL-prefix mappings. Empty array when not configured. */
-    categoryPrefixes: CategoryPrefixConfig[];
+    cart: BuildDescriptors<typeof currentCart, {}>;
+    /** URL templates for building canonical links */
+    urls: UrlTemplates;
+    /** Slug of the fallback category for pages without category context */
+    defaultCategory: string | null;
+    /** Get the cached category tree. Lazily built on first call. */
+    getCategoryTree(): Promise<CategoryTree>;
 }
 /**
  * Server service marker for Wix Stores.
- * Use with `.withServices(WIX_STORES_SERVICE_MARKER)` in component definitions.
  */
 declare const WIX_STORES_SERVICE_MARKER: _jay_framework_fullstack_component.ServiceMarker<WixStoresService>;
 /**
  * Options for initializing the Wix Stores service.
  */
 interface WixStoresServiceOptions {
-    /** Category-to-URL-prefix mappings for category-prefixed product routes */
-    categoryPrefixes?: CategoryPrefixConfig[];
+    urls?: UrlTemplates;
+    defaultCategory?: string | null;
 }
 /**
  * Creates, registers, and returns a Wix Stores service instance.
- * Called during server initialization.
  */
 declare function provideWixStoresService(wixClient: WixClient, options?: WixStoresServiceOptions): WixStoresService;
 
@@ -403,11 +475,13 @@ declare const WIX_STORES_CONTEXT: _jay_framework_runtime.ContextMarker<WixStores
 
 /**
  * URL parameters for product search routes.
- * When used as a category listing, `category` is the prefix slug (e.g., 'polgat').
+ * Supports: category (prefix slug), subcategory (sub-category slug).
  */
 interface ProductSearchParams extends UrlParams {
-    /** Category prefix slug. When present, scopes search to this category hierarchy. */
+    /** Top-level category slug (e.g., 'polgat'). Scopes search to this category. */
     category?: string;
+    /** Sub-category slug (e.g., 'shirts'). Further scopes within the category. */
+    subcategory?: string;
 }
 /**
  * Search sort options
@@ -437,23 +511,7 @@ interface SearchFastCarryForward {
     /** Root category ID when scoped to a category prefix (always applied, hidden from UI) */
     baseCategoryId: string | null;
 }
-/**
- * Product Search Full-Stack Component
- *
- * A complete headless product search component with server-side rendering,
- * filtering, sorting, and "load more" functionality.
- *
- * Rendering phases:
- * - Slow: Categories for filtering (relatively static)
- * - Fast: Products, search results, load more state (dynamic per request)
- * - Interactive: Search input, filter selections, sorting, load more (client-side)
- *
- * Usage:
- * ```typescript
- * import { productSearch } from '@jay-framework/wix-stores';
- * ```
- */
-declare const productSearch: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductSearchRefs, ProductSearchSlowViewState, ProductSearchFastViewState, ProductSearchInteractiveViewState, [SearchSlowCarryForward, WixStoresService], [Signals<ProductSearchFastViewState>, SearchFastCarryForward, WixStoresContext], PageProps & ProductSearchParams, {}, _jay_framework_component.JayComponentCore<PageProps & ProductSearchParams, ProductSearchInteractiveViewState>>;
+declare const productSearch: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductSearchRefs, ProductSearchSlowViewState, ProductSearchFastViewState, ProductSearchInteractiveViewState, [SearchSlowCarryForward, WixStoresService], [Signals<ProductSearchFastViewState>, SearchFastCarryForward, WixStoresContext], PageProps & ProductSearchParams, ProductSearchParams, _jay_framework_component.JayComponentCore<PageProps & ProductSearchParams, ProductSearchInteractiveViewState>>;
 
 declare enum MediaType {
   IMAGE,
@@ -907,6 +965,15 @@ declare const searchProducts: _jay_framework_fullstack_component.JayAction<Searc
  * ```
  */
 declare const getProductBySlug: _jay_framework_fullstack_component.JayAction<GetProductBySlugInput, ProductCardViewState> & _jay_framework_fullstack_component.JayActionDefinition<GetProductBySlugInput, ProductCardViewState, [WixStoresService]>;
+/**
+ * Get variant stock availability for a COLOR_AND_TEXT_OPTIONS product.
+ * Fetches full product data and builds a stock map: colorChoiceId -> textChoiceId -> inStock.
+ */
+declare const getVariantStock: _jay_framework_fullstack_component.JayAction<{
+    productId: string;
+}, VariantStockMap> & _jay_framework_fullstack_component.JayActionDefinition<{
+    productId: string;
+}, VariantStockMap, [WixStoresService]>;
 /**
  * Get available categories for filtering.
  *
@@ -940,4 +1007,4 @@ declare function setupWixStores(ctx: PluginSetupContext): Promise<PluginSetupRes
  */
 declare function generateWixStoresReferences(ctx: PluginReferencesContext): Promise<PluginReferencesResult>;
 
-export { type CategoryPrefixConfig, type GetProductBySlugInput, type PriceAggregationData, type PriceRangeBucket, type ProductPageParams, type ProductSearchFilters, type ProductSearchParams, type ProductSortField, type SearchProductsInput, type SearchProductsOutput, type SearchSortOption, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, categoryList, generateWixStoresReferences, getCategories, getProductBySlug, init, productPage, productSearch, provideWixStoresService, searchProducts, setupWixStores };
+export { type CategoryTree, type GetProductBySlugInput, type PriceAggregationData, type PriceRangeBucket, type ProductPageParams, type ProductSearchFilters, type ProductSearchParams, type ProductSortField, type SearchProductsInput, type SearchProductsOutput, type SearchSortOption, 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 };