@coveo/headless 3.29.0-pre.48ec9ee539 → 3.29.0-pre.4c98ddef9f

package/dist/cjs/case-assist/headless.cjs

@@ -800,7 +800,7 @@ var import_bueno5 = require("@coveo/bueno");
 var import_toolkit7 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/commerce/headless.cjs

@@ -1149,7 +1149,7 @@ var import_bueno6 = require("@coveo/bueno");
 var import_toolkit4 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/headless.cjs

@@ -1374,7 +1374,7 @@ var import_toolkit2 = require("@reduxjs/toolkit");
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/insight/headless.cjs

@@ -1278,7 +1278,7 @@ var import_toolkit2 = require("@reduxjs/toolkit");
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/recommendation/headless.cjs

@@ -881,7 +881,7 @@ var validateObject = (engine, schema, obj, validationMessage, errorMessage) => {
 };
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr/headless.cjs

@@ -1306,7 +1306,7 @@ var import_toolkit2 = require("@reduxjs/toolkit");
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/ssr-commerce/headless.cjs

@@ -468,7 +468,7 @@ var import_bueno8 = require("@coveo/bueno");
 var import_toolkit3 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr-commerce-next/headless.cjs

@@ -468,7 +468,7 @@ var import_bueno8 = require("@coveo/bueno");
 var import_toolkit3 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr-next/headless.cjs

@@ -1306,7 +1306,7 @@ var import_toolkit2 = require("@reduxjs/toolkit");
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.29.0-pre.48ec9ee539";
+var VERSION = "3.29.0-pre.4c98ddef9f";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

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

@@ -2,15 +2,13 @@ import type { UnknownAction } from '@reduxjs/toolkit';
 import type { Controller } from '../../controllers/controller/headless-controller.js';
 import type { SSRCommerceEngine } from './factories/build-factory.js';
 import type { SolutionType } from './types/controller-constants.js';
-import type { ControllerDefinitionOption, ControllerDefinitionsMap, FilteredBakedInControllers } from './types/controller-definitions.js';
+import type { ControllerDefinitionOption, ControllerDefinitionsMap } from './types/controller-definitions.js';
 import type { InferControllerPropsMapFromDefinitions, InferControllerStaticStateMapFromDefinitionsWithSolutionType, InferControllersMapFromDefinition } from './types/controller-inference.js';
