@coveo/quantic 3.10.0 → 3.11.1

package/force-app/main/default/staticresources/coveoheadless/definitions/api/analytics/instant-result-analytics.d.ts

@@ -6,7 +6,7 @@ export declare class InstantResultsAnalyticsProvider extends SearchAnalyticsProv
     constructor(getState: () => StateNeededByInstantResultsAnalyticsProvider);
     private get activeInstantResultQuery();
     private get activeInstantResultCache();
-    protected get results(): import("../../case-assist.index.js").Result[] | undefined;
+    protected get results(): import("../../ssr.index.js").Result[] | undefined;
     protected get queryText(): string;
     protected get responseTime(): number;
     protected get numberOfResults(): number;

package/force-app/main/default/staticresources/coveoheadless/definitions/api/analytics/search-analytics.d.ts

@@ -85,7 +85,7 @@ export declare class SearchAnalyticsProvider extends BaseAnalyticsProvider<State
     };
     getGeneratedAnswerMetadata(): Record<string, string | boolean>;
     private get resultURIs();
-    protected get results(): import("../../case-assist.index.js").Result[] | undefined;
+    protected get results(): import("../../ssr.index.js").Result[] | undefined;
     protected get queryText(): string;
     protected get responseTime(): number;
     protected get numberOfResults(): number;

package/force-app/main/default/staticresources/coveoheadless/definitions/api/knowledge/stream-answer-api.d.ts

@@ -1,4 +1,5 @@
-import { UnknownAction } from '@reduxjs/toolkit';
+import { EventSourceMessage } from '@microsoft/fetch-event-source';
+import { ThunkDispatch, UnknownAction } from '@reduxjs/toolkit';
 import { GeneratedContentFormat } from '../../features/generated-answer/generated-response-format.js';
 import { SearchAppState } from '../../state/search-app-state.js';
 import { ConfigurationSection, GeneratedAnswerSection, InsightConfigurationSection } from '../../state/state-sections.js';
@@ -22,6 +23,7 @@ export interface GeneratedAnswerStream {
         code: number;
     };
 }
+export declare const updateCacheWithEvent: (event: EventSourceMessage, draft: GeneratedAnswerStream, dispatch: ThunkDispatch<StateNeededByAnswerAPI, unknown, UnknownAction>) => void;
 export declare const answerApi: import("@reduxjs/toolkit/query").Api<import("@reduxjs/toolkit/query").BaseQueryFn<string | import("@reduxjs/toolkit/query").FetchArgs, unknown, import("@reduxjs/toolkit/query").FetchBaseQueryError, {} & import("@reduxjs/toolkit/query").RetryOptions, {}>, {
     getAnswer: import("@reduxjs/toolkit/query").QueryDefinition<Partial<SearchRequest>, import("@reduxjs/toolkit/query").BaseQueryFn<string | import("@reduxjs/toolkit/query").FetchArgs, unknown, import("@reduxjs/toolkit/query").FetchBaseQueryError, {} & import("@reduxjs/toolkit/query").RetryOptions, {}>, never, GeneratedAnswerStream, "answer">;
 }, "answer", never, typeof import("@reduxjs/toolkit/query").coreModuleName>;

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-engine/commerce-engine.ssr.d.ts

@@ -13,6 +13,8 @@ export interface CommerceEngineDefinition<TControllers extends ControllerDefinit
  * @param options - The commerce 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.
