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

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.f565c74b85" || 'Test version';
+export const VERSION = "3.28.4-pre.fe2dbcea63" || 'Test version';
 export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];