@behio/storefront-sdk 0.42.0 → 1.1.0

package/dist/react.d.ts

@@ -327,7 +327,55 @@ interface ProductVariant {
      */
     id: string;
     sku: string;
+    /**
+     * Variant name in the requested locale. Before SDK 1.1.0 this was always the
+     * warehouse item name, so translated shops showed one language to everyone.
+     */
     name: string;
+    /**
+     * Deep-link token for this variant — NOT a URL of its own.
+     *
+     * A variant has no standalone product page: the catalog 404s its slug and
+     * every listing excludes it, because a variant is bought from the parent's
+     * detail page. Link to `/product/{product.slug}?variant={variant.variantSlug}`
+     * and preselect the variant from that query parameter.
+     *
+     * Added in SDK 1.1.0.
+     */
+    variantSlug: string;
+    /**
+     * Short description of THIS variant, or `null` when the merchant left it
+     * empty. `null` means INHERIT: fall back to `ProductDetail.shortDescription`
+     * instead of rendering an empty block. Sanitised HTML.
+     *
+     * Added in SDK 1.1.0.
+     */
+    shortDescription?: string | null;
+    /** Long description of THIS variant. Same inherit-on-null contract as
+     *  `shortDescription`. Added in SDK 1.1.0. */
+    longDescription?: string | null;
+    /**
+     * Gallery of THIS variant, ordered. Empty means the variant has no photos of
+     * its own, so keep showing the parent's gallery.
+     *
+     * Added in SDK 1.1.0.
+     */
+    images: ProductDetail["images"];
+    /**
+     * Per-variant SEO/OG overrides, or `null` when the merchant wrote none. The
+     * canonical URL stays the parent's, so use these only when a variant is
+     * preselected via `?variant=`.
+     *
+     * Added in SDK 1.1.0.
+     */
+    seo?: {
+        title?: string | null;
+        description?: string | null;
+        keywords?: string | null;
+        ogTitle?: string | null;
+        ogDescription?: string | null;
+        ogImage?: string | null;
+    } | null;
     /**
      * Axis name/value pairs identifying this variant (e.g.
      * `[{name: 'Barva', value: 'červená'}]`) — matches the wire shape the API
@@ -356,6 +404,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;
@@ -569,25 +625,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;
@@ -617,14 +689,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;
@@ -731,13 +804,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 {
@@ -757,14 +839,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. */
@@ -859,11 +941,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[];
@@ -908,7 +996,22 @@ interface LoginInput {
     password: string;
 }
 interface CartItemProduct {
+    /**
+     * Slug of the page this line links to. For a variant line this is the
+     * PARENT's slug: a variant has no page of its own, so linking to its own slug
+     * landed customers on a 404 (fixed 2026-08-03, SDK 1.1.0).
+     */
     slug: string;
+    /**
+     * Deep-link token of the variant on this line, `null` for a plain product.
+     * Build the link as `/product/{slug}?variant={variantSlug}` so the customer
+     * returns to the exact variant sitting in their cart.
+     *
+     * Added in SDK 1.1.0.
+     */
+    variantSlug?: string | null;
+    /** Product name in the CART's language. Before SDK 1.1.0 the API picked an
+     *  arbitrary translation row, so this could come back in another language. */
     name: string;
     sku: string;
     imageUrl?: string;
@@ -1202,7 +1305,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;
@@ -1224,7 +1330,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;
@@ -1276,6 +1385,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). */
@@ -1616,15 +1726,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. */
@@ -2328,15 +2440,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.
      */
@@ -2956,6 +3095,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>;
@@ -2972,6 +3113,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;
@@ -4345,4 +4502,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 };