+ *
+ * @group Engine
  */
 export declare function defineCommerceEngine<TControllerDefinitions extends ControllerDefinitionsMap<Controller>>(options: CommerceEngineDefinitionOptions<TControllerDefinitions>): {
     listingEngineDefinition: CommerceEngineDefinition<TControllerDefinitions, SolutionType.listing>;

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/factories/build-factory.d.ts

@@ -5,6 +5,8 @@ import { ControllerDefinitionsMap, SolutionType } from '../types/common.js';
 import { BuildParameters, CommerceControllerDefinitionsMap, EngineDefinitionOptions } from '../types/core-engine.js';
 /**
  * The SSR commerce engine.
+ *
+ * @group Engine
  */
 export interface SSRCommerceEngine extends CommerceEngine {
     /**

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/factories/utils/recommendation-filter.d.ts

@@ -0,0 +1,11 @@
+import { Controller } from '../../../../controllers/controller/headless-controller.js';
+import { ControllerDefinitionsMap } from '../../types/common.js';
+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.
+     *
+     * @param controllers - A record of all controllers where the key is the controller name and the value is the controller instance.
+     * @param controllerNames - A list of all recommendation controllers to refresh
+     */
+    refresh(whitelist?: string[]): void;
+};

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/build.d.ts

@@ -1,17 +1,13 @@
+import { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllersMap, ControllersPropsMap, EngineDefinitionBuildResult, OptionsExtender, OptionsTuple } from '../../ssr-engine/types/common.js';
 import { SSRCommerceEngine } from '../factories/build-factory.js';
-import { EngineDefinitionControllersPropsOption, SolutionType } from './common.js';
+import { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption, SolutionType } from './common.js';
 export interface BuildOptions<TEngineOptions> {
     extend?: OptionsExtender<TEngineOptions>;
 }
-export type Build<TEngineOptions, TControllersMap extends ControllersMap, TControllersProps extends ControllersPropsMap, TSolutionType extends SolutionType> = TSolutionType extends SolutionType.recommendation ? {
+export type Build<TEngineOptions, TControllersMap extends ControllersMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     /**
      * Initializes an engine and controllers from the definition.
      */
-    (controllers: (keyof TControllersMap)[]): Promise<EngineDefinitionBuildResult<SSRCommerceEngine, TControllersMap>>;
-} : {
-    /**
-     * Initializes an engine and controllers from the definition.
-     */
-    (...params: OptionsTuple<BuildOptions<TEngineOptions> & EngineDefinitionControllersPropsOption<TControllersProps>>): Promise<EngineDefinitionBuildResult<SSRCommerceEngine, TControllersMap>>;
+    (...params: OptionsTuple<BuildOptions<TEngineOptions> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>): Promise<EngineDefinitionBuildResult<SSRCommerceEngine, TControllersMap>>;
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/common.d.ts

@@ -1,15 +1,26 @@
 import { UnknownAction } from '@reduxjs/toolkit';
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { InvalidControllerDefinition } from '../../../utils/errors.js';
-import type { HasKey, InferControllerStaticStateMapFromControllers, InferControllerStaticStateFromController, InferControllerPropsMapFromDefinitions, ControllerStaticStateMap, EngineDefinitionBuildResult, EngineDefinitionControllersPropsOption, HydratedState, OptionsTuple } from '../../ssr-engine/types/common.js';
+import type { HasKey, InferControllerStaticStateMapFromControllers, InferControllerStaticStateFromController, ControllerStaticStateMap, EngineDefinitionBuildResult, HydratedState, OptionsTuple, ControllersPropsMap, HasKeys, HasRequiredKeys, HasOptionalKeys } from '../../ssr-engine/types/common.js';
 import { SSRCommerceEngine } from '../factories/build-factory.js';
-export type { EngineDefinitionBuildResult, EngineDefinitionControllersPropsOption, HydratedState, OptionsTuple, InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers, InferControllerPropsMapFromDefinitions, };
+import { Kind } from './kind.js';
+export type { EngineDefinitionBuildResult, HydratedState, OptionsTuple, InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers, };
 export declare enum SolutionType {
     search = "search",
     listing = "listing",
     standalone = "standalone",
     recommendation = "recommendation"
 }
+export declare const recommendationInternalOptionKey: unique symbol;
+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.
@@ -20,6 +31,9 @@ export interface ControllerDefinitionWithoutProps<TController extends Controller
      */
     build(engine: SSRCommerceEngine, solutionType?: SolutionType): TController;
 }
+export interface ControllerWithKind extends Controller {
+    _kind: Kind;
+}
 export interface ControllerDefinitionWithProps<TController extends Controller, TProps> {
     /**
      * Creates an instance of the given controller.
@@ -29,17 +43,26 @@ export interface ControllerDefinitionWithProps<TController extends Controller, T
      * @param solutionType - The type of solution for which the controller should be built (e.g. search or listing). This option only applies to sub-controllers.
      * @returns The created controller instance.
      */
-    buildWithProps(engine: SSRCommerceEngine, props: TProps, solutionType?: SolutionType): TController;
+    buildWithProps(engine: SSRCommerceEngine, props: TProps, solutionType?: SolutionType): TController & ControllerWithKind;
 }
 export interface EngineStaticState<TSearchAction extends UnknownAction, TControllers extends ControllerStaticStateMap> {
     searchActions: TSearchAction[];
     controllers: TControllers;
 }
-export type ControllerDefinition<TController extends Controller> = ControllerDefinitionWithoutProps<TController> | ControllerDefinitionWithProps<TController, unknown>;
+export interface SolutionTypeAvailability {
+    [SolutionType.search]?: boolean;
+    [SolutionType.listing]?: boolean;
+    [SolutionType.standalone]?: boolean;
+    [SolutionType.recommendation]?: boolean;
+}
+export type ControllerDefinition<TController extends Controller> = SolutionTypeAvailability & (ControllerDefinitionWithoutProps<TController> | ControllerDefinitionWithProps<TController, unknown>);
 export interface ControllerDefinitionsMap<TController extends Controller> {
     [customName: string]: ControllerDefinition<TController>;
 }
-export type InferControllerPropsFromDefinition<TController extends ControllerDefinition<Controller>> = TController extends ControllerDefinitionWithProps<Controller, infer Props> ? Props : TController extends ControllerDefinitionWithoutProps<Controller> ? {} : unknown;
+export 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]>;
+};
 export type InferControllerFromDefinition<TDefinition extends ControllerDefinition<Controller>> = TDefinition extends ControllerDefinition<infer TController> ? TController : never;
 export type InferControllersMapFromDefinition<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     [K in keyof TControllers as HasKey<TControllers[K], TSolutionType> extends never ? never : K]: InferControllerFromDefinition<TControllers[K]>;
