@coveo/headless 3.29.1 → 3.29.2-pre.1386439450

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

@@ -1,4 +1,5 @@
 import type { 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 hydratedStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): (solutionType: SolutionType) => HydrateStaticStateFunction<TControllerDefinitions>;
+export declare function hydratedStaticStateFactory<TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: CommerceEngineDefinitionOptions<TControllerDefinitions>): (solutionType: SolutionType) => HydrateStaticStateFunction<TControllerDefinitions>;

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

@@ -1,10 +1,9 @@
-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 { OptionsTuple } from '../../common/types/utilities.js';
 import type { CartInitialState } from '../controllers/cart/headless-cart.ssr.js';
-import type { UserLocation } from '../controllers/context/headless-context.ssr.js';
+import type { ContextOptions } 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 } from './controller-definitions.js';
@@ -22,13 +21,7 @@ export interface ListingBuildConfig extends CommonBuildConfig {
 export interface StandaloneBuildConfig extends CommonBuildConfig {
 }
 export interface CommonBuildConfig {
-    context: {
-        url: string;
-        language: string;
-        country: string;
-        currency: CurrencyCodeISO4217;
-        location?: UserLocation;
-    };
+    context: ContextOptions;
     searchParams?: ParameterManagerState<Parameters>['parameters'];
     cart?: CartInitialState;
 }

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<TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<EngineStaticState<TSearchAction, TControllersStaticState & FilteredBakedInControllers<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>> & BuildConfig<TSolutionType>>;

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

@@ -3,6 +3,7 @@ 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> {
@@ -13,4 +14,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> & 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> & BuildConfig<TSolutionType> & EngineDefinitionControllersPropsOption<TControllersDefinitionsMap, TControllersProps, TSolutionType>>) => Promise<HydratedState<SSRCommerceEngine, TControllers>>;

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

@@ -1,8 +1,38 @@
+/**
+ * Controller Wiring Utilities
+ *
+ * Transforms simple user configuration into complex internal controller structures.
+ */
+import { Schema } from '@coveo/bueno';
 import type { ControllersPropsMap } from '../../common/types/controllers.js';
 import type { BuildConfig } from '../types/build.js';
-import type { SolutionType } from '../types/controller-constants.js';
+import { SolutionType } from '../types/controller-constants.js';
 import type { InferControllerPropsMapFromDefinitions } from '../types/controller-inference.js';
 import type { CommerceControllerDefinitionsMap } from '../types/engine.js';
-export declare function wireControllerParams<TControllerDefinitions extends CommerceControllerDefinitionsMap>(_solutionType: SolutionType, _controllerDefinitions: TControllerDefinitions, _paramsObject: BuildConfig<SolutionType> & {
+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: Schema<{
+    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<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;

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

@@ -2,9 +2,7 @@ import { buildFactory, } from './build-factory.js';
 export function hydratedStaticStateFactory(controllerDefinitions, options) {
     return (solutionType) => async (...params) => {
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(solutionType);
-        const { engine, controllers } = await solutionTypeBuild(
-        // @ts-expect-error: TODO: KIT-4742: the wiring will fix also the type inconsistencies
-        ...params);
+        const { engine, controllers } = await solutionTypeBuild(...params);
         params[0].searchActions.forEach((action) => {
             engine.dispatch(action);
         });

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

@@ -3,9 +3,7 @@ import { buildFactory, } from './build-factory.js';
 export function hydratedRecommendationStaticStateFactory(controllerDefinitions, options) {
     return async (...params) => {
         const solutionTypeBuild = await buildFactory(controllerDefinitions, options)(SolutionType.recommendation);
-        const { engine, controllers } = (await solutionTypeBuild(
-        // @ts-expect-error: TODO: KIT-4742: the wiring will fix also the type inconsistencies
-        ...params));
+        const { engine, controllers } = (await solutionTypeBuild(...params));
         params[0].searchActions.forEach((action) => {
             engine.dispatch(action);
         });

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

@@ -4,6 +4,7 @@ import { SolutionType } from '../types/controller-constants.js';
 import { filterRecommendationControllers } from '../utils/recommendation-filter.js';
 import { buildFactory, } from './build-factory.js';
 export function fetchRecommendationStaticStateFactory(controllerDefinitions, options) {
+    // TODO: KIT-4619: no longer the right way to get the allowed recommendation keys
     const getAllowedRecommendationKeys = (props) => {
         if (props && 'controllers' in props) {
             const enabledRecommendationControllers = filterObject(props.controllers, (value) => Boolean(value.enabled));
@@ -18,9 +19,13 @@ export function fetchRecommendationStaticStateFactory(controllerDefinitions, opt
         const { engine, controllers } = (await solutionTypeBuild(...params));
         filterRecommendationControllers(controllers, controllerDefinitions ?? {}).refresh(allowedRecommendationKeys);
         const searchActions = await Promise.all(engine.waitForRequestCompletedAction());
-        return createStaticState({
+        const staticState = createStaticState({
             searchActions,
             controllers,
         });
+        return {
+            ...params[0], // TODO: KIT-4754: remove index access after no longer relying on OptionTuple type
+            ...staticState,
+        };
     };
 }

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

@@ -27,6 +27,9 @@ export function fetchStaticStateFactory(controllerDefinitions, options) {
             searchActions,
             controllers,
         });
-        return staticState;
+        return {
+            ...params[0], // TODO: KIT-4754: remove index access after no longer relying on OptionTuple type
+            ...staticState,
+        };
     };
 }

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

@@ -1,4 +1,145 @@
-export function wireControllerParams(_solutionType, _controllerDefinitions, _paramsObject) {
-    // TODO: KIT-4742: Implement
-    return {};
+/**
+ * Controller Wiring Utilities
+ *
+ * Transforms simple user configuration into complex internal controller structures.
+ */
+import { RecordValue, Schema } from '@coveo/bueno';
+import { contextDefinition } from '../../../features/commerce/context/context-validation.js';
+import { parametersDefinition } from '../../../features/commerce/parameters/parameters-schema.js';
+import { requiredEmptyAllowedString } from '../../../utils/validate-payload.js';
+import { SolutionType } from '../types/controller-constants.js';
+const requiredDefinition = {
+    context: new RecordValue({
+        options: { required: true },
+        values: contextDefinition,
+    }),
+};
+const listingDefinition = {
+    ...requiredDefinition,
+    searchParams: new RecordValue({
+        values: parametersDefinition,
+    }),
+};
+const standaloneDefinition = {
+    ...requiredDefinition,
+};
+const searchDefinition = {
+    ...requiredDefinition,
+    searchParams: new RecordValue({
+        options: { required: true },
+        values: { query: requiredEmptyAllowedString, ...parametersDefinition },
+    }),
+};
+const recommendationsDefinition = {
+    ...requiredDefinition,
+    // recommendation:  // TODO: KIT-4619: support array of recommendations
+};
+export const listingDefinitionSchema = new Schema(listingDefinition);
+export const searchDefinitionSchema = new Schema(searchDefinition);
+export const standaloneDefinitionSchema = new Schema(standaloneDefinition);
+export const recommendationsDefinitionSchema = new Schema(recommendationsDefinition);
+/**
+ * Validates the build configuration based on the solution type.
+ */
+function validateBuildConfig(solutionType, buildConfig) {
+    const validationMap = {
+        [SolutionType.listing]: listingDefinitionSchema,
+        [SolutionType.search]: searchDefinitionSchema,
+        [SolutionType.standalone]: standaloneDefinitionSchema,
+        [SolutionType.recommendation]: recommendationsDefinitionSchema,
+    };
+    const schema = validationMap[solutionType];
+    schema.validate(buildConfig);
+}
+/**
+ * Controller wiring class that handles the complete wiring process.
+ * Transforms simple user configuration into complex internal controller structures.
+ */
+class ControllerWirer {
+    buildConfig;
+    controllerDefinitions;
+    controllerProps;
+    constructor(buildConfig, controllerDefinitions, controllerProps) {
+        this.buildConfig = buildConfig;
+        this.controllerDefinitions = controllerDefinitions;
+        this.controllerProps = controllerProps;
+    }
+    wireParameterManager() {
+        if (!this.controllerDefinitions?.parameterManager)
+            return;
+        const { searchParams } = this.buildConfig;
+        const { query, ...rest } = searchParams || {};
+        const parameters = {
+            ...(query && { q: query }),
+            ...(rest && typeof rest === 'object' ? rest : {}),
+        };
+        this.controllerProps.parameterManager = {
+            initialState: { parameters },
+        };
+    }
+    wireContext() {
+        if (!this.controllerDefinitions?.context)
+            return;
+        const { context } = this.buildConfig;
+        this.controllerProps.context = {
+            initialState: {
+                ...context,
+            },
+        };
+    }
+    wireCart() {
+        if (!this.controllerDefinitions?.cart || !this.buildConfig.cart)
+            return;
+        this.controllerProps.cart = {
+            initialState: this.buildConfig.cart,
+        };
+    }
+    wireRecommendations() {
+        // TODO: KIT-4619: wire recommendations
+    }
+    /**
+     * Wires all controllers based on solution type and controller definitions.
+     * Handles the complete wiring process in a sequential manner.
+     */
+    wire(solutionType) {
+        // Wire common controllers that apply to all solution types
+        this.wireCart();
+        this.wireContext();
+        // Wire solution-specific controllers
+        switch (solutionType) {
+            case SolutionType.search:
+            case SolutionType.listing: {
+                this.wireParameterManager();
+                break;
+            }
+            case SolutionType.recommendation: {
+                this.wireRecommendations();
+                break;
+            }
+            case SolutionType.standalone:
+                // No additional wiring needed for standalone
+                break;
+            default: {
+                // Exhaustive check - TypeScript will error if we miss a case
+                const _exhaustiveCheck = solutionType;
+                throw new Error(`Unsupported solution type: ${_exhaustiveCheck}`);
+            }
+        }
+    }
+}
+/**
+ * Converts simple user configuration (URL, language, currency, query) into the
+ * nested structure required by the internal {@link Build} method. Automatically generates
+ * appropriate controllers (context, cart, parameterManager) transparently.
+ *
+ * @param solutionType - The type of solution (search, listing, recommendation, standalone)
+ * @param controllerDefinitions - Map of controller definitions to be initialized
+ * @param buildConfig - Simple configuration object with simplified controller properties
+ * @returns Formatted and validated controller properties map defined for the controller in the definition
+ */
+export function wireControllerParams(solutionType, controllerDefinitions, buildConfig) {
+    validateBuildConfig(solutionType, buildConfig);
+    const controllerProps = buildConfig.controllers ?? {};
+    new ControllerWirer(buildConfig, controllerDefinitions, controllerProps).wire(solutionType);
+    return controllerProps;
 }

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

@@ -1,4 +1,10 @@
-export function extendEngineConfiguration(_configuration, _commonBuildOptions) {
-    // TODO: KIT-4742: Implement: wire engine configuration with validation
-    return {};
+export function extendEngineConfiguration(configuration, commonBuildOptions) {
+    const { cart, context } = commonBuildOptions;
+    return {
+        ...configuration,
+        context: {
+            ...context,
+        },
+        cart,
+    };
 }

package/dist/esm/utils/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "3.29.1" || 'Test version';
+export const VERSION = "3.29.2-pre.1386439450" || 'Test version';
 export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];