@jay-framework/wix-stores 0.15.0

package/dist/index.d.ts

@@ -0,0 +1,943 @@
+import { getCurrentCartClient, 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';
+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 { productsV3, inventoryItemsV3 } from '@wix/stores';
+import { categories } from '@wix/categories';
+import { BuildDescriptors } from '@wix/sdk-types';
+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';
+
+declare enum OptionRenderType$1 {
+  TEXT_CHOICES,
+  COLOR_SWATCH_CHOICES
+}
+
+declare enum ChoiceType$1 {
+  CHOICE_TEXT,
+  ONE_COLOR
+}
+
+interface ChoiceOfProductOptionsViewState {
+  choiceId: string,
+  name: string,
+  choiceType: ChoiceType$1,
+  colorCode: string,
+  inStock: boolean,
+  variantId: string,
+  isSelected: boolean
+}
+
+interface ProductOptionsViewState {
+  _id: string,
+  name: string,
+  optionRenderType: OptionRenderType$1,
+  choices: Array<ChoiceOfProductOptionsViewState>
+}
+
+
+interface ProductOptionsRepeatedRefs {
+  choices: {
+    choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
+  }
+}
+
+declare enum MediaType$1 {
+  IMAGE,
+  VIDEO
+}
+
+interface MainMediaOfProductCardViewState {
+  url: string,
+  altText: string,
+  mediaType: MediaType$1
+}
+
+interface ThumbnailOfProductCardViewState {
+  url: string,
+  altText: string,
+  width: number,
+  height: number
+}
+
+declare enum AvailabilityStatus {
+  IN_STOCK,
+  OUT_OF_STOCK,
+  PARTIALLY_OUT_OF_STOCK
+}
+
+declare enum PreorderStatus {
+  ENABLED,
+  DISABLED,
+  PARTIALLY_ENABLED
+}
+
+interface InventoryOfProductCardViewState {
+  availabilityStatus: AvailabilityStatus,
+  preorderStatus: PreorderStatus
+}
+
+interface RibbonOfProductCardViewState {
+  _id: string,
+  name: string
+}
+
+interface BrandOfProductCardViewState {
+  _id: string,
+  name: string
+}
+
+declare enum ProductType$1 {
+  PHYSICAL,
+  DIGITAL
+}
+
+declare enum QuickAddType {
+  SIMPLE,
+  SINGLE_OPTION,
+  NEEDS_CONFIGURATION
+}
+
+interface ProductCardViewState {
+  _id: string,
+  name: string,
+  slug: string,
+  productUrl: string,
+  categoryPrefix: string,
+  mainMedia: MainMediaOfProductCardViewState,
+  thumbnail: ThumbnailOfProductCardViewState,
+  price: string,
+  strikethroughPrice: string,
+  hasDiscount: boolean,
+  inventory: InventoryOfProductCardViewState,
+  ribbon: RibbonOfProductCardViewState,
+  hasRibbon: boolean,
+  brand: BrandOfProductCardViewState,
+  productType: ProductType$1,
+  isAddingToCart: boolean,
+  quickAddType: QuickAddType,
+  quickOption: ProductOptionsViewState
+}
+
+
+interface ProductCardRepeatedRefs {
+  productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
+  addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  viewOptionsButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  quickOption: ProductOptionsRepeatedRefs
+}
+
+interface RangeOfPriceRangeOfFilterOfProductSearchViewState {
+  rangeId: string,
+  label: string,
+  minValue: number,
+  maxValue: number,
+  productCount: number,
+  isSelected: boolean
+}
+
+interface PriceRangeOfFilterOfProductSearchViewState {
+  minPrice: number,
+  maxPrice: number,
+  minBound: number,
+  maxBound: number,
+  ranges: Array<RangeOfPriceRangeOfFilterOfProductSearchViewState>
+}
+
+interface CategoryOfCategoryFilterOfFilterOfProductSearchViewState {
+  categoryId: string,
+  categoryName: string,
+  categorySlug: string,
+  isSelected: boolean
+}
+
+interface CategoryFilterOfFilterOfProductSearchViewState {
+  categories: Array<CategoryOfCategoryFilterOfFilterOfProductSearchViewState>
+}
+
+interface FilterOfProductSearchViewState {
+  priceRange: PriceRangeOfFilterOfProductSearchViewState,
+  categoryFilter: CategoryFilterOfFilterOfProductSearchViewState,
+  inStockOnly: boolean
+}
+
+declare enum CurrentSort {
+  relevance,
+  priceAsc,
+  priceDesc,
+  newest,
+  nameAsc,
+  nameDesc
+}
+
+interface SortByOfProductSearchViewState {
+  currentSort: CurrentSort
+}
+
+interface SuggestionOfProductSearchViewState {
+  suggestionId: string,
+  suggestionText: string
+}
+
+interface ProductSearchViewState {
+  searchExpression: string,
+  searchFields: string,
+  fuzzySearch: boolean,
+  isSearching: boolean,
+  hasSearched: boolean,
+  searchResults: Array<ProductCardViewState>,
+  resultCount: number,
+  hasResults: boolean,
+  emptyStateMessage: string,
+  filters: FilterOfProductSearchViewState,
+  sortBy: SortByOfProductSearchViewState,
+  hasMore: boolean,
+  loadedCount: number,
+  totalCount: number,
+  hasSuggestions: boolean,
+  suggestions: Array<SuggestionOfProductSearchViewState>
+}
+
+type ProductSearchSlowViewState = Pick<ProductSearchViewState, 'searchFields' | 'fuzzySearch' | 'emptyStateMessage'> & {
+    filters: {
+    categoryFilter: {
+    categories: Array<Pick<ProductSearchViewState['filters']['categoryFilter']['categories'][number], 'categoryId' | 'categoryName' | 'categorySlug'>>;
+};
+};
+};
+
+type ProductSearchFastViewState = Pick<ProductSearchViewState, 'searchExpression' | 'isSearching' | 'hasSearched' | 'resultCount' | 'hasResults' | 'hasMore' | 'loadedCount' | 'totalCount' | 'hasSuggestions'> & {
+    searchResults: Array<ProductSearchViewState['searchResults'][number]>;
+    filters: Pick<ProductSearchViewState['filters'], 'inStockOnly'> & {
+    priceRange: ProductSearchViewState['filters']['priceRange'];
+    categoryFilter: {
+    categories: Array<Pick<ProductSearchViewState['filters']['categoryFilter']['categories'][number], 'categoryId' | 'isSelected'>>;
+};
+};
+    sortBy: ProductSearchViewState['sortBy'];
+    suggestions: Array<ProductSearchViewState['suggestions'][number]>;
+};
+
+type ProductSearchInteractiveViewState = Pick<ProductSearchViewState, 'searchExpression' | 'isSearching' | 'hasSearched' | 'resultCount' | 'hasResults' | 'hasMore' | 'loadedCount' | 'totalCount' | 'hasSuggestions'> & {
+    searchResults: Array<ProductSearchViewState['searchResults'][number]>;
+    filters: Pick<ProductSearchViewState['filters'], 'inStockOnly'> & {
+    priceRange: ProductSearchViewState['filters']['priceRange'];
+    categoryFilter: {
+    categories: Array<Pick<ProductSearchViewState['filters']['categoryFilter']['categories'][number], 'categoryId' | 'isSelected'>>;
+};
+};
+    sortBy: ProductSearchViewState['sortBy'];
+    suggestions: Array<ProductSearchViewState['suggestions'][number]>;
+};
+
+
+interface ProductSearchRefs {
+  searchExpression: HTMLElementProxy<ProductSearchViewState, HTMLInputElement>,
+  searchButton: HTMLElementProxy<ProductSearchViewState, HTMLButtonElement>,
+  clearSearchButton: HTMLElementProxy<ProductSearchViewState, HTMLButtonElement>,
+  loadMoreButton: HTMLElementProxy<ProductSearchViewState, HTMLButtonElement>,
+  searchResults: ProductCardRepeatedRefs,
+  filters: {
+    inStockOnly: HTMLElementProxy<FilterOfProductSearchViewState, HTMLInputElement>,
+    clearFilters: HTMLElementProxy<FilterOfProductSearchViewState, HTMLButtonElement>,
+    priceRange: {
+      minPrice: HTMLElementProxy<PriceRangeOfFilterOfProductSearchViewState, HTMLInputElement>,
+      maxPrice: HTMLElementProxy<PriceRangeOfFilterOfProductSearchViewState, HTMLInputElement>,
+      ranges: {
+        isSelected: HTMLElementCollectionProxy<RangeOfPriceRangeOfFilterOfProductSearchViewState, HTMLInputElement>
+      }
+    },
+    categoryFilter: {
+      categories: {
+        isSelected: HTMLElementCollectionProxy<CategoryOfCategoryFilterOfFilterOfProductSearchViewState, HTMLInputElement>
+      }
+    }
+  },
+  sortBy: {
+    sortDropdown: HTMLElementProxy<SortByOfProductSearchViewState, HTMLSelectElement>
+  },
+  suggestions: {
+    suggestionButton: HTMLElementCollectionProxy<SuggestionOfProductSearchViewState, HTMLButtonElement>
+  }
+}
+
+/**
+ * Wix Store API Client Factories
+ *
+ * These functions create singleton instances of Wix API clients.
+ * Used by both the server service and client context.
+ *
+ * Note: Cart client is provided by @jay-framework/wix-cart package.
+ */
+
+/**
+ * Get a configured Wix Stores Products V3 client (singleton)
+ *
+ * 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
+ */
+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
+ */
+declare function getCategoriesClient(wixClient: WixClient): BuildDescriptors<typeof categories, {}>;
+/**
+ * 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
+ */
+declare function getInventoryClient(wixClient: WixClient): BuildDescriptors<typeof inventoryItemsV3, {}>;
+
+/**
+ * Maps a Wix root category to a URL prefix slug.
+ * Products belonging to any child of this category get URLs like /products/{prefix}/{slug}.
+ */
+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;
+}
+interface WixStoresService {
+    products: ReturnType<typeof getProductsV3Client>;
+    categories: ReturnType<typeof getCategoriesClient>;
+    inventory: ReturnType<typeof getInventoryClient>;
+    /** @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[];
+}
+/**
+ * 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[];
+}
+/**
+ * Creates, registers, and returns a Wix Stores service instance.
+ * Called during server initialization.
+ */
+declare function provideWixStoresService(wixClient: WixClient, options?: WixStoresServiceOptions): WixStoresService;
+
+/**
+ * Configuration passed from server to client for Wix Stores.
+ */
+interface WixStoresInitData {
+    /** Enable client-side cart operations */
+    enableClientCart: boolean;
+    /** Enable client-side search */
+    enableClientSearch: boolean;
+}
+/**
+ * Reactive cart indicator state.
+ * Signals update automatically when cart operations occur.
+ */
+interface ReactiveCartIndicator {
+    /** Number of items in cart (reactive signal) */
+    itemCount: Getter<number>;
+    /** Whether cart has items (reactive signal) */
+    hasItems: Getter<boolean>;
+}
+/**
+ * Result of a cart operation that modifies items.
+ */
+interface CartOperationResult {
+    /** Updated cart state after the operation */
+    cartState: CartState;
+}
+interface SelectedOptionsAndModifiers {
+    /** options as (option._id, choice.choiceId) pairs */
+    options: Record<string, string>;
+    /** modifiers as (modifier._id, choice.choiceId) pairs - translated to keys in addToCart */
+    modifiers: Record<string, string>;
+    /** custom text fields as (modifier._id, user input) pairs - translated to keys in addToCart */
+    customTextFields: Record<string, string>;
+}
+/**
+ * Client-side Wix Stores context interface.
+ * Provides reactive cart indicator (delegated to WIX_CART_CONTEXT) and stores-specific operations.
+ */
+interface WixStoresContext {
+    /**
+     * Reactive cart indicator signals.
+     * Use these in render functions for automatic updates.
+     */
+    cartIndicator: ReactiveCartIndicator;
+    refreshCartIndicator(): Promise<void>;
+    getEstimatedCart(): Promise<CartState>;
+    addToCart(productId: string, quantity?: number, selections?: SelectedOptionsAndModifiers): Promise<CartOperationResult>;
+    removeLineItems(lineItemIds: string[]): Promise<CartOperationResult>;
+    updateLineItemQuantity(lineItemId: string, quantity: number): Promise<CartOperationResult>;
+    clearCart(): Promise<void>;
+    applyCoupon(couponCode: string): Promise<CartOperationResult>;
+    removeCoupon(): Promise<CartOperationResult>;
+}
+/**
+ * Context marker for client-side Wix Stores operations.
+ */
+declare const WIX_STORES_CONTEXT: _jay_framework_runtime.ContextMarker<WixStoresContext>;
+
+/**
+ * URL parameters for product search routes.
+ * When used as a category listing, `category` is the prefix slug (e.g., 'polgat').
+ */
+interface ProductSearchParams extends UrlParams {
+    /** Category prefix slug. When present, scopes search to this category hierarchy. */
+    category?: string;
+}
+/**
+ * Search sort options
+ */
+type SearchSortOption = 'relevance' | 'priceAsc' | 'priceDesc' | 'newest' | 'nameAsc' | 'nameDesc';
+/**
+ * Category info carried forward from slow to fast phase
+ */
+type CategoryInfos = ProductSearchSlowViewState['filters']['categoryFilter']['categories'];
+/**
+ * Data carried forward from slow rendering to fast rendering
+ */
+interface SearchSlowCarryForward {
+    searchFields: string;
+    fuzzySearch: boolean;
+    categories: CategoryInfos;
+    /** Root category ID when scoped to a category prefix (always applied, hidden from UI) */
+    baseCategoryId: string | null;
+}
+/**
+ * Data carried forward from fast rendering to interactive phase
+ */
+interface SearchFastCarryForward {
+    searchFields: string;
+    fuzzySearch: boolean;
+    categories: CategoryInfos;
+    /** 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 enum MediaType {
+  IMAGE,
+  VIDEO
+}
+
+interface MediaViewState {
+  url: string,
+  mediaType: MediaType,
+  thumbnail_50x50: string
+}
+
+interface MediaRefs {}
+
+declare enum Selected {
+  selected,
+  notSelected
+}
+
+interface AvailableMediaOfMediaGalleryViewState {
+  mediaId: string,
+  media: MediaViewState,
+  selected: Selected
+}
+
+interface MediaGalleryViewState {
+  selectedMedia: MediaViewState,
+  availableMedia: Array<AvailableMediaOfMediaGalleryViewState>
+}
+
+
+interface MediaGalleryRefs {
+  selectedMedia: MediaRefs,
+  availableMedia: {
+    selected: HTMLElementCollectionProxy<AvailableMediaOfMediaGalleryViewState, HTMLImageElement | HTMLDivElement>,
+    media: MediaRefs
+  }
+}
+
+declare enum ProductType {
+  PHYSICAL,
+  DIGITAL
+}
+
+declare enum StockStatus {
+  OUT_OF_STOCK,
+  IN_STOCK
+}
+
+interface QuantityOfProductPageViewState {
+  quantity: number
+}
+
+declare enum OptionRenderType {
+  TEXT_CHOICES,
+  COLOR_SWATCH_CHOICES
+}
+
+interface ChoiceOfOptionOfProductPageViewState {
+  choiceId: string,
+  choiceType: ChoiceType,
+  name: string,
+  colorCode: string,
+  inStock: boolean,
+  isSelected: boolean
+}
+
+interface OptionOfProductPageViewState {
+  _id: string,
+  name: string,
+  optionRenderType: OptionRenderType,
+  textChoiceSelection: string,
+  choices: Array<ChoiceOfOptionOfProductPageViewState>
+}
+
+interface InfoSectionOfProductPageViewState {
+  _id: string,
+  title: string,
+  plainDescription: string
+}
+
+declare enum ModifierType {
+  TEXT_CHOICES,
+  COLOR_SWATCH_CHOICES,
+  FREE_TEXT
+}
+
+declare enum ChoiceType {
+  CHOICE_TEXT,
+  ONE_COLOR
+}
+
+declare enum ChoiceType {
+  CHOICE_TEXT,
+  ONE_COLOR
+}
+
+interface ChoiceOfModifierOfProductPageViewState {
+  choiceId: string,
+  choiceType: ChoiceType,
+  name: string,
+  colorCode: string,
+  isSelected: boolean
+}
+
+interface ModifierOfProductPageViewState {
+  _id: string,
+  name: string,
+  modifierType: ModifierType,
+  textModifierSelection: string,
+  textInputLength: number,
+  textInputRequired: boolean,
+  choices: Array<ChoiceOfModifierOfProductPageViewState>
+}
+
+interface PropOfTagOfSeoDatumOfProductPageViewState {
+  key: string,
+  value: string
+}
+
+interface MetaOfTagOfSeoDatumOfProductPageViewState {
+  key: string,
+  value: string
+}
+
+interface TagOfSeoDatumOfProductPageViewState {
+  position: string,
+  type: string,
+  props: Array<PropOfTagOfSeoDatumOfProductPageViewState>,
+  meta: Array<MetaOfTagOfSeoDatumOfProductPageViewState>,
+  children: string
+}
+
+interface KeywordOfSettingOfSeoDatumOfProductPageViewState {
+  term: string,
+  isMain: boolean,
+  origin: string
+}
+
+interface SettingOfSeoDatumOfProductPageViewState {
+  preventAutoRedirect: boolean,
+  keywords: Array<KeywordOfSettingOfSeoDatumOfProductPageViewState>
+}
+
+interface SeoDatumOfProductPageViewState {
+  tags: Array<TagOfSeoDatumOfProductPageViewState>,
+  settings: SettingOfSeoDatumOfProductPageViewState
+}
+
+interface ProductPageViewState {
+  _id: string,
+  productName: string,
+  mediaGallery: MediaGalleryViewState,
+  description: string,
+  brand: string,
+  ribbon: string,
+  productType: ProductType,
+  sku: string,
+  price: string,
+  strikethroughPrice: string,
+  pricePerUnit: string,
+  stockStatus: StockStatus,
+  quantity: QuantityOfProductPageViewState,
+  actionsEnabled: boolean,
+  options: Array<OptionOfProductPageViewState>,
+  infoSections: Array<InfoSectionOfProductPageViewState>,
+  modifiers: Array<ModifierOfProductPageViewState>,
+  seoData: SeoDatumOfProductPageViewState
+}
+
+type ProductPageSlowViewState = Pick<ProductPageViewState, '_id' | 'productName' | 'description' | 'brand' | 'ribbon' | 'productType'> & {
+    options: Array<Pick<ProductPageViewState['options'][number], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductPageViewState['options'][number]['choices'][number], 'choiceId' | 'choiceType' | 'name' | 'colorCode' | 'inStock'>>;
+}>;
+    infoSections: Array<ProductPageViewState['infoSections'][number]>;
+    modifiers: Array<Pick<ProductPageViewState['modifiers'][number], '_id' | 'name' | 'modifierType' | 'textInputLength' | 'textInputRequired'> & {
+    choices: Array<Pick<ProductPageViewState['modifiers'][number]['choices'][number], 'choiceId' | 'choiceType' | 'name' | 'colorCode'>>;
+}>;
+    seoData: ProductPageViewState['seoData'];
+};
+
+type ProductPageFastViewState = Pick<ProductPageViewState, 'sku' | 'price' | 'strikethroughPrice' | 'pricePerUnit' | 'stockStatus' | 'actionsEnabled'> & {
+    mediaGallery: ProductPageViewState['mediaGallery'];
+    quantity: ProductPageViewState['quantity'];
+    options: Array<Pick<ProductPageViewState['options'][number], '_id' | 'textChoiceSelection'> & {
+    choices: Array<Pick<ProductPageViewState['options'][number]['choices'][number], 'choiceId' | 'isSelected'>>;
+}>;
+    modifiers: Array<Pick<ProductPageViewState['modifiers'][number], '_id' | 'textModifierSelection'> & {
+    choices: Array<Pick<ProductPageViewState['modifiers'][number]['choices'][number], 'choiceId' | 'isSelected'>>;
+}>;
+};
+
+type ProductPageInteractiveViewState = Pick<ProductPageViewState, 'sku' | 'price' | 'strikethroughPrice' | 'pricePerUnit' | 'stockStatus' | 'actionsEnabled'> & {
+    mediaGallery: ProductPageViewState['mediaGallery'];
+    quantity: ProductPageViewState['quantity'];
+    options: Array<Pick<ProductPageViewState['options'][number], '_id' | 'textChoiceSelection'> & {
+    choices: Array<Pick<ProductPageViewState['options'][number]['choices'][number], 'choiceId' | 'isSelected'>>;
+}>;
+    modifiers: Array<Pick<ProductPageViewState['modifiers'][number], '_id' | 'textModifierSelection'> & {
+    choices: Array<Pick<ProductPageViewState['modifiers'][number]['choices'][number], 'choiceId' | 'isSelected'>>;
+}>;
+};
+
+
+interface ProductPageRefs {
+  addToCartButton: HTMLElementProxy<ProductPageViewState, HTMLButtonElement>,
+  buyNowButton: HTMLElementProxy<ProductPageViewState, HTMLButtonElement>,
+  mediaGallery: MediaGalleryRefs,
+  quantity: {
+    decrementButton: HTMLElementProxy<QuantityOfProductPageViewState, HTMLButtonElement>,
+    incrementButton: HTMLElementProxy<QuantityOfProductPageViewState, HTMLButtonElement>,
+    quantity: HTMLElementProxy<QuantityOfProductPageViewState, HTMLInputElement>
+  },
+  options: {
+    textChoice: HTMLElementCollectionProxy<OptionOfProductPageViewState, HTMLSelectElement>,
+    choices: {
+      choiceButton: HTMLElementCollectionProxy<ChoiceOfOptionOfProductPageViewState, HTMLButtonElement>
+    }
+  },
+  modifiers: {
+    textModifier: HTMLElementCollectionProxy<ModifierOfProductPageViewState, HTMLSelectElement>,
+    textInput: HTMLElementCollectionProxy<ModifierOfProductPageViewState, HTMLInputElement | HTMLAreaElement>,
+    choices: {
+      choiceButton: HTMLElementCollectionProxy<ChoiceOfModifierOfProductPageViewState, HTMLButtonElement>
+    }
+  }
+}
+
+/**
+ * URL parameters for product page routes.
+ * Supports /products/[slug] and /products/polgat/[slug] (category-prefixed).
+ */
+interface ProductPageParams extends UrlParams {
+    slug: string;
+    /** Category prefix from static route (e.g., 'polgat'). Undefined for unprefixed routes. */
+    category?: string;
+}
+interface InteractiveVariant {
+    _id: string;
+    sku: string;
+    price: string;
+    strikethroughPrice: string;
+    choices: OptionChoice[];
+    mediaId?: string;
+    inventoryStatus: StockStatus;
+}
+/**
+ * Data carried forward from slow rendering to fast rendering
+ */
+interface ProductSlowCarryForward {
+    productId: string;
+    mediaGallery: MediaGalleryViewState;
+    options: ProductPageFastViewState['options'];
+    modifiers: ProductPageFastViewState['modifiers'];
+    pricePerUnit: string;
+    stockStatus: StockStatus;
+    variants: InteractiveVariant[];
+}
+/**
+ * Data carried forward from fast rendering to interactive phase
+ */
+interface ProductFastCarryForward {
+    productId: string;
+    variants: InteractiveVariant[];
+}
+/**
+ * Product Page Full-Stack Component
+ *
+ * A complete headless product page component with server-side rendering,
+ * real-time inventory, and client-side interactivity.
+ *
+ * Usage:
+ * ```typescript
+ * import { productPage } from '@jay-framework/wix-stores';
+ *
+ * // The component will automatically load products and render pages
+ * ```
+ */
+declare const productPage: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductPageRefs, ProductPageSlowViewState, ProductPageFastViewState, ProductPageInteractiveViewState, [ProductSlowCarryForward, WixStoresService], [Signals<ProductPageFastViewState>, ProductFastCarryForward, WixStoresContext], PageProps & ProductPageParams, ProductPageParams, _jay_framework_component.JayComponentCore<PageProps & ProductPageParams, ProductPageInteractiveViewState>>;
+
+interface CategoryOfCategoryListViewState {
+  _id: string,
+  name: string,
+  slug: string,
+  description: string,
+  productCount: number,
+  imageUrl: string
+}
+
+interface CategoryListViewState {
+  categories: Array<CategoryOfCategoryListViewState>,
+  hasCategories: boolean
+}
+
+type CategoryListSlowViewState = Pick<CategoryListViewState, 'hasCategories'> & {
+    categories: Array<CategoryListViewState['categories'][number]>;
+};
+
+type CategoryListFastViewState = {};
+
+type CategoryListInteractiveViewState = {};
+
+
+interface CategoryListRefs {
+  categories: {
+    categoryLink: HTMLElementCollectionProxy<CategoryOfCategoryListViewState, HTMLAnchorElement>
+  }
+}
+
+/**
+ * Category List Full-Stack Component
+ *
+ * A headless component that displays a grid of store categories.
+ * Categories are loaded during slow rendering as they rarely change.
+ *
+ * Usage:
+ * ```html
+ * <script type="application/jay-headless"
+ *         plugin="@jay-framework/wix-stores"
+ *         contract="category-list"
+ *         key="categoryList"
+ * ></script>
+ *
+ * <div class="categories-grid">
+ *   <article forEach="categoryList.categories" trackBy="_id">
+ *     <a href="/categories/{slug}" ref="categoryList.categories.categoryLink">
+ *       <img src="{imageUrl}" alt="{name}" />
+ *       <h2>{name}</h2>
+ *       <span>{productCount} products</span>
+ *     </a>
+ *   </article>
+ * </div>
+ * ```
+ */
+declare const categoryList: _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState, [Record<string, never>, WixStoresService], [], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>> & {
+    withFastRender<NewCarryForward extends object>(fastRender: _jay_framework_fullstack_component.RenderFast<[Record<string, never>, WixStoresService], PageProps, CategoryListFastViewState, NewCarryForward>): _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState, [Record<string, never>, WixStoresService], [_jay_framework_fullstack_component.Signals<CategoryListFastViewState>, NewCarryForward], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>> & {
+        withClientDefaults(fn: (props: PageProps) => {
+            viewState: CategoryListFastViewState;
+            carryForward?: any;
+        }): _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState, [Record<string, never>, WixStoresService], [_jay_framework_fullstack_component.Signals<CategoryListFastViewState>, NewCarryForward], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>> & /*elided*/ any;
+        withInteractive(comp: _jay_framework_component.ComponentConstructor<PageProps, CategoryListRefs, CategoryListInteractiveViewState, [_jay_framework_fullstack_component.Signals<CategoryListFastViewState>, NewCarryForward], _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>>): _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState, [Record<string, never>, WixStoresService], [_jay_framework_fullstack_component.Signals<CategoryListFastViewState>, NewCarryForward], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>>;
+    };
+    withInteractive(comp: _jay_framework_component.ComponentConstructor<PageProps, CategoryListRefs, CategoryListInteractiveViewState, [], _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>>): _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryListRefs, CategoryListSlowViewState, CategoryListFastViewState, CategoryListInteractiveViewState, [Record<string, never>, WixStoresService], [], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CategoryListInteractiveViewState>>;
+};
+
+/**
+ * Sort options for product search
+ */
+type ProductSortField = 'relevance' | 'price_asc' | 'price_desc' | 'name_asc' | 'name_desc' | 'newest';
+/**
+ * Product search filters
+ */
+interface ProductSearchFilters {
+    /** Only show products in stock */
+    inStockOnly?: boolean;
+    /** Minimum price filter */
+    minPrice?: number;
+    /** Maximum price filter */
+    maxPrice?: number;
+    /** Filter by category IDs */
+    categoryIds?: string[];
+}
+/**
+ * Price range bucket for aggregation
+ */
+interface PriceRangeBucket {
+    rangeId: string;
+    label: string;
+    minValue: number | null;
+    maxValue: number | null;
+    productCount: number;
+    isSelected: boolean;
+}
+/**
+ * Price aggregation data from search
+ */
+interface PriceAggregationData {
+    /** Minimum price across all products */
+    minBound: number;
+    /** Maximum price across all products */
+    maxBound: number;
+    /** Price range buckets with product counts */
+    ranges: PriceRangeBucket[];
+}
+/**
+ * Input for searchProducts action
+ */
+interface SearchProductsInput {
+    /** Search query text */
+    query: string;
+    /** Filters to apply */
+    filters?: ProductSearchFilters;
+    /** Sort order */
+    sortBy?: ProductSortField;
+    /** Cursor for pagination (from previous response's nextCursor) */
+    cursor?: string;
+    /** Items per page (default: 12) */
+    pageSize?: number;
+}
+/**
+ * Output for searchProducts action
+ */
+interface SearchProductsOutput {
+    /** List of matching products */
+    products: ProductCardViewState[];
+    /** Total number of matching products */
+    totalCount: number;
+    /** Cursor for next page (null if no more results) */
+    nextCursor: string | null;
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Price aggregation data (bounds and ranges) */
+    priceAggregation?: PriceAggregationData;
+}
+/**
+ * Input for getProductBySlug action
+ */
+interface GetProductBySlugInput {
+    /** Product URL slug */
+    slug: string;
+}
+/**
+ * Search products using the Wix Stores Catalog V3 searchProducts API.
+ *
+ * Uses server-side filtering and sorting for optimal performance:
+ * - Text search on name and description
+ * - Price range filtering
+ * - Stock status filtering
+ * - Category filtering
+ * - Price/name/date sorting
+ *
+ * @see https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-v3/products-v3/search-products
+ *
+ * @example
+ * ```typescript
+ * const results = await searchProducts({
+ *     query: 'shoes',
+ *     filters: { inStockOnly: true, categoryIds: ['cat-123'] },
+ *     sortBy: 'price_asc',
+ *     pageSize: 12
+ * });
+ * ```
+ */
+declare const searchProducts: _jay_framework_fullstack_component.JayAction<SearchProductsInput, SearchProductsOutput> & _jay_framework_fullstack_component.JayActionDefinition<SearchProductsInput, SearchProductsOutput, [WixStoresService]>;
+/**
+ * Get a single product by its URL slug.
+ *
+ * @example
+ * ```typescript
+ * const product = await getProductBySlug({ slug: 'blue-sneakers' });
+ * ```
+ */
+declare const getProductBySlug: _jay_framework_fullstack_component.JayAction<GetProductBySlugInput, ProductCardViewState> & _jay_framework_fullstack_component.JayActionDefinition<GetProductBySlugInput, ProductCardViewState, [WixStoresService]>;
+/**
+ * Get available categories for filtering.
+ *
+ * @example
+ * ```typescript
+ * const categories = await getCategories();
+ * ```
+ */
+declare const getCategories: _jay_framework_fullstack_component.JayAction<Record<string, never>, {
+    categoryId: string;
+    categoryName: string;
+}[]> & _jay_framework_fullstack_component.JayActionDefinition<Record<string, never>, {
+    categoryId: string;
+    categoryName: string;
+}[], [WixStoresService]>;
+
+declare const init: _jay_framework_fullstack_component.JayInit<WixStoresInitData>;
+
+/**
+ * Setup handler for wix-stores plugin (Design Log #87, #10).
+ *
+ * Validates that wix-server-client is configured.
+ * Creates config/.wix-stores.yaml with example category prefix config if missing.
+ * Generates category tree reference for agent discovery.
+ */
+
+declare function setupWixStores(ctx: PluginSetupContext): Promise<PluginSetupResult>;
+/**
+ * Generate a YAML reference file with the full category tree.
+ * Shows all categories with IDs, names, product counts, and parent-child hierarchy.
+ */
+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 };