@coveo/headless 3.28.4-pre.f345a65b79 → 3.28.4-pre.fe2dbcea63

package/dist/esm/features/commerce/recommendations/recommendations-slice.js

@@ -31,7 +31,7 @@ export const recommendationsReducer = createReducer(getRecommendationsInitialSta
             return;
         }
         const paginationOffset = getPaginationOffset(action.payload);
-        recommendations.products = response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1));
+        recommendations.products = response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1, response.responseId));
     })
         .addCase(fetchMoreRecommendations.fulfilled, (state, action) => {
         if (!action.payload) {
@@ -45,7 +45,7 @@ export const recommendationsReducer = createReducer(getRecommendationsInitialSta
             return;
         }
         const paginationOffset = getPaginationOffset(action.payload);
-        recommendations.products = recommendations.products.concat(response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1)));
+        recommendations.products = recommendations.products.concat(response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1, response.responseId)));
     })
         .addCase(fetchRecommendations.pending, (state, action) => {
         handlePending(state, action.meta.arg.slotId);
@@ -67,6 +67,7 @@ export const recommendationsReducer = createReducer(getRecommendationsInitialSta
         if (currentParentIndex === -1 || childToPromote === undefined) {
             return;
         }
+        const responseId = products[currentParentIndex].responseId;
         const position = products[currentParentIndex].position;
         const { children, totalNumberOfChildren } = products[currentParentIndex];
         const newParent = {
@@ -74,6 +75,7 @@ export const recommendationsReducer = createReducer(getRecommendationsInitialSta
             children,
             totalNumberOfChildren,
             position,
+            responseId,
         };
         products.splice(currentParentIndex, 1, newParent);
     })
@@ -119,15 +121,16 @@ function getPaginationOffset(actionPayload) {
     const pagination = actionPayload.response.pagination;
     return pagination.page * pagination.perPage;
 }
-function preprocessProduct(product, position) {
+function preprocessProduct(product, position, responseId) {
     const isParentAlreadyInChildren = product.children.some((child) => child.permanentid === product.permanentid);
     if (product.children.length === 0 || isParentAlreadyInChildren) {
-        return { ...product, position };
+        return { ...product, position, responseId };
     }
     const { children, totalNumberOfChildren: _totalNumberOfChildren, ...restOfProduct } = product;
     return {
         ...product,
         children: [restOfProduct, ...children],
         position,
+        responseId,
     };
 }

package/dist/esm/features/commerce/search/search-slice.js

@@ -14,7 +14,7 @@ export const commerceSearchReducer = createReducer(getCommerceSearchInitialState
         .addCase(executeSearch.fulfilled, (state, action) => {
         const paginationOffset = getPaginationOffset(action.payload);
         handleFulfilled(state, action.payload.response, action.payload.queryExecuted);
-        state.products = action.payload.response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1));
+        state.products = action.payload.response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1, action.payload.response.responseId));
     })
         .addCase(fetchMoreProducts.fulfilled, (state, action) => {
         if (!action.payload) {
@@ -22,7 +22,7 @@ export const commerceSearchReducer = createReducer(getCommerceSearchInitialState
         }
         const paginationOffset = getPaginationOffset(action.payload);
         handleFulfilled(state, action.payload.response, action.payload.queryExecuted);
-        state.products = state.products.concat(action.payload.response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1)));
+        state.products = state.products.concat(action.payload.response.products.map((product, index) => preprocessProduct(product, paginationOffset + index + 1, action.payload?.response.responseId)));
     })
         .addCase(executeSearch.pending, (state, action) => {
         handlePending(state, action.meta.requestId);
@@ -40,6 +40,7 @@ export const commerceSearchReducer = createReducer(getCommerceSearchInitialState
         if (currentParentIndex === -1 || childToPromote === undefined) {
             return;
         }
+        const responseId = products[currentParentIndex].responseId;
         const position = products[currentParentIndex].position;
         const { children, totalNumberOfChildren } = products[currentParentIndex];
         const newParent = {
@@ -47,6 +48,7 @@ export const commerceSearchReducer = createReducer(getCommerceSearchInitialState
             children,
             totalNumberOfChildren,
             position,
+            responseId,
         };
         products.splice(currentParentIndex, 1, newParent);
     })
@@ -76,15 +78,16 @@ function getPaginationOffset(payload) {
     const pagination = payload.response.pagination;
     return pagination.page * pagination.perPage;
 }
-function preprocessProduct(product, position) {
+function preprocessProduct(product, position, responseId) {
     const isParentAlreadyInChildren = product.children.some((child) => child.permanentid === product.permanentid);
     if (product.children.length === 0 || isParentAlreadyInChildren) {
-        return { ...product, position };
+        return { ...product, position, responseId };
     }
     const { children, totalNumberOfChildren: _totalNumberOfChildren, ...restOfProduct } = product;
     return {
         ...product,
         children: [restOfProduct, ...children],
         position,
+        responseId,
     };
 }

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

@@ -1,22 +1,13 @@
 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';
-function hasKindProperty(controller) {
-    return '_kind' in controller;
-}
 export function createStaticState({ searchActions, controllers, }) {
     return {
-        controllers: mapObject(controllers, (controller) => ({
-            state: clone(controller.state),
-            ...(hasKindProperty(controller) && { _kind: controller._kind }),
-        })),
+        controllers: mapObject(controllers, (controller) => createStaticControllerBuilder(controller).build()),
         searchActions: searchActions.map((action) => clone(action)),
     };
 }
-function buildControllerFromDefinition({ definition, engine, solutionType, props, }) {
-    return ('build' in definition
-        ? definition.build(engine, solutionType)
-        : definition.buildWithProps(engine, props, solutionType));
-}
 export function buildControllerDefinitions({ definitionsMap, engine, solutionType, propsMap, }) {
     const controllerMap = mapObject(definitionsMap, (definition, key) => {
         const unavailableInSolutionType = () => !(solutionType in definition) ||
@@ -26,12 +17,9 @@ export function buildControllerDefinitions({ definitionsMap, engine, solutionTyp
         if (unavailableInSolutionType()) {
             return null;
         }
-        return buildControllerFromDefinition({
-            definition,
-            engine,
-            solutionType,
-            props,
-        });
+        return new ControllerBuilder(definition, engine, props)
+            .withAdditionalArgs([solutionType])
+            .build();
     });
     return filterObject(controllerMap, (value) => value !== null);
 }

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

@@ -1,5 +1,4 @@
 import { buildCart, } from '../../../../controllers/commerce/context/cart/headless-cart.js';
-import { MissingControllerProps } from '../../../common/errors.js';
 import { createControllerWithKind, Kind } from '../../types/kind.js';
 /**
  * Defines a `Cart` controller instance.
@@ -14,10 +13,9 @@ export function defineCart() {
         standalone: true,
         recommendation: true,
         buildWithProps: (engine, props) => {
-            if (props === undefined) {
-                throw new MissingControllerProps(Kind.Cart);
-            }
-            const controller = buildCart(engine, { initialState: props.initialState });
+            const controller = buildCart(engine, {
+                initialState: props ? props.initialState : {},
+            });
             return createControllerWithKind(controller, Kind.Cart);
         },
     };

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

@@ -17,7 +17,7 @@ export function defineContext() {
             if (props === undefined) {
                 throw new MissingControllerProps(Kind.Context);
             }
-            const controller = buildContext(engine, { options: props });
+            const controller = buildContext(engine, { options: props.initialState });
             return createControllerWithKind(controller, Kind.Context);
         },
     };

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

@@ -18,29 +18,49 @@ import { SolutionType } from '../types/controller-constants.js';
  *
  * @example
  * ```ts
- * const engineDefinition = defineCommerceEngine(engineConfig);
- * type SearchStaticState = InferStaticState<typeof engineDefinition>;
- * type SearchHydratedState = InferHydratedState<typeof engineDefinition>;
+ * const { listingEngineDefinition } = defineCommerceEngine(engineConfig);
+ *
+ * // Pass navigator context directly to fetchStaticState
+ * const staticState = await listingEngineDefinition.fetchStaticState({
+ *   navigatorContext: {
+ *     forwardedFor: req.ip,
+ *     referrer: req.headers.referer || null,
+ *     userAgent: req.headers['user-agent'] || null,
+ *     clientId: 'unique-session-id'
+ *   }
+ * });
+ *
+ * // Framework examples:
+ * // Express.js
+ * app.get('/api/listing', async (req, res) => {
+ *   const state = await listingEngineDefinition.fetchStaticState({
+ *     navigatorContext: {
+ *       forwardedFor: req.ip,
+ *       referrer: req.headers.referer || null,
+ *       userAgent: req.headers['user-agent'] || null,
+ *       clientId: req.sessionID
+ *     }
+ *   });
+ *   res.json(state);
+ * });
+ *
+ * type SearchStaticState = InferStaticState<typeof listingEngineDefinition>;
+ * type SearchHydratedState = InferHydratedState<typeof listingEngineDefinition>;
  * ```
  *
  * @group Engine
  */
 export function defineCommerceEngine(options) {
     const { controllers: controllerDefinitions, ...engineOptions } = options;
-    const getOptions = () => engineOptions;
-    const setNavigatorContextProvider = (navigatorContextProvider) => {
-        engineOptions.navigatorContextProvider = navigatorContextProvider;
-    };
     const getAccessToken = () => engineOptions.configuration.accessToken;
     const setAccessToken = (accessToken) => {
         engineOptions.configuration.accessToken = accessToken;
     };
-    const fetchStaticState = fetchStaticStateFactory(controllerDefinitions, getOptions());
-    const hydrateStaticState = hydratedStaticStateFactory(controllerDefinitions, getOptions());
-    const fetchRecommendationStaticState = fetchRecommendationStaticStateFactory(controllerDefinitions, getOptions());
-    const hydrateRecommendationStaticState = hydratedRecommendationStaticStateFactory(controllerDefinitions, getOptions());
+    const fetchStaticState = fetchStaticStateFactory(controllerDefinitions, engineOptions);
+    const hydrateStaticState = hydratedStaticStateFactory(controllerDefinitions, engineOptions);
+    const fetchRecommendationStaticState = fetchRecommendationStaticStateFactory(controllerDefinitions, engineOptions);
+    const hydrateRecommendationStaticState = hydratedRecommendationStaticStateFactory(controllerDefinitions, engineOptions);
     const commonMethods = {
-        setNavigatorContextProvider,
         getAccessToken,
         setAccessToken,
     };

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

@@ -1,21 +1,14 @@
 import { buildProductListing } from '../../../controllers/commerce/product-listing/headless-product-listing.js';
 import { buildSearch } from '../../../controllers/commerce/search/headless-search.js';
-import { augmentPreprocessRequestWithForwardedFor } from '../../common/augment-preprocess-request.js';
+import { processNavigatorContext } from '../../common/navigator-context-utils.js';
 import { createStaticState } from '../controller-utils.js';
 import { SolutionType } from '../types/controller-constants.js';
 import { buildFactory, } from './build-factory.js';
 export function fetchStaticStateFactory(controllerDefinitions, options) {
     return (solutionType) => async (...params) => {
-        const solutionTypeBuild = await buildFactory(controllerDefinitions, {
-            ...options,
-        })(solutionType);
+        const { engineOptions } = processNavigatorContext(params, options);
+        const solutionTypeBuild = await buildFactory(controllerDefinitions, engineOptions)(solutionType);
         const { engine, controllers } = await solutionTypeBuild(...params);
-        options.configuration.preprocessRequest =
-            augmentPreprocessRequestWithForwardedFor({
-                preprocessRequest: options.configuration.preprocessRequest,
-                navigatorContextProvider: options.navigatorContextProvider,
-                loggerOptions: options.loggerOptions,
-            });
         switch (solutionType) {
             case SolutionType.listing:
                 buildProductListing(engine).executeFirstRequest();

package/dist/esm/ssr-next/common/builders/controller-builder.js

@@ -0,0 +1,38 @@
+/**
+ * Builder class for creating controllers from definitions
+ */
+export class ControllerBuilder {
+    _definition;
+    _engine;
+    _props;
+    _additionalArgs = [];
+    constructor(definition, engine, props) {
+        this._definition = definition;
+        this._engine = engine;
+        this._props = props;
+    }
+    withAdditionalArgs(additionalArgs = []) {
+        this._additionalArgs = additionalArgs;
+        return this;
+    }
+    build() {
+        if ('build' in this._definition &&
+            typeof this._definition.build === 'function') {
+            return this.buildWithoutProps();
+        }
+        if ('buildWithProps' in this._definition &&
+            typeof this._definition.buildWithProps === 'function') {
+            return this.buildWithProps();
+        }
+        throw new Error('Controller definition must have a build or buildWithProps method.');
+    }
+    buildWithoutProps() {
+        const buildFn = this._definition.build;
+        return buildFn(this._engine, ...this._additionalArgs);
+    }
+    buildWithProps() {
+        const buildWithPropsFn = this._definition.buildWithProps;
+        const controller = buildWithPropsFn(this._engine, this._props, ...this._additionalArgs);
+        return { ...controller, initialState: controller.state };
+    }
+}

package/dist/esm/ssr-next/common/builders/static-controller-builder.js

@@ -0,0 +1,46 @@
+import { clone } from '../../../utils/utils.js';
+/**
+ * Builder class for creating static controller
+ */
+class StaticControllerBuilder {
+    _state;
+    _kind;
+    _initialState;
+    withState(state) {
+        this._state = clone(state);
+        return this;
+    }
+    withKind(kind) {
+        this._kind = kind;
+        return this;
+    }
+    withInitialState(initialState) {
+        this._initialState = clone(initialState);
+        return this;
+    }
+    /**
+     * Builds and returns the static controller state object
+     */
+    build() {
+        const result = {
+            state: this._state,
+        };
+        if (this._kind) {
+            result._kind = this._kind;
+        }
+        if (this._initialState) {
+            result.initialState = this._initialState;
+        }
+        return result;
+    }
+}
+export function createStaticControllerBuilder(controller) {
+    const builder = new StaticControllerBuilder().withState(controller.state);
+    if ('_kind' in controller) {
+        builder.withKind(controller._kind);
+    }
+    if ('initialState' in controller) {
+        builder.withInitialState(controller.initialState);
+    }
+    return builder;
+}

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

@@ -1,21 +1,15 @@
 import { clone, mapObject } from '../../utils/utils.js';
-function buildControllerFromDefinition({ definition, engine, props, }) {
-    return ('build' in definition
-        ? definition.build(engine)
-        : definition.buildWithProps(engine, props));
-}
+import { ControllerBuilder } from './builders/controller-builder.js';
+import { createStaticControllerBuilder } from './builders/static-controller-builder.js';
 export function buildControllerDefinitions({ definitionsMap, engine, propsMap, }) {
-    return mapObject(definitionsMap, (definition, key) => buildControllerFromDefinition({
-        definition,
-        engine,
-        props: propsMap?.[key],
-    }));
+    return mapObject(definitionsMap, (definition, key) => {
+        const props = propsMap?.[key];
+        return new ControllerBuilder(definition, engine, props).build();
+    });
 }
 export function createStaticState({ searchAction, controllers, }) {
     return {
-        controllers: mapObject(controllers, (controller) => ({
-            state: clone(controller.state),
-        })),
+        controllers: mapObject(controllers, (controller) => createStaticControllerBuilder(controller).build()),
         searchAction: clone(searchAction),
     };
 }

package/dist/esm/ssr-next/common/navigator-context-utils.js

@@ -0,0 +1,27 @@
+import { augmentPreprocessRequestWithForwardedFor } from './augment-preprocess-request.js';
+/**
+ * Processes fetchStaticState parameters and returns enhanced engine options with navigator context.
+ * This is the single function that handles all navigator context logic for both commerce and search engines.
+ */
+export function processNavigatorContext(params, baseOptions) {
+    const [callOptions] = params;
+    // If no navigator context, return original options
+    if (!callOptions?.navigatorContext) {
+        return { engineOptions: baseOptions, callOptions };
+    }
+    // Create provider function and enhance options
+    const navigatorContextProvider = () => callOptions.navigatorContext;
+    const engineOptions = {
+        ...baseOptions,
+        navigatorContextProvider,
+        configuration: {
+            ...baseOptions.configuration,
+            preprocessRequest: augmentPreprocessRequestWithForwardedFor({
+                preprocessRequest: baseOptions.configuration?.preprocessRequest,
+                navigatorContextProvider,
+                loggerOptions: baseOptions.loggerOptions,
+            }),
+        },
+    };
+    return { engineOptions, callOptions };
+}

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

@@ -1,8 +1,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 { processNavigatorContext } from '../../common/navigator-context-utils.js';
 function isSearchCompletedAction(action) {
     return /^search\/executeSearch\/(fulfilled|rejected)$/.test(action.type);
 }
@@ -23,50 +22,52 @@ function buildSSRSearchEngine(options) {
     };
 }
 /**
- * Initializes a Search engine definition in SSR with given controllers definitions and search engine config.
+ * Initializes a Search engine definition in SSR with per-call navigator context support.
  *
  * @param options - The search engine definition
- * @returns Three utility functions to fetch the initial state of the engine in SSR, hydrate the state in CSR,
- *  and a build function that can be used for edge cases requiring more control.
+ * @returns Engine definition with support for per-call navigator context.
+ *
+ * @example
+ * ```ts
+ * const searchEngine = defineSearchEngine(config);
+ *
+ * // Pass navigator context directly to fetchStaticState
+ * const staticState = await searchEngine.fetchStaticState({
+ *   navigatorContext: {
+ *     forwardedFor: req.ip,
+ *     referrer: req.headers.referer || null,
+ *     userAgent: req.headers['user-agent'] || null,
+ *     clientId: 'abc123'
+ *   }
+ * });
+ * ```
  *
  * @group Engine
  */
 export function defineSearchEngine(options) {
     const { controllers: controllerDefinitions, ...engineOptions } = options;
-    const getOptions = () => {
-        return engineOptions;
-    };
-    const setNavigatorContextProvider = (navigatorContextProvider) => {
-        engineOptions.navigatorContextProvider = navigatorContextProvider;
-    };
-    const build = async (...[buildOptions]) => {
-        const logger = buildLogger(options.loggerOptions);
-        if (!getOptions().navigatorContextProvider) {
-            logger.warn('[WARNING] Missing navigator context in server-side code. Make sure to set it with `setNavigatorContextProvider` before calling fetchStaticState()');
-        }
-        const engine = buildSSRSearchEngine(buildOptions?.extend
-            ? await buildOptions.extend(getOptions())
-            : getOptions());
+    const hydrateStaticState = async (...params) => {
+        const engine = buildSSRSearchEngine(engineOptions);
         const controllers = buildControllerDefinitions({
             definitionsMap: (controllerDefinitions ?? {}),
             engine,
-            propsMap: (buildOptions && 'controllers' in buildOptions
-                ? buildOptions.controllers
-                : {}),
+            propsMap: {},
         });
-        return {
-            engine,
-            controllers,
-        };
+        const [staticState] = params;
+        engine.dispatch(staticState.searchAction);
+        await engine.waitForSearchCompletedAction();
+        return { engine, controllers };
     };
     const fetchStaticState = async (...params) => {
-        const { engine, controllers } = await build(...params);
-        options.configuration.preprocessRequest =
-            augmentPreprocessRequestWithForwardedFor({
-                preprocessRequest: options.configuration.preprocessRequest,
-                navigatorContextProvider: options.navigatorContextProvider,
-                loggerOptions: options.loggerOptions,
-            });
+        const { engineOptions, callOptions } = processNavigatorContext(params, options);
+        const engine = buildSSRSearchEngine(engineOptions);
+        const controllers = buildControllerDefinitions({
+            definitionsMap: (controllerDefinitions ?? {}),
+            engine,
+            propsMap: (callOptions && 'controllers' in callOptions
+                ? callOptions.controllers
+                : {}),
+        });
         engine.executeFirstSearch();
         const staticState = createStaticState({
             searchAction: await engine.waitForSearchCompletedAction(),
@@ -74,15 +75,8 @@ export function defineSearchEngine(options) {
         });
         return staticState;
     };
-    const hydrateStaticState = async (...params) => {
-        const { engine, controllers } = await build(...params);
-        engine.dispatch(params[0].searchAction);
-        await engine.waitForSearchCompletedAction();
-        return { engine, controllers };
-    };
     return {
         fetchStaticState,
         hydrateStaticState,
-        setNavigatorContextProvider,
     };
 }

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

@@ -0,0 +1,13 @@
+import { vi } from 'vitest';
+export function buildMockController() {
+    return {
+        subscribe: vi.fn(),
+        state: {},
+    };
+}
+export function buildMockControllerWithInitialState(_engine, props) {
+    return {
+        state: props.initialState,
+        subscribe: vi.fn(),
+    };
+}

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

@@ -0,0 +1,43 @@
+import { vi } from 'vitest';
+import { buildMockController, buildMockControllerWithInitialState, } from './mock-controller.js';
+export function defineMockController() {
+    return {
+        build: vi.fn((_engine) => {
+            return buildMockController();
+        }),
+    };
+}
+export function defineMockControllerWithProps() {
+    return {
+        buildWithProps: vi.fn((engine, props) => {
+            return buildMockControllerWithInitialState(engine, {
+                initialState: props?.initialState,
+            });
+        }),
+    };
+}
+export function defineMockCommerceController(options) {
+    return {
+        build: vi.fn((_engine) => {
+            return buildMockController();
+        }),
+        listing: options?.listing ?? true,
+        search: options?.search ?? true,
+        standalone: options?.standalone ?? true,
+        recommendation: options?.recommendation ?? true,
+    };
+}
+export function defineMockCommerceControllerWithProps(options) {
+    return {
+        buildWithProps: vi.fn((engine, props) => ({
+            _kind: 'some-kind',
+            ...buildMockControllerWithInitialState(engine, {
+                initialState: props?.initialState,
+            }),
+        })),
+        listing: options?.listing ?? true,
+        search: options?.search ?? true,
+        standalone: options?.standalone ?? true,
+        recommendation: options?.recommendation ?? true,
+    };
+}

package/dist/esm/utils/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "3.28.4-pre.f345a65b79" || 'Test version';
+export const VERSION = "3.28.4-pre.fe2dbcea63" || 'Test version';
 export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];