chore: Adjusting the v2 product module to follow the v1 specs (#6618)

In this PR:
1. I added upsert support for the product
2. I updated the create and update signatures to match the latest interface standards
3. Small changes to make the v1 and v2 APIs compatible (WIP)

packages/types/src/product/common.ts

@@ -927,6 +927,10 @@ export interface CreateProductTypeDTO {
 export interface UpsertProductTypeDTO {
   id?: string
   value: string
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown>
 }
 
 /**
@@ -1103,6 +1107,14 @@ export interface CreateProductVariantDTO {
   metadata?: Record<string, unknown>
 }
 
+export interface UpsertProductVariantDTO
+  extends Omit<UpdateProductVariantDTO, "id"> {
+  /**
+   * The ID of the product variant to update.
+   */
+  id?: string
+}
+
 /**
  * @interface
  *
@@ -1238,11 +1250,11 @@ export interface CreateProductDTO {
   /**
    * The product type to be associated with the product.
    */
-  type_id?: string
+  type_id?: string | null
   /**
    * The product collection to be associated with the product.
    */
-  collection_id?: string
+  collection_id?: string | null
   /**
    * The product tags to be created and associated with the product.
    */
@@ -1297,16 +1309,19 @@ export interface CreateProductDTO {
   metadata?: Record<string, unknown>
 }
 
+export interface UpsertProductDTO extends UpdateProductDTO {
+  /**
+   * The ID of the product to update.
+   */
+  id?: string
+}
+
 /**
  * @interface
  *
  * The data to update in a product. The `id` is used to identify which product to update.
  */
 export interface UpdateProductDTO {
-  /**
-   * The ID of the product to update.
-   */
-  id: string
   /**
    * The title of the product.
    */
@@ -1372,7 +1387,7 @@ export interface UpdateProductDTO {
   /**
    * The product variants to be created and associated with the product. You can also update existing product variants associated with the product.
    */
-  variants?: (CreateProductVariantDTO | UpdateProductVariantDTO)[]
+  variants?: UpsertProductVariantDTO[]
   /**
    * The width of the product.
    */

packages/types/src/product/service.ts

@@ -28,6 +28,7 @@ import {
   UpdateProductTagDTO,
   UpdateProductTypeDTO,
   UpdateProductVariantDTO,
+  UpsertProductDTO,
 } from "./common"
 
 import { FindConfig } from "../common"
@@ -2500,7 +2501,7 @@ export interface IProductModuleService extends IModuleService {
   deleteCategory(categoryId: string, sharedContext?: Context): Promise<void>
 
   /**
-   * This method is used to create a product.
+   * This method is used to create a list of products.
    *
    * @param {CreateProductDTO[]} data - The products to be created.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
@@ -2528,12 +2529,97 @@ export interface IProductModuleService extends IModuleService {
     sharedContext?: Context
   ): Promise<ProductDTO[]>
 
+  /**
+   * This method is used to create a product.
+   *
+   * @param {CreateProductDTO} data - The product to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductDTO>} The created product.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function createProduct (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const product = await productModule.create(
+   *     {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the product or return it
+   * }
+   */
+  create(data: CreateProductDTO, sharedContext?: Context): Promise<ProductDTO>
+
+  /**
+   * This method updates existing products, or creates new ones if they don't exist.
+   *
+   * @param {CreateProductDTO[]} data - The attributes to update or create for each product.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductDTO[]>} The updated and created products.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upserProduct (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdProducts = await productModule.upsert([
+   *     {
+   *       title
+   *     }
+   *   ])
+   *
+   *   // do something with the products or return them
+   * }
+   */
+  upsert(
+    data: UpsertProductDTO[],
+    sharedContext?: Context
+  ): Promise<ProductDTO[]>
+
+  /**
+   * This method updates the product if it exists, or creates a new ones if it doesn't.
+   *
+   * @param {CreateProductDTO} data - The attributes to update or create for the new product.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductDTO>} The updated or created product.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upserProduct (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdProduct = await productModule.upsert(
+   *     {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the product or return it
+   * }
+   */
+  upsert(
+    data: UpsertProductDTO[],
+    sharedContext?: Context
+  ): Promise<ProductDTO[]>
+
   /**
    * This method is used to update a product.
    *
-   * @param {UpdateProductDTO[]} data - The products to be updated, each holding the attributes that should be updated in the product.
+   * @param {string} id - The ID of the product to be updated.
+   * @param {UpdateProductDTO} data - The attributes of the product to be updated
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<ProductDTO[]>} The list of updated products.
+   * @returns {Promise<ProductDTO>} The updated product.
    *
    * @example
    * import {
@@ -2543,18 +2629,47 @@ export interface IProductModuleService extends IModuleService {
    * async function updateProduct (id: string, title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const products = await productModule.update([
-   *     {
-   *       id,
+   *   const product = await productModule.update(id, {
    *       title
    *     }
-   *   ])
+   *   )
+   *
+   *   // do something with the product or return it
+   * }
+   */
+  update(
+    id: string,
+    data: UpdateProductDTO,
+    sharedContext?: Context
+  ): Promise<ProductDTO>
+
+  /**
+   * This method is used to update a list of products determined by the selector filters.
+   *
+   * @param {FilterableProductProps} selector - The filters that will determine which products will be updated.
+   * @param {UpdateProductDTO} data - The attributes to be updated on the selected products
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductDTO[]>} The updated products.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function updateProduct (id: string, title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const products = await productModule.update({id}, {
+   *       title
+   *     }
+   *   )
    *
    *   // do something with the products or return them
    * }
    */
   update(
-    data: UpdateProductDTO[],
+    selector: FilterableProductProps,
+    data: UpdateProductDTO,
     sharedContext?: Context
   ): Promise<ProductDTO[]>