@coveo/headless 3.29.1 → 3.29.2-pre.0e2721db97

package/dist/definitions/ssr-next/{common → search}/types/hydrate-static-state.d.ts

@@ -1,17 +1,16 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
 import type { CoreEngine, CoreEngineNext } from '../../../app/engine.js';
-import type { ControllersMap, ControllersPropsMap } from './controllers.js';
-import type { EngineDefinitionBuildResult, EngineDefinitionControllersPropsOption } from './engine.js';
-import type { OptionsTuple } from './utilities.js';
+import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
+import type { OptionsTuple } from '../../common/types/utilities.js';
+import type { SearchEngineDefinitionBuildResult, SearchEngineDefinitionControllersPropsOption } from './engine.js';
+export type HydratedState<TEngine extends CoreEngine | CoreEngineNext, TControllers extends ControllersMap> = SearchEngineDefinitionBuildResult<TEngine, TControllers>;
 interface HydrateStaticStateOptions<TSearchAction> {
     searchAction: TSearchAction;
 }
-export interface HydratedState<TEngine extends CoreEngine | CoreEngineNext, TControllers extends ControllersMap> extends EngineDefinitionBuildResult<TEngine, TControllers> {
-}
 /**
  * Creates a new engine from the snapshot of the engine created in SSR with fetchStaticState.
  *
  * Useful when hydrating a server-side-rendered engine.
  */
-export type HydrateStaticState<TEngine extends CoreEngine | CoreEngineNext, TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap> = (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & EngineDefinitionControllersPropsOption<TControllersProps>>) => Promise<HydratedState<TEngine, TControllers>>;
+export type HydrateStaticState<TEngine extends CoreEngine | CoreEngineNext, TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap> = (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & SearchEngineDefinitionControllersPropsOption<TControllersProps>>) => Promise<HydratedState<TEngine, TControllers>>;
 export {};

package/dist/definitions/ssr-next.index.d.ts

@@ -58,9 +58,6 @@ export { getSampleSearchEngineConfiguration } from './app/search-engine/search-e
 export type { ErrorPayload } from './controllers/controller/error-payload.js';
 export type { Controller, Subscribable, } from './controllers/controller/headless-controller.js';
 export type { InlineLink } from './controllers/smart-snippet/headless-smart-snippet-interactive-inline-links.js';
-export type { ControllerDefinitionsMap, ControllerDefinitionWithoutProps, ControllerDefinitionWithProps, } from './ssr-next/common/types/controllers.js';
-export type { EngineDefinition, InferHydratedState, InferStaticState, } from './ssr-next/common/types/engine.js';
-export type { InferControllerFromDefinition, InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers, InferControllerStaticStateMapFromDefinitions, InferControllersMapFromDefinition, } from './ssr-next/common/types/inference.js';
 export type { AutomaticFacetBreadcrumb, Breadcrumb, BreadcrumbManager, BreadcrumbManagerDefinition, BreadcrumbManagerState, BreadcrumbValue, CategoryFacetBreadcrumb, CoreBreadcrumbManager, CoreBreadcrumbManagerState, DateFacetBreadcrumb, DeselectableValue, FacetBreadcrumb, NumericFacetBreadcrumb, StaticFilterBreadcrumb, } from './ssr-next/search/controllers/breadcrumb-manager/headless-breadcrumb-manager.ssr.js';
 export { defineBreadcrumbManager } from './ssr-next/search/controllers/breadcrumb-manager/headless-breadcrumb-manager.ssr.js';
 export type { Context, ContextDefinition, ContextInitialState, ContextPayload, ContextProps, ContextState, ContextValue, } from './ssr-next/search/controllers/context/headless-context.ssr.js';
