@coveo/headless 3.29.0-pre.032a5300a8 → 3.29.0-pre.075377ce6d

package/dist/definitions/ssr-next/commerce/utils/recommendation-filter.d.ts

@@ -1,5 +1,18 @@
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
-import type { ControllerDefinitionsMap } from '../types/controller-definitions.js';
+import type { RecommendationsDefinitionMeta } from '../controllers/recommendations/headless-recommendations.ssr.js';
+import type { ControllerDefinition, ControllerDefinitionsMap } from '../types/controller-definitions.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 declare function isRecommendationDefinition<C extends ControllerDefinition<Controller>>(controllerDefinition: C): controllerDefinition is C & RecommendationsDefinitionMeta;
+/**
+ * Extracts recommendation controller definitions from a controller definitions map.
+ *
+ * @param controllerDefinitions - Map of controller definitions
+ * @returns Object containing only the recommendation controller definitions
+ */
+export declare function getRecommendationDefinitions(controllerDefinitions: ControllerDefinitionsMap<Controller>): Record<string, ControllerDefinition<Controller> & RecommendationsDefinitionMeta>;
 export declare function filterRecommendationControllers<TControllerDefinitions extends ControllerDefinitionsMap<Controller>>(controllers: Record<string, Controller>, controllerDefinitions: TControllerDefinitions): {
     /**
      * Go through all the controllers passed in argument and only refresh recommendation controllers.

package/dist/definitions/ssr-next/commerce/validation/controller-validation.d.ts

@@ -0,0 +1 @@
+export declare const validateControllerNames: (controllers: Record<string, unknown>) => void;

package/dist/definitions/ssr-next/common/types/fetch-static-state.d.ts

@@ -2,11 +2,9 @@ import type { UnknownAction } from '@reduxjs/toolkit';
 import type { ControllerStaticStateMap, ControllersPropsMap } from './controllers.js';
 import type { EngineDefinitionControllersPropsOption, EngineStaticState } from './engine.js';
 import type { OptionsTuple } from './utilities.js';
-type FetchStaticStateOptions = {};
 /**
  * Executes only the initial search for a given configuration, then returns a resumable snapshot of engine state along with the state of the controllers.
  *
  * Useful for static generation and server-side rendering.
  */
-export type FetchStaticState<TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap> = (...params: OptionsTuple<FetchStaticStateOptions & EngineDefinitionControllersPropsOption<TControllersProps>>) => Promise<EngineStaticState<TSearchAction, TControllersStaticState>>;
-export {};
+export type FetchStaticState<TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap> = (...params: OptionsTuple<EngineDefinitionControllersPropsOption<TControllersProps>>) => Promise<EngineStaticState<TSearchAction, TControllersStaticState>>;

package/dist/definitions/ssr-next/common/types/utilities.d.ts

@@ -3,9 +3,6 @@ export type HasKeys<TObject> = TObject extends {} ? keyof TObject extends never
 export type HasRequiredKeys<TObject> = TObject extends {} ? {
     [K in keyof TObject]-?: {} extends Pick<TObject, K> ? never : K;
 }[keyof TObject] extends never ? false : true : boolean;
-export type HasOptionalKeys<TObject> = TObject extends {} ? {
-    [K in keyof TObject]-?: {} extends Pick<TObject, K> ? K : never;
-}[keyof TObject] extends never ? false : true : boolean;
 type ExtractRequiredOptions<TOptions> = {
     [TKey in keyof TOptions as Pick<TOptions, TKey> extends Required<Pick<TOptions, TKey>> ? TKey : never]: TOptions[TKey];
 };

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

@@ -1,6 +1,7 @@
 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 { recommendationInternalOptionKey } from '../ssr-next/commerce/types/controller-constants.js';
 import type { ControllerDefinitionWithoutProps, ControllerDefinitionWithProps } from '../ssr-next/common/types/controllers.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/commerce/types/kind.js

@@ -5,6 +5,7 @@ export var Kind;
     Kind["ParameterManager"] = "PARAMETER_MANAGER";
     Kind["Recommendations"] = "RECOMMENDATIONS";
 })(Kind || (Kind = {}));