@@ -47,6 +70,123 @@ export type InferControllersMapFromDefinition<TControllers extends ControllerDef
 export type InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     [K in keyof TControllers as HasKey<TControllers[K], TSolutionType> extends never ? never : K]: InferControllerStaticStateFromController<InferControllerFromDefinition<TControllers[K]>>;
 };
+/**
+ * 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> = 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()
+ * ```
+ */
+export 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: []}},
+ *   },
+ * })
+ * ```
+ *
+ */
+export type RequiredEngineDefinitionControllersPropsOption<TControllers extends ControllerDefinitionsMap<Controller>, TControllersPropsMap extends ControllersPropsMap, TSolutionType extends SolutionType> = {
+    [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];
+};
+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.
@@ -59,6 +199,20 @@ export interface ControllerDefinitionOption {
      */
     search?: boolean;
 }
+interface NonRecommendationController {
+    /**
+     * @internal
+     */
+    [SolutionType.search]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.standalone]: true;
+}
 interface UniversalController {
     /**
      * @internal
@@ -72,6 +226,10 @@ interface UniversalController {
      * @internal
      */
     [SolutionType.standalone]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.recommendation]: true;
 }
 interface SearchOnlyController {
     /**
@@ -101,14 +259,27 @@ interface SearchAndListingController {
      */
     [SolutionType.listing]: true;
 }
+interface ListingAndStandaloneController {
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.standalone]: true;
+}
 export type SearchOnlyControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & SearchOnlyController;
 export type SearchOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & SearchOnlyController;
+export type ListingAndStandaloneControllerWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & ListingAndStandaloneController;
 export type ListingOnlyControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & ListingOnlyController;
 export type ListingOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & ListingOnlyController;
 export type RecommendationOnlyControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & RecommendationOnlyController;
 export type RecommendationOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & RecommendationOnlyController;
-export type NonRecommendationControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & UniversalController;
-export type NonRecommendationControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & UniversalController;
+export type NonRecommendationControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & NonRecommendationController;
+export type NonRecommendationControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & NonRecommendationController;
+export type UniversalControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & UniversalController;
+export type UniversalControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & UniversalController;
 export type SearchAndListingControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & SearchAndListingController;
 export type SearchAndListingControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & SearchAndListingController;
 export type SubControllerDefinitionWithoutProps<TController extends Controller, TDefinition extends ControllerDefinitionOption | undefined> = TDefinition extends {

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/core-engine.d.ts

@@ -23,15 +23,15 @@ export interface EngineDefinition<TControllers extends ControllerDefinitionsMap<
     /**
      * Fetches the static state on the server side using your engine definition.
      */
-    fetchStaticState: FetchStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllers, TSolutionType>, InferControllerPropsMapFromDefinitions<TControllers>, TSolutionType>;
+    fetchStaticState: FetchStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllers, TSolutionType>, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
     /**
      * Fetches the hydrated state on the client side using your engine definition and the static state.
      */
-    hydrateStaticState: HydrateStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerPropsMapFromDefinitions<TControllers>, TSolutionType>;
+    hydrateStaticState: HydrateStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
     /**
      * Builds an engine and its controllers from an engine definition.
      */
-    build: Build<TEngineOptions, InferControllersMapFromDefinition<TControllers, TSolutionType>, InferControllerPropsMapFromDefinitions<TControllers>, TSolutionType>;
+    build: Build<TEngineOptions, InferControllersMapFromDefinition<TControllers, TSolutionType>, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
     /**
      * Sets the navigator context provider.
      * This provider is essential for retrieving navigation-related data such as referrer, userAgent, location, and clientId, which are crucial for handling both server-side and client-side API requests effectively.

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/fetch-static-state.d.ts

@@ -1,23 +1,15 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
-import { SolutionType } from '../../commerce-ssr-engine/types/common.js';
-import type { EngineDefinitionControllersPropsOption, EngineStaticState } from '../../commerce-ssr-engine/types/common.js';
+import { Controller } from '../../../controllers/controller/headless-controller.js';
+import type { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption, EngineStaticState, SolutionType } from '../../commerce-ssr-engine/types/common.js';
 import type { ControllersMap, ControllersPropsMap, ControllerStaticStateMap, OptionsTuple } from '../../ssr-engine/types/common.js';
 import { FromBuildResult } from './from-build-result.js';
 export type FetchStaticStateOptions = {};
-export type FetchStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap, TSolutionType extends SolutionType> = TSolutionType extends SolutionType.recommendation ? {
+export type FetchStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     /**
      * 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.
      */
-    (controllers: Array<keyof TControllers>): Promise<EngineStaticState<TSearchAction, TControllersStaticState>>;
-    fromBuildResult: FromBuildResult<TControllers, FetchStaticStateOptions, EngineStaticState<TSearchAction, TControllersStaticState>>;
-} : {
-    /**
-     * 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.
-     */
-    (...params: OptionsTuple<FetchStaticStateOptions & EngineDefinitionControllersPropsOption<TControllersProps>>): Promise<EngineStaticState<TSearchAction, TControllersStaticState>>;
+    (...params: OptionsTuple<FetchStaticStateOptions & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>): Promise<EngineStaticState<TSearchAction, TControllersStaticState>>;
     fromBuildResult: FromBuildResult<TControllers, FetchStaticStateOptions, EngineStaticState<TSearchAction, TControllersStaticState>>;
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/from-build-result.d.ts

@@ -13,7 +13,7 @@ export interface FromBuildResultOptions<TControllers extends ControllersMap> {
      *
      * This is applicable only if the engine is a recommendation engine.
      */
-    allowedRecommendationKeys?: (keyof TControllers)[];
+    allowedRecommendationKeys?: string[];
 }
 export interface FromBuildResult<TControllers extends ControllersMap, TOptions, TReturn> {
     (options: FromBuildResultOptions<TControllers> & TOptions): Promise<TReturn>;

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/hydrate-static-state.d.ts

@@ -1,25 +1,18 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
+import { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllersMap, ControllersPropsMap, HydratedState, OptionsTuple } from '../../ssr-engine/types/common.js';
 import { SSRCommerceEngine } from '../factories/build-factory.js';
-import { EngineDefinitionControllersPropsOption, SolutionType } from './common.js';
+import { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption, SolutionType } from './common.js';
 import { FromBuildResult } from './from-build-result.js';
 export interface HydrateStaticStateOptions<TSearchAction> {
     searchActions: TSearchAction[];
 }
-export type HydrateStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap, TSolutionType extends SolutionType> = TSolutionType extends SolutionType.recommendation ? {
+export type HydrateStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     /**
      * Creates a new engine from the snapshot of the engine created in SSR with fetchStaticState.
      *
      * Useful when hydrating a server-side-rendered engine.
      */
-    (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction>>): Promise<HydratedState<SSRCommerceEngine, TControllers>>;
-    fromBuildResult: FromBuildResult<TControllers, HydrateStaticStateOptions<TSearchAction>, HydratedState<SSRCommerceEngine, TControllers>>;
-} : {
-    /**
-     * Creates a new engine from the snapshot of the engine created in SSR with fetchStaticState.
-     *
-     * Useful when hydrating a server-side-rendered engine.
-     */
-    (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & EngineDefinitionControllersPropsOption<TControllersProps>>): Promise<HydratedState<SSRCommerceEngine, TControllers>>;
+    (...params: OptionsTuple<HydrateStaticStateOptions<TSearchAction> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>): Promise<HydratedState<SSRCommerceEngine, TControllers>>;
     fromBuildResult: FromBuildResult<TControllers, HydrateStaticStateOptions<TSearchAction>, HydratedState<SSRCommerceEngine, TControllers>>;
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/app/commerce-ssr-engine/types/kind.d.ts

@@ -0,0 +1,6 @@
+export declare enum Kind {
+    Cart = "CART",
+    Context = "CONTEXT",
+    ParameterManager = "PARAMETER_MANAGER",
+    Recommendations = "RECOMMENDATIONS"
+}

package/force-app/main/default/staticresources/coveoheadless/definitions/app/ssr-engine/types/common.d.ts

@@ -3,6 +3,12 @@ import type { Controller } from '../../../controllers/controller/headless-contro
 import { CoreEngine, CoreEngineNext } from '../../engine.js';
 export type HasKey<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] extends never ? never : true : never : never;
 export type HasKeys<TObject> = TObject extends {} ? keyof TObject extends never ? false : true : boolean;
+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;
 export type ExtractRequiredOptions<TOptions> = {
     [TKey in keyof TOptions as Pick<TOptions, TKey> extends Required<Pick<TOptions, TKey>> ? TKey : never]: TOptions[TKey];
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/commerce.index.d.ts

@@ -102,7 +102,7 @@ export type { InstantProducts, InstantProductsState, InstantProductsOptions, Ins
 export { buildStandaloneSearchBox } from './controllers/commerce/standalone-search-box/headless-standalone-search-box.js';
 export type { StandaloneSearchBox, StandaloneSearchBoxState, } from './controllers/commerce/standalone-search-box/headless-standalone-search-box.js';
 export type { StandaloneSearchBoxProps, StandaloneSearchBoxOptions, } from './controllers/standalone-search-box/headless-standalone-search-box.ts';
-export type { UrlManagerProps, UrlManagerInitialState, UrlManagerState, UrlManager, } from './controllers/commerce/core/url-manager/headless-core-url-manager.js';
+export type { BaseUrlManagerProps, UrlManagerProps, UrlManagerInitialState, UrlManagerState, UrlManager, } from './controllers/commerce/core/url-manager/headless-core-url-manager.js';
 export type { Template } from './features/templates/templates-manager.ts';
 export type { ProductTemplate, ProductTemplateCondition, ProductTemplatesManager, } from './features/commerce/product-templates/product-templates-manager.js';
 export { buildProductTemplatesManager } from './features/commerce/product-templates/product-templates-manager.js';

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/context/cart/headless-cart.ssr.d.ts

@@ -1,11 +1,11 @@
-import { NonRecommendationControllerDefinitionWithProps } from '../../../../app/commerce-ssr-engine/types/common.js';
+import { UniversalControllerDefinitionWithProps } from '../../../../app/commerce-ssr-engine/types/common.js';
 import { Cart, CartInitialState } from './headless-cart.js';
 export type { CartState, CartItem, CartProps } from './headless-cart.js';
 export type { Cart, CartInitialState };
 export interface CartBuildProps {
     initialState: CartInitialState;
 }
-export interface CartDefinition extends NonRecommendationControllerDefinitionWithProps<Cart, CartBuildProps> {
+export interface CartDefinition extends UniversalControllerDefinitionWithProps<Cart, CartBuildProps> {
 }
 /**
  * Defines a `Cart` controller instance.

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/context/headless-context.ssr.d.ts

@@ -1,8 +1,8 @@
-import { NonRecommendationControllerDefinitionWithProps } from '../../../app/commerce-ssr-engine/types/common.js';
+import { UniversalControllerDefinitionWithProps } from '../../../app/commerce-ssr-engine/types/common.js';
 import { Context, ContextOptions, View, UserLocation } from './headless-context.js';
 export type { ContextState, Context, ContextProps } from './headless-context.js';
 export type { View, UserLocation, ContextOptions };
-export interface ContextDefinition extends NonRecommendationControllerDefinitionWithProps<Context, ContextOptions> {
+export interface ContextDefinition extends UniversalControllerDefinitionWithProps<Context, ContextOptions> {
 }
 /**
  * Defines a `Context` controller instance.

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/breadcrumb-manager/headless-core-breadcrumb-manager.ssr.d.ts

@@ -3,6 +3,7 @@ import { BreadcrumbManager, BreadcrumbManagerState } from './headless-core-bread
 export type { BreadcrumbManager, BreadcrumbManagerState };
 /**
  * Defines a `BreadcrumbManager` controller instance.
+ * @group Definers
  *
  * @returns The `BreadcrumbManager` controller definition.
  *

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/facets/generator/headless-commerce-facet-generator.ssr.d.ts

@@ -17,6 +17,9 @@ export type { FacetType };
 export type MappedFacetState = {
     [T in FacetType]: T extends 'numericalRange' ? NumericFacetState : T extends 'regular' ? RegularFacetState : T extends 'dateRange' ? DateFacetState : T extends 'hierarchical' ? CategoryFacetState : T extends 'location' ? LocationFacetState : never;
 };
+/**
+ * @group Definers
+ */
 export declare function defineFacetGenerator<TOptions extends ControllerDefinitionOption | undefined>(options?: TOptions): SubControllerDefinitionWithoutProps<FacetGenerator, TOptions>;
 /**
  * The `FacetGenerator` headless sub-controller creates commerce facet sub-controllers from the Commerce API search or

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/parameter-manager/headless-core-parameter-manager.d.ts

@@ -9,7 +9,14 @@ export interface ParameterManagerProps<T extends Parameters> {
     /**
      * The initial state that should be applied to the `ParameterManager` sub-controller.
      */
-    initialState: ParameterManagerInitialState<T>;
+    initialState?: ParameterManagerInitialState<T>;
+    /**
+     * Whether the controller's state should exclude the default parameters returned by the Commerce API, and only include
+     * the parameters that were set explicitly set through dispatched actions.
+     *
+     * Defaults to `false`.
+     */
+    excludeDefaultParameters?: boolean;
 }
 export interface CoreParameterManagerProps<T extends Parameters> extends ParameterManagerProps<T> {
     /**
@@ -28,12 +35,6 @@ export interface CoreParameterManagerProps<T extends Parameters> extends Paramet
      * The action to dispatch to fetch more results.
      */
     fetchProductsActionCreator: FetchProductsActionCreator;
-    /**
-     * Enriches the parameters with the active parameters.
-     * @param state
-     * @param activeParams
-     */
-    enrichParameters(state: CommerceEngine[typeof stateKey], activeParams: T): Required<T>;
 }
 export interface ParameterManagerInitialState<T> {
     /**

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/parameter-manager/headless-core-parameter-manager.ssr.d.ts

@@ -12,7 +12,9 @@ export type { ParameterManager, ParameterManagerProps, ParameterManagerState, Pa
  *
  * @internal
  */
-export declare function defineParameterManager<TOptions extends ControllerDefinitionOption | undefined>(options?: TOptions): SubControllerDefinitionWithProps<ParameterManager<Parameters | CommerceSearchParameters | MappedParameterTypes<TOptions>>, TOptions, ParameterManagerProps<Parameters | CommerceSearchParameters | MappedParameterTypes<TOptions>>>;
+export declare function defineParameterManager<TOptions extends ControllerDefinitionOption | undefined>(options?: TOptions): SubControllerDefinitionWithProps<ParameterManager<MappedParameterTypes<TOptions>>, TOptions, SSRParameterManagerProps<MappedParameterTypes<TOptions>>>;
+export interface SSRParameterManagerProps<T extends Parameters> extends Omit<ParameterManagerProps<T>, 'excludeDefaultParameters'> {
+}
 type MappedParameterTypes<TOptions extends ControllerDefinitionOption | undefined> = TOptions extends {
     listing: true;
     search: true;

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/sub-controller/headless-sub-controller.d.ts

@@ -68,7 +68,7 @@ export interface SearchAndListingSubControllers<P extends Parameters, S extends
      * @param props - Properties for the `ParameterManager` sub-controller.
      * @returns A `ParameterManager` sub-controller.
      */
-    parameterManager(props: ParameterManagerProps<P>): ParameterManager<P>;
+    parameterManager(props?: ParameterManagerProps<P>): ParameterManager<P>;
 }
 export interface SearchSubControllers extends SearchAndListingSubControllers<CommerceSearchParameters, SearchSummaryState> {
     /**
@@ -98,7 +98,6 @@ export interface SearchAndListingSubControllerProps<P extends Parameters, S exte
     parametersDefinition: SchemaDefinition<Required<P>>;
     activeParametersSelector: (state: CommerceEngine[typeof stateKey]) => P;
     restoreActionCreator: (parameters: P) => UnknownAction;
-    enrichParameters: (state: CommerceEngine[typeof stateKey], activeParams: P) => Required<P>;
     facetSearchType: FacetSearchType;
 }
 /**

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/url-manager/headless-core-url-manager.d.ts

@@ -2,9 +2,18 @@ import { CommerceEngine } from '../../../../app/commerce-engine/commerce-engine.
 import { stateKey } from '../../../../app/state-key.js';
 import { Parameters } from '../../../../features/commerce/parameters/parameters-actions.js';
 import { Serializer } from '../../../../features/commerce/parameters/parameters-serializer.js';
-import { UrlManager, UrlManagerInitialState, type UrlManagerProps, UrlManagerState } from '../../../url-manager/headless-url-manager.js';
+import { UrlManager, UrlManagerInitialState, type UrlManagerProps as BaseUrlManagerProps, UrlManagerState } from '../../../url-manager/headless-url-manager.js';
 import { ParameterManager, ParameterManagerProps } from '../parameter-manager/headless-core-parameter-manager.js';
-export type { UrlManagerProps, UrlManager, UrlManagerInitialState, UrlManagerState, };
+export type { UrlManager, UrlManagerInitialState, UrlManagerState, BaseUrlManagerProps, };
+export interface UrlManagerProps extends BaseUrlManagerProps {
+    /**
+     * Whether the controller's state should exclude the default parameters returned by the Commerce API, and only include
+     * the parameters that were set explicitly set through dispatched actions.
+     *
+     * Defaults to `false`.
+     */
+    excludeDefaultParameters?: boolean;
+}
 interface CoreUrlManagerProps<T extends Parameters> extends UrlManagerProps {
     requestIdSelector: (state: CommerceEngine[typeof stateKey]) => string;
     parameterManagerBuilder: (engine: CommerceEngine, props: ParameterManagerProps<T>) => ParameterManager<T>;

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/product-list/headless-product-list.ssr.d.ts

@@ -2,7 +2,7 @@ import { ControllerDefinitionOption, SubControllerDefinitionWithoutProps } from
 import { ProductListing } from '../product-listing/headless-product-listing.js';
 import { Search } from '../search/headless-search.js';
 export type { ProductListingState as ProductListState } from '../product-listing/headless-product-listing.js';
-export type ProductList = Pick<ProductListing | Search, 'state' | 'subscribe' | 'interactiveProduct'>;
+export type ProductList = Pick<ProductListing | Search, 'state' | 'subscribe' | 'interactiveProduct' | 'promoteChildToParent'>;
 /**
  * Defines a `ProductList` controller instance.
  * @group Definers