feat(headless): refresh commerce recommendations server-side

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

@@ -7,7 +7,10 @@ import {buildProductListing} from '../../controllers/commerce/product-listing/he
 import {buildSearch} from '../../controllers/commerce/search/headless-search.js';
 import type {Controller} from '../../controllers/controller/headless-controller.js';
 import {createWaitForActionMiddleware} from '../../utils/utils.js';
-import {buildControllerDefinitions} from '../commerce-ssr-engine/common.js';
+import {
+  buildControllerDefinitions,
+  buildRecommendationFilter,
+} from '../commerce-ssr-engine/common.js';
 import {
   ControllerDefinitionsMap,
   InferControllerStaticStateMapFromDefinitionsWithSolutionType,
@@ -37,7 +40,7 @@ export interface SSRCommerceEngine extends CommerceEngine {
   /**
    * Waits for the search to be completed and returns a promise that resolves to a `SearchCompletedAction`.
    */
-  waitForRequestCompletedAction(): Promise<Action>;
+  waitForRequestCompletedAction(): Promise<Action>[];
 }
 
 export type CommerceEngineDefinitionOptions<
@@ -56,13 +59,20 @@ function isSearchCompletedAction(action: unknown): action is Action {
   );
 }
 
+function isRecommendationCompletedAction(action: unknown): action is Action {
+  return /^commerce\/recommendations\/fetch\/(fulfilled|rejected)$/.test(
+    (action as UnknownAction).type
+  );
+}
+
 function noSearchActionRequired(_action: unknown): _action is Action {
   return true;
 }
 
 function buildSSRCommerceEngine(
   solutionType: SolutionType,
-  options: CommerceEngineOptions
+  options: CommerceEngineOptions,
+  recommendationCount: number
 ): SSRCommerceEngine {
   let actionCompletionMiddleware: ReturnType<
     typeof createWaitForActionMiddleware
@@ -85,11 +95,17 @@ function buildSSRCommerceEngine(
       );
   }
 
+  const recommendationActionMiddlewares = Array.from(
+    {length: recommendationCount},
+    () => createWaitForActionMiddleware(isRecommendationCompletedAction)
+  );
+
   const commerceEngine = buildCommerceEngine({
     ...options,
     middlewares: [
       ...(options.middlewares ?? []),
       actionCompletionMiddleware.middleware,
+      ...recommendationActionMiddlewares.map(({middleware}) => middleware),
     ],
   });
 
@@ -101,7 +117,10 @@ function buildSSRCommerceEngine(
     },
 
     waitForRequestCompletedAction() {
-      return actionCompletionMiddleware.promise;
+      return [
+        actionCompletionMiddleware.promise,
+        ...recommendationActionMiddlewares.map(({promise}) => promise),
+      ];
     },
   };
 }
@@ -163,6 +182,10 @@ export function defineCommerceEngine<
   type HydrateStaticStateFromBuildResultParameters =
     Parameters<HydrateStaticStateFromBuildResultFunction>;
 
+  const recommendationHelper = buildRecommendationFilter(
+    controllerDefinitions ?? {}
+  );
+
   const getOptions = () => {
     return engineOptions;
   };
@@ -180,7 +203,8 @@ export function defineCommerceEngine<
         solutionType,
         buildOptions?.extend
           ? await buildOptions.extend(getOptions())
-          : getOptions()
+          : getOptions(),
+        recommendationHelper.count
       );
       const controllers = buildControllerDefinitions({
         definitionsMap: (controllerDefinitions ?? {}) as TControllerDefinitions,
@@ -232,10 +256,14 @@ export function defineCommerceEngine<
             buildSearch(engine).executeFirstSearch();
           }
 
-          const searchAction = await engine.waitForRequestCompletedAction();
+          recommendationHelper.refresh(controllers);
+
+          const searchActions = await Promise.all(
+            engine.waitForRequestCompletedAction()
+          );
 
           return createStaticState({
-            searchAction,
+            searchActions,
             controllers,
           }) as EngineStaticState<
             UnknownAction,
@@ -266,7 +294,7 @@ export function defineCommerceEngine<
           solutionType
         ).fromBuildResult({
           buildResult,
-          searchAction: params[0]!.searchAction,
+          searchActions: params[0]!.searchActions,
         });
         return staticState;
       },
@@ -277,10 +305,13 @@ export function defineCommerceEngine<
           const [
             {
               buildResult: {engine, controllers},
-              searchAction,
+              searchActions,
             },
           ] = params;
