@coveo/quantic 3.28.1 → 3.28.2-pre.04d5730f85

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

@@ -0,0 +1,12 @@
+import { type ProductListing, type ProductListingState } from '../../../../controllers/commerce/product-listing/headless-product-listing.js';
+import { type Search } from '../../../../controllers/commerce/search/headless-search.js';
+import type { ControllerDefinitionOption, SubControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { Search, ProductListing, ProductListingState as ProductListState };
+export type ProductList = Pick<ProductListing | Search, 'state' | 'subscribe' | 'interactiveProduct' | 'promoteChildToParent'>;
+/**
+ * Defines a `ProductList` controller instance.
+ * @group Definers
+ *
+ * @returns The `ProductList` controller definition.
+ */
+export declare function defineProductList<TOptions extends ControllerDefinitionOption | undefined>(options?: TOptions): SubControllerDefinitionWithoutProps<ProductList, TOptions>;

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

@@ -0,0 +1,20 @@
+import { type ProductView as BaseProductView } from '../../../../controllers/commerce/product-view/headless-product-view.js';
+import { type Controller } from '../../../../controllers/controller/headless-controller.js';
+import type { NonRecommendationControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+interface ProductViewDefinition extends NonRecommendationControllerDefinitionWithoutProps<ProductView> {
+}
+/**
+ * Defines a `ProductView` controller instance.
+ *
+ * This controller is stateless and does not implement a `subscribe` method,
+ * making it simpler but different from other controllers in the system.
+ * Its sole purpose is to log an `ec.productView` event.
+ *
+ * @returns The `ProductView` controller definition.
+ *
+ * @group Definers
+ */
+export declare function defineProductView(): ProductViewDefinition;
+export interface ProductView extends BaseProductView, Controller {
+}
+export {};

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

@@ -0,0 +1,13 @@
+import { type RecentQueriesList, type RecentQueriesListInitialState, type RecentQueriesListOptions, type RecentQueriesListProps, type RecentQueriesState } from '../../../../controllers/commerce/recent-queries-list/headless-recent-queries-list.js';
+import type { NonRecommendationControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { RecentQueriesListInitialState, RecentQueriesListOptions, RecentQueriesState, RecentQueriesList, RecentQueriesListProps, };
+export interface RecentQueriesListDefinition extends NonRecommendationControllerDefinitionWithoutProps<RecentQueriesList> {
+}
+/**
+ * Defines the `RecentQueriesList` controller for the purpose of server-side rendering.
+ * @group Definers
+ *
+ * @param props - The configuration `RecentQueriesList` properties.
+ * @returns The `RecentQueriesList` controller definition.
+ */
+export declare function defineRecentQueriesList(props?: RecentQueriesListProps): RecentQueriesListDefinition;

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

@@ -0,0 +1,17 @@
+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]: {} & RecommendationsProps['options'];
+};
+export interface RecommendationsDefinition extends RecommendationOnlyControllerDefinitionWithProps<Recommendations, Partial<RecommendationsOptions>> {
+}
+/**
+ * Defines a `Recommendations` controller instance.
+ * @group Definers
+ *
+ * @param props - The configurable `Recommendations` properties.
+ * @returns The `Recommendations` controller definition.
+ * */
+export declare function defineRecommendations(props: RecommendationsProps): RecommendationsDefinition & RecommendationsDefinitionMeta;

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

@@ -0,0 +1,12 @@
+import { type CoreSearchBox, type SearchBox, type SearchBoxOptions, type SearchBoxProps, type SearchBoxState, type Suggestion } from '../../../../controllers/commerce/search-box/headless-search-box.js';
+import type { SearchOnlyControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { CoreSearchBox, SearchBox, SearchBoxProps, SearchBoxState, SearchBoxOptions, Suggestion, };
+export interface SearchBoxDefinition extends SearchOnlyControllerDefinitionWithoutProps<SearchBox> {
+}
+/**
+ * Defines a `SearchBox` controller instance.
+ * @group Definers
+ *
+ * @returns The `SearchBox` controller definition.
+ */
+export declare function defineSearchBox(props?: SearchBoxProps): SearchBoxDefinition;

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

@@ -0,0 +1,11 @@
+import type { Sort, SortProps, SortState } from '../../../../controllers/commerce/core/sort/headless-core-commerce-sort.js';
+import type { ControllerDefinitionOption, SubControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { Sort, SortProps, SortState };
+/**
+ * Defines a `Sort` controller instance.
+ * @group Definers
+ *
+ * @param props - The configurable `Sort` properties.
+ * @returns The `Sort` controller definition.
+ */
+export declare function defineSort<TOptions extends ControllerDefinitionOption | undefined>(props?: SortProps & TOptions): SubControllerDefinitionWithoutProps<Sort, TOptions>;

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

@@ -0,0 +1,14 @@
+import { type StandaloneSearchBox, type StandaloneSearchBoxState } from '../../../../controllers/commerce/standalone-search-box/headless-standalone-search-box.js';
+import type { StandaloneSearchBoxProps } from '../../../../controllers/standalone-search-box/headless-standalone-search-box.js';
+import type { ListingAndStandaloneControllerWithoutProps } from '../../types/controller-definitions.js';
+export type { StandaloneSearchBoxState, StandaloneSearchBox, StandaloneSearchBoxProps, };
+export interface StandaloneSearchBoxDefinition extends ListingAndStandaloneControllerWithoutProps<StandaloneSearchBox> {
+}
+/**
+ * Defines the `StandaloneSearchBox` controller for the purpose of server-side rendering.
+ * @group Definers
+ *
+ * @param props - The configurable `StandaloneSearchBox` properties.
+ * @returns The `StandaloneSearchBox` controller definition.
+ */
+export declare function defineStandaloneSearchBox(props: StandaloneSearchBoxProps): StandaloneSearchBoxDefinition;

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

@@ -0,0 +1,13 @@
+import type { Summary, SummaryState } from '../../../../controllers/commerce/core/summary/headless-core-summary.js';
+import type { ProductListingSummaryState } from '../../../../controllers/commerce/product-listing/summary/headless-product-listing-summary.js';
+import type { RecommendationsSummaryState } from '../../../../controllers/commerce/recommendations/summary/headless-recommendations-summary.js';
+import type { SearchSummaryState } from '../../../../controllers/commerce/search/summary/headless-search-summary.js';
+import type { ControllerDefinitionOption, SubControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { Summary, ProductListingSummaryState, RecommendationsSummaryState, SearchSummaryState, SummaryState, };
+/**
+ * Defines a `Summary` controller instance.
+ * @group Definers
+ *
+ * @returns The `Summary` controller definition.
+ */
+export declare function defineSummary<TOptions extends ControllerDefinitionOption | undefined>(options?: TOptions): SubControllerDefinitionWithoutProps<Summary<ProductListingSummaryState | SearchSummaryState | RecommendationsSummaryState>, TOptions>;

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

@@ -0,0 +1,12 @@
+import type { NotifyTrigger, NotifyTriggerState } from '../../../../controllers/core/triggers/headless-core-notify-trigger.js';
+import type { SearchAndListingControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { NotifyTrigger, NotifyTriggerState };
+export interface NotifyTriggerDefinition extends SearchAndListingControllerDefinitionWithoutProps<NotifyTrigger> {
+}
+/**
+ * Defines the `NotifyTrigger` controller for the purpose of server-side rendering.
+ * @group Definers
+ *
+ * @returns The `NotifyTrigger` controller definition.
+ */
+export declare function defineNotifyTrigger(): NotifyTriggerDefinition;

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

@@ -0,0 +1,13 @@
+import type { QueryTrigger } from '../../../../controllers/core/triggers/headless-core-query-trigger.js';
+import type { SearchOnlyControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { QueryTriggerState } from '../../../../controllers/core/triggers/headless-core-query-trigger.js';
+export type { QueryTrigger };
+export interface QueryTriggerDefinition extends SearchOnlyControllerDefinitionWithoutProps<QueryTrigger> {
+}
+/**
+ * Defines the `QueryTrigger` controller for the purpose of server-side rendering.
+ * @group Definers
+ *
+ * @returns The `QueryTrigger` controller definition.
+ */
+export declare function defineQueryTrigger(): QueryTriggerDefinition;

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

@@ -0,0 +1,12 @@
+import type { RedirectionTrigger, RedirectionTriggerState } from '../../../../controllers/core/triggers/headless-core-redirection-trigger.js';
+import type { SearchOnlyControllerDefinitionWithoutProps } from '../../types/controller-definitions.js';
+export type { RedirectionTrigger, RedirectionTriggerState };
+export interface RedirectionTriggerDefinition extends SearchOnlyControllerDefinitionWithoutProps<RedirectionTrigger> {
+}
+/**
+ * Defines the `RedirectionTrigger` controller for the purpose of server-side rendering.
+ * @group Definers
+ *
+ * @returns The `RedirectionTrigger` controller definition.
+ */
+export declare function defineRedirectionTrigger(): RedirectionTriggerDefinition;

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

@@ -0,0 +1,25 @@
+/**
+ * Utility functions to be used for Commerce Server Side Rendering.
+ */
+import type { CommerceEngineOptions } from '../../../app/commerce-engine/commerce-engine.js';
+import type { Controller } from '../../../controllers/controller/headless-controller.js';
+import { type CommerceEngineDefinitionOptions } from '../factories/build-factory.js';
+import { SolutionType } from '../types/controller-constants.js';
+import type { ControllerDefinitionsMap } from '../types/controller-definitions.js';
+import type { EngineDefinition } from '../types/engine.js';
+export interface CommerceEngineDefinition<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> extends EngineDefinition<TControllers, CommerceEngineOptions, TSolutionType> {
+}
+/**
+ * Initializes a Commerce engine definition in SSR with given controllers definitions and commerce engine config.
+ * @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>;
+    searchEngineDefinition: CommerceEngineDefinition<TControllerDefinitions, SolutionType.search>;
+    standaloneEngineDefinition: CommerceEngineDefinition<TControllerDefinitions, SolutionType.standalone>;
+    recommendationEngineDefinition: CommerceEngineDefinition<TControllerDefinitions, SolutionType.recommendation>;
+};

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

@@ -0,0 +1,22 @@
+import type { Action } from '@reduxjs/toolkit';
+import { type CommerceEngine, type CommerceEngineOptions } from '../../../app/commerce-engine/commerce-engine.js';
+import type { Controller } from '../../../controllers/controller/headless-controller.js';
+import { SolutionType } from '../types/controller-constants.js';
+import type { ControllerDefinitionsMap } from '../types/controller-definitions.js';
+import type { BuildParameters, CommerceControllerDefinitionsMap, EngineDefinitionOptions } from '../types/engine.js';
+/**
+ * The SSR commerce engine.
+ *
+ * @group Engine
+ */
+export interface SSRCommerceEngine extends CommerceEngine {
+    /**
+     * Waits for the request to be completed and returns a promise that resolves to an `Action`.
+     */
+    waitForRequestCompletedAction(): Promise<Action>[];
+}
+export type CommerceEngineDefinitionOptions<TControllers extends ControllerDefinitionsMap<Controller> = ControllerDefinitionsMap<Controller>> = EngineDefinitionOptions<CommerceEngineOptions, TControllers>;
+export declare const buildFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => <T extends SolutionType>(solutionType: T) => (...[buildOptions]: BuildParameters<TControllerDefinitions>) => Promise<{
+    engine: SSRCommerceEngine;
+    controllers: import("../types/controller-inference.js").InferControllersMapFromDefinition<TControllerDefinitions, T>;
+}>;

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

@@ -0,0 +1,4 @@
+import type { SolutionType } from '../types/controller-constants.js';
+import type { CommerceControllerDefinitionsMap, HydrateStaticStateFunction } from '../types/engine.js';
+import { type CommerceEngineDefinitionOptions } from './build-factory.js';
+export declare const hydratedStaticStateFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => (solutionType: SolutionType) => HydrateStaticStateFunction<TControllerDefinitions>;

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/commerce/factories/recommendation-hydrated-state-factory.d.ts

@@ -0,0 +1,3 @@
+import type { CommerceControllerDefinitionsMap, HydrateStaticStateFunction } from '../types/engine.js';
+import { type CommerceEngineDefinitionOptions } from './build-factory.js';
+export declare function hydratedRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): HydrateStaticStateFunction<TControllerDefinitions>;

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/commerce/factories/recommendation-static-state-factory.d.ts

@@ -0,0 +1,3 @@
+import type { CommerceControllerDefinitionsMap, FetchStaticStateFunction } from '../types/engine.js';
+import { type CommerceEngineDefinitionOptions } from './build-factory.js';
+export declare function fetchRecommendationStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): FetchStaticStateFunction<TControllerDefinitions>;

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

@@ -0,0 +1,4 @@
+import { SolutionType } from '../types/controller-constants.js';
+import type { CommerceControllerDefinitionsMap, FetchStaticStateFunction } from '../types/engine.js';
+import { type CommerceEngineDefinitionOptions } from './build-factory.js';
+export declare const fetchStaticStateFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => (solutionType: SolutionType) => FetchStaticStateFunction<TControllerDefinitions>;

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

@@ -0,0 +1,10 @@
+import type { Controller } from '../../../controllers/controller/headless-controller.js';
+import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
+import type { OptionsExtender, OptionsTuple } from '../../common/types/utilities.js';
+import type { SSRCommerceEngine } from '../factories/build-factory.js';
+import type { SolutionType } from './controller-constants.js';
+import type { ControllerDefinitionsMap, EngineDefinitionBuildResult, EngineDefinitionControllersPropsOption } from './controller-definitions.js';
+export interface BuildOptions<TEngineOptions> {
+    extend?: OptionsExtender<TEngineOptions>;
+}
+export type Build<TEngineOptions, TControllersMap extends ControllersMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = (...params: OptionsTuple<BuildOptions<TEngineOptions> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<EngineDefinitionBuildResult<SSRCommerceEngine, TControllersMap>>;

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

@@ -0,0 +1,7 @@
+export declare enum SolutionType {
+    search = "search",
+    listing = "listing",
+    standalone = "standalone",
+    recommendation = "recommendation"
+}
+export declare const recommendationInternalOptionKey: unique symbol;

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

@@ -0,0 +1,220 @@
+import type { Controller } from '../../../controllers/controller/headless-controller.js';
+import type { InvalidControllerDefinition } from '../../common/errors.js';
+import type { ControllersPropsMap } from '../../common/types/controllers.js';
+import type { EngineDefinitionBuildResult } from '../../common/types/engine.js';
+import type { HydratedState } from '../../common/types/hydrate-static-state.js';
+import type { InferControllerStaticStateFromController, InferControllerStaticStateMapFromControllers } from '../../common/types/inference.js';
+import type { HasKey, HasOptionalKeys, HasRequiredKeys, OptionsTuple } from '../../common/types/utilities.js';
+import type { SSRCommerceEngine } from '../factories/build-factory.js';
+import { type recommendationInternalOptionKey, SolutionType } from './controller-constants.js';
+import type { ListingAndStandaloneController, ListingOnlyController, NonRecommendationController, RecommendationOnlyController, SearchAndListingController, SearchOnlyController, UniversalController } from './controller-scopes.js';
+import type { Kind } from './kind.js';
+export type { EngineDefinitionBuildResult, 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.
+     *
+     * @param engine - The search engine.
+     * @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.
+     */
+    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.
+     *
+     * @param engine - The search engine.
+     * @param props - The controller properties.
+     * @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 & ControllerWithKind;
+}
+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>;
+}
+/**
+ * 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()
+ * ```
+ */
+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 : 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.
+     * @defaultValue true
+     */
+    listing?: boolean;
+    /**
+     * Whether the controller will be used in a search page context.
+     * @defaultValue true
+     */
+    search?: boolean;
+}
+export type SearchOnlyControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & SearchOnlyController;
+type SearchOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & SearchOnlyController;
+export type ListingAndStandaloneControllerWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & ListingAndStandaloneController;
+type ListingOnlyControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & ListingOnlyController;
+type ListingOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & ListingOnlyController;
+export type RecommendationOnlyControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & RecommendationOnlyController;
+export type NonRecommendationControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & NonRecommendationController;
+export type UniversalControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & UniversalController;
+export type SearchAndListingControllerDefinitionWithoutProps<TController extends Controller> = ControllerDefinitionWithoutProps<TController> & SearchAndListingController;
+type SearchAndListingControllerDefinitionWithProps<TController extends Controller, TProps> = ControllerDefinitionWithProps<TController, TProps> & SearchAndListingController;
+export type SubControllerDefinitionWithoutProps<TController extends Controller, TDefinition extends ControllerDefinitionOption | undefined> = TDefinition extends {
+    listing?: true;
+    search?: true;
+} | undefined ? SearchAndListingControllerDefinitionWithoutProps<TController> : TDefinition extends {
+    listing?: true;
+    search?: false;
+} ? ListingOnlyControllerDefinitionWithoutProps<TController> : TDefinition extends {
+    listing?: false;
+    search?: true;
+} ? SearchOnlyControllerDefinitionWithoutProps<TController> : TDefinition extends {
+    listing: false;
+    search: false;
+} ? InvalidControllerDefinition : never;
+export type SubControllerDefinitionWithProps<TController extends Controller, TDefinition extends ControllerDefinitionOption | undefined, TProps> = TDefinition extends {
+    listing?: true;
+    search?: true;
+} | undefined ? SearchAndListingControllerDefinitionWithProps<TController, TProps> : TDefinition extends {
+    listing?: true;
+    search?: false;
+} ? ListingOnlyControllerDefinitionWithProps<TController, TProps> : TDefinition extends {
+    listing?: false;
+    search?: true;
+} ? SearchOnlyControllerDefinitionWithProps<TController, TProps> : TDefinition extends {
+    listing: false;
+    search: false;
+} ? InvalidControllerDefinition : never;

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

@@ -0,0 +1,24 @@
+import type { Controller } from '../../../controllers/controller/headless-controller.js';
+import type { HasKey, HasKeys } from '../../common/types/utilities.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']>>;
+export type InferBuildResult<T extends {
+    build(...args: unknown[]): Promise<unknown>;
+}> = Awaited<ReturnType<T['build']>>;
+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]>;
+};
+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]>>;
+};

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

@@ -0,0 +1,71 @@
+import { SolutionType } from './controller-constants.js';
+export interface NonRecommendationController {
+    /**
+     * @internal
+     */
+    [SolutionType.search]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.standalone]: true;
+}
+export interface UniversalController {
+    /**
+     * @internal
+     */
+    [SolutionType.search]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.standalone]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.recommendation]: true;
+}
+export interface SearchOnlyController {
+    /**
+     * @internal
+     */
+    [SolutionType.search]: true;
+}
+export interface ListingOnlyController {
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+}
+export interface RecommendationOnlyController {
+    /**
+     * @internal
+     */
+    [SolutionType.recommendation]: true;
+}
+export interface SearchAndListingController {
+    /**
+     * @internal
+     */
+    [SolutionType.search]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+}
+export interface ListingAndStandaloneController {
+    /**
+     * @internal
+     */
+    [SolutionType.listing]: true;
+    /**
+     * @internal
+     */
+    [SolutionType.standalone]: true;
+}