feat: Update the signatures for variants and options to follow convention (#6748)

packages/types/src/product/common.ts

@@ -1018,8 +1018,11 @@ export interface CreateProductOptionDTO {
   product_id?: string
 }
 
+export interface UpsertProductOptionDTO extends UpdateProductOptionDTO {
+  id?: string
+}
+
 export interface UpdateProductOptionDTO {
-  id: string
   title?: string
   values?: string[] | { value: string }[]
   product_id?: string
@@ -1109,8 +1112,7 @@ export interface CreateProductVariantDTO {
   metadata?: Record<string, unknown>
 }
 
-export interface UpsertProductVariantDTO
-  extends Omit<UpdateProductVariantDTO, "id"> {
+export interface UpsertProductVariantDTO extends UpdateProductVariantDTO {
   /**
    * The ID of the product variant to update.
    */
@@ -1123,10 +1125,6 @@ export interface UpsertProductVariantDTO
  * The data to update in a product variant. The `id` is used to identify which product variant to update.
  */
 export interface UpdateProductVariantDTO {
-  /**
-   * The ID of the product variant to update.
-   */
-  id: string
   /**
    * The tile of the product variant.
    */

packages/types/src/product/service.ts

@@ -30,6 +30,8 @@ import {
   UpdateProductVariantDTO,
   UpsertProductCollectionDTO,
   UpsertProductDTO,
+  UpsertProductOptionDTO,
+  UpsertProductVariantDTO,
 } from "./common"
 
 import { FindConfig } from "../common"
@@ -1256,25 +1258,25 @@ export interface IProductModuleService extends IModuleService {
    *
    * @param {CreateProductOptionDTO[]} data - The product options to be created.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {ProductOptionDTO[]} The list of created product options.
+   * @returns {Promise<ProductOptionDTO[]>} The list of created product options.
    *
    * @example
    * import {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
    *
-   * async function createProductOption (title: string, productId: string) {
+   * async function createOptions (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const productOptions = await productModule.createOptions([
+   *   const options = await productModule.createOptions([
    *     {
-   *       title,
-   *       product_id: productId
+   *       title
    *     }
    *   ])
    *
    *   // do something with the product options or return them
    * }
+   *
    */
   createOptions(
     data: CreateProductOptionDTO[],
@@ -1282,32 +1284,150 @@ export interface IProductModuleService extends IModuleService {
   ): Promise<ProductOptionDTO[]>
 
   /**
-   * This method is used to update existing product options.
+   * This method is used to create a product option.
    *
-   * @param {UpdateProductOptionDTO[]} data - The product options to be updated, each holding the attributes that should be updated in the product option.
+   * @param {CreateProductOptionDTO} data - The product option to be created.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {ProductOptionDTO[]} The list of updated product options.
+   * @returns {Promise<ProductOptionDTO>} The created product option.
    *
    * @example
    * import {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
    *
-   * async function updateProductOption (id: string, title: string) {
+   * async function createOption (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const productOptions = await productModule.updateOptions([
+   *   const option = await productModule.createOptions(
+   *     {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the product option or return them
+   * }
+   *
+   */
+  createOptions(
+    data: CreateProductOptionDTO,
+    sharedContext?: Context
+  ): Promise<ProductOptionDTO>
+
+  /**
+   * This method updates existing options, or creates new ones if they don't exist.
+   *
+   * @param {UpsertProductOptionDTO[]} data - The attributes to update or create for each option.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductOptionDTO[]>} The updated and created options.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upsertOptions (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdOptions = await productModule.upsertOptions([
    *     {
-   *       id,
    *       title
    *     }
    *   ])
    *
-   *   // do something with the product options or return them
+   *   // do something with the options or return them
+   * }
+   */
+  upsertOptions(
+    data: UpsertProductOptionDTO[],
+    sharedContext?: Context
+  ): Promise<ProductOptionDTO[]>
+
+  /**
+   * This method updates an existing option, or creates a new one if it doesn't exist.
+   *
+   * @param {UpsertProductOptionDTO} data - The attributes to update or create for the option.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductOptionDTO>} The updated or created option.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upsertOption (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdOption = await productModule.upsertOptions(
+   *     {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the option or return it
+   * }
+   */
+  upsertOptions(
+    data: UpsertProductOptionDTO,
+    sharedContext?: Context
+  ): Promise<ProductOptionDTO>
+
+  /**
+   * This method is used to update a option.
+   *
+   * @param {string} id - The ID of the option to be updated.
+   * @param {UpdateProductOptionDTO} data - The attributes of the option to be updated
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductOptionDTO>} The updated option.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function updateOption (id: string, title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const option = await productModule.updateOptions(id, {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the option or return it
    * }
    */
   updateOptions(
-    data: UpdateProductOptionDTO[],
+    id: string,
+    data: UpdateProductOptionDTO,
+    sharedContext?: Context
+  ): Promise<ProductOptionDTO>
+
+  /**
+   * This method is used to update a list of options determined by the selector filters.
+   *
+   * @param {FilterableProductOptionProps} selector - The filters that will determine which options will be updated.
+   * @param {UpdateProductOptionDTO} data - The attributes to be updated on the selected options
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductOptionDTO[]>} The updated options.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function updateOptions(ids: string[], title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const options = await productModule.updateOptions({id: ids}, {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the options or return them
+   * }
+   */
+  updateOptions(
+    selector: FilterableProductOptionProps,
+    data: UpdateProductOptionDTO,
     sharedContext?: Context
   ): Promise<ProductOptionDTO[]>
 
@@ -1560,58 +1680,180 @@ export interface IProductModuleService extends IModuleService {
   ): Promise<ProductVariantDTO[]>
 
   /**
-   * This method is used to update a product's variants.
+   * This method is used to create product variants.
    *
-   * @param {UpdateProductVariantDTO[]} data - The product variants to update.
+   * @param {CreateProductVariantDTO[]} data - The product variants to be created.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<ProductVariantDTO[]>} The updated product variants's details.
+   * @returns {Promise<ProductVariantDTO[]>} The list of created product variants.
    *
    * @example
    * import {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
-   * import {
-   *   UpdateProductVariantDTO
-   * } from "@medusajs/product/dist/types/services/product-variant"
    *
-   * async function updateProductVariants (items: UpdateProductVariantDTO[]) {
+   * async function createVariants (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const productVariants = await productModule.updateVariants(items)
+   *   const variants = await productModule.createVariants([
+   *     {
+   *       title
+   *     }
+   *   ])
    *
    *   // do something with the product variants or return them
    * }
+   *
    */
-  updateVariants(
-    data: UpdateProductVariantDTO[],
+  createVariants(
+    data: CreateProductVariantDTO[],
     sharedContext?: Context
   ): Promise<ProductVariantDTO[]>
 
   /**
-   * This method is used to create variants for a product.
+   * This method is used to create a product variant.
    *
-   * @param {CreateProductVariantDTO[]} data - The product variants to create.
+   * @param {CreateProductVariantDTO} data - The product variant to be created.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<ProductVariantDTO[]>} The created product variants' details.
+   * @returns {Promise<ProductVariantDTO>} The created product variant.
    *
    * @example
    * import {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
    *
-   * async function createProductVariants (items: {
-   *   product_id: string,
-   *   title: string
-   * }[]) {
+   * async function createVariant (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const productVariants = await productModule.createVariants(items)
+   *   const variant = await productModule.createVariants(
+   *     {
+   *       title
+   *     }
+   *   )
    *
-   *   // do something with the product variants or return them
+   *   // do something with the product variant or return them
    * }
+   *
    */
   createVariants(
-    data: CreateProductVariantDTO[],
+    data: CreateProductVariantDTO,
+    sharedContext?: Context
+  ): Promise<ProductVariantDTO>
+
+  /**
+   * This method updates existing variants, or creates new ones if they don't exist.
+   *
+   * @param {UpsertProductVariantDTO[]} data - The attributes to update or create for each variant.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductVariantDTO[]>} The updated and created variants.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upsertVariants (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdVariants = await productModule.upsertVariants([
+   *     {
+   *       title
+   *     }
+   *   ])
+   *
+   *   // do something with the variants or return them
+   * }
+   */
+  upsertVariants(
+    data: UpsertProductVariantDTO[],
+    sharedContext?: Context
+  ): Promise<ProductVariantDTO[]>
+
+  /**
+   * This method updates an existing variant, or creates a new one if it doesn't exist.
+   *
+   * @param {UpsertProductVariantDTO} data - The attributes to update or create for the variant.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductVariantDTO>} The updated or created variant.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function upsertVariant (title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const createdVariant = await productModule.upsertVariants(
+   *     {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the variant or return it
+   * }
+   */
+  upsertVariants(
+    data: UpsertProductVariantDTO,
+    sharedContext?: Context
+  ): Promise<ProductVariantDTO>
+
+  /**
+   * This method is used to update a variant.
+   *
+   * @param {string} id - The ID of the variant to be updated.
+   * @param {UpdateProductVariantDTO} data - The attributes of the variant to be updated
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductVariantDTO>} The updated variant.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function updateVariant (id: string, title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const variant = await productModule.updateVariants(id, {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the variant or return it
+   * }
+   */
+  updateVariants(
+    id: string,
+    data: UpdateProductVariantDTO,
+    sharedContext?: Context
+  ): Promise<ProductVariantDTO>
+
+  /**
+   * This method is used to update a list of variants determined by the selector filters.
+   *
+   * @param {FilterableProductVariantProps} selector - The filters that will determine which variants will be updated.
+   * @param {UpdateProductVariantDTO} data - The attributes to be updated on the selected variants
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ProductVariantDTO[]>} The updated variants.
+   *
+   * @example
+   * import {
+   *   initialize as initializeProductModule,
+   * } from "@medusajs/product"
+   *
+   * async function updateVariants(ids: string[], title: string) {
+   *   const productModule = await initializeProductModule()
+   *
+   *   const variants = await productModule.updateVariants({id: ids}, {
+   *       title
+   *     }
+   *   )
+   *
+   *   // do something with the variants or return them
+   * }
+   */
+  updateVariants(
+    selector: FilterableProductVariantProps,
+    data: UpdateProductVariantDTO,
     sharedContext?: Context
   ): Promise<ProductVariantDTO[]>
 
@@ -2147,10 +2389,10 @@ export interface IProductModuleService extends IModuleService {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
    *
-   * async function upserCollections (title: string) {
+   * async function upsertCollections (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const createdCollections = await productModule.upsert([
+   *   const createdCollections = await productModule.upsertCollections([
    *     {
    *       title
    *     }
@@ -2176,10 +2418,10 @@ export interface IProductModuleService extends IModuleService {
    *   initialize as initializeProductModule,
    * } from "@medusajs/product"
    *
-   * async function upserCollection (title: string) {
+   * async function upsertCollection (title: string) {
    *   const productModule = await initializeProductModule()
    *
-   *   const createdCollection = await productModule.upsert(
+   *   const createdCollection = await productModule.upsertCollection(
    *     {
    *       title
    *     }