feat(headless SSR): fetchStaticState should only accept solutiontype-…

…specific controllers (#4769)

This is a complex one. It introduces type changes only to ensure that
props for solution type-specific controllers are only required in their
respective engine definitions.

### Key changes:

Recommendation props are now only required in
recommendationEngineDefinition.
The same logic is applied to other solution type-specific controllers.

Additionally, unit tests have been added to verify that type inference
and conditional prop types function correctly.

https://coveord.atlassian.net/browse/KIT-3787

---------

Co-authored-by: Frederic Beaudoin <[email protected]>

packages/headless-react/src/ssr-commerce/providers.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import {
+  HydrateStaticStateOptions,
   InferHydratedState,
   InferStaticState,
   NavigatorContext,
@@ -67,7 +68,7 @@ export function buildProviderWithDefinition(looseDefinition: LooseDefinition) {
             ...controllers,
             ...hydrateControllers,
           },
-        })
+        } as HydrateStaticStateOptions<{type: string}>)
         .then(({engine, controllers}) => {
           setHydratedState({engine, controllers});
         });

packages/headless/src/app/commerce-engine/commerce-engine.ssr.test.ts

@@ -0,0 +1,83 @@
+import {defineCart} from '../../controllers/commerce/context/cart/headless-cart.ssr.js';
+import {defineParameterManager} from '../../controllers/commerce/core/parameter-manager/headless-core-parameter-manager.ssr.js';
+import {defineSummary} from '../../controllers/commerce/core/summary/headless-core-summary.ssr.js';
+import {defineRecommendations} from '../../controllers/commerce/recommendations/headless-recommendations.ssr.js';
+import {defineDidYouMean} from '../../controllers/commerce/search/did-you-mean/headless-did-you-mean.ssr.js';
+import {getSampleCommerceEngineConfiguration} from './commerce-engine-configuration.js';
+import {defineCommerceEngine} from './commerce-engine.ssr.js';
+
+describe('Commerce Engine SSR', () => {
+  const {
+    listingEngineDefinition,
+    recommendationEngineDefinition,
+    searchEngineDefinition,
+    standaloneEngineDefinition,
+  } = defineCommerceEngine({
+    configuration: {
+      ...getSampleCommerceEngineConfiguration(),
+    },
+    controllers: {
+      summary: defineSummary(),
+      didYouMean: defineDidYouMean(),
+      paramManager: defineParameterManager({listing: false}),
+      cart: defineCart(),
+      popularViewed: defineRecommendations({
+        options: {
+          slotId: 'd73afbd2-8521-4ee6-a9b8-31f064721e73',
+        },
+      }),
+    },
+  });
+
+  it('should only require cart options for standaloneEngineDefinition', () => {
+    expect(() =>
+      standaloneEngineDefinition.fetchStaticState({
+        controllers: {
+          cart: {initialState: {items: []}},
+        },
+      })
+    ).not.toThrow();
+  });
+
+  it('should only require cart options for listingEngineDefinition', () => {
+    expect(() =>
+      listingEngineDefinition.fetchStaticState({
+        controllers: {
+          cart: {initialState: {items: []}},
+        },
+      })
+    ).not.toThrow();
+  });
+
+  it('should only require cart and paramManager options for searchEngineDefinition', () => {
+    expect(() =>
+      searchEngineDefinition.fetchStaticState({
+        controllers: {
+          cart: {initialState: {items: []}},
+          paramManager: {initialState: {parameters: {}}},
+        },
+      })
+    ).not.toThrow();
+  });
+
+  it('should only require cart options for recommendationEngineDefinition', () => {
+    expect(() =>
+      recommendationEngineDefinition.fetchStaticState({
+        controllers: {
+          cart: {initialState: {items: []}},
+        },
+      })
+    ).not.toThrow();
+  });
+
+  it('should allow optional recommendation controller options for recommendationEngineDefinition', () => {
+    expect(() =>
+      recommendationEngineDefinition.fetchStaticState({
+        controllers: {
+          cart: {initialState: {items: []}},
+          popularViewed: {enabled: true, productId: 'some-product-id'},
+        },
+      })
+    ).not.toThrow();
+  });
+});

packages/headless/src/app/commerce-ssr-engine/types/build.ts

@@ -1,3 +1,4 @@
+import {Controller} from '../../../controllers/controller/headless-controller.js';
 import type {
   ControllersMap,
   ControllersPropsMap,
@@ -6,7 +7,11 @@ import type {
   OptionsTuple,
 } from '../../ssr-engine/types/common.js';
 import {SSRCommerceEngine} from '../factories/build-factory.js';
-import {EngineDefinitionControllersPropsOption} from './common.js';
+import {
+  ControllerDefinitionsMap,
+  EngineDefinitionControllersPropsOption,
+  SolutionType,
+} from './common.js';
 
 export interface BuildOptions<TEngineOptions> {
   extend?: OptionsExtender<TEngineOptions>;
@@ -16,14 +21,20 @@ 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.
    */
   (
     ...params: OptionsTuple<
       BuildOptions<TEngineOptions> &
-        EngineDefinitionControllersPropsOption<TControllersProps>
+        EngineDefinitionControllersPropsOption<
+          TControllersDefinitionsMap,
+          TControllersProps,
+          TSolutionType
+        >
     >
   ): Promise<EngineDefinitionBuildResult<SSRCommerceEngine, TControllersMap>>;
 };