feat(commerce): product seed passed through as recs context (#3904)

[CAPI-840](https://coveord.atlassian.net/jira/software/c/projects/CAPI/boards/1103?assignee=6168b023c5388b006911910a&selectedIssue=CAPI-840)

Headless Recommendations controller for Commerce API accepts an optional
product seed and passes it in every request.

[CAPI-840]:
https://coveord.atlassian.net/browse/CAPI-840?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

packages/headless/src/api/commerce/commerce-api-params.ts

@@ -25,9 +25,14 @@ export interface ContextParam {
   context: ContextParams;
 }
 
+export interface ProductParam {
+  productId: string;
+}
+
 export interface ContextParams {
   view: ViewParams;
   user?: UserParams;
+  product?: ProductParam;
   cart?: CartItemParam[];
 }
 

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

@@ -54,6 +54,10 @@ export interface RecommendationsOptions {
    * The unique identifier of the recommendations slot (e.g., `b953ab2e-022b-4de4-903f-68b2c0682942`).
    */
   slotId: string;
+  /**
+   * The unique identifier of the product to use for seeded recommendations.
+   */
+  productId?: string;
 }
 
 interface RecommendationsProps {
@@ -85,7 +89,7 @@ export function buildRecommendations(
   const controller = buildController(engine);
   const {dispatch} = engine;
 
-  const {slotId} = props.options;
+  const {slotId, productId} = props.options;
   dispatch(registerRecommendationsSlot({slotId}));
 
   const recommendationStateSelector = createSelector(
@@ -107,7 +111,7 @@ export function buildRecommendations(
       return recommendationStateSelector(engine[stateKey]);
     },
 
-    refresh: () => dispatch(fetchRecommendations({slotId})),
+    refresh: () => dispatch(fetchRecommendations({slotId, productId})),
   };
 }
 

packages/headless/src/features/commerce/recommendations/recommendations-actions.ts

@@ -24,11 +24,16 @@ export interface QueryRecommendationsCommerceAPIThunkReturn {
 
 const buildRecommendationCommerceAPIRequest = async (
   slotId: string,
-  state: StateNeededByQueryCommerceAPI
+  state: StateNeededByQueryCommerceAPI,
+  productId?: string
 ): Promise<CommerceRecommendationsRequest> => {
   const commerceAPIRequest = await buildBaseCommerceAPIRequest(state, slotId);
   return {
     ...commerceAPIRequest,
+    context: {
+      ...commerceAPIRequest.context,
+      ...(productId ? {product: {productId}} : {}),
+    },
     slotId,
   };
 };
@@ -38,6 +43,7 @@ export interface FetchRecommendationsActionCreatorPayload {
    * The unique identifier of the recommendations slot (e.g., `b953ab2e-022b-4de4-903f-68b2c0682942`).
    */
   slotId: string;
+  productId?: string;
 }
 
 export const fetchRecommendations = createAsyncThunk<
@@ -47,10 +53,11 @@ export const fetchRecommendations = createAsyncThunk<
 >(
   'commerce/recommendations/fetch',
   async (payload, {getState, rejectWithValue, extra: {apiClient}}) => {
-    const slotId = payload.slotId;
+    const {slotId, productId} = payload;
     const request = await buildRecommendationCommerceAPIRequest(
       slotId,
-      getState()
+      getState(),
+      productId
     );
     const fetched = await apiClient.getRecommendations(request);
 

packages/headless/src/features/commerce/recommendations/recommendations.ts

@@ -1,9 +1,11 @@
 import {Schema} from '@coveo/bueno';
+import {StringValue} from '@coveo/bueno';
 import {RecommendationsOptions} from '../../../controllers/commerce/recommendations/headless-recommendations';
 import {requiredNonEmptyString} from '../../../utils/validate-payload';
 
 export const recommendationsSlotDefinition = {
   slotId: requiredNonEmptyString,
+  productId: new StringValue({required: false, emptyAllowed: false}),
 };
 
 export const recommendationsOptionsSchema = new Schema<RecommendationsOptions>(