feat(headless): refresh commerce recommendations server-side (#4617)

Adding server-side rendering for commerce SSR package only.

* Updated `headless-react` package to reflect the new changes
* Updated `headless-ssr-commerce` sample to reflect the new changes


## Features
### Customizable Recommendation Controller
* Users can specify which recommendation controller to refresh by
providing the recommendation key (as defined in the engine
configuration).
* If no key is specified, the recommendation controller will not perform
any queries.
<img width="639" alt="image"
src="https://github.com/user-attachments/assets/e612f0e9-dd64-4d35-8dd8-785c82edd346">

* Supports selecting recommendations using the build method.
<img width="516" alt="image"
src="https://github.com/user-attachments/assets/28efb015-5f21-4c5e-909e-73d9e7b2ccde">

### Recommendation Name Validation
* Validation against invalid recommendation names.
* Prevention of duplicate recommendation names.

## Code to increase readability
### Factory methods
Moved factory methods into dedicated files to avoid bloating the
`commerce-engine-ssr` file.
Examples include:
* `hydrated-state-factory.ts`
* `static-state-factory.ts`

### Core Engine Types
Centralized all core engine types into `types/core-engine.ts`.

### Recommendation State Factories
Created dedicated factories for handling static and hydrated states for
recommendations (`recommendation-static-state-factory.ts`).

### Improved Controller Handling
Simplified the logic for building controllers based on solution type to
eliminate complex, hard-to-read conditional blocks
(677fd45)


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

---------

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

packages/headless-react/src/ssr-commerce/commerce-engine.test.tsx

@@ -49,6 +49,7 @@ describe('Headless react SSR utils', () => {
       listingEngineDefinition,
       searchEngineDefinition,
       standaloneEngineDefinition,
+      recommendationEngineDefinition,
       ...rest
     } = defineCommerceEngine({configuration: sampleConfig});
     const {

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

@@ -46,12 +46,14 @@ export function defineCommerceEngine<
   >;
   type ListingContext = ContextStateType<SolutionType.listing>;
   type SearchContext = ContextStateType<SolutionType.search>;
+  type RecommendationContext = ContextStateType<SolutionType.recommendation>;
   type StandaloneContext = ContextStateType<SolutionType.standalone>;
 
   const {
     listingEngineDefinition,
     searchEngineDefinition,
     standaloneEngineDefinition,
+    recommendationEngineDefinition,
   } = defineBaseCommerceEngine({...options});
   return {
     useEngine: buildEngineHook(singletonContext),
@@ -84,5 +86,14 @@ export function defineCommerceEngine<
         singletonContext as StandaloneContext
       ),
     },
+    recommendationEngineDefinition: {
+      ...recommendationEngineDefinition,
+      StaticStateProvider: buildStaticStateProvider(
+        singletonContext as RecommendationContext
+      ),
+      HydratedStateProvider: buildHydratedStateProvider(
+        singletonContext as RecommendationContext
+      ),
+    },
   };
 }