@behio/storefront-sdk 0.41.0 → 1.0.0

package/dist/react.d.mts

@@ -356,6 +356,14 @@ interface ProductVariant {
      * "default photo" or to render the picture in a subtler style.
      */
     imageIsInherited: boolean;
+    /**
+     * Parameters of this variant. A variant carries its own value where it has
+     * one and inherits the parent's everywhere else, so you can render the rows
+     * that actually differ under each variant. Empty when nothing is assigned.
+     *
+     * Added in SDK 1.0.0.
+     */
+    parameterGroups: ProductParameterGroup[];
 }
 interface ProductLabel {
     id: string;
@@ -411,6 +419,36 @@ interface ProductListItem {
      * disable the buy button, never re-derive the rule client-side.
      */
     isPurchasable: boolean;
+    /**
+     * The merchant sells this product ONLY through its variants: "Tričko" on its
+     * own means nothing, the shop sells the red one and the yellow one.
+     *
+     * The product keeps its card, its PDP and its search presence — it simply is
+     * not a sellable unit. `isPurchasable` is false and the cart/checkout reject
+     * its `id` with a 400, so the shopper must pick a variant first.
+     *
+     * When this is true, render the headline price as **"od {priceFrom}"** and
+     * keep the buy button disabled until a variant is chosen; then switch to that
+     * variant's own `price` and add `variant.id` to the cart. `price` still
+     * carries the parent's own number for backwards compatibility, but showing it
+     * as *the* price would quote 990 and charge 1990 — always label it "od".
+     *
+     * False for every product without variants, so nothing changes for shops that
+     * never turn it on.
+     */
+    variantsOnly: boolean;
+    /**
+     * "From" price: the CHEAPEST variant price, in the requested currency, or
+     * null when the product has no variants (or prices are gated behind login in
+     * B2B mode). Populated for EVERY variant parent, not only `variantsOnly`
+     * ones, so a card can render "od 990 Kč" whenever the template wants to.
+     *
+     * Computed over the same variant set the PDP lists (published, enabled
+     * variants) and deliberately IGNORING stock — a size selling out must not
+     * make the advertised price jump. `compareAtPrice` carries that same
+     * variant's strike-through price when it has one.
+     */
+    priceFrom?: ProductPrice | null;
     /**
      * Early bird (time-based launch price) is active: `price.amount` already IS
      * the discounted early-bird amount and the regular price sits in
@@ -539,25 +577,41 @@ interface VariantAxis {
     values: VariantAxisValue[];
 }
 /**
- * One custom-field (data-group value) rendered as a spec-table row. BOOLEAN
- * carries a typed `booleanValue` (value is null) so the storefront can localize
- * Ano/Ne; MONEY carries its currency in `unit`; PERCENTAGE carries "%" in
- * `unit`.
+ * One row of a curated parameter group.
+ *
+ * A parameter is something the merchant explicitly published: a label they
+ * wrote, a value resolved from a fixed string, a product field, or ONE named
+ * field of one warehouse data group. Nothing here reveals warehouse structure:
+ * no ids, no field keys, no internal types.
+ *
+ * `value` is null only for boolean parameters, where `booleanValue` carries the
+ * typed value so the storefront localizes Ano/Ne itself. A parameter with no
+ * value is omitted from the array rather than rendered as an empty row.
  */
-interface ProductCustomField {
-    key: string;
-    name: string;
-    /** TEXT | NUMBER | DECIMAL | BOOLEAN | DATE | TIME | DATETIME | PERCENTAGE | MONEY | ITEM_LIST | ... */
-    type: string;
+interface ProductParameter {
+    label: string;
     value: string | null;
     booleanValue: boolean | null;
+    /** "cm", "g", a currency code, "%"; null when the parameter has none. */
     unit: string | null;
 }
-/** A spec-table section (one inventory data group) with its fields. */
-interface ProductCustomFieldGroup {
-    key: string;
+/**
+ * One curated parameter group. A product can carry several, so a template can
+ * render one as a spec table and another as badges. Ordering is array order,
+ * both for the groups and for the parameters inside them.
+ */
+interface ProductParameterGroup {
+    /**
+     * Stable public identifier derived from the merchant's own group name
+     * ("Parametry oblečení" -> "parametry-obleceni"). Pass it to
+     * `catalog.getProductParameterGroup` to fetch just this group.
+     */
+    slug: string;
     name: string;
-    fields: ProductCustomField[];
+    parameters: ProductParameter[];
+}
+interface ProductParametersResponse {
+    groups: ProductParameterGroup[];
 }
 interface ProductDetail extends ProductListItem {
     longDescription?: string;
@@ -587,14 +641,15 @@ interface ProductDetail extends ProductListItem {
     variantAxes: VariantAxis[];
     volumePricing: ProductVolumePrice[];
     /**
-     * Structured product parameters from custom fields (inventory data groups),
-     * grouped into spec-table sections (GAP-12). Empty when the product has no
-     * data-group values. Distinct from `longDescription` (free HTML): this is
-     * machine-readable key/value data for a "Parametry" table + comparison
-     * engines. (Corrected from the old untyped `Record<string, unknown>` — the
-     * API never populated that; it now sends this structured shape.)
+     * Curated parameter groups, already resolved. Empty when the merchant
+     * assigned none. Distinct from `longDescription` (free HTML): this is
+     * machine-readable key/value data for a "Parametry" table, comparison
+     * engines and AEO.
+     *
+     * Replaced `customFields` in SDK 1.0.0. The old field returned raw warehouse
+     * data groups, which published internal bookkeeping nobody curated.
      */
-    customFields: ProductCustomFieldGroup[];
+    parameterGroups: ProductParameterGroup[];
     seo: {
         title?: string | null;
         description?: string | null;
@@ -701,13 +756,22 @@ interface CategoryDetail extends Category {
         ogImage?: string | null;
     };
 }
-type DataGroupFieldType = "TEXT" | "NUMBER" | "DECIMAL" | "BOOLEAN" | "DATE" | "TIME" | "DATETIME" | "PERCENTAGE" | "MONEY" | "ASSET" | "ITEM_LIST" | "DYNAMIC_NUMBER_CALCULATION_FROM_OTHERS";
+/**
+ * One available filter, derived from a curated parameter the merchant marked
+ * filterable. A visitor can therefore never filter by a field that does not
+ * appear in the product's parameters.
+ */
 interface FilterField {
+    /** Parameter slug. Pass it back in `ProductsQuery.parameters` or `facets`. */
     key: string;
+    /** Parameter label in the requested language. */
     name: string;
-    type: DataGroupFieldType | string;
-    groupKey: string;
+    /** How to render it: value list, numeric range, or yes/no. */
+    type: "enum" | "range" | "boolean" | string;
+    /** Slug of the parameter group this filter belongs to. */
+    groupSlug: string;
     groupName: string;
+    unit?: string | null;
     values?: string[];
 }
 interface FacetValue {
@@ -727,14 +791,14 @@ interface FacetRange {
     max: number | null;
 }
 interface Facet {
+    /** Parameter slug. Never a warehouse field key. */
     key: string;
     name: string;
     /** "enum" (checkboxes), "range" (slider) or "boolean". */
     type: "enum" | "range" | "boolean" | string;
-    groupKey: string;
+    /** Slug of the parameter group this facet belongs to. */
+    groupSlug: string;
     groupName: string;
-    /** Underlying data-group field type (TEXT, NUMBER, MONEY, ...). */
-    fieldType: string;
     /** enum/boolean facets: selectable values with counts. */
     values?: FacetValue[];
     /** range facets: numeric bounds within the current context. */
@@ -829,11 +893,17 @@ interface ProductsQuery {
     /** Minimum aggregate rating, e.g. 4 for "4 and up". */
     ratingMin?: number;
     search?: string;
-    /** Custom-field filters. A value may be an array = multi-select (OR within
-     *  the key), e.g. {"barva": ["cerna", "bila"]}. */
-    customFields?: Record<string, string | number | boolean | string[] | unknown>;
-    /** Slug-based facet selection for SEO URLs: facet key -> value slugs, e.g.
-     *  {"barva": ["cerna"]}. Resolved server-side to the underlying values. */
+    /**
+     * Parameter filters, keyed by PARAMETER SLUG. A value may be an array =
+     * multi-select (OR within the key), e.g. {"barva": ["cerna", "bila"]}.
+     * Range filters use the `_min` / `_max` suffix, e.g. {"hmotnost_min": 100}.
+     *
+     * Replaced `customFields` in SDK 1.0.0, which was keyed by a warehouse
+     * data-group field key.
+     */
+    parameters?: Record<string, string | number | boolean | string[] | unknown>;
+    /** Slug-based facet selection for SEO URLs: parameter slug -> value slugs,
+     *  e.g. {"barva": ["cerna"]}. Resolved server-side to the stored values. */
     facets?: Record<string, string[]>;
     /** Filter by specific product IDs (comma-separated in URL) */
     ids?: string[];
@@ -1172,7 +1242,10 @@ interface DigitalDownload {
     fileName: string;
     /** Localized product name the file belongs to (may be null). */
     productName: string | null;
-    /** Product slug for linking back to the PDP (may be null). */
+    /**
+     * Product slug for linking back to the PDP (may be null). Resolved the same
+     * way as everywhere else: per-locale slug first, then the product id.
+     */
     productSlug: string | null;
     fileSize: number;
     mimeType: string;
@@ -1194,7 +1267,10 @@ interface CourseListItem {
     courseId: string;
     /** Localized course (product) name, best-effort. */
     name: string | null;
-    /** Product slug for linking to the PDP. */
+    /**
+     * Product slug for linking to the PDP. Resolved the same way as in the
+     * catalog: per-locale slug first, then the product id.
+     */
     slug: string;
     imageUrl: string | null;
     totalLessons: number;
@@ -1246,6 +1322,7 @@ interface CourseModule {
 interface CourseDetail {
     courseId: string;
     name: string | null;
+    /** Product slug for linking to the PDP (resolved per-locale slug, else id). */
     slug: string;
     imageUrl: string | null;
     /** Welcome text shown at the top of the member area (markdown). */
@@ -1586,15 +1663,17 @@ interface Bundle {
     slug: string;
     name: string;
     description: string | null;
-    bundlePrice: number;
+    /** `null` when the eshop hides prices from guests and this visitor has no price entitlement. */
+    bundlePrice: number | null;
     currency: string;
     coverImage: string | null;
     endsAt: number | null;
-    itemsSum: number;
-    /** Absolute saving vs buying the components separately, in `currency`. */
-    savings: number;
-    /** Percentage saving, 0–100. 0 when `itemsSum` is zero. */
-    savingsPercent: number;
+    /** `null` when prices are hidden (see `bundlePrice`). */
+    itemsSum: number | null;
+    /** Absolute saving vs buying the components separately, in `currency`. `null` when prices are hidden. */
+    savings: number | null;
+    /** Percentage saving, 0–100. 0 when `itemsSum` is zero. `null` when prices are hidden. */
+    savingsPercent: number | null;
     /** Minimum bundles per order. Default 1. */
     minQuantity: number;
     /** Maximum bundles per order. `null` = uncapped. */
@@ -2298,15 +2377,42 @@ declare class CatalogModule {
         locale?: string;
         currency?: string;
     }): Promise<SdkResult<PaginatedResponse<ProductListItem>>>;
-    /** Get available filter fields for dynamic filter UI */
-    getFilters(): Promise<SdkResult<{
+    /**
+     * Available filters for a dynamic filter UI.
+     *
+     * Derived from curated PARAMETERS the merchant marked filterable, so a
+     * visitor can never filter by something that does not appear in the
+     * product's parameters. Labels are per language, hence `locale`.
+     */
+    getFilters(options?: {
+        locale?: string;
+    }): Promise<SdkResult<{
         filters: FilterField[];
     }>>;
     /**
-     * Facet groups + selection-aware counts for the current filter set (custom
-     * fields, labels, price, availability, rating, subcategories). Pass the SAME
-     * query you pass to `getProducts` (category, search, price, inStock, ratingMin,
-     * customFields, facets slugs, labels): counts for each facet are computed with
+     * Curated parameter groups of a product, already resolved (label, value,
+     * unit, order). Returns an ARRAY of groups so a template can lay them out
+     * however it likes: one group as a spec table, another as badges.
+     *
+     * A variant's own parameters ride along on `ProductDetail.variants[]`, so
+     * this call is for the parent product.
+     */
+    getProductParameters(slug: string, options?: {
+        locale?: string;
+    }): Promise<SdkResult<ProductParametersResponse>>;
+    /**
+     * One specific parameter group of a product, by its slug. 404 when the
+     * product does not have that group, which is deliberate: the caller asked
+     * for a named thing, so an empty array would hide a wrong slug.
+     */
+    getProductParameterGroup(slug: string, groupSlug: string, options?: {
+        locale?: string;
+    }): Promise<SdkResult<ProductParameterGroup>>;
+    /**
+     * Facet groups + selection-aware counts for the current filter set
+     * (parameters, labels, price, availability, rating, subcategories). Pass the
+     * SAME query you pass to `getProducts` (category, search, price, inStock,
+     * ratingMin, parameters, facets slugs, labels): counts are computed with
      * that facet excluded, and values that drop to 0 are still returned (render
      * them disabled). Use this to build an Alza-style filter sidebar.
      */
@@ -2926,6 +3032,8 @@ interface UseFeaturedOptions {
 declare function useFeatured(options?: UseFeaturedOptions): _tanstack_react_query.UseQueryResult<NoInfer<PaginatedResponse<ProductListItem>>, Error>;
 
 interface UseFiltersOptions {
+    /** Filter labels are per language; defaults to the shop's default language. */
+    locale?: string;
     enabled?: boolean;
 }
 declare function useFilters(options?: UseFiltersOptions): _tanstack_react_query.UseQueryResult<NoInfer<FilterField[]>, Error>;
@@ -2942,6 +3050,22 @@ interface UseFacetsOptions {
  */
 declare function useFacets(query?: ProductsQuery, options?: UseFacetsOptions): _tanstack_react_query.UseQueryResult<NoInfer<FacetsResponse>, Error>;
 
+interface UseProductParametersOptions {
+    locale?: string;
+    /** Fetch only this group (by its slug) instead of all of them. */
+    groupSlug?: string;
+    enabled?: boolean;
+}
+/**
+ * Curated parameter groups of a product.
+ *
+ * Prefer reading `product.parameterGroups` from `useProduct` when you already
+ * have the detail loaded; this hook is for the cases where you want the spec
+ * table (or one named group) on its own, e.g. a comparison table or a tab that
+ * loads lazily.
+ */
+declare function useProductParameters(slug: string, options?: UseProductParametersOptions): _tanstack_react_query.UseQueryResult<NoInfer<ProductParameterGroup[]>, Error>;
+
 interface UseSearchOptions {
     page?: number;
     limit?: number;
@@ -4315,4 +4439,4 @@ declare function revokeAnalyticsConsent(client: BehioStorefront): Promise<SdkRes
     success: boolean;
 }>>;
 
-export { type ActivePromotion, type AddToCartInput, type AnalyticsEventInput, type AuthTokens, BehioAnalyticsTracker, BehioApiError, BehioProvider, type BehioProviderProps, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, CurrencySwitcher, type CurrencySwitcherProps, type CurrencySwitcherRenderProps, type CustomerAddress, type CustomerProfile, type EcommerceEventName, type EcommerceItem, type EcommercePayload, type FilterField, type FulfillmentStatus, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, type PersonalOffer, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, type ProductVariant, type ProductsQuery, type QuoteRequest, type RegisterInput, type ReturnRequest, type ShopInfo, type ShopSeo, type StorageAdapter, StorefrontScripts, type StorefrontScriptsProps, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type UseAddressAutocompleteOptions, type UseAddressAutocompleteReturn, type UseAddressesOptions, type UseCartCountOptions, type UseCartOptions, type UseCategoriesOptions, type UseCategoryOptions, type UseCertificateVerificationOptions, type UseCourseCertificatesOptions, type UseCourseOptions, type UseCoursesOptions, type UseCurrencyResult, type UseCustomerOptions, type UseFacetsOptions, type UseFeaturedOptions, type UseFiltersOptions, type UseLabelsOptions, type UseLessonCommentsOptions, type UseLessonNoteOptions, type UseLessonQuizOptions, type UseLessonTutorOptions, type UseLoyaltyOptions, type UseMenuOptions, type UseOrderOptions, type UseOrdersOptions, type UsePageOptions, type UsePagesOptions, type UsePaymentMethodsOptions, type UsePersonalOffersOptions, type UseProductOptions, type UseProductsOptions, type UseSearchOptions, type UseShippingMethodsOptions, type UseShippingQuoteOptions, type UseShopInfoOptions, type UseShopScriptsOptions, type UseShopSeoOptions, type UseSubscriptionsOptions, type WishlistItem, cookieStorage, createMemoryStorage, detectStorage, formatPrice, generateVisitorId, getStoredVisitorId, grantAnalyticsConsent, localStorageAdapter, memoryStorage, revokeAnalyticsConsent, trackEcommerceEvent, useAddressAutocomplete, useAddresses, useAnalyticsEvents, useAuth, useBehio, useBehioClient, useBundle, useBundles, useCart, useCartCount, useCategories, useCategory, useCertificateVerification, useCheckout, useCookieConsent, useCourse, useCourseCertificates, useCourses, useCrossSell, useCurrency, useCustomer, useFacets, useFeatured, useFilters, useGiftCardBalance, useIsInWishlist, useLabels, useLessonComments, useLessonNote, useLessonQuiz, useLessonTutor, useLookupReturnableOrder, useLoyalty, useMenu, useNewsletterSubscribe, useNewsletterUnsubscribe, useNotifyWhenAvailable, useOrder, useOrderAccess, useOrders, usePage, usePages, usePaymentMethods, usePersonalOffers, usePickupPoints, useProduct, useProductGroup, useProductPromotions, useProductReviews, useProducts, useQuoteStatus, useReturnStatus, useSearch, useShippingMethods, useShippingQuote, useShopInfo, useShopScripts, useShopSeo, useSubmitQuote, useSubmitReturn, useSubmitReview, useSubscriptions, useWishlist };
+export { type ActivePromotion, type AddToCartInput, type AnalyticsEventInput, type AuthTokens, BehioAnalyticsTracker, BehioApiError, BehioProvider, type BehioProviderProps, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, CurrencySwitcher, type CurrencySwitcherProps, type CurrencySwitcherRenderProps, type CustomerAddress, type CustomerProfile, type EcommerceEventName, type EcommerceItem, type EcommercePayload, type Facet, type FacetRange, type FacetValue, type FacetsResponse, type FilterField, type FulfillmentStatus, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, type PersonalOffer, type ProductDetail, type ProductLabel, type ProductListItem, type ProductParameter, type ProductParameterGroup, type ProductParametersResponse, type ProductPrice, type ProductReview, type ProductReviewsResponse, type ProductVariant, type ProductsQuery, type QuoteRequest, type RegisterInput, type ReturnRequest, type ShopInfo, type ShopSeo, type StorageAdapter, StorefrontScripts, type StorefrontScriptsProps, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type UseAddressAutocompleteOptions, type UseAddressAutocompleteReturn, type UseAddressesOptions, type UseCartCountOptions, type UseCartOptions, type UseCategoriesOptions, type UseCategoryOptions, type UseCertificateVerificationOptions, type UseCourseCertificatesOptions, type UseCourseOptions, type UseCoursesOptions, type UseCurrencyResult, type UseCustomerOptions, type UseFacetsOptions, type UseFeaturedOptions, type UseFiltersOptions, type UseLabelsOptions, type UseLessonCommentsOptions, type UseLessonNoteOptions, type UseLessonQuizOptions, type UseLessonTutorOptions, type UseLoyaltyOptions, type UseMenuOptions, type UseOrderOptions, type UseOrdersOptions, type UsePageOptions, type UsePagesOptions, type UsePaymentMethodsOptions, type UsePersonalOffersOptions, type UseProductOptions, type UseProductParametersOptions, type UseProductsOptions, type UseSearchOptions, type UseShippingMethodsOptions, type UseShippingQuoteOptions, type UseShopInfoOptions, type UseShopScriptsOptions, type UseShopSeoOptions, type UseSubscriptionsOptions, type WishlistItem, cookieStorage, createMemoryStorage, detectStorage, formatPrice, generateVisitorId, getStoredVisitorId, grantAnalyticsConsent, localStorageAdapter, memoryStorage, revokeAnalyticsConsent, trackEcommerceEvent, useAddressAutocomplete, useAddresses, useAnalyticsEvents, useAuth, useBehio, useBehioClient, useBundle, useBundles, useCart, useCartCount, useCategories, useCategory, useCertificateVerification, useCheckout, useCookieConsent, useCourse, useCourseCertificates, useCourses, useCrossSell, useCurrency, useCustomer, useFacets, useFeatured, useFilters, useGiftCardBalance, useIsInWishlist, useLabels, useLessonComments, useLessonNote, useLessonQuiz, useLessonTutor, useLookupReturnableOrder, useLoyalty, useMenu, useNewsletterSubscribe, useNewsletterUnsubscribe, useNotifyWhenAvailable, useOrder, useOrderAccess, useOrders, usePage, usePages, usePaymentMethods, usePersonalOffers, usePickupPoints, useProduct, useProductGroup, useProductParameters, useProductPromotions, useProductReviews, useProducts, useQuoteStatus, useReturnStatus, useSearch, useShippingMethods, useShippingQuote, useShopInfo, useShopScripts, useShopSeo, useSubmitQuote, useSubmitReturn, useSubmitReview, useSubscriptions, useWishlist };