Reference

Quick-reference tables for all configuration options, API parameters, normalizers, and expected index fields.

Unified extension config

Options passed to createUnifiedExtension({ config: ... }). Controls normalization behavior.

Property	Type	Default	Description
`defaultCurrency`	`string`	`'USD'`	Fallback currency when the `vsf-currency` cookie is not set
`facetConfig`	`FacetConfigRule[]`	—	Declarative rules mapping facet names to storefront types
`facetFields`	`string[]`	—	Facet field names to request. Omit to request all available
`excludeFacets`	`string[]`	—	Facet names to exclude from the response
`facetFilterOperator`	`'AND' \| 'OR'`	`'OR'`	How multiple values within one facet are combined
`filterFacets`	`(facet) => boolean`	—	Dynamic filter callback for facets
`getFacetConfig`	`(facet) => FacetConfigRule`	—	Fallback when no `facetConfig` rule matches
`categoryRoot`	`string`	—	Root category ID for hierarchical category facets
`transformImageUrl`	`(url) => string`	—	Transform product image URLs (e.g. prepend a CDN host)

Property	Type	Default	Description
`names`	`string[]`	(required)	Facet field names this rule applies to
`type`	`string`	`'MULTI_SELECT'`	Storefront facet type: `'COLOR'`, `'SIZE'`, `'CATEGORY'`, `'PRICE'`, or custom
`range`	`boolean`	`false`	Set `true` for range facets (e.g. price)
`multiSelect`	`boolean`	`true`	Whether the facet supports multiple selections

Options under configuration.discoveryApi.search in the middleware config.

Property	Type	Default	Description
`currencies`	`string[]`	—	Indexed currencies. Adds `price_<currency>`, `sale_price_<currency>` fields to each request
`efq`	`string`	—	Static filter query applied to every search (e.g. `'availability:"In Stock"'`)
`facetVersion`	`string`	—	Set to `'3.0'` for structured facet responses from Bloomreach
`productFields`	`string[]`	—	Additional product fields to request beyond the defaults
`statsField`	`string`	—	Field for statistics aggregation

Placed inside the unified extension config. Run on every request.

Resolver	Signature	Description
`resolveDomainKey`	`(context) => string \| undefined`	Override `domain_key` per request. For locale-specific catalogs
`resolveViewId`	`(context) => string \| undefined`	Map locale + currency to a Bloomreach view
`resolveTrackingParams`	`(context) => { url?, refUrl?, brUid2? }`	Override tracking parameters extracted from cookies/headers

Resolver context provides:

Parameter	Type	Default	Description
`search`	`string`	`'*'`	Search query. Use `'*'` for all products
`category`	`string`	—	Category path filter
`facets`	`Record<string, string[]>`	—	Facet filters by field name
`sortBy`	`string`	—	Sort expression (e.g. `'price asc'`, `'title desc'`)
`pageSize`	`number`	`20`	Results per page
`currentPage`	`number`	`1`	Page number (1-indexed)
`efq`	`string`	—	Per-request filter query (overrides static `efq`)
`userId`	`string`	—	Customer ID for Bloomreach personalization

Endpoint	Response
`searchProducts`	`{ products: SfProductCatalogItem[], facets: SfFacet[], pagination: SfPagination }`
`getProductDetails`	`{ product: SfProduct, categoryHierarchy: SfCategory[] }`

Normalizer	Input	Output	Purpose
`normalizeProductCatalogItem`	Bloomreach product doc	`SfProductCatalogItem`	Product card data
`normalizeFacet`	Facet with values	`SfFacet`	Facet display and filtering
`normalizePagination`	`numFound`, `rows`, `start`	`SfPagination`	Page navigation
`normalizeMoney`	`number`	`SfMoney`	Price formatting
`normalizeDiscountablePrice`	`price`, `salePrice`	`SfDiscountablePrice`	Regular + sale price
`normalizeImage`	URL string	`SfImage`	Product images
`normalizeRating`	Bloomreach product doc	`SfProduct['rating']`	Product ratings

Core fields requested in every search and product detail call.

Field	Type	Required	Description
`pid`	`string`	Yes	Unique product identifier (also used as SKU and slug)
`title`	`string`	Yes	Product display name
`price`	`number`	Yes	Base product price
`sale_price`	`number`	Yes	Discounted price (set equal to `price` when no discount)
`thumb_image`	`string`	Yes	Primary product image URL
`url`	`string`	No	Product page URL
`description`	`string`	No	Product description (HTML allowed)
`brand`	`string`	No	Product brand name

Convention: price_<lowercase_currency_code>

Field	Type	Required	Description
`cat_id`	`string`	No	Category identifier (falls back to `cat_name`)
`cat_name`	`string`	Yes	Category display name
`parent`	`string`	No	Parent category ID (absent for top-level)
`count`	`number`	No	Number of products in this category

Read from the variants array on the product document.

Field	Type	Required	Description
`skuid`	`string`	No	SKU identifier
`sku_color_group`	`string`	No	Color/variant group name (displayed as "Color" attribute)
`sku_thumb_images`	`string[]`	No	Variant image URLs (merged into product gallery)