feat(commerce): make commerce sub-package generally available (#4088)

Opening as draft because I'd like some advice on the message we include
to indicate deprecation of the `product-listing` sub-package. I was
thinking of something like:
> @deprecated The `product-listing` sub-package is deprecated. Prefer
using the `commerce` sub-package instead.

@anthonydelage @jpmarceau 

Also, is there something else that needs to be done in headless apart
from removing the comments?

[CAPI-98]

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

packages/headless/src/api/search/search/product-recommendation.ts

@@ -1,3 +1,7 @@
+/**
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface ProductRecommendation {
   /**
    * This parameter is no longer used by the Coveo Usage Analytics service.

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

@@ -12,8 +12,6 @@ import {
 
 /**
  * The commerce engine configuration options.
- *
- * In Open Beta. Reach out to your Coveo team for support in adopting this.
  */
 export interface CommerceEngineConfiguration extends EngineConfiguration {
   context: ContextOptions;

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

@@ -61,8 +61,6 @@ export type CommerceEngineState =
 
 /**
  * The engine for powering commerce experiences.
- *
- * In Open Beta. Reach out to your Coveo team for support in adopting this.
  */
 export interface CommerceEngine<State extends object = {}>
   extends CoreEngineNext<
@@ -72,8 +70,6 @@ export interface CommerceEngine<State extends object = {}>
 
 /**
  * The commerce engine options.
- *
- * In Open Beta. Reach out to your Coveo team for support in adopting this.
  */
 export interface CommerceEngineOptions
   extends ExternalEngineOptions<CommerceEngineState> {
@@ -86,8 +82,6 @@ export interface CommerceEngineOptions
 /**
  * Creates a commerce engine instance.
  *
- * In Open Beta. Reach out to your Coveo team for support in adopting this.
- *
  * @param options - The commerce engine options.
  * @returns A commerce engine instance.
  */

packages/headless/src/app/product-listing-engine/product-listing-engine-configuration.ts

@@ -13,6 +13,9 @@ import {
 
 /**
  * The product listing engine configuration.
+ *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductListingEngineConfiguration
   extends EngineConfiguration {}
@@ -61,6 +64,9 @@ export const productListingEngineConfigurationSchema =
 /**
  * Creates a sample product listing engine configuration.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @returns The sample product listing engine configuration.
  */
 export function getSampleProductListingEngineConfiguration(): ProductListingEngineConfiguration {

packages/headless/src/app/product-listing-engine/product-listing-engine.ts

@@ -37,6 +37,9 @@ type ProductListingEngineState =
 
 /**
  * The engine for powering production listing experiences.
+ *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductListingEngine<State extends object = {}>
   extends CoreEngine<
@@ -46,6 +49,9 @@ export interface ProductListingEngine<State extends object = {}>
 
 /**
  * The product listing engine options.
+ *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductListingEngineOptions
   extends ExternalEngineOptions<ProductListingEngineState> {
@@ -58,6 +64,9 @@ export interface ProductListingEngineOptions
 /**
  * Creates a product listing engine instance.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param options - The product listing engine options.
  * @returns A product listing engine instance.
  */

packages/headless/src/app/product-recommendation-engine/product-recommendation-engine-configuration.ts

@@ -16,6 +16,9 @@ import {
 
 /**
  * The product recommendation engine configuration.
+ *
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductRecommendationEngineConfiguration
   extends EngineConfiguration {
@@ -93,6 +96,9 @@ export const productRecommendationEngineConfigurationSchema =
 /**
  * Creates a sample product recommendation engine configuration.
  *
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @returns The sample product recommendation engine configuration.
  */
 export function getSampleProductRecommendationEngineConfiguration(): ProductRecommendationEngineConfiguration {

packages/headless/src/app/product-recommendation-engine/product-recommendation-engine.ts

@@ -39,6 +39,9 @@ type ProductRecommendationEngineState =
 
 /**
  * The engine for powering production recommendation experiences.
+ *
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductRecommendationEngine<State extends object = {}>
   extends CoreEngine<
@@ -48,6 +51,9 @@ export interface ProductRecommendationEngine<State extends object = {}>
 
 /**
  * The product recommendation engine options.
+ *
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductRecommendationEngineOptions
   extends ExternalEngineOptions<ProductRecommendationEngineState> {
@@ -60,6 +66,9 @@ export interface ProductRecommendationEngineOptions
 /**
  * Creates a product recommendation engine instance.
  *
+ * Deprecated. The `product-recommendation` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param options - The product recommendation engine options.
  * @returns A product recommendation engine instance.
  */

packages/headless/src/controllers/product-listing/category-facet/headless-product-listing-category-facet.ts

@@ -62,6 +62,9 @@ export type {
 /**
  * Creates a `CategoryFacet` controller instance.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `CategoryFacet` properties.
  * @returns A `CategoryFacet` controller instance.

packages/headless/src/controllers/product-listing/facet/headless-product-listing-facet-manager.ts

@@ -16,6 +16,9 @@ export type {FacetManager, FacetManagerState, FacetManagerPayload};
 /**
  * Creates a `FacetManager` instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param productListingEngine - The headless engine.
  */
 export function buildFacetManager(

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

@@ -59,6 +59,10 @@ export type {
   CoreFacetState,
 };
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface FacetProps {
   /**
    * The options for the `Facet` controller.
@@ -69,6 +73,9 @@ export interface FacetProps {
 /**
  * Creates a `Facet` controller instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `Facet` properties.
  * @returns A `Facet` controller instance.

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

@@ -25,6 +25,10 @@ const optionsSchema = new Schema({
   }),
 });
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface ProductListingOptions {
   /**
    * The initial URL used to retrieve the product listing.
@@ -37,6 +41,10 @@ export interface ProductListingOptions {
   additionalFields?: string[];
 }
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface ProductListingProps {
   /**
    * The initial options that should be applied to this `ProductListing` controller.
@@ -46,6 +54,9 @@ export interface ProductListingProps {
 
 /**
  * The `ProductListing` controller allows the end user to configure and retrieve product listing data.
+ *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface ProductListing extends Controller {
   /**
@@ -71,6 +82,10 @@ export interface ProductListing extends Controller {
   state: ProductListingState;
 }
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface ProductListingState {
   products: ProductRecommendation[];
   error: ProductListingAPIErrorStatusResponse | null;
@@ -80,11 +95,18 @@ export interface ProductListingState {
   url: string;
 }
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export type ProductListingControllerState = ProductListing['state'];
 
 /**
  * Creates a `ProductListingController` controller instance.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `ProductListingController` properties.
  * @returns A `ProductListingController` controller instance.

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

@@ -14,6 +14,9 @@ export type {PagerInitialState, PagerOptions, PagerProps, Pager, PagerState};
 /**
  * Creates a `Pager` controller instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `Pager` properties.
  * @returns A `Pager` controller instance.

packages/headless/src/controllers/product-listing/range-facet/date-facet/headless-product-listing-date-facet.ts

@@ -34,6 +34,9 @@ export {buildDateRange};
 /**
  * Creates a `DateFacet` controller instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `DateFacet` controller properties.
  * @returns A `DateFacet` controller instance.

packages/headless/src/controllers/product-listing/range-facet/date-facet/headless-product-listing-date-filter.ts

@@ -33,6 +33,9 @@ export type {
 };
 
 /**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `DateFilter` properties.
  * @returns - A `DateFilter` controller instance.

packages/headless/src/controllers/product-listing/range-facet/numeric-facet/headless-product-listing-numeric-facet.ts

@@ -41,6 +41,9 @@ export {buildNumericRange};
 /**
  * Creates a `NumericFacet` controller instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `NumericFacet` properties.
  * @returns A `NumericFacet` controller instance.

packages/headless/src/controllers/product-listing/range-facet/numeric-facet/headless-product-listing-numeric-filter.ts

@@ -33,6 +33,9 @@ export type {
 };
 
 /**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `NumericFilter` properties.
  * @returns - A `NumericFilter` controller instance.

packages/headless/src/controllers/product-listing/result-list/headless-product-listing-interactive-result.ts

@@ -13,13 +13,22 @@ export type {
   InteractiveResultCoreOptions,
   InteractiveResultCoreProps,
 };
+
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface InteractiveResultOptions extends InteractiveResultCoreOptions {
   /**
    * The query result.
    */
   result: ProductRecommendation;
 }
 
+/**
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ */
 export interface InteractiveResultProps extends InteractiveResultCoreProps {
   /**
    * The options for the `InteractiveResult` controller.
@@ -29,12 +38,18 @@ export interface InteractiveResultProps extends InteractiveResultCoreProps {
 
 /**
  * The `InteractiveResult` controller provides an interface for triggering desirable side effects, such as logging UA events to the Coveo Platform, when a user selects a query result.
+ *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
  */
 export interface InteractiveResult extends InteractiveResultCore {}
 
 /**
  * Creates an `InteractiveResult` controller instance.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `InteractiveResult` properties.
  * @returns An `InteractiveResult` controller instance.

packages/headless/src/controllers/product-listing/results-per-page/headless-product-listing-results-per-page.ts

@@ -26,6 +26,9 @@ export type {
 /**
  * Creates a `ResultsPerPage` controller instance for the product listing.
  *
+ * Deprecated. The `product-listing` sub-package is deprecated. Use the `commerce` sub-package instead.
+ * @deprecated
+ *
  * @param engine - The headless engine.
  * @param props - The configurable `ResultsPerPage` properties.
  * @returns A `ResultsPerPage` controller instance.