feat(headless): spike supporting 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 {ResultPosition, ResultType} from './result.js';
 
 export type ChildProduct = Omit<
   BaseProduct,
@@ -143,13 +144,10 @@ export interface BaseProduct {
    * The ID of the response that returned the product.
    */
   responseId?: string;
-}
-
-export interface Product extends BaseProduct {
   /**
-   * The 1-based product's position across the non-paginated result set.
-   *
-   * For example, if the product is the third one on the second page, and there are 10 products per page, its position is 13 (not 3).
+   * The result type of the product.
    */
-  position: number;
+  resultType: ResultType.PRODUCT | ResultType.CHILD_PRODUCT;
 }
+
+export interface Product extends ResultPosition, BaseProduct {}

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

@@ -0,0 +1,54 @@
+import type {BaseProduct, Product} from './product.js';
+
+export enum ResultType {
+  CHILD_PRODUCT = 'childProduct',
+  PRODUCT = 'product',
+  SPOTLIGHT = 'spotlight',
+}
+
+export interface BaseSpotlightContent {
+  /**
+   * 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 ID of the response that returned the spotlight content.
+   */
+  responseId?: string;
+  /**
+   * The result type identifier, always SPOTLIGHT for spotlight content.
+   */
+  resultType: ResultType.SPOTLIGHT;
+}
+
+export interface ResultPosition {
+  /**
+   * The 1-based result's position across the non-paginated result set.
+   *
+   * For example, if the result is the third one on the second page, and there are 10 results per page, its position is 13 (not 3).
+   */
+  position: number;
+}
+
+export interface SpotlightContent
+  extends ResultPosition,
+    BaseSpotlightContent {}
+
+export type BaseResult = BaseProduct | BaseSpotlightContent;
+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/commerce.index.ts

@@ -239,6 +239,7 @@ export type {
 export {buildInstantProducts} from './controllers/commerce/instant-products/headless-instant-products.js';
 export type {
   ProductListing,
+  ProductListingOptions,
   ProductListingState,
 } from './controllers/commerce/product-listing/headless-product-listing.js';
 export {buildProductListing} from './controllers/commerce/product-listing/headless-product-listing.js';

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

@@ -29,18 +29,13 @@ 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(() => {
@@ -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,
@@ -75,7 +70,58 @@ describe('headless product-listing', () => {
     });
   });
 
+  it('creates closures for fetching products that capture default enableResults=false', () => {
+    const buildProductListingSubControllers = vi.spyOn(
+      SubControllers,
+      'buildProductListingSubControllers'
+    );
+    const fetchProductListingMock = vi.spyOn(
+      ProductListingActions,
+      'fetchProductListing'
+    );
+    const fetchMoreProductsMock = vi.spyOn(
+      ProductListingActions,
+      'fetchMoreProducts'
+    );
+
+    buildProductListing(engine);
+
+    const callArgs = buildProductListingSubControllers.mock.calls[0][1];
+    callArgs.fetchProductsActionCreator();
+    expect(fetchProductListingMock).toHaveBeenCalledWith({
+      enableResults: false,
+    });
+
+    callArgs.fetchMoreProductsActionCreator();
+    expect(fetchMoreProductsMock).toHaveBeenCalledWith({enableResults: false});
+  });
+
+  it('creates closures for fetching products that capture enableResults=true', () => {
+    const buildProductListingSubControllers = vi.spyOn(
+      SubControllers,
+      'buildProductListingSubControllers'
+    );
+    const fetchProductListingMock = vi.spyOn(
+      ProductListingActions,
+      'fetchProductListing'
+    );
+    const fetchMoreProductsMock = vi.spyOn(
+      ProductListingActions,
+      'fetchMoreProducts'
+    );
+
+    buildProductListing(engine, {enableResults: true});
+
+    const callArgs = buildProductListingSubControllers.mock.calls[0][1];
+    callArgs.fetchProductsActionCreator();
+    expect(fetchProductListingMock).toHaveBeenCalledWith({enableResults: true});
+
+    callArgs.fetchMoreProductsActionCreator();
+    expect(fetchMoreProductsMock).toHaveBeenCalledWith({enableResults: true});
+  });
+
   it('adds the correct reducers to engine', () => {
+    buildProductListing(engine);
     expect(engine.addReducers).toHaveBeenCalledWith({
       productListing: productListingReducer,
       commerceContext: contextReducer,
@@ -90,32 +136,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});
   });
 });