-export declare function createStaticState<TSearchAction extends UnknownAction, TControllerDefinitions extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType>({ searchActions, controllers, }: {
+import type { EngineStaticState } from './types/engine.js';
+export declare function createStaticState<TSearchAction extends UnknownAction, TControllerDefinitions extends ControllerDefinitionsMap<Controller>>({ searchActions, controllers, }: {
     searchActions: TSearchAction[];
-    controllers: Record<string, Controller>;
-}): {
-    controllers: InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllerDefinitions, TSolutionType> & FilteredBakedInControllers<TSolutionType>;
-    searchActions: TSearchAction[];
-};
+    controllers: InferControllersMapFromDefinition<TControllerDefinitions, SolutionType>;
+}): EngineStaticState<TSearchAction, InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllerDefinitions, SolutionType>>;
 export declare function buildControllerDefinitions<TControllerDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType>({ definitionsMap, engine, solutionType, propsMap, }: {
     definitionsMap: TControllerDefinitionsMap;
     engine: SSRCommerceEngine;

package/dist/definitions/ssr-next/commerce/controllers/recommendations/headless-recommendations.ssr.d.ts

@@ -1,13 +1,11 @@
-import { type Recommendations, type RecommendationsOptions, type RecommendationsState } from '../../../../controllers/commerce/recommendations/headless-recommendations.js';
+import { type Recommendations, type RecommendationsOptions, type RecommendationsProps, type RecommendationsState } from '../../../../controllers/commerce/recommendations/headless-recommendations.js';
 import { recommendationInternalOptionKey } from '../../types/controller-constants.js';
 import type { RecommendationOnlyControllerDefinitionWithProps } from '../../types/controller-definitions.js';
 export type { Recommendations, RecommendationsState };
 export type RecommendationsDefinitionMeta = {
-    [recommendationInternalOptionKey]: {} & RecommendationsOptions;
+    [recommendationInternalOptionKey]: {} & RecommendationsProps['options'];
 };
-export interface RecommendationsDefinition extends RecommendationOnlyControllerDefinitionWithProps<Recommendations, {
-    initialState: Partial<RecommendationsOptions>;
-}> {
+export interface RecommendationsDefinition extends RecommendationOnlyControllerDefinitionWithProps<Recommendations, Partial<RecommendationsOptions>> {
 }
 /**
  * Defines a `Recommendations` controller instance.
@@ -16,6 +14,4 @@ export interface RecommendationsDefinition extends RecommendationOnlyControllerD
  * @param props - The configurable `Recommendations` properties.
  * @returns The `Recommendations` controller definition.
  * */
-export declare function defineRecommendations(props: {
-    options: Omit<RecommendationsOptions, 'productId'>;
-}): RecommendationsDefinition & RecommendationsDefinitionMeta;
+export declare function defineRecommendations(props: RecommendationsProps): RecommendationsDefinition & RecommendationsDefinitionMeta;

package/dist/definitions/ssr-next/commerce/factories/build-factory.d.ts

@@ -3,9 +3,8 @@ import { type CommerceEngine } from '../../../app/commerce-engine/commerce-engin
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { SSRCommerceEngineOptions } from '../types/build.js';
 import { SolutionType } from '../types/controller-constants.js';
-import type { AugmentedControllerDefinition, BakedInControllers, ControllerDefinitionsMap } from '../types/controller-definitions.js';
-import type { InferControllersMapFromDefinition } from '../types/controller-inference.js';
-import type { CommerceControllerDefinitionsMap, EngineDefinitionOptions, FetchStaticStateParameters, HydrateStaticStateParameters } from '../types/engine.js';
+import type { ControllerDefinitionsMap } from '../types/controller-definitions.js';
+import type { BuildParameters, CommerceControllerDefinitionsMap, EngineDefinitionOptions } from '../types/engine.js';
 /**
  * The SSR commerce engine.
  *
@@ -18,7 +17,7 @@ export interface SSRCommerceEngine extends CommerceEngine {
     waitForRequestCompletedAction(): Promise<Action>[];
 }
 export type CommerceEngineDefinitionOptions<TControllers extends ControllerDefinitionsMap<Controller> = ControllerDefinitionsMap<Controller>> = EngineDefinitionOptions<SSRCommerceEngineOptions, TControllers>;
-export declare const buildFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => <TSolutionType extends SolutionType>(solutionType: TSolutionType) => (...[buildOptions]: FetchStaticStateParameters<TControllerDefinitions, TSolutionType> | HydrateStaticStateParameters<TControllerDefinitions, TSolutionType>) => Promise<{
+export declare const buildFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => <T extends SolutionType>(solutionType: T) => (...[buildOptions]: BuildParameters<TControllerDefinitions>) => Promise<{
     engine: SSRCommerceEngine;
-    controllers: InferControllersMapFromDefinition<TControllerDefinitions, TSolutionType> & BakedInControllers;
+    controllers: import("../types/controller-inference.js").InferControllersMapFromDefinition<TControllerDefinitions, T>;
 }>;

package/dist/definitions/ssr-next/commerce/factories/hydrated-state-factory.d.ts

@@ -1,8 +1,4 @@
 import type { SolutionType } from '../types/controller-constants.js';
-import type { AugmentedControllerDefinition } from '../types/controller-definitions.js';
-import type { CommerceControllerDefinitionsMap, HydrateStaticStateParameters } from '../types/engine.js';
+import type { CommerceControllerDefinitionsMap, HydrateStaticStateFunction } from '../types/engine.js';
 import { type CommerceEngineDefinitionOptions } from './build-factory.js';
-export declare function hydratedStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): <TSolutionType extends SolutionType>(solutionType: TSolutionType) => (...params: HydrateStaticStateParameters<TControllerDefinitions, TSolutionType>) => Promise<{
-    engine: import("./build-factory.js").SSRCommerceEngine;
-    controllers: import("../types/controller-inference.js").InferControllersMapFromDefinition<TControllerDefinitions, TSolutionType> & import("../types/controller-definitions.js").BakedInControllers;
-}>;
+export declare function hydratedStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): (solutionType: SolutionType) => HydrateStaticStateFunction<TControllerDefinitions>;

package/dist/definitions/ssr-next/commerce/factories/recommendation-hydrated-state-factory.d.ts

@@ -1,5 +1,3 @@
-import { SolutionType } from '../types/controller-constants.js';
-import type { AugmentedControllerDefinition } from '../types/controller-definitions.js';
 import type { CommerceControllerDefinitionsMap, HydrateStaticStateFunction } from '../types/engine.js';
 import { type CommerceEngineDefinitionOptions } from './build-factory.js';
-export declare function hydratedRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): HydrateStaticStateFunction<TControllerDefinitions, SolutionType.recommendation>;
+export declare function hydratedRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): HydrateStaticStateFunction<TControllerDefinitions>;

package/dist/definitions/ssr-next/commerce/factories/recommendation-static-state-factory.d.ts

@@ -1,14 +1,4 @@
-import type { UnknownAction } from '@reduxjs/toolkit';
-import { SolutionType } from '../types/controller-constants.js';
 import type { AugmentedControllerDefinition } from '../types/controller-definitions.js';
-import type { CommerceControllerDefinitionsMap, FetchStaticStateParameters } from '../types/engine.js';
+import type { CommerceControllerDefinitionsMap, FetchStaticStateFunction } from '../types/engine.js';
 import { type CommerceEngineDefinitionOptions } from './build-factory.js';
-export declare function fetchRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): (...params: FetchStaticStateParameters<TControllerDefinitions, SolutionType.recommendation>) => Promise<{
-    controllers: import("../types/controller-inference.js").InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllerDefinitions, SolutionType.recommendation> & import("../types/controller-definitions.js").FilteredBakedInControllers<SolutionType.recommendation>;
-    searchActions: UnknownAction[];
-    context: import("../../../commerce.index.js").ContextOptions;
-    searchParams?: import("../../../commerce.index.js").ParameterManagerState<import("../../../commerce.index.js").Parameters>["parameters"];
-    cart?: import("../../../commerce.index.js").CartInitialState;
-    productId?: string;
-    recommendations: Extract<keyof TControllerDefinitions, { [K in keyof TControllerDefinitions]: import("../../common/types/utilities.js").HasKey<TControllerDefinitions[K], SolutionType.recommendation> extends never ? never : import("../../common/types/utilities.js").HasKey<TControllerDefinitions[K], typeof import("../types/controller-constants.js").recommendationInternalOptionKey> extends never ? never : K; }[keyof TControllerDefinitions]>[];
-}>;
+export declare function fetchRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): FetchStaticStateFunction<TControllerDefinitions>;

package/dist/definitions/ssr-next/commerce/factories/static-state-factory.d.ts

@@ -1,10 +1,5 @@
-import type { UnknownAction } from '@reduxjs/toolkit';
-import type { BuildConfig } from '../types/build.js';
 import { SolutionType } from '../types/controller-constants.js';
 import type { AugmentedControllerDefinition } from '../types/controller-definitions.js';
-import type { CommerceControllerDefinitionsMap, FetchStaticStateParameters } from '../types/engine.js';
+import type { CommerceControllerDefinitionsMap, FetchStaticStateFunction } from '../types/engine.js';
 import { type CommerceEngineDefinitionOptions } from './build-factory.js';
-export declare function fetchStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): <TSolutionType extends SolutionType>(solutionType: TSolutionType) => (...params: FetchStaticStateParameters<TControllerDefinitions, TSolutionType>) => Promise<BuildConfig<TControllerDefinitions, TSolutionType> & {
-    controllers: import("../types/controller-inference.js").InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllerDefinitions, TSolutionType> & import("../types/controller-definitions.js").FilteredBakedInControllers<TSolutionType>;
-    searchActions: UnknownAction[];
-}>;
+export declare function fetchStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): (solutionType: SolutionType) => FetchStaticStateFunction<TControllerDefinitions>;

package/dist/definitions/ssr-next/commerce/types/build.d.ts

@@ -1,73 +1,38 @@
+import type { CurrencyCodeISO4217 } from '@coveo/relay-event-types';
 import type { CommerceEngineOptions } from '../../../app/commerce-engine/commerce-engine.js';
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
-import type { HasKey, OptionsTuple } from '../../common/types/utilities.js';
+import type { OptionsTuple } from '../../common/types/utilities.js';
 import type { CartInitialState } from '../controllers/cart/headless-cart.ssr.js';
-import type { ContextOptions } from '../controllers/context/headless-context.ssr.js';
+import type { UserLocation } from '../controllers/context/headless-context.ssr.js';
 import type { ParameterManagerState, Parameters } from '../controllers/parameter-manager/headless-core-parameter-manager.ssr.js';
 import type { SolutionType } from './controller-constants.js';
-import type { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption, IsRecommendationController } from './controller-definitions.js';
+import type { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption } from './controller-definitions.js';
 import type { CommerceEngineDefinitionBuildResult } from './engine.js';
 export interface SearchBuildConfig extends CommonBuildConfig {
     searchParams: ParameterManagerState<Parameters & {
         query: string;
     }>['parameters'];
 }
-/**
- * RecommendationBuildConfig defines the shape of the config object required when fetching static state for recommendations.
- *
- * The `recommendations` property is a string array containing the names of the recommendation controllers
- * that were defined in your engine definition. This allows you to specify which recommendation controllers
- * should be included in the SSR request.
- *
- * For example, on a storefront homepage, it might make sense to display a carousel of popular products.
- * However, showing recommendations based on items frequently bought together may not be relevant in that context and should not be retrieved unnecessarily.
- *
- * @example
- * Given the following engine definition:
- *
- * ```ts
- * const {recommendationEngineDefinition} = defineCommerceEngine({
- *   controllers: {
- *     popularProducts: defineRecommendations({options: {slotId: '...'}}),
- *     frequentlyBought: defineRecommendations({options: {slotId: '...'}}),
- *     // ...other controllers
- *   },
- * });
- *
- * // When fetching static state for recommendations:
- * const staticState = await recommendationEngineDefinition.fetchStaticState({
- *   recommendations: ['popularProducts'],
- *   // ...other config
- * });
- * ```
- *
- * In this example, only the `popularProducts` recommendation controller will be included in the SSR request.
- */
-export type RecommendationBuildConfig<TControllers extends ControllerDefinitionsMap<Controller>> = CommonBuildConfig & {
-    /**
-     * The unique identifier of the product to use for seeded recommendations.
-     */
-    productId?: string;
-    /**
-     * An array of recommendation controller names from your engine definition to include in the SSR request.
-     * Each name corresponds to the key used when defining recommendation controllers in your engine definition.
-     * If not specified, no recommendation requests will be executed.
-     */
-    recommendations: Array<Extract<keyof TControllers, {
-        [K in keyof TControllers]: HasKey<TControllers[K], SolutionType.recommendation> extends never ? never : IsRecommendationController<TControllers[K]> extends never ? never : K;
-    }[keyof TControllers]>>;
-};
+export interface RecommendationBuildConfig extends CommonBuildConfig {
+    recommendations?: [];
+}
 export interface ListingBuildConfig extends CommonBuildConfig {
 }
 export interface StandaloneBuildConfig extends CommonBuildConfig {
 }
 export interface CommonBuildConfig {
-    context: ContextOptions;
+    context: {
+        url: string;
+        language: string;
+        country: string;
+        currency: CurrencyCodeISO4217;
+        location?: UserLocation;
+    };
     searchParams?: ParameterManagerState<Parameters>['parameters'];
     cart?: CartInitialState;
 }
-export type BuildConfig<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = TSolutionType extends SolutionType.search ? SearchBuildConfig : TSolutionType extends SolutionType.listing ? ListingBuildConfig : TSolutionType extends SolutionType.recommendation ? RecommendationBuildConfig<TControllers> : TSolutionType extends SolutionType.standalone ? CommonBuildConfig : never;
+export type BuildConfig<TSolutionType extends SolutionType> = TSolutionType extends SolutionType.search ? SearchBuildConfig : TSolutionType extends SolutionType.listing ? ListingBuildConfig : TSolutionType extends SolutionType.recommendation ? RecommendationBuildConfig : TSolutionType extends SolutionType.standalone ? CommonBuildConfig : never;
 /**
  * Commerce engine options for SSR scenarios where context is defined when fetching static state.
  */
@@ -77,4 +42,4 @@ export type SSRCommerceEngineOptions = Omit<CommerceEngineOptions, 'configuratio
 /**
  * @internal
  */
-export type Build<TControllersMap extends ControllersMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<BuildConfig<TControllersDefinitionsMap, TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<CommerceEngineDefinitionBuildResult<TControllersMap>>;
+export type Build<TControllersMap extends ControllersMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<BuildConfig<TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<CommerceEngineDefinitionBuildResult<TControllersMap>>;

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

@@ -3,7 +3,7 @@ import type { InvalidControllerDefinition } from '../../common/errors.js';
 import type { ControllersPropsMap } from '../../common/types/controllers.js';
 import type { HydratedState } from '../../common/types/hydrate-static-state.js';
 import type { InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers } from '../../common/types/inference.js';
-import type { HasKey, HasRequiredKeys, OptionsTuple } from '../../common/types/utilities.js';
+import type { HasKey, HasOptionalKeys, HasRequiredKeys, OptionsTuple } from '../../common/types/utilities.js';
 import type { CartDefinition } from '../controllers/cart/headless-cart.ssr.js';
 import type { ContextDefinition } from '../controllers/context/headless-context.ssr.js';
 import type { ParameterManagerDefinition } from '../controllers/parameter-manager/headless-core-parameter-manager.ssr.js';
@@ -13,6 +13,15 @@ import type { ListingAndStandaloneController, ListingOnlyController, NonRecommen
 import type { Kind } from './kind.js';
 import type { HasSolutionType } from './utilities.js';
 export type { HydratedState, OptionsTuple, InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers, };
+export type RecommendationControllerSettings = {
+    /**
+     * Toggle to enable or disable the recommendation controller.
+     * When set to `true`, the controller will perform a recommendation request server-side.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+};
 export interface ControllerDefinitionWithoutProps<TController extends Controller> {
     /**
      * Creates an instance of the given controller.
@@ -85,14 +94,120 @@ export type AugmentedControllerDefinition<TControllerDefinitions extends Control
 /**
  * This type defines the required and optional controller props for the engine definition.
  */
-export type EngineDefinitionControllersPropsOption<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType> = RequiredEngineDefinitionControllersPropsOption<TControllers, TControllersPropsMap, TSolutionType>;
+export type EngineDefinitionControllersPropsOption<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType> = OptionalEngineDefinitionControllersPropsOption<TControllers, TControllersPropsMap, TSolutionType> & RequiredEngineDefinitionControllersPropsOption<TControllers, TControllersPropsMap, TSolutionType>;
+/**
+ * Represents an optional engine definition for controller properties.
+ *
+ * This type is used to define a map of optional controller properties based on the provided
+ * controller definitions, controller properties map, and solution type.
+ *
+ * @template TControllers - A map of controller definitions.
+ * @template TControllersPropsMap - A map of controller properties.
+ * @template TSolutionType - The type of solution.
+ *
+ * The type iterates over the controller keys (defined in the engine definition) and includes only those keys where:
+ * 1. The controller can be used for a specific solution type (HasKey<TControllers[K], TSolutionType> is not 'never').
+ * 2. The controller properties have optional options (HasOptionalKeys<ConditionalControllerProps<...>> is true).
+ *
+ * @example
+ * Given the following controller definitions:
+ * ```
+ * const {recommendationEngineDefinition} = defineCommerceEngine({
+ *  controllers: {
+ *    popularViewed: defineRecommendations({
+ *      options: {slotId: 'slot-id'}
+ *    })
+ *  }
+ * });
+ * ```
+ *
+ * The following code will not throw an error since the 'popularViewed' controller props are optional
+ * ```
+ * recommendationEngineDefinition.fetchStaticState({
+ *  controllers: {
+ *    popularViewed: {enabled: true, productId: 'some-product-id'} // This is optional
+ *  }
+ * })
+ * ```
+ *
+ * The following code (with no arguments) is also valid because the 'popularViewed' controller props are optional, and there are no other required controller props in the engine definition.
+ * ```
+ * recommendationEngineDefinition.fetchStaticState()
+ * ```
+ */
+type OptionalEngineDefinitionControllersPropsOption<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType> = {
+    [K in keyof TControllers as HasKey<TControllers[K], TSolutionType> extends never ? never : HasOptionalKeys<ConditionalControllerProps<TControllers, TControllersPropsMap, TSolutionType, K>> extends false ? never : 'controllers']?: ConditionalControllerProps<TControllers, TControllersPropsMap, TSolutionType, K>;
+};
+/**
+ * Represents a type that defines the required controller properties for engine definition controllers.
+ *
+ * @template TControllers - A map of controller definitions.
+ * @template TControllersPropsMap - A map of controller properties.
+ * @template TSolutionType - The type of solution being used.
+ *
+ * The type iterates over the controller keys (defined in the engine definition) and includes only those keys where:
+ * 1. The controller can be used for a specific solution type (HasKey<TControllers[K], TSolutionType> is not 'never').
+ * 2. The controller properties have required options (HasRequiredKeys<ConditionalControllerProps<...>> is true).
+ *
+ * The resulting type maps the valid keys to their corresponding conditional controller properties.
+ *
+ * @example
+ * Given the following controller definitions:
+ * ```
+ * const {standaloneEngineDefinition} = defineCommerceEngine({
+ *  controllers: {cart: defineCart()},
+ * });
+ * ```
+ *
+ * The following code will not throw an error since the 'cart' controller props are required for the standalone engine definition:
+ * ```
+ * standaloneEngineDefinition.fetchStaticState({
+ *   controllers: {
+ *     cart: {initialState: {items: []}},
+ *   },
+ * })
+ * ```
+ *
+ */
 type RequiredEngineDefinitionControllersPropsOption<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType> = {
-    [K in keyof TControllers as HasKey<TControllers[K], TSolutionType> extends never ? never : IsRecommendationController<TControllers[K]> extends never ? HasRequiredKeys<DefaultControllerProps<TControllers, TControllersPropsMap, K>> extends false ? never : 'controllers' : never]: DefaultControllerProps<TControllers, TControllersPropsMap, K>;
+    [K in keyof TControllers as HasKey<TControllers[K], TSolutionType> extends never ? never : HasRequiredKeys<ConditionalControllerProps<TControllers, TControllersPropsMap, TSolutionType, K>> extends false ? never : 'controllers']: ConditionalControllerProps<TControllers, TControllersPropsMap, TSolutionType, K>;
+};
+type IsRecommendationController<TController extends ControllerDefinition<Controller>> = HasKey<TController, typeof recommendationInternalOptionKey>;
+/**
+ * This type ensures that recommendation controller props are optional, while other controller props remain required.
+ *
+ * It works by checking if the controller definition includes the `recommendationInternalOptionKey`.
+ *
+ * - If the key is present, the controller props are made optional.
+ * - If the key is absent, the controller props are required.
+ *
+ * Example:
+ *
+ * ```typescript
+ * type ControllerProps = InferControllerPropsFromDefinition<{
+ *   recommendation: defineRecommendation({}),
+ *   cart: defineCart(),
+ * }>;
+ *
+ * // In this example:
+ * // - The `recommendation` controller props are optional.
+ * // - The `cart` controller props are required.
+ *
+ * const props: ControllerProps = {
+ *   cart: {initialState: {items: []}},
+ *   // recommendation props can be omitted
+ * };
+ * ```
+ */
+type RecommendationControllerProps<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, K extends keyof TControllers> = {
+    [I in keyof TControllersPropsMap as I extends K ? IsRecommendationController<TControllers[I]> extends never ? never : I : never]?: TControllersPropsMap[I];
+} & {
+    [I in keyof TControllersPropsMap as I extends K ? IsRecommendationController<TControllers[I]> extends never ? I : never : never]: TControllersPropsMap[I];
 };
-export type IsRecommendationController<TController extends ControllerDefinition<Controller>> = HasKey<TController, typeof recommendationInternalOptionKey>;
 type DefaultControllerProps<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, K extends keyof TControllers> = {
     [I in keyof TControllersPropsMap as I extends K ? I : never]: TControllersPropsMap[I];
 };
+type ConditionalControllerProps<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType, K extends keyof TControllers> = TSolutionType extends SolutionType.recommendation ? RecommendationControllerProps<TControllers, TControllersPropsMap, K> : DefaultControllerProps<TControllers, TControllersPropsMap, K>;
 export interface ControllerDefinitionOption {
     /**
      * Whether the controller will be used in a product listing context.

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

@@ -1,14 +1,14 @@
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { HasKey, HasKeys } from '../../common/types/utilities.js';
-import type { SolutionType } from './controller-constants.js';
-import type { ControllerDefinition, ControllerDefinitionsMap, ControllerDefinitionWithoutProps, ControllerDefinitionWithProps, InferControllerStaticStateFromController } from './controller-definitions.js';
+import type { recommendationInternalOptionKey, SolutionType } from './controller-constants.js';
+import type { ControllerDefinition, ControllerDefinitionsMap, ControllerDefinitionWithoutProps, ControllerDefinitionWithProps, InferControllerStaticStateFromController, RecommendationControllerSettings } from './controller-definitions.js';
 export type InferStaticState<T extends {
     fetchStaticState(...args: unknown[]): Promise<unknown>;
 }> = Awaited<ReturnType<T['fetchStaticState']>>;
 export type InferHydratedState<T extends {
     hydrateStaticState(...args: unknown[]): Promise<unknown>;
 }> = Awaited<ReturnType<T['hydrateStaticState']>>;
-type InferControllerPropsFromDefinition<TController extends ControllerDefinition<Controller>> = TController extends ControllerDefinitionWithProps<Controller, infer Props> ? Props : TController extends ControllerDefinitionWithoutProps<Controller> ? {} : unknown;
+type InferControllerPropsFromDefinition<TController extends ControllerDefinition<Controller>> = TController extends ControllerDefinitionWithProps<Controller, infer Props> ? HasKey<TController, typeof recommendationInternalOptionKey> extends never ? Props : Props & RecommendationControllerSettings : TController extends ControllerDefinitionWithoutProps<Controller> ? HasKey<TController, typeof recommendationInternalOptionKey> extends never ? {} : RecommendationControllerSettings : unknown;
 export type InferControllerPropsMapFromDefinitions<TControllers extends ControllerDefinitionsMap<Controller>> = {
     [K in keyof TControllers as HasKeys<InferControllerPropsFromDefinition<TControllers[K]>> extends false ? never : K]: InferControllerPropsFromDefinition<TControllers[K]>;
 };

package/dist/definitions/ssr-next/commerce/types/engine.d.ts

@@ -4,6 +4,7 @@ import type { NavigatorContextProvider } from '../../../app/navigator-context-pr
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllerStaticStateMap, ControllersMap } from '../../common/types/controllers.js';
 import type { SSRCommerceEngine } from '../factories/build-factory.js';
+import type { Build } from './build.js';
 import type { SolutionType } from './controller-constants.js';
 import type { BakedInControllers, ControllerDefinitionsMap } from './controller-definitions.js';
 import type { InferControllerPropsMapFromDefinitions, InferControllerStaticStateMapFromDefinitionsWithSolutionType, InferControllersMapFromDefinition } from './controller-inference.js';
@@ -57,13 +58,14 @@ export interface CommerceEngineDefinitionBuildResult<TControllers extends Contro
     controllers: TControllers & BakedInControllers;
 }
 export type CommerceControllerDefinitionsMap = ControllerDefinitionsMap<Controller>;
-type Definition<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = CommerceEngineDefinition<TControllerDefinitions, TSolutionType>;
-export type FetchStaticStateFunction<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = Definition<TControllerDefinitions, TSolutionType>['fetchStaticState'];
-export type HydrateStaticStateFunction<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = Definition<TControllerDefinitions, TSolutionType>['hydrateStaticState'];
-export type FetchStaticStateParameters<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = Parameters<FetchStaticStateFunction<TControllerDefinitions, TSolutionType>>;
-export type HydrateStaticStateParameters<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = Parameters<HydrateStaticStateFunction<TControllerDefinitions, TSolutionType>>;
-type Controllers<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = InferControllersMapFromDefinition<TControllerDefinitions, TSolutionType>;
-export type BuildResult<TControllerDefinitions extends CommerceControllerDefinitionsMap, TSolutionType extends SolutionType> = {
+type Definition<TControllerDefinitions extends CommerceControllerDefinitionsMap> = CommerceEngineDefinition<TControllerDefinitions, SolutionType>;
+export type FetchStaticStateFunction<TControllerDefinitions extends CommerceControllerDefinitionsMap> = Definition<TControllerDefinitions>['fetchStaticState'];
+export type HydrateStaticStateFunction<TControllerDefinitions extends CommerceControllerDefinitionsMap> = Definition<TControllerDefinitions>['hydrateStaticState'];
+export type BuildParameters<TControllerDefinitions extends CommerceControllerDefinitionsMap> = Parameters<Build<InferControllersMapFromDefinition<TControllerDefinitions, SolutionType>, InferControllerPropsMapFromDefinitions<TControllerDefinitions>, TControllerDefinitions, SolutionType>>;
+export type FetchStaticStateParameters<TControllerDefinitions extends CommerceControllerDefinitionsMap> = Parameters<FetchStaticStateFunction<TControllerDefinitions>>;
+export type HydrateStaticStateParameters<TControllerDefinitions extends CommerceControllerDefinitionsMap> = Parameters<HydrateStaticStateFunction<TControllerDefinitions>>;
+type Controllers<TControllerDefinitions extends CommerceControllerDefinitionsMap> = InferControllersMapFromDefinition<TControllerDefinitions, SolutionType>;
+export type BuildResult<TControllerDefinitions extends CommerceControllerDefinitionsMap> = {
     engine: SSRCommerceEngine;
-    controllers: Controllers<TControllerDefinitions, TSolutionType> & BakedInControllers;
+    controllers: Controllers<TControllerDefinitions> & BakedInControllers;
 };

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

@@ -10,4 +10,4 @@ import type { EngineStaticState } from './engine.js';
  *
  * Useful for static generation and server-side rendering.
  */
-export type FetchStaticState<TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<BuildConfig<TControllersDefinitionsMap, TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<EngineStaticState<TSearchAction, TControllersStaticState & FilteredBakedInControllers<TSolutionType>> & BuildConfig<TControllersDefinitionsMap, TSolutionType>>;
+export type FetchStaticState<TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<BuildConfig<TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<EngineStaticState<TSearchAction, TControllersStaticState & FilteredBakedInControllers<TSolutionType>>>;

package/dist/definitions/ssr-next/commerce/types/hydrate-static-state.d.ts

@@ -3,7 +3,6 @@ import type { Controller } from '../../../controllers/controller/headless-contro
 import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
 import type { HydratedState } from '../../common/types/hydrate-static-state.js';
 import type { SSRCommerceEngine } from '../factories/build-factory.js';
-import type { BuildConfig } from './build.js';
 import type { SolutionType } from './controller-constants.js';
 import type { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption, OptionsTuple } from './controller-definitions.js';
 export interface HydrateStaticStateOptions<TSearchAction> {
@@ -14,4 +13,4 @@ export interface HydrateStaticStateOptions<TSearchAction> {
  *
  * Useful when hydrating a server-side-rendered engine.
  */
-export type HydrateStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & BuildConfig<TControllersDefinitionsMap, TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<HydratedState<SSRCommerceEngine, TControllers>>;
+export type HydrateStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<HydratedState<SSRCommerceEngine, TControllers>>;

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

@@ -1,35 +1,8 @@
-import { Schema } from '@coveo/bueno';
 import type { ControllersPropsMap } from '../../common/types/controllers.js';
 import type { BuildConfig } from '../types/build.js';
-import { SolutionType } from '../types/controller-constants.js';
+import type { SolutionType } from '../types/controller-constants.js';
 import type { InferControllerPropsMapFromDefinitions } from '../types/controller-inference.js';
 import type { CommerceControllerDefinitionsMap } from '../types/engine.js';
-export declare const listingDefinitionSchema: Schema<{
-    searchParams: unknown;
-    context: unknown;
-}>;
-export declare const searchDefinitionSchema: Schema<{
-    searchParams: unknown;
-    context: unknown;
-}>;
-export declare const standaloneDefinitionSchema: Schema<{
-    context: unknown;
-}>;
-export declare const recommendationsDefinitionSchema: (recommendationName: string[]) => Schema<{
-    recommendations: import("@coveo/bueno").PrimitivesValues[] | null | undefined;
-    productId: string;
-    context: unknown;
-}>;
-/**
- * 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 declare function wireControllerParams<TControllerDefinitions extends CommerceControllerDefinitionsMap>(solutionType: SolutionType, controllerDefinitions: TControllerDefinitions, buildConfig: BuildConfig<TControllerDefinitions, SolutionType> & {
+export declare function wireControllerParams<TControllerDefinitions extends CommerceControllerDefinitionsMap>(_solutionType: SolutionType, _controllerDefinitions: TControllerDefinitions, _paramsObject: BuildConfig<SolutionType> & {
     controllers?: ControllersPropsMap;
 }): InferControllerPropsMapFromDefinitions<TControllerDefinitions>;

package/dist/definitions/ssr-next/commerce/utils/engine-wiring.d.ts

@@ -2,4 +2,4 @@ import type { CommerceEngineConfiguration } from '../../../app/commerce-engine/c
 import type { CommerceEngineDefinitionOptions } from '../factories/build-factory.js';
 import type { CommonBuildConfig } from '../types/build.js';
 import type { CommerceControllerDefinitionsMap } from '../types/engine.js';
-export declare function extendEngineConfiguration<TControllerDefinitions extends CommerceControllerDefinitionsMap>(configuration: CommerceEngineDefinitionOptions<TControllerDefinitions>['configuration'], commonBuildOptions: CommonBuildConfig): CommerceEngineConfiguration;
+export declare function extendEngineConfiguration<TControllerDefinitions extends CommerceControllerDefinitionsMap>(_configuration: CommerceEngineDefinitionOptions<TControllerDefinitions>['configuration'], _commonBuildOptions: CommonBuildConfig): CommerceEngineConfiguration;