@@ -143,8 +140,13 @@ export type { RedirectionTrigger, RedirectionTriggerDefinition, RedirectionTrigg
 export { defineRedirectionTrigger } from './ssr-next/search/controllers/triggers/headless-redirection-trigger.ssr.js';
 export type { UrlManager, UrlManagerBuildProps, UrlManagerInitialState, UrlManagerProps, UrlManagerState, } from './ssr-next/search/controllers/url-manager/headless-url-manager.ssr.js';
 export { defineUrlManager } from './ssr-next/search/controllers/url-manager/headless-url-manager.ssr.js';
-export type { SearchCompletedAction, SearchEngineDefinition, SearchEngineDefinitionOptions, SSRSearchEngine as SearchEngine, } from './ssr-next/search/engine/search-engine.ssr.js';
+export type { SearchCompletedAction, SSRSearchEngine as SearchEngine, } from './ssr-next/search/engine/search-engine.ssr.js';
 export { defineSearchEngine } from './ssr-next/search/engine/search-engine.ssr.js';
+export type { ControllerDefinitionsMap, InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers, InferHydratedState, InferStaticState, } from './ssr-next/search/types/controller-definition.js';
+export type { InferControllerFromDefinition, InferControllerStaticStateMapFromDefinitions, InferControllersMapFromDefinition, } from './ssr-next/search/types/controller-inference.js';
+export type { SearchEngineDefinition, SearchEngineDefinitionOptions, } from './ssr-next/search/types/engine.js';
+export type { FetchStaticState } from './ssr-next/search/types/fetch-static-state.js';
+export type { HydratedState, HydrateStaticState, } from './ssr-next/search/types/hydrate-static-state.js';
 export type { SearchAppState, SearchParametersState, } from './state/search-app-state.js';
 export { getAnalyticsNextApiBaseUrl, getOrganizationEndpoint, } from './api/platform-client.js';
 export type { RelativeDate, RelativeDatePeriod, RelativeDateUnit, } from './api/search/date/relative-date.js';

package/dist/definitions/test/mock-ssr-controller-definitions.d.ts

@@ -1,7 +1,8 @@
 import type { SearchEngine } from '../app/search-engine/search-engine.js';
 import type { Controller } from '../controllers/controller/headless-controller.js';
 import type { Kind } from '../ssr/commerce/types/kind.js';
-import type { ControllerDefinitionWithoutProps, ControllerDefinitionWithProps } from '../ssr-next/common/types/controllers.js';
+import type { ControllerDefinitionWithoutProps, ControllerDefinitionWithProps } from '../ssr/common/types/controllers.js';
+import { recommendationInternalOptionKey } from '../ssr-next/commerce/types/controller-constants.js';
 interface MockController {
     initialState?: Record<string, unknown>;
 }
@@ -35,4 +36,15 @@ export declare function defineMockCommerceControllerWithProps(options?: Solution
     standalone: boolean;
     recommendation: boolean;
 };
+export declare function defineMockRecommendationDefinition(slotId: string): {
+    recommendation: boolean;
+    [recommendationInternalOptionKey]: {
+        slotId: string;
+    };
+    buildWithProps: import("vitest").Mock<(engine: any, props: any) => {
+        state: {};
+        subscribe(listener: () => void): import("redux").Unsubscribe;
+        _kind: Kind;
+    }>;
+};
 export {};

package/dist/esm/ssr-next/commerce/controller-utils.js

@@ -1,7 +1,6 @@
 import { clone, filterObject, mapObject } from '../../utils/utils.js';
 import { ControllerBuilder } from '../common/builders/controller-builder.js';
 import { createStaticControllerBuilder } from '../common/builders/static-controller-builder.js';
-import { InvalidControllerDefinition } from '../common/errors.js';
 export function createStaticState({ searchActions, controllers, }) {
     return {
         controllers: mapObject(controllers, (controller) => createStaticControllerBuilder(controller).build()),
@@ -23,8 +22,3 @@ export function buildControllerDefinitions({ definitionsMap, engine, solutionTyp
     });
     return filterObject(controllerMap, (value) => value !== null);
 }
-export function ensureAtLeastOneSolutionType(options) {
-    if (options?.listing === false && options?.search === false) {
-        throw new InvalidControllerDefinition();
-    }
-}

package/dist/esm/ssr-next/commerce/controllers/breadcrumb-manager/headless-core-breadcrumb-manager.ssr.js

@@ -1,6 +1,5 @@
 import { buildProductListing } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch } from '../../../../controllers/commerce/search/headless-search.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * Defines a `BreadcrumbManager` controller instance.
@@ -8,12 +7,10 @@ import { SolutionType } from '../../types/controller-constants.js';
  *
  * @returns The `BreadcrumbManager` controller definition.
  */
-export function defineBreadcrumbManager(options) {
-    ensureAtLeastOneSolutionType(options);
+export function defineBreadcrumbManager() {
     return {
         listing: true,
         search: true,
-        ...options,
         build: (engine, solutionType) => solutionType === SolutionType.listing
             ? buildProductListing(engine).breadcrumbManager()
             : buildSearch(engine).breadcrumbManager(),

package/dist/esm/ssr-next/commerce/controllers/generator/headless-commerce-facet-generator.ssr.js

@@ -14,18 +14,15 @@ import { manualNumericFacetSelector } from '../../../../features/commerce/facets
 import { manualNumericFacetReducer as manualNumericFacetSet } from '../../../../features/commerce/facets/numeric-facet/manual-numeric-facet-slice.js';
 import { categoryFacetSearchStateSelector } from '../../../../features/facets/facet-search-set/category/category-facet-search-state-selector.js';
 import { specificFacetSearchStateSelector } from '../../../../features/facets/facet-search-set/specific/specific-facet-search-state-selector.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { loadReducerError } from '../../../../utils/errors.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * @group Definers
  */
-export function defineFacetGenerator(options) {
-    ensureAtLeastOneSolutionType(options);
+export function defineFacetGenerator() {
     return {
         listing: true,
         search: true,
-        ...options,
         build: (engine, solutionType) => buildFacetGenerator(engine, { props: { solutionType: solutionType } }),
     };
 }

package/dist/esm/ssr-next/commerce/controllers/pagination/headless-core-commerce-pagination.ssr.js

@@ -1,6 +1,5 @@
 import { buildProductListing } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch } from '../../../../controllers/commerce/search/headless-search.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * Defines a `Pagination` controller instance.
@@ -10,7 +9,6 @@ import { SolutionType } from '../../types/controller-constants.js';
  * @returns The `Pagination` controller definition.
  */
 export function definePagination(props) {
-    ensureAtLeastOneSolutionType(props);
     return {
         listing: true,
         search: true,

package/dist/esm/ssr-next/commerce/controllers/parameter-manager/headless-core-parameter-manager.ssr.js

@@ -8,7 +8,6 @@ import { queryReducer as query } from '../../../../features/commerce/query/query
 import { sortReducer as commerceSort } from '../../../../features/commerce/sort/sort-slice.js';
 import { facetOrderReducer as facetOrder } from '../../../../features/facets/facet-order/facet-order-slice.js';
 import { querySetReducer as querySet } from '../../../../features/query-set/query-set-slice.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { loadReducerError } from '../../../../utils/errors.js';
 import { SolutionType } from '../../types/controller-constants.js';
 import { createControllerWithKind, Kind } from '../../types/kind.js';
@@ -18,12 +17,10 @@ import { createControllerWithKind, Kind } from '../../types/kind.js';
  *
  * @returns The `ParameterManager` controller definition.
  */
-export function defineParameterManager(options) {
-    ensureAtLeastOneSolutionType(options);
+export function defineParameterManager() {
     return {
         listing: true,
         search: true,
-        ...options,
         buildWithProps: (engine, props, solutionType) => {
             if (solutionType === SolutionType.listing) {
                 if (!loadCommerceProductListingParameterReducers(engine)) {

package/dist/esm/ssr-next/commerce/controllers/product-list/headless-product-list.ssr.js

@@ -1,6 +1,5 @@
 import { buildProductListing, } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch, } from '../../../../controllers/commerce/search/headless-search.js';
-import { ensureAtLeastOneSolutionType } from '../../controller-utils.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * Defines a `ProductList` controller instance.
@@ -8,12 +7,10 @@ import { SolutionType } from '../../types/controller-constants.js';
  *
  * @returns The `ProductList` controller definition.
  */
-export function defineProductList(options) {
-    ensureAtLeastOneSolutionType(options);
+export function defineProductList() {
     return {
         listing: true,
         search: true,
-        ...options,
         build: (engine, solutionType) => solutionType === SolutionType.listing
             ? buildProductListing(engine)
             : buildSearch(engine),

package/dist/esm/ssr-next/commerce/controllers/recommendations/headless-recommendations.ssr.js

@@ -17,7 +17,7 @@ export function defineRecommendations(props) {
         buildWithProps: (engine, options) => {
             const staticOptions = props.options;
             const controller = buildRecommendations(engine, {
-                options: { ...staticOptions, ...options },
+                options: { ...staticOptions, ...options.initialState },
             });
             return createControllerWithKind(controller, Kind.Recommendations);
         },

package/dist/esm/ssr-next/commerce/controllers/sort/headless-core-commerce-sort.ssr.js

@@ -1,6 +1,5 @@
 import { buildProductListing } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch } from '../../../../controllers/commerce/search/headless-search.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * Defines a `Sort` controller instance.
@@ -10,7 +9,6 @@ import { SolutionType } from '../../types/controller-constants.js';
  * @returns The `Sort` controller definition.
  */
 export function defineSort(props) {
-    ensureAtLeastOneSolutionType(props);
     return {
         listing: true,
         search: true,

package/dist/esm/ssr-next/commerce/controllers/summary/headless-core-summary.ssr.js

@@ -1,6 +1,5 @@
 import { buildProductListing } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch } from '../../../../controllers/commerce/search/headless-search.js';
-import { ensureAtLeastOneSolutionType } from '../../../../ssr/commerce/controller-utils.js';
 import { SolutionType } from '../../types/controller-constants.js';
 /**
  * Defines a `Summary` controller instance.
@@ -8,12 +7,10 @@ import { SolutionType } from '../../types/controller-constants.js';
  *
  * @returns The `Summary` controller definition.
  */
-export function defineSummary(options) {
-    ensureAtLeastOneSolutionType(options);
+export function defineSummary() {
     return {
         listing: true,
         search: true,
-        ...options,
         build: (engine, solutionType) => solutionType === SolutionType.listing
             ? buildProductListing(engine).summary()
             : buildSearch(engine).summary(),

package/dist/esm/ssr-next/commerce/factories/build-factory.js

@@ -57,21 +57,16 @@ function buildSSRCommerceEngine(solutionType, options, recommendationCount) {
         },
     };
 }
-function fetchActiveRecommendationControllers(controllerProps, solutionType) {
-    return solutionType === SolutionType.recommendation
-        ? Object.values(controllerProps).filter((controller) => controller &&
-            typeof controller === 'object' &&
-            'enabled' in controller &&
-            controller.enabled).length
-        : 0;
-}
 export const buildFactory = (controllerDefinitions, options) => (solutionType) => async (...[buildOptions]) => {
     const controllerProps = wireControllerParams(solutionType, controllerDefinitions, buildOptions); // TODO: KIT-4754: remove non-null assertion operator
     const logger = buildLogger(options.loggerOptions);
     if (!options.navigatorContextProvider) {
         logger.warn('[WARNING] Missing navigator context in server-side code. Make sure to set it with `setNavigatorContextProvider` before calling fetchStaticState()');
     }
-    const enabledRecommendationControllers = fetchActiveRecommendationControllers(controllerProps, solutionType);
+    const enabledRecommendationControllers = buildOptions && 'recommendations' in buildOptions // TODO: KIT-4754: remove non-null assertion
+        ? buildOptions
+            ?.recommendations.length
+        : 0;
     const engineOptions = {
         ...options,
         configuration: extendEngineConfiguration(options.configuration, buildOptions), // TODO: KIT-4754: remove non-null assertion operator

package/dist/esm/ssr-next/commerce/factories/hydrated-state-factory.js

@@ -1,10 +1,8 @@
-import { buildFactory, } from './build-factory.js';
+import { buildFactory } from './build-factory.js';
 export function hydratedStaticStateFactory(controllerDefinitions, options) {
     return (solutionType) => async (...params) => {
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(solutionType);
-        const { engine, controllers } = await solutionTypeBuild(
-        // @ts-expect-error: TODO: KIT-4742: the wiring will fix also the type inconsistencies
-        ...params);
+        const { engine, controllers } = await solutionTypeBuild(...params);
         params[0].searchActions.forEach((action) => {
             engine.dispatch(action);
         });

package/dist/esm/ssr-next/commerce/factories/recommendation-hydrated-state-factory.js

@@ -1,11 +1,9 @@
 import { SolutionType } from '../types/controller-constants.js';
-import { buildFactory, } from './build-factory.js';
+import { buildFactory } from './build-factory.js';
 export function hydratedRecommendationStaticStateFactory(controllerDefinitions, options) {
     return async (...params) => {
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(SolutionType.recommendation);
-        const { engine, controllers } = (await solutionTypeBuild(
-        // @ts-expect-error: TODO: KIT-4742: the wiring will fix also the type inconsistencies
-        ...params));
+        const { engine, controllers } = (await solutionTypeBuild(...params));
         params[0].searchActions.forEach((action) => {
             engine.dispatch(action);
         });

package/dist/esm/ssr-next/commerce/factories/recommendation-static-state-factory.js

@@ -1,26 +1,22 @@
-import { filterObject } from '../../../utils/utils.js';
 import { createStaticState } from '../controller-utils.js';
 import { SolutionType } from '../types/controller-constants.js';
 import { filterRecommendationControllers } from '../utils/recommendation-filter.js';
-import { buildFactory, } from './build-factory.js';
+import { buildFactory } from './build-factory.js';
 export function fetchRecommendationStaticStateFactory(controllerDefinitions, options) {
-    const getAllowedRecommendationKeys = (props) => {
-        if (props && 'controllers' in props) {
-            const enabledRecommendationControllers = filterObject(props.controllers, (value) => Boolean(value.enabled));
-            return Object.keys(enabledRecommendationControllers);
-        }
-        return [];
-    };
     return async (...params) => {
         const [props] = params;
-        const allowedRecommendationKeys = getAllowedRecommendationKeys(props);
+        const allowedRecommendationKeys = props.recommendations;
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(SolutionType.recommendation);
         const { engine, controllers } = (await solutionTypeBuild(...params));
         filterRecommendationControllers(controllers, controllerDefinitions ?? {}).refresh(allowedRecommendationKeys);
         const searchActions = await Promise.all(engine.waitForRequestCompletedAction());
-        return createStaticState({
+        const staticState = createStaticState({
             searchActions,
             controllers,
         });
+        return {
+            ...params[0], // TODO: KIT-4754: remove index access after no longer relying on OptionTuple type
+            ...staticState,
+        };
     };
 }

package/dist/esm/ssr-next/commerce/factories/static-state-factory.js

@@ -3,7 +3,7 @@ import { buildSearch } from '../../../controllers/commerce/search/headless-searc
 import { augmentPreprocessRequestWithForwardedFor } from '../../common/augment-preprocess-request.js';
 import { createStaticState } from '../controller-utils.js';
 import { SolutionType } from '../types/controller-constants.js';
-import { buildFactory, } from './build-factory.js';
+import { buildFactory } from './build-factory.js';
 export function fetchStaticStateFactory(controllerDefinitions, options) {
     return (solutionType) => async (...params) => {
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(solutionType);
@@ -27,6 +27,9 @@ export function fetchStaticStateFactory(controllerDefinitions, options) {
             searchActions,
             controllers,
         });
-        return staticState;
+        return {
+            ...params[0], // TODO: KIT-4754: remove index access after no longer relying on OptionTuple type
+            ...staticState,
+        };
     };
 }

package/dist/esm/ssr-next/commerce/utils/controller-wiring.js

@@ -1,4 +1,162 @@
-export function wireControllerParams(_solutionType, _controllerDefinitions, _paramsObject) {
-    // TODO: KIT-4742: Implement
-    return {};
+import { ArrayValue, RecordValue, Schema, StringValue } from '@coveo/bueno';
+import { contextDefinition } from '../../../features/commerce/context/context-validation.js';
+import { parametersDefinition } from '../../../features/commerce/parameters/parameters-schema.js';
+import { nonEmptyString, requiredEmptyAllowedString, } from '../../../utils/validate-payload.js';
+import { SolutionType } from '../types/controller-constants.js';
+import { getRecommendationDefinitions, isRecommendationDefinition, } from './recommendation-filter.js';
+const requiredDefinition = {
+    context: new RecordValue({
+        options: { required: true },
+        values: contextDefinition,
+    }),
+};
+const listingDefinition = {
+    ...requiredDefinition,
+    searchParams: new RecordValue({
+        values: parametersDefinition,
+    }),
+};
+const standaloneDefinition = {
+    ...requiredDefinition,
+};
+const searchDefinition = {
+    ...requiredDefinition,
+    searchParams: new RecordValue({
+        options: { required: true },
+        values: { query: requiredEmptyAllowedString, ...parametersDefinition },
+    }),
+};
+const recommendationsDefinition = (recommendationName) => ({
+    ...requiredDefinition,
+    recommendations: new ArrayValue({
+        each: new StringValue({
+            required: true,
+            constrainTo: recommendationName,
+            emptyAllowed: false,
+        }),
+        required: true,
+    }),
+    productId: nonEmptyString,
+});
+export const listingDefinitionSchema = new Schema(listingDefinition);
+export const searchDefinitionSchema = new Schema(searchDefinition);
+export const standaloneDefinitionSchema = new Schema(standaloneDefinition);
+export const recommendationsDefinitionSchema = (recommendationName) => new Schema(recommendationsDefinition(recommendationName));
+/**
+ * Validates the build configuration based on the solution type.
+ */
+function validateBuildConfig(solutionType, controllerDefinitions, buildConfig) {
+    const validationMap = {
+        [SolutionType.listing]: listingDefinitionSchema,
+        [SolutionType.search]: searchDefinitionSchema,
+        [SolutionType.standalone]: standaloneDefinitionSchema,
+        [SolutionType.recommendation]: recommendationsDefinitionSchema(Object.keys(getRecommendationDefinitions(controllerDefinitions))),
+    };
+    const schema = validationMap[solutionType];
+    schema.validate(buildConfig);
+}
+/**
+ * Controller wiring class that handles the complete wiring process.
+ * Transforms simple user configuration into complex internal controller structures.
+ */
+class ControllerWirer {
+    buildConfig;
+    controllerDefinitions;
+    controllerProps;
+    constructor(buildConfig, controllerDefinitions, controllerProps) {
+        this.buildConfig = buildConfig;
+        this.controllerDefinitions = controllerDefinitions;
+        this.controllerProps = controllerProps;
+    }
+    wireParameterManager() {
+        if (!this.controllerDefinitions?.parameterManager)
+            return;
+        const { searchParams } = this.buildConfig;
+        const { query, ...rest } = searchParams || {};
+        const parameters = {
+            ...(query && { q: query }),
+            ...(rest && typeof rest === 'object' ? rest : {}),
+        };
+        this.controllerProps.parameterManager = {
+            initialState: { parameters },
+        };
+    }
+    wireContext() {
+        if (!this.controllerDefinitions?.context)
+            return;
+        const { context } = this.buildConfig;
+        this.controllerProps.context = {
+            initialState: {
+                ...context,
+            },
+        };
+    }
+    wireCart() {
+        if (!this.controllerDefinitions?.cart || !this.buildConfig.cart)
+            return;
+        this.controllerProps.cart = {
+            initialState: this.buildConfig.cart,
+        };
+    }
+    wireRecommendations() {
+        if (!('recommendations' in this.buildConfig)) {
+            return;
+        }
+        for (const recController in this.controllerDefinitions) {
+            if (isRecommendationDefinition(this.controllerDefinitions[recController])) {
+                this.controllerProps[recController] = {
+                    initialState: {
+                        ...('productId' in this.buildConfig && {
+                            productId: this.buildConfig.productId,
+                        }),
+                    },
+                };
+            }
+        }
+    }
+    /**
+     * Wires all controllers based on solution type and controller definitions.
+     * Handles the complete wiring process in a sequential manner.
+     */
+    wire(solutionType) {
+        // Wire common controllers that apply to all solution types
+        this.wireCart();
+        this.wireContext();
+        // Wire solution-specific controllers
+        switch (solutionType) {
+            case SolutionType.search:
+            case SolutionType.listing: {
+                this.wireParameterManager();
+                break;
+            }
+            case SolutionType.recommendation: {
+                this.wireRecommendations();
+                break;
+            }
+            case SolutionType.standalone:
+                // No additional wiring needed for standalone
+                break;
+            default: {
+                // Exhaustive check - TypeScript will error if we miss a case
+                const _exhaustiveCheck = solutionType;
+                throw new Error(`Unsupported solution type: ${_exhaustiveCheck}`);
+            }
+        }
+    }
+}
+/**
+ * Converts simple user configuration (URL, language, currency, query) into the
+ * nested structure required by the internal {@link Build} method. Automatically generates
+ * appropriate controllers (context, cart, parameterManager) transparently.
+ *
+ * @param solutionType - The type of solution (search, listing, recommendation, standalone)
+ * @param controllerDefinitions - Map of controller definitions to be initialized
+ * @param buildConfig - Simple configuration object with simplified controller properties
+ * @returns Formatted and validated controller properties map defined for the controller in the definition
+ */
+export function wireControllerParams(solutionType, controllerDefinitions, buildConfig) {
+    validateBuildConfig(solutionType, controllerDefinitions, buildConfig);
+    const controllerProps = buildConfig.controllers ?? {};
+    new ControllerWirer(buildConfig, controllerDefinitions, controllerProps).wire(solutionType);
+    return controllerProps;
 }

package/dist/esm/ssr-next/commerce/utils/engine-wiring.js

@@ -1,4 +1,10 @@
-export function extendEngineConfiguration(_configuration, _commonBuildOptions) {
-    // TODO: KIT-4742: Implement: wire engine configuration with validation
-    return {};
+export function extendEngineConfiguration(configuration, commonBuildOptions) {
+    const { cart, context } = commonBuildOptions;
+    return {
+        ...configuration,
+        context: {
+            ...context,
+        },
+        cart,
+    };
 }

package/dist/esm/ssr-next/commerce/utils/recommendation-filter.js

@@ -1,15 +1,34 @@
 import { MultipleRecommendationError } from '../../common/errors.js';
 import { recommendationInternalOptionKey } from '../types/controller-constants.js';
+/**
+ * Type guard to check if a controller definition is a recommendation controller.
+ * A recommendation controller must have both the recommendation flag and a slotId.
+ */
+export function isRecommendationDefinition(controllerDefinition) {
+    const hasRecommendationFlag = 'recommendation' in controllerDefinition &&
+        controllerDefinition.recommendation === true;
+    const hasValidSlotId = recommendationInternalOptionKey in controllerDefinition &&
+        'slotId' in
+            controllerDefinition[recommendationInternalOptionKey];
+    return hasRecommendationFlag && hasValidSlotId;
+}
+/**
+ * Extracts recommendation controller definitions from a controller definitions map.
+ *
+ * @param controllerDefinitions - Map of controller definitions
+ * @returns Object containing only the recommendation controller definitions
+ */
+export function getRecommendationDefinitions(controllerDefinitions) {
+    const recommendationMap = {};
+    for (const [name, definition] of Object.entries(controllerDefinitions)) {
+        if (isRecommendationDefinition(definition)) {
+            recommendationMap[name] = definition;
+        }
+    }
+    return recommendationMap;
+}
 export function filterRecommendationControllers(controllers, controllerDefinitions) {
     const slotIdSet = new Set();
-    const isRecommendationDefinition = (controllerDefinition) => {
-        const isControllerRecommendation = 'recommendation' in controllerDefinition &&
-            controllerDefinition.recommendation === true;
-        const hasSlotId = recommendationInternalOptionKey in controllerDefinition &&
-            'slotId' in
-                controllerDefinition[recommendationInternalOptionKey];
-        return isControllerRecommendation && hasSlotId;
-    };
     const ensureSingleRecommendationPerSlot = (slotId) => {
         throw new MultipleRecommendationError(slotId);
     };

package/dist/esm/ssr-next/{common → search}/controller-utils.js

@@ -1,6 +1,6 @@
 import { clone, mapObject } from '../../utils/utils.js';
-import { ControllerBuilder } from './builders/controller-builder.js';
-import { createStaticControllerBuilder } from './builders/static-controller-builder.js';
+import { ControllerBuilder } from '../common/builders/controller-builder.js';
+import { createStaticControllerBuilder } from '../common/builders/static-controller-builder.js';
 export function buildControllerDefinitions({ definitionsMap, engine, propsMap, }) {
     return mapObject(definitionsMap, (definition, key) => {
         const props = propsMap?.[key];

package/dist/esm/ssr-next/search/engine/search-engine.ssr.js

@@ -2,7 +2,7 @@ import { buildLogger } from '../../../app/logger.js';
 import { buildSearchEngine, } from '../../../app/search-engine/search-engine.js';
 import { createWaitForActionMiddleware } from '../../../utils/utils.js';
 import { augmentPreprocessRequestWithForwardedFor } from '../../common/augment-preprocess-request.js';
-import { buildControllerDefinitions, createStaticState, } from '../../common/controller-utils.js';
+import { buildControllerDefinitions, createStaticState, } from '../controller-utils.js';
 function isSearchCompletedAction(action) {
     return /^search\/executeSearch\/(fulfilled|rejected)$/.test(action.type);
 }

package/dist/esm/ssr-next/search/types/engine.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/ssr-next/search/types/fetch-static-state.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/ssr-next/search/types/hydrate-static-state.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/test/mock-ssr-controller-definitions.js

@@ -1,4 +1,5 @@
 import { vi } from 'vitest';
+import { recommendationInternalOptionKey } from '../ssr-next/commerce/types/controller-constants.js';
 import { buildMockController, buildMockControllerWithInitialState, } from './mock-controller.js';
 export function defineMockController() {
     return {
@@ -41,3 +42,17 @@ export function defineMockCommerceControllerWithProps(options) {
         recommendation: options?.recommendation ?? true,
     };
 }
+export function defineMockRecommendationDefinition(slotId) {
+    return {
+        recommendation: true,
+        [recommendationInternalOptionKey]: {
+            slotId,
+        },
+        buildWithProps: vi.fn((engine, props) => ({
+            _kind: 'some-kind',
+            ...buildMockControllerWithInitialState(engine, {
+                initialState: props?.initialState,
+            }),
+        })),
+    };
+}