-          engine.dispatch(searchAction);
+
+          searchActions.forEach((action) => {
+            engine.dispatch(action);
+          });
           await engine.waitForRequestCompletedAction();
           return {engine, controllers};
         },

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

@@ -1,3 +1,4 @@
+import {Recommendations} from '../../controllers/commerce/recommendations/headless-recommendations.js';
 import {Controller} from '../../controllers/controller/headless-controller.js';
 import {InvalidControllerDefinition} from '../../utils/errors.js';
 import {filterObject, mapObject} from '../../utils/utils.js';
@@ -103,3 +104,37 @@ export function ensureAtLeastOneSolutionType(
     throw new InvalidControllerDefinition();
   }
 }
+export function buildRecommendationFilter<
+  TEngine extends CoreEngine | CoreEngineNext,
+  TControllerDefinitions extends ControllerDefinitionsMap<TEngine, Controller>,
+>(controllerDefinitions: TControllerDefinitions) {
+  const keys = Object.entries(controllerDefinitions)
+    .filter(([_, value]) => 'isRecs' in value && value.isRecs)
+    .map(([key, _]) => key);
+
+  return {
+    /**
+     * Gets the number of recommendation controllers from the controller definitions map.
+     *
+     * @returns {number} The number of recommendation controllers in the controller definition map
+     */
+    get count() {
+      return keys.length;
+    },
+
+    /**
+     * 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.
+     */
+    refresh(controllers: Record<string, Controller>) {
+      const isRecommendationController = (key: string) => keys.includes(key);
+
+      Object.entries(controllers)
+        .filter(([key, _]) => isRecommendationController(key))
+        .forEach(([_, controller]) =>
+          (controller as Recommendations).refresh?.()
+        );
+    },
+  };
+}

packages/headless/src/app/search-engine/search-engine.ssr.ts

@@ -5,6 +5,7 @@ import {UnknownAction} from '@reduxjs/toolkit';
 import type {Controller} from '../../controllers/controller/headless-controller.js';
 import {LegacySearchAction} from '../../features/analytics/analytics-utils.js';
 import {createWaitForActionMiddleware} from '../../utils/utils.js';
