chore: update TSDocs of the Product Module (#6897)

Updated TSDocs of the Product Module.

packages/types/src/product/common.ts

@@ -358,6 +358,9 @@ export interface CreateProductCategoryDTO {
   rank?: number
   /**
    * The ID of the parent product category, if it has any.
+   *
+   * @privateRemarks
+   * Shouldn't this be optional?
    */
   parent_category_id: string | null
   /**
@@ -931,9 +934,16 @@ export interface CreateProductCollectionDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * The product collection to create or update.
+ */
 export interface UpsertProductCollectionDTO extends UpdateProductCollectionDTO {
   /**
-   * The ID of the product collection to update.
+   * The ID of the product collection to update. If not provided,
+   * the product collection is created. In this case, the `title` property is
+   * required.
    */
   id?: string
 }
@@ -982,9 +992,16 @@ export interface CreateProductTypeDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * A product type to create or update
+ */
 export interface UpsertProductTypeDTO extends UpdateProductTypeDTO {
   /**
-   * The product type's ID.
+   * The product type's ID. If provided, the product
+   * tag is updated. Otheriwse, it's created.
+   * In that case, the `value` property is required.
    */
   id?: string
 }
@@ -1021,9 +1038,15 @@ export interface CreateProductImageDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * A product image to create or update.
+ */
 export interface UpsertProductImageDTO extends UpdateProductImageDTO {
   /**
-   * The product image's ID.
+   * The product image's ID. If not provided, the image is created. In
+   * that case, the `url` property is required.
    */
   id?: string
 }
@@ -1056,9 +1079,15 @@ export interface CreateProductTagDTO {
   value: string
 }
 
+/**
+ * @interface
+ *
+ * A product tag to create or update.
+ */
 export interface UpsertProductTagDTO extends UpdateProductTagDTO {
   /**
-   * The ID of the product tag to update.
+   * The ID of the product tag to update. If not provided, the tag
+   * is created. In that case, the `value` property is required.
    */
   id?: string
 }
@@ -1096,9 +1125,16 @@ export interface CreateProductOptionDTO {
   product_id?: string
 }
 
+/**
+ * @interface
+ *
+ * A product option to create or update.
+ */
 export interface UpsertProductOptionDTO extends UpdateProductOptionDTO {
   /**
-   * The ID of the product option to update.
+   * The ID of the product option to update. If not provided, the product
+   * option is created. In that case, the `title` and `values` properties are
+   * required.
    */
   id?: string
 }
@@ -1193,7 +1229,12 @@ export interface CreateProductVariantDTO {
    */
   width?: number
   /**
-   * The product variant options to associate with the product variant.
+   * The options of the variant. Each key is an option's title, and value
+   * is an option's value. If an option with the specified title doesn't exist,
+   * a new one is created.
+   *
+   * @example
+   * `{ Color: "Blue" }`
    */
   options?: Record<string, string>
   /**
@@ -1202,6 +1243,15 @@ export interface CreateProductVariantDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * A product variant to create or update.
+ *
+ * @privateRemarks
+ * Shouldn't this type support passing a `product_id`? In case a variant
+ * is created.
+ */
 export interface UpsertProductVariantDTO extends UpdateProductVariantDTO {
   /**
    * The ID of the product variant to update.
@@ -1329,7 +1379,7 @@ export interface CreateProductDTO {
    */
   status?: ProductStatus
   /**
-   * The product's images to upsert and associate with the product
+   * The associated images to created or updated.
    */
   images?: UpsertProductImageDTO[]
   /**
@@ -1341,7 +1391,7 @@ export interface CreateProductDTO {
    */
   collection_id?: string
   /**
-   * The product tags to be upserted and associated with the product.
+   * The associated tags to be created or updated.
    */
   tags?: UpsertProductTagDTO[]
   /**
@@ -1394,9 +1444,13 @@ export interface CreateProductDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * A product to be created or updated.
+ */
 export interface UpsertProductDTO extends UpdateProductDTO {
   /**
-   * The ID of the product to update.
+   * The ID of the product to update. If not provided, a product
+   * is created instead. In that case, the `title` property is required.
    */
   id?: string
 }
@@ -1404,7 +1458,7 @@ export interface UpsertProductDTO extends UpdateProductDTO {
 /**
  * @interface
  *
- * The data to update in a product. The `id` is used to identify which product to update.
+ * The data to update in a product.
  */
 export interface UpdateProductDTO {
   /**
@@ -1441,7 +1495,7 @@ export interface UpdateProductDTO {
    */
   status?: ProductStatus
   /**
-   * The product's images to upsert and associate with the product
+   * The associated images to create or update.
    */
   images?: UpsertProductImageDTO[]
   /**
@@ -1453,7 +1507,7 @@ export interface UpdateProductDTO {
    */
   collection_id?: string | null
   /**
-   * The product tags to be created and associated with the product.
+   * The associated tags to create or update.
    */
   tags?: UpsertProductTagDTO[]
   /**
@@ -1461,11 +1515,12 @@ export interface UpdateProductDTO {
    */
   category_ids?: string[]
   /**
-   * The product options to be created and associated with the product.
+   * The associated options to create or update.
    */
   options?: UpsertProductOptionDTO[]
   /**
-   * The product variants to be created and associated with the product. You can also update existing product variants associated with the product.
+   * The product variants to be created and associated with the product.
+   * You can also update existing product variants associated with the product.
    */
   variants?: UpsertProductVariantDTO[]
   /**