feat(headless): support spotlight content for commerce COMHUB2-1228

packages/headless-react/src/__tests__/mock-products.ts

@@ -1,5 +1,6 @@
 import {randomUUID} from 'node:crypto';
 import type {Product} from '@coveo/headless/ssr-commerce';
+import {ResultType} from '@coveo/headless/ssr-commerce';
 
 const createMockProduct = (overrides: Partial<Product> = {}): Product => ({
   additionalFields: {},
@@ -24,6 +25,7 @@ const createMockProduct = (overrides: Partial<Product> = {}): Product => ({
   permanentid: randomUUID(),
   position: 1,
   totalNumberOfChildren: 0,
+  resultType: ResultType.PRODUCT,
   ...overrides,
 });
 

packages/headless/src/api/commerce/commerce-api-client.test.ts

@@ -9,6 +9,7 @@ import {
 } from './commerce-api-client.js';
 import type {FilterableCommerceAPIRequest} from './common/request.js';
 import type {CommerceResponse} from './common/response.js';
+import type {CommerceListingRequest} from './listing/request.js';
 import type {CommerceRecommendationsRequest} from './recommendations/recommendations-request.js';
 
 describe('commerce api client', () => {
@@ -81,7 +82,10 @@ describe('commerce api client', () => {
   };
 
   it('#getProductListing should call the platform endpoint with the correct arguments', async () => {
-    const request = await buildCommerceAPIRequest();
+    const request: CommerceListingRequest = {
+      ...(await buildCommerceAPIRequest()),
+      enableResults: false,
+    };
 
     mockPlatformCall({
       ok: true,
@@ -279,7 +283,10 @@ describe('commerce api client', () => {
   });
 
   it('should return error response on failure', async () => {
-    const request = await buildCommerceAPIRequest();
+    const request: CommerceListingRequest = {
+      ...(await buildCommerceAPIRequest()),
+      enableResults: false,
+    };
 
     const expectedError = {
       statusCode: 401,
@@ -300,7 +307,10 @@ describe('commerce api client', () => {
   });
 
   it('should return success response on success', async () => {
-    const request = await buildCommerceAPIRequest();
+    const request: CommerceListingRequest = {
+      ...(await buildCommerceAPIRequest()),
+      enableResults: false,
+    };
 
     const expectedBody: CommerceResponse = {
       products: [],

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

@@ -14,15 +14,14 @@ import type {
   CommerceAPIErrorResponse,
   CommerceAPIErrorStatusResponse,
 } from './commerce-api-error-response.js';
-import {
-  type FilterableCommerceAPIRequest,
-  getRequestOptions,
-} from './common/request.js';
+import {getRequestOptions} from './common/request.js';
 import type {CommerceSuccessResponse} from './common/response.js';
 import type {
   CommerceFacetSearchRequest,
   FacetSearchType,
 } from './facet-search/facet-search-request.js';
+import type {CommerceListingRequest} from './listing/request.js';
+import type {ListingCommerceSuccessResponse} from './listing/response.js';
 import {
   buildRecommendationsRequest,
   type CommerceRecommendationsRequest,
@@ -74,10 +73,15 @@ export class CommerceAPIClient implements CommerceFacetSearchAPIClient {
   constructor(private options: CommerceAPIClientOptions) {}
 
   async getProductListing(
-    req: FilterableCommerceAPIRequest
-  ): Promise<CommerceAPIResponse<CommerceSuccessResponse>> {
+    req: CommerceListingRequest
+  ): Promise<CommerceAPIResponse<ListingCommerceSuccessResponse>> {
+    const requestOptions = getRequestOptions(req, 'listing');
     return this.query({
-      ...getRequestOptions(req, 'listing'),
+      ...requestOptions,
+      requestParams: {
+        ...requestOptions.requestParams,
+        enableResults: req.enableResults,
+      },
       ...this.options,
     });
   }

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

@@ -25,6 +25,10 @@ export interface ContextParam {
   context: ContextParams;
 }
 
+export interface EnableResultsParam {
+  enableResults: boolean;
+}
+
 type ProductParam = {
   productId: string;
 };

packages/headless/src/api/commerce/common/product.ts

@@ -1,4 +1,5 @@
 import type {HighlightKeyword} from '../../../utils/highlight.js';
+import type {ResultType} from './result.js';
 
 export type ChildProduct = Omit<
   BaseProduct,
@@ -143,6 +144,10 @@ export interface BaseProduct {
    * The ID of the response that returned the product.
    */
   responseId?: string;
+  /**
+   * The result type of the product.
+   */
+  resultType: ResultType.PRODUCT | ResultType.CHILD_PRODUCT;
 }
 
 export interface Product extends BaseProduct {

packages/headless/src/api/commerce/common/result.ts

@@ -0,0 +1,37 @@
+import type {BaseProduct, Product} from './product.js';
+
+export enum ResultType {
+  CHILD_PRODUCT = 'childProduct',
+  PRODUCT = 'product',
+  SPOTLIGHT = 'spotlight',
+}
+
+export interface SpotlightContent {
+  /**
+   * The URI to navigate to when the spotlight content is clicked.
+   */
+  clickUri: string;
+  /**
+   * The image URL for desktop display.
+   */
+  desktopImage: string;
+  /**
+   * The image URL for mobile display.
+   */
+  mobileImage?: string;
+  /**
+   * The name of the spotlight content.
+   */
+  name?: string;
+  /**
+   * The description of the spotlight content.
+   */
+  description?: string;
+  /**
+   * The result type identifier, always SPOTLIGHT for spotlight content.
+   */
+  resultType: ResultType.SPOTLIGHT;
+}
+
+export type BaseResult = BaseProduct | SpotlightContent;
+export type Result = Product | SpotlightContent;

packages/headless/src/api/commerce/listing/request.ts

@@ -0,0 +1,5 @@
+import type {EnableResultsParam} from '../commerce-api-params.js';
+import type {FilterableCommerceAPIRequest} from '../common/request.js';
+
+export type CommerceListingRequest = FilterableCommerceAPIRequest &
+  EnableResultsParam;

packages/headless/src/api/commerce/listing/response.ts

@@ -0,0 +1,7 @@
+import type {CommerceSuccessResponse} from '../common/response.js';
+import type {BaseResult} from '../common/result.js';
+
+export interface ListingCommerceSuccessResponse
+  extends CommerceSuccessResponse {
+  results: BaseResult[];
+}

packages/headless/src/controllers/commerce/product-listing/headless-product-listing.test.ts

@@ -29,25 +29,20 @@ import {
   facetResponseSelector,
   isFacetLoadingResponseSelector,
 } from './facets/headless-product-listing-facet-options.js';
-import {
-  buildProductListing,
-  type ProductListing,
-} from './headless-product-listing.js';
+import {buildProductListing} from './headless-product-listing.js';
 
 describe('headless product-listing', () => {
-  let productListing: ProductListing;
   let engine: MockedCommerceEngine;
 
   beforeEach(() => {
     engine = buildMockCommerceEngine(buildMockCommerceState());
-    productListing = buildProductListing(engine);
   });
 
   afterEach(() => {
     vi.clearAllMocks();
   });
 
-  it('uses sub-controllers', () => {
+  it('uses sub-controllers with default enableResults=false', () => {
     const buildProductListingSubControllers = vi.spyOn(
       SubControllers,
       'buildProductListingSubControllers'
@@ -57,8 +52,8 @@ describe('headless product-listing', () => {
 
     expect(buildProductListingSubControllers).toHaveBeenCalledWith(engine, {
       responseIdSelector,
-      fetchProductsActionCreator: ProductListingActions.fetchProductListing,
-      fetchMoreProductsActionCreator: ProductListingActions.fetchMoreProducts,
+      fetchProductsActionCreator: expect.any(Function),
+      fetchMoreProductsActionCreator: expect.any(Function),
       facetResponseSelector,
       isFacetLoadingResponseSelector,
       requestIdSelector,
@@ -76,6 +71,7 @@ describe('headless product-listing', () => {
   });
 
   it('adds the correct reducers to engine', () => {
+    buildProductListing(engine);
     expect(engine.addReducers).toHaveBeenCalledWith({
       productListing: productListingReducer,
       commerceContext: contextReducer,
@@ -90,32 +86,62 @@ describe('headless product-listing', () => {
     );
     const child = {permanentid: 'childPermanentId'} as ChildProduct;
 
+    const productListing = buildProductListing(engine);
     productListing.promoteChildToParent(child);
 
     expect(promoteChildToParent).toHaveBeenCalledWith({
       child,
     });
   });
 
-  it('#refresh dispatches #fetchProductListing', () => {
+  it('#refresh dispatches #fetchProductListing with enableResults=false by default', () => {
     const fetchProductListing = vi.spyOn(
       ProductListingActions,
       'fetchProductListing'
     );
 
+    const productListing = buildProductListing(engine);
     productListing.refresh();
 
-    expect(fetchProductListing).toHaveBeenCalled();
+    expect(fetchProductListing).toHaveBeenCalledWith({enableResults: false});
   });
 
-  it('#executeFirstRequest dispatches #fetchProductListing', () => {
-    const executeRequest = vi.spyOn(
+  it('#refresh dispatches #fetchProductListing with enableResults=true when specified', () => {
+    const fetchProductListing = vi.spyOn(
       ProductListingActions,
       'fetchProductListing'
     );
+    const productListingWithResults = buildProductListing(engine, {
+      enableResults: true,
+    });
+
+    productListingWithResults.refresh();
 
+    expect(fetchProductListing).toHaveBeenCalledWith({enableResults: true});
+  });
+
+  it('#executeFirstRequest dispatches #fetchProductListing with enableResults=false by default', () => {
+    const executeRequest = vi.spyOn(
+      ProductListingActions,
+      'fetchProductListing'
+    );
+    const productListing = buildProductListing(engine);
     productListing.executeFirstRequest();
 
-    expect(executeRequest).toHaveBeenCalled();
+    expect(executeRequest).toHaveBeenCalledWith({enableResults: false});
+  });
+
+  it('#executeFirstRequest dispatches #fetchProductListing with enableResults=true when specified', () => {
+    const executeRequest = vi.spyOn(
+      ProductListingActions,
+      'fetchProductListing'
+    );
+    const productListingWithResults = buildProductListing(engine, {
+      enableResults: true,
+    });
+
+    productListingWithResults.executeFirstRequest();
+
+    expect(executeRequest).toHaveBeenCalledWith({enableResults: true});
   });
 });

packages/headless/src/controllers/commerce/product-listing/headless-product-listing.ts

@@ -17,6 +17,7 @@ import {parametersDefinition} from '../../../features/commerce/parameters/parame
 import {activeParametersSelector} from '../../../features/commerce/parameters/parameters-selectors.js';
 import {productListingSerializer} from '../../../features/commerce/parameters/parameters-serializer.js';
 import {
+  type FetchProductListingPayload,
   fetchMoreProducts,
   fetchProductListing,
   promoteChildToParent,
@@ -102,27 +103,36 @@ export interface ProductListingState {
   responseId: string;
 }
 
+interface ProductListingOptions extends FetchProductListingPayload {}
+
 /**
  * Creates a `ProductListing` controller instance.
  *
  * @param engine - The headless commerce engine.
+ * @param options - The configurable `ProductListing` controller options.
  * @returns A `ProductListing` controller instance.
  *
  * @group Buildable controllers
  * @category ProductListing
  */
-export function buildProductListing(engine: CommerceEngine): ProductListing {
+export function buildProductListing(
+  engine: CommerceEngine,
+  {enableResults = false}: ProductListingOptions = {
+    enableResults: false,
+  }
+): ProductListing {
   if (!loadBaseProductListingReducers(engine)) {
     throw loadReducerError;
   }
 
   const controller = buildController(engine);
   const {dispatch} = engine;
   const getState = () => engine[stateKey];
+
   const subControllers = buildProductListingSubControllers(engine, {
     responseIdSelector,
-    fetchProductsActionCreator: fetchProductListing,
-    fetchMoreProductsActionCreator: fetchMoreProducts,
+    fetchProductsActionCreator: () => fetchProductListing({enableResults}),
+    fetchMoreProductsActionCreator: () => fetchMoreProducts({enableResults}),
     facetResponseSelector,
     isFacetLoadingResponseSelector,
     requestIdSelector,
@@ -157,7 +167,7 @@ export function buildProductListing(engine: CommerceEngine): ProductListing {
       dispatch(promoteChildToParent({child}));
     },
 
-    refresh: () => dispatch(fetchProductListing()),
+    refresh: () => dispatch(fetchProductListing({enableResults})),
 
     executeFirstRequest() {
       const firstRequestExecuted = responseIdSelector(getState()) !== '';
@@ -166,7 +176,7 @@ export function buildProductListing(engine: CommerceEngine): ProductListing {
         return;
       }
 
-      dispatch(fetchProductListing());
+      dispatch(fetchProductListing({enableResults}));
     },
   };
 }

packages/headless/src/features/commerce/instant-products/instant-products-slice.ts

@@ -4,6 +4,7 @@ import type {
   ChildProduct,
   Product,
 } from '../../../api/commerce/common/product.js';
+import {ResultType} from '../../../api/commerce/common/result.js';
 import {
   clearExpiredItems,
   fetchItemsFulfilled,
@@ -91,6 +92,7 @@ export const instantProductsReducer = createReducer(
 
         const newParent: Product = {
           ...(childToPromote as ChildProduct),
+          resultType: ResultType.PRODUCT,
           children,
           totalNumberOfChildren,
           position,