+import {buildRecommendationFilter} from '../commerce-ssr-engine/common.js';
 import {NavigatorContextProvider} from '../navigatorContextProvider.js';
 import {
   buildControllerDefinitions,
@@ -36,7 +37,7 @@ export interface SSRSearchEngine extends SearchEngine {
   /**
    * Waits for the search to be completed and returns a promise that resolves to a `SearchCompletedAction`.
    */
-  waitForSearchCompletedAction(): Promise<SearchCompletedAction>;
+  waitForSearchCompletedAction(): Promise<SearchCompletedAction>[];
 }
 
 /**
@@ -60,21 +61,45 @@ function isSearchCompletedAction(
   );
 }
 
-function buildSSRSearchEngine(options: SearchEngineOptions): SSRSearchEngine {
+function isRecommendationCompletedAction(
+  action: unknown
+): action is SearchCompletedAction {
+  return /^recommendation\/get\/(fulfilled|rejected)$/.test(
+    (action as UnknownAction).type
+  );
+}
+
+function buildSSRSearchEngine(
+  options: SearchEngineOptions,
+  recommendationCount: number
+): SSRSearchEngine {
   const {middleware, promise} = createWaitForActionMiddleware(
     isSearchCompletedAction
   );
+
+  const recommendationActionMiddlewares = Array.from(
+    {length: recommendationCount},
+    () => createWaitForActionMiddleware(isRecommendationCompletedAction)
+  );
+
   const searchEngine = buildSearchEngine({
     ...options,
-    middlewares: [...(options.middlewares ?? []), middleware],
+    middlewares: [
+      ...(options.middlewares ?? []),
+      middleware,
+      ...recommendationActionMiddlewares.map(({middleware}) => middleware),
+    ],
   });
   return {
     ...searchEngine,
     get state() {
       return searchEngine.state;
     },
     waitForSearchCompletedAction() {
-      return promise;
+      return [
+        promise,
+        ...recommendationActionMiddlewares.map(({promise}) => promise),
+      ];
     },
   };
 }
@@ -121,6 +146,10 @@ export function defineSearchEngine<
   type HydrateStaticStateFromBuildResultParameters =
     Parameters<HydrateStaticStateFromBuildResultFunction>;
 
+  const recommendationHelper = buildRecommendationFilter(
+    controllerDefinitions ?? {}
+  );
+
   const getOptions = () => {
     return engineOptions;
   };
@@ -135,7 +164,8 @@ export function defineSearchEngine<
     const engine = buildSSRSearchEngine(
       buildOptions?.extend
         ? await buildOptions.extend(getOptions())
-        : getOptions()
+        : getOptions(),
+      recommendationHelper.count
     );
     const controllers = buildControllerDefinitions({
       definitionsMap: (controllerDefinitions ?? {}) as TControllerDefinitions,
@@ -175,8 +205,14 @@ export function defineSearchEngine<
         ] = params;
 
         engine.executeFirstSearch();
+        recommendationHelper.refresh(controllers);
+
+        const searchActions = await Promise.all(
+          engine.waitForSearchCompletedAction()
+        );
+
         return createStaticState({
-          searchAction: await engine.waitForSearchCompletedAction(),
+          searchActions,
           controllers,
         }) as EngineStaticState<
           UnknownAction,
@@ -197,7 +233,7 @@ export function defineSearchEngine<
       const buildResult = await build(...(params as BuildParameters));
       const staticState = await hydrateStaticState.fromBuildResult({
         buildResult,
-        searchAction: params[0]!.searchAction,
+        searchActions: params[0]!.searchActions,
       });
       return staticState;
     },
@@ -208,10 +244,13 @@ export function defineSearchEngine<
         const [
           {
             buildResult: {engine, controllers},
-            searchAction,
+            searchActions,
           },
         ] = params;
-        engine.dispatch(searchAction);
+
+        searchActions.forEach((action) => {
+          engine.dispatch(action);
+        });
         await engine.waitForSearchCompletedAction();
         return {engine, controllers};
       },

packages/headless/src/app/ssr-engine/common.ts

@@ -58,10 +58,10 @@ export function buildControllerDefinitions<
 }
 
 export function createStaticState<TSearchAction extends UnknownAction>({
-  searchAction,
+  searchActions,
   controllers,
 }: {
-  searchAction: TSearchAction;
+  searchActions: TSearchAction[];
   controllers: ControllersMap;
 }): EngineStaticState<
   TSearchAction,
@@ -71,7 +71,7 @@ export function createStaticState<TSearchAction extends UnknownAction>({
     controllers: mapObject(controllers, (controller) => ({
       state: clone(controller.state),
     })) as InferControllerStaticStateMapFromControllers<ControllersMap>,
-    searchAction: clone(searchAction),
+    searchActions: searchActions.map((action) => clone(action)),
   };
 }
 

packages/headless/src/app/ssr-engine/types/common.ts

@@ -105,7 +105,7 @@ export interface EngineStaticState<
   TSearchAction extends UnknownAction,
   TControllers extends ControllerStaticStateMap,
 > {
-  searchAction: TSearchAction;
+  searchActions: TSearchAction[];
   controllers: TControllers;
 }
 

packages/headless/src/app/ssr-engine/types/hydrate-static-state.ts

@@ -10,7 +10,7 @@ import {
 import {FromBuildResult} from './from-build-result.js';
 
 export interface HydrateStaticStateOptions<TSearchAction> {
-  searchAction: TSearchAction;
+  searchActions: TSearchAction[];
 }
 
 export type HydrateStaticState<

packages/headless/src/controllers/commerce/recommendations/headless-recommendations.ssr.ts

@@ -20,11 +20,12 @@ export interface RecommendationsDefinition
  * */
 export function defineRecommendations(
   props: RecommendationsProps
-): RecommendationsDefinition {
+): RecommendationsDefinition & {isRecs: true} {
   return {
     search: true,
     listing: true,
     standalone: true,
+    isRecs: true,
     build: (engine) => buildRecommendations(engine, props),
   };
 }

packages/samples/headless-ssr-commerce/app/_components/pages/listing-page.tsx

@@ -34,13 +34,10 @@ export default function ListingPage({
   useEffect(() => {
     listingEngineDefinition
       .hydrateStaticState({
-        searchAction: staticState.searchAction,
+        searchActions: staticState.searchActions,
       })
       .then(({engine, controllers}) => {
         setHydratedState({engine, controllers});
-        // Refreshing recommendations in the browser after hydrating the state in the client-side
-        // Recommendation refresh in the server is not supported yet.
-        controllers.popularBoughtRecs.refresh();
       });
   }, [staticState]);