+// TODO: KIT-4742: There is no point for this now that the wiring is happening in headless
 export function createControllerWithKind(controller, kind) {
     const copy = Object.defineProperties({}, Object.getOwnPropertyDescriptors(controller));
     Object.defineProperty(copy, '_kind', {

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/engine/commerce-engine.ssr.js

@@ -1,11 +1,15 @@
 /**
  * Utility functions to be used for Commerce Server Side Rendering.
  */
+import { defineCart } from '../controllers/cart/headless-cart.ssr.js';
+import { defineContext } from '../controllers/context/headless-context.ssr.js';
+import { defineParameterManager } from '../controllers/parameter-manager/headless-core-parameter-manager.ssr.js';
 import { hydratedStaticStateFactory } from '../factories/hydrated-state-factory.js';
 import { hydratedRecommendationStaticStateFactory } from '../factories/recommendation-hydrated-state-factory.js';
 import { fetchRecommendationStaticStateFactory } from '../factories/recommendation-static-state-factory.js';
 import { fetchStaticStateFactory } from '../factories/static-state-factory.js';
 import { SolutionType } from '../types/controller-constants.js';
+import { validateControllerNames } from '../validation/controller-validation.js';
 /**
  * Initializes a Commerce engine definition in SSR with given controllers definitions and commerce engine config.
  * @param options - The commerce engine definition
@@ -35,10 +39,17 @@ export function defineCommerceEngine(options) {
     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());
+    controllerDefinitions && validateControllerNames(controllerDefinitions);
+    const augmentedControllerDefinition = {
+        ...controllerDefinitions,
+        parameterManager: defineParameterManager(),
+        context: defineContext(),
+        cart: defineCart(),
+    };
+    const fetchStaticState = fetchStaticStateFactory(augmentedControllerDefinition, getOptions());
+    const hydrateStaticState = hydratedStaticStateFactory(augmentedControllerDefinition, getOptions());
+    const fetchRecommendationStaticState = fetchRecommendationStaticStateFactory(augmentedControllerDefinition, getOptions());
+    const hydrateRecommendationStaticState = hydratedRecommendationStaticStateFactory(augmentedControllerDefinition, getOptions());
     const commonMethods = {
         setNavigatorContextProvider,
         getAccessToken,

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

@@ -4,6 +4,8 @@ import { stateKey } from '../../../app/state-key.js';
 import { createWaitForActionMiddleware, createWaitForActionMiddlewareForRecommendation, } from '../../../utils/utils.js';
 import { buildControllerDefinitions } from '../controller-utils.js';
 import { SolutionType } from '../types/controller-constants.js';
+import { wireControllerParams } from '../utils/controller-wiring.js';
+import { extendEngineConfiguration } from '../utils/engine-wiring.js';
 function isListingFetchCompletedAction(action) {
     return /^commerce\/productListing\/fetch\/(fulfilled|rejected)$/.test(action.type);
 }
@@ -55,33 +57,26 @@ 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 controllerProps = buildOptions && 'controllers' in buildOptions
-        ? buildOptions.controllers
-        : {};
-    const enabledRecommendationControllers = fetchActiveRecommendationControllers(controllerProps, solutionType);
-    const engine = buildSSRCommerceEngine(solutionType, buildOptions && 'extend' in buildOptions && buildOptions?.extend
-        ? await buildOptions.extend(options)
-        : options, enabledRecommendationControllers);
+    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
+    };
+    const engine = buildSSRCommerceEngine(solutionType, engineOptions, enabledRecommendationControllers);
     const controllers = buildControllerDefinitions({
         definitionsMap: (controllerDefinitions ?? {}),
         engine,
         solutionType,
-        propsMap: (buildOptions && 'controllers' in buildOptions
-            ? buildOptions.controllers
-            : {}),
+        propsMap: controllerProps,
     });
     return {
         engine,

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

@@ -1,9 +1,7 @@
 import { buildFactory, } from './build-factory.js';
 export function hydratedStaticStateFactory(controllerDefinitions, options) {
     return (solutionType) => async (...params) => {
-        const solutionTypeBuild = await buildFactory(controllerDefinitions, {
-            ...options,
-        })(solutionType);
+        const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(solutionType);
         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';
 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

@@ -6,9 +6,7 @@ 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 solutionTypeBuild = await buildFactory(controllerDefinitions, options)(solutionType);
         const { engine, controllers } = await solutionTypeBuild(...params);
         options.configuration.preprocessRequest =
             augmentPreprocessRequestWithForwardedFor({
@@ -29,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/types/utilities.js

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

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

@@ -0,0 +1,153 @@
+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);
+}
+function createControllerWirer(buildConfig, controllerDefinitions, controllerProps) {
+    return {
+        wireParameterManager: () => {
+            if (!controllerDefinitions?.parameterManager)
+                return;
+            const { searchParams } = buildConfig;
+            const { query, ...rest } = searchParams || {};
+            const parameters = {
+                ...(query && { q: query }),
+                ...(rest && typeof rest === 'object' ? rest : {}),
+            };
+            controllerProps.parameterManager = {
+                initialState: { parameters },
+            };
+        },
+        wireContext: () => {
+            if (!controllerDefinitions?.context)
+                return;
+            const { context } = buildConfig;
+            controllerProps.context = {
+                initialState: {
+                    ...context,
+                },
+            };
+        },
+        wireCart: () => {
+            if (!controllerDefinitions?.cart || !buildConfig.cart)
+                return;
+            controllerProps.cart = {
+                initialState: buildConfig.cart,
+            };
+        },
+        wireRecommendations: () => {
+            if (!('recommendations' in buildConfig)) {
+                return;
+            }
+            for (const recController in controllerDefinitions) {
+                if (isRecommendationDefinition(controllerDefinitions[recController])) {
+                    controllerProps[recController] = {
+                        initialState: {
+                            ...('productId' in buildConfig && {
+                                productId: buildConfig.productId,
+                            }),
+                        },
+                    };
+                }
+            }
+        },
+    };
+}
+function wireCommonControllers(wirer) {
+    wirer.wireCart();
+    wirer.wireContext();
+}
+function wireSolutionSpecificControllers(solutionType, wirer) {
+    switch (solutionType) {
+        case SolutionType.search: {
+            wirer.wireParameterManager();
+            break;
+        }
+        case SolutionType.listing: {
+            wirer.wireParameterManager();
+            break;
+        }
+        case SolutionType.recommendation: {
+            wirer.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 ?? {};
+    const wirer = createControllerWirer(buildConfig, controllerDefinitions, controllerProps);
+    wireCommonControllers(wirer);
+    wireSolutionSpecificControllers(solutionType, wirer);
+    return controllerProps;
+}

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

@@ -0,0 +1,10 @@
+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/commerce/validation/controller-validation.js

@@ -0,0 +1,7 @@
+export const validateControllerNames = (controllers) => {
+    const reservedNames = ['context', 'cart', 'parameterManager'];
+    const invalidNames = Object.keys(controllers).filter((name) => reservedNames.includes(name));
+    if (invalidNames.length > 0) {
+        throw new Error(`Reserved controller names found: ${invalidNames.join(', ')}. Please use different controller names than ${reservedNames.join(', ')}.`);
+    }
+};

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,
+            }),
+        })),
+    };
+}

package/dist/esm/utils/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "3.29.0-pre.032a5300a8" || 'Test version';
+export const VERSION = "3.29.0-pre.075377ce6d" || 'Test version';
 export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];